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