Updated with new methods.
[squirrelmail.git] / 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, [BTYPE])
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      BTYPE - Optional backend type to search. Either "local"
69      or "remote".
70
71    This method will return an array of result arrays (see below), an
72    empty array if nothing was found, or false if the search failed.
73
74
75   s_search(QUERY, [BTYPE])
76
77    The same as search(), but the result array is sorted by backend and
78    fullname before it is returned.
79
80
81   lookup(NICKNAME, [BNUM])  
82
83      NICKNAME - Return the user identified by NICKNAME in
84      the addressbook.
85
86      BNUM - ID of the backend to look in (optional).
87
88    This method will return one result array (see below), an empty
89    array if nothing was found, or false if the search failed. The
90    lookup is only performed in "local" type backends.
91  
92
93   list_addr()  
94
95    This method will return an array of result arrays (see below) for
96    all addresses in the addressbook, or false if it failed. Only
97    addresses in "local" type backends are returned.
98  
99
100   add(USERDATA, BNUM)
101
102      USERDATA - An array with user data. Must contain the following
103      keys: nickname, firstname, lastname, email, label
104      See below for information about the keys.
105
106      BNUM - ID of the backend, as returned by add_backend, to add this
107      data to.
108
109    This method will return the backend ID of the backend where data
110    was added, or false if it failed.
111
112
113   remove(NICKNAME, BNUM)
114
115      NICKNAME - Delete the user identified by NICKNAME in the
116      addressbook or, if NICKNAME is an array, all users indentified by
117      nthe nicknames in the array.
118
119      BNUM - ID of the backend, as returned by add_backend, to remove
120      the user(s) from.
121
122    This method will retrun true if the user(s) was removed, or false
123    if removal failed.
124
125
126   modify(NICKNAME, USERDATA, BNUM)
127
128      NICKNAME - Update the user identified by NICKNAME in the
129      addressbook.
130
131      USERDATA - Array with user data. The exisiting data for the user
132      will be replaced with this.
133
134      BNUM - ID of the backend, as returned by add_backend, to update
135      the user in.
136
137    This method will retrun true if the user was modified, or false if
138    something failed.
139
140
141 If one of the above methods fail, an error message is available in the
142 AddressBook->error variable. Feel free to ignore it.
143
144
145 For the result of a search, lookup or list_addr, one or more result
146 arrays are used. These arrays contain the following keys: 
147
148   nickname:  Unique identifier for this name in this backend. Onlu
149              usable for the local_file backend, and possibly LDAP.
150   name:      Person's full name.
151   email:     Person's e-mail address.
152   backend:   Backend ID where this was found
153   source:    Name of the backend where this was found
154
155 In addition, the following keys may exist for some backends:
156
157   label:     Additional information about the person
158   firstname: Person's first name
159   lastname:  Person's last name
160
161
162 3. The backend classes
163 ----------------------
164
165 ... more later ...