IManager

interface OCP\Contacts\IManager
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.
Implemented by:OC\ContactsManager
Source:lib/public/Contacts/IManager.php#56

Methods

public OCP\Contacts\IManager::search($pattern, $searchProperties=[], $options=[])
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;
}
Source:

lib/public/Contacts/IManager.php#105
Parameters:
  • $pattern (string) which should match within the $searchProperties
  • $searchProperties (array) defines the properties within the query pattern should match
  • $options (array) = array() to define the search behavior
  • ‘escape_like_param’ - If set to false wildcards _ and % are not escaped
  • ‘limit’ - Set a numeric limit for the search results
  • ‘offset’ - Set the offset for the limited search results
Returns:

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

6.0.0
public OCP\Contacts\IManager::delete($id, $address_book_key)
This function can be used to delete the contact identified by the given id
Source:

lib/public/Contacts/IManager.php#115
Parameters:
  • $id (object) the unique identifier to a contact
  • $address_book_key (string) identifier of the address book in which the contact shall be deleted
Returns:

bool successful or not
Since:

6.0.0
public OCP\Contacts\IManager::createOrUpdate($properties, $address_book_key)
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.
Source:

lib/public/Contacts/IManager.php#126
Parameters:
  • $properties (array) this array if key-value-pairs defines a contact
  • $address_book_key (string) 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
Since:

6.0.0
public OCP\Contacts\IManager::isEnabled()
Check if contacts are available (e.g. contacts app enabled)
Source:lib/public/Contacts/IManager.php#134
Returns:bool true if enabled, false if not
Since:6.0.0
public OCP\Contacts\IManager::registerAddressBook($address_book)
Registers an address book
Source:

lib/public/Contacts/IManager.php#143
Parameters:
Returns:

void
Since:

6.0.0
public OCP\Contacts\IManager::unregisterAddressBook($address_book)
Unregisters an address book
Source:

lib/public/Contacts/IManager.php#152
Parameters:
Returns:

void
Since:

6.0.0
public OCP\Contacts\IManager::register($callable)
In order to improve lazy loading a closure can be registered which will be called in case
address books are actually requested
Source:

lib/public/Contacts/IManager.php#162
Parameters:
  • $callable (Closure)
Returns:

void
Since:

6.0.0
public OCP\Contacts\IManager::getAddressBooks()
Return a list of the user’s addressbooks display names
Source:lib/public/Contacts/IManager.php#171
Returns:array
Since:6.0.0
Deprecated:16.0.0 - Use `$this->getUserAddressBooks()` instead
public OCP\Contacts\IManager::getUserAddressBooks()
Return a list of the user’s addressbooks
Source:lib/public/Contacts/IManager.php#179
Returns:\OCP\IAddressBook[]
Since:16.0.0
public OCP\Contacts\IManager::clear()
removes all registered address book instances
Source:lib/public/Contacts/IManager.php#187
Returns:void
Since:6.0.0