nsIMsgMessageService

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.