SquirrelMail Addressbook Internals
==================================
-This document describe how the SquirrelMail address book works. It is
+This document describes how the SquirrelMail address book works. It is
primarily intended for developers.
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).
+configuration directive (if any).
An addressbook can also be initialized like this if you want to:
moment), or false if it failed.
- search(QUERY, [BTYPE])
+ 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.
- BTYPE - Optional backend type to search. Either "local"
- or "remote".
+ 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, [BTYPE])
+ s_search(QUERY, [BNUM])
The same as search(), but the result array is sorted by backend and
fullname before it is returned.
- lookup(NICKNAME)
+ 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.
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. Onlu
+ 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.
----------------------
... more later ...
+
+Ask pallo@squirrelmail.org if you have any questions on how to build
+new address book backends.