[CalendarServer-changes] [3136] CalendarServer/trunk/doc/Extensions
source_changes at macosforge.org
source_changes at macosforge.org
Thu Oct 9 08:45:03 PDT 2008
Revision: 3136
http://trac.macosforge.org/projects/calendarserver/changeset/3136
Author: cdaboo at apple.com
Date: 2008-10-09 08:45:02 -0700 (Thu, 09 Oct 2008)
Log Message:
-----------
Change names.
Removed Paths:
-------------
CalendarServer/trunk/doc/Extensions/caldav-privatecomments-00.txt
CalendarServer/trunk/doc/Extensions/caldav-privatecomments-00.xml
CalendarServer/trunk/doc/Extensions/caldav-schedulingchanges-01.txt
CalendarServer/trunk/doc/Extensions/caldav-schedulingchanges-01.xml
Deleted: CalendarServer/trunk/doc/Extensions/caldav-privatecomments-00.txt
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-privatecomments-00.txt 2008-10-09 15:44:42 UTC (rev 3135)
+++ CalendarServer/trunk/doc/Extensions/caldav-privatecomments-00.txt 2008-10-09 15:45:02 UTC (rev 3136)
@@ -1,616 +0,0 @@
-
-
-
-Calendar Server Extension C. Daboo
- Apple
- August 14, 2008
-
-
- Private Attendee Comments in CalDAV Scheduling
-
-Abstract
-
- This document defines an extension to CalDAV Scheduling that enables
- Attendees to communicate private comments back to an Organizer, and
- for the Organizer to see each Attendees' comments.
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Conventions Used in This Document . . . . . . . . . . . . . . 2
- 3. New behavior . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 3.1. Attendee . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 3.2. Organizer . . . . . . . . . . . . . . . . . . . . . . . . 3
- 4. New features . . . . . . . . . . . . . . . . . . . . . . . . . 5
- 4.1. iCalendar Changes . . . . . . . . . . . . . . . . . . . . 5
- 4.1.1. Changes to VEVENT Component . . . . . . . . . . . . . 5
- 4.1.2. Changes to VTODO Component . . . . . . . . . . . . . . 5
- 4.1.3. Changes to VJOURNAL Component . . . . . . . . . . . . 6
- 4.1.4. Private Comment Property . . . . . . . . . . . . . . . 6
- 4.1.5. Attendee Comment Property . . . . . . . . . . . . . . 7
- 4.1.6. Date-time Stamp Property Parameter . . . . . . . . . . 8
- 4.1.7. Attendee Reference Property Parameter . . . . . . . . 9
- 4.2. CalDAV Changes . . . . . . . . . . . . . . . . . . . . . . 9
- 4.2.1. OPTIONS Request . . . . . . . . . . . . . . . . . . . 9
- 4.2.1.1. Example: Using OPTIONS for the Discovery of
- Private Attendee Comments Support . . . . . . . . 10
- 4.2.2. Handling clients that do not preserve X- properties . 10
- 4.2.3. New pre-conditions for PUT . . . . . . . . . . . . . . 10
- 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
- 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
- 7. Normative References . . . . . . . . . . . . . . . . . . . . . 11
- Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 11
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 1]
-
- CalDAV Private Attendee Comments August 2008
-
-
-1. Introduction
-
- Internet calendaring and scheduling standards are defined by
- iCalendar [RFC2445] and iTIP [RFC2446]. The CalDAV Access [RFC4791]
- standard defines a way to access calendar data stored on a server,
- and the CalDAV Scheduling [I-D.desruisseaux-caldav-sched] draft
- defines how scheduling occurs between users of a CalDAV server.
-
- It is often the case that an Attendee of an event wants to
- communicate information back to an Organizer when they respond to a
- meeting invitation. Sometimes this is to tell the Organizer the
- reason why an invite was declined, sometimes to add addition
- information to an acceptance. Typically these communications are
- expected to be private as they may contain comments about other
- Attendees.
-
- This specification defines new iCalendar properties and parameters
- that are used by clients to pass private comments between Attendees
- and Organizers of events being scheduling via CalDAV scheduling. It
- also defines an extension to CalDAV scheduling that defines how a
- server automatically processes the comments to ensure they are
- communicated properly between the Attendee and Organizer.
-
-
-2. Conventions Used in This Document
-
- 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 [RFC2119].
-
- 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.
-
- The namespace "http://calendarserver.org/ns/" is used for XML
- elements defined in this specification. When XML element types in
- this namespace are referenced in this document outside of the context
- of an XML fragment, the string "CS:" will be prefixed to the element
- type names respectively.
-
- The prefix X-CALENDARSERVER- is used for all iCalendar properties and
- parameters defined in this extension.
-
-
-3. New behavior
-
-
-
-
-
-Daboo [Page 2]
-
- CalDAV Private Attendee Comments August 2008
-
-
-3.1. Attendee
-
- When an Attendee wants to send a private comment to an Organizer, the
- Attendee's calendar user agent adds or updates an "X-CALENDARSERVER-
- PRIVATE-COMMENT" property in each calendar component of a scheduling
- object resource to which the comment applies. The value of the
- comment is the actual message the Attendee is sending.
-
- The addition or update of any "X-CALENDARSERVER-PRIVATE-COMMENT"
- property causes the server to send a scheduling message to the
- Organizer as an iTIP "REPLY", and that MUST include the
- "X-CALENDARSERVER-PRIVATE-COMMENT" properties in addition to the
- normal properties sent as part of that scheduling message.
-
-3.2. Organizer
-
- When a scheduling message from an Attendee is processed by the
- server, the server will check for the presence of a
- "X-CALENDARSERVER-PRIVATE-COMMENT" property in each component of the
- scheduling message and compare this with the scheduling object
- resource corresponding to the scheduling message currently stored on
- a live calendar belonging to the Organizer. For each component in
- the scheduling message, the server will identify the corresponding
- component in the scheduling object resource (possibly creating a new
- overridden component instance if needed) and do the following:
-
- +---------+---------------------------------------------------------+
- | State | Description |
- +---------+---------------------------------------------------------+
- | State 1 | Does the scheduling message contain a |
- | | "X-CALENDARSERVER-PRIVATE-COMMENT" property |
- | | |
- | State 2 | Does the scheduling object resource contain a |
- | | "X-CALENDARSERVER-ATTENDEE-COMMENT" property with an |
- | | "X-CALENDARSERVER-ATTENDEE-REF" parameter value that |
- | | matches the "ATTENDEE" value in the scheduling message |
- +---------+---------------------------------------------------------+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 3]
-
- CalDAV Private Attendee Comments August 2008
-
-
- +---------+---------+------------------------------------+
- | State 1 | State 2 | Server Action |
- +---------+---------+------------------------------------+
- | No | No | No additional processing required. |
- | | | |
- | No | Yes | Note 1. |
- | | | |
- | Yes | No | Note 2. |
- | | | |
- | Yes | Yes | Note 3. |
- +---------+---------+------------------------------------+
-
- Note 1: The server MUST update the "X-CALENDARSERVER-DTSTAMP"
- parameter value on the "X-CALENDARSERVER-ATTENDEE-COMMENT"
- property, and it MUST set the value of that property to an empty
- string. It MUST remove all property parameters other than
- "X-CALENDARSERVER-DTSTAMP" and "X-CALENDARSERVER-ATTENDEE-REF".
-
- Note 2: The server MUST create an "X-CALENDARSERVER-ATTENDEE-
- COMMENT" and MUST set the "X-CALENDARSERVER-DTSTAMP" and
- "X-CALENDARSERVER-ATTENDEE-REF" parameter values, and MUST set the
- value of the new property to the value of the "X-CALENDARSERVER-
- PRIVATE-COMMENT" property. Other parameter values on the
- "X-CALENDARSERVER-PRIVATE-COMMENT" property MAY be copied to the
- "X-CALENDARSERVER-ATTENDEE-COMMENT" property if supported.
-
- Note 3: The server MUST update the "X-CALENDARSERVER-DTSTAMP"
- parameter value on the "X-CALENDARSERVER-ATTENDEE-COMMENT"
- property, and MUST set the value of the new property to the value
- of the "X-CALENDARSERVER-PRIVATE-COMMENT" property. It MUST
- remove all property parameters other than "X-CALENDARSERVER-
- DTSTAMP" and "X-CALENDARSERVER-ATTENDEE-REF", and other parameter
- values on the "X-CALENDARSERVER-PRIVATE-COMMENT" property MAY be
- copied to the "X-CALENDARSERVER-ATTENDEE-COMMENT" property if
- supported.
-
- When creating or updating the "X-CALENDARSERVER-DTSTAMP" property
- parameter value, the server MUST set it to the date-time UTC value
- when the processing of the scheduling message took place.
-
- When creating the "X-CALENDARSERVER-ATTENDEE-REF" property parameter
- value, the server MUST set it to the "ATTENDEE" property value in the
- scheduling message being processed. As the scheduling message is an
- iTIP "REPLY" only one "ATTENDEE" property will be present in each
- component, and the value corresponds to the Attendee sending the
- reply.
-
- Servers MUST remove an "X-CALENDARSERVER-ATTENDEE-COMMENT" property
-
-
-
-Daboo [Page 4]
-
- CalDAV Private Attendee Comments August 2008
-
-
- if the corresponding "ATTENDEE" property is removed by the Organizer.
-
- Servers MUST NOT include "X-CALENDARSERVER-ATTENDEE-COMMENT"
- properties in scheduling messages sent to Attendees triggered by
- changes to an Organizer's scheduling object resource. Clients SHOULD
- ensure that "X-CALENDARSERVER-ATTENDEE-COMMENT" properties are not
- included in any iCalendar data "exported" to other calendar systems
- or sent as scheduling messages by the client.
-
-
-4. New features
-
-4.1. iCalendar Changes
-
- This specification introduces a new iCalendar properties
- "X-CALENDARSERVER-PRIVATE-COMMENT" and "X-CALENDARSERVER-ATTENDEE-
- COMMENT" for use in iCalendar components.
-
-4.1.1. Changes to VEVENT Component
-
- The definition of the properties allowed in a "VEVENT" component is
- extended as follows:
-
- eventprop /=
-
- ; 'privatecomment' is optional,
- ; but MUST NOT occur more than once
-
- privatecomment /
-
- ; 'attendeecomment' is optional,
- ; and MAY occur more than once
-
- attendeecomment
-
-4.1.2. Changes to VTODO Component
-
- The definition of the properties allowed in a "VTODO" component is
- extended as follows:
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 5]
-
- CalDAV Private Attendee Comments August 2008
-
-
- todoprop /=
-
- ; 'privatecomment' is optional,
- ; but MUST NOT occur more than once
-
- privatecomment /
-
- ; 'attendeecomment' is optional,
- ; and MAY occur more than once
-
- attendeecomment
-
-4.1.3. Changes to VJOURNAL Component
-
- The definition of the properties allowed in a "VJOURNAL" component is
- extended as follows:
-
- jourprop /=
-
- ; 'privatecomment' is optional,
- ; but MUST NOT occur more than once
-
- privatecomment /
-
- ; 'attendeecomment' is optional,
- ; and MAY occur more than once
-
- attendeecomment
-
-4.1.4. Private Comment Property
-
- Property Name: X-CALENDARSERVER-PRIVATE-COMMENT
-
- Purpose: A private comment that an Attendee adds to their copy of an
- event and that gets communicated to the Organizer by the server.
-
- Value Type: TEXT
-
- Property Parameters: IANA, non-standard, alternate text
- representation and language property parameters can be specified
- on this property.
-
- Conformance: This property can be specified once in "VEVENT",
- "VTODO", and "VJOURNAL" calendar components.
-
-
-
-
-
-
-
-Daboo [Page 6]
-
- CalDAV Private Attendee Comments August 2008
-
-
- Description: This property can be added by an Attendee to their copy
- of a calendar component in a scheduling object resource. See
- Section 3.1.
-
- Format Definition: This property is defined by the following
- notation:
-
- privatecomment = "X-CALENDARSERVER-PRIVATE-COMMENT"
- privatecommentparam ":" text CRLF
-
- privatecommentparam = *(
-
- ; the following are OPTIONAL,
- ; but MUST NOT occur more than once
-
- (";" altrepparam) / (";" languageparam) /
-
- ; the following is OPTIONAL,
- ; and MAY occur more than once
-
- (";" other-param)
-
- )
-
- Example:
-
- X-CALENDARSERVER-PRIVATE-COMMENT:Sorry I cannot attend the mee
- ting at the specified time. I am free one hour later though.
-
-4.1.5. Attendee Comment Property
-
- Property Name: X-CALENDARSERVER-ATTENDEE-COMMENT
-
- Purpose: A private Attendee comment from an Attendee to the
- Organizer, as recorded by the server.
-
- Value Type: TEXT
-
- Property Parameters: IANA, non-standard, alternate text
- representation, language, timestamp and attendee property
- parameters can be specified on this property.
-
- Conformance: This property can be specified multiple times in
- "VEVENT", "VTODO", and "VJOURNAL" calendar components. However,
- it MUST only occur once in each component with the same
- "X-CALENDARSERVER-ATTENDEE-REF" parameter value.
-
-
-
-
-
-Daboo [Page 7]
-
- CalDAV Private Attendee Comments August 2008
-
-
- Description: This property is added or updated by the server as a
- result of receiving a scheduling message from an Attendee. See
- Section 3.2.
-
- Format Definition: This property is defined by the following
- notation:
-
- attendeecomment = "X-CALENDARSERVER-ATTENDEE-COMMENT"
- attendeecommentparam ":" text CRLF
-
- attendeecommentparam = *(
-
- ; the following are REQUIRED,
- ; but MUST occur only once
-
- (";" dtstampparam) / (";" attendeerefparam) /
-
- ; the following are OPTIONAL,
- ; but MUST NOT occur more than once
-
- (";" altrepparam) / (";" languageparam) /
-
- ; the following is OPTIONAL,
- ; and MAY occur more than once
-
- (";" other-param)
-
- )
-
- Example:
-
- X-CALENDARSERVER-ATTENDEE-COMMENT;X-CALENDARSERVER-DTSTAMP=20080814T
- 114816Z;X-CALENDARSERVER-ATTENDEE-REF="mailto:cyrus at example.com":So
- rry I cannot attend the meeting at the specified time. I am free on
- e hour later though.
-
-4.1.6. Date-time Stamp Property Parameter
-
- Parameter Name: X-CALENDARSERVER-DTSTAMP
-
- Purpose: Indicates when an iCalendar property was updated by the
- server.
-
- Format Definition: This property parameter is defined by the
- following notation:
-
- dtstampparam = "X-CALENDARSERVER-DTSTAMP" "=" date-time
- ; MUST be a date-time in UTC
-
-
-
-Daboo [Page 8]
-
- CalDAV Private Attendee Comments August 2008
-
-
- Description: This parameter indicates when specific iCalendar
- properties were added or changed as the result of the server
- automatically updating a scheduling object resource.
-
- Example:
-
- X-CALENDARSERVER-ATTENDEE-COMMENT;X-CALENDARSERVER-DTSTAMP=20080814T
- 114816Z;X-CALENDARSERVER-ATTENDEE-REF="mailto:cyrus at example.com":So
- rry I cannot attend the meeting at the specified time. I am free on
- e hour later though.
-
-4.1.7. Attendee Reference Property Parameter
-
- Parameter Name: X-CALENDARSERVER-ATTENDEE-REF
-
- Purpose: Relates an iCalendar property to a particular "ATTENDEE"
- property in the same calendar component.
-
- Format Definition: This property parameter is defined by the
- following notation:
-
- attendeerefparam = "X-CALENDARSERVER-ATTENDEE-REF" "="
- DQUOTE cal-address DQUOTE
-
- Description: This parameter relates a particular property to a
- specific "ATTENDEE" property in the same calendar component. It
- is used to tie Attendee comments back to the actual Attendee who
- made them.
-
- Example:
-
- X-CALENDARSERVER-ATTENDEE-COMMENT;X-CALENDARSERVER-DTSTAMP=20080814T
- 114816Z;X-CALENDARSERVER-ATTENDEE-REF="mailto:cyrus at example.com":So
- rry I cannot attend the meeting at the specified time. I am free on
- e hour later though.
-
-4.2. CalDAV Changes
-
-4.2.1. OPTIONS Request
-
- A server supporting the features described in this document MUST
- include "calendarserver-private-comments" as a field in the DAV
- response header from an OPTIONS request on all calendar resources. A
- value of "calendarserver-private-comments" in the DAV response header
- MUST indicate that the server supports all MUST level requirements
- specified in this document.
-
-
-
-
-
-Daboo [Page 9]
-
- CalDAV Private Attendee Comments August 2008
-
-
-4.2.1.1. Example: Using OPTIONS for the Discovery of Private Attendee
- Comments Support
-
- >> Request <<
-
- OPTIONS /home/cyrus/calendars/ HTTP/1.1
- Host: cal.example.com
-
- >> Response <<
-
- HTTP/1.1 200 OK
- Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
- Allow: PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL
- DAV: 1, 2, access-control, calendar-access
- DAV: calendarserver-private-comments
- Date: Sat, 11 Nov 2006 09:32:12 GMT
- Content-Length: 0
-
- In this example, the OPTIONS method returns the value
- "calendarserver-private-comments" in the DAV response header to
- indicate that the collection "/home/cyrus/calendars/" supports the
- behavior defined in this specification.
-
-4.2.2. Handling clients that do not preserve X- properties
-
- TODO:
-
-4.2.3. New pre-conditions for PUT
-
- The following pre-conditions for a PUT request against a calendar
- resource are defined:
-
- (CS:valid-attendee-comment-change):Only the server is allowed to
- the value and parameters on an "X-CALENDARSERVER-ATTENDEE-COMMENT"
- property.
-
- If these pre-conditions are violated the server MUST return a DAV:
- error response with the appropriate XML element indicating the pre-
- condition being violated in the response to the PUT request.
-
-
-5. Security Considerations
-
- TODO:
-
-
-
-
-
-
-
-Daboo [Page 10]
-
- CalDAV Private Attendee Comments August 2008
-
-
-6. IANA Considerations
-
- This document does not require any actions on the part of IANA.
-
-
-7. Normative References
-
- [I-D.desruisseaux-caldav-sched]
- Daboo, C., Desruisseaux, B., and L. Dusseault, "CalDAV
- Scheduling Extensions to WebDAV",
- draft-desruisseaux-caldav-sched-04 (work in progress),
- November 2007.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2445] Dawson, F. and Stenerson, D., "Internet Calendaring and
- Scheduling Core Object Specification (iCalendar)",
- RFC 2445, November 1998.
-
- [RFC2446] Silverberg, S., Mansour, S., Dawson, F., and R. Hopson,
- "iCalendar Transport-Independent Interoperability Protocol
- (iTIP) Scheduling Events, BusyTime, To-dos and Journal
- Entries", RFC 2446, November 1998.
-
- [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
- "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
- March 2007.
-
-
-Appendix A. Acknowledgments
-
- This specification is the result of discussions between the Apple
- calendar server and client teams.
-
-
-Author's Address
-
- Cyrus Daboo
- Apple Inc.
- 1 Infinite Loop
- Cupertino, CA 95014
- USA
-
- Email: cyrus at daboo.name
- URI: http://www.apple.com/
-
-
-
-
-
-Daboo [Page 11]
-
Deleted: CalendarServer/trunk/doc/Extensions/caldav-privatecomments-00.xml
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-privatecomments-00.xml 2008-10-09 15:44:42 UTC (rev 3135)
+++ CalendarServer/trunk/doc/Extensions/caldav-privatecomments-00.xml 2008-10-09 15:45:02 UTC (rev 3136)
@@ -1,435 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
-<!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
-<!ENTITY rfc2445 PUBLIC '' 'bibxml/reference.RFC.2445.xml'>
-<!ENTITY rfc2446 PUBLIC '' 'bibxml/reference.RFC.2446.xml'>
-<!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
-<!ENTITY I-D.desruisseaux-caldav-sched PUBLIC '' 'bibxml3/reference.I-D.desruisseaux-caldav-sched.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 private="Calendar Server Extension"?>
-<rfc ipr="none" docName='caldav-privatecomments-00'>
- <front>
- <title abbrev="CalDAV Private Attendee Comments">Private Attendee Comments in CalDAV Scheduling</title>
- <author initials="C." surname="Daboo" fullname="Cyrus Daboo">
- <organization abbrev="Apple">
- Apple Inc.
- </organization>
- <address>
- <postal>
- <street>1 Infinite Loop</street>
- <city>Cupertino</city>
- <region>CA</region>
- <code>95014</code>
- <country>USA</country>
- </postal>
- <email>cyrus at daboo.name</email>
- <uri>http://www.apple.com/</uri>
- </address>
- </author>
- <date year='2008'/>
- <abstract>
- <t>
- This document defines an extension to CalDAV Scheduling that enables Attendees to communicate private comments back to an Organizer, and for the Organizer to see each Attendees' comments.
- </t>
- </abstract>
- </front>
- <middle>
- <section title='Introduction'>
- <t>
- Internet calendaring and scheduling standards are defined by <xref target="RFC2445">iCalendar</xref> and <xref target="RFC2446">iTIP</xref>. The <xref target="RFC4791">CalDAV Access</xref> standard defines a way to access calendar data stored on a server, and the <xref target="I-D.desruisseaux-caldav-sched">CalDAV Scheduling</xref> draft defines how scheduling occurs between users of a CalDAV server.
- </t>
- <t>
- It is often the case that an Attendee of an event wants to communicate information back to an Organizer when they respond to a meeting invitation. Sometimes this is to tell the Organizer the reason why an invite was declined, sometimes to add addition information to an acceptance. Typically these communications are expected to be private as they may contain comments about other Attendees.
- </t>
- <t>
- This specification defines new iCalendar properties and parameters that are used by clients to pass private comments between Attendees and Organizers of events being scheduling via CalDAV scheduling. It also defines an extension to CalDAV scheduling that defines how a server automatically processes the comments to ensure they are communicated properly between the Attendee and Organizer.
- </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>
- The namespace "http://calendarserver.org/ns/" is used for XML elements defined in this specification. When XML element types in this namespace are referenced in this document outside of the context of an XML fragment, the string "CS:" will be prefixed to the element type names respectively.
- </t>
- <t>
- The prefix X-CALENDARSERVER- is used for all iCalendar properties and parameters defined in this extension.
- </t>
- </section>
-
- <!--
- <section title="Open Issues">
- <t>
- <list style="numbers">
- <t>
- None right now.
- </t>
- </list>
- </t>
- </section>
- -->
-
- <section title="New behavior">
- <section anchor="attendee" title="Attendee">
- <t>When an Attendee wants to send a private comment to an Organizer, the Attendee's calendar user agent adds or updates an "X-CALENDARSERVER-PRIVATE-COMMENT" property in each calendar component of a scheduling object resource to which the comment applies. The value of the comment is the actual message the Attendee is sending.</t>
- <t>The addition or update of any "X-CALENDARSERVER-PRIVATE-COMMENT" property causes the server to send a scheduling message to the Organizer as an iTIP "REPLY", and that MUST include the "X-CALENDARSERVER-PRIVATE-COMMENT" properties in addition to the normal properties sent as part of that scheduling message.</t>
- </section>
- <section anchor="organizer" title="Organizer">
- <t>When a scheduling message from an Attendee is processed by the server, the server will check for the presence of a "X-CALENDARSERVER-PRIVATE-COMMENT" property in each component of the scheduling message and compare this with the scheduling object resource corresponding to the scheduling message currently stored on a live calendar belonging to the Organizer. For each component in the scheduling message, the server will identify the corresponding component in the scheduling object resource (possibly creating a new overridden component instance if needed) and do the following:</t>
- <texttable>
- <ttcol>State</ttcol>
- <ttcol>Description</ttcol>
-
- <c>State 1</c>
- <c>Does the scheduling message contain a "X-CALENDARSERVER-PRIVATE-COMMENT" property</c>
-
- <c> </c>
- <c> </c>
-
- <c>State 2</c>
- <c>Does the scheduling object resource contain a "X-CALENDARSERVER-ATTENDEE-COMMENT" property with an "X-CALENDARSERVER-ATTENDEE-REF" parameter value that matches the "ATTENDEE" value in the scheduling message</c>
- </texttable>
- <texttable>
- <ttcol>State 1</ttcol>
- <ttcol>State 2</ttcol>
- <ttcol>Server Action</ttcol>
-
- <c>No</c>
- <c>No</c>
- <c>No additional processing required.</c>
-
- <c> </c>
- <c> </c>
- <c> </c>
-
- <c>No</c>
- <c>Yes</c>
- <c>Note 1.</c>
-
- <c> </c>
- <c> </c>
- <c> </c>
-
- <c>Yes</c>
- <c>No</c>
- <c>Note 2.</c>
-
- <c> </c>
- <c> </c>
- <c> </c>
-
- <c>Yes</c>
- <c>Yes</c>
- <c>Note 3.</c>
-
- </texttable>
- <t>
- <list style="hanging">
- <t hangText="Note 1:">The server MUST update the "X-CALENDARSERVER-DTSTAMP" parameter value on the "X-CALENDARSERVER-ATTENDEE-COMMENT" property, and it MUST set the value of that property to an empty string. It MUST remove all property parameters other than "X-CALENDARSERVER-DTSTAMP" and "X-CALENDARSERVER-ATTENDEE-REF".</t>
- <t hangText="Note 2:">The server MUST create an "X-CALENDARSERVER-ATTENDEE-COMMENT" and MUST set the "X-CALENDARSERVER-DTSTAMP" and "X-CALENDARSERVER-ATTENDEE-REF" parameter values, and MUST set the value of the new property to the value of the "X-CALENDARSERVER-PRIVATE-COMMENT" property. Other parameter values on the "X-CALENDARSERVER-PRIVATE-COMMENT" property MAY be copied to the "X-CALENDARSERVER-ATTENDEE-COMMENT" property if supported.</t>
- <t hangText="Note 3:">The server MUST update the "X-CALENDARSERVER-DTSTAMP" parameter value on the "X-CALENDARSERVER-ATTENDEE-COMMENT" property, and MUST set the value of the new property to the value of the "X-CALENDARSERVER-PRIVATE-COMMENT" property. It MUST remove all property parameters other than "X-CALENDARSERVER-DTSTAMP" and "X-CALENDARSERVER-ATTENDEE-REF", and other parameter values on the "X-CALENDARSERVER-PRIVATE-COMMENT" property MAY be copied to the "X-CALENDARSERVER-ATTENDEE-COMMENT" property if supported.</t>
- </list>
- </t>
- <t>When creating or updating the "X-CALENDARSERVER-DTSTAMP" property parameter value, the server MUST set it to the date-time UTC value when the processing of the scheduling message took place.</t>
- <t>When creating the "X-CALENDARSERVER-ATTENDEE-REF" property parameter value, the server MUST set it to the "ATTENDEE" property value in the scheduling message being processed. As the scheduling message is an iTIP "REPLY" only one "ATTENDEE" property will be present in each component, and the value corresponds to the Attendee sending the reply.</t>
- <t>Servers MUST remove an "X-CALENDARSERVER-ATTENDEE-COMMENT" property if the corresponding "ATTENDEE" property is removed by the Organizer.</t>
- <t>Servers MUST NOT include "X-CALENDARSERVER-ATTENDEE-COMMENT" properties in scheduling messages sent to Attendees triggered by changes to an Organizer's scheduling object resource. Clients SHOULD ensure that "X-CALENDARSERVER-ATTENDEE-COMMENT" properties are not included in any iCalendar data "exported" to other calendar systems or sent as scheduling messages by the client.</t>
- </section>
- </section>
- <section title='New features'>
- <section title='iCalendar Changes'>
- <t>This specification introduces a new iCalendar properties "X-CALENDARSERVER-PRIVATE-COMMENT" and "X-CALENDARSERVER-ATTENDEE-COMMENT" for use in iCalendar components.</t>
- <section title="Changes to VEVENT Component">
- <t>The definition of the properties allowed in a "VEVENT" component is extended as follows:
- <figure>
- <artwork><![CDATA[
-eventprop /=
-
- ; 'privatecomment' is optional,
- ; but MUST NOT occur more than once
-
- privatecomment /
-
- ; 'attendeecomment' is optional,
- ; and MAY occur more than once
-
- attendeecomment
- ]]></artwork>
- </figure>
- </t>
- </section>
- <section title="Changes to VTODO Component">
- <t>The definition of the properties allowed in a "VTODO" component is extended as follows:
- <figure>
- <artwork><![CDATA[
-todoprop /=
-
- ; 'privatecomment' is optional,
- ; but MUST NOT occur more than once
-
- privatecomment /
-
- ; 'attendeecomment' is optional,
- ; and MAY occur more than once
-
- attendeecomment
- ]]></artwork>
- </figure>
- </t>
- </section>
- <section title="Changes to VJOURNAL Component">
- <t>The definition of the properties allowed in a "VJOURNAL" component is extended as follows:
- <figure>
- <artwork><![CDATA[
-jourprop /=
-
- ; 'privatecomment' is optional,
- ; but MUST NOT occur more than once
-
- privatecomment /
-
- ; 'attendeecomment' is optional,
- ; and MAY occur more than once
-
- attendeecomment
- ]]></artwork>
- </figure>
- </t>
- </section>
- <section title="Private Comment Property">
- <t>
- <list style="hanging">
- <t hangText="Property Name:">X-CALENDARSERVER-PRIVATE-COMMENT</t>
- <t hangText="Purpose:">A private comment that an Attendee adds to their copy of an event and that gets communicated to the Organizer by the server.</t>
- <t hangText="Value Type:">TEXT</t>
- <t hangText="Property Parameters:">IANA, non-standard, alternate text representation and language property parameters can be specified on this property.</t>
- <t hangText="Conformance:">This property can be specified once in "VEVENT", "VTODO", and "VJOURNAL" calendar components.</t>
- <t hangText="Description:">This property can be added by an Attendee to their copy of a calendar component in a scheduling object resource. See <xref target="attendee"/>.</t>
- <t hangText="Format Definition:">This property is defined by the following notation:
- <figure><artwork><![CDATA[
-privatecomment = "X-CALENDARSERVER-PRIVATE-COMMENT"
- privatecommentparam ":" text CRLF
-
-privatecommentparam = *(
-
- ; the following are OPTIONAL,
- ; but MUST NOT occur more than once
-
- (";" altrepparam) / (";" languageparam) /
-
- ; the following is OPTIONAL,
- ; and MAY occur more than once
-
- (";" other-param)
-
- )
- ]]></artwork></figure></t>
- <t hangText="Example:">
- <figure>
- <artwork><![CDATA[
- X-CALENDARSERVER-PRIVATE-COMMENT:Sorry I cannot attend the mee
- ting at the specified time. I am free one hour later though.
- ]]></artwork>
- </figure>
- </t>
- </list>
- </t>
- </section>
-
- <section title="Attendee Comment Property">
- <t>
- <list style="hanging">
- <t hangText="Property Name:">X-CALENDARSERVER-ATTENDEE-COMMENT</t>
- <t hangText="Purpose:">A private Attendee comment from an Attendee to the Organizer, as recorded by the server.</t>
- <t hangText="Value Type:">TEXT</t>
- <t hangText="Property Parameters:">IANA, non-standard, alternate text representation, language, timestamp and attendee property parameters can be specified on this property.</t>
- <t hangText="Conformance:">This property can be specified multiple times in "VEVENT", "VTODO", and "VJOURNAL" calendar components. However, it MUST only occur once in each component with the same "X-CALENDARSERVER-ATTENDEE-REF" parameter value.</t>
- <t hangText="Description:">This property is added or updated by the server as a result of receiving a scheduling message from an Attendee. See <xref target="organizer"/>.</t>
- <t hangText="Format Definition:">This property is defined by the following notation:
- <figure><artwork><![CDATA[
-attendeecomment = "X-CALENDARSERVER-ATTENDEE-COMMENT"
- attendeecommentparam ":" text CRLF
-
-attendeecommentparam = *(
-
- ; the following are REQUIRED,
- ; but MUST occur only once
-
- (";" dtstampparam) / (";" attendeerefparam) /
-
- ; the following are OPTIONAL,
- ; but MUST NOT occur more than once
-
- (";" altrepparam) / (";" languageparam) /
-
- ; the following is OPTIONAL,
- ; and MAY occur more than once
-
- (";" other-param)
-
- )
- ]]></artwork></figure></t>
- <t hangText="Example:">
- <figure>
- <artwork><![CDATA[
- X-CALENDARSERVER-ATTENDEE-COMMENT;X-CALENDARSERVER-DTSTAMP=20080814T
- 114816Z;X-CALENDARSERVER-ATTENDEE-REF="mailto:cyrus at example.com":So
- rry I cannot attend the meeting at the specified time. I am free on
- e hour later though.
- ]]></artwork>
- </figure>
- </t>
- </list>
- </t>
- </section>
-
- <section title="Date-time Stamp Property Parameter">
- <t>
- <list style="hanging">
- <t hangText="Parameter Name:">X-CALENDARSERVER-DTSTAMP</t>
- <t hangText="Purpose:">Indicates when an iCalendar property was updated by the server.</t>
- <t hangText="Format Definition:">This property parameter is defined by the following notation:
- <figure>
- <artwork><![CDATA[
-dtstampparam = "X-CALENDARSERVER-DTSTAMP" "=" date-time
- ; MUST be a date-time in UTC
- ]]></artwork>
- </figure>
- </t>
- <t hangText="Description:">This parameter indicates when specific iCalendar properties were added or changed as the result of the server automatically updating a scheduling object resource.</t>
- <t hangText="Example:">
- <figure>
- <artwork><![CDATA[
- X-CALENDARSERVER-ATTENDEE-COMMENT;X-CALENDARSERVER-DTSTAMP=20080814T
- 114816Z;X-CALENDARSERVER-ATTENDEE-REF="mailto:cyrus at example.com":So
- rry I cannot attend the meeting at the specified time. I am free on
- e hour later though.
- ]]></artwork>
- </figure>
- </t>
- </list>
- </t>
- </section>
-
- <section title="Attendee Reference Property Parameter">
- <t>
- <list style="hanging">
- <t hangText="Parameter Name:">X-CALENDARSERVER-ATTENDEE-REF</t>
- <t hangText="Purpose:">Relates an iCalendar property to a particular "ATTENDEE" property in the same calendar component.</t>
- <t hangText="Format Definition:">This property parameter is defined by the following notation:
- <figure>
- <artwork><![CDATA[
-attendeerefparam = "X-CALENDARSERVER-ATTENDEE-REF" "="
- DQUOTE cal-address DQUOTE
- ]]></artwork>
- </figure>
- </t>
- <t hangText="Description:">This parameter relates a particular property to a specific "ATTENDEE" property in the same calendar component. It is used to tie Attendee comments back to the actual Attendee who made them.</t>
- <t hangText="Example:">
- <figure>
- <artwork><![CDATA[
- X-CALENDARSERVER-ATTENDEE-COMMENT;X-CALENDARSERVER-DTSTAMP=20080814T
- 114816Z;X-CALENDARSERVER-ATTENDEE-REF="mailto:cyrus at example.com":So
- rry I cannot attend the meeting at the specified time. I am free on
- e hour later though.
- ]]></artwork>
- </figure>
- </t>
- </list>
- </t>
- </section>
- </section>
- <section title="CalDAV Changes">
- <section title="OPTIONS Request">
- <t>A server supporting the features described in this document MUST include "calendarserver-private-comments" as a field in the DAV response header from an OPTIONS request on all calendar resources. A value of "calendarserver-private-comments" in the DAV response header MUST indicate that the server supports all MUST level requirements specified in this document.</t>
- <section title="Example: Using OPTIONS for the Discovery of Private Attendee Comments Support">
- <figure>
- <artwork><![CDATA[
- >> Request <<
-
- OPTIONS /home/cyrus/calendars/ HTTP/1.1
- Host: cal.example.com
-
- >> Response <<
-
- HTTP/1.1 200 OK
- Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE
- Allow: PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL
- DAV: 1, 2, access-control, calendar-access
- DAV: calendarserver-private-comments
- Date: Sat, 11 Nov 2006 09:32:12 GMT
- Content-Length: 0
- ]]></artwork>
- </figure>
-
- <t>In this example, the OPTIONS method returns the value "calendarserver-private-comments" in the DAV response header to indicate that the collection "/home/cyrus/calendars/" supports the behavior defined in this specification.</t>
- </section>
- </section>
-
- <section anchor="x-compatability" title="Handling clients that do not preserve X- properties">
- <t>TODO:</t>
- </section>
-
- <section title="New pre-conditions for PUT">
- <t>The following pre-conditions for a PUT request against a calendar resource are defined:
- <list>
- <t>(CS:valid-attendee-comment-change):Only the server is allowed to the value and parameters on an "X-CALENDARSERVER-ATTENDEE-COMMENT" property.</t>
- </list>
- </t>
- <t>
- If these pre-conditions are violated the server MUST return a DAV:error response with the appropriate XML element indicating the pre-condition being violated in the response to the PUT request.
- </t>
- </section>
-
- </section>
- </section>
-
- <section title='Security Considerations'>
- <t>TODO:</t>
- </section>
- <section title='IANA Considerations'>
- <t>
- This document does not require any actions on the part of IANA.
- </t>
- </section>
- </middle>
- <back>
- <references title='Normative References'>
- &rfc2119;
- &rfc2445;
- &rfc2446;
- &rfc4791;
- &I-D.desruisseaux-caldav-sched;
- </references>
-<!--
-<references title='Informative References'>
-</references>
--->
- <section title='Acknowledgments'>
- <t>
- This specification is the result of discussions between the Apple calendar server and client teams.
- </t>
- </section>
- <!--
- <section title='Change History'>
- <t>Changes since -00
- <list style='numbers'>
- <t></t>
- </list>
- </t>
- </section>
- -->
- </back>
-</rfc>
Deleted: CalendarServer/trunk/doc/Extensions/caldav-schedulingchanges-01.txt
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-schedulingchanges-01.txt 2008-10-09 15:44:42 UTC (rev 3135)
+++ CalendarServer/trunk/doc/Extensions/caldav-schedulingchanges-01.txt 2008-10-09 15:45:02 UTC (rev 3136)
@@ -1,504 +0,0 @@
-
-
-
-Calendar Server Extension C. Daboo
- Apple
- September 23, 2008
-
-
- Change Indicators for Processed CalDAV Scheduling Messages
-
-Abstract
-
- This document defines an extension to CalDAV Scheduling that adds a
- change summary for scheduling messages automatically processed by the
- server. It can be used by clients to provide a detailed indication
- to a calendar user of how a calendar object was changed by auto-
- processing of a scheduling message.
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Conventions Used in This Document . . . . . . . . . . . . . . . 2
- 3. New behavior . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 4. New features . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 4.1. CalDAV Changes . . . . . . . . . . . . . . . . . . . . . . 3
- 4.1.1. Change Indicator WebDAV Property . . . . . . . . . . . 3
- 4.1.2. CS:schedule-changes XML element . . . . . . . . . . . . 5
- 4.1.2.1. CS:dtstamp XML Element . . . . . . . . . . . . . . 5
- 4.1.2.2. CS:action XML Element . . . . . . . . . . . . . . . 5
- 4.1.2.3. CS:changes XML Element . . . . . . . . . . . . . . 6
- 4.1.2.4. CS:recurrences XML Element . . . . . . . . . . . . 7
- 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 7
- 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8
- 7. Normative References . . . . . . . . . . . . . . . . . . . . . 8
- Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 8
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 1]
-
- CalDAV Scheduling Change Indicators September 2008
-
-
-1. Introduction
-
- Internet calendaring and scheduling standards are defined by
- iCalendar [RFC2445] and iTIP [RFC2446]. The CalDAV Access [RFC4791]
- standard defines a way to access calendar data stored on a server,
- and the CalDAV Scheduling [I-D.desruisseaux-caldav-sched] draft
- defines how scheduling occurs between users of a CalDAV server.
-
- In CalDAV Scheduling, scheduling messages sent between calendar users
- can be automatically processed by the CalDAV server. Often clients
- need to provide an indication to the user of what changed when such
- auto-processing occurs (e.g. to inform the user that an event was re-
- scheduling or cancelled). Sometimes the client does not have the old
- copy of the automatically updated calendar object to hand, so as a
- result it can't determine changes itself.
-
- This specification defines a new WebDAV property on scheduling
- messages stored in a calendar users scheduling Inbox collection.
- This property is automatically generated by the server and contains
- XML data representing the key changes made by the server when it
- auto-processed the scheduling message. Clients can use the data in
- this property to provide an indication to a calendar user as to what
- changed.
-
-
-2. Conventions Used in This Document
-
- 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 [RFC2119].
-
- 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.
-
- The namespace "http://calendarserver.org/ns/" is used for XML
- elements defined in this specification. When XML element types in
- this namespace are referenced in this document outside of the context
- of an XML fragment, the string "CS:" will be prefixed to the element
- type names respectively.
-
-
-3. New behavior
-
- When a CalDAV scheduling server automatically processes a scheduling
- message in a scheduling inbox collection, it SHOULD determine what
- changes were applied to the matching scheduling object resource and
-
-
-
-Daboo [Page 2]
-
- CalDAV Scheduling Change Indicators September 2008
-
-
- create an XML data value (as described next) and store that in the
- CS:schedule-changes property on the scheduling message resource.
- When a client checks the scheduling inbox collection to look for
- scheduling messages that need to be acknowledged by a calendar user,
- the client MAY check for the presence of the CS:schedule-changes and
- retrieve its value via a PROPFIND or CALDAV:multiget REPORT request.
- The XML data value can then be parsed and useful information
- extracted and presented to the user in whatever way is appropriate
- for the client.
-
-
-4. New features
-
-4.1. CalDAV Changes
-
-4.1.1. Change Indicator WebDAV Property
-
- Name: schedule-changes
-
- Namespace: http://calendarserver.org/ns/
-
- Purpose: Indicates what changed when a scheduling message was
- automatically processed by a server.
-
- Protected: This property MUST be protected and SHOULD NOT be
- returned by a PROPFIND allprop request (as defined in Section 14.2
- of [RFC4918]).
-
- COPY/MOVE behavior: This property value SHOULD be kept during a MOVE
- operation, but is normally re-initialized when a resource is
- created with a COPY. It should not be set in a COPY.
-
- Description: This property SHOULD be defined on all scheduling
- messages that have been automatically processed by the server. If
- present, it contains a single CS:calendar-changes XML element.
-
- Definition:
-
- <!ELEMENT schedule-changes
- (dtstamp, action) >
-
- <!ELEMENT dtstamp CDATA>
- <!-- Date-time value in UTC -->
-
- <!ELEMENT action (create|update|cancel|reply)>
- <!-- Type of change that occurred -->
-
- <!ELEMENT create EMPTY>
-
-
-
-Daboo [Page 3]
-
- CalDAV Scheduling Change Indicators September 2008
-
-
- <!-- New calendar object was created -->
-
- <!ELEMENT update (changes, recurrences?)>
- <!-- Calendar object was changed -->
-
- <!ELEMENT cancel (recurrences?)>
- <!-- Calendar object or instances were cancelled -->
-
- <!ELEMENT reply (attendee, partstat?, private-comment?,
- recurrences?)>
- <!-- Reply received from attendee -->
-
- <!ELEMENT attendee CDATA>
- <!-- ATTENDEE iCalendar property value -->
-
- <!ELEMENT partstat EMPTY>
- <!-- ATTENDEE PARTSTAT property parameter value changed -->
-
- <!ELEMENT private-comment EMPTY>
- <!-- X-CALENDARSERVER-PRIVATE-COMMENT property value
- changed -->
-
- <!ELEMENT changes (datetime?,
- location?,
- summary?,
- description?,
- recurrence?,
- status?,
- attendees?,
- attendee-partstat?)>
-
- <!ELEMENT datetime EMPTY>
- <!ELEMENT location EMPTY>
- <!ELEMENT summary EMPTY>
- <!ELEMENT description EMPTY>
- <!ELEMENT recurrence EMPTY>
- <!ELEMENT status EMPTY>
- <!ELEMENT attendees EMPTY>
- <!ELEMENT attendee-partstat EMPTY>
-
- <!ELEMENT recurrences (master?, recurrenceid*)>
- <!-- Which instances were affected by the change -->
-
- <!ELEMENT master EMPTY>
- <!-- The "master" instance was affected -->
-
- <!ELEMENT recurrenceid CDATA>
- <!-- RECURRENCE-ID value for the affected instance -->
-
-
-
-Daboo [Page 4]
-
- CalDAV Scheduling Change Indicators September 2008
-
-
- Example:
-
- <CS:schedule-changes
- xmlns:CS="http://calendarserver.org/ns/">
- <CS:dtstamp>20080818T223423Z</CS:dtstamp>
- <CS:action><CS:create/></CS:action>
- </CS:schedule-changes>
-
- Example:
-
- <CS:schedule-changes
- xmlns:CS="http://calendarserver.org/ns/">
- <CS:dtstamp>20080818T223423Z</CS:dtstamp>
- <CS:action>
- <CS:update>
- <CS:changes>
- <CS:summary/>
- </CS:changes>
- <CS:recurrences/>
- </CS:update>
- </CS:action>
- </CS:schedule-changes>
-
-4.1.2. CS:schedule-changes XML element
-
- The CS:schedule-changes XML element is used to indicate what changes
- were made when the server automatically processed a scheduling
- message. There are four child elements that can appear, and each is
- described next.
-
-4.1.2.1. CS:dtstamp XML Element
-
- This elements contains a text value in the form of an iCalendar Date-
- Time value in UTC. This value is the time at which the automatic
- processing took place.
-
-4.1.2.2. CS:action XML Element
-
- This element indicates the nature of the changes that took place:
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 5]
-
- CalDAV Scheduling Change Indicators September 2008
-
-
- +-----------+-------------------------------------------------------+
- | Child | Description |
- | Element | |
- +-----------+-------------------------------------------------------+
- | CS:create | A new calendar object was created in the default |
- | | calendar of the recipient. |
- | | |
- | CS:update | An update to an existing calendar object occurred. |
- | | The CS:changes and CS:recurrences child elements |
- | | indicate what the changes were and which instances |
- | | were affected. If the calendar object is not |
- | | recurring, CS:recurrences MUST NOT be present. If |
- | | all or any individual instances of a recurring |
- | | calendar object were affected, then CS:recurrences |
- | | MUST be present and indicate which instances were |
- | | affected. |
- | | |
- | CS:cancel | A cancellation scheduling message was processed. If |
- | | the calendar object is not recurring or all instances |
- | | are being removed, then CS:recurrences MUST NOT be |
- | | present. If any individual instances of a recurring |
- | | calendar object were affected, then CS:recurrences |
- | | MUST be present and indicate which instances were |
- | | affected. |
- | | |
- | CS:reply | An Attendee's reply was processed. The CS:attendee, |
- | | CS:partstat and CS:private-comment elements indicate |
- | | which Attendee replied, what their new "PARTSTAT" was |
- | | set to, and what, if any, private comment was sent. |
- | | The CS:partstat and CS:private-comment child elements |
- | | MUST only be present if the relevant properties were |
- | | changed. If the calendar object is not recurring, |
- | | CS:recurrences MUST NOT be present. If all or any |
- | | individual instances of a recurring calendar object |
- | | were affected, then CS:recurrences MUST be present |
- | | and indicate which instances were affected.. |
- +-----------+-------------------------------------------------------+
-
-4.1.2.3. CS:changes XML Element
-
- This element indicates the key changes that took place:
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 6]
-
- CalDAV Scheduling Change Indicators September 2008
-
-
- +----------------------+--------------------------------------------+
- | Child Element | iCalendar Property changed |
- +----------------------+--------------------------------------------+
- | CS:datetime | "DTSTART", "DTEND", "DURATION", "DUE", or |
- | | "COMPLETED". |
- | | |
- | CS:location | "LOCATION" |
- | | |
- | CS:summary | "SUMMARY" |
- | | |
- | CS:description | "DESCRIPTION" |
- | | |
- | CS:recurrence | "RRULE", "RDATE", "EXDATE" |
- | | |
- | CS:status | "STATUS" |
- | | |
- | CS:attendees | "ATTENDEE" (added or removed) |
- | | |
- | CS:attendee-partstat | "ATTENDEE" ("PARTSTAT" parameter changed) |
- +----------------------+--------------------------------------------+
-
- If a change did take place, but that change does not correspond to
- one indicated by the currently defined child XML elements, then the
- CS:changes element MUST be present but empty.
-
-4.1.2.4. CS:recurrences XML Element
-
- This element indicates which instances were affected by a change:
-
- +-----------------+-------------------------------------------------+
- | Child Element | Description |
- +-----------------+-------------------------------------------------+
- | CS:master | The "master" component defining the recurrence |
- | | pattern was changed. |
- | | |
- | CS:recurrenceid | The instance with the specified "RECURRENCE-ID" |
- | | value was changed. |
- +-----------------+-------------------------------------------------+
-
- If no child elements were specified, then all instances were changed.
-
-
-5. Security Considerations
-
- TODO:
-
-
-
-
-
-
-Daboo [Page 7]
-
- CalDAV Scheduling Change Indicators September 2008
-
-
-6. IANA Considerations
-
- This document does not require any actions on the part of IANA.
-
-
-7. Normative References
-
- [I-D.desruisseaux-caldav-sched]
- Daboo, C., Desruisseaux, B., and L. Dusseault, "CalDAV
- Scheduling Extensions to WebDAV",
- draft-desruisseaux-caldav-sched-04 (work in progress),
- November 2007.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2445] Dawson, F. and Stenerson, D., "Internet Calendaring and
- Scheduling Core Object Specification (iCalendar)",
- RFC 2445, November 1998.
-
- [RFC2446] Silverberg, S., Mansour, S., Dawson, F., and R. Hopson,
- "iCalendar Transport-Independent Interoperability Protocol
- (iTIP) Scheduling Events, BusyTime, To-dos and Journal
- Entries", RFC 2446, November 1998.
-
- [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
- "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
- March 2007.
-
- [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
- Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
-
-
-Appendix A. Acknowledgments
-
- This specification is the result of discussions between the Apple
- calendar server and client teams.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 8]
-
- CalDAV Scheduling Change Indicators September 2008
-
-
-Author's Address
-
- Cyrus Daboo
- Apple Inc.
- 1 Infinite Loop
- Cupertino, CA 95014
- USA
-
- Email: cyrus at daboo.name
- URI: http://www.apple.com/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 9]
-
Deleted: CalendarServer/trunk/doc/Extensions/caldav-schedulingchanges-01.xml
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-schedulingchanges-01.xml 2008-10-09 15:44:42 UTC (rev 3135)
+++ CalendarServer/trunk/doc/Extensions/caldav-schedulingchanges-01.xml 2008-10-09 15:45:02 UTC (rev 3136)
@@ -1,339 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
-<!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
-<!ENTITY rfc2445 PUBLIC '' 'bibxml/reference.RFC.2445.xml'>
-<!ENTITY rfc2446 PUBLIC '' 'bibxml/reference.RFC.2446.xml'>
-<!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
-<!ENTITY rfc4918 PUBLIC '' 'bibxml/reference.RFC.4918.xml'>
-<!ENTITY I-D.desruisseaux-caldav-sched PUBLIC '' 'bibxml3/reference.I-D.desruisseaux-caldav-sched.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 private="Calendar Server Extension"?>
-<rfc ipr="none" docName='caldav-schedulingchanges-00'>
- <front>
- <title abbrev="CalDAV Scheduling Change Indicators">Change Indicators for Processed CalDAV Scheduling Messages</title>
- <author initials="C." surname="Daboo" fullname="Cyrus Daboo">
- <organization abbrev="Apple">
- Apple Inc.
- </organization>
- <address>
- <postal>
- <street>1 Infinite Loop</street>
- <city>Cupertino</city>
- <region>CA</region>
- <code>95014</code>
- <country>USA</country>
- </postal>
- <email>cyrus at daboo.name</email>
- <uri>http://www.apple.com/</uri>
- </address>
- </author>
- <date year='2008'/>
- <abstract>
- <t>
- This document defines an extension to CalDAV Scheduling that adds a change summary for scheduling messages automatically processed by the server. It can be used by clients to provide a detailed indication to a calendar user of how a calendar object was changed by auto-processing of a scheduling message.
- </t>
- </abstract>
- </front>
- <middle>
- <section title='Introduction'>
- <t>
- Internet calendaring and scheduling standards are defined by <xref target="RFC2445">iCalendar</xref> and <xref target="RFC2446">iTIP</xref>. The <xref target="RFC4791">CalDAV Access</xref> standard defines a way to access calendar data stored on a server, and the <xref target="I-D.desruisseaux-caldav-sched">CalDAV Scheduling</xref> draft defines how scheduling occurs between users of a CalDAV server.
- </t>
- <t>
- In CalDAV Scheduling, scheduling messages sent between calendar users can be automatically processed by the CalDAV server. Often clients need to provide an indication to the user of what changed when such auto-processing occurs (e.g. to inform the user that an event was re-scheduling or cancelled). Sometimes the client does not have the old copy of the automatically updated calendar object to hand, so as a result it can't determine changes itself.
- </t>
- <t>
- This specification defines a new WebDAV property on scheduling messages stored in a calendar users scheduling Inbox collection. This property is automatically generated by the server and contains XML data representing the key changes made by the server when it auto-processed the scheduling message. Clients can use the data in this property to provide an indication to a calendar user as to what changed.
- </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>
- The namespace "http://calendarserver.org/ns/" is used for XML elements defined in this specification. When XML element types in this namespace are referenced in this document outside of the context of an XML fragment, the string "CS:" will be prefixed to the element type names respectively.
- </t>
- </section>
-
- <!--
- <section title="Open Issues">
- <t>
- <list style="numbers">
- <t>
- None right now.
- </t>
- </list>
- </t>
- </section>
- -->
-
- <section title="New behavior">
- <t>When a CalDAV scheduling server automatically processes a scheduling message in a scheduling inbox collection, it SHOULD determine what changes were applied to the matching scheduling object resource and create an XML data value (as described next) and store that in the CS:schedule-changes property on the scheduling message resource. When a client checks the scheduling inbox collection to look for scheduling messages that need to be acknowledged by a calendar user, the client MAY check for the presence of the CS:schedule-changes and retrieve its value via a PROPFIND or CALDAV:multiget REPORT request. The XML data value can then be parsed and useful information extracted and presented to the user in whatever way is appropriate for the client.</t>
- </section>
- <section title='New features'>
- <section title="CalDAV Changes">
- <section title="Change Indicator WebDAV Property">
- <t>
-<?rfc compact="no" ?>
- <list style="hanging">
- <t hangText="Name:">schedule-changes</t>
- <t hangText="Namespace:">http://calendarserver.org/ns/</t>
- <t hangText="Purpose:">Indicates what changed when a scheduling message was automatically processed by a server.</t>
- <t hangText="Protected:">This property MUST be protected and 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 SHOULD be kept during a MOVE operation, but is normally re-initialized when a resource is created with a COPY. It should not be set in a COPY.</t>
- <t hangText="Description:">This property SHOULD be defined on all scheduling messages that have been automatically processed by the server. If present, it contains a single CS:calendar-changes XML element.</t>
- <t hangText="Definition:">
- <figure>
- <artwork><![CDATA[
- <!ELEMENT schedule-changes
- (dtstamp, action) >
-
- <!ELEMENT dtstamp CDATA>
- <!-- Date-time value in UTC -->
-
- <!ELEMENT action (create|update|cancel|reply)>
- <!-- Type of change that occurred -->
-
- <!ELEMENT create EMPTY>
- <!-- New calendar object was created -->
-
- <!ELEMENT update (changes, recurrences?)>
- <!-- Calendar object was changed -->
-
- <!ELEMENT cancel (recurrences?)>
- <!-- Calendar object or instances were cancelled -->
-
- <!ELEMENT reply (attendee, partstat?, private-comment?,
- recurrences?)>
- <!-- Reply received from attendee -->
-
- <!ELEMENT attendee CDATA>
- <!-- ATTENDEE iCalendar property value -->
-
- <!ELEMENT partstat EMPTY>
- <!-- ATTENDEE PARTSTAT property parameter value changed -->
-
- <!ELEMENT private-comment EMPTY>
- <!-- X-CALENDARSERVER-PRIVATE-COMMENT property value
- changed -->
-
- <!ELEMENT changes (datetime?,
- location?,
- summary?,
- description?,
- recurrence?,
- status?,
- attendees?,
- attendee-partstat?)>
-
- <!ELEMENT datetime EMPTY>
- <!ELEMENT location EMPTY>
- <!ELEMENT summary EMPTY>
- <!ELEMENT description EMPTY>
- <!ELEMENT recurrence EMPTY>
- <!ELEMENT status EMPTY>
- <!ELEMENT attendees EMPTY>
- <!ELEMENT attendee-partstat EMPTY>
-
- <!ELEMENT recurrences (master?, recurrenceid*)>
- <!-- Which instances were affected by the change -->
-
- <!ELEMENT master EMPTY>
- <!-- The "master" instance was affected -->
-
- <!ELEMENT recurrenceid CDATA>
- <!-- RECURRENCE-ID value for the affected instance -->
-
- ]]></artwork>
- </figure>
- </t>
- <t hangText="Example:">
- <figure>
- <artwork><![CDATA[
-<CS:schedule-changes
- xmlns:CS="http://calendarserver.org/ns/">
- <CS:dtstamp>20080818T223423Z</CS:dtstamp>
- <CS:action><CS:create/></CS:action>
-</CS:schedule-changes>
- ]]></artwork>
- </figure>
- </t>
- <t hangText="Example:">
- <figure>
- <artwork><![CDATA[
-<CS:schedule-changes
- xmlns:CS="http://calendarserver.org/ns/">
- <CS:dtstamp>20080818T223423Z</CS:dtstamp>
- <CS:action>
- <CS:update>
- <CS:changes>
- <CS:summary/>
- </CS:changes>
- <CS:recurrences/>
- </CS:update>
- </CS:action>
-</CS:schedule-changes>
- ]]></artwork>
- </figure>
- </t>
- </list>
-<?rfc compact="yes" ?>
- </t>
- </section>
- <section title="CS:schedule-changes XML element">
- <t>The CS:schedule-changes XML element is used to indicate what changes were made when the server automatically processed a scheduling message. There are four child elements that can appear, and each is described next.</t>
- <section title="CS:dtstamp XML Element">
- <t>This elements contains a text value in the form of an iCalendar Date-Time value in UTC. This value is the time at which the automatic processing took place.</t>
- </section>
- <section title="CS:action XML Element">
- <t>This element indicates the nature of the changes that took place:</t>
- <texttable>
- <ttcol>Child Element</ttcol>
- <ttcol>Description</ttcol>
-
- <c>CS:create</c>
- <c>A new calendar object was created in the default calendar of the recipient.</c>
-
- <c> </c>
- <c> </c>
-
- <c>CS:update</c>
- <c>An update to an existing calendar object occurred. The CS:changes and CS:recurrences child elements indicate what the changes were and which instances were affected. If the calendar object is not recurring, CS:recurrences MUST NOT be present. If all or any individual instances of a recurring calendar object were affected, then CS:recurrences MUST be present and indicate which instances were affected.</c>
-
- <c> </c>
- <c> </c>
-
- <c>CS:cancel</c>
- <c>A cancellation scheduling message was processed. If the calendar object is not recurring or all instances are being removed, then CS:recurrences MUST NOT be present. If any individual instances of a recurring calendar object were affected, then CS:recurrences MUST be present and indicate which instances were affected.</c>
-
- <c> </c>
- <c> </c>
-
- <c>CS:reply</c>
- <c>An Attendee's reply was processed. The CS:attendee, CS:partstat and CS:private-comment elements indicate which Attendee replied, what their new "PARTSTAT" was set to, and what, if any, private comment was sent. The CS:partstat and CS:private-comment child elements MUST only be present if the relevant properties were changed. If the calendar object is not recurring, CS:recurrences MUST NOT be present. If all or any individual instances of a recurring calendar object were affected, then CS:recurrences MUST be present and indicate which instances were affected..</c>
- </texttable>
- </section>
- <section title="CS:changes XML Element">
- <t>This element indicates the key changes that took place:</t>
- <texttable>
- <ttcol>Child Element</ttcol>
- <ttcol>iCalendar Property changed</ttcol>
-
- <c>CS:datetime</c>
- <c>"DTSTART", "DTEND", "DURATION", "DUE", or "COMPLETED".</c>
-
- <c> </c>
- <c> </c>
-
- <c>CS:location</c>
- <c>"LOCATION"</c>
-
- <c> </c>
- <c> </c>
-
- <c>CS:summary</c>
- <c>"SUMMARY"</c>
-
- <c> </c>
- <c> </c>
-
- <c>CS:description</c>
- <c>"DESCRIPTION"</c>
-
- <c> </c>
- <c> </c>
-
- <c>CS:recurrence</c>
- <c>"RRULE", "RDATE", "EXDATE"</c>
-
- <c> </c>
- <c> </c>
-
- <c>CS:status</c>
- <c>"STATUS"</c>
-
- <c> </c>
- <c> </c>
-
- <c>CS:attendees</c>
- <c>"ATTENDEE" (added or removed)</c>
-
- <c> </c>
- <c> </c>
-
- <c>CS:attendee-partstat</c>
- <c>"ATTENDEE" ("PARTSTAT" parameter changed)</c>
- </texttable>
- <t>If a change did take place, but that change does not correspond to one indicated by the currently defined child XML elements, then the CS:changes element MUST be present but empty.</t>
- </section>
- <section title="CS:recurrences XML Element">
- <t>This element indicates which instances were affected by a change:</t>
- <texttable>
- <ttcol>Child Element</ttcol>
- <ttcol>Description</ttcol>
-
- <c>CS:master</c>
- <c>The "master" component defining the recurrence pattern was changed.</c>
-
- <c> </c>
- <c> </c>
-
- <c>CS:recurrenceid</c>
- <c>The instance with the specified "RECURRENCE-ID" value was changed.</c>
- </texttable>
- <t>If no child elements were specified, then all instances were changed.</t>
- </section>
- </section>
- </section>
- </section>
-
- <section title='Security Considerations'>
- <t>TODO:</t>
- </section>
- <section title='IANA Considerations'>
- <t>
- This document does not require any actions on the part of IANA.
- </t>
- </section>
- </middle>
- <back>
- <references title='Normative References'>
- &rfc2119;
- &rfc2445;
- &rfc2446;
- &rfc4791;
- &rfc4918;
- &I-D.desruisseaux-caldav-sched;
- </references>
-<!--
-<references title='Informative References'>
-</references>
--->
- <section title='Acknowledgments'>
- <t>
- This specification is the result of discussions between the Apple calendar server and client teams.
- </t>
- </section>
- <!--
- <section title='Change History'>
- <t>Changes since -00
- <list style='numbers'>
- <t></t>
- </list>
- </t>
- </section>
- -->
- </back>
-</rfc>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20081009/7bb35015/attachment-0001.html
More information about the calendarserver-changes
mailing list