nsIMessenger 编辑

The nsIMessenger interface provides functions for managing the history, undo and redo operations, and for loading, saving, or deleting messages and attachments in mailnews.

Inherits from: nsISupports

Implemented by: @mozilla.org/messenger;1. To create an instance, use:

 messenger = Components.classes["@mozilla.org/messenger;1"]
                       .createInstance(Components.interfaces.nsIMessenger);

In Thunderbird, a global nsIMessenger object is defined as messenger via the createMessenger function in mailWindow.js.

Method overview

Note: Prior to Gecko 8.0, all references to nsIDOMWindow used in this interface were nsIDOMWindow.

Attributes

Constants

Methods

setDisplayCharset()

Sets the character set for the displayed message.

 void setDisplayCharset(in ACString aCharset);

Parameters

aCharset

The character set to use.

setWindow()

Sets the current window for a messenger session.

 void setWindow(in nsIDOMWindow aWin,
                in nsIMsgWindow aMsgWindow);

Parameters

aWin

The window to set as the window for the messaging session. If this window contains a messagepane element (I think this may mean a XUL:browser element with its id set to "messagepane"?), then the nsIDocShell will be used for future nsIMessenger operations. If there is no messagepane element, then the root XUL nsIDocShell will be used (so that openURL() will still work). If null is passed in then observers are removed in preparation for shutdown.

aMsgWindow

The nsIMsgWindow with the transation manager to be used.

openURL()

Opens a url in the current window (set by setWindow()) and adds it to the current history.

 void openURL(in ACString aURL);

Parameters

aURL

The url to open.

loadURL()

Load a custom message by url. Similar to openURL() except can be used to load things that appear as messages to users (e.g load an attachment as a email).

 void loadURL(in nsIDOMWindow aWin,
              in ACString aURL);

Parameters

aWin

A window. As far as I can tell this isn't used or checked.

aURL

The url to open.

launchExternalURL()

Launches the nsIExternalProtocolService and sends it the url.

 void launchExternalURL(in ACString aURL);

Parameters

aURL

The url to open.

canUndo()

Queries if there are any undo items in the transaction manager.

 boolean canUndo();

Return value

Boolean representing whether undo is available.

canRedo()

Queries if there are any redo items in the transaction manager.

 boolean canRedo();

Return value

Boolean representing whether redo is available.

getUndoTransactionType()

Gets the type of the next undo transaction.

 unsigned long getUndoTransactionType();

Return value

A long representing the type of the transaction. See #Constants for available types.

getRedoTransactionType()

Gets the type of the next redo transaction. Available types are defined as constants in nsIMessenger.

 unsigned long getRedoTransactionType();

Return value

A long representing the type of the transaction. See #Constants for available types.

undo()

Performs the next undo transaction.

 void undo(in nsIMsgWindow msgWindow);

Parameters

msgWindow

The nsIMsgWindow to perform the undo transaction on.

redo()

Performs the next redo transaction.

 void redo(in nsIMsgWindow msgWindow);

Parameters

msgWindow

The nsIMsgWindow to perform the redo transaction on.

sendUnsentMessages()

Creates a nsIMsgSendLater instance and sends all messages for the given identity.

 void sendUnsentMessages(in nsIMsgIdentity aIdentity,
                         in nsIMsgWindow aMsgWindow);

Parameters

aIdentity

The nsIMsgIdentity to send messages for.

aMsgWindow

The nsIMsgWindow to get messages from.

setDocumentCharset()

Redisplay the currently selected message (if any) using the given character set.

 void setDocumentCharset(in ACString characterSet);

Parameters

characterSet

The character set to use.

saveAs()

Save the URL given.

 void saveAs(in ACString aURI,
             in boolean aAsFile,
             in nsIMsgIdentity aIdentity,
             in AString aMsgFilename);

Parameters

aURI

The URL of the message to save.

aAsFile

If true a file picker is spawned with the option save the message as HTML, text, or EML. If false, the message is saved as a Template

aIdentity

The identity to use if saving as a Template.

aMsgFilename

The filename to use as the default filename if we are saving as a file.

openAttachment()

Open an attachment.

 void openAttachment(in ACString contentType,
                     in ACString url,
                     in ACString displayName,
                     in ACString messageUri,
                     in boolean isExternalAttachment);

Parameters

contentType

The content type of the attachment.

url

The url of the attachment.

displayName

The file name for display purposes.

messageUri

The url of the message containing the attachment.

isExternalAttachment

Is the attachment inside a message or saved somewhere externally. If set to true the attachment is opened inside the message pane which in turn should trigger the helper app dialog. Same as just using the openURL() method.

saveAttachment()

Save an attachment.

 void saveAttachment(in ACString contentType,
                     in ACString url,
                     in ACString displayName,
                     in ACString messageUri,
                     in boolean isExternalAttachment);

Parameters

contentType

The content type of the attachment.

url

The url of the attachment.

displayName

The file name for display purposes.

messageUri

The url of the message containing the attachment.

isExternalAttachment

Is the attachment inside a message or saved somewhere externally. If set to true the attachment is opened inside the message pane which in turn should trigger the helper app dialog. Same as just using the openURL() method.

saveAllAttachments()

Launches a filepicker and saves all attachments listed in an array.

 void saveAllAttachments(in unsigned long count,
                         [array, size_is(count)] in string contentTypeArray,
                         [array, size_is(count)] in string urlArray,
                         [array, size_is(count)] in string displayNameArray,
                         [array, size_is(count)] in string messageUriArray);

Parameters

count

The number of attachments being saved.

contentTypeArray

An array of content types for each attachment.

urlArray

An array of urls for each attachment.

displayNameArray

An array of file names for each attachment.

messageUriArray

An array of message uris for each attachment.

saveAttachmentToFile()

Save an attachment to a particular nsIFile.

 void saveAttachmentToFile(in nsIFile aFile,
                           in ACString aUrl,
                           in ACString aMessageUri,
                           in ACString aContentType,
                           in nsIUrlListener aListener);

Parameters

aFile

The nsIFile to save to.

aUrl

The url of the attachment.

aMessageUri

The url of the message containing this attachment.

aContentType

The content type of the attachment.

aListener

An nsIUrlListener to be notified when the file is saved.

detachAttachment()

Deletes an attachment from a message.

 void detachAttachment(in string contentType,
                       in string url,
                       in string displayName,
                       in string messageUri,
                       in boolean saveFirst,
                       [optional] in boolean withoutWarning);

Parameters

contentType

The content type of the attachment.

url

The url of the attachment.

displayName

The file name of the attachment.

messageUri

The url of the message containing the attachment.

saveFirst

If true, the attachment is saved using saveAttachment() before it is deleted.

withoutWarning

If true, no warning is shown to the user before the delete.

detachAllAttachments()

Deletes a set of attachments.

 void detachAllAttachments(in unsigned long count,
                           [array, size_is(count)] in string contentTypeArray,
                           [array, size_is(count)] in string urlArray,
                           [array, size_is(count)] in string displayNameArray,
                           [array, size_is(count)] in string messageUriArray,
                           in boolean saveFirst,
                           [optional] in boolean withoutWarning);

Parameters

count

The number of attachments to be deleted.

contentTypeArray

An array of content types for each attachment.

urlArray

An array of urls for each attachment.

displayNameArray

An array of file names for each attachment.

messageUriArray

An array of urls for the message containing each attachment.

saveFirst

If true, the attachments are saved using saveAllAttachments() before being deleted.

withoutWarning

If true, no warning is shown to the user before the delete.

saveAttachmentToFolder()

Saves an attachment in a given folder. saveAttachmentToFolder() is used by the drag and drop code to drop an attachment to a destination folder. Returns the actual file path (including the filename).

 nsILocalFile saveAttachmentToFolder(in ACString ,
                                     in ACString url,
                                     in ACString displayName,
                                     in ACString messageUri,
                                     in nsILocalFile aDestFolder);

Parameters

contentType

The content type of the attachment.

url

The url of the attachment.

displayName

The file name of the attachment.

messageUri

The url of the message containing the attachment.

aDestFolder

An nsILocalFile poiting to the folder where the attachment should be saved.

Return value

The actual nsILocalFile where the attachment was saved.

messageServiceFromURI()

Gets the nsIMsgMessageService in charge of a particular url. Message services are implemented for different protocols such as IMAP, POP3, or local mail sources.

 nsIMsgMessageService messageServiceFromURI(in ACString aUri);

Parameters

aUri

The url of the message or attachment to get the service for.

Return value

The nsIMsgMessageService responsible for the url.

msgHdrFromURI()

 nsIMsgDBHdr msgHdrFromURI(in ACString aUri);

getMsgUriAtNavigatePos()

Gets the message a particular position in the navigation history. For example, back-forward history needs a list of visited messages, and where it is in the list. Unfortunately, you must call this before navigating to a position, because calling this has the side effect of making us adjust our current history position, and not adding the loaded message to the history queue.

 ACString getMsgUriAtNavigatePos(in long aPos);

Parameters

aPos

The position to get the url from relative to the current history cursor. +1 is forward, -1 is back.

Return value

The url at that point in the history.

getFolderUriAtNavigatePos()

Gets the folder url at a particular position in the navigation history.

 ACString getFolderUriAtNavigatePos(in long aPos);

Parameters

aPos

The position to get the url from relative to the current history cursor. +1 is forward, -1 is back.

Return value

The url of the folder at that point in the history.

getNavigateHistory()

Returns information about the current navigation history. If caller just wants the count and current pos, they can pass in null for aHistory, which will be more efficent. If they want a list suitable for display, they should pass in an aHistory pointer, and they'll get returned an array with strings containing something like subject and sender of the message - other possible info is the folder containing the message, and the preview text, if available.

 void getNavigateHistory(out unsigned long aCurPos, out unsigned long aCount, [array, size_is(aCount)] out string aHistory);

Return value

aCurPos

The current position in the history.

aCount

The number of items in the history.

aHistory

An array of strings containing information about each entry in the history.