RFC 4324
Calendar Access Protocol (CAP)
Pages: 131
Experimental
Experimental
Part 4 of 5 – Pages 85 to 120
10. Commands and Responses
CAP commands and responses are described in this section.10.1. CAP Commands (CMD)
All commands are sent using the CMD property. Property Name: CMD Purpose: This property defines the command to be sent. Value Type: TEXT Property Parameters: Non-standard, id, localize, latency, action or options. Conformance: This property is the method used to specify the commands to a CS; it can exist in any object sent to the CS. Description: All of the commands to the CS are supplied in this property. The "OPTIONS" parameter is overloaded and its meaning is dependent on the CMD value supplied. Formal Definition: The property is defined by the following notation: cmd = "CMD" ( abort-cmd / continue-cmd / create-cmd / delete-cmd / generate-uid-cmd / get-capability-cmd / identify-cmd / modify-cmd / move-cmd / reply-cmd / search-cmd / set-locale-cmd / iana-cmd / x-cmd ) CRLF ; option-value = "OPTION" "=" paramtext ; paramtext ; As defined in [iCAL].
Calendaring commands allow a CUA to directly manipulate a calendar. Calendar access rights can be granted or denied for any commands.10.1.1. Bounded Latency
A CAP command can have an associated maximum latency time by specifying the "LATENCY" parameter. If the command is unable to be completed in the specified amount of time (as specified by the "LATENCY" parameter value with an "ACTION" parameter set to the "ASK" value), then a "TIMEOUT" command MUST be sent on the same channel". The reply MUST be a an "ABORT" or a "CONTINUE" command. If the CUA initiated the original command, then the CS would issue the "TIMEOUT" command and the CUA would then have to issue an "ABORT" or "CONTINUE" command. If the CS initiated the original command then the CUA would have to issue the "TIMEOUT" and the CS would send the "ABORT" or "CONTINUE". Upon receiving an "ABORT" command, the command must then be terminated. Only the "ABORT", "TIMEOUT", "REPLY, and "CONTINUE" commands cannot be aborted. The "ABORT", "TIMEOUT", and "REPLY" commands MUST NOT have latency set. Upon receiving a "CONTINUE" command the work continues as if it had not been delayed or stopped. Note that a new latency time MAY be included in a "CONTINUE" command indicating to continue the original command until the "LATENCY" parameter value expires or the results of the original command can be returned. Both the "LATENCY" parameter and the "ACTION" parameter MUST be supplied to any "CMD" property, or nether can be added to the "CMD" property. The "LATENCY" parameter MUST be set to the maximum latency time in seconds. The "ACTION" parameter accepts the following values: "ASK" and "ABORT" parameters. If the maximum latency time is exceeded and the "ACTION" parameter is set to the "ASK" value, then "TIMEOUT" command MUST be sent. Otherwise, if the "ACTION" parameter is set to the "ABORT" value, then the command MUST be terminated and return a REQUEST-STATUS code of 2.0.3 for the original command. If a CS can both start sending the reply to a command and guarantee that all of the results can be sent from a command (short of something like network or power failure) prior to the "LATENCY" timeout value, then the "LATENCY" time has not expired. Example:
In this example the initiator asks for the listeners capabilities.
I: Content-Type: text/calendar
I:
I: BEGIN:VCALENDAR
I: VERSION:2.0
I: PRODID:The CUA's PRODID
I: CMD;ID=xyz12346;LATENCY=3;ACTION=ask:GET-CAPABILITY
I: END:VCALENDAR
# After 3 seconds
L: Content-Type: text/calendar
L:
L: BEGIN:VCALENDAR
L: PRODID:-//someone's prodid
L: VERSION:2.0
L: CMD;ID=xyz12346:TIMEOUT
L: END:VCALENDAR
In order to continue and give the CS more time, the CUA would issue a
"CONTINUE" command:
I: Content-Type: text/calendar
I:
I: BEGIN:VCALENDAR
I: VERSION:2.0
I: PRODID:-//someone's prodid
I: CMD;ID=xyz12346;LATENCY=3;ACTION=ask:CONTINUE
I: END:VCALENDAR
L: Content-Type: text/calendar
L:
L: BEGIN:VCALENDAR
L: VERSION:2.0
L: PRODID:-//someone's prodid
L: CMD;ID=xyz12346:REPLY
L: BEGIN:VREPLY
L: REQUEST-STATUS:2.0.3;Continued for 3 more seconds
L: END:VREPLY
L: END:VCALENDAR
Here the "2.0.3" status is returned because it is not an error, it is
a progress status sent in reply to the "CONTINUE" command.
To abort the command and not wait any further, issue an "ABORT"
command:
I: Content-Type: text/calendar
I:
I: BEGIN:VCALENDAR
I: VERSION:2.0
I: PRODID:-//someone's prodid
I: CMD;ID=xyz12346:ABORT
I: END:VCALENDAR
# Which would result in a 2.0.3 reply.
L: Content-Type: text/calendar
L:
L: BEGIN:VCALENDAR
L: VERSION:2.0
L: PRODID:-//someone's prodid
L: CMD;ID=xyz12346:REPLY
L: BEGIN:VREPLY
L: REQUEST-STATUS:2.0.3;Aborted As Requested.
L: END:VREPLY
L: END:VCALENDAR
If the "ACTION" value had been set to "ABORT", then the listner would
send a "7.0" error on timeout in the reply to the command that
initiated the command that timed out.
10.2. ABORT Command
CMD: ABORT
Purpose: The "ABORT" command is sent to request that the named or the
only in-process command be aborted. Latency MUST not be supplied
with the "ABORT" command.
Formal Definition: An "ABORT" command is defined by the following
notation:
abort-cmd = abortparam ":" "ABORT"
;
abortparam = *(
;
; the following are optional,
; but MUST NOT occur more than once
;
id-param
/ localize-param
;
; the following is optional,
; and MAY occur more than once
;
/ other-params
)
The REPLY of any "ABORT" command is:
abort-reply = "BEGIN" ":" "VCALENDAR" CRLF
calprops
abort-vreply
"END" ":" "VCALENDAR" CRLF
;
abort-vreply = "BEGIN" ":" "VREPLY" CRLF
rstatus
other-props
"END" ":" "VREPLY" CRLF
10.3. CONTINUE Command
CMD: CONTINUE
Purpose: The "CONTINUE" command is only sent after a "TIMEOUT"
command has been received to inform the other end of the session
to resume working on a command.
Formal Definition: A "CONTINUE" command is defined by the following
notation:
continue-cmd = continueparam ":" "CONTINUE"
;
continueparam = *(
;
; the following are optional,
; but MUST NOT occur more than once
;
id-param
/ localize-param
/ latency-param
;
; the following MUST occur exactly once and only
; when the latency-param has been supplied and
; MUST NOT be supplied if the latency-param is
; not supplied.
;
/ action-param
;
; the following are optional,
; and MAY occur more than once
;
/ other-params
)
The REPLY of any "CONTINUE" command is:
continue-reply = "BEGIN" ":" "VCALENDAR" CRLF
calprops
continue-vreply
"END" ":" "VCALENDAR" CRLF
;
continue-vreply = "BEGIN" ":" "VREPLY" CRLF
rstatus
other-props
"END" ":" "VREPLY" CRLF
10.4. CREATE Command
CMD: CREATE
Purpose: The "CREATE" command is used to create one or more
iCalendar objects in the store in the "BOOKED" or "UNPROCESSED"
state.
A CUA MAY send a "CREATE" command to a CS. The "CREATE" command
MUST be implemented by all CSs.
The CS MUST NOT send a "CREATE" command to any CUA.
Formal Definition: A "CREATE" command is defined by the following
notation and the hierarchy restrictions, as defined in Section
3.2:
create-cmd = createparam ":" "CREATE"
;
createparam = *(
;
; the following are optional,
; but MUST NOT occur more than once
;
id-param
/ localize-param
/ latency-param
;
; the following MUST occur exactly once and only
; when the latency-param has been supplied and
; MUST NOT be supplied if the latency-param is
; not supplied.
;
/ action-param
;
; the following is optional,
; and MAY occur more than once
;
/ other-params
)
Response:
One iCalendar object per TARGET property MUST be returned.
The REPLY of any "CREATE" command is limited to the restriction
tables defined in [iTIP] for iTIP objects, in addition to this
ABNF:
create-reply = "BEGIN" ":" "VCALENDAR" CRLF
creply-props
1*(create-vreply)
"END" ":" "VCALENDAR" CRLF
;
create-vreply = "BEGIN" ":" "VREPLY" CRLF
created-id
rstatus
other-props
"END" ":" "VREPLY" CRLF
;
; Where the id is appropriate for the
; type of object created:
;
; VAGENDA = relcalid
; VALARM = sequence
; VCAR = carid
; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid
; VQUERY = queryid
; VTIMEZONE = tzid
; x-comp = x-id
;
created-id = ( relcalid / carid / uid / queryid /
tzid / sequence / x-id)
;
tzid = ; As defined in [iCAL].
;
sequence = ; As defined in [iCAL].
;
uid = ; As defined in [iCAL].
;
x-id = ; An ID for an x-component.
;
creply-props = 4*(
; These are REQUIRED and MUST NOT occur
; more than once.
;
prodid /version / target / reply-cmd
;
; These are optional, and may occur more
; than once.
;
other-props )
For a "CREATE" command, the "TARGET" property specifies the
containers where the components will be created.
If the iCalendar object being created does not have a "METHOD"
property, then its state is "BOOKED" and it is not an [iTIP]
scheduling object. Use the "DELETE" command to set the state of
an object to the "DELETED" state (tagged for deletion). A CUA
cannot use the "CREATE" command to create an object in the
"DELETED" state.
If the intention is to book an [iTIP] object, then the "METHOD"
property MUST NOT be supplied. Otherwise, any [iTIP] object MUST
have a valid [iTIP] "METHOD" property value and it is a scheduling
request being deposited into the CS with its state set to
"UNPROCESSED".
Format Definition: ABNF for a "CREATE" object is:
create-object = "BEGIN" ":" "VCALENDAR" CRLF
; If 'calprops' contain the "METHOD" property
; then this 'create-object' component MUST
; conform to [iTIP] restrictions.
;
; calprops MUST include 'create-cmd'
;
calprops
other-props
1*(create-comp)
"END" ":" "VCALENDAR" CRLF
; NOTE: The 'VCALSTORE' component is not included in
; 'create-comp' as it is out of scope for CAP to create
; a new CS.
;
create-comp = agendac / carc / queryc
/ timezonec / freebusyc
/ eventc / todoc / journalc
/ iana-comp / x-comp
;
freebusyc = ; As defined in [iCAL].
;
eventc = ; As defined in [iCAL].
;
journalc = ; As defined in [iCAL].
;
timezonec = ; As defined in [iCAL].
;
todoc = ; As defined in [iCAL].
In the following example, two new top level "VAGENDA" components are
created. Note that the "CSID" value of the server is
cal.example.com, which is where the new "VAGENDA" components are
going to be created.
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: PRODID:-//someone's prodid
C: VERSION:2.0
C: CMD;ID=creation01:CREATE
C: TARGET:cal.example.com
C: BEGIN:VAGENDA <- data for 1st new calendar
C: CALID:relcalz1
C: NAME;LANGUAGE=en_US:Bill's Soccer Team
C: OWNER:bill
C: CALMASTER:mailto:bill@example.com
C: TZID:US/Pacific
C: END:VAGENDA
C: BEGIN:VAGENDA <- data for 2nd new calendar
C: CALID:relcalz2
C: NAME;LANGUAGE=EN-us:Mary's personal calendar
C: OWNER:mary
C: CALMASTER:mailto:mary@example.com
C: TZID:US/Pacific
C: END:VAGENDA
C: END:VCALENDAR
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: PRODID:-//someone's prodid
S: CMD;ID=creation01:REPLY
S: TARGET:cal.example.com
S: BEGIN:VREPLY <- Reply for 1st calendar create
S: CALID:relcalz1
S: REQUEST-STATUS:2.0
S: END:REPLY
S: BEGIN:VREPLY <- Reply for 2nd calendar create
S: CALID:relcalz2
S: REQUEST-STATUS:2.0
S: END:VREPLY
S: END:VCALENDAR
To create a new component in multiple containers, simply name all
of the containers in the "TARGET" in the create command. A new
"VEVENT" component is created in two TARGET components. In this
example, the "VEVENT" component is one new [iTIP] "REQUEST" to be
stored in two calendars. The results would be iCalendar objects
that conform to the [iTIP] replies as defined in [iTIP].
This example shows two [iTIP] "VEVENT" components being created in
each of the two supplied "TARGET" properties. As it contains the
"METHOD" property, they will be stored in the "UNPROCESSED" state:
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: PRODID:-//someone's prodid
C: CMD;ID=creation02:CREATE
C: METHOD:REQUEST
C: TARGET:relcalz1
C: TARGET:relcalz2
C: BEGIN:VEVENT
C: DTSTART:20030307T180000Z
C: UID:FirstInThisExample-1
C: DTEND:20030307T190000Z
C: SUMMARY:Important Meeting
C: END:VEVENT
C: BEGIN:VEVENT
C: DTSTART:20040307T180000Z
C: UID:SecondInThisExample-2
C: DTEND:20040307T190000Z
C: SUMMARY:Important Meeting
C: END:VEVENT
C: END:VCALENDAR
The CS sends the "VREPLY" commands in separate MIME objects, one
per supplied "TARGET" property value.
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: PRODID:-//someone's prodid
S: CMD;ID=creation02:REPLY
S: TARGET:relcalz1 <- 1st TARGET listed.
S: BEGIN:REPLY <- Reply for 1st VEVENT create in 1st TARGET.
S: UID:FirstInThisExample-1
S: REQUEST-STATUS:2.0
S: END:VREPLY
S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 1st TARGET.
S: UID:SecondInThisExample-2
S: REQUEST-STATUS:2.0
S: END:VREPLY
S: END:VCALENDAR
And the second reply for the 2nd TARGET:
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: PRODID:-//someone's prodid
S: CMD;ID=creation02:REPLY
S: TARGET:relcalz2 <- 2nd TARGET listed
S: BEGIN:REPLY <- Reply for 1st VEVENT create in 2nd TARGET.
S: UID:FirstInThisExample-1
S: REQUEST-STATUS:2.0
S: END:VREPLY
S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 2nd TARGET.
S: UID:SecondInThisExample-2
S: REQUEST-STATUS:2.0
S: END:VREPLY
S: END:VCALENDAR
10.5. DELETE Command
CMD: DELETE
Purpose: The "DELETE" command physically removes the QUERY result
from the store or marks it for deletion.
A CUA MAY send a "DELETE" command to a CS. The "DELETE" command
MUST be implemented by all CSs.
The CS MUST NOT send a "DELETE" command to any CUA.
Formal Definition: A "DELETE" command is defined by the following
notation:
delete-cmd = deleteparam ":" "DELETE"
;
deleteparam = *(
;
; the following are optional,
; but MUST NOT occur more than once
;
id-param
/ localize-param
/ latency-param
/ option-param "MARK"
;
; The following MUST occur exactly once and
; only when the latency-param has been supplied.
; It MUST NOT be supplied if the latency-param
; is not supplied.
;
/ action-param
;
; the following is optional,
; and MAY occur more than once
;
/ other-params
)
The "DELETE" command is used to delete calendars or components.
The included "VQUERY" component(s) specifies the container(s) to
delete.
To mark a component for delete without physically removing it,
include the "OPTIONS" parameter with its value set to the "MARK"
value in order to alter its state to "DELETED".
When components are deleted, only the top-most component
"REQUEST-STATUS" properties are returned. No "REQUEST-STATUS"
properties are returned for components inside of the selected
components. There MUST be one "VREPLY" component returned for
each object that is deleted or marked for delete. Note that if no
"VREPLY" components are returned, then nothing matched and nothing
was deleted.
Restriction Table for the "REPLY" command for any "DELETE"
command.
delete-reply = "BEGIN" ":" "VCALENDAR" CRLF
calprops ; MUST include 'reply-cmd'
*(delete-vreply)
"END" ":" "VCALENDAR" CRLF
;
delete-vreply = "BEGIN" ":" "VREPLY" CRLF
deleted-id
rstatus
"END" ":" "VREPLY" CRLF
;
; Where the id is appropriate for the
; type of object deleted:
;
; VAGENDA = relcalid
; VCAR = carid
; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid
; VQUERY = queryid
; ALARM = sequence
; VTIMEZONE = tzid
; x-comp = x-id
; An instance = uid recurid
;
deleted-id = ( relcalid / carid / uid / uid recurid
/ queryid / tzid / sequence / x-id )
Example: to delete a "VEVENT" component with "UID" value of
"abcd12345" from the calendar "relcalid-22" from the current CS:
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: TARGET:relcalid-22
C: CMD;ID:"random but unique per CUA":DELETE
C: BEGIN:VQUERY
C: QUERY:SELECT VEVENT FROM VAGENDA WHERE UID = 'abcd12345'
C: END:VQUERY
C: END:VCALENDAR
S: BEGIN:VCALENDAR
S: TARGET:relcalid-22
S: CMD;ID:"random but unique per CUA":REPLY
S: BEGIN:VREPLY
S: UID:abcd12345
S: REQUEST-STATUS:3.0
S: END:VREPLY
S: END:VCALENDAR
One or more iCalendar objects will be returned that contain
"REQUEST-STATUS" properties for the deleted components. More than
one component could have been deleted. Any booked component and
any number of unprocessed [iTIP] scheduling components that
matched the QUERY value in the above example will be returned.
Each unique "METHOD" property value that was deleted from the
store MUST be in a separate iCalendar object. This is because
only one "METHOD" property is allowed in a single "VCALENDAR"
BEGIN/END block.
10.6. GENERATE-UID Command
CMD: GENERATE-UID
Purpose: The "GENERATE-UID" command returns one or more unique
identifiers that MUST be globally unique.
The "GENERATE-UID" command MAY be sent to any CS. The "GENERATE-
UID" command MUST be implemented by all CSs.
The "GENERATE-UID" command MUST NOT be sent to a CUA.
Formal Definition: A "GENERATE-UID" command is defined by the
following notation:
generate-uid-cmd = genuidparam ":" "GENERATE-UID"
;
genuidparam = *(
;
; The following are optional,
; but MUST NOT occur more than once.
;
id-param
/ localize-param
/ latency-param
;
; The following MUST occur exactly once and
; only when the latency-param has been supplied.
; It MUST NOT be supplied if the latency-param
; is not supplied.
;
/ action-param
;
; The following is optional,
; and MAY occur more than once.
;
/ other-params
;
; The following MUST be supplied exactly once.
; The value specifies the number of UIDs to
; be returned.
;
/ option-param posint1
)
Response:
gen-reply = "BEGIN" ":" "VCALENDAR" CRLF
calprops ; Which MUST include 'reply-cmd'
1*(gen-vreply)
"END" ":" "VCALENDAR" CRLF
gen-vreply = "BEGIN" ":" "VREPLY" CRLF
1*(uid)
rstatus
"END" ":" "VREPLY" CRLF
{%%%IS THIS RIGHT%%%?]
Example:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: PRODID:-//someone's prodid
C: CMD;ID=unique-per-cua-124;OPTIONS=5:GENERATE-UID
C: END:VCALENDAR
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: PRODID:-//someone's prodid
S: CMD;ID=unique-per-cua-124:REPLY
S: BEGIN:VREPLY
S: UID:20011121T120000Z-12340@cal.example.com
S: UID:20011121T120000Z-12341@cal.example.com
S: UID:20011121T120000Z-12342@cal.example.com
S: UID:20011121T120000Z-12343@cal.example.com
S: UID:20011121T120000Z-12344@cal.example.com
S: REQUEST-STATUS:2.0
S: END:VREPLY
S: END:VCALENDAR
10.7. GET-CAPABILITY Command
CMD: GET-CAPABILITY
Purpose: The "GET-CAPABILITY" command returns the capabilities of the
other end point of the session.
A CUA MUST send a "GET-CAPABILITY" command to a CS after the
initial connection. A CS MUST send a "GET-CAPABILITY" command to
a CUA after the initial connection. The "GET-CAPABILITY" command
and reply MUST be implemented by all CSs and CUAs.
Formal Definition: A "GET-CAPABILITY" command is defined by the
following notation:
get-capability-cmd = capabilityparam ":" "GET-CAPABILITY"
capabilityparam = *(
; the following are optional,
; but MUST NOT occur more than once
;
id-param / localize-param / latency-param
;
; the following MUST occur exactly once and only
; when the latency-param has been supplied and
; MUST NOT be supplied if the latency-param is
; not supplied.
;
/ action-param
;
; the following is optional,
; and MAY occur more than once
;
/ other-params
)
Response:
The "GET-CAPABILITY" command returns information about the
implementation at the other end of the session. The values
returned may differ depending on current user identify and the
security level of the connection.
Client implementations SHOULD NOT require any capability element
beyond those defined in this specification or future RFC
publications. They MAY ignore any nonstandard, experimental
capability elements. The "GET-CAPABILITY" reply may return
different results, depending on the UPN and if the UPN is
authenticated.
When sending a reply to a "GET-CAPABILITY" command, all of these
MUST be supplied. The following properties are returned in
response to a "GET-CAPABILITY" command:
cap-vreply = "BEGIN" ":" "VCALENDAR" CRLF
; The following properties may be in any order.
;
rodid
version
reply-cmd
other-props
"BEGIN" ":" "VREPLY" CRLF
; The following properties may be in any order.
;
cap-version
car-level
components
stores-expanded
maxdate
mindate
itip-version
max-comp-size
multipart
query-level
recur-accepted
recur-expand
recur-limit
other-props
"END" ":" "VREPLY" CRLF
"END" ":" "VCALENDAR" CRLF
Example:
I: Content-Type: text/calendar
I:
I: BEGIN:VCALENDAR
I: VERSION:2.0
I: PRODID:-//someone's prodid
I: CMD;ID=unique-per-cua-125:GET-CAPABILITY
I: END:VCALENDAR
L: Content-Type: text/calendar
L:
L: BEGIN:VCALENDAR
L: VERSION:2.0
L: PRODID:-//someone's prodid
L: CMD;ID=unique-per-cua-125:REPLY
L: BEGIN:VREPLY
L: CAP-VERSION:1.0
L: PRODID:The CS prodid
L: QUERY-LEVEL:CAL-QL-1
L: CAR-LEVEL:CAR-FULL-1
L: MAXDATE:99991231T235959Z
L: MINDATE:00000101T000000Z
L: MAX-COMPONENT-SIZE:0
L: COMPONENTS:VCALENDAR,VTODO,VJOURNAL,VEVENT,VCAR,
L: VALARM,VFREEBUSY,VTIMEZONE,STANDARD,DAYLIGHT,VREPLY
L: ITIP-VERSION:2446
L: RECUR-ACCEPTED:TRUE
L: RECUR-EXPAND:TRUE
L: RECUR-LIMIT:0
L: STORES-EXPANDED:FALSE
L: X-INET-PRIVATE-COMMANDS:1.0
L: END:VREPLY
L: END:VCALENDAR
10.8. IDENTIFY Command
CMD: IDENTIFY
Purpose: The "IDENTIFY" command allows the CUA to set a new identity
to be used for calendar access.
A CUA MAY send an "IDENTIFY" command to a CS. The "IDENTIFY"
command MUST be implemented by all CSs. A CS implementation MAY
reject all "IDENTIFY" commands.
The CS MUST NOT send an "IDENTIFY" command to any CUA.
Formal Definition: An "IDENTIFY" command is defined by the following
notation:
identify-cmd = identifyparam ":" "IDENTIFY"
;
identifyparam = *(
;
; the following are optional,
; but MUST NOT occur more than once
;
id-param
/ localize-param
/ latency-param
;
; the following MUST occur exactly once and only
; when the latency-param has been supplied and
; MUST NOT be supplied if the latency-param is
; not supplied.
;
/ action-param
;
; the following is optional,
; and MAY occur more than once
;
/ other-params
;
; The value is the UPN of the requested
; identity. If option is not supplied it is
; a request to return to the original
; authenticated identity.
;
/ option-param upn
)
Response:
A "REQUEST-STATUS" property wrapped in a "VREPLY" component with
only one of the following request-status codes:
2.0 Successful.
6.4 Identity not permitted. VCAR restriction.
The CS determines, through an internal mechanism, if the credentials
supplied at authentication permit the operation as the selected
identity. If they do, the session assumes the new identity;
otherwise, a security error is returned.
Example:
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: PRODID:-//someone's prodid
C: CMD;ID=unique-per-cua-999;OPTIONS=newUserId:IDENTIFY
C: END:VCALENDAR
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: PRODID:-//someone's prodid
S: BEGIN:VREPLY
S: REQUEST-STATUS:2.0;Request Approved
S: END:VREPLY
S: END:VCALENDAR
Or if denied:
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: PRODID:-//someone's prodid
S: VERSION:2.0
S: BEGIN:VREPLY
S: REQUEST-STATUS:6.4;Request Denied
S: END:VREPLY
S: END:VCALENDAR
For the CUA to return to its original authenticated identity, the
OPTIONS parameter is omitted:
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: PRODID:-//someone's prodid
C: CMD;ID=unique-per-cua-995:IDENTIFY
C: END:VCALENDAR
The CS may accept (2.0) or deny (6.4) the request to return to the
original identity.
If a CS considers the "IDENTIFY" command an attempt to violate
security, the CS MAY terminate the [BEEP] session without any further
notice to the CUA after sending the "REQUEST-STATUS" 6.4 reply.
10.9. MODIFY Command
CMD: MODIFY
Purpose: The "MODIFY" command is used to modify existing components.
A CUA MAY send a "MODIFY" command to a CS. The "MODIFY" command
MUST be implemented by all CSs.
The CS MUST NOT send a "MODIFY" command to any CUA.
Formal Definition: A "MODIFY" command is defined by the following
notation:
modify-cmd = modifyparam ":" "MODIFY"
;
modifyparam = *(
;
; the following are optional,
; but MUST NOT occur more than once
;
id-param
/ localize-param
/ latency-param
;
; the following MUST occur exactly once and only
; when the latency-param has been supplied and
; MUST NOT be supplied if the latency-param is
; not supplied.
;
/ action-param
;
; the following is optional,
; and MAY occur more than once
;
/ other-params
)
The "MODIFY" command is used to modify existing components. The
TARGET property specifies the calendars that contain the
components that are going to be modified.
The format of the request is three components inside of
"VCALENDAR" component:
BEGIN:VCALENDAR
BEGIN:VQUERY
END:VQUERY
BEGIN:XXX
END:XXX
BEGIN:XXX
END:XXX
END:VCALENDAR
The "VQUERY" component selects the components that are to be
modified.
The "XXX" above is a named component type (VEVENT, VTODO, ...).
Both the old and new components MUST be of the same type.
The old-values is a component and the contents of that component
are going to change and may contain information that helps
uniquely identify the original component (SEQUENCE in the example
below). If the CS cannot find a component that matches the QUERY
and does not have at least all of the OLD-VALUES, then a 6.1 error
is returned.
The new-values is a component of the same type as old-values and
new-values contains the new data for each selected component. Any
data that is in old-values and not in new-values is deleted from
the selected component. Any values in new-values that was not in
old-values is added to the component.
In this example, the "VEVENT" component with a "UID" property
value of 'unique-58' has the "LOCATION" property and "LAST-
MODIFIED" properties changed, the "VALARM" component with the
"SEQUENCE" property with a value of "3" has its "TRIGGER" property
disabled, the "X-LOCAL" property is removed from the "VEVENT"
component, and a "COMMENT" property is added.
Because "SEQUENCE" property is used to locate the "VALARM"
component in this example, both the old-values and the new-values
contain the "SEQUENCE" property with a value of "3". If the
"SEQUENCE" property were to be left out of new-values, it would
have been deleted.
Example:
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: PRODID:-//someone's prodid
C: TARGET:my-cal
C: CMD:ID=unique-mod:MODIFY
C: BEGIN:VQUERY <- Query to select data set.
C: QUERY:SELECT * FROM VEVENT WHERE UID = 'unique-58'
C: END:VQUERY
C: BEGIN:VEVENT <- Start of old data.
C: LOCATION:building 3
C: LAST-MODIFIED:20020101T123456Z
C: X-LOCAL:some private stuff
C: BEGIN:VALARM
C: SEQUENCE:3
C: TRIGGER;RELATED=END:PT5M
C: END:VALARM
C: END:VEVENT <- End of old data.
C: BEGIN:VEVENT <- Start of new data.
C: LOCATION:building 4
C: LAST-MODIFIED:20020202T010203Z
C: COMMENT:Ignore global trigger.
C: BEGIN:VALARM
C: SEQUENCE:3
C: TRIGGER;ENABLE=FALSE:RELATED=END:PT5M
C: END:VALARM
C: END:VEVENT <- End of new data.
C: END:VCALENDAR
The "X-LOCAL" property was not supplied in the new-values, so it
was deleted. The "LOCATION" property value was altered, as was
the "LAST-MODIFIED" value. The "VALARM" component with a
"SEQUENCE" property value of "3" had its "TRIGGER" property
disabled, and the "SEQUENCE" property value did not change so it
was not effected. The "COMMENT" property was added.
When it comes to inline ATTACHMENTs, the CUA only needs to
uniquely identify the contents of the ATTACHMENT value in the
old-values in order to delete them. When the CS compares the
attachment data, it is compared in its binary form. The
ATTACHMENT value supplied by the CUA MUST be valid encoded
information.
For example, to delete the same huge inline attachment from every
VEVENT in 'my-cal' that has an "ATTACH" property value with the
old-values:
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//someone's prodid
TARGET:my-cal
CMD:MODIFY
BEGIN:VQUERY
QUERY:SELECT ATTACH FROM VEVENT
END:VQUERY
BEGIN:VEVENT
ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY:
MIICajCCAdOgAwIBAgICbeUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U
EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE
...< remainder of attachment data NOT supplied >....
END:VEVENT
BEGIN:VEVENT
END:VEVENT
END:VCALENDAR
Here the new-values is empty, so everything in the old-values is
deleted.
Furthermore, the following additional restrictions apply:
1. One cannot change the "UID" property of a component.
2. If a contained component is changed inside of a selected
component, and that contained component has multiple instances,
then old-values MUST contain information that uniquely
identifies the instance or instances that are changing. It is
valid to change more than one. All contained components that
match old-values will be modified. In the first modify example
above, if "SEQUENCE" properties were to be deleted from both the
old-values and new-values, then all "TRIGGER" properties that
matched the old-values in all "VALARM" components in the
selected "VEVENT" components would be disabled.
3. The result of the modify MUST be a valid iCalendar object.
Response:
A "VCALENDAR" component is returned with one ore more "REQUEST-
STATUS" property values.
If any error occurred:
No component will be changed at all. That is, it will appear just
as it was prior to the modify and the CAP server SHOULD return a
"REQUEST-STATUS" property for each error that occurred. There
MUST be at least one error reported.
If multiple components are selected, then what uniquely identified
the component MUST be returned (UID, QUERYID, ...) if the component
contains a unique identifier. If it does not, sufficient information
to uniquely identify the modified components MUST be returned in the
reply.
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: TARGET:relcalid
S: CMD;ID=delete#1:REPLY
S: BEGIN:VREPLY
S: BEGIN:VEVENT
S: UID:123
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: END:VREPLY
S: END:VCALENDAR
10.10. MOVE Command
CMD: MOVE Purpose: The "MOVE" command is used to move components within the CS. A CUA MAY send a "MOVE" command to a CS. The "MOVE" command MUST be implemented by all CSs. The CS MUST NOT send a "MOVE" command to any CUA. Formal Definition: A "MOVE" command is defined by the following notation: move-cmd = moveparam ":" "MOVE" ; moveparam = *( ; ; the following are optional, ; but MUST NOT occur more than once ; id-param / localize-param / latency-param ; ; the following MUST occur exactly once and only ; when the latency-param has been supplied and ; MUST NOT be supplied if the latency-param is ; not supplied. ; / action-param ; ; the following is optional, ; and MAY occur more than once ; / other-params ; ) Response: The REQUEST-STATUS in a VCALENDAR object. The content of each "result" is subject to the result restriction table defined below. The access control on the "VAGENDA" component, after it has been moved to its new location in the calstore, MUST be at least as
secure as it was prior to the move. If the CS is not able to
ensure the same level of security, a permission-denied "REQUEST-
STATUS" property value MUST be returned, and the "MOVE" command
MUST NOT be performed.
The "TARGET" property value specifies the new location, and the
"VQUERY" component specifies the old location.
Restriction Table for the "REPLY" command of any "MOVE" command.
move-reply = "BEGIN" ":" "VCALENDAR" CRLF
calprops
1*(move-vreply)
"END" ":" "VCALENDAR" CRLF
move-vreply = "BEGIN" ":" "VREPLY" CRLF
move-id
rstatus
"END" ":" "VREPLY" CRLF
; Where the id is appropriate for the
; type of object moved:
;
; VAGENDA = relcalid
; VCAR = carid
; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid
; VQUERY = queryid
; ALARM = sequence
; An instance = uid recurid
; x-comp = x-id
;
move-id = ( relcalid / carid / uid / uid recurid
/ queryid / tzid / sequence / x-id)
Example: moving the VAGENDA Nellis to Area-51
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: PRODID:-//someone's prodid
C: CMD:MOVE
C: TARGET:Area-51
C: BEGIN:VQUERY
C: QUERY: SELECT *.* FROM VAGENDA WHERE CALID='Nellis'
C: END:VQUERY
C: END:VCALENDAR
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: PRODID:-//someone's prodid
S: TARGET:Area-51
S: BEGIN:VREPLY
S: CALID:Nellis
S: REQUEST-STATUS: 2.0
S: END:VREPLY
S: END:VCALENDAR
10.11. REPLY Response to a Command
CMD: REPLY
Purpose: The "REPLY" value to the "CMD" property is used to return
the results of all other commands to the CUA.
A CUA MUST send a "REPLY" command to a CS for any command a CS MAY
send to the CUA. The "REPLY" command MUST be implemented by all
CUAs that support getting the "GET-CAPABILITY" command.
A CS MUST send a "REPLY" command to a CUA for any command a CUA
MAY send to the CS. The "REPLY" command MUST be implemented by
all CSs.
Formal Definition: A "REPLY" command is defined by the following
notation:
reply-cmd = replyparam ":" "REPLY"
;
replyparam = *(
;
; The 'id' parameter value MUST be exactly the
; same as the value sent in the original
; CMD property. If the original CMD did
; not have an 'id' parameter, then the 'id'
; MUST NOT be supplied in the REPLY.
;
id-param
;
; the following is optional,
; and MAY occur more than once
;
/ other-params
)
10.12. SEARCH Command
CMD: SEARCH Purpose: The "SEARCH" command is used to return selected components to the CUA. A CUA MAY send a "SEARCH" command to a CS. The "SEARCH" command MUST be implemented by all CSs. The CS MUST NOT send a "SEARCH" command to any CUA. Formal Definition: A "SEARCH" command is defined by the following notation: search-cmd = searchparam ":" "SEARCH" ; searchparam = *( ; ; the following are optional, ; but MUST NOT occur more than once ; id-param / localize-param / latency-param ; ; the following MUST occur exactly once and only ; when the latency-param has been supplied and ; MUST NOT be supplied if the latency-param is ; not supplied. ; / action-param ; ; the following is optional, ; and MAY occur more than once ; / other-params ) The format of the request is the search command (search-cmd) followed by one or more (query) "VQUERY" components Response: The data in each result set contains one or more iCalendar components composed of all the selected results enclosed in a single "VREPLY" component per "QUERY".
Only "REQUEST-STATUS" property and the properties mentioned in the
"SELECT" clause of the QUERY are included in the components. Each
"VCALENDAR" component is tagged with the "TARGET" property.
Searching for objects
In the example below, objects on March 10,1999 between 080000Z and
190000Z are read. In this case only four properties for each
object are returned. Two calendars are specified. Only booked
(vs. scheduled) entries are to be returned (this example only
selected VEVENT objects are to be returned):
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: PRODID:-//someone's prodid
C: CMD:SEARCH
C: TARGET:relcal2
C: TARGET:relcal3
C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID
C: FROM VEVENT
C: WHERE DTEND >= '19990310T080000Z'
C: AND DTSTART <= '19990310T190000Z'
C: AND STATE() = 'BOOKED'
C: END:VQUERY
C: END:VCALENDAR
The return values are subject to VCAR filtering. That is, if the
request contains properties to which the UPN does not have access,
those properties will not appear in the return values. If the UPN
has access to at least one property of the component, but has been
denied access to all properties called out in the request, the
response will contain a single "REQUEST-STATUS" property
indicating the error.
Here the request was successful, however one of the "VEVENT"
components contents were not accessible (4.1).
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: TARGET:relcalid
S: CMD:REPLY
S: VERSION:2.0
S: PRODID:-//someone's prodid
S: BEGIN:VREPLY
S: BEGIN:VEVENT
S: REQUEST-STATUS:4.1
S: END:VEVENT
S: BEGIN:VEVENT
S: REQUEST-STATUS:2.0
S: UID:123
S: DTEND:19990310T080000Z
S: DSTART:19990310T190000Z
S: SUMMARY: Big meeting
S: END:VEVENT
S: END:VREPLY
S: END:VCALENDAR
If the UPN has no access to any components at all, the response
will simply be an empty data set. The response will look the same
if the particular components do not exist.
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: PRODID:-//someone's prodid
S: CMD:REPLY
S: TARGET:ralcalid
S: BEGIN:VREPLY
S: REQUEST-STATUS:2.0
S: END:VREPLY
S: END:VCALENDAR
If there are multiple targets, each iCalendar reply is contained
within its own iCalendar object.
10.12.1. Searching for VFREEBUSY
If a CS sets the "RECUR-EXPAND" property to "TRUE" and contains the
"VFREEBUSY" component in the "COMPONENTS" value in a reply to the
"GET-CAPABILITY" command, then it is the CS's responsibility (and not
the CUA's responsibility) to provide the correct "VFREEBUSY"
information for a calendar.
If a CUA issues a "CREATE" "VFREEBUSY", such a CS MUST return success and not store the "VFREEBUSY" component as the results would never be used. Such a CS MUST dynamically create the results of a search for "VFREEBUSY" components at search time when searching for STATE() = 'BOOKED' items. If a CUA searches for "VFREEBUSY" components with STATE() = 'UNPROCESSED', such a CS MUST return a "VREPLY" with no components. If a CUA searches for "VFREEBUSY" components without specifying the STATE, such a CS MUST return the same result as if STATE()='BOOKED' had been specified. For CSs that set the "CAPABILITY" "RECUR-EXPAND" property to "FALSE" and have the "VFREEBUSY" component in the "COMPONENTS" value in the "CAPABILITY" reply, a CUA MAY store the "VFREEBUSY" information on the CS. These CSs then MUST return a "VFREEBUSY" component calculated from the stored components. If no "VFREEBUSY" information is available for the "TARGET" calendar, then a "VFREEBUSY" with no blocked out time will be returned with a success code. A CUA sets the "VFREEBUSY" time on a/those calendars by creating a "VFREEBUSY" component without a "METHOD" creating a "BOOKED" entry. If a CS does not set the "VFREEBUSY" value in the "COMPONENTS" "CAPABILITY" value, the CS does not support the "VFREEBUSY" component and all creation and searching for a "VFREEBUSY" component MUST fail. Examples of calendars that may be in this category are public event calendars that will never require scheduling with other UPNs.10.13. SET-LOCALE Command
CMD: SET-LOCALE Purpose: The "SET-LOCALE" command is used to select the locale that will be used in error codes that are used in the "REQUEST-STATUS" property. A CUA MAY send a "SET-LOCALE" command to a CS. The SET-LOCALE command MUST be implemented by all CSs. The CS MUST NOT send a "SET-LOCALE" command to any CUA. Formal Definition: A "SET-LOCALE" command is defined by the following notation: setlocale-cmd = setlocaleparam ":" "SET-LOCALE"
;
setlocaleparam = *(
;
; the following are optional,
; but MUST NOT occur more than once
;
id-param
/ localize-param
/ latency-param
/ setlocale-option
;
; the following MUST occur exactly once and only
; only when the latency-param has been supplied.
; It MUST NOT be supplied if the latency-param
; is not supplied.
;
/ action-param
;
; the following is optional,
; and MAY occur more than once
;
/ other-params )
setlocale-option = option-param newlocale
;
newlocale = ; Any locale supplied in the initial [BEEP]
; "greeting" "localize" parameter and
; and any charset supported by the CS
; and listed in the DEFAULT-CHARSET property
; of the VCALSTORE
Examples:
CMD:OPTIONS=en_US.UTF-8:SET-LOCALE
CMD:OPTIONS=th_TH.ISO8859-11:SET-LOCALE
CMD:OPTIONS=es_MX.ISO8859-1:SET-LOCALE
Restriction Table for the "REPLY" command of any "SET-LOCALE"
command.
setlocale-reply = "BEGIN" ":" "VCALENDAR" CRLF
calprops
1*(setlocale-vreply)
"END" ":" "VCALENDAR" CRLF
setlocale-vreply = "BEGIN" ":" "VREPLY" CRLF
rstatus
"END" ":" "VREPLY" CRLF
10.14. TIMEOUT Command
CMD: TIMEOUT Purpose: The "TIMEOUT" command is only sent after a command has been sent with a latency value set. When received, it means the command could not be completed in the time allowed. Formal Definition: A "TIMEOUT" command is defined by the following notation: timeout-cmd = timeoutparam ":" "TIMEOUT" timeoutparam = *( ; the following are optional, ; but MUST NOT occur more than once id-param / localize-param / other-params )10.15. Response Codes
Numeric response codes are returned using the "REQUEST-STATUS" property. The format of these codes is described in [iCAL] and extended in [iTIP] and [iMIP]. The following describes new codes added to this set and how existing codes apply to CAP. At the application layer, response codes are returned as the value of a "REQUEST-STATUS" property. The value type of this property is modified from that defined in [iCAL], in order to make the accompanying "REQUEST-STATUS" property text optional. Code Description -------------------------------------------------------------- 2.0 Success. The parameters vary with the operation and are specified. 2.0.3 In response to the client issuing an "abort" reply, this reply code indicates that any command currently underway was successfully aborted. 3.1.4 Capability not supported. 4.1 Calendar store access denied.
6.1 Container not found.
6.2 Attempt to create or modify an object
that would overlap another object
in either of the following two circumstances:
(a) One of the objects has a TRANSP
property set to OPAQUE-NOCONFLICT or
TRANSPARENT-NOCONFLICT.
(b) The calendar's ALLOW-CONFLICT
property is set to FALSE.
6.3 Bad args.
6.4 Permission denied - VCAR restriction.
A VCAR exists and the CS will not perform
the operation.
7.0 A timeout has occurred. The server was
unable to complete the operation in the
requested time.
8.0 A failure has occurred in the CS
that prevents the operation from
succeeding.
8.1 A query was performed and the query is
too complex for the CS. The operation
was not performed.
8.2 Used to signal that an iCalendar object has
exceeded the server's size limit
8.3 A DATETIME value was too far in the future
to be represented on this Calendar.
8.4 A DATETIME value was too far in the past
to be represented on this Calendar.
8.5 An attempt was made to create a new
object, but the unique UID specified is
already in use.
9.0 An unrecognized command was received.
Or an unsupported command was received.
10.4 The operation has not been performed
because it would cause the resources
(memory, disk, CPU, etc) to exceed the
allocated quota.
--------------------------------------------------------------
(page 120 continued on part 5)