doc/addressbook.txt

   1 SquirrelMail Addressbook Internals
   2 ==================================
   3
   4 This document describe how the SquirrelMail address book works. It is
   5 primarily intended for developers.
   6
   7
   8 1. The Basics
   9 -------------
  10
  11 The address book is written using PHP classes, with one class,
  12 AddressBook, that use one or more "backend" classes to access
  13 different address books.
  14
  15 All operations, such as search, lookup, add etc., are performed by
  16 calling the appropriate methods from the AddressBook object. The
  17 operation will then be distributed by calling the correct method in
  18 the appropriate backend(s).
  19
  20 To initialize the address book, the function addressbook_init() from
  21 functions/addressbook.php is called. This function will create an
  22 AddressBook object, add one backend for a personal address book (file
  23 based storage), and add the LDAP backends defined in the $ldap_server
  24 configuration directive (is any).
  25
  26 An addressbook can also be initialized like this if you want to:
  27
  28   $abook = new AddressBook;
  29
  30   // Add one file based backend (personal address book)
  31   $abook->add_backend("local_file", Array("filename" => $filename,
  32                                           "create"   => true));
  33
  34   $abook->add_backend("ldap_server", <array with parameters>);
  35
  36   $res = $abook->search("John Doe");
  37
  38   echo $res[0]["name"] . " " . $res[0]["email"];
  39
  40
  41
  42 2. The AddressBook class
  43 ------------------------
  44
  45 This class acts as the glue for the address book. The following public
  46 methods are provided:
  47
  48   add_backend(NAME, PARAMETERS)
  49
  50      NAME - The name of the backend to add. A file with a
  51      class abook_NAME must be included before this can
  52      be done.
  53
  54      PARAMETERS - A mixed variable that is passed on to
  55      the backend class constructor. See each backend
  56      for docs.
  57
  58    This method will return a backend ID number (not usable at the
  59    moment), or false if it failed.
  60
  61
  62   search(QUERY, [BNUM])
  63
  64      QUERY - Something to search for. At the moment, only
  65      a string is allowed here, but advanced expressions
  66      will be supported through an array of parameters.
  67
  68      BNUM  - Optional backend number to search.
  69
  70    This method will return an array of result arrays (see below), an
  71    empty array if nothing was found, or false if the search failed.
  72
  73
  74   s_search(QUERY, [BNUM])
  75
  76    The same as search(), but the result array is sorted by backend and
  77    fullname before it is returned.
  78
  79
  80   lookup(NICKNAME, [BNUM])
  81
  82      NICKNAME - Return the user identified by NICKNAME in
  83      the addressbook.
  84
  85      BNUM - ID of the backend to look in (optional).
  86
  87    This method will return one result array (see below), an empty
  88    array if nothing was found, or false if the search failed. The
  89    lookup is only performed in "local" type backends.
  90
  91
  92   list_addr()
  93
  94    This method will return an array of result arrays (see below) for
  95    all addresses in the addressbook, or false if it failed. Only
  96    addresses in "local" type backends are returned.
  97
  98
  99   add(USERDATA, BNUM)
 100
 101      USERDATA - An array with user data. Must contain the following
 102      keys: nickname, firstname, lastname, email, label
 103      See below for information about the keys.
 104
 105      BNUM - ID of the backend, as returned by add_backend, to add this
 106      data to.
 107
 108    This method will return the backend ID of the backend where data
 109    was added, or false if it failed.
 110
 111
 112   remove(NICKNAME, BNUM)
 113
 114      NICKNAME - Delete the user identified by NICKNAME in the
 115      addressbook or, if NICKNAME is an array, all users indentified by
 116      nthe nicknames in the array.
 117
 118      BNUM - ID of the backend, as returned by add_backend, to remove
 119      the user(s) from.
 120
 121    This method will retrun true if the user(s) was removed, or false
 122    if removal failed.
 123
 124
 125   modify(NICKNAME, USERDATA, BNUM)
 126
 127      NICKNAME - Update the user identified by NICKNAME in the
 128      addressbook.
 129
 130      USERDATA - Array with user data. The exisiting data for the user
 131      will be replaced with this.
 132
 133      BNUM - ID of the backend, as returned by add_backend, to update
 134      the user in.
 135
 136    This method will retrun true if the user was modified, or false if
 137    something failed.
 138
 139
 140 If one of the above methods fail, an error message is available in the
 141 AddressBook->error variable. Feel free to ignore it.
 142
 143
 144 For the result of a search, lookup or list_addr, one or more result
 145 arrays are used. These arrays contain the following keys:
 146
 147   nickname:  Unique identifier for this name in this backend. Onlu
 148              usable for the local_file backend, and possibly LDAP.
 149   name:      Person's full name.
 150   email:     Person's e-mail address.
 151   backend:   Backend ID where this was found
 152   source:    Name of the backend where this was found
 153
 154 In addition, the following keys may exist for some backends:
 155
 156   label:     Additional information about the person
 157   firstname: Person's first name
 158   lastname:  Person's last name
 159
 160
 161 3. The backend classes
 162 ----------------------
 163
 164 ... more later ...
 165
 166 Ask pallo@squirrelmail.org if you have any questions on how to build
 167 new address book backends.