Network Working Group S. Mansour
Internet-Draft AOL/Netscape
Expires: August 30, 2002 D. Royer
INET-Consulting LLC
G. Babics
Steltor
P. Hill
Massachusetts Institute of
Technology
March 01, 2002
Calendar Access Protocol (CAP)
draft-ietf-calsch-cap-07
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
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 August 30, 2002.
Copyright Notice
Copyright (C) The Internet Society (2002). All Rights Reserved.
Abstract
The Calendar Access Protocol (CAP) is an Internet protocol that
permits a Calendar User (CU) to utilize a Calendar User Agent (CUA)
to access an [RFC2445] based Calendar Store (CS). This memo defines
the CAP specification.
Mansour, et al. Expires August 30, 2002 [Page 1]
Internet-Draft Calendar Access Protocol (CAP) March 2002
The CAP definition is based on requirements identified by the
Internet Engineering Task Force (IETF) Calendaring and Scheduling
(CALSCH) Working Group. More information about the IETF CALSCH
Working Group activities can be found on the IMC web site at http://
www.imc.org/ietf-calendar and at the IETF web site at http://
www.ietf.org/html.charters/calsch-charter.html [1]. Refer to the
references within this memo for further information on how to access
these various documents.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . 5
1.1 Formatting Conventions . . . . . . . . . . . . . . . . 5
1.2 Related Documents . . . . . . . . . . . . . . . . . . 6
1.3 Definitions . . . . . . . . . . . . . . . . . . . . . 6
2. CAP Design . . . . . . . . . . . . . . . . . . . . . . 12
2.1 System Model . . . . . . . . . . . . . . . . . . . . . 12
2.2 Calendar Store Object Model . . . . . . . . . . . . . 12
2.3 Protocol Model . . . . . . . . . . . . . . . . . . . . 13
2.4 Security Model . . . . . . . . . . . . . . . . . . . . 14
2.4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . 14
2.4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . 14
2.4.1.2 Anonymous Users and Authentication . . . . . . . . . . 15
2.4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . 16
2.4.2 Access Rights - Summary . . . . . . . . . . . . . . . 16
2.4.2.1 Calendar Access Right (VCAR) . . . . . . . . . . . . . 16
2.4.2.2 Predefined VCARs . . . . . . . . . . . . . . . . . . . 17
2.4.2.3 Decreed VCARs . . . . . . . . . . . . . . . . . . . . 18
2.4.3 CAP Session Identity . . . . . . . . . . . . . . . . . 19
2.5 Roles . . . . . . . . . . . . . . . . . . . . . . . . 20
2.6 CAP URL . . . . . . . . . . . . . . . . . . . . . . . 20
2.7 Calendar Addresses . . . . . . . . . . . . . . . . . . 21
2.8 Extensions to iCalendar . . . . . . . . . . . . . . . 21
2.9 Relationship of RFC 2446 (ITIP) to CAP . . . . . . . . 21
3. Protocol Framework . . . . . . . . . . . . . . . . . . 23
3.1 BEEP Exchange Styles . . . . . . . . . . . . . . . . . 23
3.2 Use BEEP, MIME and iCalendar . . . . . . . . . . . . . 23
3.3 Bounded Latency . . . . . . . . . . . . . . . . . . . 24
4. New Value Types . . . . . . . . . . . . . . . . . . . 27
4.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . . 27
4.1.1 CAP-QL notes . . . . . . . . . . . . . . . . . . . . . 31
4.2 CAP-QL notes . . . . . . . . . . . . . . . . . . . . . 37
4.3 Example, Query by UID . . . . . . . . . . . . . . . . 42
4.4 Query by Date-Time range . . . . . . . . . . . . . . . 42
4.5 Query for all Non-Booked Entries . . . . . . . . . . . 43
4.6 Query with Subset of Properties by Date/Time . . . . . 44
4.7 Components With Alarms In A Range . . . . . . . . . . 44
5. Access Rights . . . . . . . . . . . . . . . . . . . . 45
Mansour, et al. Expires August 30, 2002 [Page 2]
Internet-Draft Calendar Access Protocol (CAP) March 2002
5.1 Access Control and NOCONFLICT . . . . . . . . . . . . 45
6. Commands and Responses . . . . . . . . . . . . . . . . 46
6.1 Session Commands . . . . . . . . . . . . . . . . . . . 46
6.1.1 "generate-uid" Command . . . . . . . . . . . . . . . . 46
6.1.2 "get-capability" Command . . . . . . . . . . . . . . . 47
6.1.3 "identify" Command . . . . . . . . . . . . . . . . . . 49
6.1.4 "noop" Command . . . . . . . . . . . . . . . . . . . . 50
6.2 Calendaring and Scheduling Commands . . . . . . . . . 51
6.2.1 Restriction Tables . . . . . . . . . . . . . . . . . . 51
6.2.2 Calendaring Commands . . . . . . . . . . . . . . . . . 52
6.2.2.1 "create" Command . . . . . . . . . . . . . . . . . . . 52
6.2.2.2 "move" Command . . . . . . . . . . . . . . . . . . . . 57
6.2.2.3 "delete" Command . . . . . . . . . . . . . . . . . . . 60
6.2.2.4 "modify" Command . . . . . . . . . . . . . . . . . . . 62
6.2.2.5 "search" Command . . . . . . . . . . . . . . . . . . . 66
6.2.2.6 Response Codes . . . . . . . . . . . . . . . . . . . . 71
7. Initial Registrations . . . . . . . . . . . . . . . . 73
7.1 BEEP Profile Registration . . . . . . . . . . . . . . 73
7.2 Registration: The System (Well-Known) TCP port number
for CAP . . . . . . . . . . . . . . . . . . . . . . . 73
8. CAP DTD . . . . . . . . . . . . . . . . . . . . . . . 75
9. Properties . . . . . . . . . . . . . . . . . . . . . . 76
9.1 Calendar Store Properties . . . . . . . . . . . . . . 76
9.2 Calendar Properties . . . . . . . . . . . . . . . . . 77
10. Security Considerations . . . . . . . . . . . . . . . 80
11. Extensions To iCalendar . . . . . . . . . . . . . . . 81
11.1 Property Value Data Types . . . . . . . . . . . . . . 81
11.1.1 UPN . . . . . . . . . . . . . . . . . . . . . . . . . 81
11.1.2 UPN Filter . . . . . . . . . . . . . . . . . . . . . . 82
11.2 Calendar Components . . . . . . . . . . . . . . . . . 83
11.2.1 Agenda Component . . . . . . . . . . . . . . . . . . . 83
11.2.2 Calendar Store Component . . . . . . . . . . . . . . . 84
11.2.3 Calendar Access Right Component . . . . . . . . . . . 85
11.2.4 VRIGHT Calendar Component . . . . . . . . . . . . . . 88
11.3 Component Properties . . . . . . . . . . . . . . . . . 89
11.3.1 Allow-Conflict Component Property . . . . . . . . . . 89
11.3.2 Charset Component Property . . . . . . . . . . . . . . 90
11.3.3 Default Locale Component Property . . . . . . . . . . 91
11.3.4 Default Time Zone Property . . . . . . . . . . . . . . 91
11.3.5 Owner Component Property . . . . . . . . . . . . . . . 92
11.3.6 Relative Calendar Identifier Component Property . . . 93
11.3.7 Calendar Store Component Properties . . . . . . . . . 94
11.3.7.1 Calmaster Component Property . . . . . . . . . . . . . 94
11.3.7.2 Calendar Store Identifier Component Property . . . . . 94
11.3.7.3 Default Access Rights Component Property . . . . . . . 95
11.3.7.4 Maximum Date Component Property . . . . . . . . . . . 96
11.3.7.5 Minimum Date Component Property . . . . . . . . . . . 97
11.3.8 Descriptive Component Properties . . . . . . . . . . . 97
Mansour, et al. Expires August 30, 2002 [Page 3]
Internet-Draft Calendar Access Protocol (CAP) March 2002
11.3.8.1 REQUEST-STATUS property . . . . . . . . . . . . . . . 97
11.3.8.2 CALID Property Parameter . . . . . . . . . . . . . . . 98
11.3.8.3 Time Transparency . . . . . . . . . . . . . . . . . . 99
11.3.8.4 Name Component Property . . . . . . . . . . . . . . . 100
11.3.9 Calendar Access Right Component Properties . . . . . . 101
11.3.9.1 VCAR Identifier Component Property . . . . . . . . . . 101
11.3.9.2 VCAR Decreed Component Property . . . . . . . . . . . 102
11.3.10 Right Component Properties . . . . . . . . . . . . . . 102
11.3.10.1 Grant Component Property . . . . . . . . . . . . . . . 103
11.3.10.2 Deny Component Property . . . . . . . . . . . . . . . 103
11.3.10.3 Permission Component Property . . . . . . . . . . . . 104
11.3.10.4 Scope Component Property . . . . . . . . . . . . . . . 105
11.3.10.5 Restriction Component Property . . . . . . . . . . . . 106
12. CAP Item Registration . . . . . . . . . . . . . . . . 107
12.1 Registration of New and Modified CAP Entities . . . . 107
12.2 Registration of New Entities . . . . . . . . . . . . . 107
12.2.1 Define the Item . . . . . . . . . . . . . . . . . . . 107
12.2.2 Post the item definition . . . . . . . . . . . . . . . 108
12.2.3 Allow a comment period . . . . . . . . . . . . . . . . 108
12.2.4 Submit the proposal for approval . . . . . . . . . . . 108
12.3 Property Change Control . . . . . . . . . . . . . . . 109
13. IANA Considerations . . . . . . . . . . . . . . . . . 110
Authors' Addresses . . . . . . . . . . . . . . . . . . 111
A. Acknowledgments . . . . . . . . . . . . . . . . . . . 112
B. Bibliography . . . . . . . . . . . . . . . . . . . . . 113
Full Copyright Statement . . . . . . . . . . . . . . . 115
Mansour, et al. Expires August 30, 2002 [Page 4]
Internet-Draft Calendar Access Protocol (CAP) March 2002
1. Introduction
This document specifies how a Calendar User Agent (CUA) interacts
with a Calendar Store (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.
CAP is specified as a BEEP "profile". As such many aspects of the
protocol (e.g., authentication and privacy) are provided within the
[BEEP]. The protocol data units leverage the standard iCalendar
format [RFC2445] to convey calendar related information.
CAP can also be used to store and fetch [iTIP] objects and when those
objects are used here in this memo, they mean exactly the same as
defined in [iTIP].
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 [RFC2119].
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 [RFC2445] are referred to with capitalized, quoted-strings of
text. All calendar components start with the letter "V". For
example, "VEVENT" refers to the event calendar component, "VTODO"
refers to the to-do calendar component and "VJOURNAL" refers to the
daily journal calendar 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".
CAP commands are referred by lower-case, quotes-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.
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 of a "Calendar User". Property
parameters defined by this memo are referred to with capitalized,
Mansour, et al. Expires August 30, 2002 [Page 5]
Internet-Draft Calendar Access Protocol (CAP) March 2002
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".
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:
[RFC2445] (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 implementations. The related documents
are:
[iMIP] (RFC2447) which specifies an Internet email binding for
[iTIP].
[GUIDE] (draft/rfc...) which is 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 entry in a calendar has one of three conceptual states. It
is scheduled, booked or marked for delete. A scheduled entry
has been stored in the calendar store but has not been acted on
by a calendar user (CU) or calendar user agent (CUA). A
scheduled entry contains a METHOD property set to an [iTIP]
method. A booked entry has its METHOD property set to CREATE.
A marked for delete component has its METHOD property set to
DELETE
Mansour, et al. Expires August 30, 2002 [Page 6]
Internet-Draft Calendar Access Protocol (CAP) March 2002
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 other calendar properties
or calendar components. In addition, a calendar might be
hierarchically related to other calendars with the RELATED-TO
property. A calendar is identified by its unique calendar
identifier. The [RFC2445] defines calendar properties,
calendar components and component properties that make up the
content of a calendar.
Calendar Access Protocol (CAP)
The standard Internet protocol that permits a Calendar User
Agent to access and manipulate calendars residing on a Calendar
Store. (this memo)
Calendar Access Rights (CAR)
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 the "VCAR"
calendar components within a CS and calendar.
Calendar Component
An object within a calendar or a calendar store (CS). Some
types of calendar components include calendars, events, to-dos,
journals, alarms, time zones and freebusy data. A calendar
component consists of component properties and possibly other
sub-components. For example, an event may contain an alarm
component.
Calendar Component Properties
An attribute of a particular calendar component. Some calendar
component properties are applicable to different types of
calendar components. For example, DTSTART is applicable to
VEVENT, VTODO, VJOURNAL calendar components. Other calendar
components are applicable only to an individual type of
calendar component. For example, TZURL is only applicable to
VTIMEZONE calendar components.
Calendar Identifier (CalID)
A globally unique identifier associated with a calendar.
Mansour, et al. Expires August 30, 2002 [Page 7]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Calendars reside within a CS. See Qualified Calendar
Identifier and Relative Calendar Identifier. All CalIDs start
with "cap:"
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. For example, "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, CALSCALE specifies the
calendar scale (e.g., GREGORIAN) for the whole calendar.
Calendar Service
An implementation of a Calendar Store that manages one or more
calendars.
Calendar Store (CS)
The data and service model definition for a Calendar Service.
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 [RFC1738].
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)
Mansour, et al. Expires August 30, 2002 [Page 8]
Internet-Draft Calendar Access Protocol (CAP) March 2002
The CUA is the client application that a CU utilizes to access
and manipulate a calendar.
CAP Session
An open communication channel between a CUA and a Calendar
Service.
Contained Component / Contained Properties
A component or property that is contained inside a component.
VALARM for example may be contained inside of a VEVENT. And
TRIGGER is a contained property of a VALARM.
Delegate
A calendar user (sometimes called the delegatee) who has been
assigned participation in a scheduled calendar component (e.g.,
VEVENT) by one of the attendees in the scheduled calendar
component (sometimes called the delegator). An example of a
delegate is a team member told to go to a particular meeting.
Designate
A calendar user who is authorized to act on behalf of another
calendar user. An example of a designate is an assistant.
Overlapped Booking
A policy which indicates whether or not OPAQUE events can
overlap one another. When the policy is applied to a calendar
it indicates whether or not the time span of any entry (VEVENT,
VTODO, ...) in the calendar can overlap the time span of any
other entry in the same calendar. When applied to an
individual entry, it indicates whether or not any other entry's
time span can overlap that individual entry.
Owner
One or more CUs or UGs that are listed in the "OWNER" calendar
property in a calendar.
Qualified Calendar Identifier (Qualified CalID)
A CalID where both the <scheme> and <csid> are present.
Realm
Mansour, et al. Expires August 30, 2002 [Page 9]
Internet-Draft Calendar Access Protocol (CAP) March 2002
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).
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 portion of the "scheme part" of a Qualified
CalID following the Calendar Store Identifier. This is the
same as the "URL path" of the "Common Internet Scheme Syntax"
portion of a URL, as defined by [RFC1738].
Session Identity
A UPN associated with a CAP session. A session gains an
identity after successful authentication. The identity is used
in combination with CAR 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. A UPN
is a RFC 822 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 as there is no requirement that a person's
UPN must be his e-mail address. It consists of a Realm in the
form of a valid, and unique, DNS domain name and a unique
Username. In it's simplest form it looks like
"user@example.com".
In certain cases a UPN will not be RFC 822 compliant. When
anonymous authentication is used, or anonymous authorization is
Mansour, et al. Expires August 30, 2002 [Page 10]
Internet-Draft Calendar Access Protocol (CAP) March 2002
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". Usage of these special cases is
further discussed in the authentication and authorization
sections of this document.
Mansour, et al. Expires August 30, 2002 [Page 11]
Internet-Draft Calendar Access Protocol (CAP) March 2002
2. CAP Design
2.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 "Calendar User Agent" (CUA) to send commands to and
receive responses from a "Calendar Service".
The CUA prepares a [MIME] encapsulated command, sends it to the CS,
and receives a [MIME] encapsulated response. The calendaring related
information within these messages are represented by iCalendar
objects.
There are two distinct protocols in operation to accomplish this
exchange. [BEEP] is the transport protocol and is used to move
these encapsulations between a CUA and a CS. CAP profile defines the
application protocol. That is, the content and semantics of the
messages sent between the CUA and the Calendar Service.
2.2 Calendar Store Object Model
[RFC2445] describes components such as events, todos, alarms, and
timezones. [CAP] requires more object infrastructure. In
particular, detailed definitions of the containers for events and
todos (calendars), access control objects, and a query language.
[CAP] defines the following new objects which will be discussed in
detail in this memo
Component Description
--------- -----------------------------------------
VCAR An access control object
VQUERY A query object
VAGENDA A container that holds components and which is owned
by one or more CUs.
The conceptual model for a calendar store is shown below. The
calendar store contains VCARs, VQUERYs, VTIMEZONEs, VAGENDAs and
calendar store properties.
Calendars (VAGENDAs) contain VEVENTs, VTODOs, VJOURNALs, VCARs,
VTIMEZONEs, VQUERYs and calendar properties.
The special keyword VCALSTORE is used to denote the a root of the
calendar store. It is a point from which searches can begin. It is
the container for VTIMEZONEs, VQUERYs, and toplevel VAGENDAs.
Mansour, et al. Expires August 30, 2002 [Page 12]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Calendar Store
VCALSTORE
|
+-- VCARs
+-- VQUERYs
+-- VTIMEZONEs
+-- VAGENDA
| |
| +--VEVENTs
| | |
| | +--VALARMs
| +--VTODOs
| | |
| | +--VALARMs
| +--VJOURNALs
| +--VCARs
| +--VTIMEZONEs
| +--VQUERYs
| +--VAGENDAs
| | |
| | +--VEVENTs
| | | |
| | | +--VALARMs
| | +--VTODOs
| | | |
| | | +--VALARMs
| | +--VJOURNALs
| | +--VCARs
| | +--VTIMEZONEs
| | +--VQUERYs
| | +--VFREEBUSY
| | +--VAGENDAs
| | | |
| | | ...
Calendars within a Calendar Store are identified by their Relative
CALID.
2.3 Protocol Model
The commands listed below are used to manipulate the data on the
calendar store.
CAP Commands
-----------------------------------------------------------
Command Description
-----------------------------------------------------------
create Create a new calendar component.
Mansour, et al. Expires August 30, 2002 [Page 13]
Internet-Draft Calendar Access Protocol (CAP) March 2002
delete Delete calendar components.
generate-uid Generate one or more unique ids.
get-capability Query the capabilities the CAP server
identify Set a new identity for calendar access.
modify Modify calendar components.
move Move calendar components to another container.
noop Do nothing.
search Search for calendar components.
-----------------------------------------------------------
2.4 Security Model
2.4.1 Calendar User and UPNs
A Calendar User (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
2.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):
Mansour, et al. Expires August 30, 2002 [Page 14]
Internet-Draft Calendar Access Protocol (CAP) March 2002
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
with unfamiliar attributes in the subject name.
In addition, legacy implementations exist where an RFC 822 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.com" is the same as
"FANFEEDBACK@REDSOX.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 [RFC
2459]) 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" property 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:juser@example.com" and have it pass validation.
This validation will also defeat other attempts at confusion.
2.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.
Mansour, et al. Expires August 30, 2002 [Page 15]
Internet-Draft Calendar Access Protocol (CAP) March 2002
2.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.
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.
The CS should not preserve UG expansions across operations. A UG may
reference a static list of members, or it may represent a dynamic
list. Each operation SHOULD generate its own expansion in order to
recognize changes to UG membership.
CAP does not define commands or methods for managing UGs.
2.4.2 Access Rights - Summary
Access rights are used to grant or deny access to a calendar for a
CU. CAP defines a new component type called a Calendar Access Right
(VCAR). Specifically, a VCAR grants, or denies, UPNs the right to
read and write components, properties, and parameters on calendars
within a CS.
The VCAR model does not put any restriction on the sequence in which
the object and access rights are created. That is, an event
associated with a particular VCAR might be created before or after
the actual VCAR is defined. In addition, the VCAR and VEVENT
definition 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 grant
access.
2.4.2.1 Calendar Access Right (VCAR)
Access rights within CAP are specified with the "VCAR" calendar
component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID"
component properties.
Properties within an iCalendar object are unordered. This also is
the case for the "VCAR" properties.
Mansour, et al. Expires August 30, 2002 [Page 16]
Internet-Draft Calendar Access Protocol (CAP) March 2002
For details on the VCAR syntax please see section Section 2.4.2
2.4.2.2 Predefined VCARs
Predefined calendar access CARIDs that MUST be implemented are:
CARID:READBUSYTIMEINFO - grants all authenticated users the right to
read VFREEBUSY components. Suggested definition for this VCAR:
BEGIN:VCAR
CARID:READBUSYTIMEINFO
BEGIN:VRIGHT
GRANT:*
PERMISSION:READ
SCOPE:SELECT * FROM VFREEBUSY
END:VRIGHT
END:VCAR
CARID:REQUESTONLY - grants to users other than the owner of the
calendar the right to write new events with the property METHOD set
to REQUEST. Suggested definition for this VCAR:
BEGIN:VCAR
CARID:REQUESTONLY
BEGIN:VRIGHT
GRANT:NONOWNER
PERMISSION:WRITE
RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST'
END:VRIGHT
END:VCAR
CARID:UPDATEPARTSTATUS - grants all authenticated users the right to
modify the instances of the ATTENDEE property set to one of their
calendar adresses in the VEVENT and VTODO components for which the
ORGANIZER property is set to the address of the VAGENDA in which the
VEVENT or VTODO is stored, given that the submitted value of the
ATTENDEE property is one of their calendar adresses. Suggested
definition for this VCAR:
BEGIN:VCAR
CARID:UPDATEPARTSTATUS
BEGIN:VRIGHT
GRANT:*
PERMISSION:MODIFY
SCOPE:SELECT att FROM VEVENT
USING_PROPERTIES ATTENDEE att
WHERE SELF() IN CAL-OWNERS(att) AND ORGANIZER = CURRENT-CALID()
RESTRICTION:SELECT * FROM VEVENT
Mansour, et al. Expires August 30, 2002 [Page 17]
Internet-Draft Calendar Access Protocol (CAP) March 2002
WHERE SELF() IN CAL-OWNERS(ATTENDEE)
END:VRIGHT
BEGIN:VRIGHT
GRANT:*
PERMISSION:MODIFY
SCOPE:SELECT att FROM VTODO
USING_PROPERTIES ATTENDEE att
WHERE SELF() IN CAL-OWNERS(att) AND ORGANIZER = CURRENT-CALID()
RESTRICTION:SELECT * FROM VTODO
WHERE SELF() IN CAL-OWNERS(ATTENDEE)
END:VRIGHT
END:VCAR
CARID:DEFAULTOWNER - grants to the owner all permissions on all the
objects in the calendar. Suggested definition for this VCAR:
BEGIN:VCAR
CARID:DEFAULTOWNER
BEGIN:VRIGHT
GRANT:OWNER
PERMISSION:*
SCOPE:SELECT * FROM VAGENDA
END:VRIGHT
END:VCAR
2.4.2.3 Decreed VCARs
A CS MAY choose to implement and allow persistent immutable VCARs,
that are configured by the CS administrator, which apply to all
calendars on the server.
When a user attempts to modify or override a decreed VCAR an error
will be returned, indicating that the user has 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. The GRANT property allows the OWNERs
all access to their own calendar objects. The DENY property
disallows anyone (UPN=*) from being able to delete or modify this
VCAR.
Mansour, et al. Expires August 30, 2002 [Page 18]
Internet-Draft Calendar Access Protocol (CAP) March 2002
BEGIN:VCAR
CARID:ctjmocfbr-01
NAME:Users Default Access
DECREED:TRUE
BEGIN:VRIGHT
GRANT:OWNER
PERMISSION:*
SCOPE:SELECT * FROM VAGENDA
END:VRIGHT
BEGIN:VRIGHT
DENY:*
PERMISSION:DELETE
PERMISSION:MODIFY
SCOPE:SELECT * FROM VCAR WHERE CARID = 'ctjmocfbr-01'
END:VRIGHT
END:VCAR
Decreed VCARs MUST BE readable by the calendar owner in standard VCAR
format.
2.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" CAP command. The Calendar Service 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. A UPN with a null Username, but non-
null Realm, such as "@foo.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.
Since 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
Mansour, et al. Expires August 30, 2002 [Page 19]
Internet-Draft Calendar Access Protocol (CAP) March 2002
outside the scope of [CAP].
The "identify" command 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
identifies a group of people, and may be used for group calendar
ownership, or the granting of access rights to a group.
2.5 Roles
CAP defines methods for managing [RFC2445] objects in a Calendar
Store and exchanging [RFC2445] objects for the purposes of group
calendaring and scheduling between "Calendar Users" (CUs) or "User
Groups" (UGs). There are two distinct roles taken on by CUs in CAP.
The CU who creates an initial event or to-do and invites other CUs as
attendees takes on the role of "Organizer". The CUs asked to
participate in the event or to-do take on the role of "Attendee".
Note that "role" is also a descriptive parameter to the "ATTENDEE"
property. Its use is to convey descriptive context to an "Attendee"
such as "chair", "REQ-PARTICIPANT" or "NON-PARTICIPANT" and has
nothing to do with the scheduling workflow.
2.6 CAP URL
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 = scheme ":" [ "//" csid ] [ "/" relcalid ]
scheme = "cap"
csid = hostport ; As defined in Section 3.2.2 of RFC 2396
relcalid = *uric ; As defined in Section 2 of RFC 2396
'relcalid' is an identifier that uniquely identifies a calendar on a
particular calendar store. There is no implied structure in a
Relative CALID. 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
Mansour, et al. Expires August 30, 2002 [Page 20]
Internet-Draft Calendar Access Protocol (CAP) March 2002
cap://cal.example.com/abcd1234QWER
Relative CAP URLs are permitted and are resolved according to the
rules defined in Section 5 of RFC 2396.
Example of a relative CAP URL:
abcd1234QWER
2.7 Calendar Addresses
Calendar addresses can be described as absolute or relative CAP URLs.
Examples:
cap://cal.example.com/abcd1234QWER
abcd1234QWER
For a user currently authenticated to the CAP server on
cal.example.com, these two calendar addresses refer to the same
calendar.
2.8 Extensions to iCalendar
In mapping the calendar query feature, and access rights onto the
iCalendar format, several extended iCalendar properties and
components are defined by this memo.
The search operation makes use of a new component, called VQUERY.
The component consists of a set of new properties: QUERY, EXPAND,
NAME and QUERYID, that define a search filter. VQUERY is used by the
following CAP commands: "search", "modify", "move" and "delete".
Access rights are specified in the new iCalendar VCAR component.
Calendar are specified by the new VAGENDA component.
2.9 Relationship of RFC 2446 (ITIP) to CAP
[iTIP] describes scheduling methods which result in indirect
manipulation of calendar components. In CAP, the "create" command is
used to submit scheduling requests. Other CAP commands such as
"create", "delete", "modify" and "move" provide direct manipulation
of calendar components. In the CAP calendar store model, scheduling
messages are conceptually kept separate from other calendar
components.
Mansour, et al. Expires August 30, 2002 [Page 21]
Internet-Draft Calendar Access Protocol (CAP) March 2002
When scheduling is used, the METHOD is saved along with components.
A scheduled component becomes a booked component when its METHOD
property is set to CREATE. For example, a component whose METHOD is
"REQUEST" is scheduled. The component becomes booked when the METHOD
is set to "CREATE".
Several scheduled entries can be in the CS for the same UID. They
are consolidated when booked, or they are removed from the CS.
For example, if you were on vacation, you could have a REQUEST to
attend a meeting and several updates to that meeting. Your CUA would
have to "search" them out of the CS using CAP, process them,
determine what the final state of the object from a possible
combination of user input and programmed logic. Then the CUA would
instruct the CS to "create" a new booked entry or "modify" an
existing entry. Finally, the CUA can do a "delete" of all of these
now old scheduling requests in the CS. See [iTIP] for details on
resolving multiple [iTIP] scheduling entries.
Mansour, et al. Expires August 30, 2002 [Page 22]
Internet-Draft Calendar Access Protocol (CAP) March 2002
3. Protocol Framework
CAP uses the BEEP application protocol kernel mapped onto TCP (refer
to [BEEP] and [BEEPTCP] for more information). The default port that
the Calendar Service listens for connections on is port --TBD--.
3.1 BEEP Exchange Styles
[BEEP] defines three styles of message exchange:
MSG/ANS,ANS,...,NUL: for one-to-many exchanges.
MSG/RPY: for one-to-one exchanges.
MSG/ERR: for requests the cannot be processed due to an error.
A CAP request, targeted at more than one containers, MUST use a one-
to-many exchange, with a distinct answer associated with each target.
CAP request targeted at a single container MAY use a one-to-one
exchange or a one-to-many exchange. "MSG/ERR" MAY only be used when
an error condition prevents the execution of the request on all the
targeted calendars.
3.2 Use BEEP, MIME and iCalendar
NOTE: This topic is under debate and all CAP commands might drop the
XML wrapper and just send the text/calendar objects and it would
contain the command.
Each BEEP payload exchanged via CAP is a iCalendar MIME content that
fully conforms to [RFC2445].
C: MSG 1 2 . 432 62
C: Content-Type: application/cap+xml
C:
C: <generate-uid num="10"/>
C: END
Otherwise, arbitrary MIME content is included in the BEEP payload
using CDATA.
C: MSG 1 3 . 1023 951
C: Content-type: application/cap+xml
C:
C: <create>
C: <![CDATA[
C: Content-Type: text/calendar
C:
Mansour, et al. Expires August 30, 2002 [Page 23]
Internet-Draft Calendar Access Protocol (CAP) March 2002
C: BEGIN:VCALENDAR
C: METHOD:REQUEST
C: CMDID:abcd12346
C: BEGIN:VEVENT
C: UID:abcd12345
C: ORGAGNIZER:cap://cal.example.com/mary-relcalid
C: ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.example.com/mary-relcalid
C: ATTENDEE;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:cap://cal.example.com/john-relcalid
C: ATTENDEE;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:cap://cal.example.com/bob-relcalid
C: DTSTART:20010920T180000Z
C: DTEND:20010920T190000Z
C: SUMMARY:Mary invites John and Robert
C: END:VEVENT
C: END:VCALENDAR
C: ]]>
C: </create>
C: END
NOTE: From this point on many of the 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
boundries are independant of CAP.
3.3 Bounded Latency
A CUA can associate a maximum latency time to a CAP command with the
"latency" argument. If the CS is unable to complete the request in
the specified amount of time, then the CS sends a "timeout" MSG on
the same channel to which the CUA MUST reply with an "abort" or a
"continue" reply.
Upon receiving an "abort" reply, the CS MUST terminate the command in
progress.
When receiving a "continue" reply the server resumes its work in
progress. Note that a new latency time MAY be included in a
"continue" reply.
The timeout argument and the "action" MUST both be added to the CAP
command, or nether can be added to a command. The "latency" value
MUST BE set to the maximum latency time in seconds. The "action"
argument accepts the following values: "ask" and "abort". If the
maximum latency time is exceeded and the "action" argument is set to
"ask", then CS MUST send a "timeout" message to inform the CUA,
otherwise if the argument "action" is set to "abort" the CS can
directly terminate the request and return a request-status code
2.0.3.
Mansour, et al. Expires August 30, 2002 [Page 24]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Example:
In this example bill@cal.example.com attempts to read a calendar but
the latency time he supplies is not sufficient for the server to
complete the command.
C: MSG 1 4 . 2043 680
C: Content-Type: application/cap+xml
C:
C: <search latency="3" action="ask">
C: <![CDATA[
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: METOD:SEARCH
C: TARGET:relcalid-123
C: CMDID:xyz12346
C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID FROM VEVENT
C: WHERE DTEND >= '19990714T080000Z' AND
C: DTSTART <= '19990715T080000Z'
C: END:VQUERY
C: END:VCALENDAR
C: ]]>
C: </search>
C: END
# After 3 seconds
S: MSG 1 2 . 102 64
S: Content-Type: application/cap+xml
S:
S: <timeout cmdid="xyz12346"/>
S: END
If Bill wants to continue and give the server more time he would
issue a "continue" reply:
C: RPY 1 2 . 166 113
C: Content-Type: application/cap+xml
C:
C: <continue cmdid="xyz12346" latency="3" action="ask"/>
C: END
If instead, Bill wanted to abort the command and not wait any further
he would issue an "abort" reply:
C: RPY 1 2 . 166 62
C: Content-Type: application/cap+xml
Mansour, et al. Expires August 30, 2002 [Page 25]
Internet-Draft Calendar Access Protocol (CAP) March 2002
C:
C: <abort cmdid="xyz12346"/>
C: END
S: RPY 1 4 . 2723 114
S:
S: <request-status code="2.0.3">
S: Request Aborted by the CUA.
S: </request-status>
S: END
Mansour, et al. Expires August 30, 2002 [Page 26]
Internet-Draft Calendar Access Protocol (CAP) March 2002
4. New Value Types
4.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 was based on [SQL92] and [SQLCOM].
NOTE: This grammar is NOT SQL92.
(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 CS's 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 OR one CALSTORE
in the the FROM clause.
(4) Everything in the SELECT and WHERE clauses MUST BE from the
component type, or VAGENDA OR CALSTORE in the FROM clause.
This includes the values from the USING_PROPERTIES and
USING_COMPONENTS clauses.
(5) The '.' is used to separate the table name (component)
and column name (property) when selecting a property that
is contained inside of a component that is targeted in
the TARGET property.
In this example the '.' is used to separate the
TRIGGER property from its contained component (VALARM)
which is contained in any VEVENT in the selected TARGET
(relcalid). All TRIGGER values in any VEVENT in relcalid
would be returned.
TARGET:relcalid
QUERY: SELECT VALARM.TRIGGER FROM VEVENT
(6) A contained component without a '.' it is the same as
<component>.* with the result being a properly formatted
<component>(s) in the data stream, and correctly formatted
Mansour, et al. Expires August 30, 2002 [Page 27]
Internet-Draft Calendar Access Protocol (CAP) March 2002
in the contained component(s) in iCalendar (RFC2445) format.
(a) SELECT VEVENT.<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.
(d) Selects every property and every component
that is in any VEVENT component.
(e) Selects all properties and all contained
components in all VEVENT components that have a VALARM
with a TRIGGER property value between the provided
dates and times.
NOT VALID:
(f) SELECT VEVENET.VALARM.TRIGGER FROM VEVENT
(g) SELECT DTSTART,UID FROM VEVENT WHERE
VTODO.SUMMERY = "Fix typo in CAP"
Note: (g) Is NOT valid because it contains
two '.' characters in the SELECT clause.
(h) Is NOT valid because it mixes VEVENT
and VTODO properties in the same VQUERY.
(7) When multiple QUERY properties are supplied in a single VQUERY
component, the results returned are the same as the results
returned for multipled VQUERY components having each a single
QUERY property.
Formal Definition: The value type is defined by the following
Mansour, et al. Expires August 30, 2002 [Page 28]
Internet-Draft Calendar Access Protocol (CAP) March 2002
notation:
comp-name = "VEVENT" / "VTODO" / "VJOURNAL"
/ "VTIMEZONE" / "VALARM" / "VFREEBUSY"
/ "VAGENDA" / "VCAR" / "CALSTORE"
/ "VQUERY" / iana-name / x-comp
querycomp = queries / ( queryname queries) / queryname
queryname = "QUERYNAME" *(";" xparam) ":" text CRLF
queries = query
/ queries query
query = "QUERY" *(";" xparam) ":" cal-query CRLF
; NOTE: There is exactly one space separating
; the various parts of cal-query
;
cal-query = "SELECT" SP cap-cols SP
"FROM" SP comp-name SP
*(cauprops SP / capcprops SP)
"WHERE" SP cap-expr
/ "SELECT" SP cap-cols SP
"FROM" SP comp-name
capuprops = "USING_PROPERTIES" SP uprop-list
uprop-list = (cap-col SP cap-local)
/ uprop-list SP cap-col SP cap-local
capcprops = "USING_COMPONENTS" SP cprop-list
cprop-list = (cap-comp cap-local)
/ cprop-list SP cap-col SP cap-local
cap-col = ; Any property name found in the component
; named in the comp-tbl used in the FROM clause.
;
; SELECT ORGANIZER FROM VEVENT ...
;
; OR
;
; A component name of an existing component contained
; inside of the cmp-tbl used in the FROM clause.
;
; SELECT VALARM FROM VEVENT ...
Mansour, et al. Expires August 30, 2002 [Page 29]
Internet-Draft Calendar Access Protocol (CAP) March 2002
; NOTE: there is NO space around the "," on
; the next line
cap-cols = cap-col / ( cap-cols "," cap-col)
/ "*"
/
cap-param = ; Any parameter that may be contained in the cap-col
; in the supplied PARAM() function
cap-local = ; Any string that is composed of the characters
; that could be a cap-col name, but is not any
; cap-col name. It is suggested that the
; string start with "my-" to ensure it does not
; conflict with any existing or future cap-col name.
; This name MUST BE defined in the cap-using and
; can only be used in cap-expr of the same query.
; And this name is only known and valid for the
; provided query and only for the lifetime of
; the query. If multiple QUERY properties exist
; in the same component, it is only valid and usable
; in the same QUERY property where it was supplied.
col-value = col-literal
/ "SELF()"
/ "CAL-OWNERS(" cal-address ")"
/ "CURRENT-CALID()"
cal-address = ; A CALID as define by CAP
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
Mansour, et al. Expires August 30, 2002 [Page 30]
Internet-Draft Calendar Access Protocol (CAP) March 2002
; to be treated as wildcard characters.
cap-ucol = cap-col / cap-local
cap-expr = "(" cap-expr ")"
/ cap-term
cap-term = cap-expr SP cap-logical SP cap-expr
/ cap-factor
cap-factor = cap-colval SP cap-oper SP col-value
/ cap-colval SP "NOT LIKE" SP col-value
/ cap-colval SP "LIKE" SP col-value
/ cap-colval SP "IS NULL"
/ cap-colval SP "IS NOT NULL"
/ col-value SP "NOT IN" cap-colval"
/ col-value SP "IN" cap-colval"
cap-colval = cap-ucol
/ "PARAM(" cap-ucol "," cap-param ")"
cap-oper = "="
/ "!="
/ "<"
/ ">"
/ "<="
/ ">="
cap-logical = "AND" / "OR"
SP = ; A single white space ascii character
; (value in HEX %x20).
CRLF = ; As defined in RFC 2445.
xparam = ; As defined in RFC 2445.
x-prop = ; As defined in RFC 2445.
x-comp = ; As defined in RFC 2445.
4.1.1 CAP-QL notes
(1) There is no ORDERBY. Sorting will take place in the order the
columns are supplied in the command.
Mansour, et al. Expires August 30, 2002 [Page 31]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Float and integer values MUST BE sorted by their numeric value.
This means the result of a sort on an integer value type will be:
1, 2, 100, 1000
and not
1, 100, 1000, 2
This means the result of a sort on an float value type will be:
1.1, 2.23, 100.332, 1000.12
and not
1.1, 100.332, 1000.12, 2.23
Date and date time values will be sorted by their equivalent
value in UTC. No matter what the returned time zone in the result
set returns. This is so that if multiple components are returned
each in a unique time zone, the results will be sorted in UTC.
This does not mean the values must be converted to UTC in the
data returned to the CUA. It means the CS must do the sort in UTC.
All other values are sorted according to the locale sorting order
as specified in the calendar. Or the CS locale if the calendar
does not have any locale set, or the host operating system
locale if the CS does not specify a locale. And the locale to
use for the sort is determined in that order.
(2) The CS MUST sort at least the first column.
The CS MAY sort additional columns.
(3) If the cap-cols is only "*" and nothing else, then:
If EXPAND=FALSE sorting will be by the DTSTART value
ascending.
If EXPAND=TRUE sorting will be by the RECURRENCE-ID value
ascending.
If one or more DTSTART or RECURRENCE-ID components have
exactly the same value, the order for those matching
components is unspecified.
If the selected component(s) do not contain a DTSTART
or a RECURRENCE-ID, then the order is unspecified.
Mansour, et al. Expires August 30, 2002 [Page 32]
Internet-Draft Calendar Access Protocol (CAP) March 2002
(4) 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 RFC2445. Any LIKE wildcard characters that are part
of any literal data that is preceded by a LIKE clause and
is not intended to mean wildcard search, MUST BE escaped as
described in note (7) below.
(5) When comparing DATE-TIME to DATE value types and when
comparing DATE to DATE-TIME value types, 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.
VALUE-1 VALUE-2 Compare Results
20020304 20020304T123456 TRUE
(in UTC-3) (in UTC-3)
20020304 20020304T003456 FALSE
(in UTC-4) (in UTC-4)
20020304T003456Z 20020205T003456 FALSE
(in UTC-0) (in UTC-7)
When comparing DATE and DATE-TIME values with the LIKE
clause the comparison will be done as if the value is
a RFC2445 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%').
Again all comparisons will be done in UTC.
Using a LIKE value of "%00%, would return any value that
contained two consecutive zeros.
(6) DTEND and DURATION.
When a QUERY contains a DTEND value, then the CS MUST also
Mansour, et al. Expires August 30, 2002 [Page 33]
Internet-Draft Calendar Access Protocol (CAP) March 2002
evaluate any existing DURATION property value and determine
if it has an effective end time that matches the QUERY
supplied DTEND value or any range of values supplied by
the QUERY.
When a QUERY contains a DURATION value, then the CS MUST
also evaluate any existing DTEND property value and determine
if it has an effective duration that matches the QUERY
supplied DURATION value or any range of values supplied by
the QUERY.
As DTEND is the first time that is excluded from a components
time range, any DURATION supplied by the QUERY that is
exactly one second less than DTEND MUST match the QUERY.
And if the DURATION ends exactly at the computed DTEND it
MUST NOT match.
Any DTEND supplied by the QUERY that is exactly one second
more than an end time computed from a DURATION MUST match the
QUERY. Any end time that is computed from a DURATION that
exactly matches the supplied DTEND MUST NOT match.
(6.1) Given a meeting room reserved with a component
that contains:
DTSTART:20020127T000000Z
DTEND:20020127T010000Z
The reservation is really from:
January 27th, 2002 00:00:00
To:
January 27th, 2002,00:59:59
(6.2) Given another meeting room reserved with a component
that contains:
DTSTART:20020127T000000Z
DURATION:P59M59S
The reservation is really from:
January 27th, 2002 00:00:00
To:
January 27th, 2002,00:59:59
(6.3) A QUERY that contains:
Mansour, et al. Expires August 30, 2002 [Page 34]
Internet-Draft Calendar Access Protocol (CAP) March 2002
... VEVENT.DTSTART = '20020127T00000Z'
AND VEVENT.DTEND = '20020127T010000Z'
MUST match both (6.1) and (6.2).
(6.4) A QUERY that contains:
... VEVENT.DTSTART = '20020127T00000Z'
AND DURATION = 'P59M59S'
MUST match both (6.1) and (6.2).
(7) [NOT] LIKE notes:
The pattern matching characters is the '%' that matches
zero or more characters, and '_' that matches exactly one
character (where character does not always mean octet).
LIKE 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. ('a' = 'A').
If LIKE 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 CONTAINS() element.
And see the examples in the next note (8).
(8) 'col-value SP "NOT IN" cap-colval"
This is similar to the LIKE element, except it does value
Mansour, et al. Expires August 30, 2002 [Page 35]
Internet-Draft Calendar Access Protocol (CAP) March 2002
matching and not string comparison matches.
Some iCalendar objects can be multi instance and multi valued.
The IN operator 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. 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 FOO:parameter=1,2:x One parameter, two values.
d FOO:parameter="1,2",3:y One parameter, two value.
e FOO:parameter=","
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.
'2' IN parameter would match (c) only.
'1,2' IN parameter would match (d) only.
'%,%' IN parameter would match (d) and (e).
LIKE(property, "value1%" would match (a) and (b)
LIKE(property, 'value%') would match (a) and (b)
LIKE(parameter, '1%') would match (c) and (d)
LIKE(parameter, '%2%') would match (c) and (d)
LIKE(parameter, ',') would NOT match any.
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 CONTAINS() element.
If IN is preceded by 'NOT' then there is a match when
the value does not exist in the property or parameter value.
(9) DATE-TIME and TIME values in a WHEN clause.
All DATE-TIME and TIME literal values supplied as in
Mansour, et al. Expires August 30, 2002 [Page 36]
Internet-Draft Calendar Access Protocol (CAP) March 2002
a WHEN 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:
WHERE alarm.TRIGGER < '20020201T000000'
AND alarm.TRIGGER > '20020101T000000'
It is a syntax error and the CS MUST reject the QUERY.
4.2 CAP-QL notes
(1) There is no ORDERBY. Sorting will take place in the order the
columns are supplied in the command.
Float and integer values MUST BE sorted by their numeric value.
This means the result of a sort on an integer value type will be:
1, 2, 100, 1000
and not
1, 100, 1000, 2
This means the result of a sort on an float value type will be:
1.1, 2.23, 100.332, 1000.12
and not
1.1, 100.332, 1000.12, 2.23
Date and date time values will be sorted by their equivalent
value in UTC. No matter what the returned time zone is in the
result set. This is so that if multiple components are returned
each in a unique time zone, the results will be sorted in UTC.
This does not mean the values must be converted to UTC in the
data returned to the CUA. It means the CS must do the sort in UTC.
Mansour, et al. Expires August 30, 2002 [Page 37]
Internet-Draft Calendar Access Protocol (CAP) March 2002
All other values are sorted according to the locale sorting order
as specified in the calendar. Or the CS locale if the calendar
does not have any locale set, or the host operating system
locale if the CS does not specify a locale. And the locale to
use for the sort is determined in that order.
(2) The CS MUST sort at least the first column.
The CS MAY sort additional columns.
(3) If the cap-cols is only "*" and nothing else, then:
If EXPAND=FALSE sorting will be by the DTSTART value
ascending.
If EXPAND=TRUE sorting will be by the RECURRENCE-ID value
ascending.
If one or more DTSTART or RECURRENCE-ID components have
exactly the same value, the order for those matching
components is unspecified.
(4) 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 RFC2445. Any LIKE wildcard characters that are part
of any literal data that is preceded by a LIKE clause and
is not intended to mean wildcard search, MUST BE escaped as
described in note (7) below.
(5) When comparing DATE-TIME to DATE value types and when
comparing DATE to DATE-TIME value types, the result will
be true if the DATE value is on the same day as the DATE-TIME
value (both compared in UTC). And they MUST BE compared in UTC no
matter what time zone the object had been tagged with when the
object was stored in the CS.
VALUE-1 VALUE-2 Compare Results
20020304 20020304T123456 TRUE
(in UTC-3) (in UTC-3)
20020304 20020304T003456 FALSE
(in UTC-4) (in UTC-4)
20020304T003456Z 20020205T003456 FALSE
(in UTC-0) (in UTC-7)
Mansour, et al. Expires August 30, 2002 [Page 38]
Internet-Draft Calendar Access Protocol (CAP) March 2002
When comparing DATE and DATE-TIME values with the LIKE
clause the comparison will be done as if the value is
a RFC2445 DATE or DATE-TIME string value (again in UTC).
LIKE '2002%' will match anything in the year 2002 (UTC).
LIKE '200201%' will match anything in January 2002 (UTC).
LIKE '%T000000' will match anything at midnight (UTC).
LIKE '____01__T%' will match anything for any year or
time that is in January (UTC).
(Four '_', '01', two '_' 'T%').
Again all comparisons will be done in UTC.
Using a LIKE value of "%00%, would return any value that
contained two consecutive zeros.
(6) DTEND and DURATION.
When a VQUERY 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 VQUERY
supplied DTEND value or any range of values supplied by
the VQUERY.
When a VQUERY contains a DURATION value, then the CS MUST
also evaluate any existing DTEND property value and determine
if it has an effective duration that matches the VQUERY
supplied DURATION value or any range of values supplied by
the VQUERY.
As DTEND is the first time that is excluded from a components
time range, any DURATION supplied by the VQUERY that is
exactly one second less than DTEND MUST match the VQUERY.
And if the DURATION ends exactly at the computed DTEND it
MUST NOT match.
Any DTEND supplied by the VQUERY that is exactly one second
more than an end time computed from a DURATION MUST match the
VQUERY. Any end time that is computed from a DURATION that
exactly matches the supplied DTEND MUST NOT match.
(6.1) Given a meeting room reserved with a component
that contains:
DTSTART:20020127T000000Z
Mansour, et al. Expires August 30, 2002 [Page 39]
Internet-Draft Calendar Access Protocol (CAP) March 2002
DTEND:20020127T010000Z
The reservation is really from:
January 27th, 2002 00:00:00
To:
January 27th, 2002,00:59:59
(6.2) Given another meeting room reserved with a component
that contains:
DTSTART:20020127T000000Z
DURATION:P59M59S
The reservation is really from:
January 27th, 2002 00:00:00
To:
January 27th, 2002,00:59:59
(6.3) A VQUERY that contains:
... VEVENT.DTSTART = '20020127T00000Z'
AND VEVENT.DTEND = '20020127T010000Z'
MUST match both (6.1) and (6.2).
(6.4) A VQUERY that contains:
... VEVENT.DTSTART = '20020127T00000Z'
AND DURATION = 'P59M59S'
MUST match both (6.1) and (6.2).
(7) [NOT] LIKE notes:
The pattern matching characters is the '%' that matches
zero or more characters, and '_' that matches exactly one
character (where character does not always mean octet).
LIKE 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 as
Mansour, et al. Expires August 30, 2002 [Page 40]
Internet-Draft Calendar Access Protocol (CAP) March 2002
done in [RFC2445]. 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. ('a' = 'A').
The CS must understand the objects being compared and
understand how to determine how any multi valued property
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.
If LIKE is preceded by 'NOT' then there is a match when
the string compare fails.
(8) [NOT] "CONTAINS(" cap-lhs "," col-literal ")"
This is similar to the LIKE element, except it does value
matching and not string comparison matches.
property:value1,value2
CONTAINS(property, 'value1') would match
CONTAINS(property, 'value') would NOT match
LIKE(property, 'value%') would match
The CS must understand the objects being compared and
understand how to determine how any multi valued property
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 CONTAINS() element.
If CONTAINS() is preceded by 'NOT' then there is a match when
the value does not exist in the property or parameter value.
(9) DATE-TIME and TIME values in a WHEN clause.
All DATE-TIME and TIME literal values supplied as in
a WHEN clause MUST BE terminated with 'Z'. That means
that the CUA MUST supply the values in UTC.
Mansour, et al. Expires August 30, 2002 [Page 41]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Valid:
WHERE alarm.TRIGGER < '20020201T000000Z'
AND alarm.TRIGGER > '20020101T000000Z'
Not valid:
WHERE alarm.TRIGGER < '20020201T000000'
AND alarm.TRIGGER > '20020101T000000'
It is a syntax error and the CS MUST reject the VQUERY.
4.3 Example, Query by UID
The following example would match the entire content of the VEVENT
or VTODO 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 only supports VTODO and
VEVENT.
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
4.4 Query by Date-Time range
This query selects the entire content of every booked VEVENT that has
an instance greater than or equal to July 1st, 2000 00:00:00 UTC and
less than or equal to July 31st, 2000 23:59:59 UTC
BEGIN:VQUERY
EXPAND:TRUE
QUERY:SELECT * FROM VEVENT
WHERE RECURRENCE-ID >= '20000801T000000Z'
AND RECURRENCE-ID <= '20000831T235959Z'
AND METHOD = 'CREATE'
END:VQUERY
Mansour, et al. Expires August 30, 2002 [Page 42]
Internet-Draft Calendar Access Protocol (CAP) March 2002
4.5 Query for all Non-Booked Entries
The following example selects the entire contents of all [ITIP]
non-booked VTODOs and VEVENTs with their METHOD set to one of
the [ITIP] METHODs. The default for EXPAND is FALSE, so the
recurrence rules will not be expanded.
BEGIN:VQUERY
QUERYID:Fetch VEVENT and VTODO iTIP components
NAME;LANG=fr_ca: ...todo...
QUERY:SELECT * FROM VEVENT WHERE
METHOD = 'REQUEST' OR METHOD = 'ADD' OR METHOD = 'PUBLISH' OR
METHOD = 'CANCEL' OR METHOD = 'REPLY' OR METHOD = 'COUNTER' OR
METHOD = 'REFRESH' OR METHOD = 'DECLINECOUNTER'
QUERY:SELECT * FROM VTODO WHERE
METHOD = 'REQUEST' OR METHOD = 'ADD' OR METHOD = 'PUBLISH' OR
METHOD = 'CANCEL' OR METHOD = 'REPLY' OR METHOD = 'COUNTER' OR
METHOD = 'REFRESH' OR METHOD = 'DECLINECOUNTER'
END:VQUERY
In the above exampe, the QUERY property could have been written as:
QUERY:SELECT * FROM VEVENT WHERE METHOD != 'CREATE'
AND METHOD != 'DELETE'
The following example fetches all VEVENT and VTODO booked entries
from the CS.
BEGIN:VQUERY
QUERYID:Fetch All Booked VEVENT and VTODO components
QUERY:SELECT * FROM VEVENT WHERE METHOD = 'CREATE'
QUERY:SELECT * FROM VTODO WHERE METHOD = 'CREATE'
END:VQUERY
The following fetches the UID for all VEVENT and VTODO components
that have been marked for delete (METHOD:DELETE).
BEGIN:VQUERY
QUERYID:Fetch UIDs of marked for delete VEVENTs and VTODOs
QUERY:SELECT UID FROM VEVENT WHERE METHOD = 'DELETE'
QUERY:SELECT UID FROM VTODO WHERE METHOD = 'DELETE'
END:VQUERY
In the examples above they were bunched into groups of similar
queries. They could be performed all at once by having all of
the QUERY property in one BEGIN/END VQUERY component.
Mansour, et al. Expires August 30, 2002 [Page 43]
Internet-Draft Calendar Access Protocol (CAP) March 2002
4.6 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
from February 1st to February 10th 2000.
BEGIN:VQUERY
QUERY:SELECT UID,DTSTART,DESCRIPTION,SUMMARY FROM VEVENT
WHERE DTSTART >= '20000201T000000Z'
AND DTSTART <= '20000210T235959Z'
END:VQUERY
4.7 Components With Alarms In A Range
This example fetches all VEVENTs with an alarm that triggers
within the specified time range. In this case only the UID, SUMMARY,
and DESCRIPTION will be selected for all booked VEVENTS that have an
alarm between the two date-times.
BEGIN:VQUERY
EXPAND:TRUE
QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT
USING_COMPONENT VALARM my-alarm
WHERE my-alarm.TRIGGER >= '20000101T030405Z'
AND my-alarm.TRIGGER <= '20001231T235959Z'
AND METHOD = 'CREATE'
END:VQUERY
Mansour, et al. Expires August 30, 2002 [Page 44]
Internet-Draft Calendar Access Protocol (CAP) March 2002
5. Access Rights
Access rights within CAP are specified with the "VCAR" calendar
component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID"
component properties.
5.1 Access Control and NOCONFLICT
The TRANSP property can take on values (TRANSPARENT-NOCONFLICT,
OPAQUE-NOCONFLICT) that prohibit other events from overlapping it.
This setting overrides access. The ALLOW-CONFLICT Calendar or
component setting may also prevent overlap, returning an error code
"6.3"
Mansour, et al. Expires August 30, 2002 [Page 45]
Internet-Draft Calendar Access Protocol (CAP) March 2002
6. Commands and Responses
CAP commands and responses are described in this section.
As mentioned in Section 3.2, CAP commands are defined by MIME
objects.
The attributes of a command are described in the "Attributes:"
section in the command descriptions below. Similarly the "Elements:"
section describes the elements that compose the command. The
"Response:" section, identifies the responses that may be returned by
the server.
In the examples below, lines preceded with "S:" refer to the server
and lines preceded with "C:" refer to the client. Lines in which the
first non-whitespace character is a "#" are editorial comments and
are not part of the protocol.
6.1 Session Commands
6.1.1 "generate-uid" Command
Attributes:
num: Number of UIDs to generate (1 if omitted).
cmdid: A unique id that identifies this command to
the CUA and CS.
latency: How long before CS asks you to continue. (optional)
action: How to handle latencty - MUST BE suppled but
only when the 'latency' command is supplied.
Response:
"uid-list"
The "generate-uid" command returns one or more unique identifiers
which MUST BE globaly unique.
Example:
C: MSG 1 5 . 2837 60
C: Content-Type: application/cap+xml
C:
C: <generateuid num=5/>
C: END
Mansour, et al. Expires August 30, 2002 [Page 46]
Internet-Draft Calendar Access Protocol (CAP) March 2002
S: RPY 1 5 . 2897 328
S: Content-Type: application/cap+xml
S:
S: <uid-list>
S: <uid>20011121T120000Z-12340@cal.example.com</uid>
S: <uid>20011121T120000Z-12341@cal.example.com</uid>
S: <uid>20011121T120000Z-12342@cal.example.com</uid>
S: <uid>20011121T120000Z-12343@cal.example.com</uid>
S: <uid>20011121T120000Z-12344@cal.example.com</uid>
S: </uid-list>
S: END
6.1.2 "get-capability" Command
Attributes:
None
Elements:
None
Response:
"capability"
The "get-capability" command returns information about the Calendar
Server given the current state of the connection with the client.
The values returned may differ depending on current user identify and
the security level of the connection.
Client implementations SHOULD NOT require any capability element
beyond those defined in this specification, and MAY ignore any non-
standard, experimental capability elements. Non-standard
experimental capability elements MUST be prefixed with the text "x-".
The prefix SHOULD also include a vendor identifier. For example, "x-
foo-barcapability", for the non-standard "barcapability" capability
of the vendor "foo". It may return different results depending on
the UPN.
Capability Occurs Description
-------------------------------------------------------
cap 1 Container for CAP related elements.
cap-version 1+ Version of CAP. MUST include at
Mansour, et al. Expires August 30, 2002 [Page 47]
Internet-Draft Calendar Access Protocol (CAP) March 2002
least "1.0" for this version of
CAP.
prodid 0 or 1 The product id of the CS.
query-level 1+ Indicates level of SQL support.
CAP-QL or NONE. (NONE is for
CS's that allow ITIP methods
only to be deposited and nothing
else). If set to NONE, then the
'car' capability MUST BE set to NONE.
car 1+ Indicates level of CAR support.
CAR-NONE, CAR-MIN or CAR-FULL-1.
If CAR-FUL-1 is supplied then
CAR-MIN MUST BE supplied. CAR = NONE
MUST BE used when query-level of
NONE is supplied. If
date-max 0 or 1 The datetime value in UTC beyond
which the server cannot accept. If
not specified the default is
99991231T235959Z.
date-min 0 or 1 The datetime value prior to which
the server cannot accept. If not
specified the default is
00000101T000000Z.
max-component-size
0 or 1 A positive integer value that specifies
the size of the largest iCalendar
object that the server will accept in
octets. Objects larger than this will be
rejected. The absence of this attribute
indicates no limit. This is also the
maximum value of any BEEP payload
the CS will accept or send.
components 1 A comma seperated list of the names of
components that this CS supports. This
includes any components inside of
other components (VALARM and VEVENT
for example). MUST include at least
VCALSTORE, VCALENDAR, and VAGENDA
and at least one of VEVENT, VTODO,
or VJORNAL.
Mansour, et al. Expires August 30, 2002 [Page 48]
Internet-Draft Calendar Access Protocol (CAP) March 2002
version 1+ Version of iCalendar support.
MUST BE at least "2.0".
supported.
itip-version 1+ Version(s) of ITIP, MUST include at
least "1.0".
recur-accepted 0 or 1 whether the CS accepts recurrence rules
recur-expand 0 or 1 whether or not the CS supports the
expansion of recurrence rules.
recur-limit 0 or 1 the maximum number of occurrences or a recurrence
rule that are expanded by the CS
Example:
C: MSG 1 6 . 3225 57
C: Content-Type: application/beep+xml
C:
C: <get-capability/>
C: END
S: RPY 1 6 . 3282 423
S: Content-Type: application/beep+xml
S:
S:
S: <capability>
S: <version>2.0</version>
S: <max-component-size>65536</max-component-size>
S: <itip-version>1.0</itip-version>
S: <cap-version>1.0</cap-version>
S: <car>CAR-FULL-1</car><car>CAR-MIN</car.
S: <query-level>CAP-QL</query-level>
S: <date-min>00000101T000000Z</date-min>
S: <date-max>99991231T235959Z</date-max>
S: <components>
S: VCALSTORE,VAGENDA,VCALENDAR,VEVENT,X-my-vcomp,VALARM
S: </components>
S: </capability>
S: END
6.1.3 "identify" Command
Attribute:
upn: The UPN of the new identify to assume.
Element:
Mansour, et al. Expires August 30, 2002 [Page 49]
Internet-Draft Calendar Access Protocol (CAP) March 2002
None
Response:
"result" with one of the following request-status codes:
2.0 Successful.
6.4 Identity not permitted.
The "identify" command allows the CUA to set a new identity to be
used for calendar access.
The CS determines through an internal mechanism if the credentials
supplied at authentication permit the assumption of the selected
identity. If they do, the session assumes the new identity,
otherwise a security error is returned.
If
Example:
C: MSG 1 7 . 3705 47
C: Content-Type: application/cap+xml
C:
C: <identify upn="my-alter-ego"/>
C: END
S: RPY 1 7 . 3752 91
S: Content-Type: application/cap+xml
S:
S: <request-status code="2.0"/>
S: END
6.1.4 "noop" Command
Arguments:
None
Element:
None
Response:
Mansour, et al. Expires August 30, 2002 [Page 50]
Internet-Draft Calendar Access Protocol (CAP) March 2002
2.0 successful
This command does nothing. It can be sent to the server periodically
to request that the CS does not time out the session.
Example:
C: MSG 1 7 . 3705 47
C: Content-Type: application/cap+xml
C:
C: <noop/>
C: END
S: RPY 1 7 . 3752 91
S: Content-Type: application/cap+xml
S:
S: <request-status code="2.0"/>
S: END
6.2 Calendaring and Scheduling Commands
6.2.1 Restriction Tables
Calendaring data is sent encapsulated in iCalendar objects The
restriction tables listed in the commands below describe the
composition of the iCalendar data for these commands and replies.
The presence column uses the following values to assert whether a
property is required, is optional and the number of times it may
appear in the iCalendar object. A comment may be provided to further
clarify the presence criteria.
The table below defines the values for the presence column.
Presence
Value Description
--------------------------------------------------------------
1 One instance MUST be present
1+ At least one instance MUST be present
0 Instances of this property MUST NOT be present
0+ Multiple instances MAY be present
0 or 1 Up to 1 instance of this property MAY be present
--------------------------------------------------------------
While the tables list every component and property, their purpose is
not to define the meaning of the component or property.
Mansour, et al. Expires August 30, 2002 [Page 51]
Internet-Draft Calendar Access Protocol (CAP) March 2002
6.2.2 Calendaring Commands
Calendaring commands allow a CUA to directly manipulate a calendar.
Calendar access rights can be granted for the more generalized access
provided by the calendar commands.
There are two kinds of replies. Those that contain an iCalendar
object, and those that do not contain an iCalendar object.
Any reply from the CS that contains an iCalendar object is wrappend
in a <reply> and </reply> tags.
Any reply from the CS that does not contain an iCalendar object is
returned in a <request-status code="x.y"/> tag. And if this reply
includes any cap command replies. Then they are returned wrapped
between <request-status code="x.y"> and </request-status
code="x.y"> tags.
6.2.2.1 "create" Command
Attributes:
"latency" with "action" (optional)
Response:
One "result" iCalendar object per "target" element MUST be
returned (see Section 3.1)
One of the following "request-status" codes MUST be returned:
2.0 - successfully created the component or calendar
6.1 - Target not found
6.3 - Bad args
The "create" command is used to create one or more iCalendar objects.
The TARGET property specify the containers where the component(s)
will be created.
The CDATA portion of the command can be any valid [ITIP] object
or any iCalendar object using the following restriction table.
There MUST BE at least one component inside of the VCALENDAR
object.
Mansour, et al. Expires August 30, 2002 [Page 52]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Restriction table for the "create" command:
Component/Property Presence Comment
------------------- -------- -----------------------------
VCALENDAR 1
. VERSION 1 MUST BE at least 2.0
. TARGET 1+
. METHOD 1 MUST BE the METHOD of the newly
created components.
. CMDID 0 or 1
. [IANA-PROP] 0+ any IANA registered
property
. VAGENDA 0+
. VAGENDA 0+
. . ALLOW-CONFLICT 0 or 1
. . CALMASTER 0 or 1
. . CALSCALE 0 or 1
. . CREATED 0 or 1
. . DEFAULT-CHARSET 0 or 1
. . DEFAULT-LOCALE 0 or 1
. . DEFAULT-TZID 0 or 1
. . LAST-MODIFIED 0 or 1
. . METHOD 0 or 1 The only valid values are
"CREATE" or "DELETE."
. . NAME 0+
. . OWNER 1+
. . RELATED-TO 0+
. . RELCALID 1
. . TZID 0 or 1
. . X-PROPERTY 0+
. . [IANA-PROP] 0+ any IANA registered
property
. . X-COMPONENT 0+
. VCAR 0+
. . . CARID 1
. . . NAME 0+ Note, there MUST NOT be
more than one NAME with
no LANGUAGE parameter,
and there MUST NOT be
more than one NAME with
the same LANGUAGE value.
. . . DECREED 0 This property is outside
the scope of the protocol.
. . . X-PROPERTY 0+
. . . [IANA-PROP] 0+ any IANA registered
property
Mansour, et al. Expires August 30, 2002 [Page 53]
Internet-Draft Calendar Access Protocol (CAP) March 2002
. . . VRIGHT 1+
. . . . PERMISSION 1+
. . . . DENY 0+ Note, there must be at
least one GRANT or DENY
within the VRIGHT.
. . . . GRANT 0+ Note, there must be at
least one GRANT or DENY
within the VRIGHT.
. . . . SCOPE 0+ Note, there must be at
least one SCOPE if
PERMISSION is set to
"READ", "MODIFY",
"DELETE", or "*".
. . . . RESTRICTION 0 or 0+ Note, allowed only if
PERMISSION is set to
"WRITE", "MODIFY", or "*".
. . . . X-PROPERTY 0+
. . . . [IANA-PROP] 0+ any IANA registered
property
. VQUERY 0+
(For VQUERY minimum values - see the VQUERY sections.
Plus each each new VQUERY must have a QUERYID property)
. x-component 0+
Restriction Table for the CDATA section of a reply that contains
an iCalendar object is any valid [ITIP] response plus any from
this restriction table and the VQUERY responses can contain
any iCalendar properties that are wrapped in BEGIN/END VCALENDAR.
There MUST BE at least one component inside of the VCALENDAR
object.
Component/Property Presence Comment
------------------- -------- -------------------------------
VCALENDAR 1+
. VERSION 1 MUST BE at least 2.0
. TARGET 1+
. CMDID 0 or 1
. VAGENDA 0+
. . RELCALID 1
. . REQUEST-STATUS 1+
. VCAR 0+
. . CARID 1
Mansour, et al. Expires August 30, 2002 [Page 54]
Internet-Draft Calendar Access Protocol (CAP) March 2002
. . REQUEST-STATUS 1+
. VQUERY 0+
. . QUERYID 0+ One for each QUERYID supplied in "create"
. . REQUEST-STATUS 1+
(Plus the query results)
. x-component 0+
In the following example, two new top level VAGENDAs are created.
Note that the CSID of the server is cal.example.com.
C: MSG 1 8 . 3843 480
C: Content-Type: application/cap+xml
C:
C: <create>
C: <![CDATA[
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: CMDID:creation01
C: TARGET:cal.example.com
C: BEGIN:VAGENDA <- data for 1st new calendar
C: RELCALID:relcalz1
C: NAME;LANGUAGE=EN-us:Bill's Soccer Team
C: OWNER:bill
C: CALMASTER:mailto:bill@example.com
C: TZID:US/Pacific
C: END:VAGENDA
C: BEGIN:VAGENDA <- data for 2nd new calendar
C: RELCALID:relcalz2
C: NAME;LANGUAGE=EN-us:Mary's personal calendar
C: OWNER:mary
C: CALMASTER:mailto:mary@example.com
C: TZID:US/Pacific
C: END:VAGENDA
C: END:VCALENDAR
C: />]]>
C: END
When there are multiple TARGET'values in the original command object
then the replies MUST BE in the exact same order as they were provided
to the CS. The same is true for the objects created, their responses
MUST BE in the exact same order as they were supplied to the CS.
(With the BEEP header and footer removed)
Mansour, et al. Expires August 30, 2002 [Page 55]
Internet-Draft Calendar Access Protocol (CAP) March 2002
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: CMDID:creation01
S: TARGET:cal.example.com
S: TARGET:cal.example.com
S: BEGIN:VAGENDA <- Reply for 1st calendar create
S: RELCALID:relcalz1
S: REQUEST-STATUS:2.0
S: END:VAGENDA
S: BEGIN:VAGENDA <- Reply for 2nd calendar create
S: RELCALID:relcalz2
S: REQUEST-STATUS:2.0
S: END:VAGENDA
S: END:VCALENDAR
To create a new component in multiple containers simply name
all of the containers in the TARGET in the create command. Here
a new VEVENT is created in two TARGETs. In this example, the
VEVENT is one new iTIP REQUEST object in two calendars. The
results would be iCalendar object that conform to the iTIP
replys as defined in iTIP.
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: CMDID:creation02
C: METHOD:REQUEST
C: TARGET:relcalz1
C: TARGET:relcalz2
C: BEGIN:VEVENT
C: DTSTART:99990307T180000Z
C: UID:abcd12345
C: DTEND:99990307T190000Z
C: SUMMARY:Important Meeting
C: END:VEVENT
C: END:VCALENDAR
The CS reply can be combined when there is exactly one target.
If a <create> command deposited two METHOD:REQUEST objects into
the same target, this could be the reply.
S: <result>
S: <![CDATA[
S: Content-Type: text/calendar
S:
Mansour, et al. Expires August 30, 2002 [Page 56]
Internet-Draft Calendar Access Protocol (CAP) March 2002
S: BEGIN:VCALENDAR
S: CMDID:deposit request
S: TARGET:relcalz1
S: VERSION:2.0
S: BEGIN:VEVENT
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: BEGIN:VEVENT
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: END:VCALENDAR
S: >]]>
S: </result>
6.2.2.2 "move" Command
Attributes:
"cmdid"
Elements:
"max-time": See Section 3.3.
"target": The "target" element points to the container where
the components are to be relocated.
"select": identifies the component(s) to move.
Response:
One "result" message for each "source" in the "select" element
is returned (see Section 3.1).
One of the following "request-status" codes MUST be returned:
2.0 - successfully moved the component or calendar
6.1 - Container not found
6.3 - Bad args
The "data" element of each "result" message is subject to the
result restriction table defined below.
The "move" command is used to move components within the CS's
Mansour, et al. Expires August 30, 2002 [Page 57]
Internet-Draft Calendar Access Protocol (CAP) March 2002
hierarchy of calendars. The access control on the VAGENDA after it
has been moved to its new location in the calstore hierarchy MUST be
at least as secure as it was prior to the move. One way to
accomplish this is to build a list of VCARs that apply to the VAGENDA
in its old hierarchy and and write them into the VAGENDA before
moving it to its new location.
Restriction Table for "data" element of the "result" response:
Component/Property Presence Comment
------------------- -------- -------------------------------
VCALENDAR 1+
. VERSION 1 MUST be 2.0
. VAGENDA 0+
. . RELCALID 1
. . REQUEST-STATUS 1+
. VCAR 0+
. . CARID 1
. . REQUEST-STATUS 1+
. VEVENT 0+
. . UID 1
. . REQUEST-STATUS 1+
. . VALARM 0 if VEVENT was successfully
saved
1+ if there were errors saving
alarms
. . . ALARMID 1
. . . REQUEST-STATUS 1+
. VFREEBUSY 0
. VJOURNAL 0+
. . UID 1
. . REQUEST-STATUS 1+
. VQUERY 0+
. . REQUEST-STATUS 1+
. VTODO 0+
. . UID 1
. . REQUEST-STATUS 1+
. . VALARM 0 if VTODO was successfully
saved
Mansour, et al. Expires August 30, 2002 [Page 58]
Internet-Draft Calendar Access Protocol (CAP) March 2002
1+ if there were errors saving
alarms
. . . ALARMID 1
. . . REQUEST-STATUS 1+
---------------------------------------------------------
Example: moving the VAGENDA Nellis to Area-51
C: MSG 1 12 . 11323 613
C: Content-Type: multipart/related; boundary="boundary-kljr";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary-kljr
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <move id="move01"/>
C: <select>
C: <source csid="cal@example.com" depth=*>
C: <data content="cid:query@cal.example.com"/>
C: </select>
C: <target relcalid="area-51"/>
C: </move>
C: --boundary-kljr
C: Content-Type: text/calendar
C: Content-ID: query@cal.example.com
C:
C: BEGIN:VCALENDAR
C: BEGIN:VQUERY
C: QUERY: SELECT * FROM VAGENDA WHERE RELCALID='Nellis'
C: END:VQUERY
C: END:VCALENDAR
C: --boundary-kljr--
C: END
S: RPY 1 2 . 11936 571
S: Content-Type: multipart/related; boundary="boundary-mnbvd";
S: start="reply@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-mnbvd
S: Content-Type: application/beep+xml
S: Content-ID: reply@cal.example.com
S:
S: <result id="move01">
S: <source csid=cal@example.com depth=*>
Mansour, et al. Expires August 30, 2002 [Page 59]
Internet-Draft Calendar Access Protocol (CAP) March 2002
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-mnbvd
S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S:
S: BEGIN:VCALENDAR
S: BEGIN:VAGENDA
S: RELCALID:Nellis
S: REQUEST-STATUS: 2.0
S: END:VAGENDA
S: END:VCALENDAR
S: --boundary-mnbvd--
S: END
6.2.2.3 "delete" Command
Attributes:
"latency" and "action" (optional see Section xxxx)
Response:
One of the following "request-status" codes MUST be returned
for each target supplied and for each object deleted
as in that target that is effected.
2.0 - successfully deleted the component or calendar
6.1 - Container not found
6.3 - Bad args
The "delete" command is used to delete calendars or components.
The "select" element specifies the container(s) to delete.
Restriction Table for the "delete" command of the "reply"
response.
Component/Property Presence Comment
------------------- -------- -----------------------------
VCALENDAR 1+
. VERSION 1 MUST be at least 2.0
Mansour, et al. Expires August 30, 2002 [Page 60]
Internet-Draft Calendar Access Protocol (CAP) March 2002
. VAGENDA Only if VAGENDAS were
deleted
. CMDID 0+ MUST BE supplied if it was
supplied in the delete command.
. METHOD 1 MUST BE DELETE
. TARGET 1+
. REQUEST-STATUS 1
. VCAR 0+ Only if VCAR components were
deleted
. . CARID 1
. . REQUEST-STATUS 1
. VEVENT 0+ Only if VEVENT components
were targets of deletion.
. . UID 1
. . REQUEST-STATUS 0 or 1 Omitted if an embedded VALARM was
the target of the deletion.
. . VALARM 0+ Only if VALARM components
were targets of deletion.
. . . SEQUENCE 1
. . . REQUEST-STATUS 1
. VFREEBUSY 0+ Only if VFREEBUSY was the target
of deletion.
. . UID 1
. . DTSTAMP 1
. . REQUEST-STATUS 1
. VJOURNAL 0+ Only if VJOURNAL components
were targets of deletion.
. . UID 1
. . REQUEST-STATUS 1
. VQUERY 0+ Only if VQUERY components
were targets of deletion.
. UID 1
. REQUEST-STATUS 1
. VTIMEZONE 0+ Only if VTIMEZONE components
. . TZID were targets of deletion.
. . REQUEST-STATUS 1
. VTODO 0+ Only if VTODO components were
Mansour, et al. Expires August 30, 2002 [Page 61]
Internet-Draft Calendar Access Protocol (CAP) March 2002
targets of deletion.
. . UID 1
. . REQUEST-STATUS 0 or 1 Omitted if an embedded VALARM was
the target of the deletion.
. . VALARM 0+ Only if VALARM components
were targets of deletion.
. . . ALARMID 1
. . . REQUEST-STATUS 1
----------------------------------------------------------
Note: If a VAGENDA is deleted then NONE of its contained
components will return any REQUEST-STATUS responses.
Example to delete a VEVENT with VEVENT UID 'abcd12345' from
the calendar "relcald-22" from the current CS:
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: TARGET:relcalid-22
C: METHOD:DELETE
C: CMDID:random but unique per CAU
C: BEGIN:VQUERY
C: QUERY:SELECT * FROM VEVENT WHERE UID = 'abcd12345'
C: END:VQUERY
C: END:VCALENDAR
One or more iCalendar object will be returned that contain
a REQUEST-STATUS for the deleted components. There could have been
more than one component deleted, Any booked and any
number of unprocessed iTIP scheduling components that
matched the QUERY value in the above example. Each
unique METHOD that was deleted from the store MUST BE in a
seperate iCalendar object. This is because only one METHOD is allowed
in an iCalendar object.
6.2.2.4 "modify" Command
Attributes:
"latency" and "action" (Optional - see xxx)
Response:
Mansour, et al. Expires August 30, 2002 [Page 62]
Internet-Draft Calendar Access Protocol (CAP) March 2002
One of the following "request-status" codes MUST be returned:
2.0 - successfully modified the component or calendar
6.1 - Container not found
6.3 - Bad args
The "modify" command is used to modify existing components. The
TARGET property specifies the calendars were the components
exist that are going to be modified.
The format of the request is three containers inside of VCALENDAR
container object:
BEGIN:VCALEDNAR
<VQUERY>
<OLD-VALUES>
<NEW-VALUES>
END:CALENDAR
The VQUERY selects the components that are to be modified.
The OLD-VALUES is a component and the contents of that component
are going to change and may contain information that helps uniquely
identify the original component (SEQUENCE in the example below).
If the CS can not find a component that matches the QUERY and does
not have at least all of the OLD-VALUES, then a 6.1 error is returned.
The NEW-VALUES is a component of the same type as OLD-VALUES and
NEW-VALUES contains the new data for each selected component. Any
data that is in OLD-VALUES and not in NEW-VALUES is deleted from
the selected component. Any values in NEW-VALUES that was not in
OLD-VALULES is added to the component.
In this example the VEVENT with UID:unique-58 has; the LOCATION and
LAST-MODIFIED changed, the VALARM with SEQUENCE:3 has its
TRIGGER disabled, the X-LOCAL property is removed from the VEVENT,
and a COMMENT is added.
Because SEQUENCE is used to locate the VALARM in this example,
both the OLD-VALUES and the NEW-VALUES contains SEQUENCE:3 and
if SEQUENCE was left out of NEW-VALUES - it would have been deleted.
Example:
C: Content-Type: text/calendar
C: BEGIN:VCALENDAR
Mansour, et al. Expires August 30, 2002 [Page 63]
Internet-Draft Calendar Access Protocol (CAP) March 2002
C: VERSION:2.0
C: TARGET:my-cal
C: METHOD:MODIFY
C: BEGIN:VQUERY
C: QUERY:SELECT * FROM VEVENT WHERE UID = 'unique-58'
C: END:VQUERY
C: BEGIN:VEVENT
C: LOCATION:building 3
C: LAST-MODIFIED:20020101T123456Z
C: X-LOCAL:some private stuff
C: BEGIN:VALARM
C: SEQUENCE:3
C: TRIGGER;RELATED=END:PT5M
C: END:VALARM
C: END:VEVENT
C: BEGIN:VEVENT
C: LOCATION:building 4
C: LAST-MODIFIED:20020202T010203Z
C: COMMENT:Ignore global trigger.
C: BEGIN:VALARM
C: SEQUENCE:3
C: TRIGGER;ENABLE=FALSE:RELATED=END:PT5M
C: END:VALARM
C: END:VEVENT
C: />]]>
C: </modify>
C: END
X-LOCAL was not supplied in the NEW-VALUES, so it was deleted.
LOCATION was altered, as was LAST-MODIFIED. The VALARM with
SEQUENCE:3 had its TRIGGER disabled, and SEQUENCE did not
change so it was not effected. COMMENT was added.
When it comes to inline ATTACHMENTs, the CUA only needs to uniquely
identify the contents of the ATTACHE value in the OLD-VALUES in order
to delete them. When the CS compares the attachment data it is compared
in it binary form. The ATTACHMENT value supplied by the CUA MUST BE
valid encoded information.
For example, to delete a huge inline attachment from every
VEVENT in 'my-cal' that has an ATTACH with the OLD-VALUES:
BEGIN:VCALENDAR
VERSION:2.0
TARGET:my-cal
METHOD:MODIFY
BEGIN:VQUERY
QUERY:SELECT ATTACH FROM VEVENT
Mansour, et al. Expires August 30, 2002 [Page 64]
Internet-Draft Calendar Access Protocol (CAP) March 2002
END:VQUERY
BEGIN:VEVENT
ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY:
MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U
EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE
...<remander of attachment data NOT supplied> ....
END:VEVENT
BEGIN:VEVENT
END:VEVENT
END:VCALENDAR
Above the NEW-VALUES is empty, so everything in the OLD-VALUES
is deleted.
Furthermore, the following additional restrictions apply:
One can not change the "UID" property of a component.
If a contained component is changed inside of a selected
component, and that contained component has multiple
instances, then OLD-VALUES MUST contain information that
uniquely identifies the instance or instances that are
changing.
As all contained components that matching OLD-VALUES will be
modified. In the first modify example above, if SEQUENCE were
to be deleted from both the OLD-VALUES and NEW-VALUES, then all
TRIGGERs that matched the OLD-VALUES in all VALARM in the
selected VEVENTs would be disabled.
The result of the modify MUST BE a valid iCalendar object.
If the REQUEST-STATUS is 2.0, then the entire modification was
successful.
If any error occurred:
No component will be changed at all. That is, it will
appear just as it was prior to the modify and the CAP server
SHOULD return a REQUEST-STATUS for each error that occurred.
There MUST BE at least one error reported.
If multiple components are selected, then the UID for each selected
component MUST BE returned if the component contains a UID:
S: Content-Type: text/calendar
S:
Mansour, et al. Expires August 30, 2002 [Page 65]
Internet-Draft Calendar Access Protocol (CAP) March 2002
S: BEGIN:VCALENDAR
S: TARGET:relcalid
S: BEGIN:VEVENT
S: UID:123
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: END:VCALENDAR
6.2.2.5 "search" Command
Attributes:
"latency" and "action" (Optional - see xxx)
Response:
One iCalendar message per "target" in the "select" element is
returned (see Section xxx).
One of the following "request-status" codes MUST be returned:
2.0 - successfully executed the query
2.0.9 - success, but some data could not be returned
6.1 - Container not found
6.3 - Bad args
The data in each result contains an iCalendar object composed
of all the selected components. Only "REQUEST-STATUS"
and the properties mentioned in the "SELECT" clause of the
QUERY are included in the components. Each iCalendar object is
tagged with the TARGET property and optional CMDID property.
Searching for Events
In the example below events on March 10,1999 between 080000Z and
190000Z are read. In this case only 4 properties for each event are
returned. Two calendars are specified. Only booked (vs scheduled)
entries are to be returned.
NOTE: BEEP headers and footers not included in the examples below.
C: Content-Type: text/calendar
Mansour, et al. Expires August 30, 2002 [Page 66]
Internet-Draft Calendar Access Protocol (CAP) March 2002
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: METHOD:SEARCH
C: CMDID:search01
C: TARGET:relcal2
C: TARGET:relcal3
C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID
C: FROM VEVENT
C: WHERE DTEND >= '19990310T080000Z'
C: AND DTSTART <= '19990310T190000Z'
C: AND METHOD IS 'CREATE'
C: END:VQUERY
C: END:VCALENDAR
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: METHOD:REPLY
S: TARGET:relacal2
S: CMDID:search01
S: REQUEST-STATUS:2.0
S: BEGIN:VEVENT
S: DTSTART:19990310T090000Z
S: DTEND:19990310T100000Z
S: UID:abcxyz12345
S: SUMMARY:Meet with Sir Elton
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: BEGIN:VEVENT
S: DTSTART:19990310T130000Z
S: DTEND:19990310T133000Z
S: UID:abcxyz8999
S: SUMMARY:Meet with brave Sir Robin
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: END:VCALENDAR
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: METHOD:REPLY
S: CMDID:search01
S: TARGET:relcal3
S: REQUEST-STATUS:2.0
Mansour, et al. Expires August 30, 2002 [Page 67]
Internet-Draft Calendar Access Protocol (CAP) March 2002
S: BEGIN:VEVENT
S: REQUEST-STATUS:2.0
S: DTSTART:19990310T140000Z
S: DTEND:19990310T150000Z
S: UID:123456asdf
S: SUMMARY:Summer Budget
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: END:VCALENDAR
The return values are subject to VCAR filtering. That is, if the
request contains properties to which the UPN does not have access,
those properties will not appear in the return values. If the UPN
has access to at least one property of the component, but has been
denied access to all properties called out in the request, the
response will contain a single REQUEST-STATUS property indicating the
error. That is, the VEVENT components will be the following:
Here the request was successful, but the VEVENT contents
were not accessable (4.1).
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: METHOD:REPLY
S: TARGET:relcalid
S: CMIDID=any-id
S: VERSION:2.0
S: BEGIN:VEVENT
S: REQUEST-STATUS:4.1
S: END:VEVENT
S: END:VCALENDAR
If the UPN has no access to any components at all, the response will
simply be an empty data set. The response looks the same if there
the particular components did not exist.
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: METHOD:REPLY
S: CMDID:some-id
S: TARGET:ralcalid
S: REQUEST-STATUS:2.0
S: END:VCALENDAR
Find alarms within a range of time for booked VEVENTs.
Mansour, et al. Expires August 30, 2002 [Page 68]
Internet-Draft Calendar Access Protocol (CAP) March 2002
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: METHOD:SEARCH
C: TARGET:"Doug:Baseball"
C: TARGET:"Steve:Baseball"
C: CMDID:search02
C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID,VALARM
C: FROM VEVENT,VTODO
C: USING_COMPONENT VALARM my-alarm
C: WHERE my-alarm.TRIGGER >= '19990310T080000Z'
C: AND my-alarm.TRIGGER <= '19990310T190000Z'
C: AND METHOD = 'CREATE'
C: END:VQUERY
C: END:VCALENDAR
Here no data was returned for relcal2:
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: TARGET:relcal2
S: CMDID:search02
S: METHOD:REPLY
S: REQUEST-STATUS:X.Y <- todo
S: END:VCALENDAR
And here relcal3 did return some resuls:
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: METHOD:REPLY
S: TARGET:relcal3
S: CMDID:search02
S: REQUEST-STATUS:2.0
S: BEGIN:VEVENT
S: DTSTART:19990310T130000Z
S: DTEND:19990310T133000Z
S: UID:abcxyz8999
S: SUMMARY:Meet with brave Sir Robin
S: BEGIN:VALARM
S: TRIGGER:19990310T132500Z
S: SUMMARY:Almost time...
Mansour, et al. Expires August 30, 2002 [Page 69]
Internet-Draft Calendar Access Protocol (CAP) March 2002
S: ACTION:DISPLAY
S: END:VALARM
S: END:VEVENT
S: END:VCALENDAR
In this example bill@example.com reads a day's worth of events from
cap://cal.example.com/opaqueid99. And the optional cmdid is not
supplied as the CUA will not issue another command until this
one completes.
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: METHOD:SEARCH
C: TARGET:opaqueid99
C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY, UID FROM VEVENT
C: WHERE DTEND >= '19990714T080000Z'
C: AND DTSTART <= '19990715T080000Z'
C: END:VQUERY
C: END:VCALENDAR
If there are multiple targets, each iCalendar reply is contained
within its own <reply>.
Stored VQUERY can be used by specifying the property QUERYID
instead of QUERY.
This matches all calendar store properties. This MUST NOT return any
VAGENDAs. IT would return all RELATED-TO properties.
BEGIN:VCALENDAR
VERSION:2.0
METHOD:SEARCH
TARGET:cap://bobo.ex.com
BEGIN:VQUERY
QUERY:SELECT * FROM VCALSTORE
END:VQUERY
END:VCALENDAR
This will match all properties of the VAGENDA relcal4. This MUST NOT
return any components.
BEGIN:VCALENDAR
VERSION:2.0
METHOD:SEARCH
TARGET:cap://bobo.ex.com/relcal4
BEGIN:VQUERY
QUERY:SELECT * FROM VAGENDA
Mansour, et al. Expires August 30, 2002 [Page 70]
Internet-Draft Calendar Access Protocol (CAP) March 2002
END:VQUERY
END:VCALENDAR
This will fetch all stored VQUERYs. All stored queries MUST BE
saved with a QUERYID.
BEGIN:VCALENDAR
VERSION:2.0
METHOD:SEARCH
TARGET:relcal4
BEGIN:VQUERY
QUERY:SELECT VQUERY.* FROM VQUERY.
END:VQUERY
END:VCALENDAR
6.2.2.6 Response Codes
Numeric response codes are returned at both the transfer and
application layer. The same set of codes is used in both cases.
The format of these codes is described in [RFC2445], and extend in
[iTIP] and [iMIP]. The following describes new codes added to this
set.
At the application layer response codes are returned as the value of
a "REQUEST-STATUS" property. The value type of this property is
modified from that defined in [RFC2445], to make the accompanying
text optional.
Code Description
--------------------------------------------------------------
2.0 Success. The parameters vary with the
operation and are specified.
2.0.3 In response to the client issuing an
"abort" reply, this reply code indicates
that any command currently underway was
successfully aborted.
2.0.9 Success of the read operation, but some
requested information could not be returned
due to access control.
3.1.4 Capability not supported.
4.1 Calendar store access denied.
Mansour, et al. Expires August 30, 2002 [Page 71]
Internet-Draft Calendar Access Protocol (CAP) March 2002
6.3 Attempt to create or modify an event
such that it would overlap another event
in either of the following two circum-
stances:
(a) One of the events has a TRANSP
property set to OPAQUE-NOCONFLICT or
TRANSPARENT-NOCONFLICT.
(b) The calendar's ALLOW-CONFLICT
property is set to NO.
6.XXX [EDITORS NOTE: More are in this memo -
add here TODO]
7.0 A timeout has occurred. The server was
unable to complete the operation in the
requested time.
8.0 A failure has occurred in the Calendar Service
that prevents the operation from
succeeding.
8.2 Used to signal that an iCalendar object has
exceeded the server's size limit
8.3 A DATETIME value was too far in the future
represented on this Calendar.
8.4 A DATETIME value was too far in the past
to be represented on this Calendar.
8.5 An attempt was made to create a new
object but the unique id specified is
already in use.
9.0 An unrecognized command was received.
10.4 The operation has not been performed
because it would cause the resources
(memory, disk, CPU, etc) to exceed the
allocated quota.
--------------------------------------------------------------
Mansour, et al. Expires August 30, 2002 [Page 72]
Internet-Draft Calendar Access Protocol (CAP) March 2002
7. Initial Registrations
7.1 BEEP Profile Registration
Profile Identification: http://iana.org/beep/transient/calsch/
cap/1.0
Messages exchanged during Channel Creation: none
Messages starting one-to-one exchanges:
"timeout", "generate-uid", "identify", "get-capability"
Messages in positive replies:
"uid-list", "abort", "continue", "result", "capability"
Messages in negative replies:
"error"
Messages in one-to-many exchanges: "create", "search",
"delete", "modify" or "schedule"
Message Syntax: c.f., Section 8
Message Semantics: c.f., Section 6
Contact Information: c.f., the "Author's Address" section of
this memo
7.2 Registration: The System (Well-Known) TCP port number for CAP
A single well-known port (xxxx) is allocated to CAP.
Protocol Number:
TCP
Message Formats, Types, Opcodes, and Sequences:
Section 8
Functions:
Section 6
Mansour, et al. Expires August 30, 2002 [Page 73]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Use of Broadcast/Multicast:
none
Proposed Name:
Calendar Access Protocol
Short name:
cap
Contact Information:
cf., the "Authors' Addresses" section of this draft
Mansour, et al. Expires August 30, 2002 [Page 74]
Internet-Draft Calendar Access Protocol (CAP) March 2002
8. CAP DTD
To Be Done.
Mansour, et al. Expires August 30, 2002 [Page 75]
Internet-Draft Calendar Access Protocol (CAP) March 2002
9. Properties
[Once definitions are in iCalendar format and are agreed on, should
be moved into section "Extension to iCalendar"]
9.1 Calendar Store Properties
The following are properties of the calendar store.
Name Read Value Description
Only Type
--------------------------------------------------------------
CALMASTER N URI URL of contact address for person
responsible. SHOULD BE
mailto URL.
CSID Y URI The CSID of this calendar
store. If not specified, it is
the same as the hostname.
DEFAULT_VCARS N TEXT A multivalued property
containing the default VCARs
for newly created top level
calendars. Each entry is a
CARID. It MUST include at a
minimum
READBUSYTIMEINFO,REQUESTONLY,
UPDATEPARTSTATUS, and
DEFAULTOWNER.
MAXDATE Y DATE-TIME The date/time in the future
beyond which the server cannot
represent. If not specified,
then 99991231T235959 will be
assumed.
MINDATE Y DATE-TIME The date/time in the past prior
to which the server cannot
represent. If not specified,
then 00000101T000000 will be
assumed.
CURRENT_DATETIME Y DATE-TIME Current server time. This is
returned as a local time and
TZID.
RECUR_ACCEPTED Y BOOLEAN Boolean value will be set to
TRUE if the server will accept
Mansour, et al. Expires August 30, 2002 [Page 76]
Internet-Draft Calendar Access Protocol (CAP) March 2002
recurrence rules. It will be
set to FALSE if the server will
not accept recurrence rules. If
not specified a CUA MUST assume
TRUE.
RECUR_EXPAND Y BOOLEAN If set to TRUE, the CS supports
the expansion of recurrence
rules in the returned set. If set
to FALSE, the CS is incapable
of expanding recurrence rules.
If not specified a CUA MUST assume
TRUE.
RECUR_LIMIT Y INTEGER This numeric value describes
how the server handles
unbounded recurrences. The
value is only valid if
RECURRENCE is TRUE. If the
value is 0 it means that the
server supports unbounded
recurrence rules. If it is non-
zero, it is a positive integer
indicating the number of
instances that will be returned
when the server expands an
unbounded recurrence rule when
fetched from the CS. A CUA MUST
query for date ranges when this
value is zero.
VERSION Y TEXT The version of the CS. The
default and the only currently
Supported version is "2.0" to
match the [RFC2445] VERSION.
9.2 Calendar Properties
Name Read Value Description
Only Type
--------------------------------------------------------------
ALLOW-CONFLICT N BOOLEAN This boolean value indicates
Whether or not the calendar
supports event conflicts. That
is, whether or not any of the
events in the calendar can
overlap. If not specified the
Mansour, et al. Expires August 30, 2002 [Page 77]
Internet-Draft Calendar Access Protocol (CAP) March 2002
default value is TRUE meaning
that conflicts are allowed.
CALSCALE N TEXT The CALSCALE for this calendar.
If not specified the default is
GREGORIAN.
CHARSET N TEXT The default charset for
Localized strings in this
calendar. If not specified, the
default is UTF-8.
CHILD Y TEXT A sub-calendars belonging to this
calendar. A calendar may have
multiple sub-calendars, each one
corresponding to a CHILD property.
CREATED Y DATE-TIME The timestamp of the calendar's
create date.
DEFAULT_VCARS N TEXT The default VCARs for newly
Created top level calendars.
This is a CARID. The default
value is the value of
DEFAULT_VCARS in the VCALSTORE
table.
LANGUAGE N TEXT The default language for
localizable strings in this
calendar. There is no default.
This value MUST NOT be empty.
The possible values of this
property are those specified in
RFC-3066.
LAST-MODIFIED N DATE-TIME The timestamp when the
Properties of the calendar were
last updated. Default is the
same as CREATED.
NAME N TEXT The display name for this
calendar. It is a localizable
string. If not provided, an
empty value will be returned.
OWNER N URI A multi-instanced property
indicating the calendar owner.
Each entry returned will be a
Mansour, et al. Expires August 30, 2002 [Page 78]
Internet-Draft Calendar Access Protocol (CAP) March 2002
UPN. There must be at least one
owner.
PARENT N URI The CALID of this calendar's
Parent maintained by a CAP
server. An empty value means
the calendar is the top level
parent. The default value is no
parent.
RELCALID N URI A unique identifier within this
cal-store for the calendar.
There is no default value.
This value MUST NOT be empty.
TOMBSTONE N BOOLEAN TRUE indicator that this
Calendar has been marked as
deleted. The default value is
FALSE.
TZID N TEXT The id of the timezone
Associated with this calendar.
See TZID in [RFC2445]. The default
value is UTC.
Mansour, et al. Expires August 30, 2002 [Page 79]
Internet-Draft Calendar Access Protocol (CAP) March 2002
10. Security Considerations
Access rights should be granted cautiously, consult Section 2.4.2 for
a discussion of the subject.
The "identify" command should be carefully implemented as discussed
in Section 6.1.3.
In addition, since CAP is a profile of the BEEP, consult [BEEP]'s
Section 9 for a discussion of BEEP-specific security issues.
Although service provisioning is a policy matter, at a minimum, all
implementations must provide the following tuning profiles:
for authentication: http://iana.org/beep/SASL/DIGEST-MD5
for confidentiality: http://iana.org/beep/TLS (using the
TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher)
for both: http://iana.org/beep/TLS (using the
TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher supporting client-side
certificates)
Mansour, et al. Expires August 30, 2002 [Page 80]
Internet-Draft Calendar Access Protocol (CAP) March 2002
11. Extensions To iCalendar
The following section contains new components, properties,
parameters, and values.
11.1 Property Value Data Types
11.1.1 UPN
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME value type UPN
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
Description: This data type is an identifier that denotes a CU or a
group of CU. A UPN is a RFC 2822 compliant e-mail 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 as there is no requirement that a
person's UPN must be his e-mail address.
In certain cases a UPN will not be RFC 2822 compliant. When
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.
Example:
The following is a UPN for a CU:
jdoe@acme.com
The following is a UPN for a group of CU:
Mansour, et al. Expires August 30, 2002 [Page 81]
Internet-Draft Calendar Access Protocol (CAP) March 2002
staff@acme.com
The following is a UPN for an anonymous CU belonging to
@acme.com
The following is a UPN for an anonymous CU:
@
11.1.2 UPN Filter
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME value type UPN-FILTER
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:
upn-filter = "OWNER" /
"NONOWNER" /
"*" /
[ "*" / 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).
Example: The following are examples of this value type:
OWNER Matches the UPNs equal to any instance
of the OWNER property of the VAGENDA in
which the encapsulating VCAR is stored.
NONOWNER Matches all UPNs different from all
instances of the OWNER property of the
VAGENDA in which the encapsulating VCAR
is stored.
* Matches all UPNs.
@ Matches the UPN of anonymous CUs
Mansour, et al. Expires August 30, 2002 [Page 82]
Internet-Draft Calendar Access Protocol (CAP) March 2002
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@* Matches the UPN of the specified CU
belonging to any non-null realm
11.2 Calendar Components
11.2.1 Agenda Component
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME component VAGENDA
Component Name: VAGENDA
Purpose: Provide a grouping of component properties that defines an
agenda.
Formal Definition: A "VAGENDA" calendar component is defined by the
following notation:
agendac = "BEGIN" ":" "VAGENDA" CRLF
agendaprop
"END" ":" "VAGENDA" CRLF
agendaprop = *(
; the following MUST occur exactly once
created / recalid / last-mod /
; the following MUST occur at least once
Mansour, et al. Expires August 30, 2002 [Page 83]
Internet-Draft Calendar Access Protocol (CAP) March 2002
owner /
; the following are optional,
; but MUST NOT occur more than once
allow-conflict / calscale / default-charset / default-locale /
method / default-tzid /
; the following are optional,
; and MAY occur more than once
name / related / iana-token / x-prop / x-comp
)
Example: The following is an example of this component:
BEGIN:VAGENDA
CREATED:20020121T123149Z
NAME:Work Calendar
OWNER:john@example.calendar.com
RECALID:lhdi98dey6
LAST-MODIFIED:20020210T152301Z
ALLOW-CONFLICT:FALSE
METHOD:DELETE
END:VAGENDA
11.2.2 Calendar Store Component
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME component VCALSTORE
Component Name: VCALSTORE
Purpose: Provide a grouping of component properties that defines a
calendar store.
Formal Definition: A "VCALSTORE" calendar component is defined by the
following notation:
calstorec = "BEGIN" ":" "VCALSTORE" CRLF
calstoreprop
"END" ":" "VCALSTORE" CRLF
calstoreprop = *(
; the following MUST occur exactly once
Mansour, et al. Expires August 30, 2002 [Page 84]
Internet-Draft Calendar Access Protocol (CAP) March 2002
calmaster / current-datetime /
; the following must occur at least once
default-vcar /
; the following are optional,
; but MUST NOT occur more than once
maxdate / mindate / recur-accepted / recur-expand /
recur-limit / csid /
; the following are optional,
; and MAY occur more than once
iana-token / x-prop / x-comp / vcard
)
Example: The following is an example of this component:
BEGIN:VCALSTORE
CALMASTER:mailto:admin@example.calendar.com
DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY
DEFAULT-VCARS:UPDATEPARTSTATUS,DEFAULTOWNER
CSID:example.calendar.com
END:VCALSTORE
11.2.3 Calendar Access Right Component
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME component VCAR
Component Name: "VCAR"
Purpose: Provide a grouping of calendar access rights.
Format Definition: A "VCAR" calendar component is defined by the
following notation:
carc = "BEGIN" ":" "VCAR" CRLF
carprop 1*rightc
"END" ":" "VCAR" CRLF
carprop = 1*(
Mansour, et al. Expires August 30, 2002 [Page 85]
Internet-Draft Calendar Access Protocol (CAP) March 2002
; 'carid' is REQUIRED,
; but MUST NOT occur more than once
carid /
; the following are OPTIONAL,
; and MAY occur more than once
name / x-prop / iana-prop
)
Description: A "VCAR" calendar component is a grouping of component
properties, and "VRIGHT" calendar components, that represents access
rights granted or denied to calendar users.
The "CARID" property specifies the local identifier for the "VCAR"
calendar component. The "NAME" property specifies a localizable
display name.
Example: In the following example, the UPN "foo@host.com" is given
read access to the "DTSTART" and "DTEND" VEVENT properties. No other
access is specified:
BEGIN:VCAR
CARID:xyzzy-001
NAME:View Start and End Times
BEGIN:VRIGHT
GRANT:foo@host.com
PERMISSION:READ
SCOPE:SELECT DTSTART,DTEND FROM VEVENT
END:VRIGHT
END:VCAR
In this example, all UPNs are given read access to "DTSTART" and
"DTEND" properties of VEVENT components. "All CUs and UGs" are
specified by the UPN value "*". Note that this enumerated UPN value
is not in quotes:
BEGIN:VCAR
CARID:xyzzy-002
NAME:View Start and End Times 2
BEGIN:VRIGHT
GRANT:*
PERMISSION:READ
SCOPE:SELECT DTSTART,DTEND FROM VEVENT
END:VRIGHT
END:VCAR
Mansour, et al. Expires August 30, 2002 [Page 86]
Internet-Draft Calendar Access Protocol (CAP) March 2002
In this example, rights are specified for all UPNs to read VEVENT
components classified as PUBLIC:
BEGIN:VCAR
CARID:xyzzy-003
NAME:View PUBLIC Start and End Times
BEGIN:VRIGHT
GRANT:*
PERMISSION:READ
SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC'
END:VRIGHT
END:VCAR
In this example, rights are specified for all UPNs to read or modify
existing VEVENT components classified as PUBLIC:
BEGIN:VCAR
CARID:xyzzy-004
NAME:Read and Modify PUBLIC Calendar Entries
BEGIN:VRIGHT
GRANT:*
PERMISSION:READ
PERMISSION:MODIFY
SCOPE:SELECT * FROM VEVENT WHERE CLASS = 'PUBLIC'
END:VRIGHT
END:VCAR
In these examples, full calendar access rights are given to the
OWNER, and a hypothetical administrator is given access rights to
specify calendar access rights. If no other rights are specified,
only these two UPNs can specify calendar access rights:
BEGIN:VCAR
CARID:xyzzy-005
NAME:Only OWNER or ADMIN Settable CARs
BEGIN:VRIGHT
GRANT:OWNER
PERMISSION:*
SCOPE:SELECT * FROM VAGENDA
END:VRIGHT
BEGIN:VRIGHT
GRANT:cal-admin@host.com
PERMISSION:*
SCOPE:SELECT * FROM VCAR
RESTRICTION:SELECT * FROM VCAR
END:VRIGHT
END:VCAR
Mansour, et al. Expires August 30, 2002 [Page 87]
Internet-Draft Calendar Access Protocol (CAP) March 2002
In this example, rights to write, read, modify or delete calendar
access rights are denied to all UPNs. This example would disable
providing different access rights to the calendar store or calendar.
This calendar access right should be specified with great care, as it
remove the ability to change calendar access; even for the owner or
administrator:
BEGIN:VCAR
CARID:xyzzy-006
NAME:No CAR At All
BEGIN:VRIGHT
DENY:*
PERMISSION:*
SCOPE:SELECT * FROM VCAR
END:VRIGHT
END:VCAR
11.2.4 VRIGHT Calendar Component
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME component VRIGHT
Component Name: "VRIGHT"
Purpose: Provide a grouping of component properties that describe an
access right.
Format Definition: A "VRIGHT" calendar component is defined by the
following notation:
rightc = "BEGIN" ":" "VRIGHT" CRLF
rightprop
"END" ":" "VRIGHT" CRLF
rightprop = 2*(
; either 'grant' or 'deny' MUST
; occur at least once
; and MAY occur more than once
grant / deny /
; 'permission' MUST occur at least once
; and MAY occur more than once
permission /
Mansour, et al. Expires August 30, 2002 [Page 88]
Internet-Draft Calendar Access Protocol (CAP) March 2002
; the following are optional,
; and MAY occur more than once
scope / restriction / x-prop / iana-prop
)
Description: A "VRIGHT" calendar component is a grouping of calendar
access right component properties.
The "GRANT" property specifies the CU or UG to whom a calendar access
right is granted. The "DENY" property specifies the CU or UG to whom
a calendar access right is denied. The "PERMISSION" property
specifies the actual permission being set. The "SCOPE" property
identifies the calendar store properties, calendar properties,
calendar components, component properties to which the access right
applies. The "RESTRICTION" property specifies restriction on the
value that may take calendar store properties, calendar properties,
calendar components, and component properties after a WRITE or MODIFY
operation. Values MUST match all the instances of the RESTRICTION
property to be valid.
11.3 Component Properties
The following properties can appear within calendar components, as
specified by each component property definition.
11.3.1 Allow-Conflict Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property ALLOW-CONFLICT
Property Name: ALLOW-CONFLICT
Purpose: This property indicates whether or not the calendar 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" calendar
component.
Description: In a "VAGENDA", this property is used to indicate
Mansour, et al. Expires August 30, 2002 [Page 89]
Internet-Draft Calendar Access Protocol (CAP) March 2002
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.
Format Definition: The property is defined by the following notation:
allow-conflict = "ALLOW-CONFLICT" allowconflictparam ":" boolean
CRLF
allowconflictvalue = *(";" xparam)
Example: The following is an example of this property for a "VAGENDA"
calendar component:
ALLOW-CONFLICT:FALSE
11.3.2 Charset Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property DEFAULT-CHARSET
Property Name: DEFAULT-CHARSET
Purpose: This property indicates the default charset for localized
strings.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VAGENDA" calendar
component.
Description: In a "VAGENDA", this property is used to indicate the
charset of the localized strings of all its components. If not
specified, the default is UTF-8. The value MUST be an IANA
registered character set as defined in [RFC 2278].
Format Definition: The property is defined by the following notation:
default-charset = "DEFAULT-CHARSET" default-charsetparam ":" text CRLF
default-charsetparam = *(";" xparam)
Mansour, et al. Expires August 30, 2002 [Page 90]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Example: The following is an example of this property for a "VAGENDA"
calendar component:
DEFAULT-CHARSET:Shift_JIS
11.3.3 Default Locale Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property DEFAULT-LOCALE
Property Name: DEFAULT-LOCALE
Purpose: This property specifies the default language for text
values.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VAGENDA" calendar
component.
Description: In a "VAGENDA", this property is used to indicate the
default locale for values in the components, e.g., "VEVENT", of the
"VAGENDA." The full locale SHOULD be used. The default and minimum
locale is POSIX, if not supplied in the UTF-8 charset as defined in
RFC 2277.
Format Definition: The property is defined by the following notation:
default-locale = "DEFAULT-LOCALE" default-localeparam ":" language CRLF
default-localeparam = *(";" xparam)
default-locale = Text identifying a locale, as defined in [RFC 2277]
Example: The following is an example of this property:
DEFAULT-LOCALE:en-US.iso-8859-1
11.3.4 Default Time Zone Property
Property Name: DEFAULT-TZID
Mansour, et al. Expires August 30, 2002 [Page 91]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Purpose: This property specifies the text value that specifies the
default time zone for a calendar.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property may be specified once in a "VAGENDA"
calendar component.
Description: This is the label by which the default time zone for a
calendar is specified. The default is used for all TIME and DATE-
TIME properties, in the calendar, that do not have a timezone nor are
in UTC. The presence of the SOLIDUS character (US-ASCII decimal 47)
as a prefix, indicates that this TZID represents an unique ID in a
globally defined time zone registry (when such registry is defined).
Format Definition: This property is defined by the following
notation:
default-tzid = "DEFAULT-TZID" default-tzidpropparam ":" [tzidprefix] text CRLF
default-tzidpropparam = *(";" xparam)
Example: The following is an example of this property:
DEFAULT-TZID:US-Eastern
11.3.5 Owner Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property OWNER
Property Name: OWNER
Purpose: The property specifies an owner of a calendar.
Value Type: UPN
Property Parameters: Non-standard, alternate text representation and
language property parameters can be specified on this property.
Conformance: The property MUST be specified at in a "VAGENDA"
component.
Mansour, et al. Expires August 30, 2002 [Page 92]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Description: A multi-instanced property indicating the calendar
owner.
Format Definition: The property is defined by the following notation:
owner = "OWNER" ownerparam ":" upn CRLF
ownerparam = *(";" xparam)
Example: The following is an example of this property:
OWNER:jsmith@acme.com
OWNER:jdoe@acme.com
11.3.6 Relative Calendar Identifier Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property RELCALID
Property Name: RELCALID
Purpose: The property specifies an identifier for a "VAGENDA." It
must be unique within the CS.
Value Type: URI
Property Parameters: Non-standard, alternate text representation and
language property parameters can be specified on this property.
Conformance: The property MUST be specified in a "VAGENDA" component.
Description: The parameter value MUST be a UTF-8 string. It MUST NOT
be empty.
Format Definition: The property is defined by the following notation:
recalidprop = "RELCALID" recalidparam ":" relcalid CRLF
[EDITORS NOTE: recalid is defined in Bernard's proposition for the definition of a CAP URL]
recalidparam = *(";" xparam)
Example: The following is an example of this property:
RELCALID:hjik123A001
Mansour, et al. Expires August 30, 2002 [Page 93]
Internet-Draft Calendar Access Protocol (CAP) March 2002
11.3.7 Calendar Store Component Properties
11.3.7.1 Calmaster Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property CALMASTER
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 MUST be a MAILTO URI as defined in
[RFC 1738].
Format Definition: The property is defined by the following notation:
calmaster = "CALMASTER" calmasterparam ":" uri CRLF
calmasterparam = *(";" xparam)
uri = as defined by RFC 2445
Example: The following is an example of this property:
CALMASTER:mailto:administrator@acme.com
11.3.7.2 Calendar Store Identifier Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property CSID
Property Name: CSID
Purpose: The property specifies a the globally unique identifier for
the calendar store.
Mansour, et al. Expires August 30, 2002 [Page 94]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Value Type: URI
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: The property can be specified in a "VCALSTORE"
component.
Description: The identifier MUST be globally unique. If not
specified, it is the same as the hostname.
Format Definition: The property is defined by the following notation:
csid = "CSID" csidparam ":" capurl CRLF
[EDITORS NOTE: capurl is defined in Bernard's proposition for the definition of a CAP URL]
csidparam = *(";" xparam)
Example: The following is an example of this property:
CSID:cap://calendar.acme.com
11.3.7.3 Default Access Rights Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property DEFAULT-VCARS
Property Name: DEFAULT-VCARS
Purpose: This property is used to specify the CARID of the default
VCAR components for newly created VAGENDA components.
Value Type: TEXT
Property Parameters: Only non-standard property parameters can be
specified on this property.
Conformance: This property MUST be specified in "VCALSTORE" calendar
component and MUST at least specify the following values:
READBUSYTIMEINFO, REQUESTONLY, UPDATEPARTSTATUS, and DEFAULTOWNER.
Description: This property is used in the "VCALSTORE" calendar
component to specify the CARID of the VCAR components that must be
copied in VAGENDA at creation time.
Mansour, et al. Expires August 30, 2002 [Page 95]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Format Definition: The property is defined by the following notation:
def-vcars = "DEFAULT-VCARS" def-vcarsparam ":" text
*( "," text ) CRLF
def-vcarsparam = *( ";" xparam )
Example: The following is an example of this property:
DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY
DEFAULT-VCARS:UPDATEPARTSTATUS,DEFAULTOWNER
11.3.7.4 Maximum Date Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property MAXDATE
Property Name: MAXDATE
Purpose: This property specifies the date/time in the future beyond
which the server cannot represent.
Value Type: DATE-TIME
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: The property can be specified once in "VCALSTORE".
Description: The date and time MUST be a UTC value. If not
specified, then 99991231T235959Z will be assumed.
Format Definition: The property is defined by the following notation:
maxdate = "MAXDATE" maxdateparam ":" date-time CRLF
maxdateparam = *(";" xparam)
Example: The following is an example of this property:
MAXDATE:20990101T000000Z
Mansour, et al. Expires August 30, 2002 [Page 96]
Internet-Draft Calendar Access Protocol (CAP) March 2002
11.3.7.5 Minimum Date Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property MINDATE
Property Name: MINDATE
Purpose: This property specifies the date/time in the past prior to
which the server cannot represent.
Value Type: DATE-TIME
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: The property can be specified once in "VCALSTORE".
Description: The date and time MUST be a UTC value. If not
specified, then 00000101T000000Z will be assumed.
Format Definition: The property is defined by the following notation:
mindate = "MINDATE" mindateparam ":" date-time CRLF
mindateparam = *(";" xparam)
Example: The following is an example of this property:
MINDATE:19710101T000000Z
11.3.8 Descriptive Component Properties
The following properties specify descriptive information about
calendar components.
11.3.8.1 REQUEST-STATUS property
This description is a revision of the REQUEST-STATUS property for
VCALENDAR version 2.1.
rstatus = "REQUEST-STATUS" rstatparam ":"
statcode [";" statdesc [";" extdata]]
rstatparam = *(
; the following is optional,
; but MUST NOT occur more than once
Mansour, et al. Expires August 30, 2002 [Page 97]
Internet-Draft Calendar Access Protocol (CAP) March 2002
(";" languageparm) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)
statcode = 1*DIGIT *("." 1*DIGIT)
;Hierarchical, numeric return status code
statdesc = text
;An optional textual status description, content is
;decided by the implementor. May be empty.
extdata = text
;Textual exception data. For example, the offending property
;name and value or complete property line.
Example: The following are some possible examples of this property.
The COMMA and SEMICOLON separator characters in the property value
are BACKSLASH character escaped because they appear in a text value.
REQUEST-STATUS:2.0;Success
REQUEST-STATUS:2.0;Success despite braindead LDAP implementation
REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01
REQUEST-STATUS:2.8; Success, repeating event ignored. Scheduled
as a single event.;RRULE:FREQ=WEEKLY;INTERVAL=2
REQUEST-STATUS:4.1;Event conflict. Date/time is busy.
REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE:
MAILTO:jsmith@host.com
REQUEST-STATUS:3.7;;ATTENDEE:MAILTO:jsmith@host.com
REQUEST-STATUS:10.4;Help! That really shouldnt have happened.
11.3.8.2 CALID Property Parameter
Property Name: CALID
Mansour, et al. Expires August 30, 2002 [Page 98]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Property Parameters: none
Conformance: This property can be specified in the "VCAP"
Description: This property is used to specify a fully qualified
calid.
Format Definition: The property is defined by the following notation:
CALID = "DENY" ":" calid CRLF
Example:
CALID:cap://cal.example.com/sdfifgty4321
11.3.8.3 Time Transparency
Property Name: TRANSP
Purpose: This property defines whether an event is transparent or not
to busy time searches.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified once in a "VEVENT"
calendar component.
Description: Time Transparency is the characteristic of an event that
determines whether it appears to consume time on a calendar. Events
that consume actual time for the individual or resource associated
with the calendar SHOULD be recorded as OPAQUE, allowing them to be
detected by free-busy time searches. Other events, which do not take
up the individual's (or resource's) time SHOULD be recorded as
TRANSPARENT, making them invisible to free-busy time searches.
Format Definition: The property is specified by the following
notation:
transp = "TRANSP" tranparam ":" transvalue CRLF
tranparam = *(";" xparam)
transvalue = "OPAQUE" ;Blocks or opaque on busy time searches.
/ "TRANSPARENT" ;Transparent on busy time searches.
Mansour, et al. Expires August 30, 2002 [Page 99]
Internet-Draft Calendar Access Protocol (CAP) March 2002
/ "TRANSPARENT-NOCONFLICT" ; Transparent on busy time
; searches and no other OPAQUE
; or OPAQUE-NOCONFLICT event
; can overlap it.
/ "OPAQUE-NOCONFLICT" ; Opaque on busy time
; searches and no other OPAQUE
; or OPAQUE-NOCONFLICT event
; can overlap it.
;
;Default value is OPAQUE
Example: The following is an example of this property for an event
that is transparent or does not block on free/busy time searches:
TRANSP:TRANSPARENT
The following is an example of this property for an event that is
opaque or blocks on free/busy time searches:
TRANSP:OPAQUE
The following is an example of this property for an event that is
opaque or blocks on free/busy time searches plus no other event can
overlap it:
TRANSP:OPAQUE-NOCONFLICT
11.3.8.4 Name Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property NAME
Property Name: NAME
Purpose: This property provides a localizable display name for a
calendar component.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VAGENDA" and "VCAR"
calendar components.
Mansour, et al. Expires August 30, 2002 [Page 100]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Description: This property is used in the "VAGENDA" and in the "VCAR"
calendar components to specify a localizable display name.
Format Definition: The property is defined by the following notation:
name = "NAME" nameparam ":" text CRLF
nameparam = *(
; the following is optional,
; but MUST NOT occur more than once
( ";" languageparam ) /
; the following is optional,
; and MAY occur more than once
( ";" xparam )
)
Example: The following is an example of this property:
NAME:Restrict Guests From Creating ALARMs On Events
11.3.9 Calendar Access Right Component Properties
11.3.9.1 VCAR Identifier Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property CARID
Property Name: CARID
Purpose: This property specifies the identifier for an access right
calendar component.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property MUST be specified once in a "VCAR"
calendar component.
Description: This property is used in the "VCAR" calendar component
to specify an identifier.
Mansour, et al. Expires August 30, 2002 [Page 101]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Format Definition: The property is defined by the following notation:
carid = "CARID" caridparam ":" text CRLF
caridparam = *( ";" xparam )
Example: The following is an example of this property:
CARID:xyzzy-007
11.3.9.2 VCAR Decreed Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property DECREED
Property Name: DECREED
Purpose: This property specifies if an access right calendar
component is decreed or not.
Value Type: BOOLEAN
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property MAY be specified once in a "VCAR" calendar
component.
Description: This property is used in the "VCAR" calendar component
to specify whether the component is decreed or not.
Format Definition: The property is defined by the following notation:
decreed = "DECREED" decreedparam ":" boolean CRLF
decreedparam = *( ";" xparam )
Example: The following is an example of this property:
DECREED:TRUE
11.3.10 Right Component Properties
Mansour, et al. Expires August 30, 2002 [Page 102]
Internet-Draft Calendar Access Protocol (CAP) March 2002
11.3.10.1 Grant Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property GRANT
Property Name: GRANT
Purpose: This property identifies the UPN(s) being granted access in
the VRIGHT component.
Value Type: UPN-FILTER
Property Parameters: Only non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VRIGHT" calendar
components.
Description: This property is used in the "VRIGHT" calendar component
to specify the CU or UG being granted access.
Format Definition: The property is defined by the following notation:
grant = "GRANT" grantparam ":" upn-filter CRLF
grantparam = *( ";" xparam )
Example: The following are examples of this property:
GRANT:*
GRANT:bob@example.com
11.3.10.2 Deny Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property DENY
Property Name: DENY
Purpose: This property identifies the UPN(s) being denied access in
the VRIGHT component.
Value Type: UPN-FILTER
Mansour, et al. Expires August 30, 2002 [Page 103]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Property Parameters: Only non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VRIGHT" calendar
components.
Description: This property is used in the "VRIGHT" calendar component
to define the CU or UG being denied access.
Format Definition: The property is defined by the following notation:
deny = "DENY" denyparam ":" upn-filter CRLF
denyparam = *( ";" xparam )
Example: The following are examples of this property:
DENY:*
DENY:bob@example.com
11.3.10.3 Permission Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property PERMISSION
Property Name: PERMISSION
Purpose: This property defines a permission that is granted or denied
in a VRIGHT component.
Value Type: TEXT
Property Parameters: Only non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VRIGHT" calendar
components.
Description: This property is used in the "VRIGHT" calendar component
to define a permission that is granted or denied.
Format Definition: The property is defined by the following notation:
perm = "PERMISSION" permparam ":" permvalue CRLF
Mansour, et al. Expires August 30, 2002 [Page 104]
Internet-Draft Calendar Access Protocol (CAP) March 2002
permparam = *( ";" xparam )
permvalue = ( "READ" / "WRITE" / "DELETE" / "MODIFY" / all )
all = "*"
Example: The following is an example of this property:
PERMISSION:READ
11.3.10.4 Scope Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property SCOPE
Property Name: SCOPE
Purpose: This property identifies the objects in the CS to which the
access rights applies.
Value Type: CAL-QUERY
Property Parameters: Only non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VRIGHT" calendar
components.
Description: This property is used in the "VRIGHT" calendar component
to define the set of objects subject to the access right being
defined.
Format Definition: The property is defined by the following notation:
scope = "SCOPE" scopeparam ":" cal-query CRLF
scopeparam = *( ";" xparam )
Example: The following is an example of this property:
SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC'
Mansour, et al. Expires August 30, 2002 [Page 105]
Internet-Draft Calendar Access Protocol (CAP) March 2002
11.3.10.5 Restriction Component Property
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property RESTRICTION
Property Name: RESTRICTION
Purpose: This property defines restrictions on the value that may
take new or existent calendar components.
Value Type: CAL-QUERY
Property Parameters: Only non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in "VRIGHT" calendar
components, but only when the PERMISSION property is set to "WRITE",
"MODIFY", or "*".
Description: This property is used in the "VRIGHT" calendar component
to define restrictions on the calendar components that can be written
(i.e., by using the "create" or "move" commands) as well as on the
values that may take existent calendar store properties, calendar
properties, calendar components, and component properties (i.e., by
using the "modify" command). Accepted values MUST match the
specified RESTRICTION.
Format Definition: The property is defined by the following notation:
restrict = "RESTRICTION" restrictparam ":" cal-query CRLF
restrictparam = *( ";" xparam )
Example: The following are examples of this property:
RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST'
RESTRICTION:SELECT * FROM VEVENT WHERE
SELF() IN CAL-OWNERS(ORGANIZER)
RESTRICTION:SELECT * FROM VEVENT WHERE 'BUSINESS' IN
CATEGORIES
Mansour, et al. Expires August 30, 2002 [Page 106]
Internet-Draft Calendar Access Protocol (CAP) March 2002
12. CAP Item Registration
This section provides the process for registration of new or modified
CAP entities.
12.1 Registration of New and Modified CAP Entities
New CAP entities are registered by the publication of an IETF Request
for Comment (RFC). Changes to a CAP item are registered by the
publication of a revision of the RFC defining the method.
12.2 Registration of New Entities
This section defines procedures by which new entities (i.e.,
components, properties, parameters, enumerated values or restriction
tables) for a CAP item can be registered with the IANA.
Non-standard, experimental entities can be used by bilateral
agreement, provided the associated properties names follow the "X-"
convention. Such non-standard and experimental entities are non-IANA
entities and need not be registered using this process.
The procedures defined here are designed to allow public comment and
review of new CAP entities, while posing only a small impediment to
the definition of new properties.
Registration of a new CAP item is accomplished by the following
steps.
12.2.1 Define the Item
A CAP item is defined by completing the following template.
To: ietf-calendar@imc.org
Subject: Registration of CAP item XXX
Item name:
Item purpose:
Description:
CAP terminology changes:
CAP data model changes:
CAP system model changes:
Conformance considerations:
Format definition:
Examples:
The meaning of each field in the template is as follows.
Item name: The name of the item.
Mansour, et al. Expires August 30, 2002 [Page 107]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Item purpose: The purpose of the item (e.g., Extends the CAP
command set to poll for notifications, etc.). Give a short but
clear description.
Description: Any special notes about the item, how it is to be
used, etc.
CAP terminology changes: Any change or additions to the
existing CAP terminology needs to be specified.
CAP data model changes: Any of the valid property parameters
for the property needs to be specified.
CAP system model changes:
Conformance: A clear summary of how and where this CAP item
extension MUST, MAY, SHOULD or can be used. Any changes or
impact to the existing conformance definition for CAP should be
explained. The impact to implementations conforming to the
existing CAP specification should be clearly described.
Format definition: The ABNF for each element of the CAP item
needs to be specified.
Examples: One or more examples of instances of the CAP item and
each of its usage scenarios needs to be specified.
12.2.2 Post the item definition
The item description MUST be posted to the new item discussion list,
ietf-calendar@imc.org.
12.2.3 Allow a comment period
Discussion on the new item MUST be allowed to take place on the list
for a minimum of two weeks. Consensus MUST be reached on the
property before proceeding to the next step.
12.2.4 Submit the proposal for approval
Once the two-week comment period has elapsed, and the proposer is
convinced consensus has been reached on the proposal, the
registration application should be submitted to the Method Reviewer
for approval. The Method Reviewer is appointed by the Application
Area Directors and can either accept or reject the proposal
registration. An accepted registration should be passed on by the
Method Reviewer to the IANA for inclusion in the official IANA method
Mansour, et al. Expires August 30, 2002 [Page 108]
Internet-Draft Calendar Access Protocol (CAP) March 2002
registry. The registration can be rejected for any of the following
reasons. 1) Insufficient comment period; 2) Consensus not reached;
3) Technical deficiencies raised on the list or elsewhere have not
been addressed. The Method Reviewers decisions may be appealed to
the IESG.
12.3 Property Change Control
Existing CAP entities can be changed using the same process by which
they were registered.
1. Define the change
2. Post the change
3. Allow a comment period
4. Submit the proposal for approval
Note that the original author or any other interested party can
propose a change to an existing CAP object, but that such changes
should only be proposed when there are serious omissions or errors in
the published memo. The Method Reviewer can object to a change if it
is not backward compatible, but is not required to do so.
CAP objects definitions can never be deleted from the IANA registry,
but objects which are no longer believed to be useful can be declared
OBSOLETE by adding this text to their "Item purpose" field.
Mansour, et al. Expires August 30, 2002 [Page 109]
Internet-Draft Calendar Access Protocol (CAP) March 2002
13. IANA Considerations
This memo defines IANA registered extensions to the attributes
defined by iCalendar, as defined in [RFC2445], and [iTIP].
IANA registration proposals for iCalendar and iTIP are to be mailed
to the registration agent for the "text/calendar" [MIME] content-
type, <MAILTO: ietf-calendar@imc.org> using the format defined in
section 7 of [RFC2445].
If the IESG approves this memo for publication, then the IANA
registers the profile specified in Section 7.1, and selects an IANA-
specific URI, e.g., http://iana.org/beep/cap/1.0.
Mansour, et al. Expires August 30, 2002 [Page 110]
Internet-Draft Calendar Access Protocol (CAP) March 2002
URIs
[1] <http://www.imc.org/html.charters/calsch-charter.html>
Authors' Addresses
Steve Mansour
AOL/Netscape
466 Ellis Road
Mountain View, CA 94043
US
Phone: +1-650-937-3351
EMail: sman@netscape.com
Doug Royer
INET-Consulting LLC
1795 W. Broadway #266
Idaho Falls, ID 83402
Phone: 208-520-4044
EMail: Doug@Royer.com
George Babics
Steltor
2000 Peel Street
Montreal, Quebec H3A 2W5
CA
Phone: +1-514-733-8500 x4201
Fax: +1-514-733-8878
EMail: georgeb@steltor.com
Paul Hill
Massachusetts Institute of Technology
W92-172
77 Massachusetts Avenue
Cambridge, MA 02139
US
Phone: +1-617-253-0124
Fax: +1-617-258-8736
EMail: phb@mit.edu
Mansour, et al. Expires August 30, 2002 [Page 111]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Appendix A. Acknowledgments
The following have individuals were major contributors in the
drafting and discussion of this memo:
Harald Alvestrand, Mario Bonin, Andre Courtemanche, Dave
Crocker, Bernard Desruisseaux, Pat Egen, Gilles Fortin, Jeff
Hodges, Alex Hoppman, Bruce Kahn, Lisa Lippert, David Madeo,
Bob Mahoney, Bob Morgan, Patrice Lapierre, Pete O'Leary,
Richard Shusterman, Tony Small, John Stracke, Alexander Taler,
Mark Wahl. Special thanks to Patrice Lapierre for transforming
CAP into a BEEP profile.
Mansour, et al. Expires August 30, 2002 [Page 112]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Appendix B. Bibliography
[RFC1521] Borenstein, N., Freed, N., "Specifying and Describing the Format of Internet Message
Bodies", RFC 1521, September 1993
ftp://ftp.isi.edu/in-notes/rfc1521.txt
[RFC1738] Berners-Lee, T, Masinter, L. and McCahil, M., "Uniform Resource Locators (URL)", RFC
1738, December 1994
ftp://ftp.isi.edu/in-notes/rfc1738.txt
[RFC2045] Borenstein, N. and Freed, N., "Multipurpose Internet Mail Extensions (MIME) Part
One: Format of Internet Message Bodies", RFC 2045, November 1996
ftp://ftp.isi.edu/in-notes/rfc2045.txt
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119,
BCP 14, March 1997
ftp://ftp.isi.edu/in-notes/rfc2119.txt
[RFC2222] Myers, J., "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997
ftp://ftp.isi.edu/in-notes/rfc2222.txt
[RFC2246] Dierks, T. and Allen, C., "The TLS Protocol Version 1.0", RFC 2246, January 1999
ftp://ftp.isi.edu/in-notes/rfc2246.txt
[RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource Locators", RFC 2392,
August 1998
ftp://ftp.isi.edu/in-notes/rfc2392.txt
[RFC2396] Berners-Lee, T, Fielding, R. and Masinter, L., "Uniform Resource Identifiers (URI):
Generic Syntax", RFC 2396, August 1998
ftp://ftp.isi.edu/in-notes/rfc2396.txt
[RFC2445] Dawson, F. and Stenerson, D., "Internet Calendaring and Scheduling Core Object
Specification (iCalendar)", RFC 2445, November 1998
ftp://ftp.isi.edu/in-notes/rfc2245.txt
[RFC2446] Silverberg, S., Mansour, S., Dawson, F. and Hopson, R., "iCalendar Transport-Independent
Interoperability Protocol (iTIP) Events, BusyTime, To-dos and Journal Entries", RFC
2446, November 1998
ftp://ftp.isi.edu/in-notes/rfc2446.txt
[RFC2447] Dawson, F., Mansour, S. and Silverberg, "iCalendar Message-Based Interoperability
Protocol (iMIP)", RFC 2447, November 1998
ftp://ftp.isi.edu/in-notes/rfc2447.txt
[RFC3080] Rose, M., "The Block Extensible Exchange Protocol Core", RFC 3080, March 2001
ftp://ftp.isi.edu/in-notes/rfc3080.txt
Mansour, et al. Expires August 30, 2002 [Page 113]
Internet-Draft Calendar Access Protocol (CAP) March 2002
[RFC3081] Rose, M., "Mapping the BEEP Core onto TCP", RFC 3081, March 2001
ftp://ftp.isi.edu/in-notes/rfc3081.txt
[RFC3087] Campbell, B. and Sparks, R., "Control of Service Context using SIP Request-URI",
RFC 3087, April 2001
ftp://ftp.isi.edu/in-notes/rfc3087.txt
[SQL] "Database Language SQL", ANSI/ISO/IEC 9075: 1992, aka ANSI X3.135-1992, aka FiPS PUB 127-2
[SQLCOM] ANSI/ISO/IEC 9075:1992/TC-1-1995, Technical corrigendum 1 to ISO/IEC 9075: 1992, also
adopted as Amendment 1 to ANSI X3.135.1992
[UNICODE] The Unicode Consortium, "The Unicode Standard, Version 3.1"
http://www.unicode.org/unicode/standard/standard.html
[US-ASCII] Coded Character Set -- 7-bit American Standard Code for Information Interchange,
ANSI X3.4-1986.
[????] "Worldwide Character Encoding -- Version 1.0", Addison-Wesley, Volume 1, 1991,
Volume 2, 1992. UTF-8 is described in Unicode Technical Report #4.
Mansour, et al. Expires August 30, 2002 [Page 114]
Internet-Draft Calendar Access Protocol (CAP) March 2002
Full Copyright Statement
Copyright (C) The Internet Society (2002). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Mansour, et al. Expires August 30, 2002 [Page 115]
