Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.
Your Search Results

    Mail composition back end

    Warning: The content of this article may be out of date. It was imported from mozilla.org and last updated in 2000.



    This page has been flagged by editors or users as needing technical review. Until it is fully reviewed, it may contain inaccurate or incorrect information.

    by Richard H. Pizzarro <[email protected]> Contents

    Overview

    I've done considerable work in the past few weeks reorganizing the Mail Composition back end, so I thought it would be helpful to put together a small doc on the new interfaces and how one can use them. The Mail Composition back end is responsible for the assembly and creation of RFC822 messages to be delivered either via SMTP or NNTP services. You also have the ability to save RFC822 files to disk, should you need this data for some reason. Included in this functionality is the code to copy the messages to the appropriate locations after delivery (i.e. a "Sent" folder) as well as the ability to store messages for features like "Drafts" and "Templates". Several (but not all) of these interfaces are specified in IDL. This will change in the coming weeks and allow for developers to write JavaScript to take advantage of the back end services. Also, I will talk about some features though they may not be complete as of yet. I will try to make comments for these exceptions.
     
     

    Sending Messages
    The primary responsibility of the back end is for the creation and sending of RFC822 messages. The interface that accomplishes this task is the nsIMsgSend interface. The feedback mechanism is provided by a nsIMsgSendListener which is implemented by the caller. The caller has the ability to add or remove listener interfaces to the nsIMsgSend object and the interface can support multiple listeners. (For detailed information on the listener interfaces, see the Listener Interfaces section of this document)
     
     
    nsIMsgSend
    The following describes the methods of the nsIMsgSend interface. All of these methods are asynchronous operations.
     
     
    CreateAndSendMessage

    The CreateAndSendMessage method will create an RFC822 message and send it all in one operation as well as providing the ability to save disk files for later use. The mode of delivery can also be specified for the "Send Later", "Drafts" and "Templates" operations. (NOTE: This method could easily be broken in to a few different calls. Currently, this method does several functions depending on the arguments passed in, but this could easily lead to confusion. This is something that very well may change as time allows).

      NS_IMETHOD CreateAndSendMessage(
                      nsIEditorShell                    *aEditor,
    - the editor object for the mail compose operation. If this is not null, the body will be extracted from this object and any embedded objects or links will be sent as part of the message in MHTML
                      nsIMsgIdentity                    *aUserIdentity,
    - the user identity for the person doing the send operation. This will be needed to determine the appropriate folder for copy operations.
                      nsIMsgCompFields                  *fields,
    - the message composition fields. This will contain all of the relevant header information for message creation
                      PRBool                            digest_p,
    - this is a flag that says that most of the documents we are attaching are themselves messages, and so we should generate a multipart/digest container instead of multipart/mixed.  (It's a minor difference.)
                      PRBool                            dont_deliver_p,
    - If "dont_deliver_p" is false, then we actually deliver the message to the SMTP and/or NNTP server
                      nsMsgDeliverMode                  mode,
    - mode is the delivery mode. This can be set for the various modes of delivery. These can include nsMsgDeliverNow, nsMsgQueueForLater, nsMsgSave, nsMsgSaveAs, nsMsgSaveAsDraft, nsMsgSaveAsTemplate.
                               nsIMessage                        *msgToReplace,
    - if the delivery mode is set to nsMsgSaveAsDraft, this is a pointer to the the nsIMessage object for the message that needs to be replaced
                      const char                        *attachment1_type,
                      const char                        *attachment1_body,
                      PRUint32                          attachment1_body_length,
    - the full text of the first attachment is provided via `attachment1_type' `attachment1_body' and `attachment1_body_length'.  These may all be 0 if all attachments are provided externally.
                      const struct nsMsgAttachmentData  *attachments,
    - Subsequent attachments are provided as URLs to load, described in the nsMsgAttachmentData structures.
                      const struct nsMsgAttachedFile    *preloaded_attachments,
    - attachments that are already locally stored on disk (note: both attachments and preloaded_attachments cannot be specified on a single call
                      void                              *relatedPart /* nsMsgSendPart  */,
    - a related part for multipart related operations
                      nsIMsgSendListener                **aListenerArray) = 0;
    - an array of listeners for the send operation. this can be nsnull if you want to do the delivery operation "blind"
     
     

    SendMessageFile
    The SendMessageFile method will let the caller send a message that has been created by another process (Note: CreateAndSendMessage can accomplish this task).

      NS_IMETHOD  SendMessageFile(
                              nsIMsgIdentity                    *aUserIdentity,
    - the user identity for the person doing the send operation. This will be needed to determine the appropriate folder for copy operations.
                              nsIMsgCompFields                  *fields,
    - the message composition fields. This will contain all of the relevant header information for message delivery
                              nsFileSpec                        *sendFileSpec,
    - the file spec for the message being sent
                              PRBool                            deleteSendFileOnCompletion,
    - tell the back end if it should delete the file upon successful completion
                              PRBool                            digest_p,
    - this is a flag that says that most of the documents we are attaching are themselves messages, and so we should generate a multipart/digest container instead of multipart/mixed.  (It's a minor difference.)
                              nsMsgDeliverMode                  mode,
    - mode is the delivery mode. This can be set for the various modes of delivery. These can include nsMsgDeliverNow, nsMsgQueueForLater, nsMsgSave, nsMsgSaveAs, nsMsgSaveAsDraft, nsMsgSaveAsTemplate.
                                            nsIMessage                        *msgToReplace,
    - if the delivery mode is set to nsMsgSaveAsDraft, this is a pointer to the the nsIMessage object for the message that needs to be replaced
                              nsIMsgSendListener                **aListenerArray) = 0;
    - an array of listeners for the send operation. this can be nsnull if you want to do the delivery operation "blind"
     

    SendWebPage
    The SendWebPage method is a convenience function that will let the caller send a web page by specifying a URI. NOTE: This can be any valid URI so one can send local disk files by specifying a file:// URI.

      NS_IMETHOD  SendWebPage(
                              nsIMsgIdentity                    *aUserIdentity,
    - the user identity for the person doing the send operation. This will be needed to determine the appropriate folder for copy operations.
                              nsIMsgCompFields                  *fields,
    - the message composition fields. This will contain all of the relevant header information for message delivery
                              nsIURI                            *url,
    - the URI of the message composition fields. This will contain all of the relevant header information for message delivery
                              nsMsgDeliverMode                  mode,
    - mode is the delivery mode. This can be set for the various modes of delivery (i.e. send later, drafts, templates or send the message now)
                              nsIMsgSendListener                **aListenerArray) = 0;
    - an array of listeners for the send operation. this can be nsnull if you want to do the delivery operation "blind"

    The AddListener/RemoveListener methods let the caller add and remove listeners to the sending interface.

      NS_IMETHOD  AddListener(nsIMsgSendListener *aListener) = 0;
      NS_IMETHOD  RemoveListener(nsIMsgSendListener *aListener) = 0;
     
     

    Sending Listener Interfaces
    The nsIMsgSendListener interface will let a caller keep track of the progress and any status of a send operation. These are critical for message delivery since message sending is asynchronous. It is the only way to determine if the operation was successful or not. An important item to note is the fact that this interface should also implement the nsIMsgCopyServiceListener interface if it wants to be notified of the progress and completion of the copy operation.
     
    nsIMsgSendListener
    The following describes the methods of the nsIMsgSendListener interface:
     
    OnStartSending
    The OnStartSending interface is called when the sending operation has begun. This is called after messages creation has completed. If message creation fails, the nsIMsgSend operation will return an NS_FAILED() return code.

     NS_IMETHOD OnStartSending(const char *aMsgID,
    - the message ID for the message being sent
                                PRUint32 aMsgSize) = 0;
    - the total message size for the message being sent
     

    OnProgress
    The OnProgress interface is called with progress notification on the send operation.

     NS_IMETHOD OnProgress(const char *aMsgID,
    - the message ID for the message being sent
                            PRUint32 aProgress,
    - the progress so far
                            PRUint32 aProgressMax) = 0;
    - the maximum progress (aProgress should be used as a numerator and aProgressMax as a denominator for a message sent percentage)
     

    OnStatus
    The OnStatus gives the listener status updates for the current operation.

      NS_IMETHOD OnStatus(const char *aMsgID,
    - the message ID for the message being sent
                          const PRUnichar *aMsg) = 0;
    - a message concerning the status of the send operation
     

    OnStopSending
    The OnStopSending interface is called when the sending operation has completed. This will be called in the case of both success and failure.

      NS_IMETHOD OnStopSending(const char *aMsgID,
    - the message ID for the message being sent
                               nsresult aStatus,
    - the resulting status for the send operation
                               const PRUnichar *aMsg,
    - a message concerning the status of the send operation
                               nsIFileSpec *returnFileSpec) = 0;
    - an nsIFileSpec which will specify the file that was created (this is used if the dont_deliver_p argument is set to PR_TRUE)
     
     

    nsIMsgCopyServiceListener
    The nsIMsgCopyServiceListener interface will notify the implementor or the progress and completion of the copy operation that follows successful send operations.
     
    OnStartCopy
    The OnStartCopy interface is called when the copy operation has begun.

     NS_IMETHOD OnStartCopy(
                            nsISupports *listenerData) = 0;
    - the nsISupports pointer passed in to the original copy operation
     

    OnProgress
    The OnProgress interface is called with progress notification for the copy operation.

     NS_IMETHOD OnProgress(
                            PRUint32 aProgress,
    - the progress so far
                            PRUint32 aProgressMax) = 0;
    - the maximum progress (aProgress should be used as a numerator and aProgressMax as a denominator for a message sent percentage)
                            nsISupports *listenerData) = 0;
    - the nsISupports pointer passed in to the original copy operation
     

    OnStopCopy
    The OnStopCopy interface is called when the copy operation has completed. This will be called in the case of both success and failure.

      NS_IMETHOD OnStopCopy(
                            nsresult aStatus,
    - the resulting status for the send operation
                            nsISupports *listenerData) = 0;
    - the nsISupports pointer passed in to the original copy operation
     
     

    Copy Operations
    There are various copy operations that can result as a part of message creation and delivery. These are all controlled by the caller in various way. The following details the specific copy operations that can occur in a message send call.
     
    Copy to Sent Folder
    Copying to the "Sent" folder is controlled by a setting in the nsIMsgCompFields interface. The SetFcc() and GetFcc() methods are used by the caller to control if a message should be copied to the defined "Sent" folder if the sending operation was successful. Currently, this pref is a "char *" which is the specific name of the folder, but this will more than likely change to a PRBool (boolean) preference. The determiniation of which folder is the "Sent" folder for the user is done by a call to GetFoldersWithFlag() and the message store will control this user defined preference. If the setting for GetFcc() is set to true, the copy operation is automatically performed after a successful send operation.
     
    Drafts
    Saving a message as a draft is controlled by the "nsMsgDeliverMode  mode" argument of the CreateAndSendMessage and SendMessageFile methods. If the caller passes in nsMsgSaveAsDraft, the file created or passed in will be stored as a draft in the user specified "Drafts" folder.
     
     
    Templates
    Like Drafts, saving a message as a template is controlled by the "nsMsgDeliverMode  mode" argument of the CreateAndSendMessage and SendMessageFile methods. If the caller passes in nsMsgSaveAsTemplate, the file created or passed in will be stored as a draft in the user specified "Templates" folder.
     
    Send Later
    Developers also have the ability to do "Send Later" operations. This will store messages in the user defined "Unsent Messages or Drafts" folder. This simply does a save operation similar to Drafts and Templates. Send Later operations are controlled by the "nsMsgDeliverMode  mode" argument of the CreateAndSendMessage and SendMessageFile methods. If the caller passes in nsMsgQueueForLater.
     
    Sending Unsent Messages
    The back end has the ability to send all messages that are currently stored in the user defined "Unsent Messages or Drafts" folder. (See Send Later above) The nsIMsgSendLater is the interface that allows the caller to send all of the files previously stored. The caller will implement an nsIMsgSendLaterListener interface to monitor the progress of the send operations.

    The following describes the methods of the nsIMsgSendLater interface. This method is performs the send operations asynchronously.

    The SendUnsentMessages method will send all queued messages.

      NS_IMETHOD  SendUnsentMessages(nsIMsgIdentity           *identity,
    - the user identity for the person doing the send operation. This will be needed to determine the appropriate folder for copy operations.
                                     nsIMsgSendLaterListener  **listenerArray) = 0;
    - an array of listeners for the send operation. this can be nsnull if you want to do the delivery operations "blind"

    The AddListener & RemoveListener methods will add and remove listeners from the nsIMsgSendLater object.

      NS_IMETHOD  AddListener(nsIMsgSendLaterListener *aListener) = 0;
      NS_IMETHOD  RemoveListener(nsIMsgSendLaterListener *aListener) = 0;
     
     

    Sending Unsent Messages Listener
    The nsIMsgSendLaterListener interface will notify the implementor of the progress and completion of the send later operations.
     
    CreateAndSendMessage

    The OnStartSending interface is called when the send later operation has begun.

      NS_IMETHOD OnStartSending(
                                PRUint32 aTotalMessageCount) = 0;
    - the total messages to be sent
     

    CreateAndSendMessage

    The OnProgress interface is called with progress notification of the send later operation.

      NS_IMETHOD OnProgress(
                            PRUint32 aCurrentMessage,
    - the current message being sent
                            PRUint32 aTotalMessage) = 0;
    - the total messages to be sent
     

    CreateAndSendMessage

    The OnStatus gives the listener status updates for the current operation.

      NS_IMETHOD OnStatus(
                          const PRUnichar *aMsg) = 0;
    - the progress so far
     

    CreateAndSendMessage

    The OnStopSending interface is called when the send later operation has completed.

      NS_IMETHOD OnStopSending(
                               nsresult aStatus,
    - the resulting status for the send operation
                               const PRUnichar *aMsg,
    - a status message
                               PRUint32 aTotalTried,
    - the total messages that were attempted
                               PRUint32 aSuccessful) = 0;
    - the number of successful messages
     
     

    Quoting
    Quoting a mail message is made possible via the nsIMsgQuote interface. It is a simple interface that takes a consumer output stream for the quoted data. The message will be output in HTML form and it is up to the caller to handle plain text conversion.
     
    CreateAndSendMessage

    The QuoteMessage method is the primary interface for message quoting.

      NS_IMETHOD QuoteMessage(
                              const PRUnichar *msgURI,
    - the URI of the message to be quoted
                              nsIOutputStream *outStream) = 0;
    - the consumer output stream for the quoted data
     
     

    Sample Programs
    The mozilla/mailnews/compose/tests/ directory contains sample test programs for all of the above described interfaces. Use at your own risk and beware of bitrot!
    • compose - this program shows the use of the CreateAndSendMessage interface (CreateAndSendMessage)
    • compose2 - this program shows the use of the CreateAndSendMessage interface (SendMessageFile)
    • sendlater - this program shows the use of the nsIMsgSendLater interface
    • sendpage  - this program shows the use of the CreateAndSendMessage interface (SendWebPage)
    Last modified: Wed Nov 1, 2000 [email protected]

    Document Tags and Contributors

     Contributors to this page: chrisdavidmills, jenzed
     Last updated by: chrisdavidmills,