DAV/Methods/POST/REQUEST

From DAViCal Wiki

The CalDAV Scheduling Extensions to WebDAV (draft) 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-08)

7. Request for Busy Time Information

The POST method is used to request busy time information of one or more Calendar Users by targeting the request at a scheduling Outbox collection. The request body of a POST method MUST contain a "VFREEBUSY" calendar component with the "METHOD" iCalendar property set to the value "REQUEST" as specified in Section 3.3.2 of iTIP [I-D.ietf-calsify-2446bis]. The resource identified by the Request- URI MUST be a resource collection of type CALDAV:schedule-outbox (Section 4.1).

7.1. Status Codes

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.
• 204 (No Content) - The command succeeded.
• 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.

7.2. Additional Method Preconditions

This specification defines additional method preconditions for the POST method. Preconditions defined in WebDAV ACL [RFC3744] and CalDAV [RFC4791] that applies to the POST method are also listed here for completeness.

7.2.1. DAV:need-privileges Precondition

Name: need-privileges

Namespace: DAV:

Apply to: POST

Use with: 403 Forbidden

Purpose: (precondition) -- The currently authenticated user MUST be granted the CALDAV:schedule-send or CALDAV:schedule-send-freebusy privilege on the scheduling Outbox collection being targeted by the request.

Definition:

<!ELEMENT DAV:need-privileges (DAV:resource)* >
<!ELEMENT DAV:resource (DAV:href, DAV:privilege) >

Example:

<D:need-privileges xmlns:D="DAV:"
                   xmlns:C="urn:ietf:params:xml:ns:caldav"/>
 <D:resource>
  <D:href>/home/bernard/calendars/outbox/</D:href>
  <D:privilege><C:schedule-send-freebusy/></D:privilege>
 </D:resource>
</D:need-privileges>

7.2.2. CALDAV:supported-collection Precondition

Name: supported-collection

Namespace: urn:ietf:params:xml:ns:caldav

Apply to: POST

Use with: 400 Bad Request

Purpose: (precondition) -- The Request-URI MUST identify the location of a scheduling Outbox collection.

Definition:

<!ELEMENT supported-collection EMPTY >

Example:

<C:supported-collection xmlns:C="urn:ietf:params:xml:ns:caldav"/>

7.2.3. CALDAV:supported-calendar-data Precondition

Name: supported-calendar-data

Namespace: urn:ietf:params:xml:ns:caldav

Apply to: POST

Use with: 400 Bad Request

Purpose: (precondition) -- The resource body submitted in the POST request MUST be a supported media type (e.g., text/calendar).

Definition:

<!ELEMENT supported-calendar-data EMPTY >

Example:

<C:supported-calendar-data xmlns:C="urn:ietf:params:xml:ns:caldav"/>

7.2.4. CALDAV:valid-calendar-data Precondition

Name: valid-calendar-data

Namespace: urn:ietf:params:xml:ns:caldav

Apply to: POST

Use with: 400 Bad Request

Purpose: (precondition) -- The resource submitted in the POST request MUST be valid data for the media type being specified (e.g., a valid iCalendar object).

Definition:

<!ELEMENT valid-calendar-data EMPTY>

Example:

<C:valid-calendar-data xmlns:C="urn:ietf:params:xml:ns:caldav"/>

7.2.5. CALDAV:valid-scheduling-message Precondition

Name: valid-scheduling-message

Namespace: urn:ietf:params:xml:ns:caldav

Apply to: POST

Use with: 400 Bad Request

Purpose: (precondition) -- The resource submitted in the POST request MUST obey all restrictions specified for the POST request (e.g., the scheduling message follow the restrictions of iTIP).

Definition:

<!ELEMENT valid-scheduling-message EMPTY >

Example:

<C:valid-scheduling-message
   xmlns:C="urn:ietf:params:xml:ns:caldav"/>

7.2.6. CALDAV:organizer-allowed Precondition

Name: organizer-allowed

Namespace: urn:ietf:params:xml:ns:caldav

Apply to: POST

Use with: 409 Conflict

Purpose: (precondition) -- 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;

Definition:

<!ELEMENT organizer-allowed EMPTY >

Example:

<C:organizer-allowed xmlns:C="urn:ietf:params:xml:ns:caldav"/>

7.2.7. CALDAV:max-resource-size Precondition

Name: max-resource-size

Namespace: urn:ietf:params:xml:ns:caldav

Apply to: POST

Use with: 403 Forbidden

Purpose: (precondition) -- The resource submitted in the POST request MUST have a size in octets less than or equal to the value of the CALDAV:max-resource-size property (defined in Section 5.2.5 of [RFC4791]) specified on the scheduling Outbox collection targeted by the request.

Definition:

<!ELEMENT max-resource-size EMPTY >

Example:

<C:max-resource-size xmlns:C="urn:ietf:params:xml:ns:caldav"/>

7.3. Response to a POST request

A POST request may deliver a scheduling message to one or more Calendar Users. 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 for that recipient, any error codes and an optional description. See Section 14.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. See Appendix B.5 for an example freebusy request and response.