Merge branch devel-addressbook (r4193:4382) back into trunk

1 files changed, 106 insertions, 11 deletions

diff --git a/program/include/rcube_addressbook.php b/program/include/rcube_addressbook.php
index ae2a286c3..b9a31cc74 100644
--- a/program/include/rcube_addressbook.php
+++ b/program/include/rcube_addressbook.php
@@ -5,7 +5,7 @@
  | program/include/rcube_addressbook.php                                 |
  |                                                                       |
  | This file is part of the Roundcube Webmail client                     |
- | Copyright (C) 2006-2009, The Roundcube Dev Team                       |
+ | Copyright (C) 2006-2011, The Roundcube Dev Team                       |
  | Licensed under the GNU GPL                                            |
  |                                                                       |
  | PURPOSE:                                                              |
@@ -27,13 +27,22 @@
  */
 abstract class rcube_addressbook
 {
-    /** public properties */
-    var $primary_key;
-    var $groups = false;
-    var $readonly = true;
-    var $ready = false;
-    var $list_page = 1;
-    var $page_size = 10;
+    /** constants for error reporting **/
+    const ERROR_READ_ONLY = 1;
+    const ERROR_NO_CONNECTION = 2;
+    const ERROR_INCOMPLETE = 3;
+    const ERROR_SAVING = 4;
+    
+    /** public properties (mandatory) */
+    public $primary_key;
+    public $groups = false;
+    public $readonly = true;
+    public $ready = false;
+    public $list_page = 1;
+    public $page_size = 10;
+    public $coltypes = array('name' => array('limit'=>1), 'firstname' => array('limit'=>1), 'surname' => array('limit'=>1), 'email' => array('limit'=>1));
+    
+    protected $error;
 
     /**
      * Save a search string for future listings
@@ -55,6 +64,16 @@ abstract class rcube_addressbook
     abstract function reset();
 
     /**
+     * Refresh saved search set after data has changed
+     *
+     * @return mixed New search set
+     */
+    function refresh_search()
+    {
+        return $this->get_search_set();
+    }
+
+    /**
      * List the current set of contact records
      *
      * @param  array  List of cols to show
@@ -69,9 +88,11 @@ abstract class rcube_addressbook
      * @param array   List of fields to search in
      * @param string  Search value
      * @param boolean True if results are requested, False if count only
-     * @return Indexed list of contact records and 'count' value
+     * @param boolean True to skip the count query (select only)
+     * @param array   List of fields that cannot be empty
+     * @return object rcube_result_set List of contact records and 'count' value
      */
-    abstract function search($fields, $value, $strict=false, $select=true);
+    abstract function search($fields, $value, $strict=false, $select=true, $nocount=false, $required=array());
 
     /**
      * Count number of available contacts in database
@@ -98,6 +119,27 @@ abstract class rcube_addressbook
     abstract function get_record($id, $assoc=false);
 
     /**
+     * Returns the last error occured (e.g. when updating/inserting failed)
+     *
+     * @return array Hash array with the following fields: type, message
+     */
+    function get_error()
+    {
+      return $this->error;
+    }
+    
+    /**
+     * Setter for errors for internal use
+     *
+     * @param int Error type (one of this class' error constants)
+     * @param string Error message (name of a text label)
+     */
+    protected function set_error($type, $message)
+    {
+      $this->error = array('type' => $type, 'message' => $message);
+    }
+
+    /**
      * Close connection to source
      * Called on script shutdown
      */
@@ -129,6 +171,8 @@ abstract class rcube_addressbook
      * Create a new contact record
      *
      * @param array Assoziative array with save data
+     *  Keys:   Field name with optional section in the form FIELD:SECTION
+     *  Values: Field value. Can be either a string or an array of strings for multiple values
      * @param boolean True to check for duplicates first
      * @return mixed The created record ID on success, False on error
      */
@@ -138,10 +182,31 @@ abstract class rcube_addressbook
     }
 
     /**
+     * Create new contact records for every item in the record set
+     *
+     * @param object rcube_result_set Recordset to insert
+     * @param boolean True to check for duplicates first
+     * @return array List of created record IDs
+     */
+    function insertMultiple($recset, $check=false)
+    {
+        $ids = array();
+        if (is_object($recset) && is_a($recset, rcube_result_set)) {
+            while ($row = $recset->next()) {
+                if ($insert = $this->insert($row, $check))
+                    $ids[] = $insert;
+            }
+        }
+        return $ids;
+    }
+
+    /**
      * Update a specific contact record
      *
      * @param mixed Record identifier
      * @param array Assoziative array with save data
+     *  Keys:   Field name with optional section in the form FIELD:SECTION
+     *  Values: Field value. Can be either a string or an array of strings for multiple values
      * @return boolean True on success, False on error
      */
     function update($id, $save_cols)
@@ -176,9 +241,10 @@ abstract class rcube_addressbook
     /**
      * List all active contact groups of this source
      *
+     * @param string  Optional search string to match group name
      * @return array  Indexed list of contact groups, each a hash array
      */
-    function list_groups()
+    function list_groups($search = null)
     {
         /* empty for address books don't supporting groups */
         return array();
@@ -260,5 +326,34 @@ abstract class rcube_addressbook
         /* empty for address books don't supporting groups */
         return array();
     }
+
+
+    /**
+     * Utility function to return all values of a certain data column
+     * either as flat list or grouped by subtype
+     *
+     * @param string Col name
+     * @param array  Record data array as used for saving
+     * @param boolean True to return one array with all values, False for hash array with values grouped by type
+     * @return array List of column values
+     */
+    function get_col_values($col, $data, $flat = false)
+    {
+        $out = array();
+        foreach ($data as $c => $values) {
+            if (strpos($c, $col) === 0) {
+                if ($flat) {
+                    $out = array_merge($out, (array)$values);
+                }
+                else {
+                    list($f, $type) = explode(':', $c);
+                    $out[$type] = array_merge((array)$out[$type], (array)$values);
+                }
+            }
+        }
+      
+        return $out;
+    }
+    
 }