-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcollection-sharing.xml
1105 lines (1086 loc) · 55.5 KB
/
collection-sharing.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
<!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc3744 PUBLIC '' 'bibxml/reference.RFC.3744.xml'>
<!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
<!ENTITY rfc4918 PUBLIC '' 'bibxml/reference.RFC.4918.xml'>
<!ENTITY rfc6352 PUBLIC '' 'bibxml/reference.RFC.6352.xml'>
<!ENTITY rfc6638 PUBLIC '' 'bibxml/reference.RFC.6638.xml'>
]>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc strict="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc ipr="trust200902" docName='dav-collection-sharing-00'>
<front>
<title abbrev="WebDAV Collection Sharing">WebDAV Collection Sharing</title>
<author initials="C." surname="Daboo" fullname="Cyrus Daboo">
<organization abbrev="Apple Inc.">
Apple Inc.
</organization>
<address>
<postal>
<street>1 Infinite Loop</street>
<city>Cupertino</city>
<region>CA</region>
<code>95014</code>
<country>USA</country>
</postal>
<email>[email protected]</email>
<uri>http://www.apple.com/</uri>
</address>
</author>
<author initials="E." surname="York" fullname="Eric York">
<organization abbrev="Apple Inc.">
Apple Inc.
</organization>
<address>
<postal>
<street>1 Infinite Loop</street>
<city>Cupertino</city>
<region>CA</region>
<code>95014</code>
<country>USA</country>
</postal>
<email></email>
<uri>http://www.apple.com/</uri>
</address>
</author>
<author initials="E." surname="Pot" fullname="Evert Pot">
<organization abbrev="fruux GmbH">
fruux GmbH
</organization>
<address>
<postal>
<street>Koenigsstrasse 32</street>
<city>Muenster</city>
<region>NRW</region>
<code>48143</code>
<country>Germany</country>
</postal>
<email>[email protected]</email>
<uri>https://fruux.com/</uri>
</address>
</author>
<date/>
<abstract>
<t>
This specification defines an extension to WebDAV that enables the sharing of collections between users on a WebDAV server.
</t>
</abstract>
</front>
<middle>
<section title='Introduction'>
<t>
Users of <xref target="RFC4791">CalDAV</xref> and
<xref target="RFC6352">CardDAV</xref> often require a
mechanism to share a calendar or address book collection
with other users.
</t>
<t>
This specification introduces a mechanism that allows
users of WebDAV servers to invite another user to a collection.
The invited user can either accept or reject the invite, which
is communicated back to the inviter.
If the user chooses to accept the invite, the shared collection
will then appear in a location on the server that's accessible
by the invitee.
</t>
<t>
There are existing mechanism that address similar use-cases,
such as using <xref target='RFC3744'>WebDAV ACL</xref> for
fine-grained access control. Experiences has shown that client
developers are averse to using it due its complexity. Many
implementations have chosen to only use WebDAV ACL for
communicating access control information to clients, but not
for modification. WebDAV ACL alone also does not provide the
means for a user to invite another user.
</t>
<t>
HTTP POST operations are used to manage the sharing invitations
and replies, and WebDAV properties are used to expose the state
of shared collections.
</t>
</section>
<section title="Open Issues">
<t>
<list style="numbers">
<t>Replying to invites can't happen on the calendar home, suggest to reply using the resource URI of the notification being replied to.</t>
<t>Consider removing DAV:href from in-reply-to as well. Should contain sharee, but seems unneeded.</t>
<t>Need mime-type for POST request xml bodies.</t>
<t>DAV:common-name should probably DAV:displayname</t>
<t>Allow invite-deleted to also appear in DAV:user</t>
<t>Cleaning up notifications that have been replied to.</t>
</list>
</t>
</section>
<section title='Conventions Used in This Document'>
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in <xref target='RFC2119' />.
</t>
<t>
When XML element types in the namespaces "DAV:" and "urn:ietf:params:xml:ns:caldav" are referenced in this document outside of the context of an XML fragment, the string "DAV:" and "CALDAV:" will be prefixed to the element type names respectively.
</t>
<t>Terms Used:
<list style='hanging'>
<t hangText='Sharer'>A user who is sharing a collection with other users.</t>
<t hangText='Sharee'>A user to whom a collection has been shared.</t>
<t hangText='Sharing Invite'>A message sent by a sharer to a sharee to indicate the status of a shared collection.</t>
<t hangText='Sharing Reply'>A message sent by a sharee to a sharer to indicate the status of a shared collection.</t>
</list>
</t>
</section>
<section title='Overview' anchor='overview'>
<t>
This section provides a basic overview of this protocol by way
of a simple use case of a sharer sharing a collection with a
single sharee.
</t>
<t>
To share a collection with another user, the sharer's client
executes an HTTP POST request against the collection resource
for the collection to be shared. The POST request body will
contain details of the user to whom the collection is to be
shared as well as the access right to be granted to them. If
the request succeeds, a notification is sent to the sharee
with details of the collection being shared to them.
</t>
<t>
The sharer's client will show the notification to the sharee
and present them with the choice to accept or decline the
invitation to the shared collection. If the sharee chooses to
decline, then nothing changes for that sharee. If the sharee
chooses to accept, then the server automatically creates a new
collection resource in a location that is determined by the
server.
For example, if a <xref target='RFC4791'>CalDAV</xref> calendar
is shared, the server may create the new collection in the
sharee's calendar home.
The server enforces the appropriate access privileges for the
sharee.
</t>
<t>
At any time, the sharer can inspect properties on the
collection being shared, and determine the accept/decline
status of each sharee. Additional sharees can be added and
existing ones removed. The access privileges for existing
sharees can also be changed.
</t>
<t>
Once a sharee has access to the shared collection, they can
remove it and decline the sharing invite by simply having
their client issue an HTTP DELETE request on the shared
collection. That does not delete any data, but rather simply
removes the "link" to the sharer's collection and sets the
sharee's invite status to declined.
</t>
</section>
<section title="Notification Definitions">
<t>
In order to facilitate the process of sharing invitations, this
specification uses <!-- <xref target="dav-notifications">-->WebDAV
notifications<!-- </xref> -->, and defines several new notification
types.
</t>
<section title="Invite Notification" anchor='invite-notification'>
<t>
When a sharer adds a new sharee to a collection, or updates
a sharee, an invite notification is added to the sharee's
notification collection.
</t>
<t>
The notification contains information about the shared
collection, the owner and how to respond to said invitation.
</t>
<t>
The body of this notification is retrieved with a GET
request. The root element of the notification MUST be
<xref target="DAV:invite-notification">DAV:invite-notification</xref>.
</t>
<section title="Example: An invite notification">
<t>
This is an example of a response to a GET request on a
correct invite notification. Note that several HTTP
response headers have been removed for brevity.
</t>
<t>
<figure>
<artwork><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/davnotification+xml
Content-Length: xxxx
<D:invite-notification xmlns:D="DAV:">
<D:principal>
<D:href>/principals/users/evert</D:href>
</D:principal>
<D:invite-accepted />
<D:href>/calendars/users/evert/offdays/</D:href>
<D:access><D:read-write /></D:access>
<D:prop>
<D:displayname>Vacation days!!</D:displayname>
<D:resourcetype><D:collection /></D:resourcetype>
</D:prop>
</D:invite-notification>
]]></artwork>
</figure>
</t>
</section>
</section>
<section title="Invite Reply" anchor='invite-reply'>
<t>
TODO
</t>
</section>
</section>
<section title="Collection sharing">
<section title="Feature Discovery">
<t>
A server that supports the features described in this document MUST include "collection-sharing" as a field in the DAV response header from an OPTIONS request on any resource that supports these features.
</t>
</section>
<section title="Additional Properties for Collections" anchor='properties'>
<t>
The following new or modified WebDAV properties are defined for collections and used to view or manipulate shared collection features.
</t>
<section title="DAV:resourcetype Property" anchor="DAV:resourcetype">
<t>
Collections that are shared have elements listed in their DAV:resourcetype property in addition to DAV:collection.
<list style="symbols">
<t><xref target="DAV:shared-owner">DAV:shared-owner</xref>: used to indicate that the colection is owned by the current user and is being shared by them.</t>
<t><xref target="DAV:shared">DAV:shared</xref>: used to indicate that the collection is owned by another user and is being shared to the current user.</t>
</list>
</t>
</section>
<section title="DAV:invite Property" anchor="DAV:invite">
<t>
<list style="hanging">
<t hangText="Name:">invite</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Used to show to whom a calendar has been shared.</t>
<t hangText="Protected:">This property MUST be protected.</t>
<t hangText="PROPFIND behavior:">This property SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
<t hangText="COPY/MOVE behavior:">This property value MUST be preserved in MOVE operations, but MUST NOT be preserved in COPY operations.</t>
<t hangText="Description:">
This WebDAV property is present on a collection
resource that has been shared by the owner, or on
the collection resources for the sharees. It
provides a list of users to whom the collection has
been shared, along with the "status" of the sharing
invites sent to each user. In addition, servers
SHOULD include a DAV:organizer XML element on
collection resources of the sharees to provide
clients with a fast way to determine who the sharer
is. A server's local privacy policy may prevent
sharees from knowing about other sharees on a shared
calendar. If that is so server will not include
DAV:user XML elements for other sharees.
</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT invite (organizer?, user*)>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:shared-url Property" anchor="DAV:shared-url">
<t>
<list style="hanging">
<t hangText="Name:">shared-url</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Indicates the URL of the owner's copy of a shared collection.</t>
<t hangText="Protected:">This property MUST be protected.</t>
<t hangText="PROPFIND behavior:">This property SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of <xref target="RFC4918"/>).</t>
<t hangText="COPY/MOVE behavior:">This property value MUST be preserved in COPY and MOVE operations.</t>
<t hangText="Description:">
This WebDAV property is present on a shared
collection resource that appears in a sharee's
calendar home collection. Its content is a single
DAV:href element whose value is the URL of the
sharer's calendar being shared.
</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT shared-url (DAV:href)>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
</section>
<section title="Sharer Actions on Shared Collections">
<section title="Sharing or Unsharing a Collection">
<t>
To update an existing collection to be shared, the
sharer simply adds one or more sharees to the
collection as per <xref target="sharee"/>. The server
MUST update the DAV:resourcetype property on the
calendar collection to ensure it contains a
DAV:shared-owner XML element to indicate the calendar
collection is now shared.
</t>
<t>
To unshare a collection, the sharer simply removes all
sharees to the CS:invite property of the collection as
per <xref target="sharee"/>. The server MUST update the
DAV:resourcetype property on the calendar collection
to ensure it does not contain a CS:shared-owner XML
element to indicate the collection is not shared.
</t>
</section>
<section title="Manipulating Sharees of a Shared Collection" anchor="sharee">
<t>
The sharer of a shared collection is able to manipulate
the sharee list by issuing a POST request targeted at
the calendar collection resource. The POST request MUST
contain an XML document as its body with the root
element being <xref target="DAV:share">DAV:share</xref>.
</t>
<t>
The <xref target="DAV:share">DAV:share</xref> element in
the POST requests MUST contain one or more
<xref target="DAV:set">DAV:set</xref> or
<xref target="DAV:remove">DAV:remove</xref> elements.
For each <xref target="DAV:set">CS:set</xref> element,
the server MUST add the specified sharee access to the
collection. For each
<xref target="DAV:remove">DAV:remove</xref> element
the server MUST remove the specified sharee access
from the shared collection. In each case the server MUST
send a notification message to any sharees whose status
is changed (added, modified or removed), indicating to
them a change in status for the shared collection. The
server SHOULD NOT send notification messages to sharees
whose status is unchanged.
</t>
<t>
Sharees are identified via a DAV:href element whose
value is either a principal-URL for a sharee hosted on
the same server, an email address, or any other URI
identifying a user.
In the case of the later two, the sharee might not be
a user on the same server - though in that case how
invitations are sent or access enabled is out of scope
for this specification. A server MAY change the
sharee's "address" to any suitable alternative that
it might prefer when returning the list of sharees via
the <xref target="DAV:invite">DAV:invite property</xref>.
</t>
<t>
The client MAY include a
<xref target="DAV:common-name">DAV:common-name</xref>
element in the <xref target="DAV:set">DAV:set</xref>
element. When provided, the value represents the common
name for the sharee, and is returned in the list of
sharees via the <xref target="DAV:invite">DAV:invite property</xref>.
The server MAY change this to a suitable alternative
when it is able to match the sharee to a known user.
If absent from the client request, the server SHOULD
add a CS:common-name when it is able to match the
sharee with a known user, and a common name for that
user can be determined.
</t>
<t>
When the sharee list on a shared collection is changed,
the server MUST send notifications to each sharee to
update them on their current sharing status. This is
accomplished by sending a
<xref target="DAV:invite-notification">DAV:invite-notification</xref>
notification to each sharee.
</t>
<section title="Example: Successful Sharee Add Request">
<t>
This example shows how to add a single sharee (with email address "mailto:[email protected]") to a shared collection with DAV:read-write access.
</t>
<figure>
<preamble>>> Request <<</preamble>
<artwork><![CDATA[
POST /calendars/users/cyrus/shared/ HTTP/1.1
Host: calendar.example.com
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:share xmlns:D="DAV:">
<D:set>
<D:href>mailto:[email protected]</D:href>
<D:common-name>Eric York</D:common-name>
<D:description>Shared workspace</D:description>
<D:read-write />
</D:set>
</D:share>]]></artwork>
</figure>
<figure>
<preamble>>> Response <<</preamble>
<artwork><![CDATA[
HTTP/1.1 200 OK
Cache-Control: no-cache
Date: Sat, 11 Nov 2006 09:32:12 GMT]]></artwork>
</figure>
</section>
<section title="Example: Successful Multiple Sharee Change Request">
<t>
This example shows how multiple sharee's can be manipulated in a single request. The sharee with email address "mailto:[email protected]" has their access downgraded to CS:read, whilst another sharee is removed from the access list entirely.
</t>
<figure>
<preamble>>> Request <<</preamble>
<artwork><![CDATA[
POST /calendars/users/cyrus/shared/ HTTP/1.1
Host: calendar.example.com
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:share xmlns:D="DAV:">
<D:set>
<D:href>mailto:[email protected]</D:href>
<D:description>Shared workspace</D:description>
<D:read-write />
</D:set>
<D:remove>
<D:href>mailto:[email protected]</D:href>
</D:remove>
</D:share>]]></artwork>
</figure>
<figure>
<preamble>>> Response <<</preamble>
<artwork><![CDATA[
HTTP/1.1 200 OK
Cache-Control: no-cache
Date: Sat, 11 Nov 2006 09:32:12 GMT]]></artwork>
</figure>
</section>
</section>
</section>
<section title="Sharee Actions on Shared Collections">
<section title="Replying to a Sharing Invite">
<t>
When a sharee is invited to a shared collection they
can accept or decline the invite by issuing a POST
request to the resource URI for the invitation
notification. The POST request MUST contain an XML
document as its body with the root element being
<xref target="DAV:invite-reply">DAV:invite-reply</xref>.
</t>
<t>
The <xref target="DAV:invite-reply">DAV:invite-reply</xref>
element in the POST request specifies the accept or
decline action via the DAV:invite-accepted or
DAV:invite-declined elements, and an optional
DAV:summary element. IF the invite was accepted, the
body MUST also contain a <xref target="DAV:create-as">
DAV:create-as</xref> element. This element contains a
single DAV:href element, which content is a URI that
will be used as the target url for the new instance of
the shared resource.
</t>
<t>
All usual preconditions for creating a resource at the
DAV:create-as target url need to be taken into
considerations.
</t>
<t>
Note that some servers may restrict where certain types
of collection resources may be created. A CalDAV server
for instance, may only allow calendars to be created in
collections identified by the calendar-home-set WebDAV
property.
</t>
<t>
A successful response to this POST request should
contain a 201 status code. It's response body is
undefined.
</t>
<t>
When the sharee replies to an invite, the server
SHOULD send a notification to the sharer to update
them on the change in the sharee state. This is
accomplished by sending a
<xref target="DAV:invite-reply">DAV:invite-reply</xref>
notification to the sharer.
</t>
<t>
After the sharee has issued a reply, the server SHOULD
also remove the notification that contained the
initial invite.
</t>
</section>
<section title="Removing a Shared Collection">
<t>
To remove a shared collection a DELETE request is
targeted at the shared collection URI. When such a
request is received the server MUST remove the shared
collection and automatically update the sharee's
status in the sharer's DAV:invite property.
</t>
</section>
</section>
<section title="General Considerations">
<section title="Access Levels">
<t>
Two levels of access ca be granted by a sharer to any sharee. These are governed by the DAV:access element used in the DAV:invite/DAV:user element that specifies a shared user invite. DAV:access contains a single empty element that defines the type of access granted:
<list style="hanging">
<t hangText="DAV:read">
When present this indicates that sharees can read information from the collection, but cannot change it.
</t>
<t hangText="DAV:read-write">
When present this indicates that sharees can read and write collection data.
</t>
</list>
</t>
</section>
<section title="Per-instance WebDAV Properties" anchor="per-instance-data">
<t>
Servers MUST support "per-instance" WebDAV properties
on shared collections and MAY support them on resources
within shared collections. A "per-instance" WebDAV
property is one whose value can be set and retrieved
on an instance of a collection, but is not
automatically propagated to other instances of the
same shared collection. For example, a sharee may
change a property on their instance of a shared
collection, but the instance of the owner of the
collection will not see this updated value.
</t>
<t>
For shared collections, the server MUST allow all
users to write "per-instance" WebDAV properties on the
shared collection and MAY allow property writes on
resources within the shared collection. This is
required even in the case where the sharee has been
granted read access only (i.e., the ability to
change the calenar is disallowed). This requirement
ensures that sharees can always change "personal"
properties such as display names.
</t>
<t>
Servers MUST treat the following properties as "per-instance":
<list>
<t>DAV:displayname</t>
</list>
</t>
<t>
Servers MAY treat any dead property as per-instance.
</t>
<t>
Servers MUST NOT treat live properties as per-instance.
</t>
</section>
</section>
</section>
<section title="Sharing privileges">
<t>
Servers MAY support sharing on a per-collections basis.
This section defines a "DAV:share"
<xref target="RFC3744">WebDAV Access Control (ACL)</xref>
privilege for use on collections that may be shared.
</t>
<t>
This privilege MUST be non-abstract and MAY be protected.
This privilege MUST appear in the DAV:supported-privilege-set
property for collections that may be shared. In addition, it
MUST appear in the DAV:current-user-privilege-set, if the user
is allowed to share the collection.
</t>
</section>
<section title='XML Element Definitions'>
<section title="DAV:shared-owner" anchor="DAV:shared-owner">
<t>
<list style="hanging">
<t hangText="Name:">shared-owner</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Used to indicate that a collection is being shared by the owner.</t>
<t hangText="Description:">This property appears in the DAV:resourcetype property on the collection resource shared by a sharer. See <xref target="properties"/>.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT shared-owner EMPTY>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:shared" anchor="DAV:shared">
<t>
<list style="hanging">
<t hangText="Name:">shared</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Used to indicate that a collection is being shared to a sharee.</t>
<t hangText="Description:">This property appears in the DAV:resourcetype property on a collection resource that is shared to a sharee. See <xref target="properties"/>.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT shared EMPTY>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:share" anchor="DAV:share">
<t>
<list style="hanging">
<t hangText="Name:">share</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">A WebDAV ACL privilege to control sharing.</t>
<t hangText="Description:">
This element represents a <xref target="RFC3744">WebDAV
ACL privilege</xref>, and indicates that the current
principal is allowed to share the collection on which
it is defined.
</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT share EMPTY>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:user" anchor="DAV:user">
<t>
<list style="hanging">
<t hangText="Name:">user</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Used to show status of sharing invites sent to sharees.</t>
<t hangText="Description:">This element provides the "status" of a sharing invite sent to a particular user. See <xref target="DAV:invite"/>.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT user (DAV:href, common-name?, (invite-noresponse |
invite-accepted | invite-declined | invite-invalid),
access, description?)>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:invite-noresponse">
<t>
<list style="hanging">
<t hangText="Name:">invite-noresponse</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Sharing invite status.</t>
<t hangText="Description:">When used in a <xref target="DAV:user">DAV:user</xref> element, this element is used to indicate that the sharee has never replied to the corresponding sharing invite. When used in a <xref target="DAV:invite-notification">DAV:invite-notification</xref> element, this element is used to indicate to the sharee that a sharing reply is needed.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT invite-noresponse EMPTY>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:invite-deleted">
<t>
<list style="hanging">
<t hangText="Name:">invite-deleted</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Sharing invite status.</t>
<t hangText="Description:">When used in a <xref target="DAV:invite-notification">DAV:invite-notification</xref> element, this element is used to indicate to the sharee that a shared collection has been unshared by the sharer.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT invite-deleted EMPTY>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:invite-accepted">
<t>
<list style="hanging">
<t hangText="Name:">invite-accepted</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Sharing invite status.</t>
<t hangText="Description:">When used in a <xref target="DAV:user">DAV:user</xref> element, this element is used to indicate that the sharee has accepted the corresponding sharing invite. When used in a <xref target="DAV:invite-notification">DAV:invite-notification</xref> element, this element is used to indicate to the sharee that the sharing invite is an update for one they previously accepted.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT invite-accepted EMPTY>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:invite-declined">
<t>
<list style="hanging">
<t hangText="Name:">invite-declined</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Sharing invite status.</t>
<t hangText="Description:">When used in a <xref target="DAV:user">DAV:user</xref> element, this element is used to indicate that the sharee has declined the corresponding sharing invite. When used in a <xref target="DAV:invite-notification">DAV:invite-notification</xref> element, this element is used to indicate to the sharee that the sharing invite is an update for one they previously declined.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT invite-declined EMPTY>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:invite-invalid">
<t>
<list style="hanging">
<t hangText="Name:">invite-invalid</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Sharing invite status.</t>
<t hangText="Description:">When used in a <xref target="DAV:user">DAV:user</xref> element, this element is used to indicate that the corresponding sharee is not a valid user known to the server.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT invite-invalid EMPTY>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:access">
<t>
<list style="hanging">
<t hangText="Name:">access</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Shared collection access level.</t>
<t hangText="Description:">When used in a <xref target="DAV:user">DAV:user</xref> element, this element is used to indicate the sharing access level granted to the corresponding sharee.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT access (read | read-write)>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:read">
<t>
<list style="hanging">
<t hangText="Name:">read</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Shared collection access level privilege.</t>
<t hangText="Description:">Indicates that the access level granted only allows sharees to read data in the shared collection (though they can write <xref target="per-instance-data">per-instance data</xref>).</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT read EMPTY>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:read-write">
<t>
<list style="hanging">
<t hangText="Name:">read-write</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Shared collection access level privilege.</t>
<t hangText="Description:">Indicates that the access level granted allows sharees to read and write all data in the collection.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT read-write EMPTY>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:description">
<t>
<list style="hanging">
<t hangText="Name:">description</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Summary or title of shared collection.</t>
<t hangText="Description:">A brief description of a shared collection. This can be used by sharers to communicate the nature of a shared collection to sharees, as well as used by sharees to indicate back to the sharer how each sharee is refering to the shared collection.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT description (#PCDATA)>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:invite-notification" anchor="DAV:invite-notification">
<t>
<list style="hanging">
<t hangText="Name:">invite-notification</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">A notification used as a shared collection invite.</t>
<t hangText="Description:">Defines a notification message sent automatically by the server when a sharer adds, changes or removes a sharee from a shared collection. The DAV:href element specifies the URI of the sharee to whom the message was sent.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT invite-notification (
uid, dav:href,
(invite-noresponse | invite-deleted |
invite-accepted | invite-declined),
access, organizer,
description?,
>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:hosturl">
<t>
<list style="hanging">
<t hangText="Name:">hosturl</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Identifies the source URL of a shared collection.</t>
<t hangText="Description:">Contains a single DAV:href element that refers to the source of a shared collection - i.e., the URL of the collection shared by the sharer.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT hosturl (DAV:href)>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:organizer">
<t>
<list style="hanging">
<t hangText="Name:">organizer</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Identifies the sharer of a shared collection.</t>
<t hangText="Description:">Contains a single DAV:href element that identifies the URI of the sharer of a shared collection, and an optional DAV:common-name element that matches that user, and an optional DAV:first-name, DAV:last-name pair of elements that match that user. In some cases servers might have directory information that includes only the common name, or only the first or last name, and it is better to expose those directly to the client as-is rather than to try and split or combine the attributes to synthesize one set or the other.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT organizer (DAV:href,
DAV:common-name?,
(DAV:first-name, DAV:last-name)?)>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:common-name" anchor="DAV:common-name">
<t>
<list style="hanging">
<t hangText="Name:">common-name</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">The common name of a sharer or sharee.</t>
<t hangText="Description:">The common name is optionally provided by a client when adding a sharee and optionally included (or modified) by the server when returning results for sharers or sharees and in notifications.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT common-name (#PCDATA)>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:first-name" anchor="DAV:first-name">
<t>
<list style="hanging">
<t hangText="Name:">first-name</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">The first name of a sharer or sharee.</t>
<t hangText="Description:">The first name is optionally included by the server when returning results for sharers or sharees and in notifications.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT first-name (#PCDATA)>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:last-name" anchor="DAV:last-name">
<t>
<list style="hanging">
<t hangText="Name:">last-name</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">The last name of a sharer or sharee.</t>
<t hangText="Description:">The last name is optionally included by the server when returning results for sharers or sharees and in notifications.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT last-name (#PCDATA)>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:invite-reply" anchor="DAV:invite-reply">
<t>
<list style="hanging">
<t hangText="Name:">invite-reply</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">A notification used as a reply to a shared collection invite.</t>
<t hangText="Description:">Defines a notification message sent automatically by the server when a sharee replies to a shared collection invite. The DAV:href element specifies the URI of the sharee to whom the original invite message was sent.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT invite-reply (DAV:href,
(invite-accepted | invite-declined),
hosturl, create-as?, summary?>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:create-as" anchor="DAV:create-as">
<t>
<list style="hanging">
<t hangText="Name:">create-as</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">The target url for the new resource.</t>
<t hangText="Description:">
When a user accepts an invitation to share a collection, this URI will be used to create the new shared resource.
</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT create-as (DAV:href)>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:share">
<t>
<list style="hanging">
<t hangText="Name:">share</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Describes changes to sharees.</t>
<t hangText="Description:">The root element used in POST requests on collections by sharers to manipulate the sharee list of a shared collections.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT share (set | remove)*>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:set" anchor="DAV:set">
<t>
<list style="hanging">
<t hangText="Name:">set</t>
<t hangText="Namespace:">DAV:</t>
<t hangText="Purpose:">Sets access for a sharee.</t>
<t hangText="Description:">Used to add or modify sharee access to a shared collection. The specified access to the shared collection is given to the sharee.</t>
<t hangText="Definition:">
<figure>
<artwork><![CDATA[
<!ELEMENT set (DAV:href, common-name?, description?,
(read | read-write)>]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="DAV:remove" anchor="DAV:remove">
<t>