Objects that implements nsIMsgMessageService give the user top level routines related to messages like copying, displaying, attachment's manipulation, printing, streaming the message content to eml format string, etc.

Inherits from: nsISupports

Method overview

void CopyMessage(in string aSrcURI, in nsIStreamListener aCopyListener, in boolean aMoveMessage, in nsIUrlListener aUrlListener, in nsIMsgWindow aMsgWindow, out nsIURI aURL);
[noscript] void CopyMessages(in nsMsgKeyArrayPtr keys, in nsIMsgFolder srcFolder, in nsIStreamListener aCopyListener, in boolean aMoveMessage, in nsIUrlListener aUrlListener, in nsIMsgWindow aMsgWindow, out nsIURI aURL);
void DisplayMessage(in string aMessageURI, in nsISupports aDisplayConsumer, in nsIMsgWindow aMsgWindow, in nsIUrlListener aUrlListener, in string aCharsetOverride, out nsIURI aURL);
void openAttachment(in string aContentType, in string aFileName, in string aUrl, in string aMessageUri, in nsISupports aDisplayConsumer, in nsIMsgWindow aMsgWindow, in nsIUrlListener aUrlListener);
void SaveMessageToDisk(in string aMessageURI, in nsIFileSpec aFile, in boolean aGenerateDummyEnvelope, in nsIUrlListener aUrlListener, out nsIURI aURL, in boolean canonicalLineEnding, in nsIMsgWindow aMsgWindow);
void GetUrlForUri(in string aMessageURI, out nsIURI aURL, in nsIMsgWindow aMsgWindow);
void DisplayMessageForPrinting(in string aMessageURI, in nsISupports aDisplayConsumer, in nsIMsgWindow aMsgWindow, in nsIUrlListener aUrlListener, out nsIURI aURL);
void Search(in nsIMsgSearchSession aSearchSession, in nsIMsgWindow aMsgWindow, in nsIMsgFolder aMsgFolder, in string aSearchUri);
nsIURI streamMessage(in string aMessageURI, in nsISupports aConsumer, in nsIMsgWindow aMsgWindow, in nsIUrlListener aUrlListener, in boolean aConvertData, in string aAdditionalHeader);
nsIURI streamHeaders(in string aMessageURI, in nsIStreamListener aConsumer, in nsIUrlListener aUrlListener [optional] in boolean aLocalOnly);
boolean isMsgInMemCache(in nsIURI aURL,  in nsIMsgFolder aFolder, out  nsICacheEntryDescriptor aCacheEntry);
nsIMsgDBHdr messageURIToMsgHdr(in string uri);

Methods

CopyMessage()

Pass in the URI for the message you want to have copied. aCopyListener already knows about the destination folder.

 void CopyMessage(in string aSrcURI,
                  in nsIStreamListener aCopyListener,
                  in boolean aMoveMessage,
                  in nsIUrlListener aUrlListener,
                  in nsIMsgWindow aMsgWindow,
                  out nsIURI aURL);
Parameters
aSrcURI
The string url of the message to copy.
aCopyListener
An nsIStreamListener to be notified of copy events.
aMoveMessage
Set to true if you want the message to be moved. false leaves it as just a copy.
aUrlListener
A nsIUrlListener to be notified of url events.
aMsgWindow
nsIMsgWindow for progress and status feedback
Return values
aURL
The new nsIURI of the message.

CopyMessages()

Copy multiple messages at a time. See CopyMessage

 [noscript] void CopyMessages(in nsMsgKeyArrayPtr keys,
                              in nsIMsgFolder srcFolder,
                              in nsIStreamListener aCopyListener,
                              in boolean aMoveMessage,
                              in nsIUrlListener aUrlListener,
                              in nsIMsgWindow aMsgWindow,
                              out nsIURI aURL);
Parameters
keys
An array of message keys to be copied.
srcFolder
 
aCopyListener
An nsIStreamListener to be notified of copy events.
aMoveMessage
Set to true if you want the message to be moved. false leaves it as just a copy.
aUrlListener
An nsIUrlListener
aMsgWindow
nsIMsgWindow for progress and status feedback
Return values
aURL
The new nsIURI of the message. (?)

DisplayMessage()

When you want a message displayed....

 void DisplayMessage(in string aMessageURI,
                     in nsISupports aDisplayConsumer,
                     in nsIMsgWindow aMsgWindow,
                     in nsIUrlListener aUrlListener,
                     in string aCharsetOverride,
                     out nsIURI aURL);
Parameters
aMessageURI
A uri representing the message to display.
aDisplayConsumer
Is (for now) an nsIDocShell which the message is loaded into.
aMsgWindow
nsIMsgWindow for progress and status feedback
aUrlListener
An nsIUrlListener
aCharsetOverride
(optional) character set over ride to force the message to use.
Return values
aURL
The new nsIURI of the message.

openAttachment()

Downloads and opens an attachment.

 void openAttachment(in string aContentType,
                     in string aFileName,
                     in string aUrl,
                     in string aMessageUri,
                     in nsISupports aDisplayConsumer,
                     in nsIMsgWindow aMsgWindow,
                     in nsIUrlListener aUrlListener);
Parameters
aContentType
The content type of the attachment
aFileName
The name of the attachment.
aUrl
A string representation of the original url associated with the msg.
aMessageUri
RDF resource that describes the message
aDisplayConsumer
 
MsgWindow
nsIMsgWindow for progress and status feedback
aUrlListener
An nsIUrlListener.

SaveMessageToDisk()

When you want to spool a message out to a file on disk. This is an async operation of course.

Note: You must pass in a url listener in order to figure out when the operation is done.

 void SaveMessageToDisk(in string aMessageURI,
                        in nsIFileSpec aFile,
                        in boolean aGenerateDummyEnvelope,
                        in nsIUrlListener aUrlListener,
                        out nsIURI aURL,
                        in boolean canonicalLineEnding,
                        in nsIMsgWindow aMsgWindow);
Parameters
aMessageURI
Url representing the message to spool out to disk.
aFile
The file you want the message saved to.
aGenerateDummyEnvelope
Usually false. Set to true if you want the message appended at the end of the file.
aUrlListener
A nsIUrlListener for being notified when the copy is finished.
canonicalLineEnding
aMsgWindow
nsIMsgWindow for progress and status feedback
Return values
aURL
The new nsIURI of the saved message.

Note: This operation may be obsolete. You always can use streamMessage to get the eml string representation of the message and then write it using File I/O Methods.

GetUrlForUri()

When you have a uri and you would like to convert that to a url which can be run through necko, you can use this method.

Note: The Uri MUST refer to a message and not a folder!

 void GetUrlForUri(in string aMessageURI,
                   out nsIURI aURL,
                   in nsIMsgWindow aMsgWindow);
Parameters
aMessageURI
 
aMsgWindow
nsIMsgWindow for progress and status feedback
Return values
aURL
The nsIURI of the message.

DisplayMessageForPrinting()

When you want a message displayed in a format that is suitable for printing.

 void DisplayMessageForPrinting(in string aMessageURI,
                                in nsISupports aDisplayConsumer,
                                in nsIMsgWindow aMsgWindow,
                                in nsIUrlListener aUrlListener,
                                out nsIURI aURL);
Parameters
aMessageURI
A uri representing the message to display.
aDisplayConsumer
For now, a nsIDocShell which the message is loaded into.
aMsgWindow
nsIMsgWindow for progress and status feedback
aUrlListener
 
Return values
aURL
The new nsIURI of the message.

Search()

 void Search(in nsIMsgSearchSession aSearchSession,
             in nsIMsgWindow aMsgWindow,
             in nsIMsgFolder aMsgFolder,
             in string aSearchUri);
Parameters
aSearchSession
The nsIMsgSearchSession to use.
aMsgWindow
nsIMsgWindow for progress and status feedback
aMsgFolder
nsIMsgFolder
aSearchUri
url of the search.

streamMessage()

This method streams a message to the passed in consumer. It will also tack aAdditionalHeader onto the url (e.g., header=filter). The good thing about this method is that you can extract a standard representation of any message, no matter if they are emails, RSS, news, blogs, etc.

 nsIURI streamMessage(in string aMessageURI,
                      in nsISupports aConsumer,
                      in nsIMsgWindow aMsgWindow,
                      in nsIUrlListener aUrlListener,
                      in boolean aConvertData,
                      in string aAdditionalHeader);
Parameters
aMessageURI
uri of message to stream
aConsumer
Generally, a stream listener listening to the message. The consumer has to be a stream listener and in your listener's onDataAvailable method, you can write out the stream data to a local file or concatenate it to a string.
aMsgWindow
nsIMsgWindow for progress and status feedback.
aUrlListener
An nsIUrlListener that is notified when url starts and stops.
aConvertData
If aConvertData is true, it will create a stream converter from message rfc2822 to */*.
aAdditionalHeader
Header added to the URI. e.g., header=filter
Return

The nsIURI that gets run

Example

For example, the next piece of code shows the selected message code on a dialog: (taken from Mozillazine)

  var content = "";
  var MessageURI = GetFirstSelectedMessage();
  var MsgService = messenger.messageServiceFromURI(MessageURI);
  var MsgStream =  Components.classes["@mozilla.org/network/sync-stream-listener;1"].createInstance();
  var consumer = MsgStream.QueryInterface(Components.interfaces.nsIInputStream);
  var ScriptInput = Components.classes["@mozilla.org/scriptableinputstream;1"].createInstance();
  var ScriptInputStream = ScriptInput.QueryInterface(Components.interfaces.nsIScriptableInputStream);
  ScriptInputStream.init(consumer);
  try {
    MsgService.streamMessage(MessageURI, MsgStream, msgWindow, null, false, null);
  } catch (ex) {
    alert("error: "+ex)
  }
  ScriptInputStream .available();
  while (ScriptInputStream .available()) {
    content = content + ScriptInputStream .read(512);
  }
  alert(content

streamHeaders()

This method streams a message's headers to the passed in consumer. This is for consumers who want a particular header but don't want to stream the whole message.

 nsIURI streamMessage(in string aMessageURI,
                      in nsIStreamListener aConsumer,
                      in nsIUrlListener aUrlListener,
                      in boolean aLocalOnly);
Parameters
aMessageURI
uri of message to stream
aConsumer
nsIStreamListener Generally, a stream listener listening to the message headers. The consumer has to be a stream listener and in your listener's onDataAvailable method, you can write out the stream data to a local file or concatenate it to a string.
aUrlListener
An nsIUrlListener that is notified when url starts and stops, if we run a url.
aLocalOnly
Whether data should be retrieved only from local caches. If streaming over the network is required and this is true, then an exception is thrown. This defaults to false.
Note

If we're offline, then even if aLocalOnly is false, we won't stream over the network

Return

The URL that gets run, if any

isMsgInMemCache()

Determines whether a message is in the memory cache. Local folders don't implement this.

 boolean isMsgInMemCache(in nsIURI aUrl,
                         in nsIMsgFolder aFolder,
                        out nsICacheEntryDescriptor aCacheEntry);
Parameters
aUrl
The URL of the message, possibly with an appropriate command in it
aFolder
The folder this message is in
aCacheEntry
If a cache entry is found, then a pointer to it
Return

TRUE if the message is in mem cache; FALSE if it is not.

messageURIToMsgHdr()

Go from message uri to nsIMsgDBHdr:

 nsIMsgDBHdr messageURIToMsgHdr(in string uri);
Parameters
uri
url of the message
Return

The URL that gets run, if any.