thunderbird-dev 11.0.1+build1-0ubuntu2 / usr / share / idl / thunderbird-11.0.1 / nsIMsgSend.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

/*
 * The nsIMsgSend 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). 
 */
#include "nsISupports.idl"
#include "nsrootidl.idl"
#include "nsIMsgIdentity.idl"
#include "nsIMsgCompFields.idl"
#include "nsIMsgSendListener.idl"
#include "nsIMsgSendReport.idl"
#include "domstubs.idl"
#include "nsIPrompt.idl"
#include "MailNewsTypes2.idl"
#include "nsIMsgComposeParams.idl"

%{C++
#include "nsIURL.h"
#include "nsStringGlue.h"
%}

interface nsIMsgProgress;
interface nsIURI;
interface nsIRequest;
interface nsIMsgDBHdr;
interface nsIMsgHdr;
interface nsIDocShell;
interface nsIFile;
interface nsILocalFile;
interface nsIOutputStream;
interface nsIMsgComposeSecure;
interface nsIMsgStatusFeedback;
interface nsIEditor;
interface nsIArray;
interface nsISupportsArray;

typedef long nsMsgDeliverMode;

[scriptable, uuid(c658cd1f-dc4a-43c0-911c-c6d3e569ca7e)]
interface nsIMsgAttachmentData : nsISupports
{
  /// The URL to attach.
  attribute nsIURI url;

  /**
   * The type to which this document should be
   * converted.  Legal values are NULL, TEXT_PLAIN
   * and APPLICATION_POSTSCRIPT (which are macros
   * defined in net.h); other values are ignored.
   */
  attribute ACString desiredType;

  /**
   * The type of the URL if known, otherwise empty. For example, if
   * you were attaching a temp file which was known to contain HTML data,
   * you would pass in TEXT_HTML as the realType, to override whatever type
   * the name of the tmp file might otherwise indicate.
   */
  attribute ACString realType;

  /// Goes along with real_type.
  attribute ACString realEncoding; 

  /**
   * The original name of this document, which will eventually show up in the
   * Content-Disposition header. For example, if you had copied a document to a
   * tmp file, this would be the original, human-readable name of the document.
   */
  attribute ACString realName;
  /**
   * If you put a string here, it will show up as the Content-Description
   * header. This can be any explanatory text; it's not a file name.
   */
  attribute ACString description;

  /// mac-specific info
  attribute ACString xMacType;

  /// mac-specific info
  attribute ACString xMacCreator;
};

/**
 * When we have downloaded a URL to a tmp file for attaching, this
 * represents everything we learned about it (and did to it) in the
 * process.
 */
[scriptable, uuid(156bad99-c5a1-425d-8319-3e79c02571d4)]
interface nsIMsgAttachedFile : nsISupports
{
  /// Where it came from on the network (or even elsewhere on the local disk.)
  attribute nsIURI origUrl;

  /// The tmp file in which the (possibly converted) data now resides.
  attribute nsILocalFile tmpFile;

  /// The type of the data in file_name (not necessarily the same as the type of orig_url.)
  attribute ACString type;

  /**
   * The encoding of the tmp file. This will be set only if the original
   * document had an encoding already; we don't do base64 encoding and so forth
   * until it's time to assemble a full MIME message of all parts.
   */
  attribute ACString encoding;
  /// For Content-Description header.
  attribute ACString description;

  attribute ACString xMacType;    // mac-specific info 
  attribute ACString xMacCreator; // mac-specific info 
  attribute ACString realName;      // The real name of the file. 

  /**
   * Some statistics about the data that was written to the file, so that when
   * it comes time to compose a MIME message, we can make an informed decision
   * about what Content-Transfer-Encoding would be best for this attachment.
   * (If it's encoded already, we ignore this information and ship it as-is.)
   */
  attribute unsigned long size;
  attribute unsigned long unprintableCount;
  attribute unsigned long highbitCount;
  attribute unsigned long ctlCount;
  attribute unsigned long nullCount;
  attribute unsigned long maxLineLength;
};

%{ C++
// Forward declaration
class nsMsgAttachmentHandler;

// Attachment file/URL structures - we're letting libmime use this directly
class nsMsgAttachmentData : public nsIMsgAttachmentData
{
public:
  NS_DECL_NSIMSGATTACHMENTDATA
  NS_DECL_ISUPPORTS

  nsMsgAttachmentData();
  ~nsMsgAttachmentData();

  nsCOMPtr<nsIURI> m_url;   // The URL to attach.

  nsCString m_desiredType;  // The type to which this document should be
                            // converted.  Legal values are NULL, TEXT_PLAIN
                            // and APPLICATION_POSTSCRIPT (which are macros
                            // defined in net.h); other values are ignored.

  nsCString m_realType;     // The type of the URL if known, otherwise NULL. For example, if 
                            // you were attaching a temp file which was known to contain HTML data, 
                            // you would pass in TEXT_HTML as the real_type, to override whatever type 
                            // the name of the tmp file might otherwise indicate.

  nsCString m_realEncoding; // Goes along with real_type

  nsCString m_realName;     // The original name of this document, which will eventually show up in the 
                            // Content-Disposition header. For example, if you had copied a document to a 
                            // tmp file, this would be the original, human-readable name of the document.

  nsCString m_description;  // If you put a string here, it will show up as the Content-Description header.  
                            // This can be any explanatory text; it's not a file name.             

  nsCString m_disposition;  // The Content-Disposition header (if any). a
                            // nsMsgAttachmentData can very well have
                            // Content-Disposition: inline value, instead of
                            // "attachment".

  // Mac-specific data that should show up as optional parameters
  // to the content-type header.
  nsCString m_xMacType;
  nsCString m_xMacCreator;

  PRInt32 m_size;                  // The size of the attachment. May be 0.
  bool    m_isExternalAttachment;  // Flag for determining if the attachment is external
  bool    m_isDownloaded;          // Flag for determining if the attachment has already been downloaded
  bool    m_hasFilename;           // Tells whether the name is provided by us or if it's a Part 1.2-like attachment
};

class nsMsgAttachedFile : public nsIMsgAttachedFile
{
public:
  NS_DECL_NSIMSGATTACHEDFILE
  NS_DECL_ISUPPORTS

  nsMsgAttachedFile();
  ~nsMsgAttachedFile();

  nsCOMPtr<nsIURI> m_origUrl; // Where it came from on the network (or even elsewhere on the local disk.)

  nsCOMPtr<nsILocalFile>  m_tmpFile;    // The tmp file in which the (possibly converted) data now resides.

  nsCString m_type;        // The type of the data in file_name (not necessarily the same as the type of orig_url.)

  nsCString m_encoding;    // Likewise, the encoding of the tmp file. This will be set only if the original 
                            // document had an encoding already; we don't do base64 encoding and so forth until 
                            // it's time to assemble a full MIME message of all parts.


  nsCString m_description;    // For Content-Description header 
  nsCString m_xMacType;    // mac-specific info 
  nsCString m_xMacCreator; // mac-specific info 
  nsCString m_realName;      // The real name of the file. 

  // Some statistics about the data that was written to the file, so that when
  // it comes time to compose a MIME message, we can make an informed decision
  // about what Content-Transfer-Encoding would be best for this attachment.
  // (If it's encoded already, we ignore this information and ship it as-is.)
  PRUint32    m_size;
  PRUint32    m_unprintableCount;
  PRUint32    m_highbitCount;
  PRUint32    m_ctlCount;
  PRUint32    m_nullCount;
  PRUint32    m_maxLineLength;
};

%}

[ptr] native nsMsgAttachmentHandler(nsMsgAttachmentHandler);
[ptr] native nsMsgAttachedFile(nsMsgAttachedFile);

[scriptable, uuid(22cfe1cb-4e9a-451f-82e5-0b75d2b65a95)]
interface nsIMsgSend : nsISupports
{
  //
  // This is the primary interface for creating and sending RFC822 messages
  // in the new architecture. Currently, this method supports many arguments
  // that change the behavior of the operation. This will change in time to 
  // be separate calls that will be more singluar in nature.
  //
  // NOTE: when aEditor is non-null, a multipart related MHTML message will 
  // be created
  //

  /// Send the message straight away.
  const nsMsgDeliverMode nsMsgDeliverNow = 0;
  /**
   * Queue the message for sending later, but then wait for the user to
   * request to send it.
   */
  const nsMsgDeliverMode nsMsgQueueForLater = 1;
  const nsMsgDeliverMode nsMsgSave = 2;
  const nsMsgDeliverMode nsMsgSaveAs = 3;
  const nsMsgDeliverMode nsMsgSaveAsDraft = 4;
  const nsMsgDeliverMode nsMsgSaveAsTemplate = 5;
  const nsMsgDeliverMode nsMsgSendUnsent = 6;

  /// Queue the message in the unsent folder and send it in the background.
  const nsMsgDeliverMode nsMsgDeliverBackground = 8;

  /**
   * Create an rfc822 message and send it.
   * @param aEditor nsIEditor instance that contains message. May be a dummy,
   *                especially in the case of import.
   * @param aUserIdentity identity to send from.
   * @param aAccountKey account we're sending message from. May be null.
   * @param aFields composition fields from addressing widget
   * @param aIsDigest is this a digest message?
   * @param aDontDeliver Set to false by the import code - used when we're
   *                     trying to create a message from parts.
   * @param aMode delivery mode
   * @param aMsgToReplace e.g., when saving a draft over an old draft. May be 0
   * @param aBodyType content type of message body
   * @param aBody message body text (should have native line endings)
   * @param aBodyLength passed in to avoid extra strlen call.
   * @param aAttachments Array of nsIMsgAttachmentData
   * @param aPreloadedAttachments Array of nsIMsgAttachedFile
   * @param aParentWindow compose window; may be null.
   * @param aProgress where to send progress info; may be null.
   * @param aListener optional listener for send progress
   * @param aPassword optional smtp server password
   * @param aOriginalMsgURI may be null.
   * @param aType see nsIMsgComposeParams.idl
   */
    void createAndSendMessage(in nsIEditor aEditor,
                              in nsIMsgIdentity aUserIdentity,
                              in string aAccountKey,
                              in nsIMsgCompFields aFields,
                              in boolean aIsDigest,
                              in boolean aDontDeliver,
                              in nsMsgDeliverMode aMode,
                              in nsIMsgDBHdr aMsgToReplace,
                              in string aBodyType,
                              in string aBody,
                              in unsigned long aBodyLength,
                              in nsIArray aAttachments,
                              in nsIArray aPreloadedAttachments,
                              in nsIDOMWindow aParentWindow,
                              in nsIMsgProgress aProgress,
                              in nsIMsgSendListener aListener,
                              in string aPassword,
                              in AUTF8String aOriginalMsgURI,
                              in MSG_ComposeType aType);

  /**
   * Creates a file containing an rfc822 message, using the passed information.
   * aListener's OnStopSending method will get called with the file the message
   * was stored in. OnStopSending may be called sync or async, depending on
   * content, so you need to handle both cases.
   *
   * @param aUserIdentity    The user identity to use for sending this email.
   * @param aFields          An nsIMsgCompFields object containing information
   *                         on who to send the message to.
   * @param aBodyType content type of message body
   * @param aBody message body text (should have native line endings)
   * @param aBodyLength passed in to avoid extra strlen call.
   * @param aCreateAsDraft If true, this message will be put in a drafts folder
   * @param aAttachments Array of nsIMsgAttachmentData
   * @param aEmbeddedObjects Array of nsIDomNode objects for MHTML messages.
   *                         Primarily used for embedded images.
   *                         Almost all methods can be noops, but
   *                         GetNodeValue should return the
   *                         cid of the embedded object.
   * @param aListener listener for msg creation progress and resulting file.
   */
  void createRFC822Message(in nsIMsgIdentity aUserIdentity,
                           in nsIMsgCompFields aFields,
                           in string aBodyType,
                           in string aBody,
                           in unsigned long aBodyLength,
                           in boolean aCreateAsDraft,
                           in nsIArray aAttachments,
                           in nsISupportsArray aEmbeddedObjects,
                           in nsIMsgSendListener aListener);

  /**
   * Sends a file to the specified composition fields, via the user identity
   * provided.
   *
   * @param aUserIdentity    The user identity to use for sending this email.
   * @param aAccountKey      The key of the account that this message relates
   *                         to.
   * @param aFields          An nsIMsgCompFields object containing information
   *                         on who to send the message to.
   * @param aSendIFile       A reference to the file to send.
   * @param aDeleteSendFileOnCompletion
   *                         Set to true if you want the send file deleted once
   *                         the message has been sent.
   * @param aDigest_p        If this is a multipart message, this param
   *                         specifies whether the message is in digest or mixed
   *                         format.
   * @param aMode            The delivery mode for sending the message (see
   *                         above for values).
   * @param aMsgToReplace    A message header representing a message to be
   *                         replaced by the one sent, this param may be null.
   * @param aListener        An nsIMsgSendListener to receive feedback on the
   *                         current send status. This parameter can also
   *                         support the nsIMsgCopyServiceListener interface to
   *                         receive notifications of copy finishing e.g. after
   *                         saving a message to the sent mail folder.
   *                         This param may be null.
   * @param aStatusFeedback  A feedback listener for slightly different feedback
   *                         on the message send status. This param may be null.
   * @param aPassword        Pass this in to prevent a dialog if the password
   *                         is needed for secure transmission.
   */
  void sendMessageFile(in nsIMsgIdentity       aUserIdentity,
                       in string               aAccountKey,
                       in nsIMsgCompFields     aFields,
                       in nsIFile              aSendIFile,
                       in boolean              aDeleteSendFileOnCompletion,
                       in boolean              aDigest_p,
                       in nsMsgDeliverMode     aMode,
                       in nsIMsgDBHdr          aMsgToReplace,
                       in nsIMsgSendListener   aListener,
                       in nsIMsgStatusFeedback aStatusFeedback,
                       in string               aPassword
                       ); 

    /* Abort current send/save operation */
    void abort();

    /* Report a send failure */
    nsresult fail(in nsresult failure_code, in wstring error_msg);

    /* Disable UI notification (alert message) */
    void setGUINotificationState(in boolean aEnableFlag);

    /* Crypto */
    void BeginCryptoEncapsulation();

    /* retreive the last send process report*/
    readonly attribute nsIMsgSendReport sendReport; 

    /* methods for send listener ... */
    void notifyListenerOnStartSending(in string aMsgID, in unsigned long aMsgSize);
    void notifyListenerOnProgress(in string aMsgID, in unsigned long aProgress, in unsigned long aProgressMax);
    void notifyListenerOnStatus(in string aMsgID, in wstring aMsg);
    void notifyListenerOnStopSending(in string aMsgID, in nsresult aStatus, in wstring aMsg, in nsIFile returnFile);
    void deliverAsMailExit(in nsIURI aUrl, in nsresult aExitCode);
    void deliverAsNewsExit(in nsIURI aUrl, in nsresult aExitCode);
    
    void sendDeliveryCallback(in nsIURI aUrl, in boolean inIsNewsDelivery, in nsresult aExitCode);

    /* methods for copy listener ... */
    void notifyListenerOnStartCopy(); 
    void notifyListenerOnProgressCopy(in unsigned long aProgress, in unsigned long aProgressMax);
    void notifyListenerOnStopCopy(in nsresult aStatus);
    void getMessageId(out ACString messageID);
    /// When saving as draft, the folder uri we saved to.
    readonly attribute ACString folderUri;

    /**
     * After a draft is saved, use this to get the mime part number for the dom
     * node in the editor embedded object list with the passed in index.
     *
     * @param aDomIndex - index in the editor dom embedded object list of
     * the part we're interested in. These are generally images.
     *
     * @return the mime part number for that object.
     */
    ACString getPartForDomIndex(in long aDomIndex);

    attribute nsMsgKey messageKey;

    nsIPrompt getDefaultPrompt();

    /* process attachment */
    void gatherMimeAttachments();
    readonly attribute boolean processAttachmentsSynchronously;
    [noscript] nsMsgAttachmentHandler getAttachmentHandlers();
    readonly attribute unsigned long attachmentCount;
    attribute unsigned long pendingAttachmentCount;
    readonly attribute nsMsgDeliverMode deliveryMode;

    nsIMsgProgress getProgress();

    nsIOutputStream getOutputStream();

    attribute nsIRequest runningRequest;

    attribute nsresult status;

    attribute nsIMsgComposeSecure cryptoclosure;
};