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.

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

Method overview

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.

 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.

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.

 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.