X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=doc%2FDevelopment%2Faddressbook.txt;fp=doc%2FDevelopment%2Faddressbook.txt;h=0000000000000000000000000000000000000000;hb=6e57716a4ddc6e93623f9b7cdb93bf9a8bf8d412;hp=4d1f7d8f82691df6a268d4717c7233fa41df562f;hpb=2128bbc6c5a178906d5d7b925bcd6d0652f47f52;p=squirrelmail.git diff --git a/doc/Development/addressbook.txt b/doc/Development/addressbook.txt deleted file mode 100644 index 4d1f7d8f..00000000 --- a/doc/Development/addressbook.txt +++ /dev/null @@ -1,167 +0,0 @@ -SquirrelMail Addressbook Internals -================================== - -This document describes how the SquirrelMail address book works. It is -primarily intended for developers. - - -1. The Basics -------------- - -The address book is written using PHP classes, with one class, -AddressBook, that use one or more "backend" classes to access -different address books. - -All operations, such as search, lookup, add etc., are performed by -calling the appropriate methods from the AddressBook object. The -operation will then be distributed by calling the correct method in -the appropriate backend(s). - -To initialize the address book, the function addressbook_init() from -functions/addressbook.php is called. This function will create an -AddressBook object, add one backend for a personal address book (file -based storage), and add the LDAP backends defined in the $ldap_server -configuration directive (if any). - -An addressbook can also be initialized like this if you want to: - - $abook = new AddressBook; - - // Add one file based backend (personal address book) - $abook->add_backend("local_file", Array("filename" => $filename, - "create" => true)); - - $abook->add_backend("ldap_server", ); - - $res = $abook->search("John Doe"); - - echo $res[0]["name"] . " " . $res[0]["email"]; - - - -2. The AddressBook class ------------------------- - -This class acts as the glue for the address book. The following public -methods are provided: - - add_backend(NAME, PARAMETERS) - - NAME - The name of the backend to add. A file with a - class abook_NAME must be included before this can - be done. - - PARAMETERS - A mixed variable that is passed on to - the backend class constructor. See each backend - for docs. - - This method will return a backend ID number (not usable at the - moment), or false if it failed. - - - search(QUERY, [BNUM]) - - QUERY - Something to search for. At the moment, only - a string is allowed here, but advanced expressions - will be supported through an array of parameters. - - BNUM - Optional backend number to search. - - This method will return an array of result arrays (see below), an - empty array if nothing was found, or false if the search failed. - - - s_search(QUERY, [BNUM]) - - The same as search(), but the result array is sorted by backend and - fullname before it is returned. - - - lookup(NICKNAME, [BNUM]) - - NICKNAME - Return the user identified by NICKNAME in - the addressbook. - - BNUM - ID of the backend to look in (optional). - - This method will return one result array (see below), an empty - array if nothing was found, or false if the search failed. The - lookup is only performed in "local" type backends. - - - list_addr() - - This method will return an array of result arrays (see below) for - all addresses in the addressbook, or false if it failed. Only - addresses in "local" type backends are returned. - - - add(USERDATA, BNUM) - - USERDATA - An array with user data. Must contain the following - keys: nickname, firstname, lastname, email, label - See below for information about the keys. - - BNUM - ID of the backend, as returned by add_backend, to add this - data to. - - This method will return the backend ID of the backend where data - was added, or false if it failed. - - - remove(NICKNAME, BNUM) - - NICKNAME - Delete the user identified by NICKNAME in the - addressbook or, if NICKNAME is an array, all users indentified by - nthe nicknames in the array. - - BNUM - ID of the backend, as returned by add_backend, to remove - the user(s) from. - - This method will retrun true if the user(s) was removed, or false - if removal failed. - - - modify(NICKNAME, USERDATA, BNUM) - - NICKNAME - Update the user identified by NICKNAME in the - addressbook. - - USERDATA - Array with user data. The exisiting data for the user - will be replaced with this. - - BNUM - ID of the backend, as returned by add_backend, to update - the user in. - - This method will retrun true if the user was modified, or false if - something failed. - - -If one of the above methods fail, an error message is available in the -AddressBook->error variable. Feel free to ignore it. - - -For the result of a search, lookup or list_addr, one or more result -arrays are used. These arrays contain the following keys: - - nickname: Unique identifier for this name in this backend. Only - usable for the local_file backend, and possibly LDAP. - name: Person's full name. - email: Person's e-mail address. - backend: Backend ID where this was found - source: Name of the backend where this was found - -In addition, the following keys may exist for some backends: - - label: Additional information about the person - firstname: Person's first name - lastname: Person's last name - - -3. The backend classes ----------------------- - -... more later ... - -Ask pallo@squirrelmail.org if you have any questions on how to build -new address book backends.