From 7dd930d180a31a4e408beb1401febe84ee69811c Mon Sep 17 00:00:00 2001 From: pallo Date: Wed, 29 Mar 2000 16:52:19 +0000 Subject: [PATCH 1/1] Partial docs for address book. git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@355 7612ce4b-ef26-0410-bec9-ea0150e637f0 --- doc/addressbook.txt | 136 ++++++++++++++++++++++++++++++++++++++++++++ doc/index.html | 7 +++ 2 files changed, 143 insertions(+) create mode 100644 doc/addressbook.txt diff --git a/doc/addressbook.txt b/doc/addressbook.txt new file mode 100644 index 00000000..29d87c1e --- /dev/null +++ b/doc/addressbook.txt @@ -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", ); + + $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 ... diff --git a/doc/index.html b/doc/index.html index 24e877df..8242b472 100644 --- a/doc/index.html +++ b/doc/index.html @@ -40,6 +40,13 @@ mistakes, please email them to lehresma@css.t + +