diff options
Diffstat (limited to 'comm/mailnews/addrbook/public/nsIAbDirectory.idl')
| -rw-r--r-- | comm/mailnews/addrbook/public/nsIAbDirectory.idl | 371 |
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); + //@} + +}; |