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) 2007-2015 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 documenation 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     * @param string $principalUri
61     * @param string $url Just the 'basename' of the url.
62     * @param array $properties
63     * @return void
64     */
65    function createAddressBook($principalUri, $url, array $properties);
66
67    /**
68     * Deletes an entire addressbook and all its contents
69     *
70     * @param mixed $addressBookId
71     * @return void
72     */
73    function deleteAddressBook($addressBookId);
74
75    /**
76     * Returns all cards for a specific addressbook id.
77     *
78     * This method should return the following properties for each card:
79     *   * carddata - raw vcard data
80     *   * uri - Some unique url
81     *   * lastmodified - A unix timestamp
82     *
83     * It's recommended to also return the following properties:
84     *   * etag - A unique etag. This must change every time the card changes.
85     *   * size - The size of the card in bytes.
86     *
87     * If these last two properties are provided, less time will be spent
88     * calculating them. If they are specified, you can also ommit carddata.
89     * This may speed up certain requests, especially with large cards.
90     *
91     * @param mixed $addressbookId
92     * @return array
93     */
94    function getCards($addressbookId);
95
96    /**
97     * Returns a specfic card.
98     *
99     * The same set of properties must be returned as with getCards. The only
100     * exception is that 'carddata' is absolutely required.
101     *
102     * If the card does not exist, you must return false.
103     *
104     * @param mixed $addressBookId
105     * @param string $cardUri
106     * @return array
107     */
108    function getCard($addressBookId, $cardUri);
109
110    /**
111     * Returns a list of cards.
112     *
113     * This method should work identical to getCard, but instead return all the
114     * cards in the list as an array.
115     *
116     * If the backend supports this, it may allow for some speed-ups.
117     *
118     * @param mixed $addressBookId
119     * @param array $uris
120     * @return array
121     */
122    function getMultipleCards($addressBookId, array $uris);
123
124    /**
125     * Creates a new card.
126     *
127     * The addressbook id will be passed as the first argument. This is the
128     * same id as it is returned from the getAddressBooksForUser method.
129     *
130     * The cardUri is a base uri, and doesn't include the full path. The
131     * cardData argument is the vcard body, and is passed as a string.
132     *
133     * It is possible to return an ETag from this method. This ETag is for the
134     * newly created resource, and must be enclosed with double quotes (that
135     * is, the string itself must contain the double quotes).
136     *
137     * You should only return the ETag if you store the carddata as-is. If a
138     * subsequent GET request on the same card does not have the same body,
139     * byte-by-byte and you did return an ETag here, clients tend to get
140     * confused.
141     *
142     * If you don't return an ETag, you can just return null.
143     *
144     * @param mixed $addressBookId
145     * @param string $cardUri
146     * @param string $cardData
147     * @return string|null
148     */
149    function createCard($addressBookId, $cardUri, $cardData);
150
151    /**
152     * Updates a card.
153     *
154     * The addressbook id will be passed as the first argument. This is the
155     * same id as it is returned from the getAddressBooksForUser method.
156     *
157     * The cardUri is a base uri, and doesn't include the full path. The
158     * cardData argument is the vcard body, and is passed as a string.
159     *
160     * It is possible to return an ETag from this method. This ETag should
161     * match that of the updated resource, and must be enclosed with double
162     * quotes (that is: the string itself must contain the actual quotes).
163     *
164     * You should only return the ETag if you store the carddata as-is. If a
165     * subsequent GET request on the same card does not have the same body,
166     * byte-by-byte and you did return an ETag here, clients tend to get
167     * confused.
168     *
169     * If you don't return an ETag, you can just return null.
170     *
171     * @param mixed $addressBookId
172     * @param string $cardUri
173     * @param string $cardData
174     * @return string|null
175     */
176    function updateCard($addressBookId, $cardUri, $cardData);
177
178    /**
179     * Deletes a card
180     *
181     * @param mixed $addressBookId
182     * @param string $cardUri
183     * @return bool
184     */
185    function deleteCard($addressBookId, $cardUri);
186
187}
188