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 and 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: 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: C: C: 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: C: = '19990714T080000Z' AND C: DTSTART <= '19990715T080000Z' C: END:VQUERY C: END:VCALENDAR C: ]]> C: C: END # After 3 seconds S: MSG 1 2 . 102 64 S: Content-Type: application/cap+xml S: S: 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: 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: C: END S: RPY 1 4 . 2723 114 S: S: S: Request Aborted by the CUA. S: 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 .* with the result being a properly formatted (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. 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 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: 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: S: 20011121T120000Z-12340@cal.example.com S: 20011121T120000Z-12341@cal.example.com S: 20011121T120000Z-12342@cal.example.com S: 20011121T120000Z-12343@cal.example.com S: 20011121T120000Z-12344@cal.example.com S: 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: C: END S: RPY 1 6 . 3282 423 S: Content-Type: application/beep+xml S: S: S: S: 2.0 S: 65536 S: 1.0 S: 1.0 S: CAR-FULL-1CAR-MINCAP-QL S: 00000101T000000Z S: 99991231T235959Z S: S: VCALSTORE,VAGENDA,VCALENDAR,VEVENT,X-my-vcomp,VALARM S: S: 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: C: END S: RPY 1 7 . 3752 91 S: Content-Type: application/cap+xml S: S: 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: C: END S: RPY 1 7 . 3752 91 S: Content-Type: application/cap+xml S: S: 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 and tags. Any reply from the CS that does not contain an iCalendar object is returned in a 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 command deposited two METHOD:REQUEST objects into the same target, this could be the reply. S: S: ]]> S: 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: C: C: C: 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: S: Mansour, et al. Expires August 30, 2002 [Page 59] Internet-Draft Calendar Access Protocol (CAP) March 2002 S: S: S: 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 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: 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 ... .... 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:som