/* -*- Mode: IDL; 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 mozIDOMWindowProxy;
interface nsIAbDirectory;
interface nsIAbCard;
interface nsIFile;
interface nsIAbBooleanExpression;

/**
 * nsIAbManager is an interface to the main address book manager
 * via the contract id "@mozilla.org/abmanager;1"
 *
 * It contains the main functions to create and delete address books as well
 * as some helper functions.
 */
[scriptable, uuid(ea0d8b3d-a549-4874-82d8-3a82cee2a3f1)]
interface nsIAbManager : nsISupports
{
  const unsigned long LDAP_DIRECTORY_TYPE = 0;
  const unsigned long MAPI_DIRECTORY_TYPE = 3;
  const unsigned long JS_DIRECTORY_TYPE = 101;
  const unsigned long CARDDAV_DIRECTORY_TYPE = 102;
  const unsigned long ASYNC_DIRECTORY_TYPE = 103;

  /**
   * Returns an array containing all the top-level directories.
   */
  readonly attribute Array<nsIAbDirectory> directories;

  /**
   * Returns the directory that represents the supplied URI.
   *
   * @param  aURI       The URI of the address book to find.
   * @return            The found address book.
   */
  nsIAbDirectory getDirectory(in ACString aURI);

  /**
   * Returns the directory that has the supplied dirPrefId.
   *
   * @param aDirPrefId  The dirPrefId of the directory.
   * @return            The found AB directory.
   */
  nsIAbDirectory getDirectoryFromId(in ACString aDirPrefId);

  /**
   * Returns the directory that has the supplied UID.
   *
   * @param aUID        The UID of the directory.
   * @return            The found AB directory.
   */
  nsIAbDirectory getDirectoryFromUID(in ACString aUID);

  /**
   * Creates a new address book.
   *
   * @param  aDirName   The description of the address book.
   * @param  aURI       The URI for the address book. This is specific to each
   *                    type of address book.
   * @param  aType      One of the *_DIRECTORY_TYPE constants.
   * @param  aUID       Sets the UID of the new Address Book.
   */
  ACString newAddressBook(in AString aDirName, in ACString aURI,
                          in unsigned long aType,
                          [optional] in AUTF8String aUID);

  /**
   * Adds a previously created address book object. If it has not been removed
   * (using `deleteAddressBook`) it will be removed at the end of the session.
   *
   * @param aDir The address book object.
   */
  void addAddressBook(in nsIAbDirectory aDir);

  /**
   * Deletes an address book.
   *
   * @param  aURI       The URI for the address book. This is specific to each
   *                    type of address book.
   */
  void deleteAddressBook(in ACString aURI);

  /**
   * Finds out if the mailing list name exists in any address book.
   *
   * @param  aName      The name of the list to try and find.
   *
   * @return            True if the name exists.
   */
  boolean mailListNameExists(in AString name);

  /**
   * Finds out if the directory name already exists.
   *
   * @param  aName      The name of a directory to check for.
   *
   * @return            True if a directory called name already exists.
   */
  boolean directoryNameExists(in AString name);

  /**
   * Returns an address book card for the specified email address if found, in
   * any directory. The first matching card found is returned.
   *
   * *** Results of this function are cached! ***
   * This function is for where speed is more important than accuracy. Results
   * are stored in a cache until 60s passes without this function being called.
   * The address book *could* change in this time, in a way that produces a
   * different result, but probably won't.
   *
   * @see    nsIAbCard.cardForEmailAddress
   * @param  emailAddress The email address to find in any of the email address
   *                      fields. If emailAddress is empty, the directories
   *                      won't be searched and the function will return as if
   *                      no card was found.
   * @return              An nsIAbCard if one was found, else returns NULL.
   */
  nsIAbCard cardForEmailAddress(in AUTF8String emailAddress);

  /**
   * Returns the mailing lists that has the supplied name.
   *
   * @param aName       The name of the list.
   * @return            The found AB directory.
   */
  nsIAbDirectory getMailListFromName(in AString aName);
};