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

void setDisplayCharset(in ACString aCharset);

void setWindow(in nsIDOMWindow ptr, in nsIMsgWindow msgWindow);

void openURL(in ACString aURL);

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

void launchExternalURL(in ACString aURL);

boolean canUndo();

boolean canRedo();

unsigned long getUndoTransactionType();

unsigned long getRedoTransactionType();

void undo(in nsIMsgWindow msgWindow);

void redo(in nsIMsgWindow msgWindow);

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

void setDocumentCharset(in ACString characterSet);

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

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

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

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);

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

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

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);

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

nsIMsgMessageService messageServiceFromURI(in ACString aUri);

nsIMsgDBHdr msgHdrFromURI(in ACString aUri);

ACString getMsgUriAtNavigatePos(in long aPos);

ACString getFolderUriAtNavigatePos(in long aPos);

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

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

Attributes

Attribute	Type	Description
`transactionManager`	`nsITransactionManager`	Readonly: The transaction manager for this `nsIMessenger` instance.
`sendingUnsentMsgs`	boolean	Indicates if sending messages is in progress.
`lastDisplayedMessageUri`	ACString	Readonly: The URL of the last displayed message.
`navigatePos`	long	The current index in the navigation history.

Constants

Name	Value	Description
`eUnknown`	0	Unknown transaction type.
`eDeleteMsg`	1	Delete transaction type.
`eMoveMsg`	2	Move transaction type.
`eCopyMsg`	3	Copy transaction type.

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.