Properties

$title

$title : string

The symbolic title of this source.

Type

string

$map

$map : array

Hash describing the mapping between Turba attributes and driver-specific fields.

Type

array

$tabs

$tabs : array

Hash with all tabs and their fields.

Type

array

$fields

$fields : array

List of all fields that can be accessed in the backend (excludes composite attributes, etc.).

Type

array

$strict

$strict : array

Array of fields that must match exactly.

Type

array

$approximate

$approximate : array

Array of fields to search "approximately" (@see config/backends.php).

Type

array

$listNameField

$listNameField : string

The name of a field to store contact list names in if not the default.

Type

string

$alternativeName

$alternativeName : string

The name of a field to use as an alternative to the name field if that one is empty.

Type

string

$_name

$_name : string

The internal name of this source.

Type

string

$_params

$_params : array

Hash holding the driver's additional parameters.

Type

array

$_capabilities

$_capabilities : array

What can this backend do?

Type

array

$_objectOptions

$_objectOptions : array

Any additional options passed to Turba_Object constructors.

Type

array

$_count

$_count : integer

Number of contacts in this source.

Type

integer

$_contact_owner

$_contact_owner : string

Hold the value for the owner of this address book.

Type

string

$_asMap

$_asMap : array

Mapping of Turba attributes to ActiveSync fields.

Type

array

Methods

__construct()

__construct(string  $name = '', array  $params = array()) 

Constructor function.

Parameters

string $name

Source name

array $params

Hash containing additional configuration parameters.

getParams()

getParams() : array

Returns the current driver's additional parameters.

Returns

array —

Hash containing the driver's additional parameters.

hasCapability()

hasCapability(string  $capability) : boolean

Checks if this backend has a certain capability.

Parameters

string $capability

The capability to check for.

Returns

boolean —

Supported or not.

getBlobs()

getBlobs() : array

Returns the attributes that are blob types.

Returns

array —

List of blob attributes in the array keys.

getDateFields()

getDateFields() : array

Returns the attributes that represent dates.

Returns

array —

List of date attributes in the array keys.

toDriverKeys()

toDriverKeys(array  $hash) : array

Translates the keys of the first hash from the generalized Turba attributes to the driver-specific fields. The translation is based on the contents of $this->map.

Parameters

array $hash

Hash using Turba keys.

Returns

array —

Translated version of $hash.

makeSearch()

makeSearch(array  $criteria, string  $search_type, array  $strict, boolean  $match_begin = false, array  $custom_strict = array()) : array

Takes a hash of Turba key => search value and return a (possibly nested) array, using backend attribute names, that can be turned into a search by the driver. The translation is based on the contents of $this->map, and includes nested OR searches for composite fields.

Parameters

array $criteria

Hash of criteria using Turba keys.

string $search_type

OR search or AND search?

array $strict

Fields that must be matched exactly.

boolean $match_begin

Whether to match only at beginning of words.

array $custom_strict

Custom set of fields that are to matched exactly, but are glued using $search_type and 'AND' together with $strict fields. Allows an 'OR' search pm a custom set of $strict fields.

Returns

array —

An array of search criteria.

toDriver()

toDriver(string  $attribute) : string

Translates a single Turba attribute to the driver-specific counterpart. The translation is based on the contents of $this->map. This ignores composite fields.

Parameters

string $attribute

The Turba attribute to translate.

Returns

string —

The driver name for this attribute.

toTurbaKeys()

toTurbaKeys(array  $entry) : array

Translates a hash from being keyed on driver-specific fields to being keyed on the generalized Turba attributes. The translation is based on the contents of $this->map.

Parameters

array $entry

A hash using driver-specific keys.

Returns

array —

Translated version of $entry.

search()

search(array  $search_criteria, string  $sort_order = null, string  $search_type = 'AND', array  $return_fields = array(), array  $custom_strict = array(), boolean  $match_begin = false, boolean  $count_only = false) : mixed

Searches the source based on the provided criteria.

Parameters

array $search_criteria

Hash containing the search criteria.

string $sort_order

The requested sort order which is passed to Turba_List::sort().

string $search_type

Do an AND or an OR search (defaults to AND).

array $return_fields

A list of fields to return; defaults to all fields.

array $custom_strict

A list of fields that must match exactly.

boolean $match_begin

Whether to match only at beginning of words.

boolean $count_only

Only return the count of matching entries, not the entries themselves.

Throws

\Turba_Exception

Returns

mixed —

Turba_List|integer The sorted, filtered list of search results or the number of matching entries (if $count_only is true).

searchDuplicates()

searchDuplicates() : array

Searches the current address book for duplicate entries.

Duplicates are determined by comparing email and name or last name and first name values.

Throws

\Turba_Exception

Returns

array —

A hash with the following format: array('name' => array('John Doe' => Turba_List, ...), ...)

listTimeObjects()

listTimeObjects(\Horde_Date  $start, \Horde_Date  $end, string  $category) : array

Returns a list of birthday or anniversary hashes from this source for a certain period.

Parameters

\Horde_Date $start

The start date of the valid period.

\Horde_Date $end

The end date of the valid period.

string $category

The timeObjects category to return.

Throws

\Turba

Exception

Returns

array —

A list of timeObject hashes.

getTimeObjectTurbaList()

getTimeObjectTurbaList(\Horde_Date  $start, \Horde_Date  $end, string  $field) : \Turba_List

Default implementation for obtaining a Turba_List to get TimeObjects out of.

Parameters

\Horde_Date $start

The starting date.

\Horde_Date $end

The ending date.

string $field

The address book field containing the timeObject information (birthday, anniversary).

Throws

\Turba_Exception

Returns

\Turba_List

A list of objects.

getObjects()

getObjects(array  $objectIds) : array

Retrieves a set of objects from the source.

Parameters

array $objectIds

The unique ids of the objects to retrieve.

Throws

\Turba_Exception
\Horde_Exception_NotFound

Returns

array —

The array of retrieved objects (Turba_Objects).

getObject()

getObject(string  $objectId) : \Turba_Object

Retrieves one object from the source.

Parameters

string $objectId

The unique id of the object to retrieve.

Throws

\Turba_Exception
\Horde_Exception_NotFound

Returns

\Turba_Object

The retrieved object.

add()

add(array  $attributes) : string

Adds a new entry to the contact source.

Parameters

array $attributes

The attributes of the new object to add.

Throws

\Turba_Exception

Returns

string —

The new __key value on success.

canAdd()

canAdd() : boolean

Returns ability of the backend to add new contacts.

Returns

boolean —

Can backend add?

delete()

delete(string  $object_id, boolean  $remove_tags = true) 

Deletes the specified entry from the contact source.

Parameters

string $object_id

The ID of the object to delete.

boolean $remove_tags

Remove tags if true.

Throws

\Turba_Exception
\Horde_Exception_NotFound

deleteAll()

deleteAll(string  $sourceName = null) 

Deletes all contacts from an address book.

Parameters

string $sourceName

The identifier of the address book to delete. If omitted, will clear the current user's 'default' address book for this source type.

Throws

\Turba_Exception

save()

save(\Turba_Object  $object) : string

Modifies an existing entry in the contact source.

Parameters

\Turba_Object $object

The object to update.

Throws

\Turba_Exception

Returns

string —

The object id, possibly updated.

getCriteria()

getCriteria() : array

Returns the criteria available for this source except '__key'.

Returns

array —

An array containing the criteria.

getFields()

getFields() : array

Returns all non-composite fields for this source. Useful for importing and exporting data, etc.

Returns

array —

The field list.

tovCard()

tovCard(\Turba_Object  $object, string  $version = '2.1', array  $fields = null, boolean  $skipEmpty = false) : \Horde_Icalendar_Vcard

Exports a given Turba_Object as an iCalendar vCard.

Parameters

\Turba_Object $object

Turba_Object.

string $version

The vcard version to produce.

array $fields

Hash of field names and Horde_SyncMl_Property properties with the requested fields.

boolean $skipEmpty

Whether to skip empty fields.

Returns

\Horde_Icalendar_Vcard —

A vcard object.

toHash()

toHash(\Horde_Icalendar_Vcard  $vcard) : array

Function to convert a Horde_Icalendar_Vcard object into a Turba Object Hash with Turba attributes suitable as a parameter for add().

Parameters

\Horde_Icalendar_Vcard $vcard

The Horde_Icalendar_Vcard object to parse.

Returns

array —

A Turba attribute hash.

toASContact()

toASContact(\Turba_Object  $object, array  $options = array()) : \Horde_ActiveSync_Message_Contact

Convert the contact to an ActiveSync contact message

Parameters

\Turba_Object $object

The turba object to convert

array $options

Options:

  • protocolversion: (float) The EAS version to support DEFAULT: 2.5
  • bodyprefs: (array) A BODYPREFERENCE array. DEFAULT: none (No body prefs enforced).
  • truncation: (integer) Truncate event body to this length DEFAULT: none (No truncation).
  • device: (Horde_ActiveSync_Device) The device object.

Returns

\Horde_ActiveSync_Message_Contact

fromASContact()

fromASContact(\Horde_ActiveSync_Message_Contact  $message) : array

Convert an ActiveSync contact message into a hash suitable for importing via self::add().

Parameters

\Horde_ActiveSync_Message_Contact $message

The contact message object.

Returns

array —

A contact hash.

hasPermission()

hasPermission(integer  $perm) : boolean

Checks if the current user has the requested permissions on this source. This source is always read only.

Parameters

integer $perm

The permission to check for.

Returns

boolean —

True if the user has permission, otherwise false.

getName()

getName() 

Return the name of this address book.

(This is the key into the cfgSources array)

getContactOwner()

getContactOwner() : string

Return the owner to use when searching or creating contacts in this address book.

Returns

string —

Contact owner.

setContactOwner()

setContactOwner(string  $owner) 

Override the contactOwner setting for this driver.

Parameters

string $owner

The contact owner.

setSourceName()

setSourceName(string  $name) 

Override the name setting for this driver.

Parameters

string $name

The source name. This is the key into the $cfgSources array.

createShare()

createShare(string  $share_name, array  $params) : \Horde_Share

Creates a new Horde_Share for this source type.

Parameters

string $share_name

The share name

array $params

The params for the share.

Returns

\Horde_Share —

The share object.

setDefaultShare()

setDefaultShare(string  $share) 

Runs any actions after setting a new default tasklist.

Parameters

string $share

The default share ID.

removeUserData()

removeUserData(string  $user) 

Remove all entries owned by the specified user.

Parameters

string $user

The user's data to remove.

Throws

\Turba_Exception

checkDefaultShare()

checkDefaultShare(\Horde_Share_Object  $share, array  $srcconfig) : boolean

Check if the passed in share is the default share for this source.

Parameters

\Horde_Share_Object $share

The share object.

array $srcconfig

The cfgSource entry for the share.

Returns

boolean —

TODO

count()

count() : integer

Returns the number of contacts of the current user in this address book.

Throws

\Turba_Exception

Returns

integer —

The number of contacts that the user owns.

synchronize()

synchronize(mixed  $token = false) 

Synchronize, if needed.

Parameters

mixed $token

A value indicating the last synchronization point, if available.

_filterTags()

_filterTags(array  $objects, array  $tags, Array  $sort_order = null) : \Turba_List

Returns a Turba_List object containing $objects filtered by $tags.

Parameters

array $objects

A hash of objects, as returned by self::_search.

array $tags

An array of tags to filter by.

Array $sort_order

The sort order to pass to Turba_List::sort.

Returns

\Turba_List

The filtered Turba_List object.

_toTurbaObjects()

_toTurbaObjects(array  $objects, array  $sort_order = null) : \Turba_List

Takes an array of object hashes and returns a Turba_List containing the correct Turba_Objects

Parameters

array $objects

An array of object hashes (keyed to backend).

array $sort_order

Array of hashes describing sort fields. Each hash has the following fields:

ascending - (boolean) Indicating sort direction.
field - (string) Sort field.

Returns

\Turba_List

A list object.

_getTimeObjectTurbaListFallback()

_getTimeObjectTurbaListFallback(\Horde_Date  $start, \Horde_Date  $end, string  $field) : \Turba_List

Default implementation for obtaining a Turba_List to get TimeObjects out of.

Parameters

\Horde_Date $start

The starting date.

\Horde_Date $end

The ending date.

string $field

The address book field containing the timeObject information (birthday, anniversary).

Throws

\Turba_Exception

Returns

\Turba_List

A list of objects.

_canAdd()

_canAdd() : boolean

Returns ability of the backend to add new contacts.

Returns

boolean —

Can backend add?

_deleteAll()

_deleteAll() : array

Deletes all contacts from an address book.

Throws

\Turba_Exception

Returns

array —

An array of UIDs that have been deleted.

_hasValEnum()

_hasValEnum(array  $valEnum, string  $type) : boolean

Returns whether a ValEnum entry from a DevInf object contains a certain type.

Parameters

array $valEnum

A ValEnum hash.

string $type

A requested attribute type.

Returns

boolean —

True if $type exists in $valEnum.

_parseName()

_parseName(array  $hash) : array

Checks $hash for the presence of a 'name' attribute. If not found, attempt to build one from other available values.

Parameters

array $hash

A hash of turba attributes.

Returns

array —

Hash of Turba attributes, with the 'name' attribute populated.

_getContactOwner()

_getContactOwner() : string

Return the owner to use when searching or creating contacts in this address book.

Returns

string —

Contact owner.

_makeKey()

_makeKey(array  $attributes) : string

Creates an object key for a new object.

Parameters

array $attributes

The attributes (in driver keys) of the object being added.

Returns

string —

A unique ID for the new object.

_makeUid()

_makeUid() : string

Creates an object UID for a new object.

Returns

string —

A unique ID for the new object.

_init()

_init() 

Initialize the driver.

Throws

\Turba_Exception

_search()

_search(array  $criteria, array  $fields, array  $blobFields = array(), boolean  $count_only = false) : array

Searches the group list with the given criteria and returns a filtered list of results. If the criteria parameter is an empty array, all records will be returned.

This method 'borrowed' from the favorites driver.

Parameters

array $criteria

Array containing the search criteria.

array $fields

List of fields to return.

array $blobFields

A list of fields that contain binary data.

boolean $count_only

Only return the count of matching entries, not the entries themselves.

Throws

\Turba_Exception

Returns

array —

Hash containing the search results.

_read()

_read(string  $key, mixed  $ids, string  $owner, array  $fields, array  $blobFields = array(), array  $dateFields = array()) : array

Reads the given data from the address book and returns the results.

Parameters

string $key

The primary key field to use.

mixed $ids

The ids of the contacts to load.

string $owner

Only return contacts owned by this user.

array $fields

List of fields to return.

array $blobFields

Array of fields containing binary data.

array $dateFields

Array of fields containing date data. @since 4.2.0

Throws

\Turba_Exception

Returns

array —

Hash containing the search results.

_add()

_add(array  $attributes, array  $blob_fields = array(), array  $date_fields = array()) 

Adds the specified contact to the addressbook.

Parameters

array $attributes

The attribute values of the contact.

array $blob_fields

Fields that represent binary data.

array $date_fields

Fields that represent dates. @since 4.2.0

Throws

\Turba_Exception

_delete()

_delete(string  $object_key, string  $object_id) 

Deletes the specified contact from the addressbook.

Parameters

string $object_key

TODO

string $object_id

TODO

Throws

\Turba_Exception

_save()

_save(\Turba_Object  $object) : string

Saves the specified object in the SQL database.

Parameters

\Turba_Object $object

The object to save

Throws

\Turba_Exception

Returns

string —

The object id, possibly updated.

_guessName()

_guessName(array  $hash) 

Helper function for guessing name parts from a single name string.

Parameters

array $hash

The attributes array.

_getAddressBook()

_getAddressBook() 

TODO