mailnews/compose/public/nsIMsgSend.idl
author Karsten Düsterloh <mnyromyr@tprac.de>
Fri, 19 Jun 2009 23:35:33 +0200
changeset 2895 6f5baa0cddd240bb7c0ecc6e9f57e78adc94b90a
parent 2310 fd3d5ede674b5c3af87fd27793f67e3511ae45f9
child 6178 00b28751b20de0ae231fc47b6557e55e8280ab0c
permissions -rw-r--r--
Merge for rev. 2894

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

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

typedef long nsMsgDeliverMode;

%{ C++
//
// Callback declarations for message delivery
//
// For completion of send/message creation operations...
typedef nsresult (*nsMsgSendCompletionCallback) (nsresult aExitCode, void *tagData, nsILocalFile *returnFile);

// For completion of sending unsent messages operations...
typedef nsresult (*nsMsgSendUnsentMessagesCallback) (nsresult aExitCode, PRUint32 totalSentCount,
                                                     PRUint32 totalSentSuccessfully, void *tagData);
%}

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

// Attachment file/URL structures
struct nsMsgAttachmentData
{
  nsIURI* url;            // The URL to attach. This should be 0 to signify "end of list".

  char *desired_type;      // 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.

  char *real_type;        // 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.

  char *real_encoding;    // Goes along with real_type 

  char *real_name;        // 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.

  char *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.             

  char *x_mac_type, *x_mac_creator; // Mac-specific data that should show up as optional parameters
                                    // to the content-type header.
  PRBool  isExternalAttachment;  // Flag for determining if the attachment is external
};


//
// 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. 
//
typedef struct nsMsgAttachedFile
{
  nsCOMPtr<nsIURI> orig_url;  // Where it came from on the network (or even elsewhere on the local disk.)

  nsCOMPtr <nsILocalFile>  tmp_file;    // The tmp file in which the (possibly converted) data now resides.
  
  char        *type;        // The type of the data in file_name (not necessarily the same as the type of orig_url.)

  char        *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.


  char        *description;    // For Content-Description header 
  char        *x_mac_type;    // mac-specific info 
  char        *x_mac_creator; // mac-specific info 
  char        *real_name;      // 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    size;
  PRUint32    unprintable_count;
  PRUint32    highbit_count;
  PRUint32    ctl_count;
  PRUint32    null_count;
  PRUint32    max_line_length;
  
} nsMsgAttachedFile;
%}


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

[scriptable, uuid(1313d4e4-3ac4-4fe7-bae5-e7049018c331)]
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;

    [noscript]
    void createAndSendMessage(in nsIEditor                    aEditor,
                              in nsIMsgIdentity               aUserIdentity,
                              in string                       aAccountKey,
                              in nsIMsgCompFields             fields,
                              in PRBool                       digest_p,
                              in PRBool                       dont_deliver_p,
                              in nsMsgDeliverMode             mode, 
                              in nsIMsgDBHdr                  msgToReplace,
                              in string               attachment1_type,
                              in string               attachment1_body,
                              in PRUint32                     attachment1_body_length,
                              [const] in nsMsgAttachmentData  attachments,
                              [const] in nsMsgAttachedFile    preloaded_attachments,
                              in voidPtr                      relatedPart,
                              in nsIDOMWindowInternal         parentWindow,
                              in nsIMsgProgress               progress,
                              in nsIMsgSendListener           aListener,
                              in string                       password,
                              in AUTF8String                  aOriginalMsgURI,
                              in MSG_ComposeType              aType
                             );

  /**
   * 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 PRBool               aDeleteSendFileOnCompletion,
                       in PRBool               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 PRBool aEnableFlag);
    
    /* Crypto */
    void BeginCryptoEncapsulation();

    /* retreive the last send process report*/
    readonly attribute nsIMsgSendReport sendReport; 
    
    /* methods for send listener ... */
    [noscript] void notifyListenerOnStartSending(in string aMsgID, in unsigned long aMsgSize);
    [noscript] void notifyListenerOnProgress(in string aMsgID, in unsigned long aProgress, in unsigned long aProgressMax);
    [noscript] void notifyListenerOnStatus(in string aMsgID, in wstring aMsg);
    [noscript] void notifyListenerOnStopSending(in string aMsgID, in nsresult aStatus, in wstring aMsg, in nsIFile returnFile);
    [noscript] void deliverAsMailExit(in nsIURI aUrl, in nsresult aExitCode);
    [noscript] void deliverAsNewsExit(in nsIURI aUrl, in nsresult aExitCode);
    
    [noscript] void sendDeliveryCallback(in nsIURI aUrl, in boolean inIsNewsDelivery, in nsresult aExitCode);

    /* methods for copy listener ... */
    [noscript] void notifyListenerOnStartCopy(); 
    [noscript] void notifyListenerOnProgressCopy(in unsigned long aProgress, in unsigned long aProgressMax);
    [noscript] void notifyListenerOnStopCopy(in nsresult aStatus);
    void getMessageId(out ACString messageID);
    [noscript] attribute nsMsgKey messageKey;

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

    [noscript] nsIMsgProgress getProgress();
    
    nsIOutputStream getOutputStream();

    [noscript] attribute nsIRequest runningRequest;

    [noscript] attribute nsresult status;

    [noscript] attribute nsIMsgComposeSecure cryptoclosure;
};