Network Working Group D. Royer Internet-Draft INET-Consulting Expires: December 29, 2002 G. Babics Steltor P. Hill MIT S. Mansour AOL/Netscape June 30, 2002 Calendar Access Protocol (CAP) draft-ietf-calsch-cap-08 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 December 29, 2002. Copyright Notice Copyright (C) The Internet Society (2002). All Rights Reserved. Abstract The Calendar Access Protocol (CAP) is an Internet protocol described in this memo that permits a Calendar User (CU) to utilize a Calendar User Agent (CUA) to access an [iCAL] based Calendar Store (CS). The CAP definition is based on requirements identified by the Internet Engineering Task Force (IETF) Calendaring and Scheduling Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 1] Internet-Draft Calendar Access Protocol (CAP) June 2002 (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 . . . . . . . . . . . . . . . . . . . . . . 7 2. Additions to iCalendar . . . . . . . . . . . . . . . . . 12 2.1 New Value Types (summary) . . . . . . . . . . . . . . . 13 2.1.1 New Parameters (summary) . . . . . . . . . . . . . . . . 14 2.1.2 New Properties (summary) . . . . . . . . . . . . . . . . 15 2.1.3 New Components (summary) . . . . . . . . . . . . . . . . 17 2.2 Relationship of RFC-2446 (ITIP) and CAP . . . . . . . . 17 3. CAP Design . . . . . . . . . . . . . . . . . . . . . . . 20 3.1 System Model . . . . . . . . . . . . . . . . . . . . . . 20 3.2 Calendar Store Object Model . . . . . . . . . . . . . . 20 3.3 Protocol Model . . . . . . . . . . . . . . . . . . . . . 21 3.3.1 Use of BEEP, MIME and iCalendar . . . . . . . . . . . . 22 4. Security Model . . . . . . . . . . . . . . . . . . . . . 24 4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . . 24 4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . . 24 4.1.2 Anonymous Users and Authentication . . . . . . . . . . . 25 4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . . 25 4.2 Access Rights . . . . . . . . . . . . . . . . . . . . . 26 4.2.1 Access Control and NOCONFLICT . . . . . . . . . . . . . 26 4.2.2 Calendar Access Right (VCAR) . . . . . . . . . . . . . . 26 4.2.3 Predefined VCARs . . . . . . . . . . . . . . . . . . . . 27 4.2.4 Decreed VCARs . . . . . . . . . . . . . . . . . . . . . 28 4.3 CAP Session Identity . . . . . . . . . . . . . . . . . . 29 5. CAP URL and Calendar Address . . . . . . . . . . . . . . 31 6. New Components, Properties, Parameters, and Values . . . 33 6.1 Property Value Data Types . . . . . . . . . . . . . . . 33 6.1.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . . . 33 6.1.1.1 CAL-OWNERS() . . . . . . . . . . . . . . . . . . . . . . 39 6.1.1.2 CURRENT-TARGET() . . . . . . . . . . . . . . . . . . . . 39 6.1.1.3 [NOT] OWNER() . . . . . . . . . . . . . . . . . . . . . 39 6.1.1.4 SELF() . . . . . . . . . . . . . . . . . . . . . . . . . 39 6.1.1.5 STATE() . . . . . . . . . . . . . . . . . . . . . . . . 39 6.1.1.6 Ordering of Results . . . . . . . . . . . . . . . . . . 39 6.1.1.7 Date sorting order . . . . . . . . . . . . . . . . . . . 40 6.1.1.8 Use of single quote . . . . . . . . . . . . . . . . . . 41 6.1.1.9 Comparing DATE and DATE-TIME values . . . . . . . . . . 41 Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 2] Internet-Draft Calendar Access Protocol (CAP) June 2002 6.1.1.10 DTEND and DURATION . . . . . . . . . . . . . . . . . . . 42 6.1.1.11 [NOT] LIKE . . . . . . . . . . . . . . . . . . . . . . . 44 6.1.1.12 Empty vs. NULL . . . . . . . . . . . . . . . . . . . . . 44 6.1.1.13 [NOT] IN . . . . . . . . . . . . . . . . . . . . . . . . 45 6.1.1.14 DATE-TIME and TIME values in a WHEN clause . . . . . . . 46 6.1.1.15 Multiple contained components . . . . . . . . . . . . . 46 6.1.1.16 Example, Query by UID . . . . . . . . . . . . . . . . . 47 6.1.1.17 Query by Date-Time range . . . . . . . . . . . . . . . . 47 6.1.1.18 Query for all Unprocessed Entries . . . . . . . . . . . 47 6.1.1.19 Query with Subset of Properties by Date/Time . . . . . . 48 6.1.1.20 Query with Components and Alarms In A Range . . . . . . 49 6.1.2 UPN Value Type . . . . . . . . . . . . . . . . . . . . . 49 6.1.3 UPN-FILTER Value . . . . . . . . . . . . . . . . . . . . 50 6.2 New Parameter . . . . . . . . . . . . . . . . . . . . . 51 6.2.1 ENABLE Parameter . . . . . . . . . . . . . . . . . . . . 51 6.2.2 LOCAL Parameter . . . . . . . . . . . . . . . . . . . . 52 7. New Properties . . . . . . . . . . . . . . . . . . . . . 54 7.1 ALLOW-CONFLICT Property . . . . . . . . . . . . . . . . 54 7.2 CALID Property . . . . . . . . . . . . . . . . . . . . . 54 7.3 CALMASTER Property . . . . . . . . . . . . . . . . . . . 55 7.4 CARID Property . . . . . . . . . . . . . . . . . . . . . 56 7.5 CSID Property . . . . . . . . . . . . . . . . . . . . . 56 7.6 DECREED Property . . . . . . . . . . . . . . . . . . . . 57 7.7 DEFAULT-CHARSET Property . . . . . . . . . . . . . . . . 58 7.8 DEFAULT-LOCALE Property . . . . . . . . . . . . . . . . 58 7.9 DEFAULT-TZID Property . . . . . . . . . . . . . . . . . 59 7.10 DEFAULT-VCARS Property . . . . . . . . . . . . . . . . . 60 7.11 DENY Property . . . . . . . . . . . . . . . . . . . . . 61 7.12 EXPAND property . . . . . . . . . . . . . . . . . . . . 62 7.13 GRANT Property . . . . . . . . . . . . . . . . . . . . . 62 7.14 MAXDATE Property . . . . . . . . . . . . . . . . . . . . 63 7.15 MINDATE Property . . . . . . . . . . . . . . . . . . . . 64 7.16 NAME Property . . . . . . . . . . . . . . . . . . . . . 64 7.17 OWNER Property . . . . . . . . . . . . . . . . . . . . . 65 7.18 PERMISSION Property . . . . . . . . . . . . . . . . . . 66 7.19 QUERY property . . . . . . . . . . . . . . . . . . . . . 67 7.20 QUERYID property . . . . . . . . . . . . . . . . . . . . 67 7.21 REQUEST-STATUS property . . . . . . . . . . . . . . . . 68 7.22 RESTRICTION Property . . . . . . . . . . . . . . . . . . 69 7.23 SCOPE Property . . . . . . . . . . . . . . . . . . . . . 70 7.24 TARGET Property . . . . . . . . . . . . . . . . . . . . 71 7.25 TRANSP Property . . . . . . . . . . . . . . . . . . . . 71 8. New Components . . . . . . . . . . . . . . . . . . . . . 73 8.1 VAGENDA Component . . . . . . . . . . . . . . . . . . . 73 8.2 VCALSTORE Component . . . . . . . . . . . . . . . . . . 75 8.3 VCAR Component . . . . . . . . . . . . . . . . . . . . . 78 8.4 VRIGHT Component . . . . . . . . . . . . . . . . . . . . 81 8.5 VREPLY Component . . . . . . . . . . . . . . . . . . . . 82 Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 3] Internet-Draft Calendar Access Protocol (CAP) June 2002 8.6 VQUERY Component . . . . . . . . . . . . . . . . . . . . 82 9. Commands and Responses . . . . . . . . . . . . . . . . . 84 9.1 CAP Commands (CMD) . . . . . . . . . . . . . . . . . . . 84 9.1.1 Bounded Latency . . . . . . . . . . . . . . . . . . . . 85 9.1.2 ABORT Command . . . . . . . . . . . . . . . . . . . . . 88 9.1.3 CONTINUE Command . . . . . . . . . . . . . . . . . . . . 88 9.1.4 CREATE Command . . . . . . . . . . . . . . . . . . . . . 90 9.1.5 DELETE Command . . . . . . . . . . . . . . . . . . . . . 96 9.2 GENERATE-UID Command . . . . . . . . . . . . . . . . . . 99 9.3 GET-CAPABILITY Command . . . . . . . . . . . . . . . . . 101 9.4 IDENTIFY Command . . . . . . . . . . . . . . . . . . . . 105 9.5 MODIFY Command . . . . . . . . . . . . . . . . . . . . . 107 9.6 MOVE Command . . . . . . . . . . . . . . . . . . . . . . 112 9.7 REPLY Response to a Command . . . . . . . . . . . . . . 115 9.8 SEARCH Command . . . . . . . . . . . . . . . . . . . . . 116 9.9 SET-LOCALE Command . . . . . . . . . . . . . . . . . . . 119 9.10 TIMEOUT Command . . . . . . . . . . . . . . . . . . . . 121 9.11 Response Codes . . . . . . . . . . . . . . . . . . . . . 121 10. Object Registration . . . . . . . . . . . . . . . . . . 124 10.1 Registration of New and Modified Entities . . . . . . . 124 10.2 Post the item definition . . . . . . . . . . . . . . . . 124 10.3 Allow a comment period . . . . . . . . . . . . . . . . . 124 10.4 Release a new RFC . . . . . . . . . . . . . . . . . . . 124 11. BEEP and CAP . . . . . . . . . . . . . . . . . . . . . . 125 11.1 BEEP Profile Registration . . . . . . . . . . . . . . . 125 11.2 BEEP Exchange Styles . . . . . . . . . . . . . . . . . . 125 12. IANA Considerations . . . . . . . . . . . . . . . . . . 126 13. Security Considerations . . . . . . . . . . . . . . . . 127 Authors' Addresses . . . . . . . . . . . . . . . . . . . 128 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . 130 B. Bibliography . . . . . . . . . . . . . . . . . . . . . . 131 Full Copyright Statement . . . . . . . . . . . . . . . . 133 Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 4] Internet-Draft Calendar Access Protocol (CAP) June 2002 1. Introduction This document specifies how a Calendar CUA interacts with a CS to manage calendar information. In particular, it specifies how to query, create, modify, and delete iCalendar components (e.g., events, to-dos, or daily journal entries). It further specifies how to search for available busy time information. Synchronization with CUAs is not covered. CAP is specified as a BEEP "profile". As such, many aspects of the protocol (e.g., authentication and privacy) are provided within [BEEP]. The protocol data units leverage the standard iCalendar format [iCAL] to convey calendar related information. CAP can also be used to store and fetch [iTIP] objects and when those objects are used in this memo, they mean exactly the same as defined in [iTIP]. When iCalendar objects are transfered between the calendar user agent and a calendar server, some additional properties and parameters may be added and the calendar user agent is responsible for correctly generating iCalendar objects to non CAP processes. The definition of new components, properties, parameter's, and value types are broken into two parts. The first part summarizes and defined the new objects. The second part provides the detail and any ABNF for those objects. 1.1 Formatting Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. Calendaring and scheduling roles are referred to in quoted-strings of text with the first character of each word in upper case. For example, "Organizer" refers to a role of a "Calendar User" (CU) within the protocol defined by [iTIP]. Calendar components defined by [iCAL] are referred to with capitalized, quoted-strings of text. All iCalendar components should start with the letter "V". For example, "VEVENT" refers to the event calendar component, "VTODO" refers to the to-do component and "VJOURNAL" refers to the daily journal component. Scheduling methods defined by [iTIP], are referred to with capitalized, quoted-strings of text. For example, "REPLY" refers to the method for replying to a "REQUEST". CAP commands are referred to by upper-case, quoted-strings of text, Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 5] Internet-Draft Calendar Access Protocol (CAP) June 2002 followed by the word "command". For example, "CREATE" command refers to the command for creating a calendar entry, "SEARCH" command refers to the command for reading calendar components. CAP Commands are named using the "CMD" property. Properties defined by this memo are referred to with capitalized, quoted-strings of text, followed by the word "property". For example, "ATTENDEE" property refers to the iCalendar property used to convey the calendar address that has been invited to a "VEVENT" or "VTODO" component. Property parameters defined by this memo are referred to with capitalized, quoted-strings of text, followed by the word "parameter". For example, "PARTSTAT" parameter refers to the iCalendar property parameter used to specify the participation status of an attendee. Enumerated values defined by this memo are referred to with capitalized text, either alone or followed by the word "value". In tables, the quoted-string text is specified without quotes in order to minimize the table length. 1.2 Related Documents Implementers will need to be familiar with several other memos that, along with this one, describe the Internet calendaring and scheduling standards. These documents are: [iCAL] - (RFC2445) Which specifies the objects, data types, properties and property parameters used in the protocols, along with the methods for representing and encoding them. [iTIP] - (RFC2446) Which specifies an interoperability protocol for scheduling between different installations. [iMIP] - (RFC2447) Which specifies the Internet email binding for [iTIP]. [GUIDE] - (draft/rfc...), 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. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 6] Internet-Draft Calendar Access Protocol (CAP) June 2002 1.3 Definitions BOOKED - An entry in the calendar store has one of three conceptual states. It is "UNPROCESSED", "BOOKED" or marked as "DELETED". How the implementation stores the state of any object is not a protocol issues and is not discussed. An object can be said to be booked, unprocessed, or marked for delete. 1. A "UNPROCESSED" scheduling entry has been stored in the calendar store but has not been acted on by a Calendar User (CU) or Calendar User Agent (CUA). All scheduled entries are [iTIP] objects. All [iTIP] objects in the store are not booked. To retrieve any [iTIP] object, simply do a query asking for any objects that were stored with its state set to "UNPROCESSED". 2. A booked entry is stored with the CREATE command. It is an entry that has been acted on by a CU or CUA and there has been a decision to store an object. To retrieve any booked object, simply do a query asking for any objects that were stored with its state set to "BOOKED". 3. A marked for delete component has its state set to DELETE. To retrieve any deleted object, simply do a query asking for any objects that were stored with its state set to "DELETED". By default objects marked for delete are not returned. The CUA must specifically ask for marked for delete objects. Calendar - A collection of logically related objects or entities each of which may be associated with a calendar date and possibly time of day. These entities can include calendar properties or components. In addition, a calendar might be related to other calendars with the "RELATED-TO" property. A calendar is identified by its unique calendar identifier. The [iCAL] defines the initial calendar properties, calendar components and properties that make up the contents of a calendar. Calendar Access Protocol (CAP) - The standard Internet protocol that permits a CUA to access and manipulate calendars residing on a Calendar Store. (this memo) Calendar Access Rights (VCAR) - The mechanism for specifying the CAP operations ("PERMISSION") that a particular calendar user ("UPN") is granted or denied permission to perform on a given calendar object ("SCOPE"). The calendar access rights are specified with the "VCAR" calendar components within a CS and calendar. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 7] Internet-Draft Calendar Access Protocol (CAP) June 2002 Calendar Address - Also See Calendar URL - they are one in the same for CAP addresses. The calendar address can also be the value to the "ATTENDEE" and "ORGANIZER" properties as defined in [iCAL]. Calendar URL - A calendar URL is a URL defined in this memo that specifies the address of a CS or Calendar. Component- Any object that conforms to the iCalendar object format and that is either defined in an internet draft, registered with IANA, or is an experimental object that is prefixed with "x-". Some types of components include calendars, events, to-dos, journals, alarms, and time zones. A component consists of properties and possibly other contained components. For example, an event may contain an alarm component. Properties - An attribute of a particular component. Some properties are applicable to different types of components. For example, the "DTSTART" property is applicable to "VEVENT", "VTODO", "VJOURNAL" components. Other components are applicable only to an individual type of calendar component. For example, the "TZURL" property may only applicable to "VTIMEZONE" components. Calendar Identifier (CalID) - A globally unique identifier associated with a calendar. Calendars reside within a CS. See Qualified Calendar Identifier and Relative Calendar Identifier. All CalIDs start with "cap:". Calendar Policy - A CAP operational restriction on the access or manipulation of a calendar. These may be outside of the scope of the CAP protocol. An example of an implementation or site policy is, "events MUST BE scheduled in unit intervals of one hour". Calendar Property - An attribute of a calendar ("VAGENDA"). The attribute applies to the calendar, as a whole. For example, the "CALSCALE" property specifies the calendar scale (e.g., the "GREGORIAN" value) for the whole calendar. Calendar Server - An implementation of a Calendar Store that manages one or more calendars. Calendar Store (CS) - The data and service model definition for a Calendar Store as defined in this memo. This memo does not specify how the CS is implemented. Calendar 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 Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 8] Internet-Draft Calendar Access Protocol (CAP) June 2002 defined by [RFC1738]. The CSID excludes any reference to a specific calendar. Calendar Store Components - Components maintained in a CS specify a grouping of calendar store-wide information. Calendar Store Properties - Properties maintained in a Calendar Store calendar store-wide information. Calendar User (CU) - An entity (often biological) that uses a calendaring system. Calendar User Agent (CUA) - The client application that a CU utilizes to access and manipulate a calendar. CAP Session - An open communication channel between a CUA and a Calendar Server. If the CAP session is authenticated, the the CU is "authenticated" and it is an "authenticated CAP session". Contained Component / Contained Properties - A component or property that is contained inside of another component. A "VALARM" component for example may be contained inside of a "VEVENT" component. And a "TRIGGER" property could be a contained property of a "VALARM" component. Delegate - A calendar user (sometimes called the delegatee) who has been assigned participation in a scheduled component (e.g., VEVENT) by one of the attendees in the scheduled component (sometimes called the delegator). An example of a delegate is a team member told to go to a particular meeting in place of another Attendee who is unable to attend. Designate - A calendar user who is authorized to act on behalf of another calendar user. An example of a designate is an assistant. Experiential - The CUA and CS may implement experimental extensions to the protocol. They also might have experimental components, properties, and parameters. These extensions MUST start with "x-" (or "X-") and should include a vendor prefix (such as "x-myvendor- "). There is no guarantee that these experimental extensions will interoperate with other implementations. There is no guarantee that they will not interact in unpredictable ways with other vendor experimental extensions. Implementations should limit sending those extensions to other implementations. Object - A generic name for any component, property, parameter, or value type to be used in iCalendar. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 9] Internet-Draft Calendar Access Protocol (CAP) June 2002 Overlapped Booking - A policy which indicates whether or not components with a "TRANSP" property not set to "TRANSPARENT- NOCONFLICT" or "OPAQUE-NOCONFLICT" value can overlap one another. When the policy is applied to a calendar it indicates whether or not the time span of any component (VEVENT, VTODO, ...) in the calendar can overlap the time span of any other component in the same calendar. When applied to an individual entry, it indicates whether or not any other component's time span can overlap that individual component. If the CS does not allow overlapped booking, then the CS is unwilling to allow any overlapped bookings within any calendar in the CS. Owner - One or more CUs or UGs that are listed in the "OWNER" property in a calendar. There can be more than one owner. The " Qualified Calendar Identifier (Qualified CalID) - A CalID in which both the scheme and csid of the CAP URI are present. Realm - A collection of calendar user accounts, identified by a string. The name of the Realm is only used in UPNs. In order to avoid namespace conflict, the Realm SHOULD be postfixed with an appropriate DNS domain name. (e.g., the foobar Realm could be called foobar.example.com). Relative Calendar Identifier (Relative CalID) - An identifier for an individual calendar in a calendar store. It MUST BE unique within a calendar store. A Relative CalID consists of the "URL path" of the "Common Internet Scheme Syntax" portion of a URL, as defined by [RFC396] and [RFC2718]. Session Identity - A UPN associated with a CAP session. A session gains an identity after successful authentication. The identity is used in combination with VCAR to determine access to data in the CS. User Group (UG) - A collection of Calendar Users and/or User Groups. These groups are expanded by the CS and may reside either locally or in an external database or directory. The group membership may be fixed or dynamic over time. Username - A name which denotes a Calendar User within a Realm. This is part of a UPN. User Principal Name (UPN) - A unique identifier that denotes a CU or a group of CU. A UPN is a RFC 822 compliant email address, with exceptions listed below, and in most cases it is deliverable to the CU. In some cases it is identical to the CU's well known email address. A CU's UPN MUST never be an e-mail address that is Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 10] Internet-Draft Calendar Access Protocol (CAP) June 2002 deliverable to a different person as there is no requirement that a person's UPN MUST BE their e-mail address. A UPN is formatted as a user name followed by "@" followed by a Realm in the form of a valid, and unique, DNS domain name. The user name MUST BE unique within the Realm. In it's simplest form it looks like "user@example.com". In certain cases a UPN will not be RFC 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". Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 11] Internet-Draft Calendar Access Protocol (CAP) June 2002 2. Additions to iCalendar Several new components, properties, parameters, and value types are added in CAP. This section summarizes those new objects. This memo extends the properties that can go into 'calprops' as defined in [iCAL] section 4.6 page 51 to allow iTIP objects transmitted between a CAP aware CUA and the CS to contain the "TARGET" and "CMD" properties. This memo does not address how a CUA transmits iTIP or iMIP objects to non CAP programs. calprops = 2*( ; 'prodid' and 'version' are both REQUIRED, ; but MUST NOT occur more than once. ; prodid /version / ; These are optional, but MUST NOT occur ; more than once. ; calscale / method / target / iana-prop / cmd / ; These are optional, and may occur more ; than once. ; x-prop In addition a problem exists with the control of "VALARM" components and their "TRIGGER" properties. A CU may wish to set their own alarm (local alarms) on components. These local alarms are not to be forwarded to other CUs, CUAs, or CSs as are the "SEQUENCE" property and the "ENABLE" parameter. So for the protocol between a CUA and a CS, the following changes apply to the CAP protocol from [iCAL] section "4.6.6" page 67: Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 12] Internet-Draft Calendar Access Protocol (CAP) June 2002 alarmc = "BEGIN" ":" "VALARM" CRLF alarm-seq iana-prop (audioprop / dispprop / emailprop / procprop) "END" ":" "VALARM" CRLF alarm-seq = "SEQUENCE" alarmseqparam ":" integer CRLF alarmseqparam = *( ";" xparam) / ";" local-param The CUA adds a "SEQUENCE" property to each "VALARM" component as it books the component. This property along with the "LOCAL" and "ENABLE" parameters allow the CUA to uniquely identify any VALARM in any component. The CUA should remove those before forwarding to non CAP aware CUAs (including iMIP CUAs). In addition, if a CUA wished to ignore a "TRIGGER" property in a "VALARM" that was supplied to it by the ORGANIZER, the CUA needs a common way to tag that trigger as disabled. So for the protocol between a CUA and a CS, the following is a modification to [iCAL] section "4.8.6.3" page 127: trigger = "TRIGGER" 1*(";" enable-param) (trigrel / trigabs) Section 6.2.1 and Section 6.2.2. These additions will be transmitted between a CS and a CAP aware CUA. So the VERSION value will remain at "2.0" as no existing iTIP or iMIP implementation will be effected. 2.1 New Value Types (summary) UPN The UPN value type is text value type restricted to only UPN values. (Section 6.1.2) UPN-FILTER Like the UPN value type, but also includes filter rules that allow wildcards. (Section 6.1.3) CALQUERY The "CAL-QUERY" (Section 6.1.1) value type is a query syntax that is used by the CUA to specify the rules that apply to a CAP command. In the case of "SEARCH", the query language is used to fetch objects from the CS. When used with "DELETE", the selected objects are deleted from the CS. "CAL-QUERY" can also be used with "MOVE" and "MODIFY". Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 13] Internet-Draft Calendar Access Protocol (CAP) June 2002 2.1.1 New Parameters (summary) ENABLE - The "ENABLE" parameter in CAP is used to tag a "TRIGGER" property in a component as disabled or enabled. This is used when a scheduling request arrives and the CU wishes to ignore the trigger time included. (Section 6.2.1). Formal Definition: The "ENABLE" parameter is defined by the following notation: enable-param = "ENABLE" "=" ("TRUE" / "FALSE") LOCAL - The "LOCAL" parameter in CAP is used to tag a "SEQUENCE" property in a "VALARM" to signify that a VALARM is local or to be distributed. (Section 6.2.2). For example, when inviting others to an event, the ORGANIZERs booked VEVENT might contain VALARMs, and those VALARMS might be 'alarm be 5 minutes before the meeting'. However other ATTENDEEs, may have to set their own VALARMs for the same event (assuming they reply that they will be attending). So, by tagging the VALARM as local the CUA MUST never forward those local VALARMs to other CS's or CUAs. The CUA can not simply delete any VALARMs from components where the CU is not the ORGANIZER. If it did, any [iTIP] "COUNTER" would result in the ORGANIZER thinking that the ATTENDEE wished to also counter with removing those VALARMs. And in addition, any update to an existing component would re-create those VALARMs in the ATTENDEEs CS. Formal Definition: The "LOCAL" parameter is defined by the following notation: local-param = "LOCAL" "=" ("TRUE" / "FALSE") Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 14] Internet-Draft Calendar Access Protocol (CAP) June 2002 2.1.2 New Properties (summary) ALLOW-CONFLICT - Some entries in a calendar might not be valid if other entries were to allowed to overlap the same time span. Renting a car for example. It would not make sense to allow two reservations for the same car at the same time. The "ALLOW- CONFLICT" property takes a boolean value. If FALSE, then conflicts are not allowed. (Section 7.1) CSID - Each CS needs its own unique identifier. The "CSID" property is the official unique identifier for the CS. If the BEEP 'serverName' attribute was suppled in the BEEP 'start' message, then the CSID will be mapped to the virtual host name supplied and the host name part of the CSID MUST BE the same as the 'serverName' value. This allows one CS implementation to service multiple virtual hosts. CS's are not required to support virtual hosting. If a CS does not support virtual hosting then it must ignore the BEEP 'serverName'. (Section 7.5) CALID - Each calendar within a CS needs to be uniquely identifiable. The "CALID" property identifies a unique calendar within a CS. It can be a full CALID or a relative CALID. (Section 7.2) CALMASTER - The "CALMASTER" property specifies the contact information for the CS. (Section 7.3) CARID - Access rights can be saved and fetched by unique ID - the "CARID". (Section 7.4) CMD - The enumerated list of CAP commands and the options for those commands, as well as replies are transmitted using the "CMD" property. (Section 9.1) DECREED - Some access rights are not changeable by the CUA. When that is the case, the "DECREED" property value in the "VCAR" will be TRUE. (Section 7.6) DEFAULT-CHARSET - The list of charsets supported by the CS. The first entry MUST BE the default for the CS. (Section 7.7) DEFAULT-LOCALE - The list of locales supported by the CS. The first entry in the list is the default locale. (Section 7.8) DEFAULT-TZID - This is the list of known timezones supported. The first entry is the default. (Section 7.9) DEFAULT-VCARS - A list of the CARIDs that will be used to create new calendars. (Section 7.10) Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 15] Internet-Draft Calendar Access Protocol (CAP) June 2002 DENY - The UPNs listed in the "DENY" property of a "VCAR" will denied access as described in the "VRIGHT" component. (Section 7.11) EXPAND - This property tells the CS if the query reply should expand components into multiple instances. The default is FALSE. (Section 7.12) GRANT - The UPNs listed in the "GRANT" property of a "VCAR" will allowed access as described in the "VRIGHT" component. (Section 7.13) MAXDATE - The maximum date supported by the CS. (Section 7.14) MINDATE - The minimum date supported by the CS. (Section 7.15) NAME - Several storeable components such as "VCAR" and "VQUERY" may have the "NAME" property contained in them to describe in a various locals the purpose of the component. Components may have multiple "NAME" properties. (Section 7.16) OWNER - Each calendar has at least one "OWNER". (xref target="OWNER"/>) Related to the "OWNER()" (Section 6.1.3) query clause. PERMISSION - This property specifies the permission being granted or denied. Examples are "READ" and "MODIFY". (Section 7.18) QUERY - Use to hold the CAL-QUERY (Section 7.19) for the component. QUERYID - A unique id for a stored query. (Section 7.20) REQUEST-STATUS - The [iCAL] "REQUEST-STATUS" property is extended to include new error numbers. (Section 7.21) RESTRICTION - In the final check when granting calendar access requests, the CS test the results to the value of the "RESTRICTION" property in the corresponding "VRIGHT" component to determine if the access meets that restriction. (Section 7.22) SCOPE - The "SCOPE" property is used in "VRIGHT"s component to select the subset of data that may be acted upon when checking access rights. (Section 7.23) TARGET - The new VCALENDAR property "TARGET" (Section 7.24) used to specify which calendar(s) will be the subject of the CAP command. TRANSP - This is a modification the the [iCAL] TRANSP property and Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 16] Internet-Draft Calendar Access Protocol (CAP) June 2002 it allows more values. (Section 7.25) 2.1.3 New Components (summary) VAGENDA - CAP allows the fetching and storing of the entire contents of a calendar. The "VCALENDAR" object is not sufficient to encapsulate all of the needed data that describes a calendar. The VAGENDA object is the encapsulating object for an entire calendar. (Section 8.1) VCALSTORE - Each CS contains one or more calendars (VAGENDAs), the VCALSTORE object is the encapsulating object that can hold all of the "VAGENDA"s along with any components and properties that are unique to the store level. (Section 8.2) VCAR - Calendar Access Rights are specified and encapsulated in the new iCalendar "VCAR" (Section 8.3) component. The "VCAR" component holds some new properties and at least one "VRIGHT" component. VRIGHT - (Section 8.4) This component encapsulates a set of instructions to the CS that define the rights or restrictions needed. VREPLY - (Section 8.5) This component encapsulates a set of data that can consist of an arbitrary amounts of properties and components. Its contents is dependent on the command that was issued. VQUERY - The search operation makes use of a new component, called "VQUERY" (Section 8.6) and a new value type "CAL-QUERY" (Section 6.1.1). "VQUERY" is used to fetch objects from the CS. 2.2 Relationship of RFC-2446 (ITIP) and CAP [iTIP] describes scheduling methods which result in indirect manipulation of components. In CAP, the "CREATE" command is used to deposit entities into the store. Other CAP commands such as "DELETE", "MODIFY" and "MOVE" provide direct manipulation of components. In the CAP calendar store model, scheduling messages are conceptually kept separate from other components by their state. All scheduling operations and are as define in [iTIP]. This memo makes no changes to any of the workflow described in [iTIP]. In this memo when referring to the presence of the "METHOD" property in an object is the same as saying an [iTIP] object. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 17] Internet-Draft Calendar Access Protocol (CAP) June 2002 A CUA may create a "BOOKED" entry by depositing a iCalendar object into the store. This is done by depositing an object that does not have a "METHOD" property. The CS then knows to set the state of the object to "BOOKED". If the object has a "METHOD" property then the object is stored in the "UNPROCESSED" state. If existing "UNPROCESSED" objects exist in the CS for the same UID then a CUA may wish to consolidate the objects in to one "BOOKED" object. The CUA would fetch the "UNPROCESSED" objects for that UID and process them in the CUA as described in [iTIP]. Then if the CUA wished to book the UID, then the CUA would issue a "CREATE" command to create the new "BOOKED" object in the CS, followed by a "DELETE" command to remove any related old [iTIP] objects from the CS. And it might also involve having the CUA send some [iMIP] objects or contacting other CS's and performing CAP operations on those CSs. The CUA could also decide not to book the object. In which case the "UNPROCESSED" objects could be deleted from the CS. Or the CUA could set those object to the marked for delete. The marked for delete state is used to keep the object around so that the CUA can process duplicate requests automatically. If a duplicate [iTIP] object is deposited into the CS and there exists identical marked for delete objects, then a CUA acting on behalf of the "OWNER" can silently drop those duplicate entries. Another purpose for the marked for delete state is so that when a CU decides they do not wish to have the object show in their calendar, the CUA can book the object, changing the PARTSTAT parameter to "DECLINED" in the "ATTENDEE" property that corresponds to their UPN. Perform an iTIP processing such as sending back a decline. Then mark that object as marked for delete. Their CUA might be configurable to automatically drop any updates for that object knowing the CU has already declined. When synchronizing with multiple CUAs, the marked for delete state could be used to inform the synchronization process that an object is to be deleted. How synchronization is done is not specified in this memo. Several "UNPROCESSED" entries can be in the CS for the same UID. However once consolidated, then only one entry exists in the CS and that is the booked object. The others MUST BE removed, or have their state changed to "DELETED". There MUST NOT BE more than one "BOOKED" entry in a calendar for the same "UID". Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 18] Internet-Draft Calendar Access Protocol (CAP) June 2002 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 from the consolidated results. Finally, the CUA could do a "DELETE" or change their state to "DELETED" for all of these now old scheduling requests in the CS. See [iTIP] for details on resolving multiple [iTIP] scheduling entries. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 19] Internet-Draft Calendar Access Protocol (CAP) June 2002 3. CAP Design 3.1 System Model The system model describes the high level components of a calendar system and how they interact with each other. CAP is used by a "Calendar User Agent" (CUA) to send commands to and receive responses from a "Calendar Server" (CS). The CUA prepares a [MIME] encapsulated command, sends it to the CS, and receives a [MIME] encapsulated response. The calendaring related information within these messages are represented by iCalendar objects. There are two distinct protocols in operation to accomplish this exchange. [BEEP] is the transport protocol is used to move these encapsulations between a CUA and a CS. CAP's [BEEP] profile defines the application protocol where the content and semantics of the messages sent between the CUA and the CS are specified. 3.2 Calendar Store Object Model [iCAL] describes components such as events, todos, alarms, and timezones. [CAP] requires additional object infrastructure. In particular, detailed definitions of the containers for events and todos (calendars), access control objects, and a query language. The conceptual model for a calendar store is shown below. The calendar store (VCALSTORE - Section 8.2) contains "VCAR"s, "VQUERY"s, "VTIMEZONE"s, "VAGENDA"s and calendar store properties. Calendars (VAGENDAs) contain "VEVENT"s, "VTODO"s, "VJOURNAL"s, "VCAR"s, "VTIMEZONE"s, "VFREEBUSY", "VQUERY"s and calendar properties. The component "VCALSTORE" is used to denote the a root of the calendar store and contains all of the calendars. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 20] Internet-Draft Calendar Access Protocol (CAP) June 2002 Calendar Store VCALSTORE | +-- properties +-- VCARs +-- VQUERYs +-- VTIMEZONEs +-- VAGENDAs | | | +--properties | +--VEVENTs | | | | | +--VALARMs | +--VTODOs | | | | | +--VALARMs | +--VJOURNALs | +--VCARs | +--VTIMEZONEs | +--VQUERYs | +--VFREEBUSY | | | | ... . . +-- VAGENDAs . . . . . . Calendars within a Calendar Store are identified by their unique Relative CALID. 3.3 Protocol Model CAP uses beep as the transport and authentication protocol. The initial charset MUST BE UTF-8 for the session in an unknown locale. If the CS supplied the BEEP 'localize' attribute in the BEEP 'greeting' then the CUA may tell the CS to switch locales for the session by issuing the "SET-LOCALE" CAP command and supplying one of the locales supplied by the BEEP 'localize' attribute. If supplied the first locale supplied in the BEEP 'localize' attribute MUST BE the default locale of the CS. The locale is switched only after a successful reply. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 21] Internet-Draft Calendar Access Protocol (CAP) June 2002 The "DEFAULT-CHARSET" property of the CS contains the list of charsets supported by the CS with the first value being the default for new calendars. If the CUA wishes to switch to one of those charsets for the session, the CUA issues the "SET-LOCALE" CAP command. The CUA would have to first perform a "GET-CAPABILITY" command on the CS to get the list of charsets supported by the CS. The charset is switched only after a successful reply. The CUA may switch locales and charsets as needed. There is no requirement that a CS support multiple locales or charsets. 3.3.1 Use of BEEP, MIME and iCalendar CAP uses the BEEP application protocol over TCP. (refer to [BEEP] and [BEEPTCP] for more information). The default port that the Calendar Server listens for connections is on user port 1026. The BEEP data exchanged in CAP is a iCalendar MIME content that fully conforms to [iCAL] iCalendar format. This example tells the CS to generate and return 10 UIDs to be used by the CUA. (Note throughout this memo, 'C:' refers to what the CUA sends, 'S:' refers to what the CS sends, 'I:' refers to what the initiator sends, and 'L:' refers to what the listener sends. Where initiator and responder are used as defined in [BEEP].) C: MSG 1 2 . 432 62 C: Content-Type: text/calendar C: C: BEGIN:VCALENDAR C: VERSION:2.0 C: PRODID:-//someone's prodid C: CMD;ID=unique-per-cua-123;OPTIONS=10:GENERATE-UID C: END:VCALENDAR C: END NOTE: The following examples will not include the BEEP header and footer information. Only the iCalendar objects that are sent between the CUA and CS will be shown as the BEEP payload boundaries are independent of CAP. The commands listed below are used to manipulate or access the data on the calendar store: ABORT - Sent to halt the processing of any command except ABORT. (Section 9.1.2) Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 22] Internet-Draft Calendar Access Protocol (CAP) June 2002 CONTINUE - Sent to continue processing a command that has had its specified timeout time reached. (Section 9.1.3) CREATE - Create a new object on the CS. This can be implied for iTIP objects. Initiated by the CUA only. (Section 9.1.4) SET-LOCALE - Tell the CS to use any named locale and charset supplied. Initiated by the CUA only. (Section 9.9) DELETE - Delete objects from the CS. Initiated by the CUA only. Can also be used to mark a object for deletion. (Section 9.1.5) GENERATE-UID - Generate one or more unique ids. Initiated by the CUA only. (Section 9.2) GET-CAPABILITY - Query the capabilities the other end point of the session. (Section 9.3) IDENTIFY - Set a new identity for the session. Initiated by the CUA only. (Section 9.4) MODIFY - Modify components. Initiated by the CUA only. (Section 9.5) MOVE - Move components to another container. Initiated by the CUA only. (Section 9.6) REPLY - When replying to a command, the "CMD" value will be set to "REPLY" so that it will not be confused with a new command. (Section 9.7) SEARCH - Search for components. Initiated by the CUA only. (Section 9.8) TIMEOUT - Sent when a specified amount of time has lapsed and a command has not finished. (Section 9.10) Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 23] Internet-Draft Calendar Access Protocol (CAP) June 2002 4. Security Model The BEEP transport performs all session authentication. 4.1 Calendar User and UPNs A Calendar User (CU) is an entity that can be authenticated. It is represented in CAP as a UPN, which is a key part of access rights. The UPN representation is independent of the authentication mechanism used during a particular CUA/CS interaction. This is because UPNs are used within VCARs. If the UPN were dependent on the authentication mechanism, a VCAR could not be consistently evaluated. A CU may use one mechanism while using one CUA but the same CU may use a different authentication mechanism when using a different CUA, or while connecting from a different location. The user may also have multiple UPNs for various purposes. Note that the immutability of the user's UPN may be achieved by using SASL's authorization identity feature. (The transmitted authorization identity may be different than the identity in the client's authentication credentials.) [SASL, section 3]. This also permits a CU to authenticate using their own credentials, yet request the access privileges of the identity for which they are proxying SASL. Also, the form of authentication identity supplied by a service like TLS may not correspond to the UPNs used to express a server's access rights, requiring a server specific mapping to be done. The method by which a server determines a UPN, based on the authentication credentials supplied by a client, is implementation specific. See [BEEP] for authentication details; [BEEP] relies on SASL. 4.1.1 UPNs and Certificates When using X.509 certificates for purposes of CAP authentication, the UPN should appear in the certificate. Unfortunately there is no single correct guideline for which field should contain the UPN. From RFC-2459, section 4.1.2.6 (Subject): If subject naming information is present only in the subjectAlt- Name extension (e.g., a key bound only to an email address or URI), then the subject name MUST be an empty sequence and the subjectAltName extension MUST BE critical. Implementations of this specification MAY use these comparison rules to process unfamiliar attribute types (i.e., for name chaining). This allows implementations to process certificates Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 24] Internet-Draft Calendar Access Protocol (CAP) June 2002 with unfamiliar attributes in the subject name. In addition, legacy implementations exist where an RFC 822 name is embedded in the subject distinguished name as an EmailAddress attribute. The attribute value for EmailAddress is of type IA5String to permit inclusion of the character '@', which is not part of the PrintableString character set. EmailAddress attribute values are not case sensitive (e.g., "fanfeedback@redsox.com" is the same as "FANFEEDBACK@REDSOX.COM"). Conforming implementations generating new certificates with electronic mail addresses MUST use the rfc822Name in the subject alternative name field (see sec. 4.2.1.7 of [RFC 2459]) to describe such identities. Simultaneous inclusion of the EmailAddress attribute in the subject distinguished name to support legacy implementations is deprecated but permitted. Since no single method of including the UPN in the certificate will work in all cases, CAP implementations MUST support the ability to configure what the mapping will be by the CS administrator. Implementations MAY support multiple mapping definitions, for example, the UPN may be found in either the subject alternative name field, or the UPN may be embedded in the subject distinguished name as an EmailAddress attribute. Note: If a CS or CUA is validating data received via iMIP, if the "ORGANIZER" or "ATTENDEE" property said (e.g.) "ATTENDEE;CN=Joe Random User:MAILTO:juser@example.com" then the email address should be checked against the UPN. This is so the "ATTENDEE" property cannot be changed to something misleading like "ATTENDEE;CN=Joe Rictus User:MAILTO:jrictus@example.com" and have it pass validation. Note that it is the email addresses that miscompare, the CN miscompare is irrelevant. 4.1.2 Anonymous Users and Authentication Anonymous access is often desirable. For example an organization may publish calendar information that does not require any access control for viewing or login. Conversely, a user may wish to view unrestricted calendar information without revealing their identity. 4.1.3 User Groups A User Group is used to represent a collection of CUs or other UGs that can be referenced in VCARs. A UG is represented in CAP as a UPN. The CUA cannot distinguish between a UPN that represents a CU or a UG. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 25] Internet-Draft Calendar Access Protocol (CAP) June 2002 UGs are expanded as necessary by the CS. The CS MAY expand a UG (including nested UGs) to obtain a list of unique CUs. Duplicate UPNs are filtered during expansion. How the UG expansion is maintained across commands is implementation specific. A UG may reference a static list of members, or it may represent a dynamic list. Operations SHOULD recognize changes to UG membership. CAP does not define commands or methods for managing UGs. 4.2 Access Rights Access rights are used to grant or deny access to calendars, components, properties, and parameters in a CS to a CU. CAP defines a new component type called a Calendar Access Right (VCAR). Specifically, a "VCAR" component grants, or denies, UPNs the right to 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 object associated with a particular VCAR might be created before or after the actual VCAR is defined. In addition, the VCAR and VEVENT definition might be created in the same iCalendar object and passed together in a single object. All rights MUST BE denied unless specifically granted. If two rights specified in VCAR components are in conflict, the right that denies access always takes precedence over the right that grants access. Any attempt to create a VCAR that conflicts with an immutable VCAR must fail. 4.2.1 Access Control and NOCONFLICT The TRANSP property can take on values "TRANSPARENT-NOCONFLICT" and "OPAQUE-NOCONFLICT" that prohibit other components from overlapping it. This setting overrides access. The "ALLOW-CONFLICT" CS, Calendar or component setting may also prevent overlap, returning an error code "6.3". 4.2.2 Calendar Access Right (VCAR) Access rights within CAP are specified with the "VCAR" component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID" properties. Properties within an iCalendar object are unordered. This also is Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 26] Internet-Draft Calendar Access Protocol (CAP) June 2002 the case for the "VCAR" properties. 4.2.3 Predefined VCARs Predefined calendar access CARIDs that MUST BE implemented are: CARID:READBUSYTIMEINFO - Specifies the "GRANT" and "DENY" rules that allow UPNs to read "VFREEBUSY" components. An example definition for this VCAR is: BEGIN:VCAR CARID:READBUSYTIMEINFO BEGIN:VRIGHT GRANT:* PERMISSION:READ SCOPE:SELECT * FROM VFREEBUSY END:VRIGHT END:VCAR CARID:REQUESTONLY - Specifies the "GRANT" and "DENY" rules to UPNs other than the owner of the calendar the ability to write new objects with the property "METHOD" property set to the "REQUEST" value. This CARID allows the owner to specify which UPNs are allowed to make scheduling requests. An example definition for this VCAR is: BEGIN:VCAR CARID:REQUESTONLY BEGIN:VRIGHT GRANT:NON OWNER() PERMISSION:CREATE RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST' END:VRIGHT END:VCAR CARID:UPDATEPARTSTATUS - Grants to authenticated users the right to modify the instances of the "ATTENDEE" property set to one of their calendar addresses in any components for any booked component containing a "ATTENDEE" property. This allows (or denies) a CU the ability to update their own participation status Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 27] Internet-Draft Calendar Access Protocol (CAP) June 2002 in a calendar where they might not otherwise have MODIFY access. They are not allowed to change the "ATTENDEE" property value. An example definition for this VCAR is (This example only effects the "VEVENT" components): BEGIN:VCAR CARID:UPDATEPARTSTATUS BEGIN:VRIGHT GRANT:* PERMISSION:MODIFY SCOPE:SELECT ATTENDEE FROM VEVENT WHERE ATTENDEE = SELF() AND ORGANIZER = CURRENT-TARGET() AND STATE() = 'BOOKED' RESTRICTION:SELECT * FROM VEVENT WHERE ATTENDEE = SELF() END:VRIGHT END:VCAR CARID:DEFAULTOWNER - Grants to any owner the permission they have for the target. An example definition for this VCAR is: BEGIN:VCAR CARID:DEFAULTOWNER BEGIN:VRIGHT GRANT:OWNER() PERMISSION:* SCOPE:SELECT * FROM VAGENDA END:VRIGHT END:VCAR 4.2.4 Decreed VCARs A CS MAY choose to implement and allow persistent immutable VCARs that may be configured by the CS administrator. A reply from the CS may dynamically create VCARs that are decreed depending on the implementation. To the CUA any "VCAR" component with the "DECREED" property set to "TRUE" can not be changed by the currently authenticated UPN, and depending on the implementation and other Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 28] Internet-Draft Calendar Access Protocol (CAP) June 2002 VCARs; might not be able to be changed by any UPN using CAP, and never when the CUA gets a "DECREED:TRUE" VCAR. When a user attempts to modify or override a decreed VCAR an error will be returned indicating that the user has insufficient authorization to perform the operation. The reply to the CUA MUST BE the same as if a non-decreed VCAR caused the failure. The CAP protocol does not define the semantics used to initially create a decreed VCAR. This administrative task is outside the scope of the CAP protocol. For example; an implementation or a CS administrator may wish to define a VCAR that will always allow the calendar owners to have full access to their own calendars. Decreed VCARs MUST BE readable by the calendar owner in standard VCAR format. 4.3 CAP Session Identity A BEEP session has an associated set of authentication credentials, from which is derived a UPN. This UPN is the identity of the CAP session, and is used to determine access rights for the session. The CUA may change the identity of a CAP session by calling the "IDENTIFY" command. The Calendar Server only permits the operation if the session's authentication credentials are good for the requested identity. The method of checking this permission is implementation dependent, but may be thought of as a mapping from authentication credentials to UPNs. The "IDENTIFY" command allows a single set of authentication credentials to choose from multiple identities, and allows multiple sets of authentication credentials to assume the same identity. For anonymous access the identity of the session is "@". A UPN with a null Username and null Realm is anonymous. A UPN with a null Username, but non-null Realm, such as "@foo.com" may be used to mean any identity from that Realm, which is useful to grant access rights to all users in a given Realm. A UPN with a non-null Username and null Realm, such as "bob@" could be a security risk and MUST NOT be used. Since the UPN includes Realm information it may be used to govern calendar store access rights across Realms. However, governing access rights across Realms is only useful if login access is available. This could be done through a trusted server relationship or a temporary account. Note that trusted server relationships are Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 29] Internet-Draft Calendar Access Protocol (CAP) June 2002 outside the scope of [CAP]. The "IDENTIFY" command also provides for a weak group implementation. By allowing multiple sets of authentication credentials belonging to different users to identify as the same UPN, that UPN essentially identifies a group of people, and may be used for group calendar ownership, or the granting of access rights to a group. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 30] Internet-Draft Calendar Access Protocol (CAP) June 2002 5. CAP URL and Calendar Address The CAP URL scheme is used to designate calendar stores and calendars accessible using the CAP protocol. The CAP URL scheme conform to the generic URL syntax, defined in RFC 2396, and follows the Guidelines for URL Schemes, set forth in RFC 2718. A CAP URL begins with the protocol prefix "cap" and is defined by the following grammar. capurl = "cap://" csid [ "/" relcalid ] csid = hostport ; As defined in Section 3.2.2 of RFC 2396 relcalid = *uric ; As defined in Section 2 of RFC 2396 'relcalid' is an identifier that uniquely identifies a calendar on a particular calendar store. There is no implied structure in a Relative CALID. It may refer to the calendar of a user or of a resource such as a conference room. It MUST BE unique within the calendar store. Examples: cap://cal.example.com cap://cal.example.com/Company/Holidays cap://cal.example.com/abcd1234Usr Relative CAP URLs are permitted and are resolved according to the rules defined in Section 5 of RFC 2396. Examples of valid relative CAP URLs: opqaueXzz123String UserName/Personal A Calendar addresses can be described as qualified or relative CAP URLs. For a user currently authenticated to the CS on cal.example.com, these two example calendar addresses refer to the same calendar: Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 31] Internet-Draft Calendar Access Protocol (CAP) June 2002 cap://cal.example.com/abcd1234USR abcd1234USR Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 32] Internet-Draft Calendar Access Protocol (CAP) June 2002 6. New Components, Properties, Parameters, and Values The following sections contains new components, properties, parameters, and value definitions. The purpose of these is to extend the iCalendar objects in a compatible way so that existing iCalendar VERSION 2.0 parsers can still parse the objects without modification. 6.1 Property Value Data Types 6.1.1 CAL-QUERY Value Type Subject: Registration of text/calendar MIME value type CAL-QUERY Value Name: CAL-QUERY Value Type Purpose: This value type is used to identify values and contains query statements targeted at locating those values. This is based on [SQL92] and [SQLCOM]. 1. For the purpose of a query, all components should be handled as tables, and the properties of those components, should be handled as columns. 2. All VAGENDAs and CS's look like tables for the purpose of a QUERY. And all of their properties look like columns in those tables. 3. You CAN NOT do any cross component-type joins. And that means you can ONLY have one component, OR one VAGENDA OR one VCALSTORE in the the FROM clause. 4. Everything in the SELECT and WHERE clauses MUST BE from the same component type, or VAGENDA OR VCALSTORE in the FROM clause. 5. When multiple QUERY properties are supplied in a single VQUERY component, the results returned are the same as the results returned for multiple VQUERY components having each a single QUERY property and the results are return in the same order as the VQUERYs were specified in the original command. 6. The '.' is used to separate the table name (component) and column name (property or component) when selecting a property that is contained inside of a component that is targeted in the TARGET property. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 33] Internet-Draft Calendar Access Protocol (CAP) June 2002 7. A contained component without a '.' is not the same as "component-name.*". If given as "component-name" (no dot) the the encapsulating BEGIN/END statement will be supplied for "component-name".: In this example the '.' is used to separate the TRIGGER property from its contained component (VALARM) which is contained in any VEVENT in the selected TARGET (relcalid). All TRIGGER values in any VEVENT in relcalid would be returned. TARGET:relcalid QUERY:SELECT VALARM.TRIGGER FROM VEVENT SELECT VALARM FROM VEVENT WHERE UID = "123" This return one BEGIN/END VALARM for each VALARM in the VEVENT as there is no '.' (dot) in the VALARM: BEGIN:VALARM TRIGGER;RELATED=END:PT5M REPEAT:4 ... END:VALARM BEGIN:VALARM TRIGGER;RELATED=START:PT5M DURATION:PT10M ... END:VALARM ... ... If provided as "component-name.*", then only the properties and any contained components will be returned: Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 34] Internet-Draft Calendar Access Protocol (CAP) June 2002 SELECT VALARM.* FROM VEVENT WHERE UID = "123" Will return the properties in each VALARM in the VEVENT: TRIGGER;RELATED=END:PT5M REPEAT:4 ... TRIGGER;RELATED=START:PT5M DURATION:PT10M ... ... (a) SELECT VEVENT. FROM VEVENT (b) SELECT VALARM FROM VEVENT (c) SELECT VALARM.* FROM VEVENT (d) SELECT * FROM VEVENT (e) SELECT * FROM VEVENT WHERE VALARM.TRIGGER < '20020201T000000Z' AND VALARM.TRIGGER > '20020101T000000Z' Note: (a) Selects all instances of from all VEVENT components. (b) and (c) Select all VALARM components from all VEVENT components. (b) would return then in BEGIN/END VALARM tags. (c) would return all of the properties without BEGIN/END VALARM tags. (d) Selects every property and every component that is in any VEVENT component. (e) Selects all properties and all contained components in all VEVENT components that have a VALARM with a TRIGGER property value between the provided dates and times. NOT VALID: (f) SELECT VEVENET.VALARM.TRIGGER FROM VEVENT (g) SELECT DTSTART,UID FROM VEVENT WHERE Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 35] Internet-Draft Calendar Access Protocol (CAP) June 2002 VTODO.SUMMERY = "Fix typo in CAP" Note: (f) Is NOT valid because it contains two '.' characters in the SELECT clause. (g) Is NOT valid because it mixes VEVENT and VTODO properties in the same VQUERY. Formal Definition: The value type is defined by the following notation: comp-name = "VEVENT" / "VTODO" / "VJOURNAL" / "VTIMEZONE" / "VALARM" / "VFREEBUSY" / "VAGENDA" / "VCAR" / "VCALSTORE" / "VQUERY" / iana-name / x-comp querycomp = queries ; These next three property types ; may be in any order. ; / ( queryid *(name) queries) ; Only when using an existing stored query ; can query or queries be omitted. ; / queryid queries = query / queries query ; NOTE: There is exactly one space separating ; the various parts of cal-query ; cal-query = "SELECT" SP cap-cols SP "FROM" SP comp-name SP *(cauprops SP / capcprops SP) "WHERE" SP cap-expr / "SELECT" SP cap-cols SP "FROM" SP comp-name uprop-list = (cap-col SP cap-local) / uprop-list SP cap-col SP cap-local Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 36] Internet-Draft Calendar Access Protocol (CAP) June 2002 cprop-list = (cap-comp cap-local) / cprop-list SP cap-col SP cap-local cap-col = ; Any property name found in the component ; named in the comp-tbl used in the FROM clause. ; ; SELECT ORGANIZER FROM VEVENT ... ; ; OR ; ; A component name of an existing component contained ; inside of the cmp-tbl used in the FROM clause. ; ; SELECT VALARM FROM VEVENT ... ; NOTE: there is NO space around the "," on ; the next line cap-cols = cap-col / ( cap-cols "," cap-col) / "*" / cap-param = ; Any parameter that may be contained in the cap-col ; in the supplied PARAM() function cap-local = ; Any string that is composed of the characters ; that could be a cap-col name, but is not any ; cap-col name. It is suggested that the ; string start with "my-" to ensure it does not ; conflict with any existing or future cap-col name. ; This name MUST BE defined in the cap-using and ; can only be used in cap-expr of the same query. ; And this name is only known and valid for the ; provided query and only for the lifetime of ; the query. If multiple QUERY properties exist ; in the same component, it is only valid and usable ; in the same QUERY property where it was supplied. col-value = col-literal / "STATE()" / "SELF()" / "CAL-OWNERS()" / "CAL-OWNERS(" cal-address ")" / "CURRENT-TARGET()" cal-address = ; A CALID as define by CAP col-literal = "'" literal-data "'" literal-data = ; Any data that matches the value type of the Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 37] Internet-Draft Calendar Access Protocol (CAP) June 2002 ; column that is being compared. That is you can ; not compare PRIORITY to "some string" because ; PRIORITY has a value type of integer. If it is ; not preceded by the LIKE element, any '%' and '_' ; characters in the literal data are not treated as ; wildcard characters and do not have to be backslash ; escaped. ; ; OR ; ; If the literal-data is preceded by the LIKE ; element it may also contain the '%' and '_' ; wildcard characters. And if the literal data ; that is comparing contains any '%' or '_' ; characters, they MUST BE backslash escaped as ; described in the notes below in order for them not ; to be treated as wildcard characters. cap-ucol = cap-col / cap-local cap-expr = "(" cap-expr ")" / cap-term cap-term = cap-expr SP cap-logical SP cap-expr / cap-factor cap-factor = cap-colval SP cap-oper SP col-value / cap-colval SP "NOT LIKE" SP col-value / cap-colval SP "LIKE" SP col-value / cap-colval SP "IS NULL" / cap-colval SP "IS NOT NULL" / col-value SP "NOT IN" cap-colval" / col-value SP "IN" cap-colval" cap-colval = cap-ucolq / "PARAM(" cap-ucol "," cap-param ")" cap-oper = "=" / "!=" / "<" / ">" / "<=" / ">=" cap-logical = "AND" / "OR" SP = ; A single white space ascii character ; (value in HEX %x20). Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 38] Internet-Draft Calendar Access Protocol (CAP) June 2002 CRLF = ; As defined in RFC 2445. xparam = ; As defined in RFC 2445. x-prop = ; As defined in RFC 2445. x-comp = ; As defined in RFC 2445. 6.1.1.1 CAL-OWNERS() This function returns the list of "OWNERS" for the named calendar. If called as 'CAL-OWNERS()', it is equivalent to the comma separated list of all of the owners of the current "TARGET" calendar. If the target is a "VAGENDA", it returns the "CALMASTER" value. If called as 'CAL-OWNERS(cal-address)', then it is the equivalent to the comma separated list of owners for the named calendar id. 6.1.1.2 CURRENT-TARGET() Is equivalent to the value of the "TARGET" property in the current command. Used in a CAL-QUERY 'WHERE' clause. 6.1.1.3 [NOT] OWNER() Returns true if the current UPN is an owner of the current "TARGET". Used in a CAL-QUERY 'WHERE' clause and in the UPN-FILTER. 6.1.1.4 SELF() Used in a CAL-QUERY 'WHERE' clause. Returns the UPN of the currently authenticated CU. 6.1.1.5 STATE() Returns one of three values, 'BOOKED', 'UNPROCESSED', or 'DELETED' depending on the state of the object. Used in a CAL-QUERY 'WHERE' clause. 6.1.1.6 Ordering of Results Sorting will take place in the order the columns are supplied in the QUERY command. The CS MUST sort at least the first column. The CS MAY sort additional columns. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 39] Internet-Draft Calendar Access Protocol (CAP) June 2002 Float and integer values MUST BE sorted by their numeric value. This means the result of a sort on an integer value type will be: 1, 2, 100, 1000 and not 1, 100, 1000, 2 This means the result of a sort on an float value type will be: 1.1, 2.23, 100.332, 1000.12 and not 1.1, 100.332, 1000.12, 2.23 Date and date time values will be sorted by their equivalent value in UTC. No matter what the returned time zone in the result set returns. This is so that if multiple components are returned each in a unique time zone, the results will be sorted in UTC. This does not mean the values MUST BE converted to UTC in the data returned to the CUA. It means the CS must do the sort in UTC. All other values are sorted according to the locale sorting order as specified in the command. Or the calendar locale if known, or the CS locale if the calendar does not have any locale set. And the locale to use for the sort is determined in that order. 6.1.1.7 Date sorting order If the cap-cols is only "*" and nothing else and the result set has a DTSTART, then: If EXPAND=FALSE sorting will be by the DTSTART value ascending as if it were in UTC. If EXPAND=TRUE sorting will be by the RECURRENCE-ID value ascending as if it were in UTC. If one or more DTSTART or RECURRENCE-ID components have exactly the same value, the order for those matching components is unspecified. If the selected component(s) do not contain a DTSTART or a Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 40] Internet-Draft Calendar Access Protocol (CAP) June 2002 RECURRENCE-ID, then the order is unspecified. If an instance does not have a RECURRENCE-ID and the query compares RECURRENCE-IDs (comparing a RECURRENCE-ID to the date or date/time of a single instance object), then the CS MUST compare the DTSTART value as if it were a RECURRENCE-ID even for single instance objects that do not contain a RECURRENCE-ID. A component with a DATE and no TIME value is returned before objects with both a DATE and TIME value when the dates of those two (or more) objects are the same, sorted by date. 6.1.1.8 Use of single quote All literal values are surrounded by single quotes ('), not double quotes ("), and not without any quotes. If the value contains quotes or any other ESCAPED-CHAR, they MUST BE backslash escaped as described in section "4.3.11 Text" of RFC2445. Any LIKE wildcard characters that are part of any literal data that is preceded by a LIKE clause and is not intended to mean wildcard search, MUST BE escaped as described in note (7) below. 6.1.1.9 Comparing DATE and DATE-TIME values When comparing DATE-TIME to DATE value types and when comparing DATE to DATE-TIME value types, the result will be true if the DATE value is on the same day as the DATE-TIME value. And they are compared in UTC no matter what time zone the data may actual have been stored in. VALUE-1 VALUE-2 Compare Results 20020304 20020304T123456 TRUE (in UTC-3) (in UTC-3) 20020304 20020304T003456 FALSE (in UTC) (in UTC-4) 20020304T003456Z 20020205T003456 FALSE (in UTC-0) (in UTC-7) When the DATE or DATE-TIME value is not associated with a time zone, then the CS will compare the value assuming that the no time zone values are in the calendars default time zone. When comparing DATE and DATE-TIME values with the LIKE clause the comparison will be done as if the value is a RFC2445 DATE or DATE- Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 41] Internet-Draft Calendar Access Protocol (CAP) June 2002 TIME string value. LIKE '2002%' will match anything in the year 2002. LIKE '200201%' will match anything in January 2002. LIKE '%T000000' will match anything at midnight. LIKE '____01__T%' will match anything for any year or time that is in January. (Four '_', '01', two '_' 'T%'). Using a LIKE value of "%00%, would return any value that contained two consecutive zeros. Again all comparisons will be done in UTC. 6.1.1.10 DTEND and DURATION When a QUERY contains a DTEND value, then the CS MUST also evaluate any existing DURATION property value and determine if it has an effective end time that matches the QUERY supplied DTEND value or any range of values supplied by the QUERY. When a QUERY contains a DURATION value, then the CS MUST also evaluate any existing DTEND property value and determine if it has an effective duration that matches the QUERY supplied DURATION value or any range of values supplied by the QUERY. As DTEND is the first time that is excluded from a components time range, any DURATION supplied by the QUERY that is exactly one second less than DTEND MUST match the QUERY. And if the DURATION ends exactly at the computed DTEND it MUST NOT match. Any DTEND supplied by the QUERY that is exactly one second more than an end time computed from a DURATION MUST match the QUERY. Any end time that is computed from a DURATION that exactly matches the supplied DTEND MUST NOT match. Given a meeting room reserved with a component that contains (date- time-example-1): Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 42] Internet-Draft Calendar Access Protocol (CAP) June 2002 DTSTART:20020127T000000Z DTEND:20020127T010000Z The reservation is really from: January 27th, 2002 00:00:00 To: January 27th, 2002,00:59:59 Given another meeting room reserved with a component that contains (date-time-example-2): DTSTART:20020127T000000Z DURATION:P59M59S The reservation is really from: January 27th, 2002 00:00:00 To: January 27th, 2002,00:59:59 A QUERY that contains: ... VEVENT.DTSTART = '20020127T00000Z' AND VEVENT.DTEND = '20020127T010000Z' MUST match both (date-time-example-1) and (date-time-example-2) A QUERY that contains: ... VEVENT.DTSTART = '20020127T00000Z' AND DURATION = 'P59M59S' MUST match both (date-time-example-1) and (date-time-example-2) Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 43] Internet-Draft Calendar Access Protocol (CAP) June 2002 6.1.1.11 [NOT] LIKE The pattern matching characters are the '%' that matches zero or more characters, and '_' that matches exactly one character (where character does not always mean octet). LIKE pattern matches always cover the entire string. To match a pattern anywhere within a string, the pattern must start and end with a percent sign. To match a '%' or '_' in the data and not have it interpreted as a wildcard character, they MUST BE backslash escaped. That is to search for a '%' or '_' in the string: LIKE '%\%%' Matches any string with a '%' in it. LIKE '%\_%' Matches any string with a '_' in it. Strings compared using the LIKE clause MUST BE performed using case in-sensitive comparisons when the locale allows. (Example: in US- ASCII the compare assumes 'a' = 'A'). If LIKE is preceded by 'NOT' then there is a match when the string compare fails. Some property values (such as the 'recur' value type), contain commas and are not multi valued. The CS must understand the objects being compared and understand how to determine how any multi valued or multi instances properties or parameter values are separated, quoted, and backslash escaped and perform the comparisons as if each value existed by itself and not quoted or backslash escaped when comparing using the IN element. And see the examples in the next section (IN). 6.1.1.12 Empty vs. NULL When used in a CAL-QUERY value, "NULL" means that the property or parameter is not present in the object. If the property (or parameter) exists, but has no value then "NULL" MUST NOT match. If the property (or parameter) exists, but has no value then it matches the empty string '' (quote quote). Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 44] Internet-Draft Calendar Access Protocol (CAP) June 2002 6.1.1.13 [NOT] IN This is similar to the LIKE element, except it does value matching and not string comparison matches. Some iCalendar objects can be multi instance and multi valued. The IN operator will return a match if the literal value supplied as part of the 'IN' clause is contained in the value of any instance of the named property or parameter, or is in any of the multiple values in the named property or parameter. Unlike the 'LIKE' clause, the '%' and '_' matching characters are not used with the 'IN' clause and have no special meaning. BEGIN:A-COMPONENT a property:value1,value2 One property, two values. b property:"value1,value2" One property, one value. c FOO:parameter=1,2:x One parameter, two values. d FOO:parameter="1,2",3:y One parameter, one value. e FOO:parameter=",":z One parameter, one value. f property:x,y,z One property, three values END:A-COMPONENT 'value1' IN property would match (a) only. 'value1,value2' IN property would match (b) only. 'value%' IN property would NOT match any. ',' IN property would NOT match any. '%,%' IN property would NOT match any. 'x' IN property would match (f) and (c). '2' IN parameter would match (c) only. '1,2' IN parameter would match (d) only. ',' IN parameter would match (e) only. '%,%' IN parameter would NOT match any. property LIKE 'value1%' would match (a) and (b) property LIKE 'value%' would match (a) and (b) property LIKE 'x' would match (f) and (c). parameter LIKE '1%' would match (c) and (d) parameter LIKE '%2%' would match (c) and (d) parameter LIKE ',' would match (e) only. Some property values (such as the 'recur' value type), contain commas and are not multi valued. The CS must understand the objects being compared and understand how to determine how any multi valued or multi instances properties or parameter values are separated, quoted, and backslash escaped and perform the comparisons as if each value existed by itself and not quoted or backslash escaped when comparing Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 45] Internet-Draft Calendar Access Protocol (CAP) June 2002 using the IN element. If IN is preceded by 'NOT' then there is a match when the value does not exist in the property or parameter value. 6.1.1.14 DATE-TIME and TIME values in a WHEN clause All DATE-TIME and TIME literal values supplied in a WHEN clause MUST BE terminated with 'Z'. That means that the CUA MUST supply the values in UTC. Valid: WHERE alarm.TRIGGER < '20020201T000000Z' AND alarm.TRIGGER > '20020101T000000Z' Not valid and it is a syntax error and the CS MUST reject the QUERY. WHERE alarm.TRIGGER < '20020201T000000' AND alarm.TRIGGER > '20020101T000000' 6.1.1.15 Multiple contained components All comparisons MUST BE done from the same instance of a contained component or property and repeated for each instance. As in the following example that uses a VALARM component contained in a VEVENT. If any instance of VALARM in VEVENT matches the query and the rest of the query is satisfied, then the UID, SUMMARY, and DESCRIPTION from the VEVENT will be returned. If there were two VALARMs in a VEVENT, then both VALARMs are tested and in this example only when the VEVENT state is booked: BEGIN:VQUERY EXPAND:TRUE QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT WHERE VALARM.TRIGGER >= '20000101T030405Z' AND VALARM.TRIGGER <= '20001231T235959Z' AND STATE() = 'BOOKED' END:VQUERY Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 46] Internet-Draft Calendar Access Protocol (CAP) June 2002 6.1.1.16 Example, Query by UID The following example would match the entire content of a "VEVENT" or "VTODO" component with the "UID" property equal to "uid123" and not expand any multiple instances of the component. If the CUA does not know if "uid123" was a "VEVENT", "VTODO", "VJOURNAL", or any other component, then all components that the CUA supports MUST BE supplied in a QUERY property. This example assumes the CUA is only interested in "VTODO" and "VEVENT" components. If the results were empty it could also mean that "uid123" was a property in a component other than a VTODO or VEVENT. BEGIN:VQUERY QUERY:SELECT * FROM VTODO WHERE UID = 'uid123' QUERY:SELECT * FROM VEVENT WHERE UID = 'uid123' END:VQUERY 6.1.1.17 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. This includes single instance VEVENT objects that do no explicitly contain a RECURRENCE-ID. BEGIN:VQUERY EXPAND:TRUE QUERY:SELECT * FROM VEVENT WHERE RECURRENCE-ID >= '20000801T000000Z' AND RECURRENCE-ID <= '20000831T235959Z' AND STATE() = 'BOOKED' END:VQUERY 6.1.1.18 Query for all Unprocessed Entries The following example selects the entire contents of all non-booked "VTODO" and "VEVENT" components with their state of 'UNPROCESSED". The default for EXPAND is FALSE, so the recurrence rules will not be expanded. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 47] Internet-Draft Calendar Access Protocol (CAP) June 2002 BEGIN:VQUERY QUERYID:Fetch VEVENT and VTODO iTIP components QUERY:SELECT * FROM VEVENT WHERE STATE() = 'UNPROCESSED' QUERY:SELECT * FROM VTODO WHERE STATE() = 'UNPROCESSED' END:VQUERY The following example fetches all "VEVENT" and "VTODO" components that are booked from the CS. BEGIN:VQUERY QUERYID:Fetch All Booked VEVENT and VTODO components QUERY:SELECT * FROM VEVENT WHERE STATE() = 'BOOKED' QUERY:SELECT * FROM VTODO WHERE STATE() = 'BOOKED' END:VQUERY The following fetches the UID for all VEVENT and VTODO components that have been marked for delete). BEGIN:VQUERY QUERYID:Fetch UIDs of marked for delete VEVENTs and VTODOs QUERY:SELECT UID FROM VEVENT WHERE STATE() = 'DELETE' QUERY:SELECT UID FROM VTODO WHERE STATE() = 'DELETE' END:VQUERY In the examples above they were bunched into groups of similar queries. They could be performed all at once by having all of the QUERY property in one BEGIN/END VQUERY component. 6.1.1.19 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 (in UTC). BEGIN:VQUERY QUERY:SELECT UID,DTSTART,DESCRIPTION,SUMMARY FROM VEVENT WHERE DTSTART >= '20000201T000000Z' AND DTSTART <= '20000210T235959Z' END:VQUERY Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 48] Internet-Draft Calendar Access Protocol (CAP) June 2002 6.1.1.20 Query with Components and Alarms In A Range This example fetches all booked "VEVENT" components with an alarm that triggers within the specified time range. In this case only the "UID", "SUMMARY", and "DESCRIPTION" properties will be selected for all booked "VEVENTS" components that have an alarm between the two date-times supplied. BEGIN:VQUERY EXPAND:TRUE QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT WHERE VALARM.TRIGGER >= '20000101T030405Z' AND VALARM.TRIGGER <= '20001231T235959Z' AND STATE() = 'BOOKED' END:VQUERY 6.1.2 UPN Value Type Value Name: UPN Purpose: This value type is used to identify values that contain user principal name of CU or group of CU. Formal Definition: The value type is defined by the following notation: upn = "@" / [ dot-atom-text ] "@" dot-atom-text ; dot-atom-text is defined in RFC 2822 Description: This data type is an identifier that denotes a CU or a group of CU. Example: The following is a UPN for a CU: jdoe@acme.com Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 49] Internet-Draft Calendar Access Protocol (CAP) June 2002 The following is a UPN for a group of CU: staff@acme.com The following is a UPN for an anonymous CU belonging to a specific realm: @acme.com The following is a UPN for an anonymous CU: @ 6.1.3 UPN-FILTER Value Value Name: UPN-FILTER Purpose: This value type is used to identify values that contain a user principal name filter. Formal Definition: The value type is defined by the following notation: upn-filter = "OWNER()" / "NOT OWNER()" / "*" / [ "*" / dot-atom-text ] "@" ( "*" / dot-atom-text ) ; dot-atom-text is defined in RFC 2822 Description: The value is used to match user principal names (UPNs). For "OWNER()" and "NOT OWNER()", see Section 6.1.1.3. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 50] Internet-Draft Calendar Access Protocol (CAP) June 2002 * Matches all UPNs. @ Matches the UPN of anonymous CUs belonging to the null realm @* Matches the UPN of anonymous CUs belonging to any non-null realm @realm Matches the UPN of anonymous CUs belonging to the specified realm. *@* Matches the UPN of non-anonymous CUs belonging to any non-null realm *@realm Matches the UPN of non-anonymous CUs belonging to the specified realm user@realm Matches the UPN of the specified CU belonging to the specified realm user@* Not allowed. Example: The following are examples of this value type: DENY:NON OWNER() 6.2 New Parameter 6.2.1 ENABLE Parameter Parameter Name: ENABLE Purpose: This parameter indicates whether or not the "TRIGGER" property in a "VALARM" component should be ignored. Value Type: BOOLEAN Conformance: This property can be specified in the "TRIGGER" properties. Description: When a non owner sends an iTIP "REQUEST" to a calendar that object might contain a "VALARM" component. The owner may wish to have local control over their own CUA and when or how alarms are Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 51] Internet-Draft Calendar Access Protocol (CAP) June 2002 triggered. A CUA may add the "ENABLE" parameter to any "TRIGGER" property before booking the component. If the "ENABLE" parameter is set to "FALSE", then the alarm will be ignored by the CUA. If set to "TRUE", or of the "ENABLE" property is not in the "TRIGGER" property, the alarm is enabled. The CUA should remove the "ENABLE" parameter before forwarding the component to a non-cap CUA. If FALSE in the "VCALSTORE", then all "VAGENDA" ALLOW-CONFLICT values MUST BE false in the CS. Format Definition: The property is defined by the following notation: allow-conflict = "ALLOW-CONFLICT" *(";" xparam) ":" boolean CRLF Example: The following is an example of this property for a "VAGENDA" component: ALLOW-CONFLICT:FALSE 6.2.2 LOCAL Parameter Parameter Name: LOCAL Purpose: Indicates if the VALARM should be exported to any non- organizer calendar. Value Type: BOOLEAN Conformance: This property can be specified in the "SEQUENCE" properties in a "VALARM" component. Description: When a non owner sends an iTIP "REQUEST" to a calendar that object might contain a "VALARM" component. The owner may wish to have local control over their own CUA and when or how alarms are triggered. A CUA may add the "LOCAL" parameter to the "SEQUENCE" property before booking the component. If the "LOCAL" parameter is set to "FALSE", then the alarm MUST NOT be forwarded to any non organizer calendar. If set to "TRUE", or of the "LOCAL" property is not in the "SEQUENCE" Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 52] Internet-Draft Calendar Access Protocol (CAP) June 2002 property, the alarm is global. The CUA should remove the "LOCAL" parameter before forwarding the component to a non-cap CUA and to non organizer calendars. If FALSE in the "VCALSTORE", then all "VAGENDA" ALLOW-CONFLICT values MUST BE false in the CS. Format Definition: The property is defined by the following notation: allow-conflict = "ALLOW-CONFLICT" *(";" xparam) ":" boolean CRLF Example: The following is an example of this property for a "VAGENDA" component: ALLOW-CONFLICT:FALSE Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 53] Internet-Draft Calendar Access Protocol (CAP) June 2002 7. New Properties 7.1 ALLOW-CONFLICT Property Property Name: ALLOW-CONFLICT Purpose: This property indicates whether or not the calendar and CS supports component conflicts. That is, whether or not any of the components in the calendar can overlap. Value Type: BOOLEAN Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in "VAGENDA" and "VCALSTORE" component. Description: This property is used to indicate whether components may conflict. That is, if their expanded instances may share the same time or overlap the same time periods. If it has a value of TRUE, then conflicts are allowed. If FALSE, the no two components may conflict. If FALSE in the "VCALSTORE", then all "VAGENDA" ALLOW-CONFLICT values MUST BE false in the CS. Format Definition: The property is defined by the following notation: allow-conflict = "ALLOW-CONFLICT" *(";" xparam) ":" boolean CRLF Example: The following is an example of this property for a "VAGENDA" component: ALLOW-CONFLICT:FALSE 7.2 CALID Property Property Name: CALID Property Parameters: Non-standard property parameters can be specified on this property. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 54] Internet-Draft Calendar Access Protocol (CAP) June 2002 Conformance: This property can be specified in the "VAGENDA". Description: This property is used to specify a fully qualified calid. Format Definition: The property is defined by the following notation: CALID = "CALID" *(";" xparam) ":" calid CRLF Example: CALID:cap://cal.example.com/sdfifgty4321 7.3 CALMASTER Property Property Name: CALMASTER Purpose: The property specifies an e-mail address of a person responsible for the calendar store. Value Type: URI Property Parameters: Non-standard property parameters can be specified on this property. Conformance: The property can be specified in a "VCALSTORE" component. Description: The parameter value SHOULD BE a MAILTO URI as defined in [RFC1738]. It MUST BE a contact URI such as a MAILTO URI and not a home page or file URI that describes how to contact the calmasters. Format Definition: The property is defined by the following notation: calmaster = "CALMASTER" *(";" xparam) ":" uri CRLF uri = IANA registered uri and defined by RFC 2445 Example: The following is an example of this property: Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 55] Internet-Draft Calendar Access Protocol (CAP) June 2002 CALMASTER:mailto:administrator@example.com 7.4 CARID Property Property Name: CARID Purpose: This property specifies the identifier for an access right component. Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property MUST BE specified once in a "VCAR" component. Description: This property is used in the "VCAR" component to specify an identifier. Format Definition: The property is defined by the following notation: carid = "CARID" *(";" xparam) ":" text CRLF Example: The following are examples of this property: CARID:xyzzy-007 CARID:User Rights 7.5 CSID Property Property Name: CSID Purpose: The property specifies a the globally unique identifier for the calendar store. Value Type: URI Property Parameters: Non-standard property parameters can be specified on this property. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 56] Internet-Draft Calendar Access Protocol (CAP) June 2002 Conformance: The property can be specified in a "VCALSTORE" component. Description: The identifier MUST BE globally unique. Format Definition: The property is defined by the following notation: csid = "CSID" *(";" xparam) ":" capurl CRLF Example: The following is an example of this property: CSID:cap://calendar.example.com 7.6 DECREED Property Property Name: DECREED Purpose: This property specifies if an access right calendar component is decreed or not. Value Type: BOOLEAN Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property MAY be specified once in a "VCAR" component. Description: This property is used in the "VCAR" component to specify whether the component is decreed or not. Format Definition: The property is defined by the following notation: decreed = "DECREED" *(";" xparam) ":" boolean CRLF Example: The following is an example of this property: DECREED:TRUE Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 57] Internet-Draft Calendar Access Protocol (CAP) June 2002 7.7 DEFAULT-CHARSET Property Property Name: DEFAULT-CHARSET Purpose: This property indicates the default charset. Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in "VAGENDA" and "VCALSTORE" calendar component. Description: In a "VAGENDA", this property is used to indicate the charset of calendar. If not specified, the default the first value in the "VCALSTORE" DEFAULT-CHARSET list. The value MUST BE an IANA registered character set as defined in [RFC 2278]. In a "VCALSTORE" it is a comma separated list of charsets supported by the CS. The first entry is the default entry for all newly created "VAGENDA"s. "UTF-8" MUST BE in the "VCALSTORE" DEFAULT- CHARSET list. If a charset name contains a comma (,), then that comma must be backslashed escaped in the value. Format Definition: The property is defined by the following notation: default-charset = "DEFAULT-CHARSET" *(";" xparam) ":" text CRLF Example: The following is an example of this property for a "VAGENDA" component: DEFAULT-CHARSET:Shift_JIS,UTF-8 7.8 DEFAULT-LOCALE Property Property Name: DEFAULT-LOCALE Purpose: This property specifies the default language for text values. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 58] Internet-Draft Calendar Access Protocol (CAP) June 2002 Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in "VAGENDA" and "VCALSTORE" components. Description: In a "VAGENDA", this property is used to indicate the locale of the calendar. The full locale SHOULD be used. The default and minimum locale is POSIX. In a "VCALSTORE" it is a comma separated list of locales supported by the CS. The first value in the list is the default for all newly created VAGENDAs. POSIX MUST BE in the list. Format Definition: The property is defined by the following notation: default-locale = "DEFAULT-LOCALE" *(";" xparam) ":" language CRLF language = Text identifying a locale, as defined in [RFC 2277] Example: The following is an example of this property: DEFAULT-LOCALE:en-US.iso-8859-1,POSIX 7.9 DEFAULT-TZID Property Property Name: DEFAULT-TZID Purpose: This property specifies the text value that specifies the default time zone for a calendar. Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property may be specified once in a "VAGENDA" and "VCALSTORE" components. Description: In a "VAGENDA" it is the value of the time zone for the Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 59] Internet-Draft Calendar Access Protocol (CAP) June 2002 calendar. This time zone is used when as the localtime for object that contain a date or date-time value without a time zone. In a "VCALSTORE" it is a comma separated list of TZIDs known to the CS. Where TZID values are the same as the TZID property as defined in [iCAL]. The first entry in the list is used as the default TZID for all newly created calendars. The list MUST contain at least UTC. If the TZID contains a comma (,), the comma must be backslash escaped. Format Definition: This property is defined by the following notation: default-tzid = "DEFAULT-TZID" *(";" xparam) ":" [tzidprefix] text CRLF Example: The following is an example of this property: DEFAULT-TZID:US/Eastern,UTC 7.10 DEFAULT-VCARS Property Property Name: DEFAULT-VCARS Purpose: This property is used to specify the CARIDs of the default VCAR components for newly created VAGENDA components. Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property MUST BE specified in "VCALSTORE" calendar component and MUST at least specify the following values: READBUSYTIMEINFO, REQUESTONLY, UPDATEPARTSTATUS, and DEFAULTOWNER. Description: This property is used in the "VCALSTORE" calendar component to specify the CARID of the VCAR components that MUST BE copied in VAGENDA at creation time by the CS. These VCARS components MUST BE stored in the "VCALSTORE". Format Definition: The property is defined by the following notation: Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 60] Internet-Draft Calendar Access Protocol (CAP) June 2002 def-vcars = "DEFAULT-VCARS" *(";" xparam) ":" text *( "," text ) CRLF Example: The following is an example of this property: DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY, UPDATEPARTSTATUS,DEFAULTOWNER 7.11 DENY Property Property Name: DENY Purpose: This property identifies the UPN(s) being denied access in the VRIGHT component. Value Type: UPN-FILTER Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in "VRIGHT" calendar components. Description: This property is used in the "VRIGHT" component to define the CU or UG being denied access. Format Definition: The property is defined by the following notation: deny = "DENY" *(";" xparam) ":" upn-filter CRLF Example: The following are examples of this property: DENY:* DENY:bob@example.com Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 61] Internet-Draft Calendar Access Protocol (CAP) June 2002 7.12 EXPAND property Property Name: EXPAND Purpose: This property is to notify the CS if it should or should not expand any component with recurrence rules into multiple instances in a query reply. Value Type: BOOLEAN Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in "VQUERY" calendar components. Description: If a CUA wishes to see all of the instances of a recurring component the CUA sets EXPAND=TRUE in the VQUERY component. If not specified, the default is FALSE. Format Definition: The property is defined by the following notation: expand = "EXPAND" *(";" xparam) ":" ("TRUE" / "FALSE") CRLF Example: The following are examples of this property: EXPAND:FALSE EXPAND:TRUE 7.13 GRANT Property Property Name: GRANT Purpose: This property identifies the UPN(s) being granted access in the VRIGHT component. Value Type: UPN-FILTER Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in "VRIGHT" calendar components. Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 62] Internet-Draft Calendar Access Protocol (CAP) June 2002 Description: This property is used in the "VRIGHT" component to specify the CU or UG being granted access. Format Definition: The property is defined by the following notation: grant = "GRANT" *(";" xparam) ":" upn-filter CRLF Example: The following are examples of this property: GRANT:* GRANT:bob@example.com 7.14 MAXDATE Property Property Name: MAXDATE Purpose: This property specifies the date/time in the future beyond which the CS cannot represent. Value Type: DATE-TIME Property Parameters: Non-standard property parameters can be specified on this property. Conformance: The property can be specified in the "VCALSTORE". Description: The date and time MUST BE a UTC value and end with 'Z'. Format Definition: The property is defined by the following notation: maxdate = "MAXDATE" *(";" xparam) ":" date-time CRLF Example: The following is an example of this property: MAXDATE:20990101T000000Z Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 63] Internet-Draft Calendar Access Protocol (CAP) June 2002 7.15 MINDATE Property Property Name: MINDATE Purpose: This property specifies the date/time in the past prior to which the server cannot represent. Value Type: DATE-TIME Property Parameters: Non-standard property parameters can be specified on this property. Conformance: The property can be specified in the "VCALSTORE". Description: The date and time MUST BE a UTC value and end with 'Z'. Format Definition: The property is defined by the following notation: mindate = "MINDATE" *(";" xparam) ":" date-time CRLF Example: The following is an example of this property: MINDATE:19710101T000000Z 7.16 NAME Property Property Name: NAME Purpose: This property provides a localizeable display name for a component. Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in a component. Description: This property is used in the in component to specify a localizeable display name. If more than one NAME property is in a component, then they MUST have unique LANG parameters. If the LANG parameter is not supplied, then it defaults to the VAGENDAs default if the component is in a VAGENDA, or the VCALSTORE default if the Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 64] Internet-Draft Calendar Access Protocol (CAP) June 2002 component is stored at the VCALSTORE level. Format Definition: The property is defined by the following notation: name = "NAME" nameparam ":" text CRLF nameparam = *( ; the following is optional, ; but MUST NOT occur more than once ( ";" languageparam ) / ; the following is optional, ; and MAY occur more than once ( ";" xparam ) ) languageparam = ; As defined in [iCAL]. Example: The following is an example of this property: NAME:Restrict Guests From Creating VALARMs On VEVENTs 7.17 OWNER Property Property Name: OWNER Purpose: The property specifies an owner of the component. Value Type: UPN Property Parameters: Non-standard, alternate text representation and language property parameters can be specified on this property. Conformance: The property MUST BE specified at in a "VAGENDA" component. Description: A multi-instanced property indicating the calendar owner. Format Definition: The property is defined by the following notation: Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 65] Internet-Draft Calendar Access Protocol (CAP) June 2002 owner = "OWNER" *(";" xparam) ":" upn CRLF Example: The following is an example of this property: OWNER:jsmith@acme.com OWNER:jdoe@acme.com 7.18 PERMISSION Property Property Name: PERMISSION Purpose: This property defines a permission that is granted or denied in a VRIGHT component. Value Type: TEXT Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in "VRIGHT" calendar components. Description: This property is used in the "VRIGHT" component to define a permission that is granted or denied. Format Definition: The property is defined by the following notation: perm = "PERMISSION" *(";" xparam) ":" permvalue CRLF permvalue = ( "READ" / "CREATE" / "DELETE" / "MODIFY" / all ) all = "*" Example: The following is an example of this property: PERMISSION:READ Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 66] Internet-Draft Calendar Access Protocol (CAP) June 2002 7.19 QUERY property Property Name: QUERY Purpose: Specifies the query for the component. Value Type: CAL-QUERY Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in "VQUERY" components. Description: A "QUERY" is used to specify the CAL-QUERY (Section 6.1.1 for the query. Format Definition: The property is defined by the following notation: query = "QUERY" *(";" xparam) ":" cal-query CRLF Example: The following is an example of this property: QUERY:SELECT * FROM VEVENT 7.20 QUERYID property Property Name: QUERYID Purpose: Specifies a unique ID for a query in the targeted container. Value Type: TEXT Property Parameters: Non-standard property parameters are specified on this property. Conformance: This property can be specified in "VQUERY" components. Description: A "QUERYID" is used to specify the unique id for a stored query. Format Definition: The property is defined by the following notation: Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 67] Internet-Draft Calendar Access Protocol (CAP) June 2002 queryid = "QUERYID" *(";" xparam) ":" text CRLF Example: The following are examples of this property: QUERYID:Any Text String QUERYID:fetchUnProcessed 7.21 REQUEST-STATUS property This description is a revision of the REQUEST-STATUS property for VCALENDAR version 2.0. The 'statdesc' is optional and the 'extdata' may be included when 'statdesc' is not provided. rstatus = "REQUEST-STATUS" rstatparam ":" statcode ";" *(statdesc ) ";" *(extdata) rstatparam = *( ; the following is optional, ; but MUST NOT occur more than once (";" languageparm) / ; the following is optional, ; and MAY occur more than once (";" xparam) ) statcode = 1*DIGIT *("." 1*DIGIT) ;Hierarchical, numeric return status code statdesc = text ;An optional textual status description, content is ;decided by the implementor. May be empty. extdata = text ; Textual exception data. For example, the offending ; property name and value or complete property line. Example: The following are some possible examples of this property. The COMMA and SEMICOLON separator characters in the property value Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 68] Internet-Draft Calendar Access Protocol (CAP) June 2002 are BACKSLASH character escaped because they appear in a text value. REQUEST-STATUS:2.0;Success REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01 REQUEST-STATUS:2.8; Success\, repeating VEVENT ignored. Scheduled as a single VEVENT.;RRULE:FREQ=WEEKLY;INTERVAL=2 REQUEST-STATUS:4.1;Time conflict. Date/time is busy. REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE: MAILTO:jsmith@example.com REQUEST-STATUS:3.7;;ATTENDEE:MAILTO:jsmith@example.com REQUEST-STATUS:10.4;Help! That really shouldn't have happened. 7.22 RESTRICTION Property Property Name: RESTRICTION Purpose: This property defines restrictions on the result value of new or existing components. Value Type: CAL-QUERY Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in "VRIGHT" calendar components, but only when the PERMISSION property is set to "CREATE", "MODIFY", or "*". Description: This property is used in the "VRIGHT" component to define restrictions on the components that can be written (i.e., by using the "CREATE" or "MOVE" commands) as well as on the values that may take existent calendar store properties, calendar properties, components, and properties (i.e., by using the "MODIFY" command). Accepted values MUST match the specified RESTRICTION. Format Definition: The property is defined by the following notation: Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 69] Internet-Draft Calendar Access Protocol (CAP) June 2002 restrict = "RESTRICTION" *(";" xparam) ":" cal-query CRLF Example: The following are examples of this property: RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST' RESTRICTION:SELECT * FROM VEVENT WHERE SELF() IN CAL-OWNERS(ORGANIZER) RESTRICTION:SELECT * FROM VEVENT WHERE 'BUSINESS' IN CATEGORIES 7.23 SCOPE Property Property Name: SCOPE Purpose: This property identifies the objects in the CS to which the access rights applies. Value Type: CAL-QUERY Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in "VRIGHT" calendar components. Description: This property is used in the "VRIGHT" component to define the set of objects subject to the access right being defined. Format Definition: The property is defined by the following notation: scope = "SCOPE" *(";" xparam) ":" cal-query CRLF Example: The following is an example of this property: SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC' Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 70] Internet-Draft Calendar Access Protocol (CAP) June 2002 7.24 TARGET Property Property Name: TARGET Purpose: This property defines the container that the command that is issued will act upon. It its value is a capurl as defended in Section 5. Value Type: URI Property Parameters: Non-standard property parameters can be specified on this property. Conformance: This property can be specified in a command component. Description: This properties value is used to specify the container that the command will effect. When used in a command, the command will be performed on the container which has a capurl matching the value. Format Definition: The property is specified by the following notation: target = "TARGET" *(";" xparam) ":" capurl CRLF The following is an example of this property: TARGET:cap://mycal.example.com TARGET:SomeRelCalid 7.25 TRANSP Property Property Name: TRANSP Purpose: This property defines whether an component is transparent or not to busy time searches. This is a modification to [iCAL] TRANSP in that it adds some values. Value Type: TEXT Property Parameters: Non-standard property parameters can be Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 71] Internet-Draft Calendar Access Protocol (CAP) June 2002 specified on this property. Conformance: This property can be specified in a component. Description: Time Transparency is the characteristic of an object that determines whether it appears to consume time on a calendar. Objects that consume actual time for the individual or resource associated with the calendar SHOULD be recorded as OPAQUE, allowing them to be detected by free-busy time searches. Other objects, which do not take up the individual's (or resource's) time SHOULD be recorded as TRANSPARENT, making them invisible to free-busy time searches. Format Definition: The property is specified by the following notation: transp = "TRANSP" *(";" xparam) ":" transvalue CRLF transvalue = "OPAQUE" ;Blocks or opaque on busy time searches. / "TRANSPARENT" ;Transparent on busy time searches. / "TRANSPARENT-NOCONFLICT" ; Transparent on busy time ; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects ; can overlap it. / "OPAQUE-NOCONFLICT" ; Opaque on busy time ; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects ; can overlap it. ; ;Default value is OPAQUE The following is an example of this property for an object that is opaque or blocks on free/busy time searches plus no other object can overlap it: TRANSP:OPAQUE-NOCONFLICT Royer, Babics, Hill, Mansour Expires December 29, 2002 [Page 72] Internet-Draft Calendar Access Protocol (CAP) June 2002 8. New Components 8.1 VAGENDA Component Component Name: VAGENDA Purpose: Provide a grouping of properties that defines an agenda. Formal Definition: There are two formats of a VAGENDA. (1) When it is being created, and (2) how it exists in the VCALSTORE. A "VAGENDA" component in the VCALSTORE is defined by the following notation table and ABNF notation. The following is a summary of the properties of a calendar. Name Read Description Only ------------------------------------------------------------------ ALLOW-CONFLICT N This boolean value indicates whether or not the calendar supports object conflicts. That is, whether or not any of the components in the calendar can have a time overlap. MUST BE FALSE if VCALSTORE ALLOW-CONFLICT is FALSE. CALID N A unique identifier within the VCALSTORE for the calendar. MUST NOT BE empty. MUST BE a relative calid in a VAGENDA. CALSCALE N The CALSCALE for this calendar. MUST BE from the VCALSTORE CALSCALE list. The default is the first entry in the VCALSTORE CALSCALE list. CREATED Y timestamp of the calendar's create date. DEFAULT-CHARSET N The charset for this calendar. MUST BE from the VCALSTORE DEFAULT-CHARSET list. If empty then it is the first entry in the VCALSTORE