Properties

$_links

$_links : array

Links.

Type

array

$_noPerms

$_noPerms : array

The listing of API calls that do not require permissions checking.

Type

array

Methods

commentCallback()

commentCallback(integer  $id) : mixed

Callback for comment API.

Parameters

integer $id

Internal data identifier.

Returns

mixed —

Name of object on success, false on failure.

hasComments()

hasComments() : boolean

Does this API allow comments?

Returns

boolean —

True if API allows comments.

sources()

sources(boolean  $writeable = false, boolean  $sync_only = false) : array

Returns a list of available sources.

Parameters

boolean $writeable

If true, limits to writeable sources.

boolean $sync_only

Only include synchable address books.

Returns

array —

An array of the available sources. Keys are source IDs, values are source titles.

fields()

fields(string  $source = null) : array

Returns a list of fields avaiable in a source.

Parameters

string $source

The source name.

Throws

\Turba_Exception

Returns

array —

An array describing the fields. Keys are the field name, values are arrays with these keys:

  • name: (string) Field name.
  • label: (string) Field label.
  • search: (boolean) Can this field be searched?
  • type: (string) See turba/config/attributes.php.

getDefaultShare()

getDefaultShare() : string

Retrieve the UID for the current user's default Turba share.

Returns

string —

UID.

getGalUid()

getGalUid() : string|boolean

Retrieve the UID for the Global Address List source.

Returns

string|boolean —

The UID or false if none configured.

browse()

browse(string  $path = '', array  $properties = array('name', 'icon', 'browseable')) : array

Browses through Turba's object tree.

Parameters

string $path

The path of the tree to browse.

array $properties

The item properties to return. Defaults to 'name', 'icon', and 'browseable'.

Throws

\Turba_Exception
\Horde_Exception_NotFound

Returns

array —

Content of the specified path.

path_delete()

path_delete(string  $path) : string

Deletes a file from the Turba tree.

Parameters

string $path

The path to the file.

Throws

\Turba_Exception

Returns

string —

The event's UID.

listUids()

listUids(string|array  $sources = null) : array

Returns an array of UIDs for all contacts that the current user is authorized to see.

Parameters

string|array $sources

The name(s) of the source(s) to return contacts of. If empty, the current user's sync sources or default source are used.

Throws

\Turba_Exception

Returns

array —

An array of UIDs for all contacts the user can access.

listBy()

listBy(string  $action, integer  $timestamp, string|array  $sources = null, integer  $end = null, boolean  $isModSeq = false) : array

Returns an array of UIDs for contacts that have had a given action since a certain time.

Parameters

string $action

The action to check for - add, modify, or delete.

integer $timestamp

The time to start the search.

string|array $sources

The source(s) for which to retrieve the history.

integer $end

The optional ending timestamp.

boolean $isModSeq

If true, $timestamp and $end are modification sequences and not timestamps. @since 4.1.1

Throws

\Turba_Exception

Returns

array —

An array of UIDs matching the action and time criteria.

getChanges()

getChanges(integer  $start, integer  $end, boolean  $isModSeq = false, string|array  $sources = null) : array

Method for obtaining all server changes between two timestamps.

Essentially a wrapper around listBy(), but returns an array containing all adds, edits, and deletions.

Parameters

integer $start

The starting timestamp

integer $end

The ending timestamp.

boolean $isModSeq

If true, $start and $end are modification sequences and not timestamps. @since 4.1.1

string|array $sources

The sources to check. @since 4.2.0

Returns

array —

A hash with 'add', 'modify' and 'delete' arrays.

getChangesByModSeq()

getChangesByModSeq(integer  $start, integer  $end, string|array  $sources = null) : array

Return all changes occuring between the specified modification sequences.

Parameters

integer $start

The starting modseq.

integer $end

The ending modseq.

string|array $sources

The sources to check. @since 4.2.0

Returns

array —

The changes @see getChanges()

getActionTimestamp()

getActionTimestamp(string  $uid, string  $action, string|array  $sources = null, boolean  $modSeq = false) : integer

Returns the timestamp of an operation for a given UID and action.

Parameters

string $uid

The UID to look for.

string $action

The action to check for - add, modify, or delete.

string|array $sources

The source(s) for which to retrieve the history.

boolean $modSeq

Request a modification sequence instead of timestamp. @since 4.1.1

Throws

\Turba_Exception

Returns

integer —

The timestamp for this action.

getHighestModSeq()

getHighestModSeq(string  $id = null) : integer

Return the largest modification sequence from the history backend.

Parameters

string $id

Addressbook id to return highest MODSEQ for. If null, the highest MODSEQ across all addressbooks is returned. @since 4.2.0

Returns

integer —

The modseq.

import()

import(string  $content, string  $contentType = 'array', string  $source = null, array  $options = array()) : string

Import a contact represented in the specified contentType.

Parameters

string $content

The content of the contact.

string $contentType

What format is the data in? Currently supports array, text/directory, text/vcard, text/x-vcard, and activesync.

string $source

The source into which the contact will be imported.

array $options

Additional options:

  • match_on_email: (boolean) If true, will detect entry as duplicate if ANY email field matches. Useful for automatically adding contacts from an email application, such as IMP. @since 4.2.9

Throws

\Turba_Exception
\Turba_Exception_ObjectExists

Returns

string —

The new UID.

addGroup()

addGroup(string  $name, array  $members, array  $opts = array()) : array

Adds a group (and its members) to the source provided.

Parameters

string $name

Group name.

array $members

An array of members to add to the group. Format is the same as the 'array' argument to the import() API function.

array $opts

Additional options:

  - attr: (array) Additional attributes to add to group.
  - source: (string) Source to import contacts to.

Throws

\Turba_Exception

Returns

array —

An array with the following keys:

  - added: (integer) The number of addresses added to the group.
  - uid: (string) The uid of the group object.

export()

export(string  $uid, mixed  $contentType, string|array  $sources = null, array  $fields = null, array  $options = array()) : mixed

Export a contact, identified by UID, in the requested contentType.

Parameters

string $uid

Identify the contact to export.

mixed $contentType

What format should the data be in?

  • text/directory: Returns RFC2426 vcard3.0
  • text/vcard: Returns RFC2426 vcard3.0
  • text/x-vcard: Returns imc.org vcard 2.1 format.
  • array: Returns a raw array
  • activesync: Returns a Horde_ActiveSync_Message_Contact:: object
string|array $sources

The source(s) from which the contact will be exported.

array $fields

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

array $options

Any additional options to be passed to the exporter. Currently supported:

  • skip_empty: (boolean) {text/vcard or text/x-vcard} Set to true to not output empty properties. DEFAULT: false.
  • protocolversion: (float) {activesync} The EAS version to support DEFAULT: 2.5
  • bodyprefs: (array) {activesync} A BODYPREFERENCE array. DEFAULT: none (No body prefs enforced).
  • truncation: (integer) {activesync} Truncate event body to this length. DEFAULT: none (No truncation).

Throws

\Turba_Exception

Returns

mixed —

The requested data.

ownVCard()

ownVCard() : string

Exports the user's own contact as a vCard string.

Throws

\Turba_Exception

Returns

string —

The requested vCard data.

ownContact()

ownContact() : array

Export the user's own contact as a hash.

Throws

\Turba_Exception

Returns

array —

The contact hash.

getOwnContactObject()

getOwnContactObject() : array

Helper function to return the user's own contact object

Throws

\Turba_Exception

Returns

array —

An array containing the following keys:

  • contact: (Turba_Object) Object representing the user's own contact.
  • source: (string) The source of the user's own contact.

delete()

delete(string|array  $uid, string|array  $sources = null) : boolean

Deletes a contact identified by UID.

Parameters

string|array $uid

Identify the contact to delete, either a single UID or an array.

string|array $sources

The source(s) from which the contact will be deleted.

Throws

\Turba_Exception

Returns

boolean —

Success or failure.

replace()

replace(string  $uid, mixed  $content, string  $contentType, string|array  $sources = null) : boolean

Replaces the contact identified by UID with the content represented in the specified contentType.

Parameters

string $uid

Idenfity the contact to replace.

mixed $content

The content of the contact.

string $contentType

What format is the data in? Currently supports array, text/directory, text/vcard, text/x-vcard and activesync.

string|array $sources

The source(s) where the contact will be replaced.

Throws

\Turba_Exception

Returns

boolean —

Success or failure.

search()

search(mixed  $names = null, array  $opts = array()) : mixed

Returns a contact search result.

Parameters

mixed $names

The search filter values.

array $opts

Optional parameters:

  • customStrict: (array) An array of fields that must match exactly. DEFAULT: None
  • fields: (array) The fields to search on. DEFAULT: Search all configured search fields.
  • forceSource: (boolean) Whether to use the specified sources, even if they have been disabled in the preferences? DEFAULT: false
  • matchBegin: (boolean) Match word boundaries only? DEFAULT: false
  • returnFields: Only return these fields. Note that the __key field will always be returned. DEFAULT: Return all fields.
  • rfc822Return: Return a Horde_Mail_Rfc822_List object. DEFAULT: Returns an array of search results.
  • sources: (array) The sources to search in. DEFAULT: Search the user's default address book
  • count_only: (boolean) If true, only return the count of matching results. DEFAULT: false (Return the full data set).
  • emailSearch: (boolean) If true, indicates this is an email search like e.g., for an autocompleter. Ensures that ALL email fields are both included in 'fields' and returned in the results, regardless of the requested returnFields value. @todo Make this a separate API method in H6 (or separate API "module", e.g., an 'email search' API). @since 4.3.0

Throws

\Turba_Exception

Returns

mixed —

Either a hash containing the search results or a Rfc822 List object (if 'rfc822Return' is true).

getContact()

getContact(string  $source = null, string  $objectId = '') : array

Retrieves a contact.

Parameters

string $source

The source name where the contact is stored

string $objectId

The unique id of the contact to retrieve

Throws

\Turba_Exception
\Horde_Exception_NotFound

Returns

array —

The retrieved contact.

getContacts()

getContacts(string  $source = '', array  $objectIds = array()) : array

Retrieves a set of contacts from a single source.

Parameters

string $source

The source name where the contact is stored

array $objectIds

The unique ids of the contact to retrieve.

Throws

\Turba_Exception
\Horde_Exception_NotFound

Returns

array —

The retrieved contact.

getAllAttributeValues()

getAllAttributeValues(string  $field = '', array  $sources = array()) : array

Retrieves a list of all possible values of a field in specified source(s).

Parameters

string $field

Field name to check.

array $sources

Array containing the sources to look in.

Throws

\Turba_Exception

Returns

array —

An array of fields and possible values.

listTimeObjectCategories()

listTimeObjectCategories() : array

Retrieves a list of available time objects categories.

Returns

array —

An array of all configured time object categories.

listTimeObjects()

listTimeObjects(array  $time_categories, mixed  $start, mixed  $end) : array

Lists birthdays and/or anniversaries as time objects.

Parameters

array $time_categories

The time categories (from listTimeObjectCategories) to list.

mixed $start

The start date of the period.

mixed $end

The end date of the period.

Throws

\Turba_Exception

Returns

array —

An array of timeObject results.

getClientSource()

getClientSource() : string

Returns the client source name.

Returns

string —

The name of the source to use with the clients api.

clientFields()

clientFields() : array

Returns the available client fields.

Returns

array —

An array describing the fields.

getClient()

getClient(string  $objectId = '') : array

Returns a contact from the client source.

Parameters

string $objectId

Client unique ID.

Throws

\Turba_Exception

Returns

array —

Array of client data.

getClients()

getClients(array  $objectIds = array()) : array

Returns mulitple contacts from the client source.

Parameters

array $objectIds

client unique ids.

Throws

\Turba_Exception

Returns

array —

An array of clients data.

addClient()

addClient(array  $attributes = array()) : boolean

Adds a client to the client source.

Parameters

array $attributes

Array containing the client attributes.

Returns

boolean

updateClient()

updateClient(string  $objectId = '', array  $attributes = array()) : boolean

Updates client data.

Parameters

string $objectId

The unique id of the client.

array $attributes

An array of client attributes.

Returns

boolean

deleteClient()

deleteClient(string  $objectId = '') : boolean

Deletes a client

Parameters

string $objectId

The unique id of the client

Returns

boolean

searchClients()

searchClients(array  $names = array(), array  $fields = array(), boolean  $matchBegin = false) : array

Search for clients.

Parameters

array $names

The search filter values.

array $fields

The fields to search in.

boolean $matchBegin

Match word boundaries only.

Throws

\Turba_Exception

Returns

array —

A hash containing the search results.

addField()

addField(string|array  $address = '', string  $name = '', string  $field = '', string  $value = '', string  $source = '') 

Sets the value of the specified attribute of a contact

Parameters

string|array $address

Contact email address(es).

string $name

Contact name.

string $field

Field to update.

string $value

Field value to set.

string $source

Contact source.

Throws

\Turba_Exception

getField()

getField(string  $address = '', string  $field = '', array  $sources = array(), boolean  $strict = false, boolean  $multiple = false) : array

Returns a field value.

Parameters

string $address

Contact email address.

string $field

Field to get.

array $sources

Sources to check.

boolean $strict

Match the email address strictly.

boolean $multiple

Return more than one entry if found and true, return an error if this is false.

Throws

\Turba_Exception

Returns

array —

An array of field value(s).

deleteField()

deleteField(string  $address = '', string  $field = '', array  $sources = array()) 

Deletes a field value.

Parameters

string $address

Contact email address.

string $field

Field to delete value for.

array $sources

Sources to delete value from.

Throws

\Turba_Exception

getSourcesConfig()

getSourcesConfig(\type  $filter = array()) : array

Obtain an array of $cfgSource entries matching the filter criteria.

Parameters

\type $filter

A single key -> value hash to filter the sources.

Returns

array

listShares()

listShares(integer  $perms = \Horde_Perms::READ) : array

Lists all shares the current user has access to.

Parameters

integer $perms

Returns

array —

of Turba_Share objects.

listUserGroupObjects()

listUserGroupObjects() : array

GroupObject API - Lists all turba lists for the current user that can be treated as Horde_Group objects.

Throws

\Horde_Exception

Returns

array —

A hash of all visible groups in the form of group_id => group_name

getGroupObjects()

getGroupObjects() : array

Returns all contact groups.

Throws

\Turba_Exception

Returns

array —

A list of group hashes.

getGroupMemberships()

getGroupMemberships(string  $user, boolean  $parentGroups = false) : array

Returns all contact groups that the specified user is a member of.

Parameters

string $user

The user.

boolean $parentGroups

Include user as a member of the any parent group as well.

Throws

\Horde_Exception

Returns

array —

An array of group identifiers that the specified user is a member of.

getGroupObject()

getGroupObject(string  $gid) : array

Returns a contact group hash.

Parameters

string $gid

The group identifier.

Throws

\Turba_Exception

Returns

array —

A hash defining the group.

getGroupMembers()

getGroupMembers(string  $gid, boolean  $subGroups = false) : array

Returns a list of all members belonging to a contact group.

Parameters

string $gid

The group identifier

boolean $subGroups

Also include members of any subgroups?

Throws

\Horde_Exception

Returns

array —

An array of group members (identified by email address).

addAddressbook()

addAddressbook(string  $name, array  $params = array()) : string

Creates a new addressbook.

Parameters

string $name

The display name for the addressbook.

array $params

Any addtional parameters needed.

  • synchronize: (boolean) If true, add address book to the list of address books to syncronize. DEFAULT: false (do not add to the list). @since 4.2.1

Returns

string —

The new addressbook's id (share name).

deleteAddressbook()

deleteAddressbook(string  $id) 

Delete the specified addressbook.

Parameters

string $id

The addressbook id.

updateAddressbook()

updateAddressbook(string  $id, array  $info) 

Update an existing addressbook's name or description.

Parameters

string $id

The addressbook id.

array $info

The info to change:

  • name: The addressbook's display name.
  • desc: The addressbook's description.

listTagInfo()

listTagInfo(array  $tags = null,   $user = null) : array

Retrieve the list of used tag_names, tag_ids and the total number of resources that are linked to that tag.

Parameters

array $tags

An optional array of tag_ids. If omitted, all tags will be included.

$user

Returns

array —

An array containing tag_name, and total

searchTags()

searchTags(array  $names, integer  $max = 10, integer  $from, string  $resource_type = '', string  $user = null, boolean  $raw = false) : array

SearchTags API: Returns an application-agnostic array (useful for when doing a tag search across multiple applications)

The 'raw' results array can be returned instead by setting $raw = true.

Parameters

array $names

An array of tag_names to search for.

integer $max

The maximum number of resources to return.

integer $from

The number of the resource to start with.

string $resource_type

The resource type [bookmark, '']

string $user

Restrict results to resources owned by $user.

boolean $raw

Return the raw data?

Returns

array —

An array of results:

 'title'    - The title for this resource.
 'desc'     - A terse description of this resource.
 'view_url' - The URL to view this resource.
 'app'      - The Horde application this resource belongs to.
 'icon'     - URL to an image.

_modified()

_modified(  $uid,   $sources) 

Parameters

$uid
$sources

_getSources()

_getSources(  $sources,   $synchronize = false,   $end = false) 

Parameters

$sources
$synchronize
$end

Throws

\Turba_Exception

_getGroupObject()

_getGroupObject(  $source,   $key) 

Parameters

$source
$key

_getContactImageUrl()

_getContactImageUrl(  $obj) 

Parameters

$obj

_getSource()

_getSource(  $source) 

Parameters

$source

_encodeContent()

_encodeContent(  $content) 

Parameters

$content