Roundcubemail devel
view | history | commit | commitdiff
thomascube
2011-01-04 965ed0ca7f5e07dc6d7d7e08ad8215b7c1c63b83
commit | author | age
cc97ea 1 <?php
T 2
3 /*
4  +-----------------------------------------------------------------------+
5  | program/include/rcube_addressbook.php                                 |
6  |                                                                       |
e019f2 7  | This file is part of the Roundcube Webmail client                     |
A 8  | Copyright (C) 2006-2009, Roundcube Dev. - Switzerland                 |
cc97ea 9  | Licensed under the GNU GPL                                            |
T 10  |                                                                       |
11  | PURPOSE:                                                              |
12  |   Interface to the local address book database                        |
13  |                                                                       |
14  +-----------------------------------------------------------------------+
15  | Author: Thomas Bruederli <roundcube@gmail.com>                        |
16  +-----------------------------------------------------------------------+
17
1d786c 18  $Id$
cc97ea 19
T 20 */
21
22
23 /**
24  * Abstract skeleton of an address book/repository
25  *
26  * @package Addressbook
27  */
28 abstract class rcube_addressbook
29 {
30     /** public properties */
31     var $primary_key;
a61bbb 32     var $groups = false;
cc97ea 33     var $readonly = true;
T 34     var $ready = false;
35     var $list_page = 1;
36     var $page_size = 10;
37
38     /**
39      * Save a search string for future listings
40      *
41      * @param mixed Search params to use in listing method, obtained by get_search_set()
42      */
43     abstract function set_search_set($filter);
44
45     /**
46      * Getter for saved search properties
47      *
48      * @return mixed Search properties used by this class
49      */
50     abstract function get_search_set();
51
52     /**
53      * Reset saved results and search parameters
54      */
55     abstract function reset();
56
57     /**
58      * List the current set of contact records
59      *
60      * @param  array  List of cols to show
61      * @param  int    Only return this number of records, use negative values for tail
62      * @return array  Indexed list of contact records, each a hash array
63      */
64     abstract function list_records($cols=null, $subset=0);
a61bbb 65
T 66     /**
cc97ea 67      * Search records
T 68      *
69      * @param array   List of fields to search in
70      * @param string  Search value
71      * @param boolean True if results are requested, False if count only
72      * @return Indexed list of contact records and 'count' value
73      */
74     abstract function search($fields, $value, $strict=false, $select=true);
75
76     /**
77      * Count number of available contacts in database
78      *
5c461b 79      * @return rcube_result_set Result set with values for 'count' and 'first'
cc97ea 80      */
T 81     abstract function count();
82
83     /**
84      * Return the last result set
85      *
5c461b 86      * @return rcube_result_set Current result set or NULL if nothing selected yet
cc97ea 87      */
T 88     abstract function get_result();
89
90     /**
91      * Get a specific contact record
92      *
93      * @param mixed record identifier(s)
94      * @param boolean True to return record as associative array, otherwise a result set is returned
b393e5 95      *
cc97ea 96      * @return mixed Result object with all record fields or False if not found
T 97      */
98     abstract function get_record($id, $assoc=false);
99
100     /**
101      * Close connection to source
102      * Called on script shutdown
103      */
104     function close() { }
105
106     /**
107      * Set internal list page
108      *
109      * @param  number  Page number to list
110      * @access public
111      */
112     function set_page($page)
113     {
2eb794 114         $this->list_page = (int)$page;
cc97ea 115     }
T 116
117     /**
118      * Set internal page size
119      *
120      * @param  number  Number of messages to display on one page
121      * @access public
122      */
123     function set_pagesize($size)
124     {
2eb794 125         $this->page_size = (int)$size;
cc97ea 126     }
a61bbb 127
T 128     /**
cc97ea 129      * Create a new contact record
T 130      *
131      * @param array Assoziative array with save data
132      * @param boolean True to check for duplicates first
5c461b 133      * @return mixed The created record ID on success, False on error
cc97ea 134      */
T 135     function insert($save_data, $check=false)
136     {
2eb794 137         /* empty for read-only address books */
cc97ea 138     }
T 139
140     /**
141      * Update a specific contact record
142      *
143      * @param mixed Record identifier
144      * @param array Assoziative array with save data
5c461b 145      * @return boolean True on success, False on error
cc97ea 146      */
T 147     function update($id, $save_cols)
148     {
2eb794 149         /* empty for read-only address books */
cc97ea 150     }
T 151
152     /**
153      * Mark one or more contact records as deleted
154      *
155      * @param array  Record identifiers
156      */
157     function delete($ids)
158     {
2eb794 159         /* empty for read-only address books */
cc97ea 160     }
T 161
162     /**
163      * Remove all records from the database
164      */
165     function delete_all()
166     {
2eb794 167         /* empty for read-only address books */
cc97ea 168     }
T 169
04adaa 170     /**
b393e5 171      * Setter for the current group
A 172      * (empty, has to be re-implemented by extending class)
173      */
174     function set_group($gid) { }
175
176     /**
177      * List all active contact groups of this source
178      *
179      * @return array  Indexed list of contact groups, each a hash array
180      */
181     function list_groups()
182     {
183         /* empty for address books don't supporting groups */
184         return array();
185     }
186
187     /**
04adaa 188      * Create a contact group with the given name
T 189      *
190      * @param string The group name
5c461b 191      * @return mixed False on error, array with record props in success
04adaa 192      */
T 193     function create_group($name)
194     {
2eb794 195         /* empty for address books don't supporting groups */
A 196         return false;
04adaa 197     }
b393e5 198
04adaa 199     /**
T 200      * Delete the given group and all linked group members
201      *
202      * @param string Group identifier
203      * @return boolean True on success, false if no data was changed
204      */
205     function delete_group($gid)
206     {
2eb794 207         /* empty for address books don't supporting groups */
A 208         return false;
04adaa 209     }
b393e5 210
04adaa 211     /**
T 212      * Rename a specific contact group
213      *
214      * @param string Group identifier
215      * @param string New name to set for this group
216      * @return boolean New name on success, false if no data was changed
217      */
218     function rename_group($gid, $newname)
219     {
2eb794 220         /* empty for address books don't supporting groups */
A 221         return false;
04adaa 222     }
b393e5 223
04adaa 224     /**
T 225      * Add the given contact records the a certain group
226      *
227      * @param string  Group identifier
228      * @param array   List of contact identifiers to be added
b393e5 229      * @return int    Number of contacts added
04adaa 230      */
T 231     function add_to_group($group_id, $ids)
232     {
2eb794 233         /* empty for address books don't supporting groups */
A 234         return 0;
04adaa 235     }
b393e5 236
04adaa 237     /**
T 238      * Remove the given contact records from a certain group
239      *
240      * @param string  Group identifier
241      * @param array   List of contact identifiers to be removed
242      * @return int    Number of deleted group members
243      */
244     function remove_from_group($group_id, $ids)
245     {
2eb794 246         /* empty for address books don't supporting groups */
A 247         return 0;
04adaa 248     }
b393e5 249
A 250     /**
251      * Get group assignments of a specific contact record
252      *
253      * @param mixed Record identifier
254      *
255      * @return array List of assigned groups as ID=>Name pairs
256      * @since 0.5-beta
257      */
258     function get_record_groups($id)
259     {
260         /* empty for address books don't supporting groups */
261         return array();
262     }
cc97ea 263 }
b393e5 264