diff options
Diffstat (limited to 'comm/mailnews/base/public/nsIMsgFolderListener.idl')
| -rw-r--r-- | comm/mailnews/base/public/nsIMsgFolderListener.idl | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/comm/mailnews/base/public/nsIMsgFolderListener.idl b/comm/mailnews/base/public/nsIMsgFolderListener.idl new file mode 100644 index 0000000000..34932a3361 --- /dev/null +++ b/comm/mailnews/base/public/nsIMsgFolderListener.idl @@ -0,0 +1,227 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ +#include "nsISupports.idl" +#include "MailNewsTypes2.idl" + +interface nsIMsgDBHdr; +interface nsIMsgFolder; + +/** + * nsIMsgFolderListener defines the callbacks which are invoked by + * nsIMsgFolderNotificationService. + * + * This is similar to nsIFolderListener, but with slightly different semantics, + * especially w.r.t. moving messages and folders. Some listeners want to know + * about moves, instead of getting an itemAdded and itemRemoved notification. + * Folder listeners also only tend to get called if a view is open on the folder, + * which is not always the case. I don't want to change nsIFolderListener at this + * point since there are lots of extensions that rely on it. Eventually, + * these two interfaces should be combined somehow. + */ + +[scriptable, uuid(2f87be72-0565-4e64-a824-0eb9c258f884)] +interface nsIMsgFolderListener : nsISupports { + /** + * Notified immediately after a message is added to a folder. This could be a + * new incoming message to a local folder, or a new message in an IMAP folder + * when it is opened. + * + * You may want to consider using the msgsClassified notification instead of + * this notification if any of the following are true: + * + * - You only want to be notified about messages after junk classification + * has occurred (if it is going to occur for a message). This also goes for + * trait classification which is a generic use of the bayesian engine at + * the heart of the spam logic. + * + * - You only want to be notified about messages after all filters have been + * run. Although some filters may be run before the msgAdded notification + * is generated, filters dependent on junk/trait classification wait until + * classification completes. + * + * @param aMsg The message header that was just added + */ + void msgAdded(in nsIMsgDBHdr aMsg); + + /** + * Notification that (new to the client) messages have been through junk and + * trait classification. This event will occur for all messages at some point + * after their existence is revealed by msgAdded. + * + * Because junk classification does not run if no messages have ever been + * marked as junk by the user, it is possible to receive this message without + * any classification having actually been performed. We still generate the + * notification in this case so that code is reliably notified about the + * existence of the new message headers. + * + * @param aMsgs The message headers that have been classified or were + * intentionally not classified. + * @param aJunkProcessed Were the messages processed for junk classification? + * @param aTraitProcessed Were the messages processed for trait + * classification? + */ + void msgsClassified(in Array<nsIMsgDBHdr> aMsgs, in boolean aJunkProcessed, + in boolean aTraitProcessed); + + /** + * msgsJunkStatusChanged indicates that some messages that had already been + * reported by msgsClassified have had their junk status changed. This + * event will not fire for the initial automatic classification of + * messages; msgsClassified will tell you about those messages. + * This is not guaranteed to be a comprehensive source of junk + * notification events; right now any time an nsMsgDBView marks things as + * junk/non-junk a notification is produced. + * + * @param {nsIMsgDBHdr[]} messages - The affected messages. + * + */ + void msgsJunkStatusChanged(in Array<nsIMsgDBHdr> messages); + + /** + * Notified after a command to delete a group of messages has been given, but before the + * messages have actually been deleted. + * + * @param aMsgs An array of the message headers about to be deleted + * + * @note + * This notification will not take place if the messages are being deleted from the folder + * as the result of a move to another folder. Instead, the msgsMoveCopyCompleted() notification + * takes place. + * + * @note + * "Deleting" to a trash folder is actually a move, and is covered by msgsMoveCopyCompleted() + * + * @note + * If the user has selected the IMAP delete model (marking messages as deleted, then purging them + * later) for an IMAP account, this notification will not take place on the delete. This will only + * take place on the purge. + */ + void msgsDeleted(in Array<nsIMsgDBHdr> aMsgs); + + /** + * Notified after a command to move or copy a group of messages completes. In + * case of a move, this is before the messages have been deleted from the + * source folder. + * + * @param aMove true if a move, false if a copy + * @param aSrcMsgs An array of the message headers in the source folder + * @param aDestFolder The folder these messages were moved to. + * @param aDestMsgs This provides the list of target message headers. + For imap messages, these will be "pseudo" headers, with + a made up UID. When we download the "real" header, we + will send a msgKeyChanged notification. Currently, if + the imap move/copy happens strictly online (essentially, + not user-initiated), then aDestMsgs will be null. + * + * @note + * If messages are moved from a server which uses the IMAP delete model, + * you'll get aMove = false. That's because the messages are not deleted from + * the source database, but instead simply marked deleted. + */ + void msgsMoveCopyCompleted(in boolean aMove, + in Array<nsIMsgDBHdr> aSrcMsgs, + in nsIMsgFolder aDestFolder, + in Array<nsIMsgDBHdr> aDestMsgs); + + /** + * Notification sent when the msg key for a header may have changed. + * This is used when we create a header for an offline imap move result, + * without knowing what the ultimate UID will be. When we download the + * headers for the new message, we replace the old "pseudo" header with + * a new header that has the correct UID/message key. The uid of the new hdr + * may turn out to be the same as aOldKey if we've guessed correctly but + * the listener can use this notification to know that it can ignore the + * msgAdded notification that's coming for aNewHdr. We do NOT send a + * msgsDeleted notification for the pseudo header. + * + * @param aOldKey The fake UID. The header with this key has been removed + * by the time this is called. + * @param aNewHdr The header that replaces the header with aOldKey. + */ + void msgKeyChanged(in nsMsgKey aOldKey, in nsIMsgDBHdr aNewHdr); + + /** + * msgUnincorporatedMoved: A message received via POP was moved by a + * "before junk" rule. + * + * @param {nsIMsgFolder} srcFolder - Folder the message was moved from. + * @param {nsIMsgDBHdr} msg - The message. + */ + void msgUnincorporatedMoved(in nsIMsgFolder srcFolder, in nsIMsgDBHdr msg); + + /** + * Notified after a folder has been added. + * + * @param aFolder The folder that has just been added + */ + void folderAdded(in nsIMsgFolder aFolder); + + /** + * Notified after a folder has been deleted and its corresponding file(s) deleted from disk. + * + * @param aFolder The folder that has just been deleted + * + * @note + * "Deleting" to a trash folder is actually a move, and is covered by folderMoveCopyCompleted() + */ + void folderDeleted(in nsIMsgFolder aFolder); + + /** + * Notified after a command to move or copy a folder completes. In case of a move, at this point, + * the original folder and its files have already been moved to the new location. + * + * @param aMove true if a move, false if a copy + * @param aSrcFolder The original folder that was moved + * @param aDestFolder The parent folder this folder was moved to + */ + void folderMoveCopyCompleted(in boolean aMove, + in nsIMsgFolder aSrcFolder, + in nsIMsgFolder aDestFolder); + + /** + * Notified after a folder is renamed. + * + * @param aOrigFolder The folder with the old name + * @param aNewFolder The folder with the new name + */ + void folderRenamed(in nsIMsgFolder aOrigFolder, in nsIMsgFolder aNewFolder); + + + /** + * Called to indicate nsIMsgFolderCompactor is beginning compaction of the + * folder. If the summary file was missing or out-of-date and a parse + * is required, this notification will come after the completion of the + * parse. The compactor will be holding the folder's semaphore when + * this notification is generated. This only happens for local folders + * currently. + * + * @param {nsIMsgFolder} folder - Target folder of the compaction. + */ + void folderCompactStart(in nsIMsgFolder folder); + + + /** + * Called when nsIMsgFolderCompactor has completed compaction of the folder. + * At this point, the folder semaphore has been released and the database + * has been committed. + * + * @param {nsIMsgFolder} folder - Target folder of the compaction. + */ + void folderCompactFinish(in nsIMsgFolder folder); + + /** + * The user has opted to rebuild the mork msf index for a folder. + * Following this notification, the database will be closed, backed up + * (so that header properties can be propagated), and then rebuilt from the + * source. The rebuild is triggered by a call to updateFolder, so an + * nsIFolderListener OnFolderEvent(folder, FolderLoaded atom) notification + * will be received if you want to know when this is all completed. + * Note: this event is only generated for Thunderbird because the event + * currently comes from Thunderbird-specific code. + * + * @param {nsIMsgFolder} folder - The folder being reindexed. + */ + void folderReindexTriggered(in nsIMsgFolder folder); +}; |