diff options
Diffstat (limited to 'comm/mailnews/base/public/nsIMsgPluggableStore.idl')
| -rw-r--r-- | comm/mailnews/base/public/nsIMsgPluggableStore.idl | 335 |
1 files changed, 335 insertions, 0 deletions
diff --git a/comm/mailnews/base/public/nsIMsgPluggableStore.idl b/comm/mailnews/base/public/nsIMsgPluggableStore.idl new file mode 100644 index 0000000000..5273d6f0a6 --- /dev/null +++ b/comm/mailnews/base/public/nsIMsgPluggableStore.idl @@ -0,0 +1,335 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* 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" + +interface nsIMsgFolder; +interface nsIMsgCopyServiceListener; +interface nsIMsgDBHdr; +interface nsIMsgWindow; +interface nsIOutputStream; +interface nsIInputStream; +interface nsIUrlListener; +interface nsIMsgDatabase; +interface nsITransaction; + +[scriptable, uuid(F732CE58-E540-4dc4-B803-9456056EBEFC)] + +/** + * Pluggable message store interface. Each incoming server can have a different + * message store. + * All methods are synchronous unless otherwise specified. + */ +interface nsIMsgPluggableStore : nsISupports { + /** + * Examines the store and adds subfolders for the existing folders in the + * profile directory. aParentFolder->AddSubfolder is the normal way + * to register the subfolders. This method is expected to be synchronous. + * This shouldn't be confused with server folder discovery, which is allowed + * to be asynchronous. + * + * @param aParentFolder folder whose existing children we want to discover. + * This will be the root folder for the server object. + * @param aDeep true if we should discover all descendents. Would we ever + * not want to do this? + */ + + void discoverSubFolders(in nsIMsgFolder aParentFolder, in boolean aDeep); + /** + * Creates storage for a new, empty folder. + * + * @param aParent parent folder + * @param aFolderName leaf name of folder. + * @return newly created folder. + * @exception NS_MSG_FOLDER_EXISTS If the child exists. + * @exception NS_MSG_CANT_CREATE_FOLDER for other errors. + */ + nsIMsgFolder createFolder(in nsIMsgFolder aParent, in AString aFolderName); + + /** + * Delete storage for a folder and its subfolders, if any. + * This is a real delete, not a move to the trash folder. + * + * @param aFolder folder to delete + */ + void deleteFolder(in nsIMsgFolder aFolder); + + /** + * Rename storage for an existing folder. + * + * @param aFolder folder to rename + * @param aNewName name to give new folder + * @return the renamed folder object + */ + nsIMsgFolder renameFolder(in nsIMsgFolder aFolder, in AString aNewName); + + /** + * Tells if the store has the requested amount of space available in the + * specified folder. + * + * @param aFolder folder we want to add messages to. + * @param aSpaceRequested How many bytes we're trying to add to the store. + * + * The function returns an exception if there is not enough space to + * indicate the reason of the shortage: + * NS_ERROR_FILE_TOO_BIG = the store cannot grow further due to internal limits + * NS_ERROR_FILE_NO_DEVICE_SPACE = there is not enough space on the disk + */ + boolean hasSpaceAvailable(in nsIMsgFolder aFolder, + in long long aSpaceRequested); + + /** + * Move/Copy a folder to a new parent folder. This method is asynchronous. + * The store needs to use the aListener to notify the core code of the + * completion of the operation. And it must send the appropriate + * nsIMsgFolderNotificationService notifications. + * + * @param aSrcFolder folder to move/copy + * @param aDstFolder parent dest folder + * @param aIsMoveFolder true if move, false if copy. If move, source folder + * is deleted when copy completes. + * @param aMsgWindow used to display progress, may be null + * @param aListener - used to get notification when copy is done. + * @param aNewName Optional new name for the target folder. + * If rename is not needed, set this to empty string. + */ + void copyFolder(in nsIMsgFolder aSrcFolder, in nsIMsgFolder aDstFolder, + in boolean aIsMoveFolder, in nsIMsgWindow aMsgWindow, + in nsIMsgCopyServiceListener aListener, + in AString aNewName); + + /** + * Get an output stream for a message in a folder. + * + * @param aFolder folder to create a message output stream for. + * @param aNewHdr If aNewHdr is set on input, then this is probably for + * offline storage of an existing message. If null, the + * this is a newly downloaded message and the store needs + * to create a new header for the new message. If the db + * is invalid, this can be null. But if the db is valid, + * the store should create a message header with the right + * message key, or whatever other property it needs to set to + * be able to retrieve the message contents later. If the store + * needs to base any of this on the contents of the message, + * it will need remember the message header and hook into + * the output stream somehow to alter the message header. + * + * @return The output stream to write to. The output stream will be positioned + * for writing (e.g., for berkeley mailbox, it will be at the end). + */ + nsIOutputStream getNewMsgOutputStream(in nsIMsgFolder aFolder, + inout nsIMsgDBHdr aNewHdr); + + + /** + * Called when the current message is discarded, e.g., it is moved + * to an other folder as a filter action, or is deleted because it's + * a duplicate. This gives the berkeley mailbox store a chance to simply + * truncate the Inbox w/o leaving a deleted message in the store. + * + * discardNewMessage closes aOutputStream always unless the passed stream + * is nullptr due to error processing.. + * (Clarification/Rationale in Bug 1121842, 1122698, 1242030) + * + * @param aOutputStream stream we were writing the message to be discarded to + * @param aNewHdr header of message to discard + */ + void discardNewMessage(in nsIOutputStream aOutputStream, + in nsIMsgDBHdr aNewHdr); + + /** + * Must be called by code that calls getNewMsgOutputStream to finish + * the process of storing a new message, if the new msg has not been + * discarded. Could/should this be combined with discardNewMessage? + * + * finishNewMessage closes aOutputStream always unless the passed stream + * is nullptr due to error processing. + * (Clarification/Rationale in Bug 1121842, 1122698, 1242030) + * + * @param aOutputStream stream we were writing the message to. + * @param aNewHdr header of message finished. + */ + void finishNewMessage(in nsIOutputStream aOutputStream, + in nsIMsgDBHdr aNewHdr); + + /** + * Called by pop3 message filters when a newly downloaded message is being + * moved by an incoming filter. This is called before finishNewMessage, and + * it allows the store to optimize that case. + * + * @param aNewHdr msg hdr of message being moved. + * @param aDestFolder folder to move message to, in the same store. + * + * @return true if successful, false if the store doesn't want to optimize + * this. + * @exception If the moved failed. values TBD + */ + boolean moveNewlyDownloadedMessage(in nsIMsgDBHdr aNewHdr, + in nsIMsgFolder aDestFolder); + + /** + * Get an input stream that we can read the contents of a message from. + * + * @param aMsgFolder Folder containing the message + * @param aMsgToken token that identifies message. This is store-dependent, + * and must be set as a string property "storeToken" on the + * message hdr by the store when the message is added + * to the store. + */ + nsIInputStream getMsgInputStream(in nsIMsgFolder aFolder, + in ACString aMsgToken); + + /** + * This is a hack to expose to allow JsAccount folders to implement a + * working getLocalMsgStream(). + * It just provides a way to construct a SlicedInputStream from JS. + * It'll be removed once Bug 1733849 is complete. + * + * @param inStream The stream providing the data to be sliced. + * Should not be read after calling this function. + * @param start Where slice begins, from current position of inStream. + * @param length The size of the slice. + * + * @return A new input stream which produces the data slice when read from. + */ + nsIInputStream sliceStream(in nsIInputStream inStream, + in unsigned long long start, + in unsigned long length); + + /** + * Delete the passed in messages. These message should all be in the + * same folder. + * @param aHdrArray array of nsIMsgDBHdr's. + */ + void deleteMessages(in Array<nsIMsgDBHdr> aHdrArray); + + /** + * This allows the store to handle a msg move/copy if it wants. This lets + * it optimize move/copies within the same store. E.g., for maildir, a + * msg move mostly entails moving the file containing the message, and + * updating the db. + * If the store does the copy, it must return the appropriate undo action, + * which can be store dependent. And it must send the appropriate + * nsIMsgFolderNotificationService notifications. + * If the store does not perform the copy, it returns false and the caller + * has to handle the copy itself (by streaming messages). + * This function is synchronous. + * + * @param isMove true if this is a move, false if it is a copy. + * @param aHdrArray array of nsIMsgDBHdr's, all in the same folder + * @param aDstFolder folder to move/copy the messages to. + * @param aDstHdrs array of nsIMsgDBHdr's in the destination folder. + * @param[out,optional] aUndoAction transaction to provide undo, if + * the store does the copy itself. + * @return true if messages were copied, false if the core code should + * do the copy. + */ + boolean copyMessages(in boolean isMove, + in Array<nsIMsgDBHdr> aHdrArray, + in nsIMsgFolder aDstFolder, + out Array<nsIMsgDBHdr> aDstHdrs, + out nsITransaction aUndoAction); + + /** + * Does this store require compaction? For example, maildir doesn't require + * compaction at all. Berkeley mailbox does. A sqlite store probably doesn't. + * This is a static property of the store. It doesn't mean that any particular + * folder has space that can be reclaimed via compaction. Right now, the core + * code keeps track of the size of messages deleted, which it can use in + * conjunction with this store attribute. + */ + readonly attribute boolean supportsCompaction; + + /** + * Remove deleted messages from the store, reclaiming space. Some stores + * won't need to do anything here (e.g., maildir), and those stores + * should return false for needsCompaction. This operation is asynchronous, + * and the passed url listener should be called when the operation is done. + * + * @param aFolder folder whose storage is to be compacted + * @param aListener listener notified when compaction is done. + * @param aMsgWindow window to display progress/status in. + */ + void compactFolder(in nsIMsgFolder aFolder, in nsIUrlListener aListener, + in nsIMsgWindow aMsgWindow); + + /** + * Is the summary file for the passed folder valid? For Berkeley Mailboxes, + * for local mail folders, this checks the timestamp and size of the local + * mail folder against values stored in the db. For other stores, this may + * be a noop, though other stores could certainly become invalid. For + * Berkeley Mailboxes, this is to deal with the case of other apps altering + * mailboxes from outside mailnews code, and this is certainly possible + * with other stores. + * + * @param aFolder Folder to check if summary is valid for. + * @param aDB DB to check validity of. + * + * @return return true if the summary file is valid, false otherwise. + */ + boolean isSummaryFileValid(in nsIMsgFolder aFolder, in nsIMsgDatabase aDB); + + /** + * Marks the summary file for aFolder as valid or invalid. This method + * may not be required, since it's really used by Berkeley Mailbox code + * to fix the timestamp and size for a folder. + * + * @param aFolder folder whose summary file should be marked (in)valid. + * @param aDB db to mark valid (may not be the folder's db in odd cases + * like folder compaction. + * @param aValid whether to mark it valid or invalid. + */ + void setSummaryFileValid(in nsIMsgFolder aFolder, in nsIMsgDatabase aDB, + in boolean aValid); + + /** + * Rebuild the index from information in the store. This involves creating + * a new nsIMsgDatabase for the folder, adding the information for all the + * messages in the store, and then copying the new msg database over the + * existing database. For Berkeley mailbox, we try to maintain meta data + * stored in the existing database when possible, and other stores should do + * the same. Ideally, I would figure out a way of making that easy. That + * might entail reworking the rebuild index process into one where the store + * would iterate over the messages, and stream each message through the + * message parser, and the common code would handle maintaining the + * meta data. But the berkeley mailbox code needs to do some parsing because + * it doesn't know how big the message is (i.e., the stream can't simply be + * a file stream). + * This operation is asynchronous, + * and the passed url listener should be called when the operation is done. + * + * @param aFolder folder whose storage is to be compacted + * @param aMsgDB db to put parsed headers in. + * @param aMsgWindow msgWindow to use for progress updates. + * @param aListener listener notified when the index is rebuilt. + */ + void rebuildIndex(in nsIMsgFolder aFolder, in nsIMsgDatabase aMsgDB, + in nsIMsgWindow aMsgWindow, in nsIUrlListener aListener); + + /** + * Sets/Clears the passed flags on the passed messages. + * @param aHdrArray array of nsIMsgDBHdr's + * @param aFlags flags to set/clear + * @param aSet true to set the flag(s), false to clear. + */ + void changeFlags(in Array<nsIMsgDBHdr> aHdrArray, in unsigned long aFlags, + in boolean aSet); + /** + *Sets/Clears the passed keywords on the passed messages. + * @param aHdrArray array of nsIMsgDBHdr's + * @param aKeywords keywords to set/clear + * @param aAdd true to add the keyword(s), false to remove. + */ + void changeKeywords(in Array<nsIMsgDBHdr> aHdrArray, in ACString aKeywords, + in boolean aAdd); + + /** + * Identifies a specific type of store. Please use this only for legacy + * bug fixes, and not as a method to change behavior! + * + * Typical values: "mbox", "maildir" + */ + readonly attribute ACString storeType; +}; |