Back to index

lightning-sunbird  0.9+nobinonly
nsIMsgDatabase.idl
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is mozilla.org code.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1999
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either of the GNU General Public License Version 2 or later (the "GPL"),
00026  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #include "nsISupports.idl"
00039 #include "MailNewsTypes2.idl"
00040 #include "nsIDBChangeAnnouncer.idl"
00041 #include "nsIMsgDBView.idl"
00042 
00043 %{C++
00044 #include "nsMsgKeyArray.h"
00045 %}
00046 
00047 interface nsIFileSpec;
00048 interface nsIDBChangeListener;
00049 interface nsIMsgDBHdr;
00050 interface nsISimpleEnumerator;
00051 interface nsIMsgThread;
00052 interface nsIDBFolderInfo;
00053 interface nsIMsgOfflineImapOperation;
00054 interface nsIMsgFolder;
00055 interface nsIOFileStream;
00056 interface nsIUrlListener;
00057 interface nsISupportsArray;
00058 
00059 [ptr] native octetPtr(PRUint8);
00060 
00061 typedef unsigned long nsMsgRetainByPreference;
00062 
00063 
00064 [scriptable, uuid(063bd2ac-de85-11d4-a5b6-0060b0fc04b7)]
00065 
00066 interface nsIMsgRetentionSettings : nsISupports
00067 {
00068   const unsigned long nsMsgRetainAll = 1;
00069   const unsigned long nsMsgRetainByAge = 2;
00070   const unsigned long nsMsgRetainByNumHeaders = 3;
00071 
00072   attribute boolean useServerDefaults;
00073   attribute nsMsgRetainByPreference retainByPreference;
00074   attribute unsigned long daysToKeepHdrs;
00075   attribute unsigned long numHeadersToKeep; 
00076 
00077   // this is orthogonal to retaining by age or num headers, i.e., if
00078   // it's set, we'll only keep NNN unread messages only, or unread
00079   // messages less than NNN days old.
00080   attribute boolean keepUnreadMessagesOnly;
00081   // this is for keeping offline bodies.
00082   attribute boolean cleanupBodiesByDays;
00083   attribute unsigned long daysToKeepBodies;
00084 }; 
00085 
00086 [scriptable, uuid(86a9da90-14f1-11d5-a5c0-0060b0fc04b7)]
00087 interface nsIMsgDownloadSettings : nsISupports
00088 {
00089   attribute boolean useServerDefaults;
00090   attribute boolean downloadByDate;
00091   attribute boolean downloadUnreadOnly;
00092   attribute unsigned long ageLimitOfMsgsToDownload;
00093 };
00094 
00095 typedef long nsMsgDBCommit;
00096 
00097 [scriptable, uuid(aa4d45d0-3956-11d3-8d76-00805f8a6617)]
00098 
00099 interface nsMsgDBCommitType 
00100 {
00101   const long kSmallCommit = 0;
00102   const long kLargeCommit = 1;
00103   const long kSessionCommit = 2;
00104   const long kCompressCommit = 3;
00105 };
00106 
00107 [ref] native nsMsgKeyArrayRef(nsMsgKeyArray);
00108 [ptr] native nsMsgKeyArrayPtr(nsMsgKeyArray);
00109 
00110 [scriptable, uuid(03223c50-1e88-45e8-ba1a-7ce792dc3fc3)]
00111 interface nsIMsgDBService : nsISupports
00112 {
00113     // want to remove this method from nsIMsgDatabase...
00114     // if a db is opened on the folder, the listener will automatically be added
00115     nsIMsgDatabase openFolderDB(in nsIMsgFolder aFolder, in boolean aCreate, in boolean aLeaveInvalidDB);
00116     nsIMsgDatabase openMailDBFromFileSpec(in nsIFileSpec aFolderName, in boolean aCreate, in boolean aLeaveInvalidDB);
00117     void registerPendingListener(in nsIMsgFolder aFolder, in nsIDBChangeListener aListener);
00118     void unregisterPendingListener(in nsIDBChangeListener aListener);
00119 };
00120 
00121 [scriptable, uuid(6c8db586-57ff-4a1b-bb7e-acff79d6a4ce)]
00122 
00123 interface  nsIMsgDatabase : nsIDBChangeAnnouncer {
00124   void Open(in nsIFileSpec aFolderName, in boolean aCreate, in boolean aLeaveInvalidDB);
00125   void forceFolderDBClosed(in nsIMsgFolder aFolder);
00126   void Close(in boolean aForceCommit);
00127 
00128   void Commit(in nsMsgDBCommit commitType);
00129   // Force closed is evil, and we should see if we can do without it.
00130   // In 4.x, it was mainly used to remove corrupted databases.
00131   void ForceClosed();
00132   void clearCachedHdrs();
00133   void resetHdrCacheSize(in unsigned long size);
00134 
00135   readonly attribute nsIDBFolderInfo  dBFolderInfo;
00136 
00137   // get a message header for the given key. Caller must release()!
00138 
00139   nsIMsgDBHdr GetMsgHdrForKey(in nsMsgKey key);
00140   nsIMsgDBHdr getMsgHdrForMessageID(in string messageID);
00141   //Returns whether or not this database contains the given key
00142   boolean ContainsKey(in nsMsgKey key);
00143 
00144    // Must call AddNewHdrToDB after creating. The idea is that you create
00145   // a new header, fill in its properties, and then call AddNewHdrToDB.
00146   // AddNewHdrToDB will send notifications to any listeners.
00147   nsIMsgDBHdr CreateNewHdr(in nsMsgKey key);
00148 
00149   void AddNewHdrToDB(in nsIMsgDBHdr newHdr, in boolean notify);
00150 
00151   nsIMsgDBHdr CopyHdrFromExistingHdr(in nsMsgKey key, in nsIMsgDBHdr existingHdr, in boolean addHdrToDB);
00152 
00153   [noscript] void ListAllKeys(in nsMsgKeyArrayRef outputKeys);
00154 
00155   nsISimpleEnumerator EnumerateMessages();
00156   nsISimpleEnumerator EnumerateThreads();
00157 
00158   // count the total and unread msgs, and adjust global count if needed
00159   void syncCounts();
00160 
00161   nsIMsgThread GetThreadContainingMsgHdr(in nsIMsgDBHdr msgHdr) ;
00162 
00163   // helpers for user command functions like delete, mark read, etc.
00164 
00165   void MarkHdrRead(in nsIMsgDBHdr msgHdr, in boolean bRead,
00166                          in nsIDBChangeListener instigator);
00167 
00168   void MarkHdrReplied(in nsIMsgDBHdr msgHdr, in boolean bReplied,
00169                          in nsIDBChangeListener instigator);
00170 
00171   void MarkHdrMarked(in nsIMsgDBHdr msgHdr, in boolean mark,
00172                          in nsIDBChangeListener instigator);
00173 
00174   // MDN support
00175   void MarkMDNNeeded(in nsMsgKey key, in boolean bNeeded,
00176                            in nsIDBChangeListener instigator);
00177 
00178   // MarkMDNneeded only used when mail server is a POP3 server
00179   // or when the IMAP server does not support user defined
00180   // PERMANENTFLAGS
00181   boolean IsMDNNeeded(in nsMsgKey key);
00182 
00183   void MarkMDNSent(in nsMsgKey key, in boolean bNeeded,
00184                          in nsIDBChangeListener instigator);
00185   boolean IsMDNSent(in nsMsgKey key);
00186 
00187 // methods to get and set docsets for ids.
00188   void MarkRead(in nsMsgKey key, in boolean bRead, 
00189                       in nsIDBChangeListener instigator);
00190 
00191   void MarkReplied(in nsMsgKey key, in boolean bReplied, 
00192                          in nsIDBChangeListener instigator);
00193 
00194   void MarkForwarded(in nsMsgKey key, in boolean bForwarded, 
00195                            in nsIDBChangeListener instigator);
00196 
00197   void MarkHasAttachments(in nsMsgKey key, in boolean bHasAttachments, 
00198                                 in nsIDBChangeListener instigator);
00199 
00200   [noscript] void MarkThreadRead(in nsIMsgThread thread, 
00201                                    in nsIDBChangeListener instigator, in nsMsgKeyArrayPtr thoseMarked);
00202 
00203   void MarkThreadIgnored(in nsIMsgThread thread, in nsMsgKey threadKey, in boolean bIgnored,
00204                                in nsIDBChangeListener instigator);
00205   void MarkThreadWatched(in nsIMsgThread thread, in nsMsgKey threadKey, in boolean bWatched,
00206                                in nsIDBChangeListener instigator);
00207 
00208   boolean IsRead(in nsMsgKey key);
00209   boolean IsIgnored(in nsMsgKey key);
00210   boolean IsMarked(in nsMsgKey key);
00211   boolean HasAttachments(in nsMsgKey key);
00212 
00213   [noscript] void MarkAllRead(in nsMsgKeyArrayPtr thoseMarked);
00214 
00215   [noscript] void MarkReadByDate (in PRTime startDate, in PRTime endDate, in nsMsgKeyArrayPtr markedIds);
00216 
00217   [noscript] void DeleteMessages(in nsMsgKeyArrayPtr nsMsgKeys, in nsIDBChangeListener instigator);
00218   void DeleteMessage(in nsMsgKey key, 
00219                            in nsIDBChangeListener instigator,
00220                            in boolean commit);
00221   void DeleteHeader(in nsIMsgDBHdr msgHdr, in nsIDBChangeListener instigator,
00222                           in boolean commit, in boolean notify);
00223 
00224   // lower level routine that doesn't remove hdr from thread or adjust counts
00225   void RemoveHeaderMdbRow(in nsIMsgDBHdr msgHdr);
00226 
00227   void UndoDelete(in nsIMsgDBHdr msgHdr);
00228 
00229   void MarkMarked(in nsMsgKey key, in boolean mark,
00230                         in nsIDBChangeListener instigator);
00231   void MarkOffline(in nsMsgKey key, in boolean offline,
00232                          in nsIDBChangeListener instigator);
00233   void SetLabel(in nsMsgKey key, in nsMsgLabelValue label);
00234   void setStringProperty(in nsMsgKey aKey, in string aProperty, in string aValue);
00235 
00236   void MarkImapDeleted(in nsMsgKey key, in boolean deleted,
00237                              in nsIDBChangeListener instigator);
00238 
00239   readonly attribute nsMsgKey FirstNew;
00240 
00241   attribute nsIMsgRetentionSettings msgRetentionSettings;
00242   // purge unwanted message headers and/or bodies. If deleteViaFolder is
00243   // true, we'll call nsIMsgFolder::DeleteMessages to delete the messages.
00244   // Otherwise, we'll just delete them from the db.
00245   void applyRetentionSettings(in nsIMsgRetentionSettings aMsgRetentionSettings, 
00246                               in boolean aDeleteViaFolder);
00247 
00248   attribute nsIMsgDownloadSettings msgDownloadSettings;
00249 
00250   boolean HasNew();  
00251   void ClearNewList(in boolean notify);
00252   void AddToNewList(in nsMsgKey key);
00253 
00254   // used mainly to force the timestamp of a local mail folder db to
00255   // match the time stamp of the corresponding berkeley mail folder,
00256   // but also useful to tell the summary to mark itself invalid
00257   // Also, if a local folder is being reparsed, summary will be invalid
00258   // until the reparsing is done.
00259   attribute boolean summaryValid;
00260 
00261   // batching - can be used to cache file stream for local mail,
00262   // and perhaps to use the mdb batching mechanism as well.
00263   void StartBatch();
00264   void EndBatch();
00265   // offline operations - we could move these into an offline operation interface
00266   // but it would have to be in nsMailDatabase, since local folders can be move destinations
00267   nsIMsgOfflineImapOperation GetOfflineOpForKey(in nsMsgKey messageKey, in boolean create);
00268   void  RemoveOfflineOp(in nsIMsgOfflineImapOperation op);
00269   nsISimpleEnumerator EnumerateOfflineOps();
00270   [noscript] void ListAllOfflineOpIds(in nsMsgKeyArrayPtr offlineOpIds);
00271   [noscript] void ListAllOfflineDeletes(in nsMsgKeyArrayPtr offlineDeletes);
00272   [noscript] void ListAllOfflineMsgs(in nsMsgKeyArrayPtr offlineMsgs);
00273 
00274   void setAttributesOnPendingHdr(in nsIMsgDBHdr pendingHdr, in string property, 
00275                                   in string propertyVal, in long flags);
00276 
00277   readonly attribute nsMsgKey lowWaterArticleNum;
00278   readonly attribute nsMsgKey highWaterArticleNum;
00279   attribute nsMsgKey nextPseudoMsgKey;   //for undo-redo of move pop->imap
00280   readonly attribute nsMsgKey nextFakeOfflineMsgKey; // for saving "fake" offline msg hdrs
00281   // for sorting
00282   [noscript] void createCollationKey(in AString sourceString, out octetPtr key, out unsigned long len);
00283   [noscript] long compareCollationKeys(in octetPtr key1, in unsigned long len1, in octetPtr key2, in unsigned long len2);
00284 
00285   // when creating a view, the default sort order and view flags 
00286   // use these for the default.  (this allows news to override, so that
00287   // news can be threaded by default)
00288   readonly attribute nsMsgViewFlagsTypeValue defaultViewFlags;
00289   readonly attribute nsMsgViewSortTypeValue  defaultSortType;
00290   readonly attribute nsMsgViewSortOrderValue defaultSortOrder;
00291 
00292   // for msg hdr hash table allocation. controllable by caller to improve folder loading preformance.
00293   attribute unsigned long msgHdrCacheSize;
00294 
00295   // extremely deprecated - this is going away when we get rid of nsFileSpec and friends.
00296   // and it's [noscript] though I don't know if you can make an attribute noscript.
00297   attribute nsIOFileStream folderStream;
00298 
00305   void getNewList(out unsigned long count, [array, size_is(count)] out nsMsgKey newKeys);
00306   
00307   // These are used for caching search hits in a db, to speed up saved search folders.
00308   nsISimpleEnumerator getCachedHits(in string aSearchFolderUri);
00309   void refreshCache(in string aSearchFolderUri, in unsigned long aNumKeys, [array, size_is (aNumKeys)] in nsMsgKey aNewHits,
00310      out unsigned long aNumBadHits, [array, size_is(aNumBadHits)] out nsMsgKey aStaleHits);
00311   void updateHdrInCache(in string aSearchFolderUri, in nsIMsgDBHdr aHdr, in boolean aAdd);
00312   boolean hdrIsInCache(in string aSearchFolderUri, in nsIMsgDBHdr aHdr);
00313 
00314 };
00315