Network Working Group S. Mansour Internet-Draft AOL/Netscape Expires: May 21, 2002 D. Royer INET-Consulting LLC G. Babics Steltor P. Hill Massachusetts Institute of Technology November 20, 2001 Calendar Access Protocol (CAP) draft-ietf-calsch-cap-06 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 May 21, 2002. Copyright Notice Copyright (C) The Internet Society (2001). 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 [iCAL] based Calendar Store (CS). This memo defines the CAP specification. Mansour, et. al. Expires May 21, 2002 [Page 1] Internet-Draft Calendar Access Protocol (CAP) November 2001 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 . . . . . . . . . . . 16 2.4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . . 16 2.4.2 Access Rights - Summary . . . . . . . . . . . . . . . . 16 2.4.2.1 Calendar Access Right (VCAR) . . . . . . . . . . . . . . 17 2.4.2.2 Decreed VCARs . . . . . . . . . . . . . . . . . . . . . 17 2.4.3 Inheritance . . . . . . . . . . . . . . . . . . . . . . 18 2.4.4 CAP Session Identity . . . . . . . . . . . . . . . . . . 18 2.5 Roles . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.6 Calendar Addresses . . . . . . . . . . . . . . . . . . . 19 2.7 Extensions to iCalendar . . . . . . . . . . . . . . . . 20 2.8 Relationship of RFC 2446 (ITIP) to CAP . . . . . . . . . 20 3. Protocol Framework . . . . . . . . . . . . . . . . . . . 22 3.1 BEEP Exchange Styles . . . . . . . . . . . . . . . . . . 22 3.2 Use of XML, MIME and iCalendar . . . . . . . . . . . . . 22 3.3 Bounded Latency . . . . . . . . . . . . . . . . . . . . 23 4. Formal Command Syntax . . . . . . . . . . . . . . . . . 26 4.1 Searching and Filtering . . . . . . . . . . . . . . . . 26 4.1.1 Grammar For Search Mechanism . . . . . . . . . . . . . . 26 4.1.2 SQL-MIN notes . . . . . . . . . . . . . . . . . . . . . 27 4.1.3 Querying Experminental Properties . . . . . . . . . . . 28 4.1.4 Example, Query by UID . . . . . . . . . . . . . . . . . 28 4.1.5 Query by Date-Time range . . . . . . . . . . . . . . . . 29 4.1.6 Query for all Non-Booked Entries . . . . . . . . . . . . 29 4.1.7 Query with Subset of Properties by Date/Time . . . . . . 29 4.1.8 Components With Alarms In A Range . . . . . . . . . . . 30 5. Access Rights . . . . . . . . . . . . . . . . . . . . . 31 Mansour, et. al. Expires May 21, 2002 [Page 2] Internet-Draft Calendar Access Protocol (CAP) November 2001 5.1 VCAR Inheritance . . . . . . . . . . . . . . . . . . . . 31 5.2 Access Control and NOCONFLICT . . . . . . . . . . . . . 31 6. Commands and Responses . . . . . . . . . . . . . . . . . 32 6.1 Session Commands . . . . . . . . . . . . . . . . . . . . 32 6.1.1 "generate-uid" Command . . . . . . . . . . . . . . . . . 32 6.1.2 "get-capability" Command . . . . . . . . . . . . . . . . 33 6.1.3 "identify" Command . . . . . . . . . . . . . . . . . . . 35 6.1.4 "noop" Command . . . . . . . . . . . . . . . . . . . . . 35 6.2 Calendaring and Scheduling Commands . . . . . . . . . . 36 6.2.1 Restriction Tables . . . . . . . . . . . . . . . . . . . 36 6.2.2 Common Attributes . . . . . . . . . . . . . . . . . . . 37 6.2.2.1 "id" Attribute . . . . . . . . . . . . . . . . . . . . . 37 6.2.3 Common Elements . . . . . . . . . . . . . . . . . . . . 37 6.2.3.1 "data" Element . . . . . . . . . . . . . . . . . . . . . 37 6.2.3.2 "select" Element . . . . . . . . . . . . . . . . . . . . 37 6.2.3.3 "source" Element . . . . . . . . . . . . . . . . . . . . 39 6.2.3.4 "target" Element . . . . . . . . . . . . . . . . . . . . 39 6.2.4 Calendaring Commands . . . . . . . . . . . . . . . . . . 40 6.2.4.1 "create" Command . . . . . . . . . . . . . . . . . . . . 40 6.2.4.2 "delete" Command . . . . . . . . . . . . . . . . . . . . 50 6.2.4.3 "modify" Command . . . . . . . . . . . . . . . . . . . . 53 6.2.4.4 "move" Command . . . . . . . . . . . . . . . . . . . . . 59 6.2.4.5 "search" Command . . . . . . . . . . . . . . . . . . . . 62 6.3 Scheduling Commands . . . . . . . . . . . . . . . . . . 72 6.3.1 "schedule" Command . . . . . . . . . . . . . . . . . . . 72 6.3.2 Processing Scheduling Components . . . . . . . . . . . . 74 6.3.3 iTIP Examples . . . . . . . . . . . . . . . . . . . . . 76 6.3.3.1 Sending and Receiving an iTIP request . . . . . . . . . 76 6.3.3.2 Handling an iTIP refresh . . . . . . . . . . . . . . . . 81 6.3.3.3 Sending and accepting an iTIP counter . . . . . . . . . 83 6.3.3.4 Declining an iTIP counter . . . . . . . . . . . . . . . 86 7. Response Codes . . . . . . . . . . . . . . . . . . . . . 89 8. BEEP Profile Registration . . . . . . . . . . . . . . . 91 9. CAP DTD . . . . . . . . . . . . . . . . . . . . . . . . 92 10. Implementation Issues . . . . . . . . . . . . . . . . . 95 11. Properties . . . . . . . . . . . . . . . . . . . . . . . 96 11.1 Calendar Store Properties . . . . . . . . . . . . . . . 96 11.2 Calendar Properties . . . . . . . . . . . . . . . . . . 97 12. CAP Item Registration . . . . . . . . . . . . . . . . . 100 12.1 Registration of New and Modified CAP Entities . . . . . 100 12.2 Registration of New Entities . . . . . . . . . . . . . . 100 12.2.1 Define the Item . . . . . . . . . . . . . . . . . . . . 100 12.2.2 Post the item definition . . . . . . . . . . . . . . . . 101 12.2.3 Allow a comment period . . . . . . . . . . . . . . . . . 101 12.2.4 Submit the proposal for approval . . . . . . . . . . . . 101 12.3 Property Change Control . . . . . . . . . . . . . . . . 102 13. IANA Considerations . . . . . . . . . . . . . . . . . . 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . 103 Mansour, et. al. Expires May 21, 2002 [Page 3] Internet-Draft Calendar Access Protocol (CAP) November 2001 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . 105 B. Bibliography . . . . . . . . . . . . . . . . . . . . . . 106 Full Copyright Statement . . . . . . . . . . . . . . . . 108 Mansour, et. al. Expires May 21, 2002 [Page 4] Internet-Draft Calendar Access Protocol (CAP) November 2001 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 core [BEEP]. The protocol data units leverage the standard iCalendar format [iCAL] to convey calendar related information. 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 this memo. Calendar components defined by [iCAL] 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". Calendar 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, 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 Mansour, et. al. Expires May 21, 2002 [Page 5] Internet-Draft Calendar Access Protocol (CAP) November 2001 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: [iCAL] (RFC2445) which specifies the objects, data types, properties and property parameters used in the protocols, along with the methods for representing and encoding them, [iTIP] (RFC2446) which specifies an interoperability protocol for scheduling between different 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 two conceptual states. It is scheduled or it is booked. 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 is a component does not have a METHOD property. 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 Mansour, et. al. Expires May 21, 2002 [Page 6] Internet-Draft Calendar Access Protocol (CAP) November 2001 calendar components. In addition, a calendar might be hierarchically related to other sub-calendars. A calendar is identified by its unique calendar identifier. The [iCAL] 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. Calendar Access Rights (CAR) The mechanism for specifying the CAP operations ("ACTION") that a particular calendar user ("UPN") are granted or denied permission to perform on a given calendar object ("OBJECT"). 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. Calendars reside within a CS. See Qualified Calendar Identifier and Relative Calendar Identifier. Calendar Policy A CAP operational restriction on the access or manipulation of a calendar. For example, "events MUST be scheduled in unit intervals of one hour". Mansour, et. al. Expires May 21, 2002 [Page 7] Internet-Draft Calendar Access Protocol (CAP) November 2001 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 [URL]. Calendar Store Components Components maintained in a CS specify a grouping of calendar store-wide information. Calendar Store Properties Properties maintained in a Calendar Store calendar store-wide information. Calendar User (CU) An entity (often biological) that uses a calendaring system. Calendar User Agent (CUA) The 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. Delegate A calendar user (sometimes called the delegatee) who has been Mansour, et. al. Expires May 21, 2002 [Page 8] Internet-Draft Calendar Access Protocol (CAP) November 2001 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. Fan Out The calendaring and scheduling process by which a calendar operation on one calendar is also performed on every other calendar specified in the operation. Hierarchical Calendars A CS feature where a calendar has a hierarchical relationship with another calendar in the CS. The top-most calendars in the hierarchical relationship have the CS as their parent. There may be multiple top-most calendars in a given CS. Within a given hierarchical relationship, all sub-calendars have a calendar with a "parent" relationship. In addition, sub-calendars may have a relationship with another calendar that has a "child" relationship. The hierarchical calendar feature is not a storage relationship of the calendars within the CS. Instead it is a feature that relates access control rights to calendar content between different calendars in the CS. The hierarchical relationship of a calendar is specified in the "PARENT" and "CHILDREN" calendar properties. 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 have "OWNER" calendar access rights for a calendar. The owner is specified in the "OWNER" calendar property. Mansour, et. al. Expires May 21, 2002 [Page 9] Internet-Draft Calendar Access Protocol (CAP) November 2001 Qualified Calendar Identifier (Qualified CalID) A CalID where both the and are present. Realm A collection of calendar user accounts, identified by a string. The name of the Realm is only used in UPNs. In order to avoid namespace conflict, the Realm SHOULD be postfixed with an appropriate DNS domain name. (e.g., the foobar Realm could be called foobar.example.com). Relative Calendar Identifier (Relative CalID) An identifier for an individual calendar in a calendar store. It is unique within a calendar store. It is recommended to be globally unique. 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 [URL]. 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. Sub-calendars Calendars that have a "child" hierarchical relationship with another calendar, its "parent". 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, Mansour, et. al. Expires May 21, 2002 [Page 10] Internet-Draft Calendar Access Protocol (CAP) November 2001 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 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 May 21, 2002 [Page 11] Internet-Draft Calendar Access Protocol (CAP) November 2001 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 used to move these encapsulations between a CUA and a CS. The CAP profile defines the content and semantics of the messages sent between the CUA and the Calendar Service. 2.2 Calendar Store Object Model 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. Calendars may also contain other calendars (VAGENDAs). Mansour, et. al. Expires May 21, 2002 [Page 12] Internet-Draft Calendar Access Protocol (CAP) November 2001 Calendar Store | +-- 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. In this model, VSCHEDULE is a set of scheduling messages that have not yet been applied to the calendar. Components in VSCHEDULE are discussed in more detail below. 2.3 Protocol Model The commands listed below are used to manipulate the data on the calendar store. Their usage and semantics are defined in Section 6. CAP Commands ----------------------------------------------------------- Mansour, et. al. Expires May 21, 2002 [Page 13] Internet-Draft Calendar Access Protocol (CAP) November 2001 Command Description ----------------------------------------------------------- create Create a new calendar component. delete Delete calendar components. generate-uid Generate one or more unique ids. get-capability Query the capabilities of the CS. identify Set a new identity for calendar access. modify Modify calendar components. move Move calendar components to another container. noop Do nothing. schedule Add an [iTIP] object to the VSCHEDULE set. 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 the subject 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. 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 Mansour, et. al. Expires May 21, 2002 [Page 14] Internet-Draft Calendar Access Protocol (CAP) November 2001 single correct guideline for which field should contain the UPN. From RFC-2459, section 4.1.2.6 (Subject): If subject naming information is present only in the subjectAlt- Name extension (e.g., a key bound only to an email address or URI), then the subject name MUST be an empty sequence and the subjectAltName extension MUST be critical. Implementations of this specification MAY use these comparison rules to process unfamiliar attribute types (i.e., for name chaining). This allows implementations to process certificates 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, and the CN should also be checked. 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. Mansour, et. al. Expires May 21, 2002 [Page 15] Internet-Draft Calendar Access Protocol (CAP) November 2001 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. 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 command. All rights MUST be denied unless specifically granted; individual VCARs MUST be specifically granted to an authenticated CU. The access for a particular UPN is the union of all grants for that UPN minus the union of its denies. Mansour, et. al. Expires May 21, 2002 [Page 16] Internet-Draft Calendar Access Protocol (CAP) November 2001 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 "GRANT", "DENY" and "CARID" properties. Likewise, there is no implied ordering required for components of a "RIGHTS" value type other than that specified by the ABNF. [EDITOR'S NOTE, this requires a lot of review. We think that this paragraph may be incorrect.] For details on the VCAR syntax please see section 2.4.2.2 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 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 (OBJECT=*) access to their own calendar objects. The DENY property disallows anyone (UPN=*) from being able to delete or modify this VCAR. BEGIN:VCAR CARID:Users Default Access GRANT:UPN=OWNER;OBJECT=*;OBJECT=OBJECT=METHOD;VALUE=* DENY:UPN=*;OBJECT=VCAR;OBJECT=CARID; VALUE="Users Default Access" ;OBJECT=METHOD,VALUE=DELETE,MODIFY END:VCAR Decreed VCARs MUST be readable by the calendar owner in standard VCAR format. Mansour, et. al. Expires May 21, 2002 [Page 17] Internet-Draft Calendar Access Protocol (CAP) November 2001 2.4.3 Inheritance Calendars inherit VCARs from their parent calendar. Calendars whose parent is the Calendar Store inherit VCARs from the Calendar Store. VCARs specified in a calendar or a sub-calendar override all inherited VCARs. 2.4.4 CAP Session Identity A BEEP session has an associated set of authentication credentials, from which is derived a UPN. This UPN is the identity of the CAP session, and is used to determine access rights for the session. The CUA may change the identity of a CAP session by calling the "identify" command. The 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. 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 [iCAL] objects in a Calendar Store and exchanging [iCAL] objects for the purposes of group calendaring and scheduling between "Calendar Users" (CUs) or "User Groups" (UGs). Mansour, et. al. Expires May 21, 2002 [Page 18] Internet-Draft Calendar Access Protocol (CAP) November 2001 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 Calendar Addresses Calendar addresses are URIs that are modeled after URLs [URL]. CAP uses the following forms of URI. [[]://[:]/] where: is "cap", the protocol described in this memo. is the Calendar Store ID. It is the network address of the computer on which the CAP server is running. is optional. The port must be present in the URL if the CAP server does not listen on the default port number. is an identifier that uniquely identifies the calendar on a particular calendar store. There is no implied structure in a Relative CALID. It is an arbitrary string of printable 7 bit ASCII characters. 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. It is recommended that the Relative CALID be globally unique. If the and are present the calendar address is said to be "qualified". Senders are required to supply the portion of the address. A qualified calendar address is required when the of the target calendar address differs from that of the CAP server receiving the command. Examples of CAP URIs: cap://calendar.example.com/user1 ://calendar.example.com/user1 user1 cap://calendar.example.com/conferenceRoomA cap://calendar.example.com/89798-098-zytytasd Mansour, et. al. Expires May 21, 2002 [Page 19] Internet-Draft Calendar Access Protocol (CAP) November 2001 For a user currently authenticated to a CAP server on calendar.example.com, the first three addresses refer to the same calendar. 2.7 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 and QUERYNAME, that define a search filter. VQUERY is used by the following CAP commands: "search", "move", "modify" and "delete". Access rights are specified in the new iCalendar VCAR component. Calendar are specified by the new VAGENDA component. 2.8 Relationship of RFC 2446 (ITIP) to CAP [iTIP] describes scheduling methods which result in indirect manipulation of calendar components. In CAP, the "schedule" 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. This is modeled with the VSCHEDULE set. Note that this is a conceptual model, the actual storage details are left to implementations. When scheduling is used, the METHOD is saved along with components. A scheduled component becomes a booked component when its METHOD property is removed. For example, a component whose METHOD is "REQUEST" is scheduled. The component becomes booked when the METHOD is removed. 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 Mansour, et. al. Expires May 21, 2002 [Page 20] Internet-Draft Calendar Access Protocol (CAP) November 2001 resolving multiple [iTIP] scheduling entries. Mansour, et. al. Expires May 21, 2002 [Page 21] Internet-Draft Calendar Access Protocol (CAP) November 2001 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 5229. 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 of XML, MIME and iCalendar Each BEEP payload exchanged via CAP consists of an XML document and possibly an arbitrary MIME content. The XML document defines the action to be performed. When needed, the calendaring related data is included in a related MIME part containing an iCalendar object. If only an XML document is sent in the BEEP payload, then the mapping to a BEEP payload is straight-forward, e.g., C: MSG 1 2 . 432 62 C: Content-Type: application/beep+xml C: C: C: END Otherwise, arbitrary MIME content is included in the BEEP payload by using a "multipart/related" (see [RFC 3087]), identified using a "cid" URL (see [RFC 2392]), and the XML control document occurs as the starting body part, e.g., C: MSG 1 3 . 1023 951 C: Content-Type: multipart/related; boundary="boundary-asdf123"; C: start="<1@cal.example.com>"; C: type="application/beep+xml" Mansour, et. al. Expires May 21, 2002 [Page 22] Internet-Draft Calendar Access Protocol (CAP) November 2001 C: C: --boundary-asdf123 C: Content-Type: application/beep+xml C: Content-ID: <1@cal.example.com> C: C: C: C: C: C: C: C: --boundary-asdf123 C: Content-Type: text/calendar C: Content-ID: 2@cal.example.com C: C: BEGIN:VCALENDAR C: METHOD:REQUEST C: BEGIN:VEVENT C: UID:abcd12345 C: ORGAGNIZER:cap://cal.example.com/mary-relcalid C: ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.example.com/mary-relcalid C: ATTENDEE;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:cap://cal.example.com/john-relcalid C: ATTENDEE;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:cap://cal.example.com/bob-relcalid C: DTSTART:20010920T180000Z C: DTEND:20010920T190000Z C: SUMMARY:Mary invites John and Robert C: END:VEVENT C: END:VCALENDAR C: --boundary-asdf123-- C: END The MIME content-type "application/beep+xml" is defined in Section 6.4 of [BEEP]. 3.3 Bounded Latency A CUA can associate a maximum latency time to a command with the "max-time" element. If the CS is unable to complete the request in the specified amount of time, then the server sends a "timeout" request to which the CUA MUST respond with a "abort" or "continue" reply. Upon receiving an "abort" reply, the CS MUST terminate the command in progress and return a request-status code 2.0.3. 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 element takes two arguments "latency" and "action". The Mansour, et. al. Expires May 21, 2002 [Page 23] Internet-Draft Calendar Access Protocol (CAP) November 2001 "latency" argument 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. 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: multipart/related; boundary="boundary-zxy123"; C: start="1@cal.example.com"; C: type="application/beep+xml" C: C: --boundary-zxy123 C: Content-Type: application/beep+xml C: Content-ID: 1@cal.example.com C: C: C: C: C: C: --boundary-zxy123 C: Content-Type: text/calendar C: Content-ID: 2@cal.example.com C: C: BEGIN:VCALENDAR C: BEGIN:VQUERY C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID FROM VEVENT C: WHERE DTEND >= '19990714T080000Z' AND C: DTSTART <= '19990715T080000Z' C: END:VQUERY C: END:VCALENDAR C: --boundary-zxy123-- C: END # After 3 seconds S: MSG 1 2 . 102 64 S: Content-Type: application/beep+xml S: S: Mansour, et. al. Expires May 21, 2002 [Page 24] Internet-Draft Calendar Access Protocol (CAP) November 2001 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/beep+xml C: C: C: C: C: END If Bill wants 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/beep+xml C: C: C: END S: RPY 1 4 . 2723 114 S: S: S: S: Request Aborted by the CUA. S: S: S: END Mansour, et. al. Expires May 21, 2002 [Page 25] Internet-Draft Calendar Access Protocol (CAP) November 2001 4. Formal Command Syntax 4.1 Searching and Filtering This section describes CAP's selecting and filtering entities within a calendar store. It is based on the Standard Query Language (SQL) defined in [SQL]. 4.1.1 Grammar For Search Mechanism search = "BEGIN:VQUERY" CRLF [expand] querycomp "END:VQUERY" CRLF expand = "EXPAND" ":" ( "TRUE" / "FALSE") CRLF # the default is EXPAND:FALSE comp-name = "VEVENT" / "VTODO" / "VJOURNAL" / "VTIMEZONE" / "VALARM" / "VFREEBUSY" / "VAGENDA" / "VCAR" / iana-name / x-name querycomp = ( query ) / ( queryname query ) / queryname queryname = "QUERYNAME:" text query = "QUERY:" ( query-min / query-92 ) # # NOTE: query-min MUST be implemented in CSs. # # query-92 is ONLY used if CAPABILITY returns SQL-92 # as the QUERYLEVEL value or if QUERYLEVEL is not # specified. # query-min = capselect-min capselect-min = "SELECT" capmin-cols "FROM" capmin-comps "WHERE" capmin-cmp capmin-col = # Any property name found in any of the components. capmin-cols = ( capmin-col / capmin-col "," capmin-cols ) Mansour, et. al. Expires May 21, 2002 [Page 26] Internet-Draft Calendar Access Protocol (CAP) November 2001 capmin-comps = ( comp-name / comp-name "," compmin-comps ) capmin-cmp = ( colname capmin-cmp-rhs / colname capmin-cmp-rhs capmin-logical capmin-cmp ) capmin-cmp-rhs = ( capmin-oper colvalue / "IS" ["NOT"] "NULL" ) colname = ( # Any valid component property name. / "*" ) cmpmin-oper = ( " = " / " != " / " < " / " > " / " <= " / " >= " ) capmin-logical = ( " AND " / " OR " ) query-92 = capselect-92 capfrom-92 capwhere-92 caporderby-92 capselect-92 = # Any valid [SQL] string that goes into a SELECT clause. capfrom-92 = # Like capmin-comps except embedded spaces # are allowed between commas - per [SQL]. capwhere-92 = # Any valid [SQL] string that goes into a # WHERE clause. caporderby-92 = # Any valid [SQL] string that goes into a # ORDERBY clause. 4.1.2 SQL-MIN notes (1) No inlined spaces are allowed if not in the grammar above. (2) Note that cmpmin-oper and capmin-logical elements are surrounded by exactly one space. Mansour, et. al. Expires May 21, 2002 [Page 27] Internet-Draft Calendar Access Protocol (CAP) November 2001 Use 'VEVENT,VTODO', not 'VEVENT, VTODO' Use 'DTSTART <= 20000605T131313Z', not 'DTSTART <= 20000605T131313Z'. Use ' AND ' and ' OR ', not 'AND' and not 'OR'. (3) There is no ORDERBY. Sorting will take place in the order the columns are supplied in the command. (4) The CS MUST sort at least the first column. The CS MAY sort additional columns. (5) If EXPAND=FALSE and if colname is "*" sorting will be by the DTSTART value ascending. If EXPAND=TRUE and if colname is "*" sorting will be by the RECURRENCE-ID value ascending. If colname is "*" and capmin-coms is VALARM only then sorting will be by TRIGGER time in UTC ascending. (6) SQL-MIN MUST be implemented. 4.1.3 Querying Experminental Properties 4.1.4 Example, Query by UID The following example would match the entire content of the component with the UID property equal to "uid123" and not expand any multiple instances of the component. If the CUA does not know if "uid123" was a VEVENT, VTODO, VJOURNAL, or any other component, then all components that the CUA supports MUST be supplied on the 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 VEVENT,VTODO WHERE UID = 'uid123' END:VQUERY The following example would match the entire content of the component with the UID property equal to "uid123" and would expand any instances of the component after applying any recurrence rules. This query could select multiple instances of components each with the same UID. Each instance would have a unique RECURRENCE-ID of the expanded component. Mansour, et. al. Expires May 21, 2002 [Page 28] Internet-Draft Calendar Access Protocol (CAP) November 2001 BEGIN:VQUERY EXPAND:TRUE QUERY:SELECT * FROM VEVENT,VTODO WHERE UID = 'uid123' END:VQUERY 4.1.5 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 4.1.6 Query for all Non-Booked Entries The following example selects the entire content of all scheduling VEVENTS in the CS. The default for EXPAND is FALSE, so the recurrence rules will not be expanded. BEGIN:VQUERY QUERY:SELECT * FROM VEVENT,VTODO WHERE METHOD IS NOT NULL END:VQUERY The following example fetches the UIDs of all non-booked VEVENTs and VTODOs. BEGIN:VQUERY QUERY:SELECT UID FROM VEVENT,VTODO WHERE METHOD IS NOT NULL END:VQUERY 4.1.7 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 Mansour, et. al. Expires May 21, 2002 [Page 29] Internet-Draft Calendar Access Protocol (CAP) November 2001 WHERE DTSTART >= '20000201T000000Z' AND DTSTART <= '20000210T235959Z' END:VQUERY 4.1.8 Components With Alarms In A Range This example fetches all components 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 WHERE VALARM.TRIGGER >= '20000101T030405Z' AND VALARM.TRIGGER <= '20001231T235959Z' AND METHOD = 'CREATE' END:VQUERY Mansour, et. al. Expires May 21, 2002 [Page 30] Internet-Draft Calendar Access Protocol (CAP) November 2001 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. Properties within a VCAR must be evaluated in the order provided. 5.1 VCAR Inheritance Calendar access rights specified in a calendar store are inherited as default calendar access rights for any calendar in the parent calendar store. Likewise, any calendar access rights specified in a root calendar are inherited as default calendar access rights for any sub-calendar to the root calendar. Furthermore, calendar access rights specified in a sub-calendar are inherited as default calendar access rights for any calendars that are hierarchically below the sub-calendar. Calendar access rights specified in a calendar override any default calendar access rights. Calendar access rights specified within a sub-calendar override any default calendar access rights. 5.2 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 May 21, 2002 [Page 31] Internet-Draft Calendar Access Protocol (CAP) November 2001 6. Commands and Responses CAP commands and responses are described in this section. As mentioned in Section 3.2, CAP commands are defined by XML documents. The syntax of the commands is defined in Section 9, this section describes their semantic. 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). Response: "uid-list" The "generate-uid" command returns one or more unique identifiers which MUST be unique on the server's calendar store. It is recommended that the return values be globally unique ids. Example: C: MSG 1 5 . 2837 60 C: Content-Type: application/beep+xml C: C: C: END S: RPY 1 5 . 2897 328 S: Content-Type: application/beep+xml S: S: S: 20011121T120000Z-12340@cal.example.com S: 20011121T120000Z-12341@cal.example.com Mansour, et. al. Expires May 21, 2002 [Page 32] Internet-Draft Calendar Access Protocol (CAP) November 2001 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 Service 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. version 1+ Version(s) of CAP, MUST include at least "1.0". query-level 1+ Indicates level of SQL support. SQL-MIN or SQL-92. MUST include at least SQL-MIN. car 1+ Indicates level of CAR support. CAR-MIN or CAR-FULL-1. CAR-MIN MUST be present. Mansour, et. al. Expires May 21, 2002 [Page 33] Internet-Draft Calendar Access Protocol (CAP) November 2001 date 0 or 1 max 0 or 1 The datetime value in UTC beyond which the server cannot accept. If not specified the default is 99991231T235959Z. min 0 or 1 The datetime value prior to which the server cannot accept. If not specified the default is 00000101T000000Z. icalendar 1 Container for CAP related elements. version 1+ Version(s) of iCalendar that is (are) supported. 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 bytes. Objects larger than this will be rejected. The absence of this attribute indicates no limit. itip 1 Container for iTIP related elements. version 1+ Version(s) of ITIP, MUST include at least "1.0". 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: S: 2.1 S: 65536 S: S: S: 1.0 S: S: S: 1.0 S: CAR-MIN S: SQL-MIN S: Mansour, et. al. Expires May 21, 2002 [Page 34] Internet-Draft Calendar Access Protocol (CAP) November 2001 S: 00000101T000000Z S: 99991231T235959Z S: S: S: S: END 6.1.3 "identify" Command Attribute: upn: The UPN of the new identify to assume. Element: 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. 6.1.4 "noop" Command Arguments: None Element: None Response: "result" with the following request-status code: Mansour, et. al. Expires May 21, 2002 [Page 35] Internet-Draft Calendar Access Protocol (CAP) November 2001 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. [EDITORS NOTE: should an unauthenticated and unidentified client be able to issue this command?] [EDITORS NOTE: in view of the integration with BEEP should "noop" be removed?] Example: C: MSG 1 7 . 3705 47 C: Content-Type: application/beep+xml C: C: C: END S: RPY 1 7 . 3752 91 S: Content-Type: application/beep+xml S: S: S: S: S: END 6.2 Calendaring and Scheduling Commands 6.2.1 Restriction Tables Calendaring data are sent encapsulated in iCalendar objects (see Section 6.2.3.1). 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 Mansour, et. al. Expires May 21, 2002 [Page 36] Internet-Draft Calendar Access Protocol (CAP) November 2001 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. 6.2.2 Common Attributes 6.2.2.1 "id" Attribute The "id" attribute is an optional identifier for the command. When specified, the CS will include this attribute in all the related messages it returns to the client. The "id" attribute is mainly useful for the "timeout" message (see Section 3.3). The CAP server imposes no restriction on the value. If uniqueness is required, then it is the responsibility of the CUA to generate unique values. 6.2.3 Common Elements 6.2.3.1 "data" Element The role of the "data" element is to join an iCalendar document to an XML document forming a CAP command or response. The "data" element is composed of a single attribute ("content") that MUST be set to a "cid" URL that refers to an iCalendar document. See Section 3.2 for more information. Depending of the context, the content of the referred iCalendar object is subject to restrictions. See Section 6.2.1 for more details. 6.2.3.2 "select" Element Many calendaring commands can target several components stored on the CS (e.g., "search", "delete", "modify" and "move"). The "select" element is used to identify the targeted components. The "select" element is composed of the following: A "data" element that MUST refer to a VQUERY component. One or more "source" elements that identify the containers to consider. Mansour, et. al. Expires May 21, 2002 [Page 37] Internet-Draft Calendar Access Protocol (CAP) November 2001 Restriction Table for the "data" element: Component/Property Presence Comment ------------------- -------- --------------------------- VCALENDAR 1 . VERSION 1 MUST be 2.1 . [IANA-PROP] 0+ any IANA registered property . VQUERY 1 . . EXPAND 0 or 1 . . QUERYNAME 0 or 1 MUST be present if QUERY is absent. . . QUERY 0 or 1 MUST be present if QUERYNAME is absent. . . [IANA-PROP] 0+ any IANA registered property . VTIMEZONE 0+ MUST be present if any date/time refers to a timezone . . DAYLIGHT 0+ MUST be one or more of either STANDARD or DAYLIGHT . . . . COMMENT 0 or 1 . . . . DTSTART 1 . . . . RDATE 0+ if present RRULE MUST NOT be present . . . . RRULE 0+ if present RDATE MUST NOT be present . . . . TZNAME 0 or 1 . . . . TZOFFSET 1 . . . . TZOFFSETFROM 1 . . . . TZOFFSETTO 1 . . . . X-PROPERTY 0+ . . . . [IANA-PROP] 0+ any IANA registered property . . LAST-MODIFIED 0 or 1 . . STANDARD 0+ . . . . COMMENT 0 or 1 . . . . DTSTART 1 . . . . RDATE 0+ if present RRULE MUST NOT be present . . . . RRULE 0+ if present RDATE MUST NOT be present . . . . TZNAME 0 or 1 . . . . TZOFFSETFROM 1 . . . . TZOFFSETTO 1 . . . . X-PROPERTY 0+ Mansour, et. al. Expires May 21, 2002 [Page 38] Internet-Draft Calendar Access Protocol (CAP) November 2001 . . . . [IANA-PROP] 0+ any IANA registered property . . TZID 1 . . TZURL 0 or 1 . . X-PROPERTY 0+ . . [IANA-PROP] 0+ any IANA registered 6.2.3.3 "source" Element The "source" element is used to specify container(s) that will be examined during the execution of a CAP command. The "source" element is similar to the "target" element (see Section 6.2.3.4, but can refer to several containers (e.g., a calendar hierarchy or all the calendar owned by a given CU). Attributes: csid: when specified MUST point to a CSID. When omitted the CSID of the current server is assumed. relcalid: when specified MUST point to a RELCALID. The value is relative the value of the "csid" attribute. depth: specifies the maximal depth of the calendar hierarchy to explore. When omitted the value "0" is assumed. The accepted values are positives integers and "*". owner: if present MUST be set to a UPN. When specified only the VAGENDA owned by the given UPN are considered. 6.2.3.4 "target" Element The "target" element is used to specify a container targeted by a CAP command (e.g., the destination of a "create" command). A "target" element MAY refer to a VAGENGA or the top level container of a Calendar Store. Attributes: csid: when specified MUST point to a CSID. When omitted the CSID of the current server is assumed. relcalid: when specified MUST point to a RELCALID. The value is relative the value of the "csid" attribute. Mansour, et. al. Expires May 21, 2002 [Page 39] Internet-Draft Calendar Access Protocol (CAP) November 2001 6.2.4 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. 6.2.4.1 "create" Command Attributes: "id" (see Section 6.2.2.1). Elements: "max-time": See Section 3.3. "target": Each "target" element points to a container where the new component will be created. "data": MUST point to an iCalendar object defining the component(s) to create. See the restriction table given below. Response: One "result" message per "target" element MUST be returned (see Section 3.1). One of the following "request-status" codes MUST be returned: 2.0 - successfully created the component or calendar 6.1 - Container not found 6.3 - Bad args The "data" element of each "result" message is subject to the result restriction table defined below. The "create" command is used to create one or more iCalendar objects. The "target" elements specify the containers where the component(s) will be created. Restriction table for the "data" element of the "create" command: Component/Property Presence Comment ------------------- -------- ----------------------------- VCALENDAR 1 Mansour, et. al. Expires May 21, 2002 [Page 40] Internet-Draft Calendar Access Protocol (CAP) November 2001 . VERSION 1 MUST be 2.1 . [IANA-PROP] 0+ any IANA registered property . VAGENDA 0+ . . CALMASTER 0 or 1 . . NAME 0 or 1 . . OWNER 1+ . . RELCALID 1 . . TZID 0 or 1 . . [IANA-PROP] 0+ any IANA registered property . VCAR 0+ . . CARID 0 or 1 . . DENY 0+ Note, there must be at least one GRANT or DENY within the VCAR. . . GRANT 0+ Note, there must be at least one GRANT or DENY within the VCAR. . . [IANA-PROP] 0+ any IANA registered property . VQUERY 0+ . . EXPAND 0 or 1 . . QUERYNAME 1 . . QUERY 1 . . [IANA-PROP] 0+ any IANA registered property . VEVENT 0+ . . ATTENDEE 0+ . . SEQUENCE 0 or 1 MUST be present if value is greater than 0, MAY be present if 0 . . SUMMARY 1 Can be null . . UID 1 . . ATTACH 0+ . . CATEGORIES 0 or 1 . . CLASS 0 or 1 . . COMMENT 0 or 1 . . CONTACT 0+ . . CREATED 0 or 1 . . DESCRIPTION 0 or 1 Can be null . . DTEND 0 or 1 if present DURATION MUST NOT be present Mansour, et. al. Expires May 21, 2002 [Page 41] Internet-Draft Calendar Access Protocol (CAP) November 2001 . . DTSTAMP 1 . . DTSTART 1 . . DURATION 0 or 1 if present DTEND MUST NOT be present . . EXDATE 0+ . . EXRULE 0+ . . GEO 0 or 1 . . LAST-MODIFIED 0 or 1 . . LOCATION 0 or 1 . . ORGANIZER 1 . . PRIORITY 0 or 1 . . RDATE 0+ . . RECURRENCE-ID 0 or 1 only if referring to an instance of a recurring calendar component. Otherwise it MUST NOT be present. . . RELATED-TO 0+ . . REQUEST-STATUS 0+ . . RESOURCES 0 or 1 This property MAY contain a list of values . . RRULE 0+ . . STATUS 0 or 1 . . TRANSP 0 or 1 . . URL 0 or 1 . . X-PROPERTY 0+ . . [IANA-PROP] 0+ any IANA registered property . . VALARM 0+ . . . ACTION 1 . . . ALARMID 1 . . . ATTACH 0+ . . . DESCRIPTION 0 or 1 . . . DURATION 0 or 1 if present REPEAT MUST be present . . . REPEAT 0 or 1 if present DURATION MUST be present . . . SUMMARY 0 or 1 . . . TRIGGER 1 . . . X-PROPERTY 0+ . . . [IANA-PROP] 0+ any IANA registered property . VTODO 0+ . . ATTENDEE 0+ . . SEQUENCE 0 or 1 MUST be present if value is greater than 0, MAY be Mansour, et. al. Expires May 21, 2002 [Page 42] Internet-Draft Calendar Access Protocol (CAP) November 2001 present if 0 . . SUMMARY 1 Can be null. . . UID 1 . . ATTACH 0+ . . CATEGORIES 0 or 1 This property may contain a list of values . . CLASS 0 or 1 . . COMMENT 0 or 1 . . CONTACT 0+ . . CREATED 0 or 1 . . DESCRIPTION 0 or 1 Can be null . . DTSTAMP 1 . . DTSTART 1 . . DUE 0 or 1 If present DURATION MUST NOT be present . . DURATION 0 or 1 If present DUE MUST NOT be present . . EXDATE 0+ . . EXRULE 0+ . . GEO 0 or 1 . . LAST-MODIFIED 0 or 1 . . LOCATION 0 or 1 . . ORGANIZER 1 . . PRIORITY 1 . . PERCENT-COMPLETE 0 or 1 . . RDATE 0+ . . RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a recurring calendar component. Otherwise it MUST NOT be present. . . RELATED-TO 0+ . . REQUEST-STATUS 0 . . RESOURCES 0 or 1 This property may contain a list of values . . RRULE 0+ . . STATUS 0 or 1 MAY be one of COMPLETED, NEEDS-ACTION, IN-PROCESS, CANCELLED . . URL 0 or 1 . . X-PROPERTY 0+ . . [IANA-PROP] 0+ any IANA registered property . . VALARM 0+ . . . ACTION 1 . . . ALARMID 1 Mansour, et. al. Expires May 21, 2002 [Page 43] Internet-Draft Calendar Access Protocol (CAP) November 2001 . . . ATTACH 0+ . . . DESCRIPTION 0 or 1 . . . DURATION 0 or 1 if present REPEAT MUST be present . . . REPEAT 0 or 1 if present DURATION MUST be present . . . SUMMARY 0 or 1 . . . TRIGGER 1 . . . X-PROPERTY 0+ . . . [IANA-PROP] 0+ any IANA registered property . VJOURNAL 0+ . . ATTENDEE 0 . . DESCRIPTION 1 Can be null. . . DTSTAMP 1 . . DTSTART 1 . . ORGANIZER 1 . . UID 1 . . ATTACH 0+ . . CATEGORIES 0 or 1 This property MAY contain a list of values . . CLASS 0 or 1 . . COMMENT 0 or 1 . . CONTACT 0+ . . CREATED 0 or 1 . . EXDATE 0+ . . EXRULE 0+ . . LAST-MODIFIED 0 or 1 . . RDATE 0+ . . RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a recurring calendar component. Otherwise it MUST NOT be present. . . RELATED-TO 0+ . . REQUEST-STATUS 0+ . . RRULE 0+ . . SEQUENCE 0 or 1 MUST be present if non-zero. MAY be present if zero. . . STATUS 0 or 1 . . SUMMARY 0 or 1 Can be null . . URL 0 or 1 . . X-PROPERTY 0+ . . [IANA-PROP] 0+ any IANA registered property Mansour, et. al. Expires May 21, 2002 [Page 44] Internet-Draft Calendar Access Protocol (CAP) November 2001 . VFREEBUSY 0 . VTIMEZONE 0+ MUST be present if any date/time refers to a timezone . . DAYLIGHT 0+ MUST be one or more of either STANDARD or DAYLIGHT . . . . COMMENT 0 or 1 . . . . DTSTART 1 . . . . RDATE 0+ if present RRULE MUST NOT be present . . . . RRULE 0+ if present RDATE MUST NOT be present . . . . TZNAME 0 or 1 . . . . TZOFFSET 1 . . . . TZOFFSETFROM 1 . . . . TZOFFSETTO 1 . . . . X-PROPERTY 0+ . . . . [IANA-PROP] 0+ any IANA registered property . . LAST-MODIFIED 0 or 1 . . STANDARD 0+ . . . . COMMENT 0 or 1 . . . . DTSTART 1 . . . . RDATE 0+ if present RRULE MUST NOT be present . . . . RRULE 0+ if present RDATE MUST NOT be present . . . . TZNAME 0 or 1 . . . . TZOFFSETFROM 1 . . . . TZOFFSETTO 1 . . . . X-PROPERTY 0+ . . . . [IANA-PROP] 0+ any IANA registered property . . TZID 1 . . TZURL 0 or 1 . . X-PROPERTY 0+ . . [IANA-PROP] 0+ any IANA registered property Restriction Table for the "data" element of the "result" response: Component/Property Presence Comment ------------------- -------- ------------------------------- VCALENDAR 1+ . VERSION 1 MUST be 2.1 . VAGENDA 0+ Mansour, et. al. Expires May 21, 2002 [Page 45] Internet-Draft Calendar Access Protocol (CAP) November 2001 . . RELCALID 1 . . REQUEST-STATUS 1+ . VCAR 0+ . . CARID 1 . . REQUEST-STATUS 1+ . VEVENT 0+ . . UID 1 The UID for which this REQUEST-STATUS applies . . REQUEST-STATUS 1+ . . RECURRENCE-ID 0 or 1 MUST be specified only if instance of a recurring component was created. . . 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 The UID for which this REQUEST-STATUS applies . . RECURRENCE-ID 0 or 1 MUST be specified only if instance of a recurring component was created. . . REQUEST-STATUS 1+ . VQUERY 0+ . . REQUEST-STATUS 1+ . VTODO 0+ . . UID 1 The UID for which this REQUEST-STATUS applies . . RECURRENCE-ID 0 or 1 MUST be specified only if instance of a recurring component was created. . . REQUEST-STATUS 1+ . . VALARM 0 if VTODO was successfully saved 1+ if there were errors saving alarms . . . ALARMID 1 . . . REQUEST-STATUS 1+ Example: In the following example, two new top level VAGENDAs are created. Mansour, et. al. Expires May 21, 2002 [Page 46] Internet-Draft Calendar Access Protocol (CAP) November 2001 Note that the CSID of the server is cal.example.com. C: MSG 1 8 . 3843 778 C: Content-Type: multipart/related; boundary="boundary-foo321"; C: start="1@cal.example.com"; C: type="application/beep+xml" C: C: --boundary-foo321 C: Content-Type: application/beep+xml C: Content-ID: 1@cal.example.com C: C: C: C: C: C: --boundary-foo321 C: Content-Type: text/calendar C: Content-ID: 2@cal.example.com C: C: BEGIN:VCALENDAR C: VERSION:2.1 C: BEGIN:VAGENDA C: RELCALID:relcalz1 C: NAME;LANGUAGE=EN-us:Bill's Soccer Team C: OWNER:bill C: CALMASTER:mailto:bill@example.com C: TZID:US_PST C: END:VAGENDA C: BEGIN:VAGENDA C: RELCALID:relcalz2 C: NAME;LANGUAGE=EN-us:Mary's personal calendar C: OWNER:mary C: CALMASTER:mailto:mary@example.com C: TZID:US_PST C: END:VAGENDA C: END:VCALENDAR C: --boundary-foo321-- C: END S: RPY 1 8 . 4621 647 S: Content-Type: multipart/related; boundary="boundary-bar321"; S: start="1@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-bar321 S: Content-Type: application/beep+xml S: Content-ID: 1@cal.example.com S: S: Mansour, et. al. Expires May 21, 2002 [Page 47] Internet-Draft Calendar Access Protocol (CAP) November 2001 S: S: S: S: S: --boundary-bar321 S: Content-Type:text/calendar; S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: VERSION:2.1 S: BEGIN:VAGENDA S: RELCALID:relcalz1 S: REQUEST-STATUS:2.0 S: END:VAGENDA S: BEGIN:VAGENDA S: RELCALID:relcalz2 S: REQUEST-STATUS:2.0 S: END:VAGENDA S: END:VCALENDAR S: --boundary-bar321-- S: END Example to create a new component in multiple containers. C: MSG 1 9 . 5268 622 C: Content-Type: multipart/related; boundary="boundary-kshgd"; C: start="1@cal.example.com"; C: type="application/beep+xml" C: C: --boundary-kshgd C: Content-Type: application/beep+xml C: Content-ID: 1@cal.example.com C: C: C: C: C: C: C: --boundary-kshgd C: Content-Type: text/calendar C: Content-ID: 2@cal.example.com C: C: BEGIN:VCALENDAR C: VERSION:2.1 C: BEGIN:VEVENT C: DTSTART:99990307T180000Z C: UID:abcd12345 C: DTEND:99990307T190000Z Mansour, et. al. Expires May 21, 2002 [Page 48] Internet-Draft Calendar Access Protocol (CAP) November 2001 C: SUMMARY:Important Meeting C: END:VEVENT C: END:VCALENDAR C: --boundary-kshgd-- C: END S: ANS 1 9 . 58901 563 0 S: Content-Type: multipart/related; boundary="boundary-eqrga"; S: start="1@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-eqrga S: Content-Type: application/beep+xml S: Content-ID: 1@cal.example.com S: S: S: S: S: S: S: --boundary-eqrga S: Content-Type: text/calendar S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: VERSION:2.1 S: BEGIN:VEVENT S: UID:abcd12345 S: REQUEST-STATUS:2.9 S: END:VEVENT S: END:VCALENDAR S: --boundary-eqrga-- S: END S: ANS 1 9 . 6453 563 1 S: Content-Type: multipart/related; boundary="boundary-982hf"; S: start="1@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-982hf S: Content-Type: application/beep+xml S: Content-ID: 1@cal.example.com S: S: S: S: S: S: S: --boundary-982hf S: Content-Type: text/calendar Mansour, et. al. Expires May 21, 2002 [Page 49] Internet-Draft Calendar Access Protocol (CAP) November 2001 S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: VERSION:2.1 S: BEGIN:VEVENT S: UID:abcd12345 S: REQUEST-STATUS:6.0 S: END:VEVENT S: END:VCALENDAR S: --boundary-982hf-- S: END S: NUL 1 9 . 7016 0 S: END As described in Section 3.1, the CS sends one response per "target" element present in the "create" command. 6.2.4.2 "delete" Command Attributes: "id" (see Section 6.2.2.1). Elements: "max-time": See Section 3.3. "select": specifies the compoments to delete (see Section 6.2.3.2). Response: One "result" message per "source" in the "select" element (see Section 3.1). One of the following "request-status" codes MUST be returned: 2.0 - successfully created 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 define below. The "delete" command is used to delete a calendar or component. The "select" element specifies the container(s) to delete. Mansour, et. al. Expires May 21, 2002 [Page 50] Internet-Draft Calendar Access Protocol (CAP) November 2001 Restriction Table for the "data" element of the "result" response(s). Component/Property Presence Comment ------------------- -------- ----------------------------- VCALENDAR 1+ . VERSION 1 MUST be 2.1 . VAGENDA Only if VAGENDAS were deleted . RELCALID 1 . REQUEST-STATUS 1 . VCAR 0+ Only if VCAR components were deleted . . CARID 1 . . REQUEST-STATUS 1 . VEVENT 0+ Only if VEVENT components were deleted . . 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 deleted . . . ALARMID 1 . . . REQUEST-STATUS 1 . VFREEBUSY 0 . . UID 1 . . DTSTAMP 1 . . REQUEST-STATUS 1 . VJOURNAL 0+ Only if VJOURNAL components were deleted . . UID 1 . . REQUEST-STATUS 1 . VQUERY 0+ Only if VQUERY components were deleted . UID 1 . REQUEST-STATUS 1 . VTIMEZONE 0+ Only if VTIMEZONE components . . TZID were deleted . . REQUEST-STATUS 1 Mansour, et. al. Expires May 21, 2002 [Page 51] Internet-Draft Calendar Access Protocol (CAP) November 2001 . VTODO 0+ Only if VTODO components were deleted . . 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 deleted . . . ALARMID 1 . . . REQUEST-STATUS 1 ---------------------------------------------------------- [EDITORS NOTE: Issues: - Can one use DELETE to remove all VALARMs and VTIMEZONEs that match a certain search criteria and that belong to all components, event though VALARMs and VTIMEZONEs never exist as independent components? Or should one use MODIFY? If they can be deleted, do we return the REQUEST-STATUS of their deletion in a VEVENT or separately? Example to delete a VEVENT with UID 'abcd12345' from any of the calendar owned by the CU with the UPN="user@cal.example.com": C: MSG 1 10 . 7016 558 C: Content-Type: multipart/related; boundary="boundary-gsdmx3"; C: start="1@cal.example.com"; C: type="application/beep+xml" C: C: --boundary-gsdmx3 C: Content-Type: application/beep+xml C: Content-ID: 1@cal.example.com C: C: C: C: C: --boundary-gsdmx3 C: Content-Type: text/calendar C: Content-ID: 2@cal.example.com C: C: BEGIN:VQUERY C: QUERY:SELECT * FROM VEVENT WHERE UID = 'abcd12345' C: END:VQUERY Mansour, et. al. Expires May 21, 2002 [Page 52] Internet-Draft Calendar Access Protocol (CAP) November 2001 C: --boundary-gsdmx3-- C: END S: RPY 1 10 . 7574 587 S: Content-Type: multipart/related; boundary="boundary-oifc3j"; S: start="1@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-oifc3j S: Content-Type: application/beep+xml S: Content-ID: 1@cal.example.com S: S: S: S: S: S: S: --boundary-oifc3j S: Content-Type: text/calendar S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: VERSION:2.1 S: BEGIN:VEVENT S: UID:abcd12345 S: REQUEST-STATUS: 2.0 S: END:VEVENT S: END:VCALENDAR S: --boundary-oifc3j-- S: END 6.2.4.3 "modify" Command Attributes: "id" (see Section 6.2.2.1). Elements: "max-time": See Section 3.3. "select": identifies the component(s) to modify. "add": adds properties to the selected component(s). "remove": removes properties from the selected component(s). "update": updates the content of the selected component(s). Mansour, et. al. Expires May 21, 2002 [Page 53] Internet-Draft Calendar Access Protocol (CAP) November 2001 Response: One "result" message per "source" in the "select" is returned (see Section 3.1). One of the following "request-status" codes MUST be returned: 2.0 - successfully created the component or calendar 6.1 - Container not found 6.3 - Bad args The "data" element of each "result" message is subject to the restriction table defined below. The "modify" command is used to modify existing components. The "select" element specifies the components to modify. The "add", "remove" and "update" elements define the operations to perform. The "add" element is used to add properties or nested components to the selected components. The "add" element is composed of a "data" element that contains a component with the properties to add. For example to add an inline attachment to a VEVENT the following iCalendar object could be: BEGIN:VCALENDAR BEGIN:VEVENT ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY: MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE <...remainder of "BASE64" encoded binary data...> END:VEVENT END:VCALENDAR The "remove" element is used to remove properties from the selected components. The "data" element contains an iCalendar with the properties to delete. When the "ignore-value" attribute is set to true, all the properties specified in the "data" element are removed even if the values do not match the current state of the component. This is useful to remove potentially large properties efficiently (e.g., "ATTACH"). The "update" element is used to update or add the properties referred to by the "data" element. If the "remove-missing" attribute is set to true, then all the elements not present in the "data" element document will be removed from the selected components. Mansour, et. al. Expires May 21, 2002 [Page 54] Internet-Draft Calendar Access Protocol (CAP) November 2001 When more than one operations is specified, the modifications MUST must respect the following order: "remove" followed by "update" followed by "add". The modifications MUST only be applied if the resulting component respects the restriction table of the "create" command. Restriction Table for "data" element of the "result" response: Component/Property Presence Comment ------------------- -------- ------------------------------- VCALENDAR 1+ . VERSION 1 MUST be 2.1 . VAGENDA 0+ . . RELCALID 1 . . REQUEST-STATUS 1+ . VCAR 0+ . . CARID 1 . . REQUEST-STATUS 1+ . VEVENT 0+ . . UID 1 . . RECURRENCE-ID 0 or 1 MUST be specified only if instance of a recurring component was modified. . . REQUEST-STATUS 1+ . . VALARM 0 if VEVENT was successfully saved 1+ if there were errors saving alarms . . . REQUEST-STATUS 1+ . VFREEBUSY 0 . VJOURNAL 0+ . . UID 1 . . RECURRENCE-ID 0 or 1 MUST be specified only if instance of a recurring component was modified. . . REQUEST-STATUS 1+ . VQUERY 0+ . . REQUEST-STATUS 1+ . VTODO 0+ . . UID 1 . . RECURRENCE-ID 0 or 1 MUST be specified only if instance of Mansour, et. al. Expires May 21, 2002 [Page 55] Internet-Draft Calendar Access Protocol (CAP) November 2001 a recurring component was modified. . . REQUEST-STATUS 1+ . . VALARM 0 if VTODO was successfully saved 1+ if there were errors saving alarms . . . REQUEST-STATUS 1+ In the example below, the start and end time of the event with UID abcd12345 is changed and the LOCATION property is removed. C: MSG 1 11 . 8161 1144 C: Content-Type: multipart/related; boundary="boundary-324dav"; C: start="1@cal.example.com"; C: type="application/beep+xml" C: C: --boundary-324dav C: Content-Type: application/beep+xml C: Content-ID: 1@cal.cal.example.com C: C: C: C: C: C: C: C: C: C: C: --boundary-324dav C: Content-Type: text/calendar C: Content-ID: query@cal.example.com C: C: BEGIN:VCALENDAR C: BEGIN:VQUERY C: QUERY: SELECT * FROM VEVENT WHERE UID='abcd12345' C: END:VQUERY C: END:VCALENDAR C: --boundary-324dav C: Content-Type: text/calendar C: Content-ID: remove@cal.example.com C: C: BEGIN:VCALENDAR C: BEGIN:VEVENT C: LOCATION: Mansour, et. al. Expires May 21, 2002 [Page 56] Internet-Draft Calendar Access Protocol (CAP) November 2001 C: END:VEVENT C: END:VCALENDAR C: --boundary-324dav C: Content-Type: text/calendar C: Content-ID: update@cal.example.com C: C: BEGIN:VCALENDAR C: BEGIN:VEVENT C: DTSTART:19990421T160000Z C: DTEND:19990421T163000Z C: END:VEVENT C: END:VCALENDAR C: --boundary-324dav-- C: END S: RPY 1 11 . 9305 570 S: Content-Type: multipart/related; boundary="boundary-tvx2"; S: start="command@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-tvx2 S: Content-Type: application/beep+xml S: Content-ID: command@cal.example.com S: S: S: S: S: S: S: --boundary-tvx2 S: Content-Type: text/calendar S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: BEGIN:VEVENT S: UID:abcd12345 S: REQUEST-STATUS: 2.0 S: END:VEVENT S: END:VCALENDAR S: --boundary-tvx2-- S: END In this example, all instances of "Building 6" are replaced by "New office lobby" in VEVENTs: C: MSG 1 12 . 9875 870 C: Content-Type: multipart/related; boundary="boundary-trew2"; C: start="1@cal.example.com"; C: type="application/beep+xml" Mansour, et. al. Expires May 21, 2002 [Page 57] Internet-Draft Calendar Access Protocol (CAP) November 2001 C: C: --boundary-trew2 C: Content-Type: application/beep+xml C: Content-ID: 1@cal.example.com C: C: C: C: C: C: C: C: --boundary-trew2 C: Content-Type: text/calendar C: Content-ID: query@cal.example.com C: C: BEGIN:VCALENDAR C: BEGIN:VQUERY C: QUERY: SELECT * FROM VEVENT WHERE LOCATION='Building 6' C: END:VQUERY C: END:VCALENDAR C: --boundary-trew2 C: Content-Type: text/calendar C: Content-ID: update@cal.example.com C: C: BEGIN:VCALENDAR C: BEGIN:VEVENT C: LOCATION:New office lobby C: END:VEVENT C: END:VCALENDAR C: --boundary-trew2-- C: END S: RPY 1 12 . 10745 578 S: Content-Type: multipart/related; boundary="boundary-poiu51"; S: start="command@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-poiu51 S: Content-Type: application/beep+xml S: Content-ID: command@cal.example.com S: S: S: S: S: S: Mansour, et. al. Expires May 21, 2002 [Page 58] Internet-Draft Calendar Access Protocol (CAP) November 2001 S: --boundary-poiu51 S: Content-Type: text/calendar S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: BEGIN:VEVENT S: UID:abcd12345 S: REQUEST-STATUS: 2.0 S: END:VEVENT S: END:VCALENDAR S: --boundary-poiu51-- S: END 6.2.4.4 "move" Command Attributes: "id" (see Section 6.2.2.1). 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 created 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 hierarchy of calendars. When moving VAGENDA, the CS MUST ensure that VCARs are still valid after the move, and the CS MUST update the Mansour, et. al. Expires May 21, 2002 [Page 59] Internet-Draft Calendar Access Protocol (CAP) November 2001 PARENT and CHILDREN properties of the new and old parent containers. Restriction Table for "data" element of the "result" response: Component/Property Presence Comment ------------------- -------- ------------------------------- VCALENDAR 1+ . VERSION 1 MUST be 2.1 . 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 1+ if there were errors saving alarms . . . ALARMID 1 . . . REQUEST-STATUS 1+ Mansour, et. al. Expires May 21, 2002 [Page 60] Internet-Draft Calendar Access Protocol (CAP) November 2001 --------------------------------------------------------- [EDITORS NOTE: Issues: 1) Should one be able to move a calendar owned by person X into a calendar owned by person Y. (Can these such rights be specified in VCARs?) 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 May 21, 2002 [Page 61] Internet-Draft Calendar Access Protocol (CAP) November 2001 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.4.5 "search" Command Attributes: "id" (see Section 6.2.2.1). Elements: "max-time": See Section 3.3. "select": identifies the components to return. "max-results": maximum number of components to return per source (if omited unlimited). "max-size": maximum size in bytes, of the iCalendar object to return. Response: A "result" message per "source" in the "select" element is returned (see Section 3.1). One of the following "request-status" codes MUST be returned: 2.0 - successfully created the component or calendar 6.1 - Container not found 6.3 - Bad args Mansour, et. al. Expires May 21, 2002 [Page 62] Internet-Draft Calendar Access Protocol (CAP) November 2001 The "data" element of each "result" message points to 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. 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. The first result returns two VEVENTs that match in that "source", the second result returns only one VEVENT for the second "source". C: MSG 1 13 . 12507 704 C: Content-Type: multipart/related; boundary="boundary-5329"; C: start="1@cal.example.com"; C: type="application/beep+xml" C: C: --boundary-5329 C: Content-Type: application/beep+xml C: Content-ID: 1@cal.example.com C: C: C: C: C: --boundary-5329 C: Content-Type: text/calendar C: Content-ID: query@cal.example.com C: C: BEGIN:VCALENDAR 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 NULL C: END:VQUERY C: END:VCALENDAR C: --boundary-5329-- C: END S: ANS 1 13 . 13211 803 0 S: Content-Type: multipart/related; boundary="boundary-f4fw2"; S: start="answer@cal.example.com"; Mansour, et. al. Expires May 21, 2002 [Page 63] Internet-Draft Calendar Access Protocol (CAP) November 2001 S: type="application/beep+xml" S: S: --boundary-f4fw2 S: Content-Type: application/beep+xml S: Content-ID: answer@cal.example.com S: S: S: S: S: S: S: --boundary-f4fw2 S: Content-Type: text/calendar S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: VERSION:2.1 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: --boundary-f4fw2-- S: END S: ANS 1 13 . 14014 664 1 S: Content-Type: multipart/related; boundary="boundary-r432"; S: start="answer@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-r432 S: Content-Type: application/beep+xml S: Content-ID: answer@cal.example.com S: S: S: S: S: S: Mansour, et. al. Expires May 21, 2002 [Page 64] Internet-Draft Calendar Access Protocol (CAP) November 2001 S: --boundary-r432 S: Content-Type: text/calendar S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: VERSION:2.1 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 S: --boundary-r432-- S: END S: NUL 1 13 . 14678 0 S: END 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: [EDITORS NOTE: Should the one(s) that the UPN has access to - be returned?] S: ANS 1 13 . 14014 548 0 S: Content-Type: multipart/related; boundary="boundary-fmei3"; S: start="command@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-fmei3 S: Content-Type: application/beep+xml S: Content-ID: command@cal.example.com S: S: S: S: S: S: S: --boundary-fmei3 S: Content-Type: text/calendar S: Content-ID: 2@cal.example.com Mansour, et. al. Expires May 21, 2002 [Page 65] Internet-Draft Calendar Access Protocol (CAP) November 2001 S: S: BEGIN:VCALENDAR S: VERSION:2.1 S: BEGIN:VEVENT S: REQUEST-STATUS:4.1 S: END:VEVENT S: END:VCALENDAR S: --boundary-fmei3-- S: END If the UPN has no access to any events at all, the response will simply be an empty data set. The response looks the same if there are particular events to which the CU has been denied access. S: ANS 1 13 . 14014 502 0 S: Content-Type: multipart/related; boundary="boundary-ewrvc"; S: start="command@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-ewrvc S: Content-Type: application/beep+xml S: Content-ID: command@cal.example.com S: S: S: S: S: S: S: --boundary-ewrvc S: Content-Type: text/calendar S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: VERSION:2.1 S: END:VCALENDAR S: --boundary-ewrvc-- S: END Find alarms within a range of time for booked VEVENTs. C: MSG 1 15 . 14678 747 C: Content-Type: multipart/related; boundary="boundary-weoiu"; C: start="1@cal.example.com"; C: type="application/beep+xml" C: C: --boundary-weoiu C: Content-Type: application/beep+xml C: Content-ID: 1@cal.example.com Mansour, et. al. Expires May 21, 2002 [Page 66] Internet-Draft Calendar Access Protocol (CAP) November 2001 C: C: C: C: C: --boundary-weoiu C: Content-Type: text/calendar C: Content-ID: query@cal.example.com C: C: BEGIN:VCALENDAR C: BEGIN:VQUERY C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID,VALARM.* C: FROM VEVENT,VTODO C: WHERE VALARM.TRIGGER >= '19990310T080000Z' C: AND VALARM.TRIGGER <= '19990310T190000Z' C: AND METHOD IS NULL C: END:VQUERY C: END:VCALENDAR C: --boundary-weoiu-- C: END S: ANS 1 15 . 15426 511 0 S: Content-Type: multipart/related; boundary="boundary-kjhs"; S: start="command@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-kjhs S: Content-Type: application/beep+xml S: Content-ID: command@cal.example.com S: S: S: S: S: S: S: --boundary-kjhs S: Content-Type: text/calendar S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: VERSION:2.1 S: END:VCALENDAR S: --boundary-kjhs-- S: END S: ANS 1 2 . 15937 734 1 S: Content-Type: multipart/related; boundary="boundary-435fe"; Mansour, et. al. Expires May 21, 2002 [Page 67] Internet-Draft Calendar Access Protocol (CAP) November 2001 S: start="command@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-435fe S: Content-Type: application/beep+xml S: Content-ID: command@cal.example.com S: S: S: S: S: S: S: --boundary-435fe S: Content-Type: text/calendar S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: VERSION:2.1 S: BEGIN:VEVENT S: DTSTART:19990310T130000Z S: DTEND:19990310T133000Z S: UID:abcxyz8999 S: SUMMARY:Meet with brave Sir Robin S: BEGIN:VALARM S: TRIGGER:19990310T132500Z S: SUMMARY:Almost time... S: ACTION:DISPLAY S: END:VALARM S: END:VEVENT S: END:VCALENDAR S: --boundary-435fe-- S: END S: NUL 1 15 . 16671 0 S: END In this example bill@example.com reads a day's worth of events from cap://cal.example.com/opaqueid99. C: MSG 1 16 . 16671 668 C: Content-Type: multipart/related; boundary="boundary-vnj43"; C: start="1@cal.example.com"; C: type="application/beep+xml" C: C: --boundary-vnj43 C: Content-Type: application/beep+xml C: Content-ID: 1@cal.example.com C: C: Mansour, et. al. Expires May 21, 2002 [Page 68] Internet-Draft Calendar Access Protocol (CAP) November 2001 C: C: C: --boundary-vnj43 C: Content-Type: text/calendar C: Content-ID: query@cal.example.com C: C: BEGIN:VCALENDAR C: VERSION:2.1 C: BEGIN:VQUERY C: QUERY:SELECT DTSTART,DTEND,SUMMARY, UID FROM VEVENT C: WHERE DTEND >= '19990714T080000Z' C: AND DTSTART <= '19990715T080000Z' C: END:VQUERY C: END:VCALENDAR C: --boundary-vnj43-- C: END S: RPY 1 16 . 17359 751 S: Content-Type: multipart/related; boundary="boundary-rfew"; S: start="command@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-rfew S: Content-Type: application/beep+xml S: Content-ID: command@cal.example.com S: S: S: S: S: S: S: --boundary-rfew S: Content-Type: text/calendar S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: VERSION:2.1 S: BEGIN:VEVENT S: DTSTART:19990714T200000Z S: DTEND:19990714T210000Z S: UID:000444888929922 S: SUMMARY:Blah blah S: END:VEVENT S: BEGIN:VEVENT S: UID:0034848098038888989443 S: SUMMARY:meeting Mansour, et. al. Expires May 21, 2002 [Page 69] Internet-Draft Calendar Access Protocol (CAP) November 2001 S: DTEND:19990714T233000Z S: DTSTART:19990714T223000Z S: END:VEVENT S: END:VCALENDAR S: --boundary-rfew-- S: END In this example bill@example.com reads a day's worth of events from cap://cal.example.com/opaqueid101 and cap://cal.example.com/opaqueid103 C: MSG 1 17 . 18110 694 C: Content-Type: multipart/related; boundary="boundary=wtu"; C: start="1@cal.example.com"; C: type="application/beep+xml" C: C: --boundary=wtu C: Content-Type: application/beep+xml C: Content-ID: 1@cal.example.com C: C: C: C: C: --boundary=wtu C: Content-Type: text/calendar C: Content-ID: query@cal.example.com C: C: BEGIN:VCALENDAR C: VERSION:2.1 C: BEGIN:VQUERY C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID FROM VEVENT C: WHERE DTEND >= 19990714T080000Z AND C: DTSTART <= 19990715T080000Z C: END:VQUERY C: END:VCALENDAR C: --boundary=wtu-- C: END S: ANS 1 17 . 18804 717 0 S: Content-Type: multipart/related; boundary="boundary-09436"; S: start="command@cal.example.com"; S: type="application/beep+xml" S: S: --boundary-09436 Mansour, et. al. Expires May 21, 2002 [Page 70] Internet-Draft Calendar Access Protocol (CAP) November 2001 S: Content-Type: application/beep+xml S: Content-ID: command@cal.example.com S: S: S: S: # this response code means that the transport successfully # delivered the data. S: S: S: --boundary-09436 S: Content-Type: text/calendar S: Content-ID: 2@cal.example.com S: S: BEGIN:VCALENDAR S: VERSION:2.1 S: BEGIN:VEVENT S: UID:0034848098038888989443 S: SUMMARY:meeting S: DTEND:19990714T233000Z S: DTSTART:19990714T223000Z S: END:VEVENT S: END:VCALENDAR S: --boundary-09436-- S: END S: ANS 1 18 . 19521 216 1 S: Content-Type: application/beep+xml S: S: S: S: Access Denied S: S: S: END S: NUL 1 18 . 19737 0 S: END Stored VQUERY can be used by specifying the property QUERYNAME instead of QUERY. Example: BEGIN:VQUERY QUERYNAME:StoredVQuery-1 END:VQUERY Mansour, et. al. Expires May 21, 2002 [Page 71] Internet-Draft Calendar Access Protocol (CAP) November 2001 This match all calendar store properties. This MUST NOT return any VAGENDAs. BEGIN:VCALENDAR VERSION:2.1 BEGIN:VQUERY QUERY:SELECT * FROM CALSTORE WHERE CSID='bobo.ex.com' END:VQUERY END:VCALENDAR This will match all properties of the VAGENDA relcal4. This MUST NOT return any components. BEGIN:VCALENDAR VERSION:2.1 BEGIN:VQUERY QUERY:SELECT * FROM VAGENDA WHERE RELCALID='relcal4' END:VQUERY END:VCALENDAR This will fetch all stored VQUERYs. BEGIN:VCALENDAR VERSION:2.1 BEGIN:VQUERY QUERY:SELECT * FROM VQUERY WHERE QUERYNAME IS NOT NULL END:VQUERY END:VCALENDAR 6.3 Scheduling Commands Scheduling commands allow a CU to indirectly manipulate a calendar by asking another CU to perform an operation on their calendar. For example, CU-A can request CU-B to add a meeting to their calendar; in effect inviting CU-B to the meeting. Calendar access rights can be granted for scheduling commands without granting rights for more generalized access with the calendar commands. [EDITORS NOTE: This section needs to be completed by adding the restriction tables for each of these iTIP methods. The basis for the text is to be taken from [iTIP].] 6.3.1 "schedule" Command Attributes: Mansour, et. al. Expires May 21, 2002 [Page 72] Internet-Draft Calendar Access Protocol (CAP) November 2001 "id" (see Section 6.2.2.1). Elements: "max-time": See Section 3.3. "target": Each "target" element points to a container where the sceduled element will be created. "data": MUST point to a valid iTip iCalendar object. Refer to [iTIP] for the definition of the accepted METHOD and restriction tables. Response: One "result" message per "target" element MUST be returned (see Section 3.1). One of the following "request-status" codes MUST be returned: 2.0 - Success 6.1 - Container not found 6.3 - Bad args Additionnal request-status code MAY be returned as described on [iTIP]. The "data" element of each "result" message is subject to the result restriction table defined below. The "schedule" command insert a new scheduled component into the VSCHEDULE set of the container(s) referred to by the "target" element(s). A Calendar Service MUST accept iCalendar object with the following METHODs as described in [iTIP]: ----------------------------------------------------------- Command Description ----------------------------------------------------------- PUBLISH Publish a calendar entry to one or more calendars. REQUEST Schedule a calendar entry with one or more calendars. REPLY Response to a scheduling request. ADD Add one or more instances to an existing Mansour, et. al. Expires May 21, 2002 [Page 73] Internet-Draft Calendar Access Protocol (CAP) November 2001 calendar entry. CANCEL Cancel one or more instances to an existing calendar entry. REFRESH A request for the latest version of a calendar entry. COUNTER A request for a change (a counter-proposal) to a calendar entry. DECLINECOUNTER Decline a counter proposal. ----------------------------------------------------------- 6.3.2 Processing Scheduling Components A CU might be invited to a meeting. If the CU had been invited by CAP, the entry in the CU calendar will be scheduled, but not booked. So a CUA will need to look for scheduled entries in the calendar and present them to the CU or automatically decide if the invitation is to be accepted or processed. Example: The little league coach places the teams entire schedule into your calendar. Lets say that every game and practice is on a Friday night and your calendar now has this iTIP scheduling data: BEGIN:VCALENDAR VERSION:2.0 METHOD:PUBLISH BEGIN:VEVENT DTSTAMP;TZID=US/Pacific:20000229T180000 DTSTART;TZID=US/Pacific:20000303T180000 ORGANIZER:coach@little.league.com SUMMARY:Schedule of games and practice UID:1-coach@little.league.com SEQUENCE:0 DESCRIPTION:Please have your child at the field and ready to play by 6pm. RRULE:FREQ=WEEKLY;COUNT=10 END:VEVENT END:VCALENDAR At this point the above VEVENT is not booked in your calendar; it is simply