Partial docs for address book.

git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@355 7612ce4b-ef26-0410-bec9-ea0150e637f0

diff --git a/doc/addressbook.txt b/doc/addressbook.txt
new file mode 100644 (file)
index 0000000..29d87c1
--- /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", <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 ...

diff --git a/doc/index.html b/doc/index.html
index 24e877dff739e4949a8ffb7d4c32151ec9251a0e..8242b472f5654230e46f0703b2a0ab10eaba6786 100644 (file)
--- a/doc/index.html
+++ b/doc/index.html
@@ -40,6 +40,13 @@ mistakes, please email them to <a href="lehresma@css.tayloru.edu">lehresma@css.t
    </ul>
 </ul>
 
+<ul>
+   <a href="addressbook.txt">The Addressbook</a>
+   <ul>
+      This explains how the addressbook works internally.
+   </ul>
+</ul>
+
 <ul>
    Basic documentation that comes with distrbution:
    <ul>