DAV/Methods/POST/REQUEST

From Davical
< DAV‎ | Methods‎ | POST
Revision as of 09:23, 14 November 2009 by Karora (talk)
Jump to navigationJump to search

The CalDAV Scheduling Extensions to WebDAV (RFC6638) defines two forms of POST request which apply to the schedule-outbox collection of a principal.

REQUEST

The iTIP request method allows clients to request free/busy information related to a principal for a period of time.

The response-status element should contain codes in line with the iTIP REQUEST-STATUS element.

REFRESH

Allows clients to ask for the information they have regarding the status of an event be brought up-to-date with the current canonical information from the event organiser.

Specification (from draft-schedule-05)

The POST method submits a scheduling or freebusy message to one or more recipients by targeting the request at the URI of a scheduling Outbox collection. The request body of a POST method MUST contain a scheduling message or freebusy message (e.g., an iCalendar object that follows the iTIP semantic). The resource identified by the Request-URI MUST be a resource collection of type CALDAV:schedule- outbox (Section 3.1.2).

Only specific types of scheduling message are allowed in a POST request on a scheduling Outbox collection:

          +----------------+---------------------------------+
          | iTIP METHOD    | COMPONENT                       |
          +----------------+---------------------------------+
          | PUBLISH        | None                            |
          | REQUEST        | VFREEBUSY                       |
          | REPLY          | None                            |
          | ADD            | None                            |
          | CANCEL         | None                            |
          | REFRESH        | Any except VTIMEZONE, VFREEBUSY |
          | COUNTER        | None                            |
          | DECLINECOUNTER | None                            |
          +----------------+---------------------------------+

Servers SHOULD reject any scheduling message that is not allowed. However, for backwards compatibility with earlier version of this specification, servers MAY return a valid schedule response result indicating success for the iTIP operation being executed.

  Preconditions:
     (CALDAV:supported-collection): The Request-URI MUST identify the
     location of a scheduling Outbox collection;
     (CALDAV:supported-calendar-data): The resource submitted in the
     POST request MUST be a supported media type (e.g., "text/
     calendar") for scheduling or freebusy messages;
     (CALDAV:valid-calendar-data): The resource submitted in the POST
     request MUST be valid data for the media type being specified
     (e.g., valid iCalendar object);
     (CALDAV:valid-scheduling-message): The resource submitted in the
     POST request MUST obey all restrictions specified for the POST
     request (e.g., the scheduling message follows the restrictions of
     iTIP);
     (CALDAV:originator-allowed): The currently authenticated user MUST
     be granted the CALDAV:schedule-deliver privilege or a suitable
     sub-privilege on the scheduling Outbox collection being targeted
     by the request;
     (CALDAV:organizer-allowed): The calendar user identified by the
     "ORGANIZER" property in the POST request's scheduling message MUST
     be the calendar user (or one of the calendar users) associated
     with the scheduling Outbox collection being targeted by the
     request when the scheduling message is an outgoing scheduling
     message;
     (CALDAV:max-resource-size): The resource submitted in the POST
     request MUST have an octet size less than or equal to the value of
     the CALDAV:max-resource-size property value [RFC4791]on the
     scheduling Outbox collection targeted by the request;
     (CALDAV:attachments-allowed): The resource submitted in the POST
     request MUST NOT contain any inline ATTACH properties;
  Postconditions: None

8.1.1. Handling a REFRESH

  When an iTIP REFRESH scheduling message is executed, the server
  delivers the scheduling message to the calendar user specified by the
  "ORGANIZER" property value in the scheduling object resource that was
  POST'ed.


8.1.2. Response to a POST request

  A POST request may deliver a scheduling message to one or more
  calendar user recipients.  Since the behavior of each recipient may
  vary, it is useful to get response status information for each
  recipient in the overall POST response.  This specification defines a
  new XML response to convey multiple recipient status.
  A response to a POST method that indicates status for one or more
  recipients MUST be a CALDAV:schedule-response XML element.  This MUST
  contain one or more CALDAV:response elements for each recipient, with
  each of those containing elements that indicate which recipient they
  correspond to, the scheduling status of the request for that
  recipient, any error codes and an optional description.  See
  Section 11.1.
  In the case of a freebusy request, the CALDAV:response elements can
  also contain CALDAV:calendar-data elements which contain freebusy
  information (e.g., an iCalendar VFREEBUSY component) indicating the
  busy state of the corresponding recipient, assuming that the freebusy
  request for that recipient succeeded.

8.1.3. Status Codes for use with the POST method

  The following are examples of response codes one would expect to be
  used for this method.  Note, however, that unless explicitly
  prohibited any 2/3/4/5xx series response code may be used in a
  response.
     200 (OK) - The command succeeded.
     201 (Created) - The command succeeded and a new resource was
     created in the scheduling Outbox collection.
     400 (Bad Request) - The client has provided an invalid scheduling
     message.
     403 (Forbidden) - The client cannot submit a scheduling message to
     the specified Request-URI.
     404 (Not Found) - The URL in the Request-URI was not present.
     423 (Locked) - The specified resource is locked and the client
     either is not a lock owner or the lock type requires a lock token
     to be submitted and the client did not submit it.
     507 (Insufficient Storage) - The server did not have sufficient
     space to record the scheduling message in a scheduling Outbox
     collection being targeted by the POST request.

8.1.4. Example - Simple meeting invitation refresh

  >> Request <<
  POST /bernard/calendar/outbox/ HTTP/1.1
  Host: cal.example.com
  Content-Type: text/calendar
  Content-Length: xxxx
  BEGIN:VCALENDAR
  VERSION:2.0
  PRODID:-//Example Corp.//CalDAV Client//EN
  METHOD:REFRESH
  BEGIN:VEVENT
  UID:43777-876@example.com
  DTSTAMP:20040901T200200Z
  ORGANIZER:mailto:lisa@example.com
  ATTENDEE;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;ROLE=RE
   Q-PARTICIPANT;CUTYPE=INDIVIDUAL;CN=Bernard Desr
   uisseaux:mailto:bernard@example.com
  END:VEVENT
  END:VCALENDAR
  >> Response <<
  HTTP/1.1 200 OK
  Date: Thu, 02 Sep 2004 16:53:32 GMT
  Content-Type: application/xml; charset="utf-8"
  Content-Length: xxxx
  <?xml version="1.0" encoding="utf-8" ?>
  <C:schedule-response xmlns:D="DAV:"
               xmlns:C="urn:ietf:params:xml:ns:caldav">
  <C:response>
    <C:recipient>mailto:lisa@example.com</C:recipient>
    <C:request-status>2.0;Success</C:request-status>
    <D:responsedescription>Delivered to recipient
    scheduling inbox</D:responsedescription>
  </C:response>
  </C:schedule-response>
  In this example, the client requests the server to deliver a
  "REFRESH" scheduling message to the "Organizer" of the meeting
  mailto:lisa@example.com.  The response indicates that delivery to the
  relevant scheduling Inbox collection of the "Organizer" was
  accomplished successfully.


8.1.5. Example - Freebusy lookup

  >> Request <<
  POST /lisa/calendar/outbox/ HTTP/1.1
  Host: cal.example.com
  Content-Type: text/calendar
  Content-Length: xxxx
  BEGIN:VCALENDAR
  VERSION:2.0
  PRODID:-//Example Corp.//CalDAV Client//EN
  METHOD:REQUEST
  BEGIN:VFREEBUSY
  DTSTAMP:20040901T200200Z
  ORGANIZER:mailto:lisa@example.com
  DTSTART:20040902T000000Z
  DTEND:20040903T000000Z
  UID:34222-232@example.com
  ATTENDEE;CN=Bernard Desruisseaux:mailto:bernard@
   example.com
  ATTENDEE;CN=Cyrus Daboo:mailto:cyrus@example.com
  END:VFREEBUSY
  END:VCALENDAR
  >> Response <<
  HTTP/1.1 200 OK
  Date: Thu, 02 Sep 2004 16:53:32 GMT
  Content-Type: application/xml; charset="utf-8"
  Content-Length: xxxx
  <?xml version="1.0" encoding="utf-8" ?>
  <C:schedule-response xmlns:D="DAV:"
               xmlns:C="urn:ietf:params:xml:ns:caldav">
  <C:response>
    <C:recipient>mailto:bernard@example.com</C:recipient>
    <C:request-status>2.0;Success</C:request-status>
    <C:calendar-data>BEGIN:VCALENDAR
  VERSION:2.0
  PRODID:-//Example Corp.//CalDAV Server//EN
  METHOD:REPLY
  BEGIN:VFREEBUSY
  DTSTAMP:20040901T200200Z
  ORGANIZER:mailto:lisa@example.com
  DTSTART:20040902T000000Z
  DTEND:20040903T000000Z
  UID:34222-232@example.com
  ATTENDEE;CN=Bernard Desruisseaux:mailto:bernard@
   example.com
  FREEBUSY;FBTYPE=BUSY-UNAVAILABLE:20040902T000000Z/
   20040902T090000Z,20040902T170000Z/20040903T000000Z
  END:VFREEBUSY
  END:VCALENDAR
  </C:calendar-data>
  </C:response>
  <C:response>
    <C:recipient>mailto:cyrus@example.com</C:recipient>
    <C:request-status>2.0;Success</C:request-status>
    <C:calendar-data>BEGIN:VCALENDAR
  VERSION:2.0
  PRODID:-//Example Corp.//CalDAV Server//EN
  METHOD:REPLY
  BEGIN:VFREEBUSY
  DTSTAMP:20040901T200200Z
  ORGANIZER:mailto:lisa@example.com
  DTSTART:20040902T000000Z
  DTEND:20040903T000000Z
  UID:34222-232@example.com
  ATTENDEE;CN=Cyrus Daboo:mailto:cyrus@example.com
  FREEBUSY;FBTYPE=BUSY-UNAVAILABLE:20040902T000000Z/
   20040902T090000Z,20040902T170000Z/20040903T000000Z
  FREEBUSY;FBTYPE=BUSY:20040902T120000Z/20040902T130000Z
  END:VFREEBUSY
  END:VCALENDAR
  </C:calendar-data>
  </C:response>
  </C:schedule-response>
  In this example, the client requests the server to determine the busy
  information of the calendar users mailto:bernard@example.com and
  mailto:cyrus@example.com, over the time range specified by the
  scheduling message sent in the request.  The response includes
  "VFREEBUSY" components for each of those calendar users with their
  busy time indicated.