|
|
@@ -0,0 +1,136 @@
|
|
|
+SquirrelMail Addressbook Internals
|
|
|
+==================================
|
|
|
+
|
|
|
+This document describe 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 (is 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", <array with parameters>);
|
|
|
+
|
|
|
+ $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, [BTYPE])
|
|
|
+
|
|
|
+ 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.
|
|
|
+
|
|
|
+ BTYPE - Optional backend type to search. Either "local"
|
|
|
+ or "remote".
|
|
|
+
|
|
|
+ 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, [BTYPE])
|
|
|
+
|
|
|
+ The same as search(), but the result array is sorted by backend and
|
|
|
+ fullname before it is returned.
|
|
|
+
|
|
|
+
|
|
|
+ lookup(NICKNAME)
|
|
|
+
|
|
|
+ NICKNAME - Return the user identified by NICKNAME in
|
|
|
+ the addressbook.
|
|
|
+
|
|
|
+ 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.
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+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. Onlu
|
|
|
+ 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 ...
|
pallo