1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is mozilla.org code.
16 *
17 * The Initial Developer of the Original Code is
18 * Netscape Communications Corporation.
19 * Portions created by the Initial Developer are Copyright (C) 1998
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 * David Bienvenu <bienvenu@nventure.com>
24 *
25 * Alternatively, the contents of this file may be used under the terms of
26 * either of the GNU General Public License Version 2 or later (the "GPL"),
27 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
28 * in which case the provisions of the GPL or the LGPL are applicable instead
29 * of those above. If you wish to allow use of your version of this file only
30 * under the terms of either the GPL or the LGPL, and not to allow others to
31 * use your version of this file under the terms of the MPL, indicate your
32 * decision by deleting the provisions above and replace them with the notice
33 * and other provisions required by the GPL or the LGPL. If you do not delete
34 * the provisions above, a recipient may use your version of this file under
35 * the terms of any one of the MPL, the GPL or the LGPL.
36 *
37 * ***** END LICENSE BLOCK ***** */
38
39 #include "nsISupports.idl"
40 #include "nsIFolderListener.idl"
41 #include "nsIMsgThread.idl"
42 #include "nsIMsgIncomingServer.idl"
43 #include "nsISupportsArray.idl"
44 #include "nsIMsgCopyServiceListener.idl"
45 #include "nsIUrlListener.idl"
46 #include "nsISimpleEnumerator.idl"
47
48 [ptr] native octet_ptr(PRUint8);
49
50 interface nsIMsgDBHdr;
51 interface nsIMsgWindow;
52 interface nsIMsgDatabase;
53 interface nsIDBFolderInfo;
54 interface nsIMsgFilterList;
55
56 interface nsIMsgFolderCacheElement;
57 interface nsITransport;
58 interface nsIFile;
59 interface nsIOutputStream;
60 interface nsIInputStream;
61 interface nsILocalFile;
62 interface nsIMsgIdentity;
63
64 typedef long nsMsgBiffState;
65
66 // enumerated type for determining if a message has been replied to, forwarded, etc.
67 typedef long nsMsgDispositionState;
68
69 [scriptable, uuid(31fa97db-c073-4ea1-a4ad-f561269dcf8d)]
70 interface nsIMsgFolder : nsISupports {
71
72 const nsMsgBiffState nsMsgBiffState_NewMail = 0; // User has new mail waiting.
73 const nsMsgBiffState nsMsgBiffState_NoMail = 1; // No new mail is waiting.
74 const nsMsgBiffState nsMsgBiffState_Unknown = 2; // We dunno whether there is new mail.
75
76 nsISimpleEnumerator getMessages(in nsIMsgWindow aMsgWindow);
77
78 void startFolderLoading();
79 void endFolderLoading();
80
81 /* get new headers for db */
82 void updateFolder(in nsIMsgWindow aWindow);
83
84 readonly attribute AString prettiestName;
85
86 /**
87 * URL for this folder
88 */
89 readonly attribute ACString folderURL;
90
91 /**
92 * should probably move to the server
93 */
94 readonly attribute boolean showDeletedMessages;
95
96 /**
97 * this folder's parent server
98 */
99 readonly attribute nsIMsgIncomingServer server;
100
101 /**
102 * is this folder the "phantom" server folder?
103 */
104 readonly attribute boolean isServer;
105 readonly attribute boolean canSubscribe;
106 readonly attribute boolean canFileMessages;
107 readonly attribute boolean noSelect; // this is an imap no select folder
108 readonly attribute boolean imapShared; // this is an imap shared folder
109 readonly attribute boolean canDeleteMessages; // can't delete from imap read-only
110
111 /**
112 * does this folder allow subfolders?
113 * for example, newsgroups cannot have subfolders, and the INBOX
114 * on some IMAP servers cannot have subfolders
115 */
116 readonly attribute boolean canCreateSubfolders;
117
118 /**
119 * can you change the name of this folder?
120 * for example, newsgroups
121 * and some special folders can't be renamed
122 */
123 readonly attribute boolean canRename;
124
125 readonly attribute boolean canCompact;
126
127 /**
128 * the phantom server folder
129 */
130 readonly attribute nsIMsgFolder rootFolder;
131
132 /**
133 * function to get the filter list on folder's server
134 * (or in the case of news, the filter list for this newsgroup)'
135 */
136 nsIMsgFilterList getFilterList(in nsIMsgWindow msgWindow);
137 void setFilterList(in nsIMsgFilterList filterList);
138
139 void ForceDBClosed ();
140 void Delete ();
141
142 void deleteSubFolders(in nsISupportsArray folders, in nsIMsgWindow msgWindow);
143 void propagateDelete(in nsIMsgFolder folder, in boolean deleteStorage,
144 in nsIMsgWindow msgWindow);
145 void recursiveDelete(in boolean deleteStorage, in nsIMsgWindow msgWindow);
146
147 void createSubfolder(in AString folderName, in nsIMsgWindow msgWindow);
148 nsIMsgFolder addSubfolder(in AString folderName);
149 /* this method ensures the storage for the folder exists.
150 For local folders, it creates the berkeley mailbox if missing.
151 For imap folders, it subscribes to the folder if it exists,
152 or creates it if it doesn't exist
153 */
154 void createStorageIfMissing(in nsIUrlListener urlListener);
155
156 void compact(in nsIUrlListener aListener, in nsIMsgWindow aMsgWindow);
157 void compactAll(in nsIUrlListener aListener, in nsIMsgWindow aMsgWindow,
158 in nsISupportsArray aFolderArray, in boolean aCompactOfflineAlso,
159 in nsISupportsArray aOfflineFolderArray);
160 void compactAllOfflineStores(in nsIMsgWindow aMsgWindow,
161 in nsISupportsArray aOfflineFolderArray);
162 void emptyTrash(in nsIMsgWindow aMsgWindow, in nsIUrlListener aListener);
163
164 /**
165 * change the name of the folder
166 *
167 * @param name the new name of the folder
168 */
169 void rename(in AString name, in nsIMsgWindow msgWindow);
170 void renameSubFolders( in nsIMsgWindow msgWindow, in nsIMsgFolder oldFolder);
171 /**
172 * looks in immediate children of this folder for the given name
173 *
174 * @param name the name of the target subfolder
175 */
176 boolean containsChildNamed(in AString name);
177 boolean isAncestorOf(in nsIMsgFolder folder);
178
179 AString generateUniqueSubfolderName(in AString prefix,
180 in nsIMsgFolder otherFolder);
181
182 void updateSummaryTotals(in boolean force);
183 void summaryChanged();
184 /**
185 * get the total number of unread messages in this folder,
186 * or in all subfolders
187 *
188 * @param deep if true, descends into all subfolders and gets a grand total
189 */
190 long getNumUnread(in boolean deep);
191
192 /**
193 * get the total number of messages in this folder,
194 * or in all subfolders
195 *
196 * @param deep if true, descends into all subfolders and gets a grand total
197 */
198 long getTotalMessages(in boolean deep);
199
200 /**
201 * does this folder have new messages
202 *
203 */
204 attribute boolean hasNewMessages;
205
206 /**
207 * return the first new message in the folder
208 *
209 */
210 readonly attribute nsIMsgDBHdr firstNewMessage;
211
212 /**
213 * clear new status flag of all of the new messages
214 *
215 */
216 void clearNewMessages();
217
218 readonly attribute unsigned long expungedBytes;
219
220 /**
221 * can this folder be deleted?
222 * for example, special folders cannot be deleted
223 */
224 readonly attribute boolean deletable;
225
226 /**
227 * should we be displaying recipients instead of the sender?
228 * for example, in the Sent folder, recipients are more relevant
229 * than the sender
230 */
231 readonly attribute boolean displayRecipients;
232
233 /**
234 * used to determine if it will take a long time to download all
235 * the headers in this folder - so that we can do folder notifications
236 * synchronously instead of asynchronously
237 */
238 readonly attribute boolean manyHeadersToDownload;
239
240 readonly attribute boolean requiresCleanup;
241 void clearRequiresCleanup();
242
243 /**
244 * this should go into a news-specific interface
245 */
246 readonly attribute boolean knowsSearchNntpExtension;
247
248 /**
249 * this should go into a news-specific interface
250 */
251 readonly attribute boolean allowsPosting;
252
253 readonly attribute ACString relativePathName;
254
255 /**
256 * size of this folder on disk (not including .msf file)
257 * for imap, it's the sum of the size of the messages
258 */
259 attribute unsigned long sizeOnDisk;
260
261 readonly attribute ACString username;
262 readonly attribute ACString hostname;
263
264 void setFlag(in unsigned long flag);
265 void clearFlag(in unsigned long flag);
266 boolean getFlag(in unsigned long flag);
267 void setPrefFlag();
268
269 void toggleFlag (in unsigned long flag);
270 void onFlagChange (in unsigned long flag);
271
272 attribute unsigned long flags;
273
274 nsIMsgFolder getFoldersWithFlag(in unsigned long flags,
275 in unsigned long resultsize,
276 out unsigned long numFolders);
277
278 nsISupportsArray getAllFoldersWithFlag(in unsigned long aFlag);
279
280 void getExpansionArray(in nsISupportsArray expansionArray);
281
282 ACString getUriForMsg(in nsIMsgDBHdr msgHdr);
283
284 void deleteMessages(in nsISupportsArray messages,
285 in nsIMsgWindow msgWindow,
286 in boolean deleteStorage, in boolean isMove,
287 in nsIMsgCopyServiceListener listener, in boolean allowUndo);
288
289 void copyMessages(in nsIMsgFolder srcFolder, in nsISupportsArray messages,
290 in boolean isMove, in nsIMsgWindow msgWindow,
291 in nsIMsgCopyServiceListener listener, in boolean isFolder,
292 in boolean allowUndo);
293
294 void copyFolder(in nsIMsgFolder srcFolder, in boolean isMoveFolder,
295 in nsIMsgWindow msgWindow, in nsIMsgCopyServiceListener listener );
296
297 void copyFileMessage(in nsIFile file, in nsIMsgDBHdr msgToReplace,
298 in boolean isDraft, in unsigned long newMsgFlags,
299 in nsIMsgWindow msgWindow,
300 in nsIMsgCopyServiceListener listener);
301
302 void acquireSemaphore (in nsISupports semHolder);
303 void releaseSemaphore (in nsISupports semHolder);
304 boolean testSemaphore (in nsISupports semHolder);
305 readonly attribute boolean locked;
306
307 void getNewMessages(in nsIMsgWindow aWindow, in nsIUrlListener aListener);
308
309 /**
310 * write out summary data for this folder
311 * to the given folder cache (i.e. panacea.dat)
312 */
313 void writeToFolderCache(in nsIMsgFolderCache folderCache, in boolean deep);
314
315 /**
316 * the charset of this folder
317 */
318 attribute ACString charset;
319 attribute boolean charsetOverride;
320 attribute unsigned long biffState;
321
322 /**
323 * the number of new messages since this folder was last visited
324 * @param deep if true, descends into all subfolders and gets a grand total
325 */
326
327 long getNumNewMessages (in boolean deep);
328
329 void setNumNewMessages(in long numNewMessages);
330
331 /**
332 * are we running a url as a result of the user clicking get msg?
333 */
334 attribute boolean gettingNewMessages;
335
336 /**
337 * local path of this folder
338 */
339 attribute nsILocalFile filePath;
340
341 readonly attribute ACString baseMessageURI;
342 ACString generateMessageURI(in nsMsgKey msgKey);
343
344 const nsMsgDispositionState nsMsgDispositionState_None = -1;
345 const nsMsgDispositionState nsMsgDispositionState_Replied = 0;
346 const nsMsgDispositionState nsMsgDispositionState_Forwarded = 1;
347 void addMessageDispositionState(in nsIMsgDBHdr aMessage,
348 in nsMsgDispositionState aDispositionFlag);
349
350 void markMessagesRead(in nsISupportsArray messages, in boolean markRead);
351 void markAllMessagesRead();
352 void markMessagesFlagged(in nsISupportsArray messages, in boolean markFlagged);
353 void markThreadRead(in nsIMsgThread thread);
354 void setLabelForMessages(in nsISupportsArray messages, in nsMsgLabelValue label);
355 nsIMsgDatabase getMsgDatabase(in nsIMsgWindow msgWindow);
356 void setMsgDatabase (in nsIMsgDatabase msgDatabase);
357 nsIMsgDatabase getDBFolderInfoAndDB(out nsIDBFolderInfo folderInfo);
358 nsIMsgDBHdr GetMessageHeader(in nsMsgKey msgKey);
359
360 readonly attribute boolean supportsOffline;
361 boolean shouldStoreMsgOffline(in nsMsgKey msgKey);
362 boolean hasMsgOffline(in nsMsgKey msgKey);
363
364 nsIInputStream getOfflineFileStream(in nsMsgKey msgKey, out PRUint32 offset,
365 out PRUint32 size);
366 readonly attribute nsIOutputStream offlineStoreOutputStream;
367 readonly attribute nsIInputStream offlineStoreInputStream;
368 void DownloadMessagesForOffline(in nsISupportsArray messages,
369 in nsIMsgWindow window);
370 nsIMsgFolder getChildWithURI(in ACString uri, in boolean deep,
371 in boolean caseInsensitive);
372 void downloadAllForOffline(in nsIUrlListener listener, in nsIMsgWindow window);
373 /**
374 * Turn notifications on/off for various notification types. Currently only
375 * supporting allMessageCountNotifications which refers to both total and
376 * unread message counts.
377 */
378 const unsigned long allMessageCountNotifications = 0;
379 void enableNotifications(in long notificationType, in boolean enable,
380 in boolean dbBatching);
381 boolean isCommandEnabled(in ACString command);
382 boolean matchOrChangeFilterDestination(in nsIMsgFolder folder,
383 in boolean caseInsensitive);
384 boolean confirmFolderDeletionForFilter(in nsIMsgWindow msgWindow);
385 void alertFilterChanged(in nsIMsgWindow msgWindow);
386 void throwAlertMsg(in string msgName, in nsIMsgWindow msgWindow);
387 AString getStringWithFolderNameFromBundle(in string msgName);
388 void notifyCompactCompleted();
389 long compareSortKeys(in nsIMsgFolder msgFolder);
390 [noscript] void getSortKey(out octet_ptr key, out unsigned long length);
391
392 attribute nsIMsgRetentionSettings retentionSettings;
393 attribute nsIMsgDownloadSettings downloadSettings;
394 boolean callFilterPlugins(in nsIMsgWindow aMsgWindow);
395 /**
396 * used for order in the folder pane, folder pickers, etc.
397 */
398 attribute long sortOrder;
399
400 /* handy accessor when we want a msg folder */
401 readonly attribute nsIMsgFolder parentMsgFolder;
402
403 attribute nsIDBFolderInfo dBTransferInfo;
404
405 ACString getStringProperty(in string propertyName);
406 void setStringProperty(in string propertyName, in ACString propertyValue);
407
408 /* does not persist across sessions */
409 attribute nsMsgKey lastMessageLoaded;
410
411 /* old nsIFolder properties and methods */
412 readonly attribute ACString URI;
413 attribute AString name;
414 attribute AString prettyName;
415 readonly attribute AString abbreviatedName;
416
417 nsISupports getChildNamed(in AString name);
418 attribute nsIMsgFolder parent;
419
420 /**
421 * Returns an enumerator containing a list of nsIMsgFolder items that are
422 * subfolders of the instance this is called on.
423 */
424 readonly attribute nsISimpleEnumerator subFolders;
425
426 /**
427 * Returns true if this folder has sub folders.
428 */
429 readonly attribute boolean hasSubFolders;
430
431 /**
432 * Returns the number of sub folders that this folder has.
433 */
434 readonly attribute unsigned long numSubFolders;
435
436 void AddFolderListener(in nsIFolderListener listener);
437 void RemoveFolderListener(in nsIFolderListener listener);
438 nsIMsgFolder FindSubFolder(in ACString escapedSubFolderName);
439
440 void NotifyPropertyChanged(in nsIAtom property,
441 in ACString oldValue,
442 in ACString newValue);
443 void NotifyIntPropertyChanged(in nsIAtom property,
444 in long oldValue,
445 in long newValue);
446 void NotifyBoolPropertyChanged(in nsIAtom property,
447 in boolean oldValue,
448 in boolean newValue);
449 void NotifyPropertyFlagChanged(in nsIMsgDBHdr item,
450 in nsIAtom property,
451 in unsigned long oldValue,
452 in unsigned long newValue);
453 void NotifyUnicharPropertyChanged(in nsIAtom property,
454 in AString oldValue,
455 in AString newValue);
456
457 void NotifyItemAdded(in nsISupports item);
458 void NotifyItemRemoved(in nsISupports item);
459
460 void NotifyFolderEvent(in nsIAtom event);
461
462 // void NotifyFolderLoaded();
463 // void NotifyDeleteOrMoveMessagesCompleted(in nsIMsgFolder folder);
464
465 // lists all descendents, not just first level children
466 void ListDescendents(in nsISupportsArray descendents);
467 void Shutdown(in boolean shutdownChildren);
468
469 readonly attribute boolean inVFEditSearchScope;
470 void setInVFEditSearchScope(in boolean aSearchThisFolder, in boolean aSetOnSubFolders);
471 void copyDataToOutputStreamForAppend(in nsIInputStream aIStream,
472 in long aLength, in nsIOutputStream outputStream);
473 void copyDataDone();
474 void setJunkScoreForMessages(in nsISupportsArray aMessages, in ACString aJunkScore);
475 void applyRetentionSettings();
476
477 /**
478 * Get the beginning of the message bodies for the passed in keys and store
479 * them in the msg hdr property "preview". This is intended for
480 * new mail alerts, title tips on folders with new messages, and perhaps
481 * titletips/message preview in the thread pane.
482 *
483 * @param aKeysToFetch keys of msgs to fetch
484 * @param aNumKeys number of keys to fetch
485 * @param aLocalOnly whether to fetch msgs from server (imap msgs might
486 * be in memory cache from junk filter)
487 * @param aUrlListener url listener to notify if we run url to fetch msgs
488 *
489 * @result aAsyncResults if true, we ran a url to fetch one or more of msg bodies
490 *
491 */
492 boolean fetchMsgPreviewText([array, size_is (aNumKeys)] in nsMsgKey aKeysToFetch,
493 in unsigned long aNumKeys, in boolean aLocalOnly,
494 in nsIUrlListener aUrlListener);
495
496 // used to set/clear tags - we could have a single method to setKeywords which
497 // would figure out the diffs, but these methods might be more convenient.
498 // keywords are space delimited, in the case of multiple keywords
499 void addKeywordsToMessages(in nsISupportsArray aMessages, in ACString aKeywords);
500 void removeKeywordsFromMessages(in nsISupportsArray aMessages, in ACString aKeywords);
501 /**
502 * Extract the message preview text from aStream, storing it as a string property
503 * on aMsgHdr.
504 *
505 * @param aMsgHdr
506 * @param aStream
507 * @param aBytesToRead number of bytes to read from the stream
508 * @param aMaxOutputLen desired length of the converted message text. Used to control how many characters
509 * of msg text we want to store.
510 * @param aCompressQuotes Replace quotes and citations with " ... " in the preview text
511 */
512 ACString getMsgTextFromStream(in nsIMsgDBHdr aMsgHdr, in nsIInputStream aStream,
513 in long aBytesToRead, in long aMaxOutputLen, in boolean aCompressQuotes);
514
515 // this allows a folder to have a special identity. E.g., you might want to
516 // associate an identity with a particular newsgroup, or for IMAP shared folders in
517 // the other users namespace, you might want to create a delegated identity
518 readonly attribute nsIMsgIdentity customIdentity;
519 };