nsIMessenger

by 3 contributors:

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

web.html($0) is defined in wiki.template('tbsource', mediawiki.args([$1])). It is wiki.template(mediawiki.path('InterfaceStatus:Scriptable_' + $4, "en")) and wiki.template(mediawiki.path('InterfaceStatus:' + $2, "en"), mediawiki.args([$3])).

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.

Document Tags and Contributors

Contributors to this page: Sheppy, kscarfone, Wjjohnst
Last updated by: Sheppy,