path: root/comm/mailnews/addrbook/public/nsIAbDirectory.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 nsIAbCard;
interface nsIAbDirSearchListener;

/* moz-abdirectory:// is the URI to access nsAbBSDirectory,
 * which is the root directory for all types of address books
 * this is used to get all address book directories. */

%{C++
#define kAllDirectoryRoot          "moz-abdirectory://"

#define kPersonalAddressbook       "abook.sqlite"
#define kPersonalAddressbookUri    "jsaddrbook://abook.sqlite"
#define kCollectedAddressbook      "history.sqlite"
#define kCollectedAddressbookUri   "jsaddrbook://history.sqlite"

#define kABFileName_PreviousSuffix ".na2" /* final v2 address book format */
#define kABFileName_PreviousSuffixLen 4
#define kABFileName_CurrentSuffix  ".mab" /* v3 address book extension */

#define kJSDirectoryRoot           "jsaddrbook://"
#define kJSAddressBook             "abook.sqlite"
%}

/**
 * A top-level address book directory.
 *
 * Please note that in order to be properly instantiated by nsIAbManager, every
 * type of nsIAbDirectory must have a contract ID of the form:
 *
 * @mozilla.org/addressbook/directory;1?type=<AB URI Scheme>
 *
 * Where AB URI Scheme does not include the ://.  For example, for the
 * SQLite-based address book, the scheme is "jsaddrbook", so the contract ID for
 * the SQLite-based address book type is:
 *
 * @mozilla.org/addressbook/directory;1?type=jsaddrbook
 */
[scriptable, uuid(72dc868b-db5b-4daa-b6c6-071be4a05d02)]
interface nsIAbDirectory : nsISupports {
  /**
   * Returns true if this collection is read-only.
   */
  readonly attribute boolean readOnly;

  /**
   * Returns true if this collection is accessed over a network connection.
   */
  readonly attribute boolean isRemote;

  /**
   * Returns true if this collection is accessed over a secure connection.
   *
   * If isRemote returns false, then this value MUST be false as well.
   */
  readonly attribute boolean isSecure;

  /**
   * Returns an address book card for the specified email address if found.
   *
   * If there are multiple cards with the given email address, this method will
   * return one of these cards in an implementation-defined manner.
   *
   * Matching is performed in a case-insensitive manner.
   *
   * This method performs a synchronous operation. If the collection cannot do
   * the search in such a manner, then it should throw NS_ERROR_NOT_IMPLEMENTED.
   *
   * @param  emailAddress The email address to find in any of the email address
   *                      fields. If emailAddress is empty, the database 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.
   * @exception NS_ERROR_NOT_IMPLEMENTED If the collection cannot do this.
   */
  nsIAbCard cardForEmailAddress(in AUTF8String emailAddress);

  /**
   * Returns an address book card for the specified property if found.
   *
   * If there are multiple cards with the given value for the property, this
   * method will return one of these cards in an implementation-defined manner.
   *
   * This method performs a synchronous operation. If the collection cannot do
   * the search in such a manner, then it should throw NS_ERROR_NOT_IMPLEMENTED.
   *
   * If the property is not natively a string, it can still be searched for
   * using the string-encoded value of the property, e.g. "0". See
   * nsIAbCard::getPropertyAsAUTF8String for more information. Empty values will
   * return no match, to prevent spurious results.
   *
   * @param  aProperty      The property to look for.
   * @param  aValue         The value to search for.
   * @param  aCaseSensitive True if matching should be done case-sensitively.
   * @result                An nsIAbCard if one was found, else returns NULL.
   * @exception NS_ERROR_NOT_IMPLEMENTED If the collection cannot do this.
   */
  nsIAbCard getCardFromProperty(in string aProperty, in AUTF8String aValue,
                                in boolean aCaseSensitive);

  /**
   * Returns all address book cards with a specific property matching value
   *
   * This function is almost identical to getCardFromProperty, with the
   * exception of returning all cards rather than just the first.
   *
   * @param  aProperty      The property to look for.
   * @param  aValue         The value to search for.
   * @param  aCaseSensitive True if matching should be done case-sensitively.
   * @result                The matching nsIAbCard instances.
   */
  Array<nsIAbCard> getCardsFromProperty(in string aProperty,
                                        in AUTF8String aValue,
                                        in boolean aCaseSensitive);

  /**
   * Returns the nsIAbDirectory for a mailing list with the specified name.
   */
  nsIAbDirectory getMailListFromName(in AString aName);

  /**
   * The chrome URI to use for bringing up a dialog to edit this directory.
   * When opening the dialog, use a JS argument of
   * {selectedDirectory: thisdir} where thisdir is this directory that you just
   * got the chrome URI from.
   */
  readonly attribute ACString propertiesChromeURI;

  /**
   * The description of the directory. If this directory is not a mailing list,
   * then setting this attribute will send round a "DirName" update via
   * nsIAddrBookSession.
   */
  attribute AString dirName;

  // XXX This should really be replaced by a QI or something better
  readonly attribute long dirType;

  // The filename for address books within this directory.
  readonly attribute ACString fileName;

  /**
   * A 128-bit unique identifier for this directory.
   */
  readonly attribute AUTF8String UID;
  [noscript] void setUID(in AUTF8String aUID);

  // The URI of the address book
  readonly attribute ACString URI;

  // The position of the directory on the display.
  readonly attribute long position;

  // will be used for LDAP replication
  attribute unsigned long lastModifiedDate;

  // Defines whether this directory is a mail
  // list or not
  attribute boolean isMailList;

  // Get the children directories
  readonly attribute Array<nsIAbDirectory> childNodes;

  /**
   * Get the count of cards associated with the directory. This includes the
   * cards associated with the mailing lists too.
   */
  readonly attribute unsigned long childCardCount;

  /**
   * Get the cards associated with the directory. This will return the cards
   * associated with the mailing lists too.
   */
  readonly attribute Array<nsIAbCard> childCards;

  /**
   * Searches the directory for cards matching query.
   *
   * The query takes the form:
   * (BOOL1(FIELD1,OP1,VALUE1)..(FIELDn,OPn,VALUEn)(BOOL2(FIELD1,OP1,VALUE1)...)...)
   *
   * BOOLn   A boolean operator joining subsequent terms delimited by ().
   *         For possible values see CreateBooleanExpression().
   * FIELDn  An addressbook card data field.
   * OPn     An operator for the search term.
   *         For possible values see CreateBooleanConditionString().
   * VALUEn  The value to be matched in the FIELDn via the OPn operator.
   *         The value must be URL encoded by the caller, if it contains any
   *         special characters including '(' and ')'.
   */
  void search(in AString query, in AString searchString, in nsIAbDirSearchListener listener);

  /**
   * Initializes a directory, pointing to a particular URI.
   */
  void init(in string aURI);

  /**
   * Clean up any database connections or open file handles.
   * Called at shutdown or if the directory is about to be deleted.
   */
  [implicit_jscontext]
  Promise cleanUp();

  // Deletes either a mailing list or a top
  // level directory, which also updates the
  // preferences
  void deleteDirectory(in nsIAbDirectory directory);

  // Check if directory contains card
  // If the implementation is asynchronous the card
  // may not yet have arrived. If it is in the process
  // of obtaining cards the method will throw an
  // NS_ERROR_NOT_AVAILABLE exception if the card
  // cannot be found.
  boolean hasCard(in nsIAbCard cards);

  // Check if directory contains directory
  boolean hasDirectory(in nsIAbDirectory dir);

  // Check if directory contains a mailinglist by name
  boolean hasMailListWithName(in AString aName);

  /**
   * Adds a card to the database.
   *
   * This card does not need to be of the same type as the database, e.g., one
   * can add an nsIAbLDAPCard to an nsIAbMDBDirectory.
   *
   * @return "Real" card (eg nsIAbLDAPCard) that can be used for some
   *         extra functions.
   */
  nsIAbCard addCard(in nsIAbCard card);

  /**
   * Modifies a card in the database to match that supplied.
   */
  void modifyCard(in nsIAbCard modifiedCard);

  /**
   * Deletes the array of cards from the database.
   *
   * @param  aCards  The cards to delete from the database.
   */
  void deleteCards(in Array<nsIAbCard> aCards);

  void dropCard(in nsIAbCard card, in boolean needToCopyCard);

  /**
   * Whether or not the directory should be searched when doing autocomplete,
   * (currently by using GetChildCards); LDAP does not support this in online
   * mode, so that should return false; additionally any other directory types
   * that also do not support GetChildCards should return false.
   *
   * @param aIdentity  An optional parameter detailing the identity key (see
   *                   nsIMsgAccountManager) that this autocomplete is being
   *                   run against.
   * @return           True if this directory should/can be used during
   *                   local autocomplete.
   */
  boolean useForAutocomplete(in ACString aIdentityKey);

  /**
   * Does this directory support mailing lists? Note that in the case
   * this directory is a mailing list and nested mailing lists are not
   * supported, this will return false rather than true which the parent
   * directory might.
   */
  readonly attribute boolean supportsMailingLists;

  // Specific to a directory which stores mail lists

  /**
   * Creates a new mailing list in the directory. Currently only supported
   * for top-level directories.
   *
   * @param  list  The new mailing list to add.
   * @return The mailing list directory added, which may have been modified.
   */
  nsIAbDirectory addMailList(in nsIAbDirectory list);

  /**
   * Nick Name of the mailing list. This attribute is only really used when
   * the nsIAbDirectory represents a mailing list.
   */
  attribute AString listNickName;

  /**
   * Description of the mailing list. This attribute is only really used when
   * the nsIAbDirectory represents a mailing list.
   */
  attribute AString description;

  /**
   * Edits an existing mailing list (specified as listCard) into its parent
   * directory. You should call this function on the resource with the same
   * uri as the listCard.
   *
   * @param  listCard  A nsIAbCard version of the mailing list with the new
   *                   values.
   */
  void editMailListToDatabase(in nsIAbCard listCard);

  // Copies mail list properties from the srcList
  void copyMailList(in nsIAbDirectory srcList);

  /**
   * The id of the directory used in prefs e.g. "ldap_2.servers.pab"
   */
  readonly attribute ACString dirPrefId;

  /**
   * @name  getXXXValue
   *
   * Helper functions to get different types of pref, but return a default
   * value if a pref value was not obtained.
   *
   * @param aName         The name of the pref within the branch dirPrefId to
   *                      get a value from.
   *
   * @param aDefaultValue The default value to return if getting the pref fails
   *                      or the pref is not present.
   *
   * @return              The value of the pref or the default value.
   *
   * @exception           NS_ERROR_NOT_INITIALIZED if the pref branch couldn't
   *                      be obtained (e.g. dirPrefId isn't set).
   */
  //@{
  long getIntValue(in string aName, in long aDefaultValue);
  boolean getBoolValue(in string aName, in boolean aDefaultValue);
  ACString getStringValue(in string aName, in ACString aDefaultValue);
  AUTF8String getLocalizedStringValue(in string aName, in AUTF8String aDefaultValue);
  //@}

  /**
   * The following attributes are read from an nsIAbDirectory via the above methods:
   *
   * HidesRecipients (Boolean)
   *    If true, and this nsIAbDirectory is a mailing list, then when sending mail to
   *    this list, recipients addresses will be hidden from one another by sending
   *    via BCC.
   */

  /**
   * @name  setXXXValue
   *
   * Helper functions to set different types of pref values.
   *
   * @param aName         The name of the pref within the branch dirPrefId to
   *                      get a value from.
   *
   * @param aValue        The value to set the pref to.
   *
   * @exception           NS_ERROR_NOT_INITIALIZED if the pref branch couldn't
   *                      be obtained (e.g. dirPrefId isn't set).
   */
  //@{
  void setIntValue(in string aName, in long aValue);
  void setBoolValue(in string aName, in boolean aValue);
  void setStringValue(in string aName, in ACString aValue);
  void setLocalizedStringValue(in string aName, in AUTF8String aValue);
  //@}

};