DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (47b55c578f95)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
/* -*- 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.
   *
   * @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);
};