Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 371 insertions, 0 deletions

diff --git a/comm/mailnews/addrbook/public/nsIAbDirectory.idl b/comm/mailnews/addrbook/public/nsIAbDirectory.idl
new file mode 100644
index 0000000000..07eab7aa81
--- /dev/null
+++ b/comm/mailnews/addrbook/public/nsIAbDirectory.idl
@@ -0,0 +1,371 @@
+/* -*- 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);
+  //@}
+
+};