Add index.html to Development subdir, rename README.russian_apache to

[squirrelmail.git] / doc / Development / addressbook.txt

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.