diff options
Diffstat (limited to 'mailnews/addrbook/public/nsIAbManager.idl')
| -rw-r--r-- | mailnews/addrbook/public/nsIAbManager.idl | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/mailnews/addrbook/public/nsIAbManager.idl b/mailnews/addrbook/public/nsIAbManager.idl new file mode 100644 index 000000000..49a585544 --- /dev/null +++ b/mailnews/addrbook/public/nsIAbManager.idl @@ -0,0 +1,190 @@ +/* -*- 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" +#include "nsIAbListener.idl" + +interface mozIDOMWindowProxy; +interface nsIAbDirectory; +interface nsIAbCard; +interface nsIAbDirectoryProperties; +interface nsIFile; +interface nsISimpleEnumerator; +interface nsIAbBooleanExpression; + +/** + * nsIAbManager is an interface to the main address book mananger + * 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 +{ + /** + * Returns an enumerator containing all the top-level directories + * (non-recursive) + */ + readonly attribute nsISimpleEnumerator 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); + + /** + * 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 The type of the address book (see nsDirPrefs.h) + * @param aPrefName Overrides the default of ldap_2.servers.<aDirName> + * (note that the caller must ensure its uniqueness). + */ + ACString newAddressBook(in AString aDirName, in ACString aURI, + in unsigned long aType, + [optional] in ACString aPrefName); + + /** + * 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); + + /** + * Exports an address book, it will provide a dialog to the user for the + * location to save the file to and will then save the address book to media. + * + * @param aParentWin Parent Window for the file save dialog to use. + * @param aDirectory The directory to export. + */ + void exportAddressBook(in mozIDOMWindowProxy aParentWin, in nsIAbDirectory aDirectory); + + /** + * Adds a nsIAbListener to receive notifications of address book updates + * according to the specified notifyFlags. + * + * @param aListener The listener that is to receive updates. + * @param aNotifyFlags A bitwise-or of abListenerNotifyFlagValue items + * specifying which notifications to receive. See + * nsIAbListener for possible values. + */ + void addAddressBookListener(in nsIAbListener aListener, + in abListenerNotifyFlagValue aNotifyFlags); + + /** + * Removes a nsIAbListener from receive notifications of address book + * updates. + * + * @param aListener The listener that is to no longer receive updates. + */ + void removeAddressBookListener(in nsIAbListener aListener); + + /** + * Call to notify the registered listeners when a property on an item has + * changed. + * + * @param aItem The items that has changed (e.g. an nsIAbDirectory) + * @param aProperty The property that has changed (e.g. DirName) + * @param aOldValue The old value of the property. + * @param aNewValue The new value of the property. + */ + void notifyItemPropertyChanged(in nsISupports aItem, + in string aProperty, + in wstring aOldValue, + in wstring aNewValue); + + /** + * Call to notify the registered listeners when a directory item is added. + * + * @param aParentDirectory The parent directory of the item that has been + * added. + * @param aItem The item that has been added. + */ + void notifyDirectoryItemAdded(in nsIAbDirectory aParentDirectory, + in nsISupports aItem); + + /** + * Call to notify the registered listeners when a directory item is removed. + * + * @param aParentDirectory The parent directory of the item that has been + * removed. + * @param aItem The item that has been removed. + */ + void notifyDirectoryItemDeleted(in nsIAbDirectory aParentDirectory, + in nsISupports aItem); + + /** + * Call to notify the registered listeners when a directory is removed. + * + * @param aParentDirectory The parent directory of the directory that has + * been removed. + * @param aDirectory The directory that has been removed. + */ + void notifyDirectoryDeleted(in nsIAbDirectory aParentDirectory, + in nsISupports aDirectory); + + /** + * Returns the user profile directory. NOTE: this should not be used + * as it may go away soon. + */ + readonly attribute nsIFile userProfileDirectory; + + /** + * Finds out if the mailing list name exists in any *mork/MDB* based + * address book + * + * @param aName The name of the list to try and find. + * + * @return True if the name exists. + */ + boolean mailListNameExists(in wstring name); + + /** + * Translates an escaped vcard string into a nsIAbCard. + * + * @param escapedVCardStr The string containing the vcard. + * + * @return A card containing the translated vcard data. + */ + nsIAbCard escapedVCardToAbCard(in string escapedVCardStr); + + /** + * Generates a UUID from a (directory ID, local ID) tuple. + * + * Use of this method is preferred in such cases, since it is designed to work + * with other methods of this interface. + * + * @param directoryId The directory ID. + * @param localId The per-directory ID. + * @return A string to use for the UUID. + */ + AUTF8String generateUUID(in AUTF8String directoryId, in AUTF8String localId); + + + /** + * A utility function that converts an nsIAbDirectory query string to an + * nsIAbBooleanExpression. + * + * @param aQueryString The nsIAbDirectory query string + * @return an nsIAbBooleanExpression for the query string + */ + nsIAbBooleanExpression convertQueryStringToExpression(in AUTF8String aQueryString); +}; |