+ /* empty for read-only address books */
+ }
+
+ /**
+ * Setter for the current group
+ * (empty, has to be re-implemented by extending class)
+ */
+ function set_group($gid) { }
+
+ /**
+ * 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($search = null)
+ {
+ /* empty for address books don't supporting groups */
+ return array();
+ }
+
+ /**
+ * Get group properties such as name and email address(es)
+ *
+ * @param string Group identifier
+ * @return array Group properties as hash array
+ */
+ function get_group($group_id)
+ {
+ /* empty for address books don't supporting groups */
+ return null;
+ }
+
+ /**
+ * Create a contact group with the given name
+ *
+ * @param string The group name
+ * @return mixed False on error, array with record props in success
+ */
+ function create_group($name)
+ {
+ /* empty for address books don't supporting groups */
+ return false;
+ }
+
+ /**
+ * Delete the given group and all linked group members
+ *
+ * @param string Group identifier
+ * @return boolean True on success, false if no data was changed
+ */
+ function delete_group($gid)
+ {
+ /* empty for address books don't supporting groups */
+ return false;
+ }
+
+ /**
+ * Rename a specific contact group
+ *
+ * @param string Group identifier
+ * @param string New name to set for this group
+ * @param string New group identifier (if changed, otherwise don't set)
+ * @return boolean New name on success, false if no data was changed
+ */
+ function rename_group($gid, $newname, &$newid)
+ {
+ /* empty for address books don't supporting groups */
+ return false;
+ }
+
+ /**
+ * Add the given contact records the a certain group
+ *
+ * @param string Group identifier
+ * @param array List of contact identifiers to be added
+ * @return int Number of contacts added
+ */
+ function add_to_group($group_id, $ids)
+ {
+ /* empty for address books don't supporting groups */
+ return 0;
+ }
+
+ /**
+ * Remove the given contact records from a certain group
+ *
+ * @param string Group identifier
+ * @param array List of contact identifiers to be removed
+ * @return int Number of deleted group members
+ */
+ function remove_from_group($group_id, $ids)
+ {
+ /* empty for address books don't supporting groups */
+ return 0;
+ }
+
+ /**
+ * Get group assignments of a specific contact record
+ *
+ * @param mixed Record identifier
+ *
+ * @return array List of assigned groups as ID=>Name pairs
+ * @since 0.5-beta
+ */
+ function get_record_groups($id)
+ {
+ /* 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 ($c === $col || 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;
+ }
+
+
+ /**
+ * Normalize the given string for fulltext search.
+ * Currently only optimized for Latin-1 characters; to be extended
+ *
+ * @param string Input string (UTF-8)
+ * @return string Normalized string
+ */
+ protected static function normalize_string($str)
+ {
+ // split by words
+ $arr = explode(" ", preg_replace(
+ array('/[\s;\+\-\/]+/i', '/(\d)[-.\s]+(\d)/', '/\s\w{1,3}\s/'),
+ array(' ', '\\1\\2', ' '),
+ $str));
+
+ foreach ($arr as $i => $part) {
+ if (utf8_encode(utf8_decode($part)) == $part) { // is latin-1 ?
+ $arr[$i] = utf8_encode(strtr(strtolower(strtr(utf8_decode($part),
+ 'ÇçäâàåéêëèïîìÅÉöôòüûùÿøØáíóúñÑÁÂÀãÃÊËÈÍÎÏÓÔõÕÚÛÙýÝ',
+ 'ccaaaaeeeeiiiaeooouuuyooaiounnaaaaaeeeiiioooouuuyy')),
+ array('ß' => 'ss', 'ae' => 'a', 'oe' => 'o', 'ue' => 'u')));
+ }
+ else
+ $arr[$i] = mb_strtolower($part);
+ }
+
+ return join(" ", $arr);
+ }
+
+
+ /**
+ * Compose a valid display name from the given structured contact data
+ *
+ * @param array Hash array with contact data as key-value pairs
+ * @param bool The name will be used on the list
+ *
+ * @return string Display name
+ */
+ public static function compose_display_name($contact, $list_mode = false)
+ {
+ $contact = rcmail::get_instance()->plugins->exec_hook('contact_displayname', $contact);
+ $fn = $contact['name'];
+
+ if (!$fn)
+ $fn = join(' ', array_filter(array($contact['prefix'], $contact['firstname'], $contact['middlename'], $contact['surname'], $contact['suffix'])));
+
+ // use email address part for name
+ $email = is_array($contact['email']) ? $contact['email'][0] : $contact['email'];
+
+ if ($email && (empty($fn) || $fn == $email)) {
+ // Use full email address on contacts list
+ if ($list_mode)
+ return $email;
+
+ list($emailname) = explode('@', $email);
+ if (preg_match('/(.*)[\.\-\_](.*)/', $emailname, $match))
+ $fn = trim(ucfirst($match[1]).' '.ucfirst($match[2]));
+ else
+ $fn = ucfirst($emailname);
+ }
+
+ return $fn;