Revision control
Copy as Markdown
Other Tools
/* -*- 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
#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 kCollectedAddressbook "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);
//@}
};