Forgot one {
[squirrelmail.git] / doc / addressbook.txt
CommitLineData
7dd930d1 1SquirrelMail Addressbook Internals
2==================================
3
4This document describe how the SquirrelMail address book works. It is
5primarily intended for developers.
6
7
81. The Basics
9-------------
10
11The address book is written using PHP classes, with one class,
12AddressBook, that use one or more "backend" classes to access
13different address books.
14
15All operations, such as search, lookup, add etc., are performed by
16calling the appropriate methods from the AddressBook object. The
17operation will then be distributed by calling the correct method in
18the appropriate backend(s).
19
20To initialize the address book, the function addressbook_init() from
21functions/addressbook.php is called. This function will create an
22AddressBook object, add one backend for a personal address book (file
23based storage), and add the LDAP backends defined in the $ldap_server
24configuration directive (is any).
25
26An 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
422. The AddressBook class
43------------------------
44
45This class acts as the glue for the address book. The following public
46methods 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
2f73dc15 62 search(QUERY, [BNUM])
7dd930d1 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
2f73dc15 68 BNUM - Optional backend number to search.
7dd930d1 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
2f73dc15 74 s_search(QUERY, [BNUM])
7dd930d1 75
76 The same as search(), but the result array is sorted by backend and
77 fullname before it is returned.
78
79
b8360704 80 lookup(NICKNAME, [BNUM])
7dd930d1 81
82 NICKNAME - Return the user identified by NICKNAME in
83 the addressbook.
84
b8360704 85 BNUM - ID of the backend to look in (optional).
86
7dd930d1 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
b8360704 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
7dd930d1 139
140If one of the above methods fail, an error message is available in the
141AddressBook->error variable. Feel free to ignore it.
142
143
144For the result of a search, lookup or list_addr, one or more result
145arrays 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
154In 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
1613. The backend classes
162----------------------
163
164... more later ...
2f73dc15 165
166Ask pallo@squirrelmail.org if you have any questions on how to build
167new address book backends.