/* 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 nsIMsgOutgoingServer;
interface nsIURI;
interface nsIUrlListener;
interface nsIMsgIdentity;
interface nsIInterfaceRequestor;
interface nsIFile;
interface nsIRequest;
interface nsIMsgWindow;

[scriptable, uuid(1b11b532-1527-4fc0-a00f-4ce7e6886419)]
interface nsIMsgOutgoingServerService : nsISupports {
  /**
   * Return the outgoing server that is associated with an identity.
   * If no outgoing server is associated with the given identity, the default
   * server is returned.
   *
   * @param  aSenderIdentity   the identity
   */
  nsIMsgOutgoingServer getServerByIdentity(in nsIMsgIdentity aSenderIdentity);

  /**
   * A copy of the array of outgoing servers, as stored in the preferences.
   */
  readonly attribute Array<nsIMsgOutgoingServer> servers;

  /**
   * The default server, across sessions of the app.
   */
  attribute nsIMsgOutgoingServer defaultServer;

  /**
   * Create a new outgoing server.
   *
   * Use this instead of createInstance(), so that this service can be aware of
   * this server.
   *
   * The service will raise an error if the `type` parameter is not in lower
   * case.
   *
   * @param type  The protocol implemented by the server, in lower case. The
   *              service uses this value to create an instance of the component
   *              with the contract ID
   *              @mozilla.org/messenger/outgoing/server;1?type=$type
   * @returns     The server once it has been created
   */
  nsIMsgOutgoingServer createServer(in AUTF8String type);

  /**
   * 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
   * @param type      The protocol the server implements. This parameter has the
   *                  same semantics as in createServer().
   * @returns         null if no server is found
   */
  nsIMsgOutgoingServer findServer(in AUTF8String username,
                                  in AUTF8String hostname,
                                  in AUTF8String type);

  /**
   * Look up the server with the given key.
   */
  nsIMsgOutgoingServer getServerByKey(in AUTF8String 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 nsIMsgOutgoingServer server);
};