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
210
211
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);
};
|
