\OCP\ContactsIManager

This class provides access to the contacts app. Use this class exclusively if you want to access contacts.

Contacts in general will be expressed as an array of key-value-pairs. The keys will match the property names defined in https://tools.ietf.org/html/rfc2426#section-1

Proposed workflow for working with contacts:

  • search for the contacts
  • manipulate the results array
  • createOrUpdate will save the given contacts overwriting the existing data

For updating it is mandatory to keep the id. Without an id a new contact will be created.

Summary

Methods
Constants
search()
delete()
createOrUpdate()
isEnabled()
registerAddressBook()
unregisterAddressBook()
register()
getAddressBooks()
clear()
No constants found
No protected methods found
N/A
No private methods found
N/A

Methods

search()

search(string  $pattern, array  $searchProperties = array(), array  $options = array(), integer  $limit = null, integer  $offset = null) : array

This function is used to search and find contacts within the users address books.

In case $pattern is empty all contacts will be returned.

Example: Following function shows how to search for contacts for the name and the email address.

public static function getMatchingRecipient($term) {
    $cm = \OC::$server->getContactsManager();
    // The API is not active -> nothing to do
    if (!$cm->isEnabled()) {
        return array();
    }

    $result = $cm->search($term, array('FN', 'EMAIL'));
    $receivers = array();
    foreach ($result as $r) {
        $id = $r['id'];
        $fn = $r['FN'];
        $email = $r['EMAIL'];
        if (!is_array($email)) {
            $email = array($email);
        }

        // loop through all email addresses of this contact
        foreach ($email as $e) {
        $displayName = $fn . " <$e>";
        $receivers[] = array(
            'id'    => $id,
            'label' => $displayName,
            'value' => $displayName);
        }
    }

    return $receivers;
}

Parameters

string $pattern

which should match within the $searchProperties

array $searchProperties

defines the properties within the query pattern should match

array $options
  • for future use. One should always have options!
integer $limit
integer $offset

Returns

array —

an array of contacts which are arrays of key-value-pairs

delete()

delete(object  $id, string  $address_book_key) : boolean

This function can be used to delete the contact identified by the given id

Parameters

object $id

the unique identifier to a contact

string $address_book_key

identifier of the address book in which the contact shall be deleted

Returns

boolean —

successful or not

createOrUpdate()

createOrUpdate(array  $properties, string  $address_book_key) : array

This function is used to create a new contact if 'id' is not given or not present.

Otherwise the contact will be updated by replacing the entire data set.

Parameters

array $properties

this array if key-value-pairs defines a contact

string $address_book_key

identifier of the address book in which the contact shall be created or updated

Returns

array —

an array representing the contact just created or updated

isEnabled()

isEnabled() : boolean

Check if contacts are available (e.g. contacts app enabled)

Returns

boolean —

true if enabled, false if not

registerAddressBook()

registerAddressBook(\OCP\IAddressBook  $address_book) : void

Registers an address book

Parameters

\OCP\IAddressBook $address_book

unregisterAddressBook()

unregisterAddressBook(\OCP\IAddressBook  $address_book) : void

Unregisters an address book

Parameters

\OCP\IAddressBook $address_book

register()

register(\Closure  $callable) : void

In order to improve lazy loading a closure can be registered which will be called in case address books are actually requested

Parameters

\Closure $callable

getAddressBooks()

getAddressBooks() : array

Returns

array

clear()

clear() : void

removes all registered address book instances