1<?php
2
3namespace Sabre\CalDAV\Backend;
4
5/**
6 * Adds support for sharing features to a CalDAV server.
7 *
8 * Note: This feature is experimental, and may change in between different
9 * SabreDAV versions.
10 *
11 * Early warning: Currently SabreDAV provides no implementation for this. This
12 * is, because in it's current state there is no elegant way to do this.
13 * The problem lies in the fact that a real CalDAV server with sharing support
14 * would first need email support (with invite notifications), and really also
15 * a browser-frontend that allows people to accept or reject these shares.
16 *
17 * In addition, the CalDAV backends are currently kept as independent as
18 * possible, and should not be aware of principals, email addresses or
19 * accounts.
20 *
21 * Adding an implementation for Sharing to standard-sabredav would contradict
22 * these goals, so for this reason this is currently not implemented, although
23 * it may very well in the future; but probably not before SabreDAV 2.0.
24 *
25 * The interface works however, so if you implement all this, and do it
26 * correctly sharing _will_ work. It's not particularly easy, and I _urge you_
27 * to make yourself acquainted with the following document first:
28 *
29 * https://trac.calendarserver.org/browser/CalendarServer/trunk/doc/Extensions/caldav-sharing.txt
30 *
31 * An overview
32 * ===========
33 *
34 * Implementing this interface will allow a user to share his or her calendars
35 * to other users. Effectively, when a calendar is shared the calendar will
36 * show up in both the Sharer's and Sharee's calendar-home root.
37 * This interface adds a few methods that ensure that this happens, and there
38 * are also a number of new requirements in the base-class you must now follow.
39 *
40 *
41 * How it works
42 * ============
43 *
44 * When a user shares a calendar, the updateShares() method will be called with
45 * a list of sharees that are now added, and a list of sharees that have been
46 * removed.
47 * Removal is instant, but when a sharee is added the sharee first gets a
48 * chance to accept or reject the invitation for a share.
49 *
50 * After a share is accepted, the calendar will be returned from
51 * getUserCalendars for both the sharer, and the sharee.
52 *
53 * If the sharee deletes the calendar, only their share gets deleted. When the
54 * owner deletes a calendar, it will be removed for everybody.
55 *
56 *
57 * Notifications
58 * =============
59 *
60 * During all these sharing operations, a lot of notifications are sent back
61 * and forward.
62 *
63 * Whenever the list of sharees for a calendar has been changed (they have been
64 * added, removed or modified) all sharees should get a notification for this
65 * change.
66 * This notification is always represented by:
67 *
68 * Sabre\CalDAV\Notifications\Notification\Invite
69 *
70 * In the case of an invite, the sharee may reply with an 'accept' or
71 * 'decline'. These are always represented by:
72 *
73 * Sabre\CalDAV\Notifications\Notification\InviteReply
74 *
75 *
76 * Calendar access by sharees
77 * ==========================
78 *
79 * As mentioned earlier, shared calendars must now also be returned for
80 * getCalendarsForUser for sharees. A few things change though.
81 *
82 * The following properties must be specified:
83 *
84 * 1. {http://calendarserver.org/ns/}shared-url
85 *
86 * This property MUST contain the url to the original calendar, that is.. the
87 * path to the calendar from the owner.
88 *
89 * 2. {http://sabredav.org/ns}owner-principal
90 *
91 * This is a url to to the principal who is sharing the calendar.
92 *
93 * 3. {http://sabredav.org/ns}read-only
94 *
95 * This should be either 0 or 1, depending on if the user has read-only or
96 * read-write access to the calendar.
97 *
98 * Only when this is done, the calendar will correctly be marked as a calendar
99 * that's shared to him, thus allowing clients to display the correct interface
100 * and ACL enforcement.
101 *
102 * If a sharee deletes their calendar, only their instance of the calendar
103 * should be deleted, the original should still exists.
104 * Pretty much any 'dead' WebDAV properties on these shared calendars should be
105 * specific to a user. This means that if the displayname is changed by a
106 * sharee, the original is not affected. This is also true for:
107 *   * The description
108 *   * The color
109 *   * The order
110 *   * And any other dead properties.
111 *
112 * Properties like a ctag should not be different for multiple instances of the
113 * calendar.
114 *
115 * Lastly, objects *within* calendars should also have user-specific data. The
116 * two things that are user-specific are:
117 *   * VALARM objects
118 *   * The TRANSP property
119 *
120 * This _also_ implies that if a VALARM is deleted by a sharee for some event,
121 * this has no effect on the original VALARM.
122 *
123 * Understandably, the this last requirement is one of the hardest.
124 * Realisticly, I can see people ignoring this part of the spec, but that could
125 * cause a different set of issues.
126 *
127 *
128 * Publishing
129 * ==========
130 *
131 * When a user publishes a url, the server should generate a 'publish url'.
132 * This is a read-only url, anybody can use to consume the calendar feed.
133 *
134 * Calendars are in one of two states:
135 *   * published
136 *   * unpublished
137 *
138 * If a calendar is published, the following property should be returned
139 * for each calendar in getCalendarsForUser.
140 *
141 * {http://calendarserver.org/ns/}publish-url
142 *
143 * This element should contain a {DAV:}href element, which points to the
144 * public url that does not require authentication. Unlike every other href,
145 * this url must be absolute.
146 *
147 * Ideally, the following property is always returned
148 *
149 * {http://calendarserver.org/ns/}pre-publish-url
150 *
151 * This property should contain the url that the calendar _would_ have, if it
152 * were to be published. iCal uses this to display the url, before the user
153 * will actually publish it.
154 *
155 *
156 * Selectively disabling publish or share feature
157 * ==============================================
158 *
159 * If Sabre\CalDAV\Property\AllowedSharingModes is returned from
160 * getCalendarsForUser, this allows the server to specify whether either sharing,
161 * or publishing is supported.
162 *
163 * This allows a client to determine in advance which features are available,
164 * and update the interface appropriately. If this property is not returned by
165 * the backend, the SharingPlugin automatically injects it and assumes both
166 * features are available.
167 *
168 * @copyright Copyright (C) 2007-2015 fruux GmbH (https://fruux.com/).
169 * @author Evert Pot (http://evertpot.com/)
170 * @license http://sabre.io/license/ Modified BSD License
171 */
172interface SharingSupport extends NotificationSupport {
173
174    /**
175     * Updates the list of shares.
176     *
177     * The first array is a list of people that are to be added to the
178     * calendar.
179     *
180     * Every element in the add array has the following properties:
181     *   * href - A url. Usually a mailto: address
182     *   * commonName - Usually a first and last name, or false
183     *   * summary - A description of the share, can also be false
184     *   * readOnly - A boolean value
185     *
186     * Every element in the remove array is just the address string.
187     *
188     * Note that if the calendar is currently marked as 'not shared' by and
189     * this method is called, the calendar should be 'upgraded' to a shared
190     * calendar.
191     *
192     * @param mixed $calendarId
193     * @param array $add
194     * @param array $remove
195     * @return void
196     */
197    function updateShares($calendarId, array $add, array $remove);
198
199    /**
200     * Returns the list of people whom this calendar is shared with.
201     *
202     * Every element in this array should have the following properties:
203     *   * href - Often a mailto: address
204     *   * commonName - Optional, for example a first + last name
205     *   * status - See the Sabre\CalDAV\SharingPlugin::STATUS_ constants.
206     *   * readOnly - boolean
207     *   * summary - Optional, a description for the share
208     *
209     * This method may be called by either the original instance of the
210     * calendar, as well as the shared instances. In the case of the shared
211     * instances, it is perfectly acceptable to return an empty array in case
212     * there are privacy concerns.
213     *
214     * @param mixed $calendarId
215     * @return array
216     */
217    function getShares($calendarId);
218
219    /**
220     * This method is called when a user replied to a request to share.
221     *
222     * If the user chose to accept the share, this method should return the
223     * newly created calendar url.
224     *
225     * @param string href The sharee who is replying (often a mailto: address)
226     * @param int status One of the SharingPlugin::STATUS_* constants
227     * @param string $calendarUri The url to the calendar thats being shared
228     * @param string $inReplyTo The unique id this message is a response to
229     * @param string $summary A description of the reply
230     * @return null|string
231     */
232    function shareReply($href, $status, $calendarUri, $inReplyTo, $summary = null);
233
234    /**
235     * Publishes a calendar
236     *
237     * @param mixed $calendarId
238     * @param bool $value
239     * @return void
240     */
241    function setPublishStatus($calendarId, $value);
242
243}
244