+++ /dev/null
-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", <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, [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.
projects / squirrelmail.git / blobdiff