nsIMsgDatabase

The nsIMsgDatabase interface is an abstract interface used to access the mail database backend.

Please add a summary to this article.
Last changed in Gecko 1.9 (Firefox 3)

Inherits from: nsIDBChangeAnnouncer

Method overview

void Open(in nsILocalFile aFolderName, in boolean aCreate, in boolean aLeaveInvalidDB);
void forceFolderDBClosed(in nsIMsgFolder aFolder);
void Close(in boolean aForceCommit);
void Commit(in nsMsgDBCommit commitType);
void ForceClosed();
void clearCachedHdrs;
void resetHdrCacheSize(in unsigned long size);
nsIMsgDBHdr GetMsgHdrForKey(in nsMsgKey key);
nsIMsgDBHdr getMsgHdrForMessageID(in string messageID);
boolean ContainsKey(in nsMsgKey key);
nsIMsgDBHdr CreateNewHdr(in nsMsgKey key);
void AddNewHdrToDB(in nsIMsgDBHdr newHdr, in boolean notify);
nsIMsgDBHdr CopyHdrFromExistingHdr(in nsMsgKey key, in nsIMsgDBHdr existingHdr, in boolean addHdrToDB);
void ListAllKeys(in nsMsgKeyArrayRef outputKeys); Native code only!
nsISimpleEnumerator EnumerateMessages();
nsISimpleEnumerator EnumerateThreads();
void syncCounts;
nsIMsgThread GetThreadContainingMsgHdr(in nsIMsgDBHdr msgHdr);
void MarkHdrRead(in nsIMsgDBHdr msgHdr, in boolean bRead, in nsIDBChangeListener instigator);
void MarkHdrReplied(in nsIMsgDBHdr msgHdr, in boolean bReplied, in nsIDBChangeListener instigator);
void MarkHdrMarked(in nsIMsgDBHdr msgHdr, in boolean mark,in nsIDBChangeListener instigator);
void MarkMDNNeeded(in nsMsgKey key, in boolean bNeeded,in nsIDBChangeListener instigator);
boolean IsMDNNeeded(in nsMsgKey key);
void MarkMDNSent(in nsMsgKey key, in boolean bNeeded, in nsIDBChangeListener instigator);
boolean IsMDNSent(in nsMsgKey key);
void MarkRead(in nsMsgKey key, in boolean bRead, in nsIDBChangeListener instigator);
void MarkReplied(in nsMsgKey key, in boolean bReplied, in nsIDBChangeListener instigator);
void MarkForwarded(in nsMsgKey key, in boolean bForwarded, in nsIDBChangeListener instigator);
void MarkHasAttachments(in nsMsgKey key, in boolean bHasAttachments, in nsIDBChangeListener instigator);
void MarkThreadRead(in nsIMsgThread thread, in nsIDBChangeListener instigator, in nsMsgKeyArrayPtr thoseMarked); Native code only!
void MarkThreadIgnored(in nsIMsgThread thread, in nsMsgKey threadKey, in boolean bIgnored, in nsIDBChangeListener instigator);
void MarkThreadWatched(in nsIMsgThread thread, in nsMsgKey threadKey, in boolean bWatched, in nsIDBChangeListener instigator);
void MarkHeaderKilled(in nsIMsgDBHdr msg, in boolean bIgnored, in nsIDBChangeListener instigator);
boolean IsRead(in nsMsgKey key);
boolean IsIgnored(in nsMsgKey key);
boolean IsMarked(in nsMsgKey key);
boolean HasAttachments(in nsMsgKey key);
void MarkAllRead(in nsMsgKeyArrayPtr thoseMarked); Native code only!
void MarkReadByDate(in PRTime startDate, in PRTime endDate, in nsMsgKeyArrayPtr markedIds); Native code only!
void DeleteMessages(in nsMsgKeyArrayPtr nsMsgKeys, in nsIDBChangeListener instigator); Native code only!
void DeleteMessage(in nsMsgKey key, in nsIDBChangeListener instigator, in boolean commit);
void DeleteHeader(in nsIMsgDBHdr msgHdr, in nsIDBChangeListener instigator,in boolean commit, in boolean notify);
void RemoveHeaderMdbRow(in nsIMsgDBHdr msgHdr);
void UndoDelete(in nsIMsgDBHdr msgHdr);
void MarkMarked(in nsMsgKey key, in boolean mark, in nsIDBChangeListener instigator);
void MarkOffline(in nsMsgKey key, in boolean offline, in nsIDBChangeListener instigator);
void SetLabel(in nsMsgKey key, in nsMsgLabelValue label);
void setStringProperty(in nsMsgKey aKey, in string aProperty, in string aValue);
void MarkImapDeleted(in nsMsgKey key, in boolean deleted, in nsIDBChangeListener instigator);
void applyRetentionSettings(in nsIMsgRetentionSettings aMsgRetentionSettings, in boolean aDeleteViaFolder);
boolean HasNew();
void ClearNewList(in boolean notify);
void AddToNewList(in nsMsgKey key);
void StartBatch();
void EndBatch();
nsIMsgOfflineImapOperation GetOfflineOpForKey(in nsMsgKey messageKey, in boolean create);
void RemoveOfflineOp(in nsIMsgOfflineImapOperation op);
nsISimpleEnumerator EnumerateOfflineOps();
void ListAllOfflineOpIds(in nsMsgKeyArrayPtr offlineOpIds); Native code only!
void ListAllOfflineDeletes(in nsMsgKeyArrayPtr offlineDeletes); Native code only!
void ListAllOfflineMsgs(in nsMsgKeyArrayPtr offlineMsgs); Native code only!
void setAttributesOnPendingHdr(in nsIMsgDBHdr pendingHdr, in string property, in string propertyVal, in long flags);
void createCollationKey(in AString sourceString, out octetPtr key, out unsigned long len); Native code only!
long compareCollationKeys(in octetPtr key1, in unsigned long len1, in octetPtr key2, in unsigned long len2); Native code only!
void getNewList(out unsigned long count, array, size_is(count) out nsMsgKey newKeys);
nsISimpleEnumerator getCachedHits(in string aSearchFolderUri);
void refreshCache(in string aSearchFolderUri, in unsigned long aNumKeys, array, size_is (aNumKeys) in nsMsgKey aNewHits, out unsigned long aNumBadHits, array, size_is(aNumBadHits) out nsMsgKey aStaleHits);
void updateHdrInCache(in string aSearchFolderUri, in nsIMsgDBHdr aHdr, in boolean aAdd);
boolean hdrIsInCache(in string aSearchFolderUri, in nsIMsgDBHdr aHdr);

Attributes

Attribute Type Description
dBFolderInfo nsIDBFolderInfo Readonly:
FirstNew nsMsgKey Readonly:
msgRetentionSettings nsIMsgRetentionSettings
msgDownloadSettings nsIMsgDownloadSettings
lowWaterArticleNum nsMsgKey Readonly:
highWaterArticleNum nsMsgKey Readonly:
nextPseudoMsgKey nsMsgKey For undo-redo of move pop->imap.
nextFakeOfflineMsgKey nsMsgKey Readonly: For saving "fake" offline msg hdrs.
defaultViewFlags nsMsgViewFlagsTypeValue Readonly:
defaultSortType nsMsgViewSortTypeValue Readonly:
defaultSortOrder nsMsgViewSortOrderValue Readonly:
msgHdrCacheSize unsigned long
folderStream nsIOutputStream
summaryValid boolean

Methods

Open()

Opens a database folder.

 void Open(in nsILocalFile aFolderName,
           in boolean aCreate,
           in boolean aLeaveInvalidDB);
Parameters
aFolderName
The name of the folder to create.
aCreate
Whether or not the file should be created.
aLeaveInvalidDB
Set to true if you do not want the database to bedeleted if it is invalid.
Exceptions Thrown
NS_ERROR_FILE_TARGET_DOES_NOT_EXIST
aFolderName doesn't exist and aCreate was false.
NS_MSG_ERROR_FOLDER_SUMMARY_OUT_OF_DATE
The database is present (and was opened), but the summary file is out of date.
NS_MSG_ERROR_FOLDER_SUMMARY_MISSING
The database is present (and was opened), but the summary file is missing.

forceFolderDBClosed()

 void forceFolderDBClosed(in nsIMsgFolder aFolder);
Parameters
aFolder

Close()

 void Close(in boolean aForceCommit);
Parameters
aForceCommit

Commit()

 void Commit(in nsMsgDBCommit commitType);
Parameters
commitType

ForceClosed()

Force closed is evil, and we should see if we can do without it. In 4.x, it was mainly used to remove corrupted databases.

 void ForceClosed();

clearCachedHdrs()

 void clearCachedHdrs();

resetHdrCacheSize()

 void resetHdrCacheSize(in unsigned long size);

GetMsgHdrForKey()

 nsIMsgDBHdr GetMsgHdrForKey(in nsMsgKey key);
Parameters
key

getMsgHdrForMessageID()

 nsIMsgDBHdr getMsgHdrForMessageID(in string messageID);
Parameters
messageID

ContainsKey()

Returns whether or not this database contains the given key.

 boolean ContainsKey(in nsMsgKey key);
Parameters
key

CreateNewHdr()

Must call AddNewHdrToDB after creating. The idea is that you create a new header, fill in its properties, and then call AddNewHdrToDB. AddNewHdrToDB will send notifications to any listeners.

 nsIMsgDBHdr CreateNewHdr(in nsMsgKey key);

AddNewHdrToDB()

 void AddNewHdrToDB(in nsIMsgDBHdr newHdr, in boolean notify);

CopyHdrFromExistingHdr()

 nsIMsgDBHdr CopyHdrFromExistingHdr(in nsMsgKey key, in nsIMsgDBHdr existingHdr, in boolean addHdrToDB);

ListAllKeys()

 [noscript] void ListAllKeys(in nsMsgKeyArrayRef outputKeys);

EnumerateMessages()

 nsISimpleEnumerator EnumerateMessages();

EnumerateThreads()

 nsISimpleEnumerator EnumerateThreads();

syncCounts()

Count the total and unread msgs, and adjust global count if needed.

 void syncCounts();

GetThreadContainingMsgHdr()

 nsIMsgThread GetThreadContainingMsgHdr(in nsIMsgDBHdr msgHdr) ;

MarkHdrRead()

Helpers for user command functions like delete, mark read, etc.

 void MarkHdrRead(in nsIMsgDBHdr msgHdr,
                  in boolean bRead,
                  in nsIDBChangeListener instigator);

MarkHdrReplied()

 void MarkHdrReplied(in nsIMsgDBHdr msgHdr,
                     in boolean bReplied,
                     in nsIDBChangeListener instigator);

MarkHdrMarked()

 void MarkHdrMarked(in nsIMsgDBHdr msgHdr,
                    in boolean mark,
                    in nsIDBChangeListener instigator);

MarkMDNNeeded()

MDN (Message Disposition Notification) support.

 void MarkMDNNeeded(in nsMsgKey key,
                    in boolean bNeeded,
                    in nsIDBChangeListener instigator);

IsMDNNeeded()

MarkMDNneeded only used when mail server is a POP3 server, or when the IMAP server does not support user defined PERMANENTFLAGS.

 boolean IsMDNNeeded(in nsMsgKey key);

MarkMDNSent()

 void MarkMDNSent(in nsMsgKey key,
                  in boolean bNeeded,
                  in nsIDBChangeListener instigator);

IsMDNSent()

 boolean IsMDNSent(in nsMsgKey key);

MarkRead()

Methods to get and set docsets for ids.

 void MarkRead(in nsMsgKey key,
               in boolean bRead,
               in nsIDBChangeListener instigator);

MarkReplied()

 void MarkReplied(in nsMsgKey key,
                  in boolean bReplied,
                  in nsIDBChangeListener instigator);

MarkForwarded()

 void MarkForwarded(in nsMsgKey key,
                    in boolean bForwarded,
                    in nsIDBChangeListener instigator);

MarkHasAttachments()

 void MarkHasAttachments(in nsMsgKey key,
                         in boolean bHasAttachments,
                         in nsIDBChangeListener instigator);

MarkThreadRead()

 [noscript] void MarkThreadRead(in nsIMsgThread thread,
                                in nsIDBChangeListener instigator,
                                in nsMsgKeyArrayPtr thoseMarked);

MarkThreadIgnored()

 void MarkThreadIgnored(in nsIMsgThread thread,
                        in nsMsgKey threadKey,
                        in boolean bIgnored,
                        in nsIDBChangeListener instigator);

MarkThreadWatched()

 void MarkThreadWatched(in nsIMsgThread thread,
                        in nsMsgKey threadKey,
                        in boolean bWatched,
                        in nsIDBChangeListener instigator);

MarkHeaderKilled()

 void MarkHeaderKilled(in nsIMsgDBHdr msg,
                       in boolean bIgnored,
                       in nsIDBChangeListener instigator);

IsRead()

 boolean IsRead(in nsMsgKey key);

IsIgnored()

 boolean IsIgnored(in nsMsgKey key);

IsMarked()

 boolean IsMarked(in nsMsgKey key);

HasAttachments()

 boolean HasAttachments(in nsMsgKey key);

MarkAllRead()

 [noscript] void MarkAllRead(in nsMsgKeyArrayPtr thoseMarked);

MarkReadByDate()

 [noscript] void MarkReadByDate (in PRTime startDate,
                                 in PRTime endDate,
                                 in nsMsgKeyArrayPtr markedIds);

DeleteMessages()

 [noscript] void DeleteMessages(in nsMsgKeyArrayPtr nsMsgKeys,
                                in nsIDBChangeListener instigator);

DeleteMessage()

 void DeleteMessage(in nsMsgKey key,
                    in nsIDBChangeListener instigator,
                    in boolean commit);

DeleteHeader()

 void DeleteHeader(in nsIMsgDBHdr msgHdr,
                   in nsIDBChangeListener instigator,
                   in boolean commit,
                   in boolean notify);

RemoveHeaderMdbRow()

This is a lower level routine that doesn't remove the header from its thread or adjust message counts.

 void RemoveHeaderMdbRow(in nsIMsgDBHdr msgHdr);

UndoDelete()

 void UndoDelete(in nsIMsgDBHdr msgHdr);

MarkMarked()

 void MarkMarked(in nsMsgKey key,
                 in boolean mark,
                 in nsIDBChangeListener instigator);

MarkOffline()

 void MarkOffline(in nsMsgKey key,
                  in boolean offline,
                  in nsIDBChangeListener instigator);

SetLabel()

 void SetLabel(in nsMsgKey key,
               in nsMsgLabelValue label);

setStringProperty()

 void setStringProperty(in nsMsgKey aKey,
                        in string aProperty,
                        in string aValue);

MarkImapDeleted()

 void MarkImapDeleted(in nsMsgKey key,
                      in boolean deleted,
                      in nsIDBChangeListener instigator);

applyRetentionSettings()

Purge unwanted message headers and/or bodies. If deleteViaFolder is true, we'll call nsIMsgFolder.DeleteMessages() to delete the messages. Otherwise, we'll just delete them from the db.

 void applyRetentionSettings(in nsIMsgRetentionSettings aMsgRetentionSettings,
                             in boolean aDeleteViaFolder);

HasNew()

 boolean HasNew();

ClearNewList()

 void ClearNewList(in boolean notify);

AddToNewList()

 void AddToNewList(in nsMsgKey key);

StartBatch()

Batching - can be used to cache file stream for local mail, and perhaps to use the mdb batching mechanism as well.

 void StartBatch();

EndBatch()

 void EndBatch();

GetOfflineOpForKey()

Offline operations - we could move these into an offline operation interface but it would have to be in nsMailDatabase, since local folders can be move destinations.

 nsIMsgOfflineImapOperation GetOfflineOpForKey(in nsMsgKey messageKey,
                                               in boolean create);

RemoveOfflineOp()

 void  RemoveOfflineOp(in nsIMsgOfflineImapOperation op);

EnumerateOfflineOps()

 nsISimpleEnumerator EnumerateOfflineOps();

ListAllOfflineOpIds()

 [noscript] void ListAllOfflineOpIds(in nsMsgKeyArrayPtr offlineOpIds);

ListAllOfflineDeletes()

 [noscript] void ListAllOfflineDeletes(in nsMsgKeyArrayPtr offlineDeletes);

ListAllOfflineMsgs()

 [noscript] void ListAllOfflineMsgs(in nsMsgKeyArrayPtr offlineMsgs);

setAttributesOnPendingHdr()

 void setAttributesOnPendingHdr(in nsIMsgDBHdr pendingHdr,
                                in string property,
                                in string propertyVal,
                                in long flags);

createCollationKey()

 [noscript] void createCollationKey(in AString sourceString,
                                    out octetPtr key,
                                    out unsigned long len);

compareCollationKeys()

 [noscript] long compareCollationKeys(in octetPtr key1,
                                      in unsigned long len1,
                                      in octetPtr key2,
                                      in unsigned long len2);

getNewList()

The list of messages currently in the NEW state. If there are no such messages, null may be returned. The caller should free when done using nsMemory.Free().

 void getNewList(out unsigned long count,
                 [array, size_is(count)] out nsMsgKey newKeys);

getCachedHits()

These are used for caching search hits in a database, to speed up saved search folders.

 nsISimpleEnumerator getCachedHits(in string aSearchFolderUri);

refreshCache()

 void refreshCache(in string aSearchFolderUri,
                   in unsigned long aNumKeys,
                   [array, size_is (aNumKeys)] in nsMsgKey aNewHits,
                   out unsigned long aNumBadHits,
                   [array, size_is(aNumBadHits)] out nsMsgKey aStaleHits);

updateHdrInCache()

 void updateHdrInCache(in string aSearchFolderUri,
                       in nsIMsgDBHdr aHdr,
                       in boolean aAdd);

hdrIsInCache()

 boolean hdrIsInCache(in string aSearchFolderUri,
                      in nsIMsgDBHdr aHdr);