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:  $
  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 $readonly = true;
  33     var $ready = false;
  34     var $list_page = 1;
  35     var $page_size = 10;
  36
  37     /**
  38      * Save a search string for future listings
  39      *
  40      * @param mixed Search params to use in listing method, obtained by get_search_set()
  41      */
  42     abstract function set_search_set($filter);
  43
  44     /**
  45      * Getter for saved search properties
  46      *
  47      * @return mixed Search properties used by this class
  48      */
  49     abstract function get_search_set();
  50
  51     /**
  52      * Reset saved results and search parameters
  53      */
  54     abstract function reset();
  55
  56     /**
  57      * List the current set of contact records
  58      *
  59      * @param  array  List of cols to show
  60      * @param  int    Only return this number of records, use negative values for tail
  61      * @return array  Indexed list of contact records, each a hash array
  62      */
  63     abstract function list_records($cols=null, $subset=0);
  64
  65     /**
  66      * Search records
  67      *
  68      * @param array   List of fields to search in
  69      * @param string  Search value
  70      * @param boolean True if results are requested, False if count only
  71      * @return Indexed list of contact records and 'count' value
  72      */
  73     abstract function search($fields, $value, $strict=false, $select=true);
  74
  75     /**
  76      * Count number of available contacts in database
  77      *
  78      * @return object rcube_result_set Result set with values for 'count' and 'first'
  79      */
  80     abstract function count();
  81
  82     /**
  83      * Return the last result set
  84      *
  85      * @return object rcube_result_set Current result set or NULL if nothing selected yet
  86      */
  87     abstract function get_result();
  88
  89     /**
  90      * Get a specific contact record
  91      *
  92      * @param mixed record identifier(s)
  93      * @param boolean True to return record as associative array, otherwise a result set is returned
  94      * @return mixed Result object with all record fields or False if not found
  95      */
  96     abstract function get_record($id, $assoc=false);
  97
  98     /**
  99      * Close connection to source
 100      * Called on script shutdown
 101      */
 102     function close() { }
 103
 104     /**
 105      * Set internal list page
 106      *
 107      * @param  number  Page number to list
 108      * @access public
 109      */
 110     function set_page($page)
 111     {
 112       $this->list_page = (int)$page;
 113     }
 114
 115     /**
 116      * Set internal page size
 117      *
 118      * @param  number  Number of messages to display on one page
 119      * @access public
 120      */
 121     function set_pagesize($size)
 122     {
 123       $this->page_size = (int)$size;
 124     }
 125
 126     /**
 127      * Create a new contact record
 128      *
 129      * @param array Assoziative array with save data
 130      * @param boolean True to check for duplicates first
 131      * @return The created record ID on success, False on error
 132      */
 133     function insert($save_data, $check=false)
 134     {
 135       /* empty for read-only address books */
 136     }
 137
 138     /**
 139      * Update a specific contact record
 140      *
 141      * @param mixed Record identifier
 142      * @param array Assoziative array with save data
 143      * @return True on success, False on error
 144      */
 145     function update($id, $save_cols)
 146     {
 147       /* empty for read-only address books */
 148     }
 149
 150     /**
 151      * Mark one or more contact records as deleted
 152      *
 153      * @param array  Record identifiers
 154      */
 155     function delete($ids)
 156     {
 157       /* empty for read-only address books */
 158     }
 159
 160     /**
 161      * Remove all records from the database
 162      */
 163     function delete_all()
 164     {
 165       /* empty for read-only address books */
 166     }
 167
 168 }
 169