1<?php 2 3namespace Sabre\CardDAV\Backend; 4 5/** 6 * CardDAV Backend Interface 7 * 8 * Any CardDAV backend must implement this interface. 9 * 10 * Note that there are references to 'addressBookId' scattered throughout the 11 * class. The value of the addressBookId is completely up to you, it can be any 12 * arbitrary value you can use as an unique identifier. 13 * 14 * @copyright Copyright (C) fruux GmbH (https://fruux.com/) 15 * @author Evert Pot (http://evertpot.com/) 16 * @license http://sabre.io/license/ Modified BSD License 17 */ 18interface BackendInterface { 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 function getAddressBooksForUser($principalUri); 38 39 /** 40 * Updates properties for an address book. 41 * 42 * The list of mutations is stored in a Sabre\DAV\PropPatch object. 43 * To do the actual updates, you must tell this object which properties 44 * you're going to process with the handle() method. 45 * 46 * Calling the handle method is like telling the PropPatch object "I 47 * promise I can handle updating this property". 48 * 49 * Read the PropPatch documentation for more info and examples. 50 * 51 * @param string $addressBookId 52 * @param \Sabre\DAV\PropPatch $propPatch 53 * @return void 54 */ 55 function updateAddressBook($addressBookId, \Sabre\DAV\PropPatch $propPatch); 56 57 /** 58 * Creates a new address book. 59 * 60 * This method should return the id of the new address book. The id can be 61 * in any format, including ints, strings, arrays or objects. 62 * 63 * @param string $principalUri 64 * @param string $url Just the 'basename' of the url. 65 * @param array $properties 66 * @return mixed 67 */ 68 function createAddressBook($principalUri, $url, array $properties); 69 70 /** 71 * Deletes an entire addressbook and all its contents 72 * 73 * @param mixed $addressBookId 74 * @return void 75 */ 76 function deleteAddressBook($addressBookId); 77 78 /** 79 * Returns all cards for a specific addressbook id. 80 * 81 * This method should return the following properties for each card: 82 * * carddata - raw vcard data 83 * * uri - Some unique url 84 * * lastmodified - A unix timestamp 85 * 86 * It's recommended to also return the following properties: 87 * * etag - A unique etag. This must change every time the card changes. 88 * * size - The size of the card in bytes. 89 * 90 * If these last two properties are provided, less time will be spent 91 * calculating them. If they are specified, you can also ommit carddata. 92 * This may speed up certain requests, especially with large cards. 93 * 94 * @param mixed $addressbookId 95 * @return array 96 */ 97 function getCards($addressbookId); 98 99 /** 100 * Returns a specfic card. 101 * 102 * The same set of properties must be returned as with getCards. The only 103 * exception is that 'carddata' is absolutely required. 104 * 105 * If the card does not exist, you must return false. 106 * 107 * @param mixed $addressBookId 108 * @param string $cardUri 109 * @return array 110 */ 111 function getCard($addressBookId, $cardUri); 112 113 /** 114 * Returns a list of cards. 115 * 116 * This method should work identical to getCard, but instead return all the 117 * cards in the list as an array. 118 * 119 * If the backend supports this, it may allow for some speed-ups. 120 * 121 * @param mixed $addressBookId 122 * @param array $uris 123 * @return array 124 */ 125 function getMultipleCards($addressBookId, array $uris); 126 127 /** 128 * Creates a new card. 129 * 130 * The addressbook id will be passed as the first argument. This is the 131 * same id as it is returned from the getAddressBooksForUser method. 132 * 133 * The cardUri is a base uri, and doesn't include the full path. The 134 * cardData argument is the vcard body, and is passed as a string. 135 * 136 * It is possible to return an ETag from this method. This ETag is for the 137 * newly created resource, and must be enclosed with double quotes (that 138 * is, the string itself must contain the double quotes). 139 * 140 * You should only return the ETag if you store the carddata as-is. If a 141 * subsequent GET request on the same card does not have the same body, 142 * byte-by-byte and you did return an ETag here, clients tend to get 143 * confused. 144 * 145 * If you don't return an ETag, you can just return null. 146 * 147 * @param mixed $addressBookId 148 * @param string $cardUri 149 * @param string $cardData 150 * @return string|null 151 */ 152 function createCard($addressBookId, $cardUri, $cardData); 153 154 /** 155 * Updates a card. 156 * 157 * The addressbook id will be passed as the first argument. This is the 158 * same id as it is returned from the getAddressBooksForUser method. 159 * 160 * The cardUri is a base uri, and doesn't include the full path. The 161 * cardData argument is the vcard body, and is passed as a string. 162 * 163 * It is possible to return an ETag from this method. This ETag should 164 * match that of the updated resource, and must be enclosed with double 165 * quotes (that is: the string itself must contain the actual quotes). 166 * 167 * You should only return the ETag if you store the carddata as-is. If a 168 * subsequent GET request on the same card does not have the same body, 169 * byte-by-byte and you did return an ETag here, clients tend to get 170 * confused. 171 * 172 * If you don't return an ETag, you can just return null. 173 * 174 * @param mixed $addressBookId 175 * @param string $cardUri 176 * @param string $cardData 177 * @return string|null 178 */ 179 function updateCard($addressBookId, $cardUri, $cardData); 180 181 /** 182 * Deletes a card 183 * 184 * @param mixed $addressBookId 185 * @param string $cardUri 186 * @return bool 187 */ 188 function deleteCard($addressBookId, $cardUri); 189 190} 191