Dactyloidae/mailnews/compose/public/nsISmtpService.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 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/. */

#include "nsISupports.idl"

interface nsISmtpServer;
interface nsIURI;
interface nsIUrlListener;
interface nsIMsgIdentity;
interface nsIInterfaceRequestor;
interface nsIFile;
interface nsIMsgStatusFeedback;
interface nsIRequest;
interface nsISimpleEnumerator;
interface nsIMsgWindow;

[scriptable, uuid(1b11b532-1527-4fc0-a00f-4ce7e6886419)]
interface nsISmtpService : nsISupports {
  /**
   * Sends a mail message via the given parameters. This function builds an
   * SMTP URL and makes an SMTP connection, and then runs the url.
   * The SMTP server defined
   * in the aSenderIdentity object (see nsIMsgIdentity) will be used to send
   * the message. If there is no SMTP server defined in aSenderIdentity, the
   * default SMTP server will be used.
   *
   * @note The file to send must be in the format specified by RFC 2822 for
   *       sending data. This includes having the correct CRLF line endings
   *       throughout the file, and the <CRLF>.<CRLF> at the end of the file.
   *       sendMailMessage does no processing/additions on the file.
   *
   * @param aFilePath               The file to send.
   * @param aRecipients             A comma delimited list of recipients.
   * @param aSenderIdentity         The identity of the sender.
   * @param aPassword               Pass this in to prevent a dialog if the
   *                                password is needed for secure transmission.
   * @param aUrlListener            A listener to listen to the URL being run,
   *                                this parameter may be null.
   * @param aStatusListener         A feedback listener for slightly different
   *                                feedback on the message send status. This
   *                                parameter may be null.
   * @param aNotificationCallbacks  More notification callbacks
   * @param aRequestDSN             Pass true to request Delivery Status
   *                                Notification.
   * @param aURL                    Provides a handle on the running url. You
   *                                can later interrupt the action by asking the
   *                                netlib service manager to interrupt the url
   *                                you are given back. This parameter may be
   *                                null.
   * @param aRequest                Provides a handle to the running request.
   *                                This parameter may be null.
   */
  void sendMailMessage(in nsIFile aFilePath, in string aRecipients, 
                       in nsIMsgIdentity aSenderIdentity,
                       in string aPassword,
                       in nsIUrlListener aUrlListener, 
                       in nsIMsgStatusFeedback aStatusListener, 
                       in nsIInterfaceRequestor aNotificationCallbacks,
                       in boolean aRequestDSN,
                       out nsIURI aURL,
                       out nsIRequest aRequest);

  /**
   * Verifies that we can logon to the server with given password
   *
   * @param  aSmtpServer       Server to try to logon to.
   * @param  aUrlListener      Listener that will get notified whether logon
   *                           was successful or not.
   * @param aMsgWindow         nsIMsgWindow to use for notification callbacks.
   * @return - the url that we run.
   */
  nsIURI verifyLogon(in nsISmtpServer aServer, in nsIUrlListener aListener,
                     in nsIMsgWindow aMsgWindow);

  /**
   * Return the SMTP server that is associated with an identity.
   * @param  aSenderIdentity   the identity
   * @param  aServer           the SMTP server
   */
  void getServerByIdentity(in nsIMsgIdentity aSenderIdentity,
                           out nsISmtpServer aServer);

  /**
   * A copy of the array of SMTP servers, as stored in the preferences
   */
  readonly attribute nsISimpleEnumerator servers;

  /**
   * The default server, across sessions of the app
   * (eventually there will be a session default which does not
   * persist past shutdown)
   */
  attribute nsISmtpServer defaultServer;

  /**
   * The "session default" server - this is never saved, and only used
   * for the current session. Always falls back to the default server
   * unless explicitly set.
   */
  attribute nsISmtpServer sessionDefaultServer;

  /**
   * Create a new SMTP server.
   * Use this instead of createInstance(), so that the SMTP Service can
   * be aware of this server
   */
  nsISmtpServer createServer();

  /**
   * Find the first server with the given hostname and/or username.
   * Note: if either username or hostname is empty, then that parameter will
   * not be used in the matching process.
   * @param username  the username for the server
   * @param hostname  the hostname of the server
   * @returns         null if no server is found
   */
  nsISmtpServer findServer(in string username, in string hostname);

  /**
   * Look up the server with the given key
   * If the server does not exist, create it and add it to our list
   */
  nsISmtpServer getServerByKey(in string key);
  
  /**
   * Delete the given server from the server list - does nothing if the server
   * does not exist
   * @param server   the server to delete. Use findServer() if you only know
   *                 the hostname
   */
  void deleteServer(in nsISmtpServer server);
};