/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/*
 * 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"

interface nsIMsgProgress;
interface nsIURI;
interface nsIRequest;
interface nsIMsgDBHdr;
interface nsIMsgHdr;
interface nsIFile;
interface nsIOutputStream;
interface nsIMsgComposeSecure;
interface nsIEditor;
interface mozIDOMWindowProxy;

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;
};

/**
 * 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(c552345d-c74b-40b0-a673-79bb461e920b)]
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 nsIFile 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;

  /// X-Mozilla-Cloud-Part, if any.
  attribute ACString cloudPartInfo;

  attribute ACString realName;      // The real name of the file.
};

/**
 * This interface is used by Outlook import to shuttle embedded
 * image information over to nsIMsgSend's createRFC822Message method via
 * the aEmbbeddedObjects parameter.
 */
[scriptable, uuid(5d2c6554-b4c8-4d68-b864-50e0df929707)]
interface nsIMsgEmbeddedImageData : nsISupports
{
  attribute nsIURI uri;
  attribute ACString cid;
  attribute ACString name;
};

[ptr] native nsMsgAttachedFile(nsMsgAttachedFile);

[scriptable, uuid(747fdfa2-1754-4282-ab26-1e55fd8de13c)]
interface nsIMsgSend : nsISupports
{
  /// 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 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
   */
  Promise 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 AString aBody,
                               in mozIDOMWindowProxy aParentWindow,
                               in nsIMsgProgress aProgress,
                               in nsIMsgSendListener aListener,
                               in AString 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 aCreateAsDraft If true, this message will be put in a drafts folder
   * @param aAttachments Array of nsIMsgAttachedFile objects
   * @param aEmbeddedObjects Array of nsIMsgEmbeddedImageData objects for
   *                         MHTML messages.
   * @param aListener listener for msg creation progress and resulting file.
   */
  void createRFC822Message(in nsIMsgIdentity aUserIdentity,
                           in nsIMsgCompFields aFields,
                           in string aBodyType,
                           in ACString aBody,
                           in boolean aCreateAsDraft,
                           in Array<nsIMsgAttachedFile> aAttachments,
                           in Array<nsIMsgEmbeddedImageData> 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          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 aPassword        Pass this in to prevent a dialog if the password
   *                         is needed for secure transmission.
   */
  Promise sendMessageFile(in nsIMsgIdentity       aUserIdentity,
                          in string               aAccountKey,
                          in nsIMsgCompFields     aFields,
                          in nsIFile              aSendIFile,
                          in boolean              aDeleteSendFileOnCompletion,
                          in boolean              aDigest,
                          in nsMsgDeliverMode     aMode,
                          in nsIMsgDBHdr          aMsgToReplace,
                          in nsIMsgSendListener   aListener,
                          in wstring              aPassword
                          );

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

    /**
     * Report a send failure.
     *
     * @param aFailureCode - The failure code of the send operation.
     *   NS_OK is a possible value as well; if passed, the function won't prompt
     *   the user but will still about the session.
     * @param aErrorMsg - The appropriate error string for the failure.
     * @result A modified result value in the case a user action results in
     *   a different way to handle the failure.
     */
    nsresult fail(in nsresult aFailureCode, in wstring aErrorMsg);

    /* retrieve 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 notifyListenerOnTransportSecurityError(in string msgID, in nsresult status, in nsITransportSecurityInfo secInfo, in ACString location);

    void sendDeliveryCallback(in nsIURI aServerURI,
                              in nsresult aExitCode,
                              [optional] in nsITransportSecurityInfo secInfo,
                              [optional] in string errMsg,
                              [optional] in boolean inIsNewsDelivery);

    /* methods for copy listener ... */
    void notifyListenerOnStartCopy();
    void notifyListenerOnProgressCopy(in unsigned long aProgress, in unsigned long aProgressMax);
    void notifyListenerOnStopCopy(in nsresult aStatus);
    /// When saving as draft, the folder uri we saved to.
    readonly attribute AUTF8String folderUri;
    /// The unique Message-ID assigned to each composed message.
    readonly attribute AUTF8String messageId;

    attribute nsMsgKey messageKey;

    nsIMsgProgress getProgress();
};