Internet DRAFT - draft-royer-calsch-cap
draft-royer-calsch-cap
Calendaring and Scheduling D. Royer
Internet-Draft IntelliCal, LLC
Expires: February 9, 2006 G. Babics
Oracle
P. Hill
Massachusetts Institute of
Technology
S. Mansour
AOL/Netscape
August 8, 2005
Calendar Access Protocol (CAP)
draft-royer-calsch-cap-03
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on February 9, 2006.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
The Calendar Access Protocol (CAP) is an Internet protocol described
in this memo that permits a Calendar User (CU) to utilize a Calendar
Royer, et al. Expires February 9, 2006 [Page 1]
Internet-Draft Calendar Access Protocol (CAP) August 2005
User Agent (CUA) to access an [iCAL] based Calendar Store (CS).
At the time of this writing there are three vendors implementing CAP.
It has already been determined that some changes are needed. In
order to get implementation experience the participants felt that CAP
needed to be released so that many years of work could be preserved.
Many properties in CAP can be used by other iCalendar protocols and
have had many years of debate.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1 Formatting Conventions . . . . . . . . . . . . . . . . . 5
1.2 Related Documents . . . . . . . . . . . . . . . . . . . 6
1.3 Definitions . . . . . . . . . . . . . . . . . . . . . . 7
2. Additions to iCalendar . . . . . . . . . . . . . . . . . . . 12
2.1 New Value Types (summary) . . . . . . . . . . . . . . . 15
2.1.1 New Parameters (summary) . . . . . . . . . . . . . . 15
2.1.2 New or Updated Properties (summary) . . . . . . . . 16
2.1.3 New Components (summary) . . . . . . . . . . . . . . 18
2.2 Relationship of RFC-2446 (ITIP) and CAP . . . . . . . . 19
3. CAP Design . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.1 System Model . . . . . . . . . . . . . . . . . . . . . . 22
3.2 Calendar Store Object Model . . . . . . . . . . . . . . 22
3.3 Protocol Model . . . . . . . . . . . . . . . . . . . . . 23
3.3.1 Use of BEEP, MIME and iCalendar . . . . . . . . . . 24
4. Security Model . . . . . . . . . . . . . . . . . . . . . . . 26
4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . . 26
4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . 26
4.1.2 Anonymous Users and Authentication . . . . . . . . . 27
4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . 27
4.2 Access Rights . . . . . . . . . . . . . . . . . . . . . 28
4.2.1 Access Control and NOCONFLICT . . . . . . . . . . . 28
4.2.2 Predefined VCARs . . . . . . . . . . . . . . . . . . 28
4.2.3 Decreed VCARs . . . . . . . . . . . . . . . . . . . 30
4.3 CAP Session Identity . . . . . . . . . . . . . . . . . . 31
5. CAP URL and Calendar Address . . . . . . . . . . . . . . . . 33
6. New Value Types . . . . . . . . . . . . . . . . . . . . . . 35
6.1 Property Value Data Types . . . . . . . . . . . . . . . 35
6.1.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . 35
6.1.2 UPN Value Type . . . . . . . . . . . . . . . . . . . 51
6.1.3 UPN-FILTER Value . . . . . . . . . . . . . . . . . . 52
7. New Parameters . . . . . . . . . . . . . . . . . . . . . . . 55
7.1 ACTION Parameter . . . . . . . . . . . . . . . . . . . . 55
7.2 ENABLE Parameter . . . . . . . . . . . . . . . . . . . . 55
7.3 ID Parameter . . . . . . . . . . . . . . . . . . . . . . 56
7.4 LATENCY Parameter . . . . . . . . . . . . . . . . . . . 57
7.5 LOCAL Parameter . . . . . . . . . . . . . . . . . . . . 58
Royer, et al. Expires February 9, 2006 [Page 2]
Internet-Draft Calendar Access Protocol (CAP) August 2005
7.6 LOCALIZE Parameter . . . . . . . . . . . . . . . . . . . 58
7.7 OPTIONS Parameter . . . . . . . . . . . . . . . . . . . 59
8. New Properties . . . . . . . . . . . . . . . . . . . . . . . 61
8.1 ALLOW-CONFLICT Property . . . . . . . . . . . . . . . . 61
8.2 ATT-COUNTER Property . . . . . . . . . . . . . . . . . . 61
8.3 CALID Property . . . . . . . . . . . . . . . . . . . . . 62
8.4 CALMASTER Property . . . . . . . . . . . . . . . . . . . 63
8.5 CAP-VERSION Property . . . . . . . . . . . . . . . . . . 63
8.6 CARID Property . . . . . . . . . . . . . . . . . . . . . 64
8.7 CAR-LEVEL Property . . . . . . . . . . . . . . . . . . . 65
8.8 COMPONENTS Property . . . . . . . . . . . . . . . . . . 65
8.9 CSID Property . . . . . . . . . . . . . . . . . . . . . 67
8.10 DECREED Property . . . . . . . . . . . . . . . . . . . . 67
8.11 DEFAULT-CHARSET Property . . . . . . . . . . . . . . . . 68
8.12 DEFAULT-LOCALE Property . . . . . . . . . . . . . . . . 69
8.13 DEFAULT-TZID Property . . . . . . . . . . . . . . . . . 70
8.14 DEFAULT-VCARS Property . . . . . . . . . . . . . . . . . 71
8.15 DENY Property . . . . . . . . . . . . . . . . . . . . . 72
8.16 EXPAND property . . . . . . . . . . . . . . . . . . . . 72
8.17 GRANT Property . . . . . . . . . . . . . . . . . . . . . 73
8.18 ITIP-VERSION Property . . . . . . . . . . . . . . . . . 74
8.19 MAX-COMP-SIZE Property . . . . . . . . . . . . . . . . . 74
8.20 MAXDATE Property . . . . . . . . . . . . . . . . . . . . 75
8.21 MINDATE Property . . . . . . . . . . . . . . . . . . . . 76
8.22 MULTIPART Property . . . . . . . . . . . . . . . . . . . 76
8.23 NAME Property . . . . . . . . . . . . . . . . . . . . . 77
8.24 OWNER Property . . . . . . . . . . . . . . . . . . . . . 78
8.25 PERMISSION Property . . . . . . . . . . . . . . . . . . 79
8.26 QUERY property . . . . . . . . . . . . . . . . . . . . . 79
8.27 QUERYID property . . . . . . . . . . . . . . . . . . . . 80
8.28 QUERY-LEVEL Property . . . . . . . . . . . . . . . . . . 81
8.29 RECUR-ACCEPTED Property . . . . . . . . . . . . . . . . 81
8.30 RECUR-LIMIT Property . . . . . . . . . . . . . . . . . . 82
8.31 RECUR-EXPAND Property . . . . . . . . . . . . . . . . . 83
8.32 RESTRICTION Property . . . . . . . . . . . . . . . . . . 83
8.33 SCOPE Property . . . . . . . . . . . . . . . . . . . . . 84
8.34 STORES-EXPANDED Property . . . . . . . . . . . . . . . . 85
8.35 TARGET Property . . . . . . . . . . . . . . . . . . . . 86
8.36 TRANSP Property . . . . . . . . . . . . . . . . . . . . 86
9. New Components . . . . . . . . . . . . . . . . . . . . . . . 88
9.1 VAGENDA Component . . . . . . . . . . . . . . . . . . . 88
9.2 VCALSTORE Component . . . . . . . . . . . . . . . . . . 90
9.3 VCAR Component . . . . . . . . . . . . . . . . . . . . . 92
9.4 VRIGHT Component . . . . . . . . . . . . . . . . . . . . 95
9.5 VREPLY Component . . . . . . . . . . . . . . . . . . . . 96
9.6 VQUERY Component . . . . . . . . . . . . . . . . . . . . 96
10. Commands and Responses . . . . . . . . . . . . . . . . . . 98
10.1 CAP Commands (CMD) . . . . . . . . . . . . . . . . . . . 98
Royer, et al. Expires February 9, 2006 [Page 3]
Internet-Draft Calendar Access Protocol (CAP) August 2005
10.1.1 Bounded Latency . . . . . . . . . . . . . . . . . . 99
10.2 ABORT Command . . . . . . . . . . . . . . . . . . . . . 101
10.3 CONTINUE Command . . . . . . . . . . . . . . . . . . . . 102
10.4 CREATE Command . . . . . . . . . . . . . . . . . . . . . 103
10.5 DELETE Command . . . . . . . . . . . . . . . . . . . . . 109
10.6 GENERATE-UID Command . . . . . . . . . . . . . . . . . . 112
10.7 GET-CAPABILITY Command . . . . . . . . . . . . . . . . . 114
10.8 IDENTIFY Command . . . . . . . . . . . . . . . . . . . . 117
10.9 MODIFY Command . . . . . . . . . . . . . . . . . . . . . 120
10.10 MOVE Command . . . . . . . . . . . . . . . . . . . . . 124
10.11 REPLY Response to a Command . . . . . . . . . . . . . 127
10.12 SEARCH Command . . . . . . . . . . . . . . . . . . . . 128
10.12.1 Searching for VFREEBUSY . . . . . . . . . . . . . 131
10.13 SET-LOCALE Command . . . . . . . . . . . . . . . . . . 132
10.14 TIMEOUT Command . . . . . . . . . . . . . . . . . . . 134
10.15 Response Codes . . . . . . . . . . . . . . . . . . . . 134
11. Object Registration . . . . . . . . . . . . . . . . . . . 137
11.1 Registration of New and Modified Entities . . . . . . . 137
11.2 Post the item definition . . . . . . . . . . . . . . . . 137
11.3 Allow a comment period . . . . . . . . . . . . . . . . . 137
11.4 Release a new RFC . . . . . . . . . . . . . . . . . . . 137
12. BEEP and CAP . . . . . . . . . . . . . . . . . . . . . . . 138
12.1 BEEP Profile Registration . . . . . . . . . . . . . . . 138
12.2 BEEP Exchange Styles . . . . . . . . . . . . . . . . . . 140
12.3 BEEP connection details . . . . . . . . . . . . . . . . 140
13. IANA Considerations . . . . . . . . . . . . . . . . . . . 143
14. Security Considerations . . . . . . . . . . . . . . . . . 144
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 145
A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 146
B. Bibliography . . . . . . . . . . . . . . . . . . . . . . . . 147
Intellectual Property and Copyright Statements . . . . . . . 149
Royer, et al. Expires February 9, 2006 [Page 4]
Internet-Draft Calendar Access Protocol (CAP) August 2005
1. Introduction
This document specifies how a Calendar CUA interacts with a CS to
manage calendar information. In particular, it specifies how to
query, create, modify, and delete iCalendar components (e.g., events,
to-dos, or daily journal entries). It further specifies how to
search for available busy time information. Synchronization with
CUAs is not covered and believed to be possible using CAP.
CAP is specified as a [BEEP] "profile". As such, many aspects of the
protocol (e.g., authentication and privacy) are provided within
[BEEP]. The protocol data units leverage the standard iCalendar
format [iCAL] to convey calendar related information.
CAP can also be used to store and fetch [iTIP] objects and when those
objects are used in this memo, they mean exactly the same as defined
in [iTIP]. When iCalendar objects are transferred between the CUA
and a CS, some additional properties and parameters may be added and
the CUA is responsible for correctly generating iCalendar objects to
non CAP processes.
The definition of new components, properties, parameter's, and value
types are broken into two parts. The first part summarizes and
defines the new objects. The second part provides the detail and any
ABNF for those objects. The ABNF in CAP as in other iCalendar
specifications is order independent. That is properties in a
component may occur in any order and parameters in any property may
occur in any order.
1.1 Formatting Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this
document are to be interpreted as described in [RFCWORDS].
Calendaring and scheduling roles are referred to in quoted-strings of
text with the first character of each word in upper case. For
example, "Organizer" refers to a role of a "Calendar User" (CU)
within the protocol defined by [iTIP]. Calendar components defined
by [iCAL] are referred to with capitalized, quoted-strings of text.
All iCalendar components should start with the letter "V". For
example, "VEVENT" refers to the event calendar component, "VTODO"
refers to the to-do component and "VJOURNAL" refers to the daily
journal component.
Scheduling methods defined by [iTIP], are referred to with
capitalized, quoted-strings of text. For example, "REPLY" refers to
the method for replying to a "REQUEST".
Royer, et al. Expires February 9, 2006 [Page 5]
Internet-Draft Calendar Access Protocol (CAP) August 2005
CAP commands are referred to by upper-case, quoted-strings of text,
followed by the word "command". For example, "CREATE" command refers
to the command for creating a calendar entry, "SEARCH" command refers
to the command for reading calendar components. CAP Commands are
named using the "CMD" property.
Properties defined by this memo are referred to with capitalized,
quoted-strings of text, followed by the word "property". For
example, "ATTENDEE" property refers to the iCalendar property used to
convey the calendar address that has been invited to a "VEVENT" or
"VTODO" component.
Property parameters defined by this memo are referred to with
capitalized, quoted-strings of text, followed by the word
"parameter". For example, "PARTSTAT" parameter refers to the
iCalendar property parameter used to specify the participation status
of an attendee. Enumerated values defined by this memo are referred
to with capitalized text, either alone or followed by the word
"value".
Object states defined by this memo are referred to with capitalized,
quoted-strings of text, followed by the word "state". For example,
"BOOKED" state refers to an object in the booked state.
Within a query, the different parts are referred to as a "clause" and
its value as "clause value" and the clause name will be in uppercase
enclosed in quotes. Example, The "SELECT" clause or if the "SELECT"
clause value contains ...
In tables, the quoted-string text is specified without quotes in
order to minimize the table length.
1.2 Related Documents
Implementers will need to be familiar with several other memos that,
along with this one, describe the Internet calendaring and scheduling
standards. These documents are:
[iCAL] - (RFC2445) Which specifies the objects, data types,
properties and property parameters used in the protocols, along
with the methods for representing and encoding them.
[iTIP] - (RFC2446) Which specifies an interoperability protocol for
scheduling between different installations.
Royer, et al. Expires February 9, 2006 [Page 6]
Internet-Draft Calendar Access Protocol (CAP) August 2005
[iMIP] - (RFC2447) Which specifies the Internet email binding for
[iTIP].
[GUIDE] - (RFC3283), a guide to implementers and describes the
elements of a calendaring system, how they interact with each
other, how they interact with end users, and how the standards and
protocols are used.
This memo does not attempt to repeat the specification of concepts
and definitions from these other memos. Where possible, references
are made to the memo that provides for the specification of these
concepts and definitions.
1.3 Definitions
BOOKED - An object in the calendar store has one of three conceptual
states. It is in the "UNPROCESSED" state, "BOOKED" state, or
marked for deletion which is the "DELETED" state. How the
implementation stores the state of any object is not a protocol
issues and is not discussed. An object can be said to be booked,
unprocessed, or marked for delete.
1. An "UNPROCESSED" state scheduling object has been stored in
the calendar store but has not been acted on by a CU or CUA.
All scheduled entries are [iTIP] objects. All [iTIP] objects
in the store are not in the "BOOKED" state. To retrieve any
[iTIP] object, simply do a query asking for any objects that
are stored in the "UNPROCESSED" state.
2. A "BOOKED" state entry is stored with the "CREATE" command.
It is an object that has been acted on by a CU or CUA and
there has been a decision to store an object. To retrieve any
booked object, simply do a query asking for any objects that
were stored in the "BOOKED" state.
3. A "DELETED" state entry is created by sending a "DELETE"
command with the "OPTION" parameter value set to "MARK". To
retrieve any deleted object, simply do a query asking for any
objects that were stored in the "DELETED" state. By default
objects marked for delete are not returned. The CUA must
specifically ask for marked for delete objects. You can not
ask for components in the "DELETED" state and in other states
in the same "VQUERY" component, as there would be no way to
distinguish between them in the reply.
Royer, et al. Expires February 9, 2006 [Page 7]
Internet-Draft Calendar Access Protocol (CAP) August 2005
Calendar - A collection of logically related objects or entities
each of which may be associated with a calendar date and possibly
time of day. These entities can include calendar properties or
components. In addition, a calendar might be related to other
calendars with the "RELATED-TO" property. A calendar is
identified by its unique calendar identifier. The [iCAL] defines
the initial calendar properties, calendar components and
properties that make up the contents of a calendar.
Calendar Access Protocol (CAP) - The standard Internet protocol that
permits a CUA to access and manipulate calendars residing on a
Calendar Store. (this memo)
Calendar Access Rights (VCAR) - The mechanism for specifying the CAP
operations ("PERMISSION") that a particular calendar user ("UPN")
is granted or denied permission to perform on a given calendar
object ("SCOPE"). The calendar access rights are specified with a
"VCAR" component. (Section 9.3.)
Calendar Address - Also See Calendar URL - they are one in the same
for CAP addresses. The calendar address can also be the value to
the "ATTENDEE" and "ORGANIZER" properties as defined in [iCAL].
Calendar URL - A calendar URL is a URL defined in this memo that
specifies the address of a CS or Calendar.
Component- Any object that conforms to the iCalendar object format
and that is either defined in an internet draft, registered with
IANA, or is an experimental object that is prefixed with "x-".
Some types of components include calendars, events, to-dos,
journals, alarms, and time zones. A component consists of
properties and possibly other contained components. For example,
an event may contain an alarm component.
Container - This is a generic name for VCALSTORE or VAGENDA.
Properties - An attribute of a particular component. Some
properties are applicable to different types of components. For
example, the "DTSTART" property is applicable to the "VEVENT",
"VTODO", and "VJOURNAL" components. Other components are
applicable only to an individual type of calendar component. For
example, the "TZURL" property may only be applicable to the
"VTIMEZONE" components.
Calendar Identifier (CALID) - A globally unique identifier
associated with a calendar. Calendars reside within a CS. See
Qualified Calendar Identifier and Relative Calendar Identifier.
All CALIDs start with "cap:".
Royer, et al. Expires February 9, 2006 [Page 8]
Internet-Draft Calendar Access Protocol (CAP) August 2005
Calendar Policy - A CAP operational restriction on the access or
manipulation of a calendar. These may be outside of the scope of
the CAP protocol. An example of an implementation or site policy
is, "events MUST BE scheduled in unit intervals of one hour".
Calendar Property - An attribute of a calendar ("VAGENDA"). The
attribute applies to the calendar, as a whole. For example, the
"CALSCALE" property specifies the calendar scale (e.g., the
"GREGORIAN" value) for the all entries within the calendar.
Calendar Store (CS) - The data and service model definition for a
Calendar Store as defined in this memo. This memo does not
specify how the CS is implemented.
Calendar Server - An implementation of a Calendar Store (CS) that
manages one or more calendars.
Calendar Store Identifier (CSID) - The globally unique identifier
for an individual CS. A CSID consists of the host and port
portions of a "Common Internet Scheme Syntax" part of a URL, as
defined by [URL]. The CSID excludes any reference to a specific
calendar. (Section 8.9)
Calendar Store Components - Components maintained in a CS specify a
grouping of calendar store-wide information.
Calendar Store Properties - Properties maintained in a Calendar
Store calendar store-wide information.
Calendar User (CU) - An entity (often biological) that uses a
calendaring system.
Calendar User Agent (CUA) - The client application that a CU
utilizes to access and manipulate a calendar.
CAP Session - An open communication channel between a CUA and a CS.
If the CAP session is authenticated, the CU is "authenticated" and
it is an "authenticated CAP session".
Contained Component / Contained Properties - A component or property
that is contained inside of another component. A "VALARM"
component for example may be contained inside of a "VEVENT"
component. And a "TRIGGER" property could be a contained property
of a "VALARM" component.
Royer, et al. Expires February 9, 2006 [Page 9]
Internet-Draft Calendar Access Protocol (CAP) August 2005
Delegate - A CU (sometimes called the delegatee) who has been
assigned participation in a scheduled component (e.g., VEVENT) by
one of the attendees in the scheduled component (sometimes called
the delegator). An example of a delegate is a team member told to
go to a particular meeting in place of another Attendee who is
unable to attend.
Designate - A CU who is authorized to act on behalf of another CU.
An example of a designate is an assistant.
Experimental - The CUA and CS may implement experimental extensions
to the protocol. They also might have experimental components,
properties, and parameters. These extensions MUST start with "x-"
(or "X-") and should include a vendor prefix (such as
"x-myvendor-"). There is no guarantee that these experimental
extensions will interoperate with other implementations. There is
no guarantee that they will not interact in unpredictable ways
with other vendor experimental extensions. There is no guarantee
that the same specific experimental extension is not used my
multiple vendors in incompatible ways. Implementations should
limit sending those extensions to other implementations.
Object - A generic name for any component, property, parameter, or
value type to be used in iCalendar.
Overlapped Booking - A policy which indicates whether or not
components with a "TRANSP" property not set to "TRANSPARENT-
NOCONFLICT" or "OPAQUE-NOCONFLICT" value can overlap one another.
When the policy is applied to a calendar it indicates whether or
not the time span of any component (VEVENT, VTODO, ...) in the
calendar can overlap the time span of any other component in the
same calendar. When applied to an individual object, it indicates
whether or not any other component's time span can overlap that
individual component. If the CS does not allow overlapped
booking, then the CS is unwilling to allow any overlapped bookings
within any calendar or entry in the CS.
Owner - One or more CUs or UGs that are listed in the "OWNER"
property in a calendar. There can be more than one owner.
Qualified Calendar Identifier (Qualified CALID) - A CALID in which
both the scheme and CSID of the CAP URI are present.
Realm - A collection of calendar user accounts, identified by a
string. The name of the Realm is only used in UPNs. In order to
avoid namespace conflict, the Realm SHOULD be postfixed with an
appropriate DNS domain name. (e.g., the foobar Realm could be
called foobar.example.com).
Royer, et al. Expires February 9, 2006 [Page 10]
Internet-Draft Calendar Access Protocol (CAP) August 2005
Relative Calendar Identifier (Relative CALID) - An identifier for an
individual calendar in a calendar store. It MUST BE unique within
a calendar store. A Relative CALID consists of the "URL path" of
the "Common Internet Scheme Syntax" portion of a URL, as defined
by [URI] and [URLGUIDE].
Session Identity - A UPN associated with a CAP session. A session
gains an identity after successful authentication. The identity
is used in combination with VCAR to determine access to data in
the CS.
User Group (UG) - A collection of Calendar Users and/or User Groups.
These groups are expanded by the CS and may reside either locally
or in an external database or directory. The group membership may
be fixed or dynamic over time.
Username - A name which denotes a Calendar User within a Realm.
This is part of a UPN.
User Principal Name (UPN) - A unique identifier that denotes a CU or
a group of CU. (Section 6.1.2)
Royer, et al. Expires February 9, 2006 [Page 11]
Internet-Draft Calendar Access Protocol (CAP) August 2005
2. Additions to iCalendar
Several new components, properties, parameters, and value types are
added in CAP. This section summarizes those new objects.
This memo extends the properties that can go into 'calprops' as
defined in [iCAL] section 4.6 page 51 to allow [iTIP] objects
transmitted between a CAP aware CUA and the CS to contain the
"TARGET" and "CMD" properties. This memo also adds to the [iCAL]
ABNF to allow IANA and experimental extensions. This memo does not
address how a CUA transmits [iTIP] or [iMIP] objects to non CAP
programs. (What follows is ABNF as described in [ABNF])
calprops = 2*(
; 'prodid' and 'version' are both REQUIRED,
; but MUST NOT occur more than once.
;
prodid /version /
;
; These are optional, but MUST NOT occur
; more than once.
;
calscale /
method /
cmd /
;
; Target is optional, and may occur more
; than once.
;
target / other-props )
;
other-props = *(x-prop) *(iana-prop) *(other-props)
;
iana-prop = ; Any property registered by IANA directly or
; included in an RFC that may be applied to
; the component and within the rules published.
;
x-prop = ; As defined in [iCAL]
;
methodp = ; As defined in [iCAL]
;
prodid = ; As defined in [iCAL]
;
calscale = ; As defined in [iCAL]
;
Royer, et al. Expires February 9, 2006 [Page 12]
Internet-Draft Calendar Access Protocol (CAP) August 2005
Another change is that the 'component' part of the 'icalbody' ABNF as
described in [iCAL] section 4.6 is optional when sending a command as
shown in the following updated ABNF:
icalbody = calprops component
; If the "VCALENDAR" component contains the "CMD"
; property then the 'component' is optional:
;
/ calprops ; Which MUST include a "CMD" property
;
component = ; As defined in [iCAL]
In addition a problem exists with the control of "VALARM" components
and their "TRIGGER" properties. A CU may wish to set their own alarm
(local alarms) on components. These local alarms are not to be
forwarded to other CUs, CUAs, or CSs as are the "SEQUENCE" property
and the "ENABLE" parameter. So for the protocol between a CUA and a
CS, the following changes apply to the CAP protocol from [iCAL]
section 4.6.6 page 67:
Royer, et al. Expires February 9, 2006 [Page 13]
Internet-Draft Calendar Access Protocol (CAP) August 2005
alarmc = "BEGIN" ":" "VALARM" CRLF
alarm-seq
other-props
(audioprop / dispprop / emailprop / procprop)
"END" ":" "VALARM" CRLF
;
emailprop = ; As definded in [iCAL]
;
procprop = ; As definded in [iCAL]
;
dispprop = ; As definded in [iCAL]
;
audioprop = ; As definded in [iCAL]
;
alarm-seq = "SEQUENCE" alarmseqparams ":" posint0 CRLF
;
alarmseqparams = other-params [";" local-param] other-params
;
; Where DIGIT is defined in [iCAL]
;
posint0 = 1*DIGIT
posint1 = posintfirst 1*DIGIT
;
; A number starting with 1 through 9.
;
posintfirst = %x31-39
;
other-params = *(";" xparam) *(";" iana-params) *(";" other-params)
;
iana-params = ; Any parameter registered by IANA directly or
; included in an RFC that may be applied to
; the property and within the rules published.
;
xparam ; As defined in [iCAL]
;
The CUA adds a "SEQUENCE" property to each "VALARM" component as it
books the component. This property along with the "LOCAL" and
"ENABLE" parameters allow the CUA to uniquely identify any VALARM in
any component. The CUA should remove those before forwarding to non
CAP aware CUAs.
In addition, if a CUA wished to ignore a "TRIGGER" property in a
"VALARM" component that was supplied to it by the "Organizer", the
CUA needs a common way to tag that trigger as disabled. So the
following is a modification to [iCAL] section 4.8.6.3 page 127:
Royer, et al. Expires February 9, 2006 [Page 14]
Internet-Draft Calendar Access Protocol (CAP) August 2005
trigger = "TRIGGER" 1*(";" enable-param) (trigrel / trigabs)
;
trigrel = ; As defined in [iCAL]
;
trigabs = ; As defined in [iCAL]
Section 7.2 and Section 7.5.
2.1 New Value Types (summary)
UPN The UPN value type is text value type restricted to only UPN
values. (Section 6.1.2)
UPN-FILTER Like the UPN value type, but also includes filter rules
that allow wildcards. (Section 6.1.3)
CALQUERY The "CAL-QUERY" value type is a query syntax that is used by
the CUA to specify the rules that apply to a CAP command.
(Section 6.1.1)
2.1.1 New Parameters (summary)
ACTION - The "ACTION" parameter informs the endpoint if it should
abort or ask to continue on timeout. (Section 7.1).
ENABLE - The "ENABLE" parameter in CAP is used to tag a property in
a component as disabled or enabled. (Section 7.2).
ID - The "ID" parameter specifies a unique identifier to be used for
any outstanding commands.
LATENCY - The "LATENCY" parameter supplies the timeout value for
command completion to the other endpoint. (Section 7.4).
LOCAL - The "LOCAL" parameter in CAP is used to tag a property in a
component to signify that the component is local or to be
distributed. (Section 7.5).
LOCALIZE - The "LOCALIZE" parameter specifies the locale to be used
in error and warning messages.
OPTIONS - The "OPTIONS" parameter passes optional information for
the command being sent.
Royer, et al. Expires February 9, 2006 [Page 15]
Internet-Draft Calendar Access Protocol (CAP) August 2005
2.1.2 New or Updated Properties (summary)
ALLOW-CONFLICT - Some entries in a calendar might not be valid if
other entries were allowed to overlap the same time span.
(Section 8.1)
ATT-COUNTER - When storing a "METHOD" property with the "COUNTER"
method, there needs to be a way to remember the "ATTENDEE" value
that sent the COUNTER. (Section 8.2)
CAP-VERSION - The version of CAP the implementation supports.
(Section 8.5)
CAR-LEVEL - The level of calendar access level supported.
(Section 8.7)
COMPONENTS - The list of components supported. (Section 8.8)
CSID - The Calendar Store IDentifier (CSID) uniquely identifies a
CAP server. (Section 8.9)
CALID - Each calendar within a CS needs to be uniquely identifiable.
The "CALID" property identifies a unique calendar within a CS. It
can be a full CALID or a relative CALID. (Section 8.3)
CALMASTER - The "CALMASTER" property specifies the contact
information for the CS. (Section 8.4)
CARID - Access rights can be saved and fetched by unique ID - the
"CARID" property. (Section 8.6)
CMD - The CAP commands, as well as replies are transmitted using the
"CMD" property. (Section 10.1)
DECREED - Some access rights are not changeable by the CUA. When
that is the case, the "DECREED" property value in the "VCAR"
component will be "TRUE". (Section 8.10)
DEFAULT-CHARSET - The list of charsets supported by the CS. The
first entry is the default for the CS. (Section 8.11)
DEFAULT-LOCALE - The list of locales supported by the CS. The first
entry in the list is the default locale. (Section 8.12)
DEFAULT-TZID - This is the list of known timezones supported. The
first entry is the default. (Section 8.13)
Royer, et al. Expires February 9, 2006 [Page 16]
Internet-Draft Calendar Access Protocol (CAP) August 2005
DEFAULT-VCARS - A list of the "CARID" properties that will be used
to create new calendars. (Section 8.14)
DENY - The UPNs listed in the "DENY" property of a "VCAR" component
will denied access as described in the "VRIGHT" component.
(Section 8.15)
EXPAND - This property tells the CS if the query reply should expand
components into multiple instances. The default is "FALSE" and is
ignored for CSs that can not expand recurrence rules.
(Section 8.16)
GRANT - The UPNs listed in the "GRANT" property of a "VCAR"
component will allowed access as described in the "VRIGHT"
component. (Section 8.17)
ITIP-VERSION - The version of [iTIP] supported. (Section 8.18)
MAXDATE - The maximum date supported by the CS. (Section 8.20)
MAX-COMP-SIZE - The largest component size allowed in the
implementation including attachments in octets. (Section 8.19)
MINDATE - The minimum date supported by the CS. (Section 8.21)
MULTIPART - Passed in the capability messages to indicate which MIME
multipart types the sender supports. (Section 8.22)
NAME - The "NAME" property is used to add locale specific
descriptions into components. (Section 8.23)
OWNER - Each calendar has at least one "OWNER" property. (xref
target="OWNER"/>) Related to the "CAL-OWNERS()" (Section 6.1.1.1)
query clause.
PERMISSION - This property specifies the permission being granted or
denied. Examples are the "SEARCH" and "MODIFY" values.
(Section 8.25)
QUERY - Used to hold the CAL-QUERY (Section 8.26) for the component.
QUERYID - A unique id for a stored query. (Section 8.27)
QUERY-LEVEL - The level of the query language supported.
(Section 8.28)
Royer, et al. Expires February 9, 2006 [Page 17]
Internet-Draft Calendar Access Protocol (CAP) August 2005
RECUR-ACCEPTED - If the implementation support recurrence rules.
(Section 8.29)
RECUR-EXPAND - If the implementation support expanding recurrence
rules. (Section 8.31)
RECUR-LIMIT - Any maximum limit on the number of instances the
implementation will expand recurring objects. (Section 8.30)
REQUEST-STATUS - The [iCAL] "REQUEST-STATUS" property is extended to
include new error numbers.
RESTRICTION - In the final check when granting calendar access
requests, the CS test the results to the value of the
"RESTRICTION" property in the corresponding "VRIGHT" component to
determine if the access meets that restriction. (Section 8.32)
SCOPE - The "SCOPE" property is used in "VRIGHT"s component to
select the subset of data that may be acted upon when checking
access rights. (Section 8.33)
SEQUENCE - When the "SEQUENCE" property is used in a "VALARM"
component it uniquely identifies the instances of the "VALARM"
within that component.
STORES-EXPANDED - Specifies if the implementation stores recurring
object expanded or not. (Section 8.34)
TARGET - The new "VCALENDAR" component property "TARGET"
(Section 8.35) is used to specify which calendar(s) will be the
subject of the CAP command.
TRANSP - This is a modification the [iCAL] "TRANSP" property and it
allows more values. The new values are related to conflict
control. (Section 8.36)
2.1.3 New Components (summary)
VAGENDA - CAP allows the fetching and storing of the entire contents
of a calendar. The "VCALENDAR" component is not sufficient to
encapsulate all of the needed data that describes a calendar. The
"VAGENDA" component is the encapsulating object for an entire
calendar. (Section 9.1)
Royer, et al. Expires February 9, 2006 [Page 18]
Internet-Draft Calendar Access Protocol (CAP) August 2005
VCALSTORE - Each CS contains one or more calendars (VAGENDAs), the
"VCALSTORE" component is the encapsulating object that can hold
all of the "VAGENDA" components along with any components and
properties that are unique to the store level. (Section 9.2)
VCAR - Calendar Access Rights are specified and encapsulated in the
new iCalendar "VCAR" component. The "VCAR" component holds some
new properties and at least one "VRIGHT" component. (Section 9.3)
VRIGHT - This component encapsulates a set of instructions to the CS
that define the rights or restrictions needed. (Section 9.4)
VREPLY - This component encapsulates a set of data that can consist
of an arbitrary amounts of properties and components. Its
contents is dependent on the command that was issued.
(Section 9.5)
VQUERY - The search operation makes use of a new component, called
"VQUERY" and a new value type "CAL-QUERY" (Section 6.1.1). The
"VQUERY" component is used to fetch objects from the CS.
(Section 9.6)
2.2 Relationship of RFC-2446 (ITIP) and CAP
[iTIP] describes scheduling methods which result in indirect
manipulation of components. In CAP, the "CREATE" command is used to
deposit entities into the store. Other CAP commands such as
"DELETE", "MODIFY" and "MOVE" command values provide direct
manipulation of components. In the CAP calendar store model,
scheduling messages are conceptually kept separate from other
components by their state.
All scheduling operations are as defined in [iTIP]. This memo makes
no changes to any of the methods or procedures described in [iTIP].
In this memo referring to the presence of the "METHOD" property in an
object is the same as saying an [iTIP] object.
A CUA may create a "BOOKED" state object by depositing an iCalendar
object into the store. This is done by depositing an object that
does not have a "METHOD" property. The CS then knows to set the
state of the object to the "BOOKED" state. If the object has a
"METHOD" property then the object is stored in the "UNPROCESSED"
state.
If existing "UNPROCESSED" state objects exist in the CS for the same
UID (UID is defined in [iCAL]) then a CUA may wish to consolidate the
objects in to one "BOOKED" state object. The CUA would fetch the
Royer, et al. Expires February 9, 2006 [Page 19]
Internet-Draft Calendar Access Protocol (CAP) August 2005
"UNPROCESSED" state objects for that UID and process them in the CUA
as described in [iTIP]. Then if the CUA wished to book the UID, the
CUA would issue a "CREATE" command to create the new "BOOKED" state
object in the CS, followed by a "DELETE" command to remove any
related old [iTIP] objects from the CS. And it might also involve
having the CUA send some [iMIP] objects or contacting other CSs and
performing CAP operations on those CSs.
The CUA could also decide not to book the object. In which case the
"UNPROCESSED" state objects could be removed from the CS or the CUA
could set those object to the marked for delete state. The CUA could
also ignore objects for later processing.
The marked for delete state is used to keep the object around so that
the CUA can process duplicate requests automatically. If a duplicate
[iTIP] object is deposited into the CS and there exists identical
marked for delete objects, then a CUA acting on behalf of the "OWNER"
can silently drop those duplicate entries.
Another purpose for the marked for delete state is so that when a CU
decides they do not wish to have the object show in their calendar,
the CUA can book the object; changing the "PARTSTAT" parameter to
"DECLINED" in the "ATTENDEE" property that corresponds to their UPN.
Then perform an [iTIP] processing such as sending back a decline.
Then mark that object as marked for delete. Their CUA might be
configurable to automatically drop any updates for that object
knowing the CU has already declined.
When synchronizing with multiple CUAs, the marked for delete state
could be used to inform the synchronization process that an object is
to be deleted. How synchronization is done is not specified in this
memo.
Several "UNPROCESSED" state entries can be in the CS for the same
UID. However once consolidated, then only one object exists in the
CS and that is the booked object. The others MUST BE removed, or
have their state changed to "DELETED".
There MUST NOT BE more than one "BOOKED" state object in a calendar
for the same "UID". The "ADD" method value may create multiple
objects all in the "BOOKED" state for the same UID, however for the
purpose of this memo, they are the same object that simply have
multiple "VCALENDAR" components.
For example, if you were on vacation, you could have received a
"REQUEST" method to attend a meeting and several updates to that
meeting. Your CUA would have to issue "SEARCH" commands to find them
in the CS using CAP, process them, determine what the final state of
Royer, et al. Expires February 9, 2006 [Page 20]
Internet-Draft Calendar Access Protocol (CAP) August 2005
the object from a possible combination of user input and programmed
logic. Then the CUA would instruct the CS to create a new booked
object from the consolidated results. Finally, the CUA could do a
"DELETE" command to remove the related "UNPROCESSED" state objects.
See [iTIP] for details on resolving multiple [iTIP] scheduling
entries.
Royer, et al. Expires February 9, 2006 [Page 21]
Internet-Draft Calendar Access Protocol (CAP) August 2005
3. CAP Design
3.1 System Model
The system model describes the high level components of a calendar
system and how they interact with each other.
CAP is used by a CUA to send commands to and receive responses from a
CS.
The CUA prepares a [MIME] encapsulated message, sends it to the CS,
and receives a [MIME] encapsulated response. The calendaring related
information within these messages are represented by iCalendar
objects. In addition the "GET-CAPABILITY" command can be sent from
the CS to the CUA.
There are two distinct protocols in operation to accomplish this
exchange. [BEEP] is the transport protocol used to move these
encapsulations between a CUA and a CS. CAP's [BEEP] profile defines
the application protocol where the content and semantics of the
messages sent between the CUA and the CS are specified.
3.2 Calendar Store Object Model
[iCAL] describes components such as events, todos, alarms, and
timezones. [CAP] requires additional object infrastructure. In
particular, detailed definitions of the containers for events and
todos (calendars), access control objects, and a query language.
The conceptual model for a calendar store is shown below. The
calendar store (VCALSTORE - Section 9.2) contains "VCAR"s, "VQUERY"s,
"VTIMEZONE"s, "VAGENDA"s and calendar store properties.
Calendars (VAGENDAs) contain "VEVENT"s, "VTODO"s, "VJOURNAL"s,
"VCAR"s, "VTIMEZONE"s, "VFREEBUSY", "VQUERY"s and calendar
properties.
The component "VCALSTORE" is used to denote the a root of the
calendar store and contains all of the calendars.
Royer, et al. Expires February 9, 2006 [Page 22]
Internet-Draft Calendar Access Protocol (CAP) August 2005
Calendar Store
VCALSTORE
|
+-- properties
+-- VCARs
+-- VQUERYs
+-- VTIMEZONEs
+-- VAGENDA
| |
| +--properties
| +--VEVENTs
| | |
| | +--VALARMs
| +--VTODOs
| | |
| | +--VALARMs
| +--VJOURNALs
| +--VCARs
| +--VTIMEZONEs
| +--VQUERYs
| +--VFREEBUSYs
| |
| | ...
.
.
+-- VAGENDA
. .
. .
. .
Calendars within a Calendar Store are identified by their unique
Relative CALID.
3.3 Protocol Model
CAP uses [BEEP] as the transport and authentication protocol.
The initial charset MUST BE UTF-8 for the session in an unknown
locale. If the CS supplied the [BEEP] 'localize' attribute in the
[BEEP] 'greeting' then the CUA may tell the CS to switch locales for
the session by issuing the "SET-LOCALE" CAP command and supplying one
of the locales supplied by the [BEEP] 'localize' attribute. If
supplied the first locale in the [BEEP] 'localize' attribute is the
default locale of the CS. The locale is switched only after a
successful reply.
Royer, et al. Expires February 9, 2006 [Page 23]
Internet-Draft Calendar Access Protocol (CAP) August 2005
The "DEFAULT-CHARSET" property of the CS contains the list of
charsets supported by the CS with the first value being the default
for new calendars. If the CUA wishes to switch to one of those
charsets for the session, the CUA issues the "SET-LOCALE" command.
The CUA would have to first perform a "GET-CAPABILITY" command on the
CS to get the list of charsets supported by the CS. The charset is
switched only after a successful reply.
The CUA may switch locales and charsets as needed. There is no
requirement that a CS support multiple locales or charsets.
3.3.1 Use of BEEP, MIME and iCalendar
CAP uses the [BEEP] application protocol over TCP. (refer to [BEEP]
and [BEEPTCP] for more information). The default port that the CS
listens for connections is on user port 1026.
The [BEEP] data exchanged in CAP is a iCalendar MIME content that
fully conforms to [iCAL] iCalendar format.
This example tells the CS to generate and return 10 UIDs to be used
by the CUA. Note throughout this memo, 'C:' refers to what the CUA
sends, 'S:' refers to what the CS sends, 'I:' refers to what the
initiator sends, and 'L:' refers to what the listener sends. Where
initiator and listener are used as defined in [BEEP].
C: MSG 1 2 . 432 62
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: PRODID:-//someone's prodid
C: CMD;ID=unique-per-cua-123;OPTIONS=10:GENERATE-UID
C: END:VCALENDAR
NOTE: The following examples will not include the [BEEP] header and
footer information. Only the iCalendar objects that are sent between
the CUA and CS will be shown as the [BEEP] payload boundaries are
independent of CAP.
The commands listed below are used to manipulate or access the data
on the calendar store:
Royer, et al. Expires February 9, 2006 [Page 24]
Internet-Draft Calendar Access Protocol (CAP) August 2005
ABORT - Sent to halt the processing of some of the commands.
(Section 10.2)
CONTINUE - Sent to continue processing a command that has had its
specified timeout time reached. (Section 10.3)
CREATE - Create a new object on the CS. Initiated by the CUA only.
(Section 10.4)
SET-LOCALE - Tell the CS to use any named locale and charset
supplied. Initiated by the CUA only. (Section 10.13)
DELETE - Delete objects from the CS. Initiated by the CUA only.
Can also be used to mark an object for deletion. (Section 10.5)
GENERATE-UID - Generate one or more unique ids. Initiated by the
CUA only. (Section 10.6)
GET-CAPABILITY - Query the capabilities the other end point of the
session. (Section 10.7)
IDENTIFY - Set a new identity for the session. Initiated by the CUA
only. (Section 10.8)
MODIFY - Modify components. Initiated by the CUA only.
(Section 10.9)
MOVE - Move components to another container. Initiated by the CUA
only. (Section 10.10)
REPLY - When replying to a command, the "CMD" value will be set to
"REPLY" so that it will not be confused with a new command.
(Section 10.11)
SEARCH - Search for components. Initiated by the CUA only.
(Section 10.12)
TIMEOUT - Sent when a specified amount of time has lapsed and a
command has not finished. (Section 10.14)
Royer, et al. Expires February 9, 2006 [Page 25]
Internet-Draft Calendar Access Protocol (CAP) August 2005
4. Security Model
The [BEEP] transport performs all session authentication.
4.1 Calendar User and UPNs
A CU is an entity that can be authenticated. It is represented in
CAP as a UPN, which is a key part of access rights. The UPN
representation is independent of the authentication mechanism used
during a particular CUA/CS interaction. This is because UPNs are
used within VCARs. If the UPN were dependent on the authentication
mechanism, a VCAR could not be consistently evaluated. A CU may use
one mechanism while using one CUA but the same CU may use a different
authentication mechanism when using a different CUA, or while
connecting from a different location.
The user may also have multiple UPNs for various purposes.
Note that the immutability of the user's UPN may be achieved by using
SASL's authorization identity feature. (The transmitted
authorization identity may be different than the identity in the
client's authentication credentials.) [SASL, section 3]. This also
permits a CU to authenticate using their own credentials, yet request
the access privileges of the identity for which they are proxying
SASL. Also, the form of authentication identity supplied by a
service like TLS may not correspond to the UPNs used to express a
server's access rights, requiring a server specific mapping to be
done. The method by which a server determines a UPN, based on the
authentication credentials supplied by a client, is implementation
specific. See [BEEP] for authentication details; [BEEP] relies on
SASL.
4.1.1 UPNs and Certificates
When using X.509 certificates for purposes of CAP authentication, the
UPN should appear in the certificate. Unfortunately there is no
single correct guideline for which field should contain the UPN.
From RFC-2459, section 4.1.2.6 (Subject):
If subject naming information is present only in the subjectAlt-
Name extension (e.g., a key bound only to an email address or
URI), then the subject name MUST be an empty sequence and the
subjectAltName extension MUST BE critical.
Implementations of this specification MAY use these comparison
rules to process unfamiliar attribute types (i.e., for name
chaining). This allows implementations to process certificates
Royer, et al. Expires February 9, 2006 [Page 26]
Internet-Draft Calendar Access Protocol (CAP) August 2005
with unfamiliar attributes in the subject name.
In addition, legacy implementations exist where an RFC 2822 name
is embedded in the subject distinguished name as an EmailAddress
attribute. The attribute value for EmailAddress is of type
IA5String to permit inclusion of the character '@', which is not
part of the PrintableString character set. EmailAddress attribute
values are not case sensitive (e.g.,
"fanfeedback@redsox.example.com" is the same as "FANFEEDBACK@
REDSOX.EXAMPLE.COM").
Conforming implementations generating new certificates with
electronic mail addresses MUST use the rfc822Name in the subject
alternative name field (see sec. 4.2.1.7 of [X509CRL]) to describe
such identities. Simultaneous inclusion of the EmailAddress
attribute in the subject distinguished name to support legacy
implementations is deprecated but permitted.
Since no single method of including the UPN in the certificate will
work in all cases, CAP implementations MUST support the ability to
configure what the mapping will be by the CS administrator.
Implementations MAY support multiple mapping definitions, for
example, the UPN may be found in either the subject alternative name
field, or the UPN may be embedded in the subject distinguished name
as an EmailAddress attribute.
Note: If a CS or CUA is validating data received via [iMIP], if the
"ORGANIZER" or "ATTENDEE" properties said (e.g.) "ATTENDEE;CN=Joe
Random User:MAILTO:juser@example.com" then the email address should
be checked against the UPN. This is so the "ATTENDEE" property
cannot be changed to something misleading like "ATTENDEE;CN=Joe
Rictus User:MAILTO:jrictus@example.com" and have it pass validation.
Note that it is the email addresses that miscompare, the CN
miscompare is irrelevant.
4.1.2 Anonymous Users and Authentication
Anonymous access is often desirable. For example an organization may
publish calendar information that does not require any access control
for viewing or login. Conversely, a user may wish to view
unrestricted calendar information without revealing their identity.
4.1.3 User Groups
A User Group is used to represent a collection of CUs or other UGs
that can be referenced in VCARs. A UG is represented in CAP as a
UPN. The CUA cannot distinguish between a UPN that represents a CU
or a UG.
Royer, et al. Expires February 9, 2006 [Page 27]
Internet-Draft Calendar Access Protocol (CAP) August 2005
UGs are expanded as necessary by the CS. The CS MAY expand a UG
(including nested UGs) to obtain a list of unique CUs. Duplicate
UPNs are filtered during expansion.
How the UG expansion is maintained across commands is implementation
specific. A UG may reference a static list of members, or it may
represent a dynamic list. Operations SHOULD recognize changes to UG
membership.
CAP does not define commands or methods for managing UGs.
4.2 Access Rights
Access rights are used to grant or deny access to calendars,
components, properties, and parameters in a CS to a CU. CAP defines
a new component type called a Calendar Access Right (VCAR).
Specifically, a "VCAR" component grants, or denies, UPNs the right to
search and write components, properties, and parameters on calendars
within a CS.
The "VCAR" component model does not put any restriction on the
sequence in which the object and access rights are created. That is,
an object associated with a particular "VCAR" component might be
created before or after the actual "VCAR" component is defined. In
addition, the "VCAR" and "VEVENT" components might be created in the
same iCalendar object and passed together in a single object.
All rights MUST BE denied unless specifically granted.
If two rights specified in "VCAR" components are in conflict, the
right that denies access always takes precedence over the right that
grants access. Any attempt to create a "VCAR" component that
conflicts with a "VCAR" components with a "DECREED" property set to
the "TRUE" value must fail.
4.2.1 Access Control and NOCONFLICT
The "TRANSP" property can take on values "TRANSPARENT-NOCONFLICT" and
"OPAQUE-NOCONFLICT" that prohibit other components from overlapping
it. This setting overrides access. The "ALLOW-CONFLICT" CS,
Calendar or component setting may also prevent overlap, returning an
error code "6.3".
4.2.2 Predefined VCARs
Predefined calendar access CARIDs that MUST BE implemented are:
Royer, et al. Expires February 9, 2006 [Page 28]
Internet-Draft Calendar Access Protocol (CAP) August 2005
CARID:READBUSYTIMEINFO - Specifies the "GRANT" and "DENY" rules that
allow UPNs to search "VFREEBUSY" components. An example
definition for this VCAR is:
BEGIN:VCAR
CARID:READBUSYTIMEINFO
BEGIN:VRIGHT
GRANT:*
PERMISSION:SEARCH
SCOPE:SELECT * FROM VFREEBUSY WHERE STATE() = 'BOOKED'
END:VRIGHT
END:VCAR
CARID:REQUESTONLY - Specifies the "GRANT" and "DENY" rules to UPNs
other than the owner of the calendar the ability to write new
objects with the property "METHOD" property set to the "REQUEST"
value. This CARID allows the owner to specify which UPNs are
allowed to make scheduling requests. An example definition for
this VCAR is:
BEGIN:VCAR
CARID:REQUESTONLY
BEGIN:VRIGHT
GRANT:NON CAL-OWNERS()
PERMISSION:CREATE
RESTRICTION:SELECT VEVENT FROM VAGENDA WHERE METHOD = 'REQUEST'
RESTRICTION:SELECT VTODO FROM VAGENDA WHERE METHOD = 'REQUEST'
RESTRICTION:SELECT VJOURNAL FROM VAGENDA WHERE METHOD = 'REQUEST'
END:VRIGHT
END:VCAR
CARID:UPDATEPARTSTATUS - Grants to authenticated users the right to
modify the instances of the "ATTENDEE" property set to one of
their calendar addresses in any components for any booked
component containing an "ATTENDEE" property. This allows (or
denies) a CU the ability to update their own participation status
in a calendar where they might not otherwise have "MODIFY" command
access. They are not allowed to change the "ATTENDEE" property
value. An example definition for this VCAR is (This example only
affects the "VEVENT" components):
Royer, et al. Expires February 9, 2006 [Page 29]
Internet-Draft Calendar Access Protocol (CAP) August 2005
BEGIN:VCAR
CARID:UPDATEPARTSTATUS
BEGIN:VRIGHT
GRANT:*
PERMISSION:MODIFY
SCOPE:SELECT ATTENDEE FROM VEVENT
WHERE ATTENDEE = SELF()
AND ORGANIZER = CURRENT-TARGET()
AND STATE() = 'BOOKED'
RESTRICTION:SELECT * FROM VEVENT
WHERE ATTENDEE = SELF()
END:VRIGHT
END:VCAR
CARID:DEFAULTOWNER - Grants to any owner the permission they have
for the target. An example definition for this VCAR is:
BEGIN:VCAR
CARID:DEFAULTOWNER
BEGIN:VRIGHT
GRANT:CAL-OWNERS()
PERMISSION:*
SCOPE:SELECT * FROM VAGENDA
END:VRIGHT
END:VCAR
4.2.3 Decreed VCARs
A CS MAY choose to implement and allow persistent immutable VCARs
that may be configured by the CS administrator. A reply from the CS
may dynamically create "VCAR" components that are decreed depending
on the implementation. To the CUA any "VCAR" component with the
"DECREED" property set to "TRUE" can not be changed by the currently
authenticated UPN, and depending on the implementation and other
"VCAR" components; might not be able to be changed by any UPN using
CAP, and never when the CUA gets a "DECREED:TRUE" VCAR.
When a user attempts to modify or override a decreed "VCAR" component
rules an error will be returned indicating that the user has
Royer, et al. Expires February 9, 2006 [Page 30]
Internet-Draft Calendar Access Protocol (CAP) August 2005
insufficient authorization to perform the operation. The reply to
the CUA MUST BE the same as if a non-decreed VCAR caused the failure.
The CAP protocol does not define the semantics used to initially
create a decreed VCAR. This administrative task is outside the scope
of the CAP protocol.
For example; an implementation or a CS administrator may wish to
define a VCAR that will always allow the calendar owners to have full
access to their own calendars.
Decreed "VCAR" components MUST BE readable by the calendar owner in
standard "VCAR" component format.
4.3 CAP Session Identity
A [BEEP] session has an associated set of authentication credentials,
from which is derived a UPN. This UPN is the identity of the CAP
session, and is used to determine access rights for the session.
The CUA may change the identity of a CAP session by calling the
"IDENTIFY" command. The CS only permits the operation if the
session's authentication credentials are good for the requested
identity. The method of checking this permission is implementation
dependent, but may be thought of as a mapping from authentication
credentials to UPNs. The "IDENTIFY" command allows a single set of
authentication credentials to choose from multiple identities, and
allows multiple sets of authentication credentials to assume the same
identity.
For anonymous access the identity of the session is "@". A UPN with
a null Username and null Realm is anonymous. A UPN with a null
Username, but non-null Realm, such as "@example.com" may be used to
mean any identity from that Realm, which is useful to grant access
rights to all users in a given Realm. A UPN with a non-null Username
and null Realm, such as "bob@" could be a security risk and MUST NOT
be used.
As the UPN includes Realm information it may be used to govern
calendar store access rights across Realms. However, governing
access rights across Realms is only useful if login access is
available. This could be done through a trusted server relationship
or a temporary account. Note that trusted server relationships are
outside the scope of [CAP].
The "IDENTIFY" command also provides for a weak group implementation.
By allowing multiple sets of authentication credentials belonging to
different users to identify as the same UPN, that UPN essentially
Royer, et al. Expires February 9, 2006 [Page 31]
Internet-Draft Calendar Access Protocol (CAP) August 2005
identifies a group of people, and may be used for group calendar
ownership, or the granting of access rights to a group.
Royer, et al. Expires February 9, 2006 [Page 32]
Internet-Draft Calendar Access Protocol (CAP) August 2005
5. CAP URL and Calendar Address
The CAP URL scheme is used to designate calendar stores and calendars
accessible using the CAP protocol.
The CAP URL scheme conform to the generic URL syntax, defined in RFC
2396, and follows the Guidelines for URL Schemes, set forth in RFC
2718.
A CAP URL begins with the protocol prefix "cap" and is defined by the
following grammar.
capurl = "cap://" csidpart [ "/" relcalid ]
;
csidpart = hostport ; As defined in Section 3.2.2 of RFC 2396
;
relcalid = *uric ; As defined in Section 2 of RFC 2396
A 'relcalid' is an identifier that uniquely identifies a calendar on
a particular calendar store. There is no implied structure in a
Relative CALID (relcalid). It may refer to the calendar of a user or
of a resource such as a conference room. It MUST BE unique within
the calendar store.
Examples:
cap://cal.example.com
cap://cal.example.com/Company/Holidays
cap://cal.example.com/abcd1234Usr
A 'relcalid' is permitted and is resolved according to the rules
defined in Section 5 of RFC 2396.
Examples of valid relative CAP URLs:
opqaueXzz123String
UserName/Personal
A Calendar addresses can be described as qualified or relative CAP
URLs.
For a user currently authenticated to the CS on cal.example.com,
Royer, et al. Expires February 9, 2006 [Page 33]
Internet-Draft Calendar Access Protocol (CAP) August 2005
these two example calendar addresses refer to the same calendar:
cap://cal.example.com/abcd1234USR
abcd1234USR
Royer, et al. Expires February 9, 2006 [Page 34]
Internet-Draft Calendar Access Protocol (CAP) August 2005
6. New Value Types
The following sections contains new components, properties,
parameters, and value definitions.
The purpose of these is to extend the iCalendar objects in a
compatible way so that existing iCalendar "VERSION" property "2.0"
value parsers can still parse the objects without modification.
6.1 Property Value Data Types
6.1.1 CAL-QUERY Value Type
Subject: Registration of text/calendar MIME value type CAL-QUERY
Value Name: CAL-QUERY
Value Type Purpose: This value type is used to identify values and
contains query statements targeted at locating those values.
This is based on [SQL92] and [SQLCOM].
1. For the purpose of a query, all components should be handled as
tables, and the properties of those components, should be handled
as columns.
2. All VAGENDAs and CSs look like tables for the purpose of a QUERY.
And all of their properties look like columns in those tables.
3. You CAN NOT do any cross component-type joins. And that means
you can ONLY have one component, OR one "VAGENDA" component OR
one "VCALSTORE" component in the "FROM" clause.
4. Everything in the "SELECT" clause and "WHERE" clauses in MUST BE
from the same component type, or "VAGENDA" component OR
"VCALSTORE" component in the "FROM" clause.
5. When multiple "QUERY" properties are supplied in a single
"VQUERY" component, the results returned are the same as the
results returned for multiple "VQUERY" components having each a
single "QUERY" property.
6. The '.' is used to separate the table name (component) and column
name (property or component) when selecting a property that is
contained inside of a component that is targeted in the TARGET
property.
Royer, et al. Expires February 9, 2006 [Page 35]
Internet-Draft Calendar Access Protocol (CAP) August 2005
7. A contained component without a '.' is not the same as
"component-name.*". If given as "component-name" (no dot) the
encapsulating BEGIN/END statement will be supplied for
"component-name".:
In this example the '.' is used to separate the "TRIGGER" property
from its contained component (VALARM). Which is contained in any
"VEVENT" component in the selected "TARGET" property value (a
relcalid). All "TRIGGER" properties in any "VEVENT" component in
relcalid would be returned.
TARGET:relcalid
QUERY:SELECT VALARM.TRIGGER FROM VEVENT
SELECT VALARM FROM VEVENT WHERE UID = "123"
This returns one BEGIN/END "VALARM" component for each
"VALARM" component in the matching "VEVENT" component.
As there is no '.' (dot) in the VALARM after the SELECT above:
BEGIN:VALARM
TRIGGER;RELATED=END:PT5M
REPEAT:4
...
END:VALARM
BEGIN:VALARM
TRIGGER;RELATED=START:PT5M
DURATION:PT10M
...
END:VALARM
...
...
If provided as "component-name.*", then only the properties and any
contained components will be returned:
Royer, et al. Expires February 9, 2006 [Page 36]
Internet-Draft Calendar Access Protocol (CAP) August 2005
SELECT VALARM.* FROM VEVENT WHERE UID = "123"
Will return all of the properties in each "VALARM" component
in the matching "VEVENT" component:
TRIGGER;RELATED=END:PT5M
REPEAT:4
...
TRIGGER;RELATED=START:PT5M
DURATION:PT10M
...
...
Royer, et al. Expires February 9, 2006 [Page 37]
Internet-Draft Calendar Access Protocol (CAP) August 2005
(a) SELECT <a-property-name> FROM VEVENT
(b) SELECT VALARM FROM VEVENT
(c) SELECT VALARM.* FROM VEVENT
(d) SELECT * FROM VEVENT
(e) SELECT * FROM VEVENT WHERE
VALARM.TRIGGER < '20020201T000000Z'
AND VALARM.TRIGGER > '20020101T000000Z'
Note:
(a) Selects all instances of <a-property-name>
from all "VEVENT" components.
(b) and (c) Select all "VALARM" components from all
"VEVENT" components. (b) would return then in
BEGIN/END VALARM tags. (c) would return all
of the properties without BEGIN/END VALARM tags.
(d) Selects every property and every component
that is in any "VEVENT" component, with each "VEVENT"
component wrapped in a BEGIN/END VEVENT tags.
(e) Selects all properties and all contained
components in all "VEVENT" components that have a "VALARM"
component with a "TRIGGER" property value between
the provided dates and times, with each "VEVENT"
component wrapped in a BEGIN/END VEVENT tags.
NOT VALID:
(f) SELECT VEVENT.VALARM.TRIGGER FROM VEVENT
(g) SELECT DTSTART,UID FROM VEVENT WHERE
VTODO.SUMMERY = "Fix typo in CAP"
Note: (f) Is NOT valid because it contains
two '.' characters in the "SELECT" clause.
(g) Is NOT valid because it mixes VEVENT
and VTODO properties in the same VQUERY.
Formal Definition: The value type is defined by the following
notation:
Royer, et al. Expires February 9, 2006 [Page 38]
Internet-Draft Calendar Access Protocol (CAP) August 2005
cal-query = "SELECT" SP cap-val SP
"FROM" SP comp-name SP
"WHERE" SP cap-expr
/ "SELECT" SP cap-cols SP
"FROM" SP comp-name
;
cap-val = cap-cols / param
/ ( cap-val "," cap-val )
;
; NOTE: there is NO space around the "," on
; the next line
cap-cols = cap-col / ( cap-cols "," cap-col)
/ "*"
/ "*.*" ; only valid when the target is a "VAGENDA"
;
; A 'cap-col' is:
;
; Any property name ('cap-prop') found in the component
; named in the 'comp-name' used in the "FROM" clause.
;
; SELECT ORGANIZER FROM VEVENT ...
;
; OR
;
; A component name ('comp-name') of an existing component
; contained inside of the 'comp-name' used in the "FROM"
; clause.
;
; SELECT VALARM FROM VEVENT ...
;
; OR
;
; A component name ('comp-name') of an existing
; component contained inside of the 'comp-name' used
; in the "FROM" clause followed by a property
; name ('cap-prop') to be selected from that component.
; (comp-name "." cap-prop)
;
; SELECT VALARM.TRIGGER FROM VEVENT ...
;
cap-col = comp-name
/ comp-name "." cap-prop
/ cap-prop
;
comp-name = "VEVENT" / "VTODO" / "VJOURNAL" / "VFREEBUSY"
/ "VALARM" / "DAYLIGHT" / "STANDARD" / "VAGENDA"
/ "VCAR" / "VCALSTORE" / "VQUERY" / "VTIMEZONE"
Royer, et al. Expires February 9, 2006 [Page 39]
Internet-Draft Calendar Access Protocol (CAP) August 2005
/ "VRIGHT" / x-comp / iana-comp
;
cap-prop = ; A property that may be in the 'cap-comp' named
; in the "SELECT" clause.
;
cap-expr = "(" cap-expr ")"
/ cap-term
;
cap-term = cap-expr SP cap-logical SP cap-expr
/ cap-factor
;
cap-logical= "AND" / "OR"
;
cap-factor = cap-colval SP cap-oper SP col-value
/ cap-colval SP "LIKE" SP col-value
/ cap-colval SP "NOT LIKE" SP col-value
/ cap-colval SP "IS NULL"
/ cap-colval SP "IS NOT NULL"
/ col-value SP "IN" cap-colval
/ col-value SP "NOT IN" cap-colval
/ "STATE()" "=" ( "BOOKED"
/ "UNPROCESSED"
/ "DELETED"
/ iana-state
/ x-state )
;
iana-state = ; Any state registered by IANA directly or
; included in an RFC that may be applied to
; the component and within the rules published.
;
x-state = ; Any experimental state that starts with
; "x-" or "X-".
;
cap-colval = cap-col / param
;
param = "PARAM(" cap-col "," cap-param ")"
;
cap-param = ; Any parameter that may be contained in the cap-col
; in the supplied PARAM() function
;
col-value = col-literal
/ "SELF()"
/ "CAL-OWNERS()"
/ "CAL-OWNERS(" cal-address ")"
/ "CURRENT-TARGET()"
;
cal-address = ; A CALID as define by CAP
;
Royer, et al. Expires February 9, 2006 [Page 40]
Internet-Draft Calendar Access Protocol (CAP) August 2005
col-literal = "'" literal-data "'"
;
literal-data = ; Any data that matches the value type of the
; column that is being compared. That is you can
; not compare PRIORITY to "some string" because
; PRIORITY has a value type of integer. If it is
; not preceded by the LIKE element, any '%' and '_'
; characters in the literal data are not treated as
; wildcard characters and do not have to be backslash
; escaped.
;
; OR
;
; If the literal-data is preceded by the LIKE
; element it may also contain the '%' and '_'
; wildcard characters. And if the literal data
; that is comparing contains any '%' or '_'
; characters, they MUST BE backslash escaped as
; described in the notes below in order for them not
; to be treated as wildcard characters.
;
; And if the literal data contains any characters
; that would have to be backslash escaped if
; a property or parameter value then they must
; be backslash escaped in the literal-data.
; PLUS the quote character (') must be backslash
; escaped. Example:
;
; ... WHERE SUBJECT = 'It\'s time to ski'
;
cap-oper = "="
/ "!="
/ "<"
/ ">"
/ "<="
/ ">="
;
SP = ; A single white space ASCII character
; (value in HEX %x20).
;
x-comp = ; As defined in [iCAL] section 4.6
;
iana-comp = ; As defined in [iCAL] section 4.6
Royer, et al. Expires February 9, 2006 [Page 41]
Internet-Draft Calendar Access Protocol (CAP) August 2005
6.1.1.1 [NOT] CAL-OWNERS()
This function returns the list of "OWNER" properties for the named
calendar when used in the "SELECT" clause.
If called as 'CAL-OWNERS()', it is equivalent to the comma separated
list of all of the owners of the calendar that match the provided
"TARGET" property value. If the target is a "VCALSTORE", it returns
the "CALMASTER" property.
If called as 'CAL-OWNERS(cal-address)', then it is the equivalent to
the comma separated list of owners for the named calendar id. If
'cal-address' is a CS, it returns the "CALMASTER" property.
If used in the "WHERE" clause it then returns true if the currently
authenticated UPN is an owner of the currently selected object
matched in the provided "TARGET" property. Used in a CAL-QUERY
"WHERE" clause and in the UPN-FILTER.
6.1.1.2 CURRENT-TARGET()
Is equivalent to the value of the "TARGET" property in the current
command. Used in a CAL-QUERY "WHERE" clause.
6.1.1.3 PARAM()
Used in a CAL-QUERY. Returns or tests for the value of the named
parameter from the named property.
6.1.1.3.1 PARAM() in SELECT
When used in a "SELECT" clause, it returns the entire property and
all of that properties parameters (the result is not limited to the
supplied parameter). If the property does not contain the named
parameter, then the property is not returned (It could however be
returned as a result of another "SELECT" clause value.) If multiple
properties of the supplied name have the named parameter, all
properties with that named parameter are returned. If multiple
PARAM() clauses in a single "SELECT" CLAUSE match the same property,
then the single matching property is returned only once.
Also note that many parameters have default values defined in [iCAL]
that must be treated as existing with their default value in the
properties as defined in [iCAL} even when not explicitly present. So
for example if a query were performed with PARAM(ATTENDEE,ROLE) then
ALL "ATTENDEE" properties would match because even when they do not
explicitly contain the "ROLE" parameter, it has a default value and
therefore must match.
Royer, et al. Expires February 9, 2006 [Page 42]
Internet-Draft Calendar Access Protocol (CAP) August 2005
So when PARAM() is used in a "SELECT" clause, then it is more
accurate to say that it means return the property if it contains the
named parameter explicitly in the property or simply because the
parameter has a default for that property.
6.1.1.3.2 PARAM() in WHERE
When used in the "WHERE" clause, a match is true when the parameter
value matches the compare clause according to the supplied WHERE
values. If multiple named properties contain the named parameter,
then each parameter value is compared in turn to the condition and if
any match, then the results would be true for that condition the same
as if only one had existed. Each matching properties or components
are returned only once.
As a parameter may be multivalued then the comparison might need to
be done with an "IN" or "NOT IN" comparator.
Given the following query:
ATTENDEE;PARTSTAT=ACCEPTED:cap://host.com/joe
SELECT VEVENT FROM VAGENDA
WHERE PARAM(ATTENDEE,PARTSTAT) = 'ACCEPTED'
Then all "VEVENT" components that contain one or more "ATTENDEE"
properties that have a "PARTSTAT" parameter with a "ACCEPTED" value
would be returned. And each uniquely matching VEVENT would only be
returned once no matter how many "ATTENDEE" properties had matching
roles in each unique "VEVENT" component.
Also note that many parameters have default values defined in [iCAL].
So if the following query were performed on the "ATTENDEE" property
in the above example:
SELECT VEVENT FROM VAGENDA
WHERE PARAM(ATTENDEE,ROLE) = 'REQ-PARTICIPANT'
It would return the "ATTENDEE" property exampled above because the
default value for the "ROLE" parameter is "REQ-PARTICIPANT".
6.1.1.4 SELF()
Used in a CAL-QUERY "WHERE" clause. Returns the UPN of the currently
authenticated UPN or their current UPN as a result of an IDENTIFY
command.
Royer, et al. Expires February 9, 2006 [Page 43]
Internet-Draft Calendar Access Protocol (CAP) August 2005
6.1.1.5 STATE()
Returns one of three values, "BOOKED", "UNPROCESSED", or "DELETED"
depending on the state of the object. Where "DELETED" is a component
in the marked for delete state. Components that have been removed
from the store are never returned.
If not specified in a query then both "BOOKED" and "UNPROCESSED" data
is returned. Each unique "METHOD" property must be in a separate
MIME object per the [iCAL] section 3.2 restriction.
6.1.1.6 Use of single quote
All literal values are surrounded by single quotes ('), not double
quotes ("), and not without any quotes. If the value contains quotes
or any other ESCAPED-CHAR, they MUST BE backslash escaped as
described in section 4.3.11 "Text" of [iCAL]. Any "LIKE" clause
wildcard characters that are part of any literal data that is
preceded by a "LIKE" clause or "NOT LIKE" clause and is not intended
to mean wildcard search MUST BE escaped as described in note (7)
below.
6.1.1.7 Comparing DATE and DATE-TIME values
When comparing "DATE-TIME" values to "DATE" values and when comparing
"DATE" values to "DATE-TIME" values, the result will be true if the
"DATE" value is on the same day as the "DATE-TIME" value. And they
are compared in UTC no matter what time zone the data may actual have
been stored in.
Local time event as descibed in section 4.2.19 of [iCAL] must be
considered to be in the CUA default timezone that was supplied by the
CUA in the "CAPABILITY" exchange.
VALUE-1 VALUE-2 Compare Results
20020304 20020304T123456 TRUE
(in UTC-3) (in UTC-3)
20020304 20020304T003456 FALSE
(in UTC) (in UTC-4)
20020304T003456Z 20020205T003456 FALSE
(in UTC-0) (in UTC-7)
When comparing "DATE" values and "DATE-TIME" values with the "LIKE"
Royer, et al. Expires February 9, 2006 [Page 44]
Internet-Draft Calendar Access Protocol (CAP) August 2005
clause the comparison will be done as if the value is a [iCAL] DATE
or DATE-TIME string value.
LIKE '2002%' will match anything in the year 2002.
LIKE '200201%' will match anything in January 2002.
LIKE '%T000000' will match anything at midnight.
LIKE '____01__T%' will match anything for any year or
time that is in January.
(Four '_', '01', two '_' 'T%').
Using a "LIKE" clause value of "%00%, would return any value that
contained two consecutive zeros.
All comparisons will be done in UTC.
6.1.1.8 DTEND and DURATION
The "DTEND" property value is not included in the time occupied by
the component. That is a "DTEND" property value of 20030614T12000
includes all of the time up to but not including noon on that day.
The "DURATION" property value end time is also not inclusive. So an
object with a "DTSTART" property value of 20030514T110000 and a
"DURATION" property value of "1H" does not include noon on that day.
When a "QUERY" property value contains a "DTEND" value, then the CS
MUST also evaluate any existing "DURATION" property value and
determine if it has an effective end time that matches the "QUERY"
property supplied "DTEND" value or any range of values supplied by
the "QUERY" property.
When a "QUERY" property contains a "DURATION" value, then the CS MUST
also evaluate any existing "DTEND" property values and determine if
they have an effective duration that matches the "QUERY" property
value supplied "DURATION" value or any range of values supplied by
the "QUERY" property.
6.1.1.9 [NOT] LIKE
The pattern matching characters are the '%' that matches zero or more
characters, and '_' that matches exactly one character (where
character does not always mean octet).
Royer, et al. Expires February 9, 2006 [Page 45]
Internet-Draft Calendar Access Protocol (CAP) August 2005
"LIKE" clause pattern matches always cover the entire string. To
match a pattern anywhere within a string, the pattern must start and
end with a percent sign.
To match a '%' or '_' in the data and not have it interpreted as a
wildcard character, they MUST BE backslash escaped. That is to
search for a '%' or '_' in the string:
LIKE '%\%%' Matches any string with a '%' in it.
LIKE '%\_%' Matches any string with a '_' in it.
Strings compared using the "LIKE" clause MUST BE performed using case
in-sensitive comparisons when the locale allows. (Example: in US-
ASCII the compare assumes 'a' = 'A').
If the "LIKE" clause is preceded by 'NOT' then there is a match when
the string compare fails.
Some property values (such as the 'recur' value type), contain commas
and are not multi valued. The CS must understand the objects being
compared and understand how to determine how any multi valued or
multi instances properties or parameter values are separated, quoted,
and backslash escaped and perform the comparisons as if each value
existed by itself and not quoted or backslash escaped when comparing
using the LIKE element.
See related examples in Section 6.1.1.11
6.1.1.10 Empty vs. NULL
When used in a CAL-QUERY value, "NULL" means that the property or
parameter is not present in the object. Paramaters that are not
provided and have a default value in the property are considered to
exist with their default value and will not be "NULL".
If the property exists but has no value then "NULL" MUST NOT match.
If the parameter exists but has no value then "NULL" MUST NOT match.
If the parameter not present and has a default value then "NULL" MUST
NOT match.
If the property (or parameter) exists, but has no value then it
matches the empty string '' (quote quote).
6.1.1.11 [NOT] IN
This is similar to the "LIKE" clause, except it does value matching
Royer, et al. Expires February 9, 2006 [Page 46]
Internet-Draft Calendar Access Protocol (CAP) August 2005
and not string comparison matches.
Some iCalendar objects can be multi instance and multi valued. The
"IN" clause will return a match if the literal value supplied as part
of the "IN" clause is contained in the value of any instance of the
named property or parameter, or is in any of the multiple values in
the named property or parameter. Unlike the "LIKE" clause, the '%'
and '_' matching characters are not used with the "IN" clause and
have no special meaning.
BEGIN:A-COMPONENT
a property:value1,value2 One property, two values.
b property:"value1,value2" One property, one value.
c property:parameter=1,2:x One parameter, two values.
d property:parameter="1,2",3:y One parameter, one value.
e property:parameter=",":z One parameter, one value.
f property:x,y,z One property, three values
END:A-COMPONENT
'value1' IN property would match (a) only.
'value1,value2' IN property would match (b) only.
'value%' IN property would NOT match any.
',' IN property would NOT match any.
'%,%' IN property would NOT match any.
'x' IN property would match (f) and (c).
'2' IN parameter would match (c) only.
'1,2' IN parameter would match (d) only.
',' IN parameter would match (e) only.
'%,%' IN parameter would NOT match any.
property LIKE 'value1%' would match (a) and (b).
property LIKE 'value%' would match (a) and (b).
property LIKE 'x' would match (f) and (c).
parameter LIKE '1%' would match (c) and (d).
parameter LIKE '%2%' would match (c) and (d).
parameter LIKE ',' would match (e) only.
Some property values (such as the "RECUR" value type), contain commas
and are not multi valued. The CS must understand the objects being
compared and understand how to determine how any multi valued or
multi instances properties or parameter values are separated, quoted,
and backslash escaped and perform the comparisons as if each value
existed by itself and not quoted or backslash escaped when comparing
using the IN element.
If the "IN" clause is preceded by 'NOT' then there is a match when
Royer, et al. Expires February 9, 2006 [Page 47]
Internet-Draft Calendar Access Protocol (CAP) August 2005
the value does not exist in the property or parameter value.
6.1.1.12 DATE-TIME and TIME values in a WHERE clause
All "DATE-TIME" and "TIME" literal values supplied in a "WHERE"
clause MUST BE terminated with 'Z'. That means that the CUA MUST
supply the values in UTC.
Valid:
WHERE alarm.TRIGGER < '20020201T000000Z'
AND alarm.TRIGGER > '20020101T000000Z'
Not valid and it is a syntax error and the CS MUST reject the QUERY.
WHERE alarm.TRIGGER < '20020201T000000'
AND alarm.TRIGGER > '20020101T000000'
6.1.1.13 Multiple contained components
If a query references a component and a component or property
contained in the component, any clauses referring to the contained
component or property must be evaluated on all of the contained
components or properties. If any of the contained components or
properties match the query, and the conditions on the containing
component are also true, the component matches the query.
For example, in the query below, if a BOOKED VEVENT contains multiple
VALARMs, and the VALARM.TRIGGER clause is true for any of the VALARMs
in the VEVENT, then the UID, SUMMARY, and DESCRIPTION of this VEVENT
would be included in the QUERY results.
BEGIN:VQUERY
EXPAND:TRUE
QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT
WHERE VALARM.TRIGGER >= '20000101T030405Z'
AND VALARM.TRIGGER <= '20001231T235959Z'
AND STATE() = 'BOOKED'
END:VQUERY
Royer, et al. Expires February 9, 2006 [Page 48]
Internet-Draft Calendar Access Protocol (CAP) August 2005
6.1.1.14 Example, Query by UID
The following example would match the entire content of a "VEVENT" or
"VTODO" component with the "UID" property equal to "uid123" and not
expand any multiple instances of the component. If the CUA does not
know if "uid123" was a "VEVENT", "VTODO", "VJOURNAL", or any other
component, then all components that the CUA supports MUST BE supplied
in a QUERY property. This example assumes the CUA is only interested
in "VTODO" and "VEVENT" components.
If the results were empty it could also mean that "uid123" was a
property in a component other than a VTODO or VEVENT.
BEGIN:VQUERY
QUERY:SELECT * FROM VTODO WHERE UID = 'uid123'
QUERY:SELECT * FROM VEVENT WHERE UID = 'uid123'
END:VQUERY
6.1.1.15 Query by Date-Time range
This query selects the entire content of every booked "VEVENT"
component that has an instance greater than or equal to July 1st,
2000 00:00:00 UTC and less than or equal to July 30st, 2000 23:59:59
UTC. This includes single instance "VEVENT" components that do no
explicitly contain any recurence properties or "RECURRENCE-ID"
properties. This works only for CSs that have the "RECUR-EXPAND"
property value set to "TRUE" in the "GET-CAPABILITY" exchange.
BEGIN:VQUERY
EXPAND:TRUE
QUERY:SELECT * FROM VEVENT
WHERE RECURRENCE-ID >= '20000701T000000Z'
AND RECURRENCE-ID <= '20000730T235959Z'
AND STATE() = 'BOOKED'
END:VQUERY
6.1.1.16 Query for all Unprocessed Entries
The following example selects the entire contents of all non-booked
"VTODO" and "VEVENT" components in the "UNPROCESSED" state. The
default for the "EXPAND" property is "FALSE", so the recurrence rules
will not be expanded.
Royer, et al. Expires February 9, 2006 [Page 49]
Internet-Draft Calendar Access Protocol (CAP) August 2005
BEGIN:VQUERY
QUERYID:Fetch VEVENT and VTODO iTIP components
QUERY:SELECT * FROM VEVENT WHERE STATE() = 'UNPROCESSED'
QUERY:SELECT * FROM VTODO WHERE STATE() = 'UNPROCESSED'
END:VQUERY
The following example fetches all "VEVENT" and "VTODO" components in
the "BOOKED" state.
BEGIN:VQUERY
QUERYID:Fetch All Booked VEVENT and VTODO components
QUERY:SELECT * FROM VEVENT WHERE STATE() = 'BOOKED'
QUERY:SELECT * FROM VTODO WHERE STATE() = 'BOOKED'
END:VQUERY
The following fetches the "UID" property for all "VEVENT" and "VTODO"
components that have been marked for delete.
BEGIN:VQUERY
QUERYID:Fetch UIDs of marked for delete VEVENTs and VTODOs
QUERY:SELECT UID FROM VEVENT WHERE STATE() = 'DELETED'
QUERY:SELECT UID FROM VTODO WHERE STATE() = 'DELETED'
END:VQUERY
6.1.1.17 Query with Subset of Properties by Date/Time
In this example only the named properties will be selected and all
booked and non-booked components will be selected that have a
"DTSTART" value from February 1st to February 10th 2000 (in UTC).
BEGIN:VQUERY
QUERY:SELECT UID,DTSTART,DESCRIPTION,SUMMARY FROM VEVENT
WHERE DTSTART >= '20000201T000000Z'
AND DTSTART <= '20000210T235959Z'
END:VQUERY
6.1.1.18 Query with Components and Alarms In A Range
This example fetches all booked "VEVENT" components with an alarm
Royer, et al. Expires February 9, 2006 [Page 50]
Internet-Draft Calendar Access Protocol (CAP) August 2005
that triggers within the specified time range. In this case only the
"UID", "SUMMARY", and "DESCRIPTION" properties will be selected for
all booked "VEVENTS" components that have an alarm between the two
date-times supplied.
BEGIN:VQUERY
EXPAND:TRUE
QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT
WHERE VALARM.TRIGGER >= '20000101T030405Z'
AND VALARM.TRIGGER <= '20001231T235959Z'
AND STATE() = 'BOOKED'
END:VQUERY
6.1.2 UPN Value Type
Value Name: UPN
Purpose: This value type is used to identify values that contain user
principal name of CU or group of CU.
Formal Definition: The value type is defined by the following
notation:
;
upn = "@"
/ [ dot-atom-text ] "@" dot-atom-text
;
; dot-atom-text is defined in RFC 2822
;
;
dot-atom-text = ; As defined in [iCAL]
Description: This data type is an identifier that denotes a CU or a
group of CU. A UPN is a RFC 2822 compliant email address, with
exceptions listed below, and in most cases it is deliverable to the
CU. In some cases it is identical to the CU's well known email
address. A CU's UPN MUST never be an e-mail address that is
deliverable to a different person. And there is no requirement that
a person's UPN MUST BE their e-mail address. A UPN is formatted as a
user name followed by "@" followed by a Realm in the form of a valid,
and unique, DNS domain name. The user name MUST BE unique within the
Realm. In it's simplest form it looks like "user@example.com".
In certain cases a UPN will not be RFC 2822 compliant. When
Royer, et al. Expires February 9, 2006 [Page 51]
Internet-Draft Calendar Access Protocol (CAP) August 2005
anonymous authentication is used, or anonymous authorization is being
defined, the special UPN "@" will be used. When authentication MUST
BE used, but unique identity MUST BE obscured, a UPN of the form
@DNS-domain-name may be used. For example, "@example.com".
Example:
The following is a UPN for a CU:
jdoe@example.com
The following is a example of a UPN that could be for a group of CU:
staff@example.com
The following is a UPN for an anonymous CU belonging to a specific
realm or when used as a UPN-FILTER it specifies that it applies to
all UPNs in a specific realm:
@example.com
The following is a UPN for an anonymous CU:
@
6.1.3 UPN-FILTER Value
Value Name: UPN-FILTER
Purpose: This value type is used to identify values that contain a
user principal name filter.
Formal Definition: The value type is defined by the following
notation:
Royer, et al. Expires February 9, 2006 [Page 52]
Internet-Draft Calendar Access Protocol (CAP) August 2005
;
; NOTE: "CAL-OWNERS(cal-address)"
; and "NOT CAL-OWNERS(cal-address)"
; are both NOT allowed below.
;
upn-filter = "CAL-OWNERS()" /
"NOT CAL-OWNERS()" /
"*" /
[ "*" / dot-atom-text ] "@" ( "*" / dot-atom-text )
;
; dot-atom-text is defined in RFC 2822
Description: The value is used to match user principal names (UPNs).
For "CAL-OWNERS()" and "NOT CAL-OWNERS()", see Section 8.24.
* Matches all UPNs.
@ Matches the UPN of anonymous CUs
belonging to the null realm
@* Matches the UPN of anonymous CUs
belonging to any non-null realm
@realm Matches the UPN of anonymous CUs
belonging to the specified realm.
*@* Matches the UPN of non-anonymous CUs
belonging to any non-null realm
*@realm Matches the UPN of non-anonymous CUs
belonging to the specified realm
user@realm Matches the UPN of the specified CU
belonging to the specified realm
user@* Not allowed.
user@ Not allowed.
Example: The following are examples of this value type:
Royer, et al. Expires February 9, 2006 [Page 53]
Internet-Draft Calendar Access Protocol (CAP) August 2005
DENY:NON CAL-OWNERS()
DENY:@hackers.example.com
DENY:*@hackers.example.com
GRANT:sam@example.com
Royer, et al. Expires February 9, 2006 [Page 54]
Internet-Draft Calendar Access Protocol (CAP) August 2005
7. New Parameters
7.1 ACTION Parameter
Parameter Name: ACTION
Purpose: This parameter indicates the action to be taken when a
timeout occurs.
Value Type: TEXT
Conformance: This property can be specified in the "CMD" property.
When present in a "CMD" property the "ACTION" parameter specifies the
action to be taken when the command timeout expires.
Formal Definition: The parameter is defined by the following
notation:
action-param = ";" "ACTION" "=" ( "ASK" / "ABORT" )
; If 'action-param' is supplied then
; 'latency-param' MUST BE supplied.
Example: The following is an example of this parameter:
CMD;LATENCY=10;ACTION=ASK:CREATE
7.2 ENABLE Parameter
Parameter Name: ENABLE
Purpose: This parameter indicates whether or not the property should
be ignored. Example if a "TRIGGER" property in a "VALARM" component
should be ignored.
Value Type: BOOLEAN
Conformance: This property can be specified in the "TRIGGER"
properties.
Description: When a non owner sends an [iTIP] "REQUEST" to a calendar
that object might contain a "VALARM" component. The owner may wish
to have local control over their own CUA and when or how alarms are
Royer, et al. Expires February 9, 2006 [Page 55]
Internet-Draft Calendar Access Protocol (CAP) August 2005
triggered.
A CUA may add the "ENABLE" parameter to any "TRIGGER" property before
booking the component. If the "ENABLE" parameter is set to "FALSE",
then the alarm will be ignored by the CUA. If set to "TRUE", or if
the "ENABLE" property is not in the "TRIGGER" property, the alarm is
enabled. This parameter may not be known by pre-CAP implementations
and should not be an issue as it conforms to an 'ianaparam' as
defined in [iCAL].
Formal Definition: The property is defined by the following notation:
enable-param = "ENABLE" "=" boolean
;
boolean = ; As defined in [iCAL]
Example: The following is an example of this property for a "VAGENDA"
component:
TRIGGER;ENABLE=FALSE;RELATED=END:PT5M
7.3 ID Parameter
Parameter Name: ID
Purpose: When used in a "CMD" component provides a unique identifier.
Value Type: TEXT
Conformance: This parameter can be specified in the "CMD" property.
Description: If there is more than one command sent then the "ID"
parameter is used to uniquely identify the command.
A CUA may add the "ID" parameter to any "CMD" property before sending
the command. There must not be more than one outstanding command
tagged with the same "ID" parameter value.
Formal Definition: The property is defined by the following notation:
Royer, et al. Expires February 9, 2006 [Page 56]
Internet-Draft Calendar Access Protocol (CAP) August 2005
id-param = ";" "ID" "=" unique-id
; The text value supplied is a unique value
; shared between the CUA and CS to uniquely
; identify the instance of command in the
; the current CUA session. The value has
; no meaning to other CUAs or other sessions.
;
unique-id = ; text
;
text = ; As defined in [iCAL].
Example: The following is an example of this parameter component:
CMD;UD=some-unique-value:CREATE
7.4 LATENCY Parameter
Parameter Name: LATENCY
Purpose: This parameter indicates time in seconds for when a timeout
occurs.
Value Type: TEXT
Conformance: This property can be specified in the "CMD" property.
When present in a "CMD" property the "LATENCY" parameter specifies
the time in sections when the command timeout expires.
Formal Definition: The parameter is defined by the following
notation:
latency-param = ";" "LATENCY" "=" latency-sec
; The value supplied in the time in seconds.
; If 'latency-param' is supplied then
; 'action-param' MUST BE supplied.
;
latency-sec = posint1
; Default is zero (0) meaning no timeout.
Royer, et al. Expires February 9, 2006 [Page 57]
Internet-Draft Calendar Access Protocol (CAP) August 2005
Example: The following is an example of this parameter:
CMD;LATENCY=10;ACTION=ASK:CREATE
7.5 LOCAL Parameter
Parameter Name: LOCAL
Purpose: Indicates if the named component should be exported to any
non-organizer calendar.
Value Type: BOOLEAN
Conformance: This parameter can be specified in the "SEQUENCE"
properties in a "VALARM" component.
Description: When a non owner sends an [iTIP] "REQUEST" to a calendar
that object might contain a "VALARM" component. The owner may wish
to have local control over their own CUA and when or how alarms are
triggered.
A CUA may add the "LOCAL" parameter to the "SEQUENCE" property before
booking the component. If the "LOCAL" parameter is set to "TRUE",
then the alarm MUST NOT be forwarded to any other calender. If set
to "FALSE", or if the "LOCAL" parameter is not in the "SEQUENCE"
property, the alarm is global.
Formal Definition: The property is defined by the following notation:
local-param = "LOCAL" "=" boolean
Example: The following is an example of this parameter:
SEQUENCE;LOCAL=TRUE:4
7.6 LOCALIZE Parameter
Parameter Name: LOCALIZE
Purpose: If provided the "LOCALIZE" parameter specifies the desired
Royer, et al. Expires February 9, 2006 [Page 58]
Internet-Draft Calendar Access Protocol (CAP) August 2005
language for error and warning messages.
Value Type: TEXT
Conformance: This parameter can be specified in the "CMD" properties.
When the "LOCALIZE" parameter is supplied then its value MUST BE one
of the values listed in the initial [BEEP] greeting 'localize'
attribute.
A CUA may add the "LOCALIZE" parameter to the "CMD" property to
specify the language of any error or warning messages.
Formal Definition: The property is defined by the following notation:
localize-param = ";" "LOCALIZE" "=" beep-localize
;
beep-localize = text ; As defined in [BEEP]
; The value supplied MUST BE one value from the initial
; [BEEP] greeting 'localize' attribute specifying
; the locale to use for error messages during
; this instance of the command sent.
Example: The following is an example of this parameter:
CMD;LOCALIZE=fr_CA:CREATE
7.7 OPTIONS Parameter
Parameter Name: OPTIONS
Purpose: If provided the "OPTIONS" parameter specifies some "CMD"
property specific options.
Value Type: TEXT
Conformance: This parameter can be specified in the "CMD" properties.
A CUA adds the "OPTIONS" parameter to the "CMD" property when the
command needs extra values.
Formal Definition: The property is defined by the following notation:
Royer, et al. Expires February 9, 2006 [Page 59]
Internet-Draft Calendar Access Protocol (CAP) August 2005
option-param = ";" "OPTIONS" "=" cmd-specific
;
cmd-specific = ; The value supplied is dependent on the
; CMD value. See the specific CMDs for the
; correct values to use for each CMD.
Example: The following is an example of this parameter:
CMD;OPTIONS=10:GENERATE-UID
Royer, et al. Expires February 9, 2006 [Page 60]
Internet-Draft Calendar Access Protocol (CAP) August 2005
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, if 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.
Royer, et al. Expires February 9, 2006 [Page 61]
Internet-Draft Calendar Access Protocol (CAP) August 2005
Conformance: This property MUST be specified in an iCalendar object
that specifies 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/sdfifgty4321
Royer, et al. Expires February 9, 2006 [Page 62]
Internet-Draft Calendar Access Protocol (CAP) August 2005
8.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
