diff options
Diffstat (limited to 'mailnews/base/public/nsIMsgFolderListener.idl')
| -rw-r--r-- | mailnews/base/public/nsIMsgFolderListener.idl | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/mailnews/base/public/nsIMsgFolderListener.idl b/mailnews/base/public/nsIMsgFolderListener.idl new file mode 100644 index 000000000..de557b846 --- /dev/null +++ b/mailnews/base/public/nsIMsgFolderListener.idl @@ -0,0 +1,212 @@ +/* -*- 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; +interface nsIArray; + +/** + * 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 nsIArray aMsgs, in boolean aJunkProcessed, + in boolean aTraitProcessed); + + /** + * 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 nsIArray 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 nsIArray aSrcMsgs, + in nsIMsgFolder aDestFolder, + in nsIArray 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); + + /** + * 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); + + /** + * Notified when a particular event takes place for an item. + * + * Current uses by event string: + * + * - FolderCompactStart: 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. aItem is the folder. + * - FolderCompactFinish: nsIMsgFolderCompactor has completed compaction of + * the folder. This notification will be generated immediately prior to + * the nsIFolderListener::itemEvent() notification with a + * "CompactCompleted" atom. At this point, the folder semaphore has been + * released and the database has been committed. aItem is the folder. + * + * - FolderReindexTriggered: 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 OnItemEvent(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. + * + * - JunkStatusChanged: 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 + * notification may be promoted to an explicit callback function at some + * point. 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. aItem is an nsIArray of + * messages, aData is either a "junk" or "notjunk" atom if all of the + * messages have the same state. + * + * - UnincorporatedMessageMoved: A messages received via POP was moved + * by a "before junk" rule. + * + * @param aItem The item the event takes place on + * @param aEvent String describing the event + * @param aData Data relevant to the event + */ + void itemEvent(in nsISupports aItem, in ACString aEvent, in nsISupports aData); +}; |