RFC 4324
Calendar Access Protocol (CAP)
Pages: 131
Experimental
Experimental
Part 3 of 5 – Pages 52 to 84
8. New Properties
8.1. ALLOW-CONFLICT Property
Property Name: ALLOW-CONFLICT Purpose: This property indicates whether or not the calendar and CS supports component conflicts. That is, whether or not any of the components in the calendar can overlap. Value Type: BOOLEAN Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in "VAGENDA" and "VCALSTORE" component. Description: This property is used to indicate whether components may conflict, that is, whether their expanded instances may share the same time or overlap the same time periods. If it has a value of
"TRUE", then conflicts are allowed. If "FALSE", the no two
components may conflict.
If "FALSE" in the "VCALSTORE" component, then all "VAGENDA"
component "ALLOW-CONFLICT" property values MUST be "FALSE" in the
CS.
Formal Definition: The property is defined by the following notation:
allow-conflict = "ALLOW-CONFLICT" other-params ":" boolean
CRLF
Example: The following is an example of this property for a "VAGENDA"
component:
ALLOW-CONFLICT:FALSE
8.2. ATT-COUNTER Property
Property Name: ATT-COUNTER
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property MUST be specified in an iCalendar object
that specifies a counter proposal to a group-scheduled calendar
entity. When storing a "METHOD" property with the "COUNTER"
method, there needs to be a way to remember who sent the COUNTER.
The ATT-COUNTER property MUST be added to all "COUNTER" [iTIP]
components by the CUA before storing in a CS.
Description: This property is used to identify the CAL-ADDRESS of the
entity that sent the "COUNTER" [iTIP] object.
Formal Definition: The property is defined by the following notation:
attcounter = "ATT-COUNTER" other-params ":" cal-address CRLF
Examples:
ATT-COUNTER:cap:example.com/Doug
ATT-COUNTER:mailto:Doug@Example.com
8.3. CALID Property
Property Name: CALID Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in the "VAGENDA" component. Description: This property is used to specify a fully-qualified CALID. Formal Definition: The property is defined by the following notation: calid = "CALID" other-params ":" relcalid CRLF Example: CALID:cap://cal.example.com/sdfifgty43218.4. CALMASTER Property
Property Name: CALMASTER Purpose: The property specifies an e-mail address of a person responsible for the calendar store. Value Type: URI Property Parameters: Non-standard property parameters can be specified on this property. Conformance: The property can be specified in a "VCALSTORE" component. Description: The parameter value SHOULD be a MAILTO URI as defined in [URL]. It MUST be a contact URI such as a MAILTO URI and not a home page or file URI that describes how to contact the calmasters. Formal Definition: The property is defined by the following notation: calmaster = "CALMASTER" other-params ":" uri CRLF ; uri = ; IANA registered uri as defined in [iCAL]. Example: The following is an example of this property:
CALMASTER:mailto:administrator@example.com
8.5. CAP-VERSION Property
Property Name: CAP-VERSION
Purpose: This property specifies the version of CAP supported.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property is specified in the "VREPLY" component
that is sent in response to a "GET-CAPABILITY" command.
Description: This specifies the version of CAP that the endpoint
supports. The list is a comma-separated list of supported RFC
numbers. The list MUST contain at least 4324.
Formal Definition: The property is defined by the following notation:
cap-version = "CAP-VERSION" other-params ":" text CRLF
Example: The following are examples of this property:
CAP-VERSION:4324
8.6. CARID Property
Property Name: CARID
Purpose: This property specifies the identifier for an access right
component.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property MUST be specified once in a "VCAR"
component.
Description: This property is used in the "VCAR" component to specify
an identifier. A "CARID" property value is unique per container.
Formal Definition: The property is defined by the following notation:
carid = "CARID" other-params ":" text CRLF
Example: The following are examples of this property:
CARID:xyzzy-007
CARID:User Rights
8.7. CAR-LEVEL Property
Property Name: CAR-LEVEL
Purpose: The property specifies the level of VCAR supported.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: The property can be specified in a "VREPLY" component
that is sent in response to a "GET-CAPABILITY" command.
Description: The value is one from a list of "CAR-NONE", "CAR-MIN",
or "CAR-FULL-1". If "CAR-FULL-1" is supplied, then "CAR-MIN" is
also available. A "CAR-MIN" implementation only supported the
"DEFAULT-VCARS" property values listed in the "VCALSTORE"
component, and a "CAR-MIN" implementation does not support the
creation or modification of "VCAR" components from the CUA.
Formal Definition: The property is defined by the following notation:
car-level = "CAR-LEVEL" ":" other-params ":"
car-level-values
car-level-values = ( "CAR-NONE" / "CAR-MIN" / "CAR-FULL-1"
/ other-levels )
other-levels = ; Any name published in an RFC for a
; "CAR-LEVEL" property value.
Example: The following is an example of this property:
CAR-LEVEL:CAR-FULL-1
8.8. COMPONENTS Property
Property Name: COMPONENTS
Purpose: The property specifies a the list of components supported by
the endpoint.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: The property can be specified in a "VREPLY" component in
response to a "GET-CAPABILITY" command.
Description: A comma-separated list of components that are supported
by the endpoint. A component that is not in the list sent from
the endpoint is not supported by that endpoint. Sending an
unsupported component results in unpredictable results. This
includes any components inside of other components (VALARM for
example). The recommended list is
"VCALSTORE,VCALENDAR,VREPLY,VAGENDA,
VEVENT,VALARM,VTIMEZONE,VJOURNAL,VTODO,VALARM,
DAYLIGHT,STANDARD,VCAR,VRIGHT,VQUERY".
Formal Definition: The property is defined by the following notation:
components = "COMPONENTS" other-params ":" comp-list CRLF
;
; All of these MUST be supplied only once.
;
comp-list-req = "VCALSTORE" "," "VCALENDAR" "," "VTIMEZONE" ","
"VREPLY" "," "VAGENDA" "," "STANDARD" ","
"DAYLIGHT"
; At least one MUST be supplied. The same value
; MUST NOT occur more than once.
;
comp-list-min = ( "," "VEVENT")
/ ( "," "VTODO")
/ ( "," "VJOURNAL" )
; The same value MUST NOT occur
; more than once. If "VCAR" is supplied then
; "VRIGHT" must be supplied.
;
comp-list-opt = ( "," "VFREEBUSY" ) / ( "," "VALARM" )
/ ( "," "VCAR" ) / ( "," "VRIGHT" )
/ ( "," "VQUERY") / ( "," x-comp )
/ ( "," iana-comp )
;
comp-list = comp-list-req 1*3comp-list-min *(comp-list-opt)
Example: The following is an example of this property:
COMPONENTS:VCALSTORE,VCALENDAR,VREPLY,VAGENDA,
VEVENT,VALARM,VTIMEZONE,VJOURNAL,VTODO,
DAYLIGHT,STANDARD,VFREEBUSY,VCAR,VRIGHT,VQUERY
8.9. CSID Property
Property Name: CSID
Purpose: The property specifies a globally unique identifier for the
calendar store.
Value Type: URI
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: The property can be specified in a "VCALSTORE"
component.
Description: The identifier MUST be globally unique. Each CS needs
its own unique identifier. The "CSID" property is the official
unique identifier for the CS. If the BEEP 'serverName' attribute
was supplied in the BEEP 'start' message, then the CSID will be
mapped to the virtual host name supplied, and the host name part
of the CSID MUST be the same as the 'serverName' value. This
allows one CS implementation to service multiple virtual hosts.
CS's are not required to support virtual hosting. If a CS does
not support virtual hosting, then it must ignore the BEEP
'serverName' attribute.
Formal Definition: The property is defined by the following notation:
csid = "CSID" other-params ":" capurl CRLF
Example: The following is an example of this property:
CSID:cap://calendar.example.com
8.10. DECREED Property
Property Name: DECREED
Purpose: This property specifies if an access right calendar
component is decreed or not.
Value Type: BOOLEAN
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property MAY be specified once in a "VCAR"
component.
Description: This property is used in the "VCAR" component to specify
whether the component is decreed or not. If the "DECREED"
property value is "TRUE" then the CUA will be unable to change the
contents of the "VCAR" component and any attempt will fail with an
error.
Formal Definition: The property is defined by the following notation:
decreed = "DECREED" other-params ":" boolean CRLF
Example: The following is an example of this property:
DECREED:TRUE
8.11. DEFAULT-CHARSET Property
Property Name: DEFAULT-CHARSET
Purpose: This property indicates the default charset.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VAGENDA" and
"VCALSTORE" calendar component.
Description: In a "VAGENDA" component this property is used to
indicate the charset of calendar. If not specified, the default
is the first value in the "VCALSTORE" components "DEFAULT-CHARSET"
property value list. The value MUST be an IANA registered
character set as defined in [CHARREG].
In a "VCALSTORE" component it is a comma-separated list of charsets
supported by the CS. The first entry is the default entry for all
newly created "VAGENDA" components. The "UTF-8" value MUST be in
the "VCALSTORE" component "DEFAULT-CHARSET" property list. All
compliant
CAP implementations (CS and CUA) MUST support at least the "UTF-8"
charset.
If a charset name contains a comma (,), that comma must be
backslash-escaped in the value.
Formal Definition: The property is defined by the following notation:
default-charset = "DEFAULT-CHARSET" other-params ":" text
*( "," text) CRLF
Example: The following is an example of this property for a "VAGENDA"
component:
DEFAULT-CHARSET:Shift_JIS,UTF-8
8.12. DEFAULT-LOCALE Property
Property Name: DEFAULT-LOCALE
Purpose: This property specifies the default language for text
values.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VAGENDA" and
"VCALSTORE" components.
Description: In a "VAGENDA" component, the "DEFAULT-LOCALE" property
is used to indicate the locale of the calendar. The full locale
SHOULD be used. The default and minimum locale is POSIX (aka the
'C' locale).
In a "VCALSTORE" component, it is a comma-separated list of
locales supported by the CS. The first value in the list is the
default for all newly created VAGENDAs. "POSIX" MUST be in the
list.
Formal Definition: The property is defined by the following notation:
default-locale = "DEFAULT-LOCALE" other-params ":" language
*( "," language) CRLF
;
language = ; Text identifying a locale, as defined in [CHARPOL]
Example: The following is an example of this property:
DEFAULT-LOCALE:en-US.iso-8859-1,POSIX
8.13. DEFAULT-TZID Property
Property Name: DEFAULT-TZID Purpose: This property specifies the text value that specifies the time zones. Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property may be specified once in a "VAGENDA" and "VCALSTORE" components. Description: A multi-valued property that lists the known time zones. The first is the default. Here "TZID" property values are the same as the "TZID" property defined in [iCAL]. If used in a "VCALSTORE" component, it is a comma-separated list of TZIDs known to the CS. The entry is used as the default TZID list for all newly created calendars. The list MUST contain at least "UTC". A "VCALSTORE" components MUST contain one "VTIMEZONE" component for each value in the "DEFAULT-TZID" property value. If used in a "VAGENDA" component, it is a comma-separated list of "TZID" property values naming the time zones known to the calendar. The first time zone in the list is the default and is used as the localtime for objects that contain a date or date-time value without a time zone. All "VAGENDA" components MUST have one "VTIMEZONE" component contained for each value in the "DEFAULT- TZID" property value. If a "TZID" property value contains a comma (,), the comma must be backslash-escaped. Formal Definition: This property is defined by the following notation: default-tzid = "DEFAULT-TZID" other-params ":" [tzidprefix] text *("," [tzidprefix] text) CRLF ; txidprefix = ; As defined in [iCAL]. Example: The following is an example of this property:
DEFAULT-TZID:US/Mountain,UTC
8.14. DEFAULT-VCARS Property
Property Name: DEFAULT-VCARS
Purpose: This property is used to specify the "CARID" property ids of
the default "VCAR" components for newly created "VAGENDA"
components.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property MUST be specified in "VCALSTORE" calendar
component and MUST at least specify the following values:
"READBUSYTIMEINFO", "REQUESTONLY", "UPDATEPARTSTATUS", and
"DEFAULTOWNER".
Description: This property is used in the "VCALSTORE" component to
specify the "CARID" value of the "VCAR" components that MUST be
copied into now "VAGENDA" components at creation time by the CS.
All "DEFAULT-VCAR" values must have "VCARS" components stored in
the "VCALSTORE".
Formal Definition: The property is defined by the following notation:
defautl-vcars = "DEFAULT-VCARS" other-params ":" text
*( "," text ) CRLF
Example: The following is an example of this property:
DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY,
UPDATEPARTSTATUS,DEFAULTOWNER
8.15. DENY Property
Property Name: DENY
Purpose: This property identifies the UPN(s) being denied access in
the "VRIGHT" component.
Value Type: UPN-FILTER
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VRIGHT" components.
Description: This property is used in the "VRIGHT" component to
define the CU or UG being denied access.
Formal Definition: The property is defined by the following notation:
deny = "DENY" other-params ":" upn-filter CRLF
Example: The following are examples of this property:
DENY:*
DENY:bob@example.com
8.16. EXPAND property
Property Name: EXPAND
Purpose: This property is used to notify the CS whether to expand any
component with recurrence rules into multiple instances, in a
query reply.
Value Type: BOOLEAN
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VQUERY" components.
Description: If a CUA wishes to see all of the instances of a
recurring component, the CUA sets EXPAND=TRUE in the "VQUERY"
component. If not specified, the default is "FALSE". Note that
if the CS has its "RECUR-EXPAND" CS property value set to "FALSE",
then the "EXPAND" property will be ignored and the result will be
as if the "EXPAND" value was set to "FALSE". The results will be
bounded by any date range or other limits in the query.
Formal Definition: The property is defined by the following notation:
expand = "EXPAND" other-params ":" ("TRUE" / "FALSE") CRLF
Example: The following are examples of this property:
EXPAND:FALSE
EXPAND:TRUE
8.17. GRANT Property
Property Name: GRANT Purpose: This property identifies the UPN(s) being granted access in the "VRIGHT" component. Value Type: UPN-FILTER Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in "VRIGHT" calendar components. Description: This property is used in the "VRIGHT" component to specify the CU or UG being granted access. Formal Definition: The property is defined by the following notation: grant = "GRANT" other-params ":" upn-filter CRLF Example: The following are examples of this property: GRANT:* GRANT:bob@example.com8.18. ITIP-VERSION Property
Property Name: ITIP-VERSION Purpose: This property specifies the version of ITIP supported. Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property is specified in the "VREPLY" component that is sent in response to a "GET-CAPABILITY" command. Description: This specifies the version of ITIP that the endpoint supports. The list is a comma-separated list of supported RFC numbers. The list MUST contain at least 2446, which is [iTIP] Formal Definition: The property is defined by the following notation:
itip-version = "ITIP-VERSION" other-params ":" text CRLF
Example: The following are examples of this property:
ITIP-VERSION:2446
8.19. MAX-COMP-SIZE Property
Property Name: MAX-COMP-SIZE
Purpose: This property specifies the largest size of any object
accepted.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property is specified in the "VREPLY" component
that is sent in response to a "GET-CAPABILITY" command.
Description: A positive integer value that specifies the size of the
largest iCalendar object that can be accepted in octets. Objects
larger than this will be rejected. A value of zero (0) means no
limit. This is also the maximum value of any [BEEP] payload that
will be accepted or sent.
Formal Definition: The property is defined by the following notation:
max-comp-size = "MAX-COMP-SIZE" other-params ":" posint0 CRLF
Example: The following are examples of this property:
MAX-COMP-SIZE:1024
8.20. MAXDATE Property
Property Name: MAXDATE
Purpose: This property specifies the date/time in the future, beyond
which the CS or CUA cannot represent.
Value Type: DATE-TIME
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: The property can be specified in the "VCALSTORE"
component.
Description: The date and time MUST be a UTC value and end with 'Z'.
Formal Definition: The property is defined by the following notation:
maxdate = "MAXDATE" other-params ":" date-time CRLF
Example: The following is an example of this property:
MAXDATE:20990101T000000Z
8.21. MINDATE Property
Property Name: MINDATE
Purpose: This property specifies the date/time in the past, prior to
which the server cannot represent.
Value Type: DATE-TIME
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: The property can be specified in the "VCALSTORE"
component.
Description: The date and time MUST be a UTC value and end with 'Z'.
Formal Definition: The property is defined by the following notation:
mindate = "MINDATE" other-params ":" date-time CRLF
date-time = ; As defined in [iCAL].
Example: The following is an example of this property:
MINDATE:19710101T000000Z
8.22. MULTIPART Property
Property Name: MULTIPART
Purpose: This property provides a comma-separated list of supported
MIME multipart types supported by the sender.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property is specified in the "VREPLY" component
that is sent in response to a "GET-CAPABILITY" command.
Description: This property is used in the in the "GET-CAPABILITY"
command reply to indicate the MIME multipart types supported. A
CS and CUA SHOULD support all registered MIME multipart types.
Formal Definition: The property is defined by the following notation:
multipart = "MULTIPART" other-params ":" text *( "," text) CRLF
Example: The following is an example of this property:
MULTIPART:related,alternate,mixed
8.23. NAME Property
Property Name: NAME
Purpose: This property provides a localizable display name for a
component.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in a component.
Description: This property is used in the component to specify a
localizable display name. If more than one "NAME" properties are
in a component, then they MUST have unique "LANG" parameters. If
the "LANG" parameter is not supplied, then it defaults to the
"VAGENDA" component's "DEFAULT-LOCALE" first value. If the
component is a "VAGENDA", then the default value is the "VAGENDA"s
component's "DEFAULT-LOCALE" first value. A "VCALSTORE"
component's "DEFAULT-LOCALE" first value is the default if the
component is stored at the "VCALSTORE" level.
Formal Definition: The property is defined by the following notation:
name = "NAME" nameparam ":" text CRLF
;
nameparam = other-params [ ";" languageparam ] other-params
;
languageparam = ; As defined in [iCAL].
Example: The following is an example of this property:
NAME:Restrict Guests From Creating VALARMs On VEVENTs
8.24. OWNER Property
Property Name: OWNER
Purpose: The property specifies an owner of the component.
Value Type: UPN
Property Parameters: Non-standard, alternate text representation and
language property parameters can be specified on this property.
Conformance: The property MUST be specified in a "VAGENDA" component.
Description: A multi-instanced property indicating the calendar
owner.
Formal Definition: The property is defined by the following notation:
owner = "OWNER" other-params ":" upn CRLF
Example: The following is an example of this property:
OWNER:jsmith@example.com
OWNER:jdough@example.com
8.25. PERMISSION Property
Property Name: PERMISSION
Purpose: This property defines a permission that is granted or denied
in a "VRIGHT" component.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VRIGHT" components.
Description: This property is used in the "VRIGHT" component to
define a permission that is granted or denied.
Formal Definition: The property is defined by the following notation:
permission = "PERMISSION" other-params ":" permvalue CRLF
;
permvalue = ( "SEARCH" / "CREATE" / "DELETE"
/ "MODIFY" / "MOVE" / all
/ iana-cmd / x-cmd )
;
all = "*"
;
iana-cmd = ; Any command registered by IANA directly or
; included in an RFC that may be applied as
; a command.
;
x-cmd = ; Any experimental command that starts with
; "x-" or "X-".
Example: The following is an example of this property:
PERMISSION:SEARCH
8.26. QUERY property
Property Name: QUERY
Purpose: Specifies the query for the component.
Value Type: CAL-QUERY
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VQUERY" components.
Description: A "QUERY" is used to specify the "CAL-QUERY" (Section
6.1.1 for the query.
Formal Definition: The property is defined by the following notation:
query = "QUERY" other-params ":" cal-query CRLF
Example: The following is an example of this property:
QUERY:SELECT * FROM VEVENT
8.27. QUERYID property
Property Name: QUERYID Purpose: Specifies a unique ID for a query in the targeted container. Value Type: TEXT Property Parameters: Non-standard property parameters are specified on this property. Conformance: This property can be specified in "VQUERY" components. Description: A "QUERYID" property is used to specify the unique id for a query. A "QUERYID" property value is unique per container. Formal Definition: The property is defined by the following notation: queryid = "QUERYID" other-params ":" text CRLF Example: The following are examples of this property: QUERYID:Any Text String QUERYID:fetchUnProcessed8.28. QUERY-LEVEL Property
Property Name: QUERY-LEVEL Purpose: This property specifies the level of query supported. Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: The property can be specified in the "VREPLY" component in response to a "GET-CAPABILITY" command. Description: Indicates level of query support. CAL-QL-NONE is for CS's that allow ITIP methods only to be deposited and nothing else. Formal Definition: The property is defined by the following notation: query-level = "QUERY-LEVEL" other-params ":" ( "CAL-QL-1" / "CAL-QL-NONE") CRLF
Example: The following is an example of this property:
QUERY-LEVEL:CAL-QL-1
8.29. RECUR-ACCEPTED Property
Property Name: RECUR-ACCEPTED
Purpose: This property specifies if the endpoint supports recurring
instances.
Value Type: BOOLEAN
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: The property can be specified in the "VREPLY" component
in response to a "GET-CAPABILITY" command.
Description: Indicates if recurrence rules are supported. If "FALSE"
then the endpoint cannot process any kind of recurring rules.
Formal Definition: The property is defined by the following notation:
recur-accepted = "RECUR-ACCEPTED" other-params ":" boolean CRLF
Example: The following is an example of this property:
RECUR-ACCEPTED:TRUE
RECUR-ACCEPTED:FALSE
8.30. RECUR-LIMIT Property
Property Name: RECUR-LIMIT
Purpose: This property specifies the maximum number of instances the
endpoint will expand instances at query or storage time.
Value Type: INTEGER
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: The property can be specified in the "VREPLY" component
in response to a "GET-CAPABILITY" command.
Description: For implementations that have the "STORES-EXPANDED"
value set to "TRUE", this value specifies the maximum number of
instances that will be stored and fetched. For all
implementations, this is the maximum number of instances that will
be returned when the "EXPAND" parameter is specified as "TRUE" and
the results contain an infinite or large number of recurring
instances.
Formal Definition: The property is defined by the following notation:
recur-limit = "RECUR-LIMIT" other-params ":" posint1 CRLF
Example: The following is an example of this property:
RECUR-LIMIT:1000
8.31. RECUR-EXPAND Property
Property Name: RECUR-EXPAND
Purpose: This property specifies if the endpoint can expand
recurrences into multiple objects.
Value Type: BOOLEAN
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: The property can be specified in the "VREPLY" component
in response to a "GET-CAPABILITY" command.
Description: If "TRUE", then the endpoint can expand an object into
multiple instances as defined by its recurrence rules when the
"EXPAND" property is supplied. If "FALSE", then the endpoint
ignores the "EXPAND" property.
Formal Definition: The property is defined by the following notation:
recur-expand = "RECUR-EXPAND" other-params ":" boolean CRLF
Example: The following is an example of this property:
RECUR-EXPAND:TRUE
RECUR-EXPAND:FALSE
8.32. RESTRICTION Property
Property Name: RESTRICTION
Purpose: This property defines restrictions on the result value of
new or existing components.
Value Type: CAL-QUERY
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VRIGHT" components,
but only when the "PERMISSION" property is set to "CREATE",
"MODIFY", or "*" property value.
Description: This property is used in the "VRIGHT" component to
define restrictions on the components that can be written (i.e.,
by using the "CREATE" or "MOVE" commands) as well as on the values
that may take existent calendar store properties, calendar
properties, components, and properties (i.e., by using the
"MODIFY" command). Accepted values MUST match any specified
"RESTRICTION" property values.
Formal Definition: The property is defined by the following notation:
restriction = "RESTRICTION" other-params ":" cal-query CRLF
Example: The following are examples of this property:
RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST'
RESTRICTION:SELECT * FROM VEVENT WHERE
SELF() IN ORGANIZER
RESTRICTION:SELECT * FROM VEVENT WHERE 'BUSINESS' IN
CATEGORIES
8.33. SCOPE Property
Property Name: SCOPE
Purpose: This property identifies the objects in the CS to which the
access rights apply.
Value Type: CAL-QUERY
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VRIGHT" components.
Description: This property is used in the "VRIGHT" component to
define the set of objects, subject to the access right being
defined.
Formal Definition: The property is defined by the following notation:
scope = "SCOPE" other-params ":" cal-query CRLF
Example: The following is an example of this property:
SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC'
8.34. STORES-EXPANDED Property
Property Name: STORES-EXPANDED
Purpose: This property specifies if the sending endpoint expands
recurrence rules prior to storing them into the CS.
Value Type: BOOLEAN
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in a "VREPLY" component
in response to a "GET-CAPABILITY" command.
Description: If the value is "TRUE", then the endpoint expands
recurrence rules and stores the results into the CS. If this is
"TRUE", then the "RECUR-LIMIT" property is significant because an
infinitely-recurring appointment will store no more than "RECUR-
LIMIT" property values into the CS and all other instances will be
lost.
Formal Definition: The property is specified by the following
notation:
stores-expanded = "STORES-EXPANDED" other-params ":" boolean
CRLF
The following is an example of this property:
STORES-EXPANDED:TRUE
STORES-EXPANDED:FALSE
8.35. TARGET Property
Property Name: TARGET
Purpose: This property defines the container that the issued command
will act upon. Its value is a capurl, as defined in Section 5.
Value Type: URI
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in a command component.
Description: This property value is used to specify the container
that the command will effect. When used in a command, the command
will be performed on the container that has a capurl matching the
value.
Formal Definition: The property is specified by the following
notation:
target = "TARGET" other-params ":" ( capurl / relcalid ) CRLF
Example: The following is an example of this property:
TARGET:cap://mycal.example.com
TARGET:SomeRelCalid
8.36. TRANSP Property
Property Name: TRANSP
Purpose: This property defines whether a component is transparent or
not to busy-time searches. This is a modification to [iCAL]
"TRANSP" property, in that it adds some values.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in a component.
Description: Time Transparency is the characteristic of an object
that determines whether it appears to consume time on a calendar.
Objects that consume actual time for the individual or resource
associated with the calendar SHOULD be recorded as "OPAQUE",
allowing them to be detected by free-busy time searches. Other
objects, which do not take up the individual's (or resource's)
time SHOULD be recorded as "TRANSPARENT", making them invisible to
free/busy time searches.
Formal Definition: The property is specified by the following
notation:
transp = "TRANSP" other-params ":" transvalue CRLF
;
transvalue = "OPAQUE" ;Blocks or opaque on busy time searches.
/ "TRANSPARENT"
; Transparent on busy time searches.
/ "TRANSPARENT-NOCONFLICT"
; Transparent on busy time searches,
; and no other OPAQUE or OPAQUE-
; NOCONFLICT objects can overlap it.
;
/ "OPAQUE-NOCONFLICT"
; Opaque on busy time searches, and
; no other OPAQUE or OPAQUE-NOCONFLICT
; objects can overlap it.
;
; Default value is OPAQUE
The following is an example of this property for an object that is
opaque or blocks on free/busy time searches, and no other object
can overlap it:
TRANSP:OPAQUE-NOCONFLICT
9. New Components
9.1. VAGENDA Component
Component Name: VAGENDA
Purpose: Provide a grouping of properties that defines an agenda.
Formal Definition: There are two formats of the "VAGENDA" component.
(1) When it is being created, and (2) how it exists in the
"VCALSTORE" component.
A "VAGENDA" component in a "VCALSTORE" component is defined by the
following notes and ABNF notation:
CALSCALE - The value MUST be from the "VCALSTORE" "CALSCALE"
property list. The default is the first entry in the
VCALSTORE CALSCALE list.
CREATED - The timestamp of the calendar's create date. This
is a READ ONLY property in a "VAGENDA".
LAST-MODIFIED - The timestamp of any change to the "VAGENDA"
properties or when any component was last created, modified,
or deleted.
agenda = "BEGIN" ":" "VAGENDA" CRLF
agendaprop
*(icalobject) ; as defined in [iCAL]
"END" ":" "VAGENDA" CRLF
agendaprop = *(
; The following MUST occur exactly once.
;
allow-conflict / relcalid / calscale / created
/ default-charset / default-locale
/ default-tzid / last-mod
;
; The following MUST occur at least once.
; and the value MUST NOT be empty.
;
/ owner
;
; The following are optional,
; and MAY occur more than once.
;
/ name / related-to / other-props / x-comp
)
icalobject = ; As defined in [iCAL].
;
created = ; As defined in [iCAL].
;
related-to = ; As defined in [iCAL].
When creating a VAGENDA, use the following notation:
agendac = "BEGIN" ":" "VAGENDA" CRLF
agendacprop
*(icalobject) ; as defined in [iCAL].
"END" ":" "VAGENDA" CRLF
agendacprop = *(
; The following MUST occur exactly once.
;
allow-conflict / relcalid / calscale
/ default-charset / default-locale
/ default-tzid
;
; The following MUST occur at least once.
; and the value MUST NOT be empty.
;
/ owner
;
; The following are optional,
; and MAY occur more than once.
;
/ name / related-to / other-props / x-comp
)
To fetch all of the properties from the targeted "VAGENDA" component
but do not fetch any components, use:
SELECT * FROM VAGENDA
To fetch all of the properties from the targeted VAGENDA and all of
the contained components, use the special '*.*' value:
SELECT *.* FROM VAGENDA
9.2. VCALSTORE Component
Component Name: VCALSTORE
Purpose: Provide a grouping of properties that defines a calendar
store.
Formal Definition: A "VCALSTORE" component is defined by the
following table and ABNF notation. The creation of a "VCALSTORE"
component is an administrative task and not part of the CAP
protocol.
The following are notes to some of the properties in the
"VCALSTORE" component.
CALSCALE - A comma-separated list of CALSCALEs supported by
this CS. All "VAGENDA" component calendar CALSCALE
properties MUST be from this list. This list MUST contain
at least "GREGORIAN". The default for newly created
"VAGENDA" components is the first entry.
RELATED-TO - This is a multiple-instance property. There MUST
be a "RELATED-TO" property for each of the "VAGENDA"
components contained in the "VCALSTORE" component, each with
the "RELTYPE" parameter value set to "CHILD". Other
"RELATED-TO" properties may be included.
CREATED - The timestamp of the CS creation time. This is a
READ ONLY property.
CSID - The CSID of this calendar store. This MUST NOT be
empty. How this property is set in the VCALSTORE is an
administrative or implementation-specific issue and is not
covered in CAP. This is a READ ONLY property. A suggested
value is the fully-qualified host name or a fully-qualified
virtual host name supported by the system.
LAST-MODIFIED - The timestamp when the Properties of the
"VCALSTORE" component were last updated or calendars were
created or deleted. This is a READ ONLY PROPERTY.
calstorec = "BEGIN" ":" "VCALSTORE" CRLF
calstoreprop
*(vagendac)
"END" ":" "VCALSTORE" CRLF
;
calstoreprop = *(
; the following MUST occur exactly once
;
allow-conflict / calscale / calmaster
/ created / csid / default-charset
/ default-locale / default-vcars
/ default-tzid / last-mod / maxdate / mindate
;
; the following are optional,
; and MAY occur more than once
;
/ name / related-to / other-props / x-comp
)
;
vagendac = ; As defined in [iCAL].
;
last-mod = ; As defined in [iCAL].
To fetch all of the properties from the targeted VCALSTORE and not
fetch the calendars that it contains, use:
SELECT * FROM VCALSTORE
To fetch all of the properties from the targeted "VCALSTORE"
component and all of the contained calendars and all of those
calendars' contained properties and components, use the special '*.*'
value:
SELECT *.* FROM VCALSTORE
9.3. VCAR Component
Component Name: VCAR
Purpose: Provide a grouping of calendar access rights.
Formal Definition: A "VCAR" component is defined by the following
notation:
carc = "BEGIN" ":" "VCAR" CRLF
carprop 1*rightc
"END" ":" "VCAR" CRLF
;
carprop = 1*(
;
; 'carid' is REQUIRED,
; but MUST NOT occur more than once
;
carid /
;
; the following are OPTIONAL,
; and MAY occur more than once
;
name / decreed / other-props
)
Description: A "VCAR" component is a grouping of properties, and
"VRIGHT" components, that represents access rights granted or
denied to UPNs.
The "CARID" property specifies the local identifier for the "VCAR"
component. The "NAME" property specifies a localizable display
name.
Example: In the following example, the UPN "foo@example.com" is given
search access to the "DTSTART" and "DTEND" VEVENT properties. No
other access is specified:
BEGIN:VCAR
CARID:View Start and End Times
NAME:View Start and End Times
BEGIN:VRIGHT
GRANT:foo@example.com
PERMISSION:SEARCH
SCOPE:SELECT DTSTART,DTEND FROM VEVENT
END:VRIGHT
END:VCAR
In this example, all UPNs are given search access to "DTSTART" and
"DTEND" properties of VEVENT components. "All CUs and UGs" are
specified by the UPN value "*". Note that this enumerated UPN
value is not in quotes:
BEGIN:VCAR
CARID:ViewStartEnd2
NAME:View Start and End Times 2
BEGIN:VRIGHT
GRANT:*
PERMISSION:SEARCH
SCOPE:SELECT DTSTART,DTEND FROM VEVENT
END:VRIGHT
END:VCAR
In these examples, full calendar access rights are given to the
CAL-OWNERS(), and a hypothetical administrator is given access
rights to specify calendar access rights. If no other rights are
specified, only these two UPNs can specify calendar access rights:
BEGIN:VCAR
CARID:some-id-3
NAME:Only OWNER or ADMIN Settable VCARs
BEGIN:VRIGHT
GRANT:CAL-OWNERS()
PERMISSION:*
SCOPE:SELECT * FROM VAGENDA
END:VRIGHT
BEGIN:VRIGHT
GRANT:cal-admin@example.com
PERMISSION:*
SCOPE:SELECT * FROM VCAR
RESTRICTION:SELECT * FROM VCAR
END:VRIGHT
END:VCAR
In this example, rights to write, search, modify or delete
calendar access are denied to all UPNs. This example would
disable providing different access rights to the calendar store or
calendar. This calendar access right should be specified with
great care, as it removes the ability to change calendar access;
even for the owner or administrator. It could be used by small
devices that do not support changing any VCAR:
BEGIN:VCAR
CARID:VeryRestrictiveVCAR-2
NAME:No CAR At All
BEGIN:VRIGHT
DENY:*
PERMISSION:*
SCOPE:SELECT * FROM VCAR
END:VRIGHT
END:VCAR
9.4. VRIGHT Component
Component Name: "VRIGHT"
Purpose: Provide a grouping of properties that describe an access
right (granted or denied).
Formal Definition: A "VRIGHT" component is defined by the following
notation:
rightc = "BEGIN" ":" "VRIGHT" CRLF
rightprop
"END" ":" "VRIGHT" CRLF
;
rightprop = 2*(
;
; either 'grant' or 'deny' MUST
; occur at least once
; and MAY occur more than once
;
grant / deny /
;
; 'permission' MUST occur at least once
; and MAY occur more than once
;
permission /
;
; the following are optional,
; and MAY occur more than once
;
scope / restriction / other-props
)
Description: A "VRIGHT" component is a grouping of calendar access
right properties.
The "GRANT" property specifies the UPN that is being granted
access. The "DENY" property specifies the UPN that is being
denied access. The "PERMISSION" property specifies the actual
permission being set. The "SCOPE" property identifies the
calendar store properties, calendar properties, components, or
properties to which the access right applies. The "RESTRICTION"
property specifies restrictions on commands and results. If the
command does not match the restrictions, or if the results of the
command do not match the restrictions, then it is an access
violation.
9.5. VREPLY Component
Component Name: "VREPLY"
Purpose: Provide a grouping of arbitrary properties and components
that are the data set result from an issued command.
Formal Definition: A "VREPLY" component is defined by the following
notation:
replyc = "BEGIN" ":" "VREPLY" CRLF
any-prop-or-comp
"END" ":" "VREPLY" CRLF
;
any-prop-or-comp = ; Zero or more iana or experimental
; properties and components, in any order.
Description: Provide a grouping of arbitrary properties and
components that are the data set result from an issued command.
A query can return a predictable set of arbitrary properties and
components. This component is used by query and other commands to
return data that does not fit into any other component. It may
contain any valid property or component, even if they are not
registered.
9.6. VQUERY Component
Component Name: VQUERY
Purpose: A component describes a set of objects to be acted upon.
Formal Definition: A "VQUERY" component is defined by the following
notation:
queryc = "BEGIN" ":" "VQUERY" CRLF
queryprop
"END" ":" "VCAR" CRLF
;
queryprop = 1*(
;
; 'queryid' is OPTIONAL but MUST NOT occur
; more than once. If the "TARGET" property
; is supplied then the "QUERYID" property
; MUST be supplied.
;
queryid / target
;
; 'expand' is OPTIONAL but MUST NOT occur
; more than once.
;
expand
;
; the following are OPTIONAL, and MAY occur
; more than once
;
/ name / other-props
;
; the following MUST occur at least once if
; queryid is not supplied.
;
/ query
)
Description: A "VQUERY" contains properties that describe which
properties and components the CS is requested to act upon.
The "QUERYID" property specifies the local identifier for a
"VQUERY" component.
For a search, if the "TARGET" property is supplied in a "VQUERY"
component, then the CS is to search for the query in the CALID
supplied by the "TARGET" property value.
For a create, the "TARGET" property MUST NOT be supplied because
the destination container is already supplied in the "TARGET"
property of the "VCALENDAR" component.
Examples: see Section 6.1.1.