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.