dav/SabreDAV/lib/Sabre/CardDAV/Backend/Abstract.php

   1 <?php
   2
   3 /**
   4  * Abstract Backend class
   5  *
   6  * This class serves as a base-class for addressbook backends
   7  *
   8  * Note that there are references to 'addressBookId' scattered throughout the
   9  * class. The value of the addressBookId is completely up to you, it can be any
  10  * arbitrary value you can use as an unique identifier.
  11  *
  12  * @package Sabre
  13  * @subpackage CardDAV
  14  * @copyright Copyright (C) 2007-2012 Rooftop Solutions. All rights reserved.
  15  * @author Evert Pot (http://www.rooftopsolutions.nl/)
  16  * @license http://code.google.com/p/sabredav/wiki/License Modified BSD License
  17  */
  18 abstract class Sabre_CardDAV_Backend_Abstract {
  19
  20     /**
  21      * Returns the list of addressbooks for a specific user.
  22      *
  23      * Every addressbook should have the following properties:
  24      *   id - an arbitrary unique id
  25      *   uri - the 'basename' part of the url
  26      *   principaluri - Same as the passed parameter
  27      *
  28      * Any additional clark-notation property may be passed besides this. Some
  29      * common ones are :
  30      *   {DAV:}displayname
  31      *   {urn:ietf:params:xml:ns:carddav}addressbook-description
  32      *   {http://calendarserver.org/ns/}getctag
  33      *
  34      * @param string $principalUri
  35      * @return array
  36      */
  37     public abstract function getAddressBooksForUser($principalUri);
  38
  39     /**
  40      * Updates an addressbook's properties
  41      *
  42      * See Sabre_DAV_IProperties for a description of the mutations array, as
  43      * well as the return value.
  44      *
  45      * @param mixed $addressBookId
  46      * @param array $mutations
  47      * @see Sabre_DAV_IProperties::updateProperties
  48      * @return bool|array
  49      */
  50     public abstract function updateAddressBook($addressBookId, array $mutations);
  51
  52     /**
  53      * Creates a new address book
  54      *
  55      * @param string $principalUri
  56      * @param string $url Just the 'basename' of the url.
  57      * @param array $properties
  58      * @return void
  59      */
  60     abstract public function createAddressBook($principalUri, $url, array $properties);
  61
  62     /**
  63      * Deletes an entire addressbook and all its contents
  64      *
  65      * @param mixed $addressBookId
  66      * @return void
  67      */
  68     abstract public function deleteAddressBook($addressBookId);
  69
  70     /**
  71      * Returns all cards for a specific addressbook id.
  72      *
  73      * This method should return the following properties for each card:
  74      *   * carddata - raw vcard data
  75      *   * uri - Some unique url
  76      *   * lastmodified - A unix timestamp
  77      *
  78      * It's recommended to also return the following properties:
  79      *   * etag - A unique etag. This must change every time the card changes.
  80      *   * size - The size of the card in bytes.
  81      *
  82      * If these last two properties are provided, less time will be spent
  83      * calculating them. If they are specified, you can also ommit carddata.
  84      * This may speed up certain requests, especially with large cards.
  85      *
  86      * @param mixed $addressbookId
  87      * @return array
  88      */
  89     public abstract function getCards($addressbookId);
  90
  91     /**
  92      * Returns a specfic card.
  93      *
  94      * The same set of properties must be returned as with getCards. The only
  95      * exception is that 'carddata' is absolutely required.
  96      *
  97      * @param mixed $addressBookId
  98      * @param string $cardUri
  99      * @return array
 100      */
 101     public abstract function getCard($addressBookId, $cardUri);
 102
 103     /**
 104      * Creates a new card.
 105      *
 106      * The addressbook id will be passed as the first argument. This is the
 107      * same id as it is returned from the getAddressbooksForUser method.
 108      *
 109      * The cardUri is a base uri, and doesn't include the full path. The
 110      * cardData argument is the vcard body, and is passed as a string.
 111      *
 112      * It is possible to return an ETag from this method. This ETag is for the
 113      * newly created resource, and must be enclosed with double quotes (that
 114      * is, the string itself must contain the double quotes).
 115      *
 116      * You should only return the ETag if you store the carddata as-is. If a
 117      * subsequent GET request on the same card does not have the same body,
 118      * byte-by-byte and you did return an ETag here, clients tend to get
 119      * confused.
 120      *
 121      * If you don't return an ETag, you can just return null.
 122      *
 123      * @param mixed $addressBookId
 124      * @param string $cardUri
 125      * @param string $cardData
 126      * @return string|null
 127      */
 128     abstract public function createCard($addressBookId, $cardUri, $cardData);
 129
 130     /**
 131      * Updates a card.
 132      *
 133      * The addressbook id will be passed as the first argument. This is the
 134      * same id as it is returned from the getAddressbooksForUser method.
 135      *
 136      * The cardUri is a base uri, and doesn't include the full path. The
 137      * cardData argument is the vcard body, and is passed as a string.
 138      *
 139      * It is possible to return an ETag from this method. This ETag should
 140      * match that of the updated resource, and must be enclosed with double
 141      * quotes (that is: the string itself must contain the actual quotes).
 142      *
 143      * You should only return the ETag if you store the carddata as-is. If a
 144      * subsequent GET request on the same card does not have the same body,
 145      * byte-by-byte and you did return an ETag here, clients tend to get
 146      * confused.
 147      *
 148      * If you don't return an ETag, you can just return null.
 149      *
 150      * @param mixed $addressBookId
 151      * @param string $cardUri
 152      * @param string $cardData
 153      * @return string|null
 154      */
 155     abstract public function updateCard($addressBookId, $cardUri, $cardData);
 156
 157     /**
 158      * Deletes a card
 159      *
 160      * @param mixed $addressBookId
 161      * @param string $cardUri
 162      * @return bool
 163      */
 164     abstract public function deleteCard($addressBookId, $cardUri);
 165
 166 }