program/include/rcube_addressbook.php

   1 <?php
   2
   3 /*
   4  +-----------------------------------------------------------------------+
   5  | program/include/rcube_addressbook.php                                 |
   6  |                                                                       |
   7  | This file is part of the Roundcube Webmail client                     |
   8  | Copyright (C) 2006-2009, Roundcube Dev. - Switzerland                 |
   9  | Licensed under the GNU GPL                                            |
  10  |                                                                       |
  11  | PURPOSE:                                                              |
  12  |   Interface to the local address book database                        |
  13  |                                                                       |
  14  +-----------------------------------------------------------------------+
  15  | Author: Thomas Bruederli <roundcube@gmail.com>                        |
  16  +-----------------------------------------------------------------------+
  17
  18  $Id: rcube_addressbook.php 4145 2010-10-27 07:23:57Z alec $
  19
  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;
  32     var $groups = false;
  33     var $readonly = true;
  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);
  65
  66     /**
  67      * Search records
  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      *
  79      * @return rcube_result_set Result set with values for 'count' and 'first'
  80      */
  81     abstract function count();
  82
  83     /**
  84      * Return the last result set
  85      *
  86      * @return rcube_result_set Current result set or NULL if nothing selected yet
  87      */
  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
  95      *
  96      * @return mixed Result object with all record fields or False if not found
  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     {
 114         $this->list_page = (int)$page;
 115     }
 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     {
 125         $this->page_size = (int)$size;
 126     }
 127
 128     /**
 129      * Create a new contact record
 130      *
 131      * @param array Assoziative array with save data
 132      * @param boolean True to check for duplicates first
 133      * @return mixed The created record ID on success, False on error
 134      */
 135     function insert($save_data, $check=false)
 136     {
 137         /* empty for read-only address books */
 138     }
 139
 140     /**
 141      * Update a specific contact record
 142      *
 143      * @param mixed Record identifier
 144      * @param array Assoziative array with save data
 145      * @return boolean True on success, False on error
 146      */
 147     function update($id, $save_cols)
 148     {
 149         /* empty for read-only address books */
 150     }
 151
 152     /**
 153      * Mark one or more contact records as deleted
 154      *
 155      * @param array  Record identifiers
 156      */
 157     function delete($ids)
 158     {
 159         /* empty for read-only address books */
 160     }
 161
 162     /**
 163      * Remove all records from the database
 164      */
 165     function delete_all()
 166     {
 167         /* empty for read-only address books */
 168     }
 169
 170     /**
 171      * Setter for the current group
 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     /**
 188      * Create a contact group with the given name
 189      *
 190      * @param string The group name
 191      * @return mixed False on error, array with record props in success
 192      */
 193     function create_group($name)
 194     {
 195         /* empty for address books don't supporting groups */
 196         return false;
 197     }
 198
 199     /**
 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     {
 207         /* empty for address books don't supporting groups */
 208         return false;
 209     }
 210
 211     /**
 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     {
 220         /* empty for address books don't supporting groups */
 221         return false;
 222     }
 223
 224     /**
 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
 229      * @return int    Number of contacts added
 230      */
 231     function add_to_group($group_id, $ids)
 232     {
 233         /* empty for address books don't supporting groups */
 234         return 0;
 235     }
 236
 237     /**
 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     {
 246         /* empty for address books don't supporting groups */
 247         return 0;
 248     }
 249
 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     }
 263 }
 264