1
0
mirror of https://github.com/owncloudarchive/contacts.git synced 2024-12-04 15:24:35 +01:00
OwncloudContactsOfficial/lib/backend/abstractbackend.php
babelouest 5e95953799 rebase
2014-05-09 13:54:45 -04:00

466 lines
14 KiB
PHP

<?php
/**
* ownCloud - Base class for Contacts backends
*
* @author Thomas Tanghus
* @copyright 2013-2014 Thomas Tanghus (thomas@tanghus.net)
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE
* License as published by the Free Software Foundation; either
* version 3 of the License, or any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU AFFERO GENERAL PUBLIC LICENSE for more details.
*
* You should have received a copy of the GNU Affero General Public
* License along with this library. If not, see <http://www.gnu.org/licenses/>.
*
*/
namespace OCA\Contacts\Backend;
use OCA\Contacts\VObject\VCard;
/**
* Subclass this class for address book backends.
*/
abstract class AbstractBackend {
/**
* The following methods MUST be implemented:
*
* @method array getAddressBooksForUser(array $options = array())
* @method array|null getAddressBook(string $addressbookid, array $options = array())
* @method array getContacts(string $addressbookid, array $options = array())
* @method array|null getContact(string $addressbookid, mixed $id, array $options = array())
* The following methods MAY be implemented:
* @method bool hasAddressBook(string $addressbookid)
* @method bool updateAddressBook(string $addressbookid, array $updates, array $options = array())
* @method string createAddressBook(array $properties, array $options = array())
* @method bool deleteAddressBook(string $addressbookid, array $options = array())
* @method int lastModifiedAddressBook(string $addressbookid)
* @method array numContacts(string $addressbookid)
* @method bool updateContact(string $addressbookid, string $id, VCard $contact, array $options = array())
* @method string createContact(string $addressbookid, VCard $contact, array $properties)
* @method bool deleteContact(string $addressbookid, string $id, array $options = array())
* @method int lastModifiedContact(string $addressbookid)
*/
/**
* The name of the backend.
* @var string
*/
public $name;
/**
* The current usert.
* @var string
*/
public $userid;
protected $possibleContactPermissions = array(
\OCP\PERMISSION_CREATE => 'createContact',
\OCP\PERMISSION_READ => 'getContact',
\OCP\PERMISSION_UPDATE => 'updateContact',
\OCP\PERMISSION_DELETE => 'deleteContact',
);
protected $possibleAddressBookPermissions = array(
\OCP\PERMISSION_CREATE => 'createAddressBook',
\OCP\PERMISSION_READ => 'getAddressBook',
\OCP\PERMISSION_UPDATE => 'updateAddressBook',
\OCP\PERMISSION_DELETE => 'deleteAddressBook',
);
/**
* Sets up the backend
*
*/
public function __construct($userid = null) {
$this->userid = $userid ? $userid : \OCP\User::getUser();
}
/**
* @brief Get all possible permissions for contacts based on what the backend implements.
* @returns bitwise-or'ed actions
*
* Returns the supported actions as an int to be
* compared with \OCP\PERMISSION_CREATE etc.
*/
protected function getContactPermissions() {
$permissions = 0;
foreach ($this->possibleContactPermissions as $permission => $methodName) {
if(method_exists($this, $methodName)) {
$permissions |= $permission;
}
}
//\OCP\Util::writeLog('contacts', __METHOD__.', permissions' . $permissions, \OCP\Util::DEBUG);
return $permissions;
}
/**
* @brief Get all permissions for address book based on what the backend implements.
* @returns bitwise-or'ed actions
*
* Returns the supported actions as int to be
* compared with \OCP\PERMISSION_CREATE etc.
*/
protected function getAddressBookPermissions() {
$permissions = 0;
foreach ($this->possibleAddressBookPermissions as $permission => $methodName) {
if (method_exists($this, $methodName)) {
$permissions |= $permission;
}
}
//\OCP\Util::writeLog('contacts', __METHOD__.', permissions' . $permissions, \OCP\Util::DEBUG);
return $permissions;
}
/**
* @brief Check if backend implements action for contacts
* @param $actions bitwise-or'ed actions
* @returns boolean
*
* Returns the supported actions as int to be
* compared with \OCP\PERMISSION_CREATE etc.
*/
public function hasContactMethodFor($permission) {
return (bool)($this->getContactPermissions() & $permission);
}
/**
* @brief Check if backend implements action for contacts
* @param $actions bitwise-or'ed actions
* @returns boolean
*
* Returns the supported actions as int to be
* compared with \OCP\PERMISSION_CREATE etc.
*/
public function hasAddressBookMethodFor($permission) {
return (bool)($this->getAddressBookPermissions() & $permission);
}
/**
* Check if the backend has the address book
*
* This can be reimplemented in the backend to improve performance.
*
* @param string $addressBookId
* @return bool
*/
public function hasAddressBook($addressBookId) {
return count($this->getAddressBook($addressBookId)) > 0;
}
/**
* Returns the number of contacts in an address book.
* Implementations can choose to override this method to either
* get the result more effectively or to return null if the backend
* cannot determine the number.
*
* @param string $addressBookId
* @return integer|null
*/
public function numContacts($addressBookId) {
return count($this->getContacts($addressBookId));
}
/**
* Returns the list of addressbooks for a specific user.
*
* The returned arrays MUST contain a unique 'id' for the
* backend and a 'displayname', and it MAY contain a
* 'description'.
*
* @param array $options - Optional (backend specific options)
* @return array
*/
public abstract function getAddressBooksForUser(array $options = array());
/**
* Get an addressbook's properties
*
* The returned array MUST contain string: 'displayname',string: 'backend'
* and integer: 'permissions' value using there ownCloud CRUDS constants
* (which MUST be at least \OCP\PERMISSION_READ).
* Currently the only ones supported are 'displayname' and
* 'description', but backends can implement additional.
*
* @param string $addressBookId
* @param array $options - Optional (backend specific options)
* @return array|null $properties
*/
public abstract function getAddressBook($addressBookId, array $options = array());
/**
* Updates an addressbook's properties
*
* The $properties array contains the changes to be made.
*
* Currently the only ones supported are 'displayname' and
* 'description', but backends can implement additional.
*
* @param string $addressBookId
* @param array $properties
* @param array $options - Optional (backend specific options)
* @return bool
public function updateAddressBook($addressBookId, array $properties, array $options = array());
*/
/**
* Creates a new address book
*
* Classes that doesn't support adding address books MUST NOT implement this method.
*
* Currently the only ones supported are 'displayname' and
* 'description', but backends can implement additional.
* 'displayname' MUST be present.
*
* @param array $properties
* @param array $options - Optional (backend specific options)
* @return string|false The ID if the newly created AddressBook or false on error.
public function createAddressBook(array $properties, array $options = array());
*/
/**
* Deletes an entire address book and all its contents
*
* Classes that doesn't support deleting address books MUST NOT implement this method.
*
* @param string $addressBookId
* @param array $options - Optional (backend specific options)
* @return bool
public function deleteAddressBook($addressBookId, array $options = array());
*/
/**
* @brief Get the last modification time for an address book.
*
* Must return a UNIX time stamp or null if the backend
* doesn't support it.
*
* @param string $addressBookId
* @returns int | null
*/
public function lastModifiedAddressBook($addressBookId) {
}
/**
* @brief 'touch' an address book.
*
* If implemented this method must mark the address books
* modification date so lastModifiedAddressBook() can be
* used to invalidate the cache.
*
* @param string $addressBookId
*/
public function setModifiedAddressBook($addressBookId) {
}
/**
* Returns all contacts for a specific addressbook id.
*
* The returned array MUST contain the unique ID a string value 'id', a string
* value 'displayname', a string value 'owner' and an integer 'permissions' value using there
* ownCloud CRUDS constants (which MUST be at least \OCP\PERMISSION_READ), and SHOULD
* contain the properties of the contact formatted as a vCard 3.0
* https://tools.ietf.org/html/rfc2426 mapped to 'carddata' or as an
* \OCA\Contacts\VObject\VCard object mapped to 'vcard'.
*
* Example:
*
* array(
* 0 => array('id' => '4e111fef5df', 'owner' => 'foo', 'permissions' => 1, 'displayname' => 'John Q. Public', 'vcard' => $vobject),
* 1 => array('id' => 'bbcca2d1535', 'owner' => 'bar', 'permissions' => 32, 'displayname' => 'Jane Doe', 'carddata' => $data)
* );
*
* For contacts that contain loads of data, the 'carddata' or 'vcard' MAY be omitted
* as it can be fetched later.
*
* The following options are supported in the $options array:
*
* - 'limit': An integer value for the number of contacts to fetch in each call.
* - 'offset': The offset to start at.
* - 'omitdata': Whether to fetch the entire carddata or vcard.
*
* @param string $addressBookId
* @param array $options - Optional options
* @return array
*/
public abstract function getContacts($addressBookId, array $options = array());
/**
* Returns a specfic contact.
*
* Same as getContacts except that either 'carddata' or 'vcard' is mandatory.
*
* @param string $addressBookId
* @param mixed $id
* @param array $options - Optional options
* @return array|null
*/
public abstract function getContact($addressBookId, $id, array $options = array());
/**
* Creates a new contact
*
* Classes that doesn't support adding contacts MUST NOT implement this method.
*
* @param string $addressBookId
* @param VCard $contact
* @param array $options - Optional options
* @return string|bool The identifier for the new contact or false on error.
public function createContact($addressbookid, $contact, array $options = array());
*/
/**
* Updates a contact
*
* Classes that doesn't support updating contacts MUST NOT implement this method.
*
* @param string $addressBookId
* @param mixed $id
* @param VCard $contact
* @param array $options - Optional options
* @return bool
public function updateContact($addressbookid, $id, $carddata, array $options = array());
*/
/**
* Deletes a contact
*
* Classes that doesn't support deleting contacts MUST NOT implement this method.
*
* @param string $addressBookId
* @param mixed $id
* @param array $options - Optional options
* @return bool
public function deleteContact($addressbookid, $id, array $options = array());
*/
/**
* @brief Get the last modification time for a contact.
*
* Must return a UNIX time stamp or null if the backend
* doesn't support it.
*
* @param string $addressBookId
* @param mixed $id
* @returns int | null
*/
public function lastModifiedContact($addressBookId, $id) {
}
/**
* Creates a unique key for inserting into oc_preferences.
* As IDs can have any length and the key field is limited to 64 chars,
* the IDs are transformed to the first 8 chars of their md5 hash.
*
* @param string $addressBookId.
* @param string $contactId.
* @throws \BadMethodCallException
* @return string
*/
protected function combinedKey($addressBookId = null, $contactId = null) {
$key = $this->name;
if (!is_null($addressBookId)) {
$key .= '_' . substr(md5($addressBookId), 0, 8);
if (!is_null($contactId)) {
$key .= '_' . substr(md5($contactId), 0, 8);
}
} else if (!is_null($contactId)) {
throw new \BadMethodCallException(
__METHOD__ . ' cannot be called with a contact ID but no address book ID'
);
}
return $key;
}
/**
* @brief Query whether a backend or an address book is active
* @param string $addressbookid If null it checks whether the backend is activated.
* @return boolean
*/
public function isActive($addressBookId = null) {
$key = $this->combinedKey($addressBookId);
$key = 'active_' . $key;
return !!(\OCP\Config::getUserValue($this->userid, 'contacts', $key, 1));
}
/**
* @brief Activate a backend or an address book
* @param bool active
* @param string $addressbookid If null it activates the backend.
* @return boolean
*/
public function setActive($active, $addressBookId = null) {
$key = $this->combinedKey($addressBookId);
$key = 'active_' . $key;
$this->setModifiedAddressBook($addressBookId);
return \OCP\Config::setUserValue($this->userid, 'contacts', $key, (int)$active);
}
/**
* @brief get all the preferences for the addressbook
* @param string $id
* @return array Format array('param1' => 'value', 'param2' => 'value')
*/
public function getPreferences($addressBookId) {
$key = 'prefs_' . $this->combinedKey($addressBookId);
$data = \OCP\Config::getUserValue($this->userid, 'contacts', $key, false);
return $data ? json_decode($data, true) : array();
}
/**
* @brief sets the preferences for the addressbook given in parameter
* @param string $id
* @param array the preferences, format array('param1' => 'value', 'param2' => 'value')
* @return boolean
*/
public function setPreferences($addressbookid, array $params) {
$key = 'prefs_' . $this->combinedKey($addressbookid);
$data = json_encode($params);
return $data
? \OCP\Config::setUserValue($this->userid, 'contacts', $key, $data)
: false;
}
public function removePreferences($addressbookid) {
$key = $this->combinedKey($addressbookid);
$key = 'prefs_' . $key;
\OC_Preferences::deleteKey( $this->userid, 'contacts', $key );
}
}