# /CalendarServer/trunk/doc/Extensions/caldav-sharing-02.txt – Calendar and Contacts Server

Calendar and Contacts Server
Search:

# root / CalendarServer / trunk / doc / Extensions / caldav-sharing-02.txt

View revision:

Revision 6401, 53.0 KB (checked in by cdaboo@…, 21 months ago)
Sharing extension specification.

Line |
--- | ---
1 |
2 |
3 |
4 | Calendar Server Extension C. Daboo
5 | E. York
6 | Apple Inc.
7 | October 6, 2010
8 |
9 |
10 | Shared and Published Calendars in CalDAV
11 |
12 | Abstract
13 |
14 | This specification defines an extension to CalDAV that enables the
15 | sharing of calendars between users on a CalDAV server.
16 |
17 |
18 | Table of Contents
19 |
20 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
21 | 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
22 | 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
23 | 4. Notifications . . . . . . . . . . . . . . . . . . . . . . . . 5
24 | 4.1. Additional Principal Properties . . . . . . . . . . . . . 5
25 | 4.1.1. CS:notification-URL Property . . . . . . . . . . . . . 6
26 | 4.2. Properties on Notification Resources . . . . . . . . . . . 6
27 | 4.2.1. CS:notificationtype Property . . . . . . . . . . . . . 6
28 | 5. Shared Calendaring . . . . . . . . . . . . . . . . . . . . . . 7
29 | 5.1. Feature Discovery . . . . . . . . . . . . . . . . . . . . 7
30 | 5.2. Additional Properties for Calendars . . . . . . . . . . . 7
31 | 5.2.1. DAV:resourcetype Property . . . . . . . . . . . . . . 7
32 | 5.2.2. CS:invite Property . . . . . . . . . . . . . . . . . . 8
33 | 5.2.3. CS:allowed-sharing-modes Property . . . . . . . . . . 8
34 | 5.2.4. CS:shared-url Property . . . . . . . . . . . . . . . . 9
35 | 5.3. Sharer Actions on Shared Calendars . . . . . . . . . . . . 9
36 | 5.3.1. Creating a Shared Calendar . . . . . . . . . . . . . . 9
37 | 5.3.1.1. Example: Successful MKCALENDAR Request . . . . . . 10
38 | 5.3.1.2. Example: Successful Extended MKCOL Request . . . . 10
39 | 5.3.2. Sharing an Existing Calendar . . . . . . . . . . . . . 11
40 | 5.3.2.1. Example: Successful PROPPATCH Request . . . . . . 11
41 | 5.3.3. Manipulating Sharees of a Shared Calendar . . . . . . 12
42 | 5.3.3.1. Example: Successful Sharee Add Request . . . . . . 13
43 | 5.3.3.2. Example: Successful Multiple Sharee Change
44 | Request . . . . . . . . . . . . . . . . . . . . . 14
45 | 5.4. Sharee Actions on Shared Calendars . . . . . . . . . . . . 15
46 | 5.4.1. Replying to a Sharing Invite . . . . . . . . . . . . . 15
47 | 5.4.2. Removing a Shared Calendar . . . . . . . . . . . . . . 16
48 | 5.5. General Considerations . . . . . . . . . . . . . . . . . . 16
49 | 5.5.1. Access Levels . . . . . . . . . . . . . . . . . . . . 16
50 | 5.5.2. Allowing or Disallowing Sharing . . . . . . . . . . . 16
51 | 5.5.3. Per-user WebDAV Properties . . . . . . . . . . . . . . 17
52 |
53 |
54 |
55 | Daboo & York [Page 1]
56 |
57 | CalDAV Sharing and Publishing October 2010
58 |
59 |
60 | 5.5.4. Per-user Calendar Data . . . . . . . . . . . . . . . . 17
61 | 5.5.5. Scheduling . . . . . . . . . . . . . . . . . . . . . . 18
62 | 6. XML Element Definitions . . . . . . . . . . . . . . . . . . . 19
63 | 6.1. CS:shared-owner . . . . . . . . . . . . . . . . . . . . . 19
64 | 6.2. CS:shared . . . . . . . . . . . . . . . . . . . . . . . . 20
65 | 6.3. CS:can-be-shared . . . . . . . . . . . . . . . . . . . . . 20
66 | 6.4. CS:can-be-published . . . . . . . . . . . . . . . . . . . 21
67 | 6.5. CS:user . . . . . . . . . . . . . . . . . . . . . . . . . 21
68 | 6.6. CS:invite-noresponse . . . . . . . . . . . . . . . . . . . 21
69 | 6.7. CS:invite-deleted . . . . . . . . . . . . . . . . . . . . 22
70 | 6.8. CS:invite-accepted . . . . . . . . . . . . . . . . . . . . 22
71 | 6.9. CS:invite-declined . . . . . . . . . . . . . . . . . . . . 22
72 | 6.10. CS:invite-invalid . . . . . . . . . . . . . . . . . . . . 23
73 | 6.11. CS:access . . . . . . . . . . . . . . . . . . . . . . . . 23
74 | 6.12. CS:read . . . . . . . . . . . . . . . . . . . . . . . . . 24
75 | 6.13. CS:read-write . . . . . . . . . . . . . . . . . . . . . . 24
76 | 6.14. CS:summary . . . . . . . . . . . . . . . . . . . . . . . . 24
77 | 6.15. CS:invite-notification . . . . . . . . . . . . . . . . . . 25
78 | 6.16. CS:uid . . . . . . . . . . . . . . . . . . . . . . . . . . 25
79 | 6.17. CS:hosturl . . . . . . . . . . . . . . . . . . . . . . . . 25
80 | 6.18. CS:organizer . . . . . . . . . . . . . . . . . . . . . . . 26
81 | 6.19. CS:common-name . . . . . . . . . . . . . . . . . . . . . . 26
82 | 6.20. CS:invite-reply . . . . . . . . . . . . . . . . . . . . . 26
83 | 6.21. CS:in-reply-to . . . . . . . . . . . . . . . . . . . . . . 27
84 | 6.22. CS:notification . . . . . . . . . . . . . . . . . . . . . 27
85 | 6.23. CS:dtstamp . . . . . . . . . . . . . . . . . . . . . . . . 28
86 | 6.24. CS:share . . . . . . . . . . . . . . . . . . . . . . . . . 28
87 | 6.25. CS:set . . . . . . . . . . . . . . . . . . . . . . . . . . 28
88 | 6.26. CS:remove . . . . . . . . . . . . . . . . . . . . . . . . 29
89 | 6.27. CS:shared-as . . . . . . . . . . . . . . . . . . . . . . . 29
90 | 7. Security Considerations . . . . . . . . . . . . . . . . . . . 29
91 | 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29
92 | 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30
93 | 10. Normative References . . . . . . . . . . . . . . . . . . . . . 30
94 | Appendix A. Change History . . . . . . . . . . . . . . . . . . . 30
95 | Appendix B. Change History . . . . . . . . . . . . . . . . . . . 30
96 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 31
97 |
98 |
99 |
100 |
101 |
102 |
103 |
104 |
105 |
106 |
107 |
108 |
109 |
110 |
111 | Daboo & York [Page 2]
112 |
113 | CalDAV Sharing and Publishing October 2010
114 |
115 |
116 | 1. Introduction
117 |
118 | CalDAV [RFC4791] provides a way for calendar users to store calendar
119 | data and exchange this data via scheduling operations. Based on the
120 | WebDAV [RFC4918] protocol, it also includes the ability to manage
121 | access to calendar data via the WebDAV ACL [RFC3744] extension.
122 |
123 | WebDAV ACL [RFC3744] provides a way to manage fine-grained access
124 | controls on WebDAV resources. Whilst this could be used directly to
125 | manage sharing of calendars, experience has shown that client
126 | developers are averse to using it due to its complexity. Instead a
127 | simpler process for sharing calendars is preferred.
128 |
129 | This extension defines a way for individual calendar users to share
130 | calendars with other users. This is done via an "opt-in" process in
131 | which a sharing invite is sent from the sharer to a sharee, allowing
132 | the sharee to accept or decline. If the sharee accepts the sharing
133 | invite, the shared calendar is made available to them in their own
134 | calendar home collection (i.e., alongside their own personal
135 | calendars). HTTP POST operations are used to manage the sharing
136 | invitations and replies, and WebDAV properties are used to expose the
137 | state of shared calendars.
138 |
139 |
140 | 2. Conventions Used in This Document
141 |
142 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
143 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
144 | document are to be interpreted as described in [RFC2119].
145 |
146 | When XML element types in the namespaces "DAV:" and
147 | "urn:ietf:params:xml:ns:caldav" are referenced in this document
148 | outside of the context of an XML fragment, the string "DAV:" and
149 | "CALDAV:" will be prefixed to the element type names respectively.
150 |
151 | The namespace "http://calendarserver.org/ns/" is used for XML
152 | elements defined in this specification. When XML element types in
153 | that namespace are referenced in this document outside of the context
154 | of an XML fragment, the string "CS:" will be prefixed to the element
155 | type names.
156 |
157 | Terms Used:
158 |
159 | Sharer A calendar user who is sharing a calendar with other calendar
160 | users.
161 |
162 |
163 |
164 |
165 |
166 |
167 | Daboo & York [Page 3]
168 |
169 | CalDAV Sharing and Publishing October 2010
170 |
171 |
172 | Sharee A calendar user to whom a calendar has been shared.
173 |
174 | Sharing Invite A message sent by a sharer to a sharee to indicate
175 | the status of a shared calendar.
176 |
177 | Sharing Reply A message sent by a sharee to a sharer to indicate the
178 | status of a shared calendar.
179 |
180 |
181 | 3. Overview
182 |
183 | This section provides a basic overview of this protocol by way of a
184 | simple use case of a sharer sharing a calendar with a single sharee.
185 |
186 | To share a calendar with another user, the sharer's client executes
187 | an HTTP POST request against the calendar collection resource for the
188 | calendar to be shared. The POST request body will contain details of
189 | the calendar user to whom the calendar is to be shared as well as the
190 | access right to be granted to them. If the request succeeds, a
191 | notification is sent to the sharee with details of the calendar being
192 | shared to them.
193 |
194 | The sharer's client will show the notification to the sharee and
195 | present them with the choice to accept or decline the invitation to
196 | the shared calendar. If the sharee chooses to decline, then nothing
197 | changes for that sharee. If the sharee chooses to accept, then the
198 | server automatically creates a new calendar collection resource in
199 | the sharee's calendar home collection, and ensures that calendar
200 | provides a mapping to the actual shared calendar of the sharer. Thus
201 | the shared calendar is available to the sharee as just another
202 | calendar in their calendar home. The server enforces the appropriare
203 | access privileges for the sharee.
204 |
205 | At any time, the sharer can inspect properties on the calendar
206 | collection being shared, and determine the accept/decline status of
207 | each sharee. Additional sharees can be added and existing ones
208 | removed. The access privileges for existing sharees can also be
209 | changed.
210 |
211 | Once a sharee has a shared calendar set to appear in their calendar
212 | home collection, they can remove it and decline the sharing invite by
213 | simply having their client issue an HTTP DELETE request on the shared
214 | calendar collection. That does not delete any calendar data, but
215 | rather simply removes the "link" to the sharer's calendar collection
216 | and sets the sharee's inviate status to declined.
217 |
218 |
219 |
220 |
221 |
222 |
223 | Daboo & York [Page 4]
224 |
225 | CalDAV Sharing and Publishing October 2010
226 |
227 |
228 | 4. Notifications
229 |
230 | In order to facilitate the process of sharing invitations, this
231 | specification defines a new generic notification mechanism for CalDAV
232 | servers. When this feature is available, a CS:notification-URL
233 | (Section 4.1.1) property appears on principal resources for those
234 | principals who are able to receive notifications. That property
235 | specifies a single DAV:href element whose content refers to a WebDAV
236 | collection resource. Notification "messages" are deposited into this
237 | collection and can be retrieved by clients and acted on accordingly.
238 |
239 | The notification collection referenced by the CS:notification-URL
240 | (Section 4.1.1) property MUST have a DAV:resourcetype property with
241 | DAV:collection and CS:notification (Section 6.22) child elements.
242 |
243 | Notification "messages" are XML documents stored as resources in the
244 | notification collection. Each XML document contains a CS:
245 | notification (Section 6.22) element as its root. The root element
246 | contains a CS:dtstamp (Section 6.23) element, and one additional
247 | element which represents the type of notification being conveyed in
248 | the message. That child element will typically contain additional
249 | content that describes the notification.
250 |
251 | Each notification resource has a CS:notificationtype (Section 4.2.1)
252 | property which contains as its single child element an empty element
253 | that matches the child element of the notification resource XML
254 | document root. Any attributes on the child element in the XML
255 | document are also present in the property child element.
256 |
257 | Notifications are automatically generated by the server (perhaps in
258 | response to a client action) with an appropriate resource stored in
259 | the notifications collection of the user to whom the notification is
260 | targeted. Clients SHOULD monitor the notification collection looking
261 | for new notification resources. When doing so, clients SHOULD look
262 | at the CS:notificationtype (Section 4.2.1) property to ensure that
263 | the notification is of a type that the client can handle. Once a
264 | client has handled the notification in whatever way is appropriate it
265 | SHOULD delete the notification resource. Servers MAY delete
266 | notification resources on their own if they determine that the
267 | notifications are no longer relevant or valid. Servers MAY coalesce
268 | notifications as appropriate.
269 |
270 | 4.1. Additional Principal Properties
271 |
272 | This section defines new properties for WebDAV principal resources as
273 | defined in RFC3744 [RFC3744]. These properties are likely to be
274 | protected but the server MAY allow them to be written by appropriate
275 | users.
276 |
277 |
278 |
279 | Daboo & York [Page 5]
280 |
281 | CalDAV Sharing and Publishing October 2010
282 |
283 |
284 | 4.1.1. CS:notification-URL Property
285 |
286 | Name: notification-URL
287 |
288 | Namespace: http://calendarserver.org/ns/
289 |
290 | Purpose: Identify the URL of the notification collection owned by
291 | the associated principal resource.
292 |
293 | Protected: This property SHOULD be protected.
294 |
295 | PROPFIND behavior: This property SHOULD NOT be returned by a
296 | PROPFIND allprop request (as defined in Section 14.2 of
297 | [RFC4918]).
298 |
299 | COPY/MOVE behavior: This property value SHOULD be preserved in COPY
300 | and MOVE operations.
301 |
302 | Description: This property is needed for a client to determine where
303 | the notification collection of the current user is located so that
304 | processing of notification messages can occur. If not present,
305 | then the associated calendar user is not enabled for notification
306 | messages on the server.
307 |
308 | Definition:
309 |
310 | <!ELEMENT notification-URL (DAV:href)>
311 |
312 | 4.2. Properties on Notification Resources
313 |
314 | The following new WebDAV properties are defined for notification
315 | resources.
316 |
317 | 4.2.1. CS:notificationtype Property
318 |
319 | Name: notificationtype
320 |
321 | Namespace: http://calendarserver.org/ns/
322 |
323 | Purpose: Identify the type of notification of the corresponding
324 | resource.
325 |
326 | Protected: This property MUST be protected.
327 |
328 | PROPFIND behavior: This property SHOULD NOT be returned by a
329 | PROPFIND allprop request (as defined in Section 14.2 of
330 | [RFC4918]).
331 |
332 |
333 |
334 |
335 | Daboo & York [Page 6]
336 |
337 | CalDAV Sharing and Publishing October 2010
338 |
339 |
340 | COPY/MOVE behavior: This property value MUST be preserved in COPY
341 | and MOVE operations.
342 |
343 | Description: This property allows a client, via a PROPFIND Depth:1
344 | request, to quickly find notification messages that the client can
345 | handle in a notification collection. The single child element is
346 | the notification resource root element's child defining the
347 | notification itself. This element MUST be empty, though any
348 | attributes on the element in the notification resource MUST be
349 | present in the property element.
350 |
351 | Definition:
352 |
353 | <!ELEMENT notificationtype (invite-notification | invite-reply)>
354 | <!-- Child elements are empty but will have appropriate attributes.
355 | Any valid notification message child element can appear.-->
356 |
357 |
358 | 5. Shared Calendaring
359 |
360 | 5.1. Feature Discovery
361 |
362 | A server that supports the features described in this document MUST
363 | include "calendarserver-sharing" as a field in the DAV response
364 | header from an OPTIONS request on any resource that supports these
365 | features.
366 |
367 | 5.2. Additional Properties for Calendars
368 |
369 | The following new or modified WebDAV properties are defined for
370 | calendar collections and used to view or manipulate shared calendar
371 | features.
372 |
373 | 5.2.1. DAV:resourcetype Property
374 |
375 | Calendar collections that are shared have addition elements listed in
376 | their DAV:resourcetype property in addition to DAV:collection and
377 | CALDAV:calendar.
378 |
379 | o CS:shared-owner (Section 6.1): used to indicate that the calendar
380 | is owned by the current user and is being shared by them.
381 |
382 | o CS:shared (Section 6.2): used to indicate that the calendar is
383 | owned by another user and is being shared to the current user.
384 |
385 |
386 |
387 |
388 |
389 |
390 |
391 | Daboo & York [Page 7]
392 |
393 | CalDAV Sharing and Publishing October 2010
394 |
395 |
396 | 5.2.2. CS:invite Property
397 |
398 | Name: invite
399 |
400 | Namespace: http://calendarserver.org/ns/
401 |
402 | Purpose: Used to show to whom a calendar has been shared.
403 |
404 | Protected: This property MUST be protected.
405 |
406 | PROPFIND behavior: This property SHOULD NOT be returned by a
407 | PROPFIND allprop request (as defined in Section 14.2 of
408 | [RFC4918]).
409 |
410 | COPY/MOVE behavior: This property value MUST be preserved in COPY
411 | and MOVE operations.
412 |
413 | Description: This WebDAV property is present on a calendar
414 | collection resource that has been shared by the owner. It MUST
415 | NOT appear on the calendar collection resources of the sharees of
416 | the calendar. It provides a list of users to whom the calendar
417 | has been shared, along with the "status" of the sharing invites
418 | sent to each user.
419 |
420 | Definition:
421 |
422 | <!ELEMENT invite (user*)>
423 |
424 | 5.2.3. CS:allowed-sharing-modes Property
425 |
426 | Name: allowed-sharing-modes
427 |
428 | Namespace: http://calendarserver.org/ns/
429 |
430 | Purpose: Used to show which modes of sharing are supported on a
431 | calendar collection.
432 |
433 | Protected: This property MUST be protected.
434 |
435 | PROPFIND behavior: This property SHOULD NOT be returned by a
436 | PROPFIND allprop request (as defined in Section 14.2 of
437 | [RFC4918]).
438 |
439 | COPY/MOVE behavior: This property value MUST be preserved in COPY
440 | and MOVE operations.
441 |
442 |
443 |
444 |
445 |
446 |
447 | Daboo & York [Page 8]
448 |
449 | CalDAV Sharing and Publishing October 2010
450 |
451 |
452 | Description: This WebDAV property is present on a calendar
453 | collection resource that can been shared or published. It
454 | provides a list of options indicating what sharing modes are
455 | allowed as per Section 5.5.2.
456 |
457 | Definition:
458 |
459 | <!ELEMENT allowed-sharing-modes
460 | (can-be-shared?, can-be-published?)>
461 |
462 | 5.2.4. CS:shared-url Property
463 |
464 | Name: shared-url
465 |
466 | Namespace: http://calendarserver.org/ns/
467 |
468 | Purpose: Indicates the URL of the owner's copy of a shared calendar.
469 |
470 | Protected: This property MUST be protected.
471 |
472 | PROPFIND behavior: This property SHOULD NOT be returned by a
473 | PROPFIND allprop request (as defined in Section 14.2 of
474 | [RFC4918]).
475 |
476 | COPY/MOVE behavior: This property value MUST be preserved in COPY
477 | and MOVE operations.
478 |
479 | Description: This WebDAV property is present on a shared calendar
480 | collection resource that appears in a sharee's calendar home
481 | collection. Its content is a single DAV:href element whose value
482 | is the URL of the sharer's calendar being shared.
483 |
484 | Definition:
485 |
486 | <!ELEMENT shared-url (DAV:href)>
487 |
488 | 5.3. Sharer Actions on Shared Calendars
489 |
490 | 5.3.1. Creating a Shared Calendar
491 |
492 | To create a shared calendar, clients use the MKCALENDAR [RFC4791] or
493 | extended MKCOL [RFC5689] requests, and include a DAV:resourcetype
494 | property to be set upon creation. That property MUST contain DAV:
495 | collection, CALDAV:calendar and CS:shared-owner child elements to
496 | enable sharing.
497 |
498 |
499 |
500 |
501 |
502 |
503 | Daboo & York [Page 9]
504 |
505 | CalDAV Sharing and Publishing October 2010
506 |
507 |
508 | 5.3.1.1. Example: Successful MKCALENDAR Request
509 |
510 | This example shows how the MKCALENDAR request is used to create a
511 | shared calendar collection. The response body is empty as the
512 | request completed successfully.
513 |
514 | >> Request <<
515 |
516 | MKCALENDAR /calendars/users/cyrus/shared/ HTTP/1.1
517 | Host: calendar.example.com
518 | Content-Type: application/xml; charset="utf-8"
519 | Content-Length: xxxx
520 |
521 | <?xml version="1.0" encoding="utf-8" ?>
522 | <C:mkcalendar xmlns:D="DAV:"
523 | xmlns:C="urn:ietf:params:xml:ns:caldav"
524 | xmlns:CS="http://calendarserver.org/ns/">
525 | <D:set>
526 | <D:prop>
527 | <D:resourcetype>
528 | <D:collection/>
529 | <C:calendar/>
530 | <CS:shared-owner/>
531 | </D:resourcetype>
532 | </D:prop>
533 | </D:set>
534 | </C:mkcalendar>
535 |
536 | >> Response <<
537 |
538 | HTTP/1.1 201 Created
539 | Cache-Control: no-cache
540 | Date: Sat, 11 Nov 2006 09:32:12 GMT
541 |
542 | 5.3.1.2. Example: Successful Extended MKCOL Request
543 |
544 | This example shows how the extended MKCOL request is used to create a
545 | shared calendar collection. The response body is empty as the
546 | request completed successfully.
547 |
548 |
549 |
550 |
551 |
552 |
553 |
554 |
555 |
556 |
557 |
558 |
559 | Daboo & York [Page 10]
560 |
561 | CalDAV Sharing and Publishing October 2010
562 |
563 |
564 | >> Request <<
565 |
566 | MKCOL /calendars/users/cyrus/shared/ HTTP/1.1
567 | Host: calendar.example.com
568 | Content-Type: application/xml; charset="utf-8"
569 | Content-Length: xxxx
570 |
571 | <?xml version="1.0" encoding="utf-8" ?>
572 | <D:mkcol xmlns:D="DAV:"
573 | xmlns:C="urn:ietf:params:xml:ns:caldav"
574 | xmlns:CS="http://calendarserver.org/ns/">
575 | <D:set>
576 | <D:prop>
577 | <D:resourcetype>
578 | <D:collection/>
579 | <C:calendar/>
580 | <CS:shared-owner/>
581 | </D:resourcetype>
582 | </D:prop>
583 | </D:set>
584 | </D:mkcol>
585 |
586 | >> Response <<
587 |
588 | HTTP/1.1 201 Created
589 | Cache-Control: no-cache
590 | Date: Sat, 11 Nov 2006 09:32:12 GMT
591 |
592 | 5.3.2. Sharing an Existing Calendar
593 |
594 | Sharing an existing calendar can be accomplished in two ways. One
595 | option is to use a PROPPATCH request to set the DAV:resourcetype
596 | property to include CS:shared-owner as a child element. Another
597 | option is to add sharee's directly to the calendar collection (as
598 | described in Section 5.3.3) - that action MUST upgrade a non-shared
599 | calendar to a shared calendar when it completes successfully,
600 | assuming that such an upgrade is allowed as per Section 5.5.2.
601 |
602 | 5.3.2.1. Example: Successful PROPPATCH Request
603 |
604 | This example shows how the PROPPATCH request is used to upgrade to a
605 | shared calendar collection.
606 |
607 |
608 |
609 |
610 |
611 |
612 |
613 |
614 |
615 | Daboo & York [Page 11]
616 |
617 | CalDAV Sharing and Publishing October 2010
618 |
619 |
620 | >> Request <<
621 |
622 | PROPPATCH /calendars/users/cyrus/shared/ HTTP/1.1
623 | Host: calendar.example.com
624 | Content-Type: application/xml; charset="utf-8"
625 | Content-Length: xxxx
626 |
627 | <?xml version="1.0" encoding="utf-8" ?>
628 | <D:propertyupdate xmlns:D="DAV:"
629 | xmlns:C="urn:ietf:params:xml:ns:caldav"
630 | xmlns:CS="http://calendarserver.org/ns/">
631 | <D:set>
632 | <D:prop>
633 | <D:resourcetype>
634 | <D:collection/>
635 | <C:calendar/>
636 | <CS:shared-owner/>
637 | </D:resourcetype>
638 | </D:prop>
639 | </D:set>
640 | </D:propertyupdate>
641 |
642 | >> Response <<
643 |
644 | HTTP/1.1 207 Multi-Status
645 | Date: Sat, 11 Nov 2006 09:32:12 GMT
646 | Content-Type: application/xml; charset="utf-8"
647 | Content-Length: xxxx
648 |
649 | <?xml version="1.0" encoding="utf-8" ?>
650 | <D:multistatus xmlns:D="DAV:">
651 | <D:response>
652 | <D:href>/calendars/users/cyrus/shared/</D:href>
653 | <D:propstat>
654 | <D:prop>
655 | <D:resourcetype/>
656 | </D:prop>
657 | <D:status>HTTP/1.1 200 OK</D:status>
658 | </D:propstat>
659 | </D:response>
660 | </D:multistatus>
661 |
662 | 5.3.3. Manipulating Sharees of a Shared Calendar
663 |
664 | The sharer of a shared calendar is able to manipulate the sharee list
665 | by issuing a POST request targeted at the shared calendar collection
666 | resource. The POST request MUST contain an XML document as its body
667 | with the root element being CS:share (Section 6.24).
668 |
669 |
670 |
671 | Daboo & York [Page 12]
672 |
673 | CalDAV Sharing and Publishing October 2010
674 |
675 |
676 | The CS:share (Section 6.24) element in the POST requests MUST contain
677 | one or more CS:set (Section 6.25) or CS:remove (Section 6.26)
678 | elements. For each CS:set (Section 6.25) element, the server MUST
679 | add the specified sharee access to the shared calendar. For each CS:
680 | remove (Section 6.26) element the server MUST remove the specified
681 | sharee access from the shared calendar. In each case the server MUST
682 | send a notification message to any sharees whose status is changed
683 | (added, modified or removed), indicating to them a change in status
684 | for the shared calendar. The server SHOULD NOT send notification
685 | messages to sharees whose status is unchanged.
686 |
687 | Sharee's are identified via a DAV:href element whose value is either
688 | a principal-URL for a sharee hosted on the same server, a calendar
689 | user address or email address. In the case of the later two, the
690 | sharee might not be a user on the same server - though in that case
691 | how invitations are sent or access enabled is out of scope for this
692 | specification. A server MAY change the sharee's "address" to any
693 | suitable alternative that it might prefer when returning the list of
694 | sharees via the CS:invite property (Section 5.2.2).
695 |
696 | The client MAY include a CS:common-name (Section 6.19) element in the
697 | CS:set (Section 6.25) element. When provided, the value represents
698 | the common name for the sharee, and is returned in the list of
699 | sharees via the CS:invite property (Section 5.2.2). The server MAY
700 | change this to a suitable alternative when it is able to match the
701 | sharee to a known user. If absent from the client request, the
702 | server SHOULD add a CS:common-name when it is able to match the
703 | sharee with a known user, and a common name for that user can be
704 | determined.
705 |
706 | When the sharee list on a shared calendar is changed, the server MUST
707 | send notifications to each sharee to update them on their current
708 | sharing status. This is accomplished by sending a CS:invite-
709 | notification (Section 6.15) notification to each sharee.
710 |
711 | 5.3.3.1. Example: Successful Sharee Add Request
712 |
713 | This example shows how to add a single sharee (with calendar user
714 | address "mailto:eric@example.com") to a shared calendar with CS:read-
715 | write access.
716 |
717 |
718 |
719 |
720 |
721 |
722 |
723 |
724 |
725 |
726 |
727 | Daboo & York [Page 13]
728 |
729 | CalDAV Sharing and Publishing October 2010
730 |
731 |
732 | >> Request <<
733 |
734 | POST /calendars/users/cyrus/shared/ HTTP/1.1
735 | Host: calendar.example.com
736 | Content-Type: application/xml; charset="utf-8"
737 | Content-Length: xxxx
738 |
739 | <?xml version="1.0" encoding="utf-8" ?>
740 | <CS:share xmlns:D="DAV:"
741 | xmlns:CS="http://calendarserver.org/ns/">
742 | <CS:set>
743 | <D:href>mailto:eric@example.com</D:href>
744 | <CS:common-name>Eric York</CS:common-name>
745 | <CS:summary>Shared workspace</CS:summary>
746 | <CS:read-write />
747 | </CS:set>
748 | </CS:share>
749 |
750 | >> Response <<
751 |
752 | HTTP/1.1 200 OK
753 | Cache-Control: no-cache
754 | Date: Sat, 11 Nov 2006 09:32:12 GMT
755 |
756 | 5.3.3.2. Example: Successful Multiple Sharee Change Request
757 |
758 | This example shows how multiple sharee's can be manipulated in a
759 | single request. The sharee with calendar user address
760 | "mailto:eric@example.com" has their access downgraded to CS:read,
761 | whilst another sharee is removed from the access list entirely.
762 |
763 |
764 |
765 |
766 |
767 |
768 |
769 |
770 |
771 |
772 |
773 |
774 |
775 |
776 |
777 |
778 |
779 |
780 |
781 |
782 |
783 | Daboo & York [Page 14]
784 |
785 | CalDAV Sharing and Publishing October 2010
786 |
787 |
788 | >> Request <<
789 |
790 | POST /calendars/users/cyrus/shared/ HTTP/1.1
791 | Host: calendar.example.com
792 | Content-Type: application/xml; charset="utf-8"
793 | Content-Length: xxxx
794 |
795 | <?xml version="1.0" encoding="utf-8" ?>
796 | <CS:share xmlns:D="DAV:"
797 | xmlns:CS="http://calendarserver.org/ns/">
798 | <CS:set>
799 | <D:href>mailto:eric@example.com</D:href>
800 | <CS:summary>Shared workspace</CS:summary>
801 | <CS:read-write />
802 | </CS:set>
803 | <CS:remove>
804 | <D:href>mailto:wilfredo@example.com</D:href>
805 | </CS:remove>
806 | </CS:share>
807 |
808 | >> Response <<
809 |
810 | HTTP/1.1 200 OK
811 | Cache-Control: no-cache
812 | Date: Sat, 11 Nov 2006 09:32:12 GMT
813 |
814 | 5.4. Sharee Actions on Shared Calendars
815 |
816 | 5.4.1. Replying to a Sharing Invite
817 |
818 | When a sharee is invited to a shared calendar they can accept or
819 | decline the invite by issuing a POST request to the sharee's calendar
820 | home collection resource. The POST request MUST contain an XML
821 | document as its body with the root element being CS:invite-reply
822 | (Section 6.20).
823 |
824 | The CS:invite-reply (Section 6.20) element in the POST request
825 | specifies the sharee who is replying in the DAV:href element, the
826 | accept or decline action via the CS:invite-accepted or CS:invite-
827 | declined elements, the URL of the shared calendar in the CS:hosturl
828 | element, the unique identifier of the invite to which it is a reply
829 | in the CS:in-reply-to element, and an optional CS:summary element.
830 |
831 | The response to a POST request that accepts a shared calendar invite
832 | MUST be an XML document containing CS:shared-as (Section 6.27) as its
833 | root element. That root element contains a single DAV:href element
834 | whose content is the URI of the shared calendar in the sharee's
835 | calendar home created by the invite acceptance.
836 |
837 |
838 |
839 | Daboo & York [Page 15]
840 |
841 | CalDAV Sharing and Publishing October 2010
842 |
843 |
844 | When the sharee replies to an invite, the server SHOULD send a
845 | notification to the sharer to update them on the change in the sharee
846 | state. This is accomplished by sending a CS:invite-reply
847 | (Section 6.20) notification to the sharer.
848 |
849 | 5.4.2. Removing a Shared Calendar
850 |
851 | To remove a shared calendar from a sharee's calendar home collection
852 | a DELETE request is targeted at the shared calendar URI. When such a
853 | request is received the server MUST remove the shared calendar from
854 | the sharee's calendar home and automatically update the sharee's
855 | status in the sharer's calendar's CS:invite property.
856 |
857 | 5.5. General Considerations
858 |
859 | 5.5.1. Access Levels
860 |
861 | Two levels of access ca be granted by a sharer to any sharee. These
862 | are governed by the CS:access element used in the CS:invite/CS:user
863 | element that specifies a shared user invite. CS:access contains a
864 | single empty element that defines the type of access granted:
865 |
866 | CS:read When present this indicates that sharees can read calendar
867 | data but cannot change it.
868 |
869 | CS:read-write When present this indicates that sharees can read and
870 | write calendar data.
871 |
872 | 5.5.2. Allowing or Disallowing Sharing
873 |
874 | Servers MAY support calendar sharing on a per-calendar basis - e.g.,
875 | they could treat some calendars as always private (cannot be shared)
876 | or always public (always shared). As a result clients need a way to
877 | determine which calendar could be shared so they can enable or
878 | disable sharing options on a per-calendar basis.
879 |
880 | This specification adds a CS:allowed-sharing-modes (Section 5.2.3)
881 | WebDAV property which servers can return on calendar collection
882 | resources. This property contains XML elements that describe which
883 | sharing or publishing capabilities can be supported by the
884 | corresponding calendar collection:
885 |
886 | CS:can-be-shared (Section 6.3): when present indicates that the
887 | calendar collection can be shared. When not present, the calendar
888 | collection cannot be shared.
889 |
890 | CS:can-be-published (Section 6.4): when present indicates that the
891 | calendar collection can be published. When not present, the
892 |
893 |
894 |
895 | Daboo & York [Page 16]
896 |
897 | CalDAV Sharing and Publishing October 2010
898 |
899 |
900 | calendar collection cannot be published.
901 |
902 | When not present on a calendar collection, sharing or publishing of
903 | that calendar is not allowed. Clients SHOULD NOT attempt to use
904 | requests to enable sharing or publishing targeted at those calendar
905 | collections.
906 |
907 | 5.5.3. Per-user WebDAV Properties
908 |
909 | Servers MUST support "per-user" WebDAV properties on shared calendar
910 | collections and MAY support them on calendar object resources within
911 | shared calendar collections. A "per-user" WebDAV property is one
912 | whose value can be set and retrieved independently by each user with
913 | appropriate access rights. e.g., user "A" changes the DAV:displayname
914 | property on a shared calendar in their calendar home to "My
915 | calendar", and user "B" changes the same property to "Shared" on the
916 | same shared calendar in their calendar home. When each user
917 | retrieves the property value they will see their own last stored
918 | value and not the value of the other user.
919 |
920 | For shared calendars, the server MUST allow all users to write "per-
921 | user" WebDAV properties on the shared calendar collection and MAY
922 | allow property writes on calendar object resources within the shared
923 | calendar collection. This is required even in the case where the
924 | sharee has been granted read access only (i.e., the ability to change
925 | calendar data is disallowed). This requirement ensures that sharees
926 | can always change "personal" properties such as calendar colors and
927 | display names.
928 |
929 | Servers MUST treat the following properties as "per-user":
930 |
931 | DAV:displayname
932 |
933 | CALDAV:calendar-description
934 |
935 | CALDAV:schedule-calendar-transp
936 |
937 | ICAL:calendar-color
938 |
939 | Servers MAY treat any dead property as per-user.
940 |
941 | Servers MUST NOT treat live properties as per-user.
942 |
943 | 5.5.4. Per-user Calendar Data
944 |
945 | Servers MUST support "per-user" calendar data in calendar object
946 | resources stored in shared calendars. This allows each sharee and
947 | the sharer to store their own alarms and free busy transparency
948 |
949 |
950 |
951 | Daboo & York [Page 17]
952 |
953 | CalDAV Sharing and Publishing October 2010
954 |
955 |
956 | status without "interfering" with other users who also have access to
957 | the same calendar object resources.
958 |
959 | For calendaring object resources in shared calendar collections, the
960 | server MUST treat the following iCalendar data objects as per-user:
961 |
962 | TRANSP property
963 |
964 | VALARM component
965 |
966 | Servers MAY treat any non-standard X- iCalendar properties as per-
967 | user.
968 |
969 | When handling per-user data in recurring components, servers SHOULD
970 | eliminate overridden instances when returning iCalendar data to
971 | clients in the case where there are no differences between the
972 | overridden component and the instance that could be derived from the
973 | "master" recurrence component. For example, consider a daily
974 | recurring event, Monday through Friday, initially defined without any
975 | overridden instances, that is in a shared calendar. If user "A"
976 | overrides the Tuesday instance and adds their own "VALARM" component
977 | only, then when user "A" later retrieves the data again they would
978 | see that overridden instance, but when user "B" does so, they would
979 | not. This ensures that each user sees the most "compact"
980 | representation of the calendar data.
981 |
982 | 5.5.5. Scheduling
983 |
984 | CalDAV Scheduling [I-D.desruisseaux-caldav-sched] defines how a
985 | CalDAV server carries out scheduling operations when calendar object
986 | resources are created, modified or deleted and include "ORGANIZER"
987 | and "ATTENDEE" iCalendar properties.
988 |
989 | When calendar object resources are created, modified or deleted in
990 | shared calendars by sharees, the following restrictions apply:
991 |
992 | 1. The "ORGANIZER" iCalendar property value in the iCalendar data
993 | MUST match a calendar user address of the sharer (owner) of the
994 | shared calendar. The DAV:owner WebDAV property MUST be present
995 | on a shared calendar and MUST provide a reference to a principal-
996 | URL of the sharer (owner) of the shared calendar. Clients can
997 | use this value to determine what the allowed "ORGANIZER"
998 | iCalendar property values are. The server MUST reject any
999 | attempt by a sharee to create an iCalendar component with an
1000 | "ORGANIZER" property value other than the sharer (owner) of the
1001 | shared calendar.
1002 |
1003 |
1004 |
1005 |
1006 |
1007 | Daboo & York [Page 18]
1008 |
1009 | CalDAV Sharing and Publishing October 2010
1010 |
1011 |
1012 | 2. The server MUST reject any attempt by a sharee to MOVE a calendar
1013 | object resource in a shared calendar to some other collection.
1014 |
1015 | 3. When a sharee is listed as an Attendee in a calendar object
1016 | resource in a shared calendar, and write access is granted, the
1017 | sharee is allowed to change not only iCalendar data related to
1018 | the Organizer, but also data related to the Attendee. i.e., a
1019 | sharee can change their own participation status on the
1020 | "ATTENDEE" iCalendar property referring to them. Additionally,
1021 | if the sharee is not listed as an Attendee, and write access is
1022 | granted, the sharee can add themselves as an Attendee.
1023 |
1024 | 4. The default calendar collection defined in Section 6.3 of
1025 | [I-D.desruisseaux-caldav-sched] MUST NOT be a calendar shared to
1026 | the corresponding calendar user.
1027 |
1028 | Following are additional considerations for scheduling with shared
1029 | calendars:
1030 |
1031 | 1. A scheduled iCalendar component could appear in more than one
1032 | calendar collection within a sharee's calendar home if the sharee
1033 | is an Attendee and the Organizer or other Attendees have shared a
1034 | calendar with the sharee that includes their copies of the
1035 | iCalendar component. It is important to note that the scheduled
1036 | component in the shared calendar could have different access
1037 | rights than the one in the sharee's owned calendar.
1038 |
1039 | 2. A scheduled iCalendar component appearing in a sharee's shared
1040 | calendar could include the sharee as an Attendee. For recurring
1041 | events, it is possible for the sharee to only be listed as an
1042 | Attendee in some instances, as opposed to all. Clients will need
1043 | to be aware of this when allowing sharee's to set their own
1044 | participation status.
1045 |
1046 | In addition, when a shared calendar is first accepted by a sharee,
1047 | the server SHOULD set the CALDAV:schedule-calendar-transp property to
1048 | the value CALDAV:transparent to ensure newly accepted shared
1049 | calendars do not contribute to the sharee's freebusy time until the
1050 | sharee explicitly requests it.
1051 |
1052 |
1053 | 6. XML Element Definitions
1054 |
1055 | 6.1. CS:shared-owner
1056 |
1057 |
1058 |
1059 |
1060 |
1061 |
1062 |
1063 | Daboo & York [Page 19]
1064 |
1065 | CalDAV Sharing and Publishing October 2010
1066 |
1067 |
1068 | Name: shared-owner
1069 |
1070 | Namespace: http://calendarserver.org/ns/
1071 |
1072 | Purpose: Used to indicate that a calendar is being shared by the
1073 | owner.
1074 |
1075 | Description: This property appears in the DAV:resourcetype property
1076 | on the calendar collection resource shared by a sharer. See
1077 | Section 5.2.
1078 |
1079 | Definition:
1080 |
1081 | <!ELEMENT shared-owner EMPTY>
1082 |
1083 | 6.2. CS:shared
1084 |
1085 | Name: shared
1086 |
1087 | Namespace: http://calendarserver.org/ns/
1088 |
1089 | Purpose: Used to indicate that a calendar is being shared to a
1090 | sharee.
1091 |
1092 | Description: This property appears in the DAV:resourcetype property
1093 | on a calendar collection resource that is shared to a sharee and
1094 | appears in the sharee's calendar home collection. See
1095 | Section 5.2.
1096 |
1097 | Definition:
1098 |
1099 | <!ELEMENT shared EMPTY>
1100 |
1101 | 6.3. CS:can-be-shared
1102 |
1103 | Name: can-be-shared
1104 |
1105 | Namespace: http://calendarserver.org/ns/
1106 |
1107 | Purpose: Used to indicate that a calendar can be shared.
1108 |
1109 | Description: This element indicates that a calendar can be shared
1110 | with other users. See Section 5.2.3
1111 |
1112 | Definition:
1113 |
1114 | <!ELEMENT can-be-shared EMPTY>
1115 |
1116 |
1117 |
1118 |
1119 | Daboo & York [Page 20]
1120 |
1121 | CalDAV Sharing and Publishing October 2010
1122 |
1123 |
1124 | 6.4. CS:can-be-published
1125 |
1126 | Name: can-be-published
1127 |
1128 | Namespace: http://calendarserver.org/ns/
1129 |
1130 | Purpose: Used to indicate that a calendar can be published.
1131 |
1132 | Description: This element indicates that a calendar can be published
1133 | to anyone. See Section 5.2.3
1134 |
1135 | Definition:
1136 |
1137 | <!ELEMENT can-be-published EMPTY>
1138 |
1139 | 6.5. CS:user
1140 |
1141 | Name: user
1142 |
1143 | Namespace: http://calendarserver.org/ns/
1144 |
1145 | Purpose: Used to show status of sharing invites sent to sharees.
1146 |
1147 | Description: This element provides the "status" of a sharing invite
1148 | sent to a particular user. See Section 5.2.2.
1149 |
1150 | Definition:
1151 |
1152 | <!ELEMENT user (DAV:href, common-name?, (invite-noresponse |
1153 | invite-accepted | invite-declined | invite-invalid),
1154 | access, summary?)>
1155 |
1156 | 6.6. CS:invite-noresponse
1157 |
1158 | Name: invite-noresponse
1159 |
1160 | Namespace: http://calendarserver.org/ns/
1161 |
1162 | Purpose: Sharing invite status.
1163 |
1164 | Description: When used in a CS:user (Section 6.5) element, this
1165 | element is used to indicate that the sharee has never replied to
1166 | the corresponding sharing invite. When used in a CS:invite-
1167 | notification (Section 6.15) element, this element is used to
1168 | indicate to the sharee that a sharing reply is needed.
1169 |
1170 |
1171 |
1172 |
1173 |
1174 |
1175 | Daboo & York [Page 21]
1176 |
1177 | CalDAV Sharing and Publishing October 2010
1178 |
1179 |
1180 | Definition:
1181 |
1182 | <!ELEMENT invite-noresponse EMPTY>
1183 |
1184 | 6.7. CS:invite-deleted
1185 |
1186 | Name: invite-deleted
1187 |
1188 | Namespace: http://calendarserver.org/ns/
1189 |
1190 | Purpose: Sharing invite status.
1191 |
1192 | Description: When used in a CS:invite-notification (Section 6.15)
1193 | element, this element is used to indicate to the sharee that a
1194 | shared calendar has been unshared by the sharer.
1195 |
1196 | Definition:
1197 |
1198 | <!ELEMENT invite-deleted EMPTY>
1199 |
1200 | 6.8. CS:invite-accepted
1201 |
1202 | Name: invite-accepted
1203 |
1204 | Namespace: http://calendarserver.org/ns/
1205 |
1206 | Purpose: Sharing invite status.
1207 |
1208 | Description: When used in a CS:user (Section 6.5) element, this
1209 | element is used to indicate that the sharee has accepted the
1210 | corresponding sharing invite. When used in a CS:invite-
1211 | notification (Section 6.15) element, this element is used to
1212 | indicate to the sharee that the sharing invite is an update for
1213 | one they previously accepted.
1214 |
1215 | Definition:
1216 |
1217 | <!ELEMENT invite-accepted EMPTY>
1218 |
1219 | 6.9. CS:invite-declined
1220 |
1221 | Name: invite-declined
1222 |
1223 | Namespace: http://calendarserver.org/ns/
1224 |
1225 |
1226 |
1227 |
1228 |
1229 |
1230 |
1231 | Daboo & York [Page 22]
1232 |
1233 | CalDAV Sharing and Publishing October 2010
1234 |
1235 |
1236 | Purpose: Sharing invite status.
1237 |
1238 | Description: When used in a CS:user (Section 6.5) element, this
1239 | element is used to indicate that the sharee has declined the
1240 | corresponding sharing invite. When used in a CS:invite-
1241 | notification (Section 6.15) element, this element is used to
1242 | indicate to the sharee that the sharing invite is an update for
1243 | one they previously declined.
1244 |
1245 | Definition:
1246 |
1247 | <!ELEMENT invite-declined EMPTY>
1248 |
1249 | 6.10. CS:invite-invalid
1250 |
1251 | Name: invite-invalid
1252 |
1253 | Namespace: http://calendarserver.org/ns/
1254 |
1255 | Purpose: Sharing invite status.
1256 |
1257 | Description: When used in a CS:user (Section 6.5) element, this
1258 | element is used to indicate that the corresponding sharee is not a
1259 | valid calendar user known to the server.
1260 |
1261 | Definition:
1262 |
1263 | <!ELEMENT invite-invalid EMPTY>
1264 |
1265 | 6.11. CS:access
1266 |
1267 | Name: access
1268 |
1269 | Namespace: http://calendarserver.org/ns/
1270 |
1271 | Purpose: Shared calendar access level.
1272 |
1273 | Description: When used in a CS:user (Section 6.5) element, this
1274 | element is used to indicate the sharing access level granted to
1275 | the corresponding sharee.
1276 |
1277 | Definition:
1278 |
1279 | <!ELEMENT invite-invalid (read | read-write)>
1280 |
1281 |
1282 |
1283 |
1284 |
1285 |
1286 |
1287 | Daboo & York [Page 23]
1288 |
1289 | CalDAV Sharing and Publishing October 2010
1290 |
1291 |
1292 | 6.12. CS:read
1293 |
1294 | Name: read
1295 |
1296 | Namespace: http://calendarserver.org/ns/
1297 |
1298 | Purpose: Shared calendar access level privilege.
1299 |
1300 | Description: Indicates that the access level granted only allows
1301 | sharees to read data in the shared calendar (though they can write
1302 | per-user data (Section 5.5.4)).
1303 |
1304 | Definition:
1305 |
1306 | <!ELEMENT read EMPTY>
1307 |
1308 | 6.13. CS:read-write
1309 |
1310 | Name: read-write
1311 |
1312 | Namespace: http://calendarserver.org/ns/
1313 |
1314 | Purpose: Shared calendar access level privilege.
1315 |
1316 | Description: Indicates that the access level granted allows sharees
1317 | to read and write all data in the shared calendar, with the
1318 | exception of components that would trigger scheduling.
1319 |
1320 | Definition:
1321 |
1322 | <!ELEMENT read-write EMPTY>
1323 |
1324 | 6.14. CS:summary
1325 |
1326 | Name: summary
1327 |
1328 | Namespace: http://calendarserver.org/ns/
1329 |
1330 | Purpose: Summary or title of shared calendar.
1331 |
1332 | Description: A brief description of a shared calendar. This can be
1333 | used by sharers to communicate the nature of a shared calendar to
1334 | sharees, as well as used by sharees to indicate back to the sharer
1335 | how each sharee is refering to the shared calendar.
1336 |
1337 |
1338 |
1339 |
1340 |
1341 |
1342 |
1343 | Daboo & York [Page 24]
1344 |
1345 | CalDAV Sharing and Publishing October 2010
1346 |
1347 |
1348 | Definition:
1349 |
1350 | <!ELEMENT summary (#PCDATA)>
1351 |
1352 | 6.15. CS:invite-notification
1353 |
1354 | Name: invite-notification
1355 |
1356 | Namespace: http://calendarserver.org/ns/
1357 |
1358 | Purpose: A notification used as a shared calendar invite.
1359 |
1360 | Description: Defines a notification message sent automatically by
1361 | the server when a sharer adds, changes or removes a sharee from a
1362 | shared calendar. The DAV:href element specifies the calendar user
1363 | address of the sharee to whom the message was sent.
1364 |
1365 | Definition:
1366 |
1367 | <!ELEMENT invite-notification (uid, DAV:href,
1368 | (invite-noresponse | invite-deleted |
1369 | invite-accepted | invite-declined),
1370 | access, hosturl, organizer, summary?>
1371 |
1372 | 6.16. CS:uid
1373 |
1374 | Name: uid
1375 |
1376 | Namespace: http://calendarserver.org/ns/
1377 |
1378 | Purpose: Unique identifier.
1379 |
1380 | Description: A unique identifier for an invitation to a shared
1381 | calendar.
1382 |
1383 | Definition:
1384 |
1385 | <!ELEMENT uid (#PCDATA)>
1386 |
1387 | 6.17. CS:hosturl
1388 |
1389 | Name: hosturl
1390 |
1391 | Namespace: http://calendarserver.org/ns/
1392 |
1393 |
1394 |
1395 |
1396 |
1397 |
1398 |
1399 | Daboo & York [Page 25]
1400 |
1401 | CalDAV Sharing and Publishing October 2010
1402 |
1403 |
1404 | Purpose: Identifies the source URL of a shared calendar.
1405 |
1406 | Description: Contains a single DAV:href element that refers to the
1407 | source of a shared calendar - i.e., the URL of the calendar shared
1408 | by the sharer.
1409 |
1410 | Definition:
1411 |
1412 | <!ELEMENT hosturl (DAV:href)>
1413 |
1414 | 6.18. CS:organizer
1415 |
1416 | Name: organizer
1417 |
1418 | Namespace: http://calendarserver.org/ns/
1419 |
1420 | Purpose: Identifies the sharer of a shared calendar.
1421 |
1422 | Description: Contains a single DAV:href element that identifies the
1423 | calendar user address of the sharer of a shared calendar, and an
1424 | optional CS:common-name element that matches that user.
1425 |
1426 | Definition:
1427 |
1428 | <!ELEMENT organizer (DAV:href, CS:common-name?)>
1429 |
1430 | 6.19. CS:common-name
1431 |
1432 | Name: common-name
1433 |
1434 | Namespace: http://calendarserver.org/ns/
1435 |
1436 | Purpose: The common name of a sharer or sharee.
1437 |
1438 | Description: The common name is optionally provided by a client when
1439 | adding a sharee and optionally included (or modified) by the
1440 | server when returning results for sharers or sharees and in
1441 | notifications.
1442 |
1443 | Definition:
1444 |
1445 | <!ELEMENT common-name (#PCDATA)>
1446 |
1447 | 6.20. CS:invite-reply
1448 |
1449 |
1450 |
1451 |
1452 |
1453 |
1454 |
1455 | Daboo & York [Page 26]
1456 |
1457 | CalDAV Sharing and Publishing October 2010
1458 |
1459 |
1460 | Name: invite-reply
1461 |
1462 | Namespace: http://calendarserver.org/ns/
1463 |
1464 | Purpose: A notification used as a reply to a shared calendar invite.
1465 |
1466 | Description: Defines a notification message sent automatically by
1467 | the server when a sharee replies to a shared calendar invite. The
1468 | DAV:href element specifies the calendar user address of the sharee
1469 | to whom the original invite message was sent.
1470 |
1471 | Definition:
1472 |
1473 | <!ELEMENT invite-reply (DAV:href,
1474 | (invite-accepted | invite-declined),
1475 | hosturl, in-reply-to, summary?>
1476 |
1477 | 6.21. CS:in-reply-to
1478 |
1479 | Name: in-reply-to
1480 |
1481 | Namespace: http://calendarserver.org/ns/
1482 |
1483 | Purpose: Unique identifier.
1484 |
1485 | Description: Specifies the unique identifier of the inviate message
1486 | that this notification message is a reply to.
1487 |
1488 | Definition:
1489 |
1490 | <!ELEMENT in-reply-to (#PCDATA)>
1491 |
1492 | 6.22. CS:notification
1493 |
1494 | Name: notification
1495 |
1496 | Namespace: http://calendarserver.org/ns/
1497 |
1498 | Purpose: Notification message root element.
1499 |
1500 | Description: The root element used in notification resources.
1501 |
1502 | Definition:
1503 |
1504 | <!ELEMENT notification (CS:dtstamp,
1505 | (invite-notification | invite-reply)>
1506 | <!-- Any notification type element can appear after CS:dtstamp,
1507 | this specification defines only the two listed above -->
1508 |
1509 |
1510 |
1511 | Daboo & York [Page 27]
1512 |
1513 | CalDAV Sharing and Publishing October 2010
1514 |
1515 |
1516 | 6.23. CS:dtstamp
1517 |
1518 | Name: dtstamp
1519 |
1520 | Namespace: http://calendarserver.org/ns/
1521 |
1522 | Purpose: Date-time stamp.
1523 |
1524 | Description: Contains the date-time stamp corresponding to the
1525 | creation of a notification message.
1526 |
1527 | Definition:
1528 |
1529 | <!ELEMENT dtstamp (#PCDATA)>
1530 |
1531 | 6.24. CS:share
1532 |
1533 | Name: share
1534 |
1535 | Namespace: http://calendarserver.org/ns/
1536 |
1537 | Purpose: Describes changes to sharees.
1538 |
1539 | Description: The root element used in POST requests on calendars by
1540 | sharers to manipulate the sharee list of a shared calendar.
1541 |
1542 | Definition:
1543 |
1544 | <!ELEMENT share (set | remove)*>
1545 |
1546 | 6.25. CS:set
1547 |
1548 | Name: set
1549 |
1550 | Namespace: http://calendarserver.org/ns/
1551 |
1552 | Purpose: Sets access for a sharee.
1553 |
1554 | Description: Used to add or modify sharee access to a shared
1555 | calendar. The specified access to the shared calendar is given to
1556 | the sharee.
1557 |
1558 | Definition:
1559 |
1560 | <!ELEMENT set (DAV:href, common-name?, summary?,
1561 | (read | read-write)>
1562 |
1563 |
1564 |
1565 |
1566 |
1567 | Daboo & York [Page 28]
1568 |
1569 | CalDAV Sharing and Publishing October 2010
1570 |
1571 |
1572 | 6.26. CS:remove
1573 |
1574 | Name: remove
1575 |
1576 | Namespace: http://calendarserver.org/ns/
1577 |
1578 | Purpose: Removes access for a sharee.
1579 |
1580 | Description: Used to remove sharee access to a shared calendar. All
1581 | access to the shared calendar is removed for the sharee.
1582 |
1583 | Definition:
1584 |
1585 | <!ELEMENT remove (DAV:href)>
1586 |
1587 | 6.27. CS:shared-as
1588 |
1589 | Name: shared-as
1590 |
1591 | Namespace: http://calendarserver.org/ns/
1592 |
1593 | Purpose: Identifies a shared calendar.
1594 |
1595 | Description: Returned by the server for a POST request by a sharee
1596 | accepting a shared calendar invite. The DAV:href element
1597 | specifies the URI of the calendar created by the acceptance.
1598 |
1599 | Definition:
1600 |
1601 | <!ELEMENT shared-as (DAV:href)>
1602 |
1603 |
1604 | 7. Security Considerations
1605 |
1606 | Per-user WebDAV properties and iCalendar data MUST only be accessible
1607 | by the user that created them.
1608 |
1609 | Alarms set by the sharer SHOULD NOT be propagated to sharees by
1610 | default. Clients SHOULD NOT automatically enable triggering of
1611 | alarms on shared calendars that have just been accepted without
1612 | confirmation by the user.
1613 |
1614 | TBD
1615 |
1616 |
1617 | 8. IANA Considerations
1618 |
1619 | This document does not require any actions on the part of IANA.
1620 |
1621 |
1622 |
1623 | Daboo & York [Page 29]
1624 |
1625 | CalDAV Sharing and Publishing October 2010
1626 |
1627 |
1628 | 9. Acknowledgments
1629 |
1630 | This specification is the result of discussions between the Apple
1631 | calendar server and client teams.
1632 |
1633 |
1634 | 10. Normative References
1635 |
1636 | [I-D.desruisseaux-caldav-sched]
1637 | Daboo, C. and B. Desruisseaux, "CalDAV Scheduling
1638 | Extensions to WebDAV", draft-desruisseaux-caldav-sched-08
1639 | (work in progress), August 2009.
1640 |
1641 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1642 | Requirement Levels", BCP 14, RFC 2119, March 1997.
1643 |
1644 | [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
1645 | Distributed Authoring and Versioning (WebDAV)
1646 | Access Control Protocol", RFC 3744, May 2004.
1647 |
1648 | [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
1649 | "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
1650 | March 2007.
1651 |
1652 | [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
1653 | Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
1654 |
1655 | [RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring
1656 | and Versioning (WebDAV)", RFC 5689, September 2009.
1657 |
1658 |
1659 | Appendix A. Change History
1660 |
1661 | Changes in -02:
1662 |
1663 | 1. Removed read-write-shared access mode - now a server that does
1664 | not support shared scheduling should advertise that via a DAV
1665 | header
1666 |
1667 |
1668 | Appendix B. Change History
1669 |
1670 | Changes in -01:
1671 |
1672 | 1. Added CS:shared-url property
1673 |
1674 | 2. Clarified that notifications are only required to be sent when
1675 | sharee status is changed
1676 |
1677 |
1678 |
1679 | Daboo & York [Page 30]
1680 |
1681 | CalDAV Sharing and Publishing October 2010
1682 |
1683 |
1684 | Authors' Addresses
1685 |
1686 | Cyrus Daboo
1687 | Apple Inc.
1688 | 1 Infinite Loop
1689 | Cupertino, CA 95014
1690 | USA
1691 |
1692 | Email: cyrus@daboo.name
1693 | URI: http://www.apple.com/
1694 |
1695 |
1696 | Eric York
1697 | Apple Inc.
1698 | 1 Infinite Loop
1699 | Cupertino, CA 95014
1700 | USA
1701 |
1702 | Email:
1703 | URI: http://www.apple.com/
1704 |
1705 |
1706 |
1707 |
1708 |
1709 |
1710 |
1711 |
1712 |
1713 |
1714 |
1715 |
1716 |
1717 |
1718 |
1719 |
1720 |
1721 |
1722 |
1723 |
1724 |
1725 |
1726 |
1727 |
1728 |
1729 |
1730 |
1731 |
1732 |
1733 |
1734 |
1735 | Daboo & York [Page 31]
1736 |

Note: See TracBrowser for help on using the browser.

### Download in other formats:

- Plain Text
- Original Format