\OCPContacts

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
Properties
Constants
search()
delete()
createOrUpdate()
isEnabled()
registerAddressBook()
unregisterAddressBook()
getAddressBooks()
clear()
No public properties found
No constants found
No protected methods found
No protected properties found
N/A
No private methods found
No private properties found
N/A

Methods

search()

search(string  $pattern, array  $searchProperties = array(), array  $options = array()) : 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) {
    // The API is not active -> nothing to do
    if (!\OCP\Contacts::isEnabled()) {
        return array();
    }

    $result = \OCP\Contacts::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!

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

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) 

Parameters

\OCP\IAddressBook $address_book

unregisterAddressBook()

unregisterAddressBook(\OCP\IAddressBook  $address_book) 

Parameters

\OCP\IAddressBook $address_book

getAddressBooks()

getAddressBooks() : array

Returns

array

clear()

clear() 

removes all registered address book instances