Documentation

Turba_Driver_Imsp extends Turba_Driver
in package

Turba

Turba directory driver implementation for an IMSP server.

See the enclosed file LICENSE for license information (ASL). If you did did not receive this file, see http://www.horde.org/licenses/apache.

$alternativeName

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


    public
        string
    $alternativeName
     = \null

$approximate

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


    public
        array<string|int, mixed>
    $approximate
     = array()

$fields

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


    public
        array<string|int, mixed>
    $fields
     = array()

$listNameField

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


    public
        string
    $listNameField
     = \null

$map

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


    public
        array<string|int, mixed>
    $map
     = array()

$strict

Array of fields that must match exactly.


    public
        array<string|int, mixed>
    $strict
     = array()

$tabs

Hash with all tabs and their fields.


    public
        array<string|int, mixed>
    $tabs
     = array()

$title

The symbolic title of this source.


    public
        string
    $title

$_asMap

Mapping of Turba attributes to ActiveSync fields.


    protected
    static    array<string|int, mixed>
    $_asMap
     = array('name' => 'fileas', 'lastname' => 'lastname', 'firstname' => 'firstname', 'middlenames' => 'middlename', 'nickname' => 'nickname', 'namePrefix' => 'title', 'nameSuffix' => 'suffix', 'homeStreet' => 'homestreet', 'homeCity' => 'homecity', 'homeProvince' => 'homestate', 'homePostalCode' => 'homepostalcode', 'homeCountryFree' => 'homecountry', 'otherStreet' => 'otherstreet', 'otherCity' => 'othercity', 'otherProvince' => 'otherstate', 'otherPostalCode' => 'otherpostalcode', 'otherCountryFree' => 'othercountry', 'workStreet' => 'businessstreet', 'workCity' => 'businesscity', 'workProvince' => 'businessstate', 'workPostalCode' => 'businesspostalcode', 'workCountryFree' => 'businesscountry', 'title' => 'jobtitle', 'company' => 'companyname', 'department' => 'department', 'office' => 'officelocation', 'spouse' => 'spouse', 'website' => 'webpage', 'assistant' => 'assistantname', 'manager' => 'managername', 'yomifirstname' => 'yomifirstname', 'yomilastname' => 'yomilastname', 'imaddress' => 'imaddress', 'imaddress2' => 'imaddress2', 'imaddress3' => 'imaddress3', 'homePhone' => 'homephonenumber', 'homePhone2' => 'home2phonenumber', 'workPhone' => 'businessphonenumber', 'workPhone2' => 'business2phonenumber', 'fax' => 'businessfaxnumber', 'homeFax' => 'homefaxnumber', 'pager' => 'pagernumber', 'cellPhone' => 'mobilephonenumber', 'carPhone' => 'carphonenumber', 'assistPhone' => 'assistnamephonenumber', 'companyPhone' => 'companymainphone', 'radioPhone' => 'radiophonenumber')

$_authenticated

Holds if we are authenticated.


    protected
        bool
    $_authenticated
     = ''

$_bookName

The name of the addressbook.


    protected
        string
    $_bookName
     = ''

$_capabilities

Driver capabilities.


    protected
        array<string|int, mixed>
    $_capabilities
     = array('delete_all' => \true, 'delete_addressbook' => \true)

$_contact_owner

Hold the value for the owner of this address book.


    protected
        string
    $_contact_owner
     = ''

$_count

Number of contacts in this source.


    protected
        int
    $_count
     = \null

$_groupField

Holds name of the field indicating an IMSP group.


    protected
        string
    $_groupField
     = ''

$_groupValue

Holds value that $_groupField will have if entry is an IMSP group.


    protected
        string
    $_groupValue
     = ''

$_imsp

Horde_Imsp object


    protected
        Horde_Imsp
    $_imsp

$_name

The internal name of this source.


    protected
        string
    $_name

$_noGroups

Used to set if the current search is for contacts only.


    protected
        bool
    $_noGroups
     = ''

$_objectOptions

Any additional options passed to Turba_Object constructors.


    protected
        array<string|int, mixed>
    $_objectOptions
     = array()

$_params

Hash holding the driver's additional parameters.


    protected
        array<string|int, mixed>
    $_params
     = array()

__construct()

Constructs a new Turba imsp driver object.


    public
                    __construct([string $name = '' ][, array<string|int, mixed> $params = array() ]) : mixed

Parameters

$name : string = '': Source name
$params : array<string|int, mixed> = array(): Hash containing additional configuration parameters.

Return values

mixed —

_sendSearch()

Sends a search request to the server.


    public
                    _sendSearch(array<string|int, mixed> $criteria) : array<string|int, mixed>

Parameters

$criteria : array<string|int, mixed>: Array containing the search critera.

Return values

array<string|int, mixed> —

Array containing a list of names that match the search.

add()

Adds a new entry to the contact source.


    public
                    add(array<string|int, mixed> $attributes) : string

Parameters

$attributes : array<string|int, mixed>: The attributes of the new object to add.

Return values

string —

The new __key value on success.

canAdd()

Returns ability of the backend to add new contacts.


    public
                    canAdd() : bool

Return values

bool —

Can backend add?

checkDefaultShare()

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


    public
                    checkDefaultShare(mixed $share, mixed $srcConfig) : TODO

Parameters

$share : mixed: The share object.
$srcConfig : mixed

Return values

TODO —

count()

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


    public
                    count() : int

Return values

int —

The number of contacts that the user owns.

createShare()

Creates a new Horde_Share and creates the address book on the IMSP server.


    public
                    createShare(mixed $share_id, mixed $params) : Horde_Share

Parameters

$share_id : mixed
$params : mixed: The params for the share.

Return values

Horde_Share —

The share object.

delete()

Deletes the specified entry from the contact source.


    public
                    delete(string $object_id[, bool $remove_tags = true ]) : mixed

Parameters

$object_id : string: The ID of the object to delete.
$remove_tags : bool = true: Remove tags if true.

Return values

mixed —

deleteAll()

Deletes all contacts from an address book.


    public
                    deleteAll([string $sourceName = null ]) : mixed

Parameters

$sourceName : string = null: The identifier of the address book to delete. If omitted, will clear the current user's 'default' address book for this source type.

Return values

mixed —

fromASContact()

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


    public
                    fromASContact(Horde_ActiveSync_Message_Contact $message) : array<string|int, mixed>

Parameters

$message : Horde_ActiveSync_Message_Contact: The contact message object.

Return values

array<string|int, mixed> —

A contact hash.

getBlobs()

Returns the attributes that are blob types.


    public
                    getBlobs() : array<string|int, mixed>

Return values

array<string|int, mixed> —

List of blob attributes in the array keys.

getContactOwner()

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


    public
                    getContactOwner() : string

Return values

string —

Contact owner.

getCriteria()

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


    public
                    getCriteria() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An array containing the criteria.

getDateFields()

Returns the attributes that represent dates.


    public
                    getDateFields() : array<string|int, mixed>

Return values

array<string|int, mixed> —

List of date attributes in the array keys.

getFields()

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


    public
                    getFields() : array<string|int, mixed>

Return values

array<string|int, mixed> —

The field list.

getName()

Return the name of this address book.


    public
                    getName() : mixed

(This is the key into the cfgSources array)

Return values

mixed —

getObject()

Retrieves one object from the source.


    public
                    getObject(string $objectId) : Turba_Object

Parameters

$objectId : string: The unique id of the object to retrieve.

Return values

Turba_Object —

The retrieved object.

getObjects()

Retrieves a set of objects from the source.


    public
                    getObjects(array<string|int, mixed> $objectIds) : array<string|int, mixed>

Parameters

$objectIds : array<string|int, mixed>: The unique ids of the objects to retrieve.

Return values

array<string|int, mixed> —

The array of retrieved objects (Turba_Objects).

getParams()

Returns the current driver's additional parameters.


    public
                    getParams() : array<string|int, mixed>

Return values

array<string|int, mixed> —

Hash containing the driver's additional parameters.

getTimeObjectTurbaList()

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


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

Parameters

$start : Horde_Date: The starting date.
$end : Horde_Date: The ending date.
$field : string: The address book field containing the timeObject information (birthday, anniversary).

Return values

Turba_List —

A list of objects.

hasCapability()

Checks if this backend has a certain capability.


    public
                    hasCapability(string $capability) : bool

Parameters

$capability : string: The capability to check for.

Return values

bool —

Supported or not.

hasPermission()

Checks if the current user has the requested permission on this source.


    public
                    hasPermission(int $perm) : bool

Parameters

$perm : int: The permission to check for.

Return values

bool —

true if user has permission, false otherwise.

listTimeObjects()

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


    public
                    listTimeObjects(Horde_Date $start, Horde_Date $end, string $category) : array<string|int, mixed>

Parameters

$start : Horde_Date: The start date of the valid period.
$end : Horde_Date: The end date of the valid period.
$category : string: The timeObjects category to return.

Return values

array<string|int, mixed> —

A list of timeObject hashes.

makeSearch()

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.


    public
                    makeSearch(array<string|int, mixed> $criteria, string $search_type, array<string|int, mixed> $strict[, bool $match_begin = false ][, array<string|int, mixed> $custom_strict = array() ]) : array<string|int, mixed>

Parameters

$criteria : array<string|int, mixed>: Hash of criteria using Turba keys.
$search_type : string: OR search or AND search?
$strict : array<string|int, mixed>: Fields that must be matched exactly.
$match_begin : bool = false: Whether to match only at beginning of words.
$custom_strict : array<string|int, mixed> = array(): 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.

Return values

array<string|int, mixed> —

An array of search criteria.

removeUserData()

Remove all entries owned by the specified user.


    public
                    removeUserData(string $user) : mixed

Parameters

$user : string: The user's data to remove.

Return values

mixed —

save()

Modifies an existing entry in the contact source.


    public
                    save(Turba_Object $object) : string

Parameters

$object : Turba_Object: The object to update.

Return values

string —

The object id, possibly updated.

search()

Searches the source based on the provided criteria.


    public
                    search(array<string|int, mixed> $search_criteria[, string $sort_order = null ][, string $search_type = 'AND' ][, array<string|int, mixed> $return_fields = array() ][, array<string|int, mixed> $custom_strict = array() ][, bool $match_begin = false ][, bool $count_only = false ]) : mixed

Parameters

$search_criteria : array<string|int, mixed>: Hash containing the search criteria.
$sort_order : string = null: The requested sort order which is passed to Turba_List::sort().
$search_type : string = 'AND': Do an AND or an OR search (defaults to AND).
$return_fields : array<string|int, mixed> = array(): A list of fields to return; defaults to all fields.
$custom_strict : array<string|int, mixed> = array(): A list of fields that must match exactly.
$match_begin : bool = false: Whether to match only at beginning of words.
$count_only : bool = false: Only return the count of matching entries, not the entries themselves.

Return values

mixed —

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

searchDuplicates()

Searches the current address book for duplicate entries.


    public
                    searchDuplicates() : array<string|int, mixed>

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

Return values

array<string|int, mixed> —

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

setContactOwner()

Override the contactOwner setting for this driver.


    public
                    setContactOwner(string $owner) : mixed

Parameters

$owner : string: The contact owner.

Return values

mixed —

setDefaultShare()

Runs any actions after setting a new default tasklist.


    public
                    setDefaultShare(string $share) : mixed

Parameters

$share : string: The default share ID.

Return values

mixed —

setSourceName()

Override the name setting for this driver.


    public
                    setSourceName(string $name) : mixed

Parameters

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

Return values

mixed —

synchronize()

Synchronize, if needed.


    public
                    synchronize([mixed $token = false ]) : mixed

Parameters

$token : mixed = false: A value indicating the last synchronization point, if available.

Return values

mixed —

toASContact()

Convert the contact to an ActiveSync contact message


    public
                    toASContact(Turba_Object $object[, array<string|int, mixed> $options = array() ]) : Horde_ActiveSync_Message_Contact

Parameters

$object : Turba_Object

The turba object to convert

$options : array<string|int, mixed> = array()

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.

Return values

Horde_ActiveSync_Message_Contact —

toDriver()

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


    public
                    toDriver(string $attribute) : string

Parameters

$attribute : string: The Turba attribute to translate.

Return values

string —

The driver name for this attribute.

toDriverKeys()

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.


    public
                    toDriverKeys(array<string|int, mixed> $hash) : array<string|int, mixed>

Parameters

$hash : array<string|int, mixed>: Hash using Turba keys.

Return values

array<string|int, mixed> —

Translated version of $hash.

toHash()

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


    public
                    toHash(Horde_Icalendar_Vcard $vcard) : array<string|int, mixed>

Parameters

$vcard : Horde_Icalendar_Vcard: The Horde_Icalendar_Vcard object to parse.

Return values

array<string|int, mixed> —

A Turba attribute hash.

toTurbaKeys()

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.


    public
                    toTurbaKeys(array<string|int, mixed> $entry) : array<string|int, mixed>

Parameters

$entry : array<string|int, mixed>: A hash using driver-specific keys.

Return values

array<string|int, mixed> —

Translated version of $entry.

tovCard()

Exports a given Turba_Object as an iCalendar vCard.


    public
                    tovCard(Turba_Object $object[, string $version = '2.1' ][, array<string|int, mixed> $fields = null ][, bool $skipEmpty = false ]) : Horde_Icalendar_Vcard

Parameters

$object : Turba_Object: Turba_Object.
$version : string = '2.1': The vcard version to produce.
$fields : array<string|int, mixed> = null: Hash of field names and Horde_SyncMl_Property properties with the requested fields.
$skipEmpty : bool = false: Whether to skip empty fields.

Return values

Horde_Icalendar_Vcard —

A vcard object.

_aclToHordePerms()

Converts an acl string to a Horde Permissions bitmask.


    protected
                    _aclToHordePerms(string $acl) : int

Parameters

$acl : string: A standard, IMAP style acl string.

Return values

int —

Horde Permissions bitmask.

_add()

Adds the specified contact to the addressbook.


    protected
                    _add(array<string|int, mixed> $attributes[, array<string|int, mixed> $blob_fields = array() ][, array<string|int, mixed> $date_fields = array() ]) : mixed

Parameters

$attributes : array<string|int, mixed>: The attribute values of the contact.
$blob_fields : array<string|int, mixed> = array(): Fields that represent binary data.
$date_fields : array<string|int, mixed> = array(): Fields that represent dates. @since 4.2.0

Return values

mixed —

_canAdd()

TODO


    protected
                    _canAdd() : bool

Return values

bool —

Can backend add?

_countDelimiters()

Helper function to count the occurances of the ':' * delimiter in group member entries.


    protected
                    _countDelimiters(string $in) : int

Parameters

$in : string: The group member entry.

Return values

int —

The number of ':' in $in.

_delete()

Deletes the specified object from the IMSP server.


    protected
                    _delete(mixed $object_key, mixed $object_id) : mixed

Parameters

$object_key : mixed: TODO
$object_id : mixed: TODO

Return values

mixed —

_deleteAll()

Deletes the address book represented by this driver from the IMSP server.


    protected
                    _deleteAll() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An array of UIDs that have been deleted.

_doSearch()

Parses the search criteria, requests the individual searches from the server and performs any necessary ANDs / ORs on the results.


    protected
                    _doSearch(array<string|int, mixed> $criteria, string $glue) : array<string|int, mixed>

Parameters

$criteria : array<string|int, mixed>: Array containing the search criteria.
$glue : string: Type of search to perform (AND / OR).

Return values

array<string|int, mixed> —

Array containing contact names that match $criteria.

_filterTags()

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


    protected
                    _filterTags(array<string|int, mixed> $objects, array<string|int, mixed> $tags[, array<string|int, mixed> $sort_order = null ]) : Turba_List

Parameters

$objects : array<string|int, mixed>: A hash of objects, as returned by self::_search.
$tags : array<string|int, mixed>: An array of tags to filter by.
$sort_order : array<string|int, mixed> = null: The sort order to pass to Turba_List::sort.

Return values

Turba_List —

The filtered Turba_List object.

_getContactOwner()

Returns the owner for this contact. For an IMSP source, this should be the name of the address book.


    protected
                    _getContactOwner() : string

Return values

string —

TODO

_getDuplicated()

Returns only those names that are duplicated in $names


    protected
                    _getDuplicated(array<string|int, mixed> $names) : array<string|int, mixed>

Parameters

$names : array<string|int, mixed>: A nested array of arrays containing names

Return values

array<string|int, mixed> —

Array containing the 'AND' of all arrays in $names

_getGroupEmails()

Parses out $emailText into an array of pure email addresses suitable for searching the IMSP datastore with.


    protected
                    _getGroupEmails(string $emailText) : array<string|int, mixed>

Parameters

$emailText : string: Single string containing email addressses.

Return values

array<string|int, mixed> —

Pure email address.

_getTimeObjectTurbaListFallback()

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


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

Parameters

$start : Horde_Date: The starting date.
$end : Horde_Date: The ending date.
$field : string: The address book field containing the timeObject information (birthday, anniversary).

Return values

Turba_List —

A list of objects.

_guessName()

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


    protected
                    _guessName(array<string|int, mixed> &$hash) : mixed

Parameters

$hash : array<string|int, mixed>: The attributes array.

Return values

mixed —

_hasValEnum()

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


    protected
                    _hasValEnum(array<string|int, mixed> $valEnum, string $type) : bool

Parameters

$valEnum : array<string|int, mixed>: A ValEnum hash.
$type : string: A requested attribute type.

Return values

bool —

True if $type exists in $valEnum.

_init()

Initialize the driver.


    protected
                    _init() : mixed

Return values

mixed —

_makeKey()

Create an object key for a new object.


    protected
                    _makeKey(array<string|int, mixed> $attributes) : string

Parameters

$attributes : array<string|int, mixed>: The attributes (in driver keys) of the object being added.

Return values

string —

A unique ID for the new object.

_makeUid()

Creates an object UID for a new object.


    protected
                    _makeUid() : string

Return values

string —

A unique ID for the new object.

_parseName()

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


    protected
                    _parseName(array<string|int, mixed> $hash) : array<string|int, mixed>

Parameters

$hash : array<string|int, mixed>: A hash of turba attributes.

Return values

array<string|int, mixed> —

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

_read()

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


    protected
                    _read(string $key, mixed $ids, string $owner, array<string|int, mixed> $fields[, array<string|int, mixed> $blobFields = array() ]) : array<string|int, mixed>

Parameters

$key : string: The primary key field to use (always 'name' for IMSP).
$ids : mixed: The ids of the contacts to load.
$owner : string: Only return contacts owned by this user.
$fields : array<string|int, mixed>: List of fields to return.
$blobFields : array<string|int, mixed> = array(): Array of fields containing binary data.

Return values

array<string|int, mixed> —

Hash containing the search results.

_removeDuplicated()

Returns an array with all duplicate names removed.


    protected
                    _removeDuplicated(array<string|int, mixed> $names) : array<string|int, mixed>

Parameters

$names : array<string|int, mixed>: Nested array of arrays containing names.

Return values

array<string|int, mixed> —

Array containg the 'OR' of all arrays in $names.

_save()

Saves the specified object to the IMSP server.


    protected
                    _save(Turba_Object $object) : string

Parameters

$object : Turba_Object: The object to save/update.

Return values

string —

The object id, possibly updated.

_search()

Returns all entries matching $critera.


    protected
                    _search(array<string|int, mixed> $criteria, array<string|int, mixed> $fields[, array<string|int, mixed> $blobFields = array() ][, mixed $count_only = false ]) : array<string|int, mixed>

Parameters

$criteria : array<string|int, mixed>: Array containing the search criteria.
$fields : array<string|int, mixed>: List of fields to return.
$blobFields : array<string|int, mixed> = array(): Array of fields containing binary data.
$count_only : mixed = false: Only return the count of matching entries, not the entries themselves.

Return values

array<string|int, mixed> —

Hash containing the search results.

_toTurbaObjects()

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


    protected
                    _toTurbaObjects(array<string|int, mixed> $objects[, array<string|int, mixed> $sort_order = null ]) : Turba_List

Parameters

$objects : array<string|int, mixed>

An array of object hashes (keyed to backend).

$sort_order : array<string|int, mixed> = null

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

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

Return values

Turba_List —

A list object.

Turba_Driver_Imsp extends Turba_Driver in package Turba

Tags

Table of Contents

Properties

$alternativeName

$approximate

$fields

$listNameField

$map

$strict

$tabs

$title

$_asMap

$_authenticated

$_bookName

$_capabilities

$_contact_owner

$_count

$_groupField

$_groupValue

$_imsp

$_name

$_noGroups

$_objectOptions

$_params

Methods

__construct()

Parameters

Return values

_sendSearch()

Parameters

Return values

add()

Parameters

Tags

Return values

canAdd()

Return values

checkDefaultShare()

Parameters

Tags

Return values

count()

Tags

Return values

createShare()

Parameters

Tags

Return values

delete()

Parameters

Tags

Return values

deleteAll()

Parameters

Tags

Return values

fromASContact()

Parameters

Return values

getBlobs()

Return values

getContactOwner()

Return values

getCriteria()

Return values

getDateFields()

Tags

Return values

getFields()

Return values

getName()

Tags

Return values

getObject()

Parameters

Tags

Return values

getObjects()

Parameters

Turba_Driver_Imsp extends Turba_Driver
in package

Turba