diff options
Diffstat (limited to '3rdparty/Sabre/CardDAV/Backend/Abstract.php')
| -rwxr-xr-x[-rw-r--r--] | 3rdparty/Sabre/CardDAV/Backend/Abstract.php | 145 |
1 files changed, 95 insertions, 50 deletions
diff --git a/3rdparty/Sabre/CardDAV/Backend/Abstract.php b/3rdparty/Sabre/CardDAV/Backend/Abstract.php index 1f0253ddab8..e4806b7161f 100644..100755 --- a/3rdparty/Sabre/CardDAV/Backend/Abstract.php +++ b/3rdparty/Sabre/CardDAV/Backend/Abstract.php @@ -5,14 +5,14 @@ * * This class serves as a base-class for addressbook backends * - * Note that there are references to 'addressBookId' scattered throughout the - * class. The value of the addressBookId is completely up to you, it can be any + * Note that there are references to 'addressBookId' scattered throughout the + * class. The value of the addressBookId is completely up to you, it can be any * arbitrary value you can use as an unique identifier. - * + * * @package Sabre * @subpackage CardDAV - * @copyright Copyright (C) 2007-2011 Rooftop Solutions. All rights reserved. - * @author Evert Pot (http://www.rooftopsolutions.nl/) + * @copyright Copyright (C) 2007-2012 Rooftop Solutions. All rights reserved. + * @author Evert Pot (http://www.rooftopsolutions.nl/) * @license http://code.google.com/p/sabredav/wiki/License Modified BSD License */ abstract class Sabre_CardDAV_Backend_Abstract { @@ -25,97 +25,142 @@ abstract class Sabre_CardDAV_Backend_Abstract { * uri - the 'basename' part of the url * principaluri - Same as the passed parameter * - * Any additional clark-notation property may be passed besides this. Some + * Any additional clark-notation property may be passed besides this. Some * common ones are : * {DAV:}displayname * {urn:ietf:params:xml:ns:carddav}addressbook-description * {http://calendarserver.org/ns/}getctag - * - * @param string $principalUri - * @return array + * + * @param string $principalUri + * @return array */ - public abstract function getAddressBooksForUser($principalUri); + public abstract function getAddressBooksForUser($principalUri); /** * Updates an addressbook's properties * - * See Sabre_DAV_IProperties for a description of the mutations array, as - * well as the return value. + * See Sabre_DAV_IProperties for a description of the mutations array, as + * well as the return value. * * @param mixed $addressBookId * @param array $mutations * @see Sabre_DAV_IProperties::updateProperties * @return bool|array */ - public abstract function updateAddressBook($addressBookId, array $mutations); + public abstract function updateAddressBook($addressBookId, array $mutations); /** - * Creates a new address book + * Creates a new address book * - * @param string $principalUri - * @param string $url Just the 'basename' of the url. - * @param array $properties + * @param string $principalUri + * @param string $url Just the 'basename' of the url. + * @param array $properties * @return void */ - abstract public function createAddressBook($principalUri, $url, array $properties); + abstract public function createAddressBook($principalUri, $url, array $properties); /** * Deletes an entire addressbook and all its contents * - * @param mixed $addressBookId + * @param mixed $addressBookId * @return void */ - abstract public function deleteAddressBook($addressBookId); + abstract public function deleteAddressBook($addressBookId); /** - * Returns all cards for a specific addressbook id. + * Returns all cards for a specific addressbook id. * * This method should return the following properties for each card: * * carddata - raw vcard data * * uri - Some unique url * * lastmodified - A unix timestamp - - * @param mixed $addressbookId - * @return array + * + * It's recommended to also return the following properties: + * * etag - A unique etag. This must change every time the card changes. + * * size - The size of the card in bytes. + * + * If these last two properties are provided, less time will be spent + * calculating them. If they are specified, you can also ommit carddata. + * This may speed up certain requests, especially with large cards. + * + * @param mixed $addressbookId + * @return array */ - public abstract function getCards($addressbookId); + public abstract function getCards($addressbookId); /** - * Returns a specfic card - * - * @param mixed $addressBookId - * @param string $cardUri - * @return void + * Returns a specfic card. + * + * The same set of properties must be returned as with getCards. The only + * exception is that 'carddata' is absolutely required. + * + * @param mixed $addressBookId + * @param string $cardUri + * @return array */ - public abstract function getCard($addressBookId, $cardUri); + public abstract function getCard($addressBookId, $cardUri); /** - * Creates a new card - * - * @param mixed $addressBookId - * @param string $cardUri - * @param string $cardData - * @return bool + * Creates a new card. + * + * The addressbook id will be passed as the first argument. This is the + * same id as it is returned from the getAddressbooksForUser method. + * + * The cardUri is a base uri, and doesn't include the full path. The + * cardData argument is the vcard body, and is passed as a string. + * + * It is possible to return an ETag from this method. This ETag is for the + * newly created resource, and must be enclosed with double quotes (that + * is, the string itself must contain the double quotes). + * + * You should only return the ETag if you store the carddata as-is. If a + * subsequent GET request on the same card does not have the same body, + * byte-by-byte and you did return an ETag here, clients tend to get + * confused. + * + * If you don't return an ETag, you can just return null. + * + * @param mixed $addressBookId + * @param string $cardUri + * @param string $cardData + * @return string|null */ - abstract public function createCard($addressBookId, $cardUri, $cardData); + abstract public function createCard($addressBookId, $cardUri, $cardData); /** - * Updates a card - * - * @param mixed $addressBookId - * @param string $cardUri - * @param string $cardData - * @return bool + * Updates a card. + * + * The addressbook id will be passed as the first argument. This is the + * same id as it is returned from the getAddressbooksForUser method. + * + * The cardUri is a base uri, and doesn't include the full path. The + * cardData argument is the vcard body, and is passed as a string. + * + * It is possible to return an ETag from this method. This ETag should + * match that of the updated resource, and must be enclosed with double + * quotes (that is: the string itself must contain the actual quotes). + * + * You should only return the ETag if you store the carddata as-is. If a + * subsequent GET request on the same card does not have the same body, + * byte-by-byte and you did return an ETag here, clients tend to get + * confused. + * + * If you don't return an ETag, you can just return null. + * + * @param mixed $addressBookId + * @param string $cardUri + * @param string $cardData + * @return string|null */ - abstract public function updateCard($addressBookId, $cardUri, $cardData); + abstract public function updateCard($addressBookId, $cardUri, $cardData); /** * Deletes a card - * - * @param mixed $addressBookId - * @param string $cardUri - * @return bool + * + * @param mixed $addressBookId + * @param string $cardUri + * @return bool */ - abstract public function deleteCard($addressBookId, $cardUri); + abstract public function deleteCard($addressBookId, $cardUri); } |