idnits 2.17.1 draft-ietf-calsch-cap-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 18 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** There are 114 instances of lines with control characters in the document. ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? RFC 2119 keyword, line 384: '... is, "events MUST BE scheduled in ...' RFC 2119 keyword, line 439: '... These extensions MUST start with "x-"...' RFC 2119 keyword, line 472: '...flict, the Realm SHOULD be postfixed w...' RFC 2119 keyword, line 477: '...endar store. It MUST BE unique within...' RFC 2119 keyword, line 511: '...odid' and 'version' are both REQUIRED,...' (235 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 317 has weird spacing: '...hat has been ...' == Line 369 has weird spacing: '...able to diffe...' == Line 819 has weird spacing: '... for that U...' == Line 1933 has weird spacing: '...roperty woul...' == Line 1983 has weird spacing: '...mponent match...' == (6 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Purpose: The "ABORT" command is sent to request that the named or only in process command be aborted. Latency MUST not be supplied with the "ABORT" command. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 27, 2003) is 7722 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '1' on line 5598 looks like a reference -- Missing reference section? 'BEEP' on line 5667 looks like a reference -- Missing reference section? 'RFCWORDS' on line 5704 looks like a reference -- Missing reference section? 'GUIDE' on line 5682 looks like a reference -- Missing reference section? 'URL' on line 5727 looks like a reference -- Missing reference section? 'URI' on line 5723 looks like a reference -- Missing reference section? 'URLGUIDE' on line 5719 looks like a reference -- Missing reference section? 'MIME' on line 5699 looks like a reference -- Missing reference section? 'CAP' on line 1309 looks like a reference -- Missing reference section? 'BEEPTCP' on line 5671 looks like a reference -- Missing reference section? 'X509CRL' on line 5731 looks like a reference -- Missing reference section? 'SQL92' on line 5712 looks like a reference -- Missing reference section? 'SQLCOM' on line 5715 looks like a reference -- Missing reference section? 'NOT' on line 1910 looks like a reference -- Missing reference section? 'CHARREG' on line 5674 looks like a reference -- Missing reference section? 'CHARPOL' on line 5678 looks like a reference -- Missing reference section? 'SASL' on line 5708 looks like a reference Summary: 5 errors (**), 0 flaws (~~), 11 warnings (==), 20 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Royer 3 Internet-Draft INET-Consulting 4 Expires: August 28, 2003 G. Babics 5 Oracle 6 P. Hill 7 Massachusetts Institute of 8 Technology 9 S. Mansour 10 AOL/Netscape 11 February 27, 2003 13 Calendar Access Protocol (CAP) 14 draft-ietf-calsch-cap-10 16 Status of this Memo 18 This document is an Internet-Draft and is in full conformance with 19 all provisions of Section 10 of RFC2026. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at http:// 32 www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This Internet-Draft will expire on August 28, 2003. 39 Copyright Notice 41 Copyright (C) The Internet Society (2003). All Rights Reserved. 43 Abstract 45 The Calendar Access Protocol (CAP) is an Internet protocol described 46 in this memo that permits a Calendar User (CU) to utilize a Calendar 47 User Agent (CUA) to access an [iCAL] based Calendar Store (CS). 49 The CAP definition is based on requirements identified by the 50 Internet Engineering Task Force (IETF) Calendaring and Scheduling 51 (CALSCH) Working Group. More information about the IETF CALSCH 52 Working Group activities can be found on the IMC web site at http:// 53 www.imc.org/ietf-calendar and at the IETF web site at http:// 54 www.ietf.org/html.charters/calsch-charter.html [1]. Refer to the 55 references within this memo for further information on how to access 56 these various documents. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . 6 61 1.1 Formatting Conventions . . . . . . . . . . . . . . . . . 6 62 1.2 Related Documents . . . . . . . . . . . . . . . . . . . 7 63 1.3 Definitions . . . . . . . . . . . . . . . . . . . . . . 8 64 2. Additions to iCalendar . . . . . . . . . . . . . . . . . 13 65 2.1 New Value Types (summary) . . . . . . . . . . . . . . . 15 66 2.1.1 New Parameters (summary) . . . . . . . . . . . . . . . . 15 67 2.1.2 New Properties (summary) . . . . . . . . . . . . . . . . 16 68 2.1.3 New Components (summary) . . . . . . . . . . . . . . . . 18 69 2.2 Relationship of RFC-2446 (ITIP) and CAP . . . . . . . . 19 70 3. CAP Design . . . . . . . . . . . . . . . . . . . . . . . 22 71 3.1 System Model . . . . . . . . . . . . . . . . . . . . . . 22 72 3.2 Calendar Store Object Model . . . . . . . . . . . . . . 22 73 3.3 Protocol Model . . . . . . . . . . . . . . . . . . . . . 23 74 3.3.1 Use of BEEP, MIME and iCalendar . . . . . . . . . . . . 24 75 4. Security Model . . . . . . . . . . . . . . . . . . . . . 26 76 4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . . 26 77 4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . . 26 78 4.1.2 Anonymous Users and Authentication . . . . . . . . . . . 27 79 4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . . 27 80 4.2 Access Rights . . . . . . . . . . . . . . . . . . . . . 28 81 4.2.1 Access Control and NOCONFLICT . . . . . . . . . . . . . 28 82 4.2.2 Predefined VCARs . . . . . . . . . . . . . . . . . . . . 28 83 4.2.3 Decreed VCARs . . . . . . . . . . . . . . . . . . . . . 30 84 4.3 CAP Session Identity . . . . . . . . . . . . . . . . . . 31 85 5. CAP URL and Calendar Address . . . . . . . . . . . . . . 32 86 6. New Value Types . . . . . . . . . . . . . . . . . . . . 34 87 6.1 Property Value Data Types . . . . . . . . . . . . . . . 34 88 6.1.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . . . 34 89 6.1.1.1 [NOT] CAL-OWNERS() . . . . . . . . . . . . . . . . . . . 39 90 6.1.1.2 CURRENT-TARGET() . . . . . . . . . . . . . . . . . . . . 40 91 6.1.1.3 PARAM() . . . . . . . . . . . . . . . . . . . . . . . . 40 92 6.1.1.4 SELF() . . . . . . . . . . . . . . . . . . . . . . . . . 40 93 6.1.1.5 STATE() . . . . . . . . . . . . . . . . . . . . . . . . 41 94 6.1.1.6 Ordering of Results . . . . . . . . . . . . . . . . . . 41 95 6.1.1.7 Date sorting order . . . . . . . . . . . . . . . . . . . 42 96 6.1.1.8 Use of single quote . . . . . . . . . . . . . . . . . . 42 97 6.1.1.9 Comparing DATE and DATE-TIME values . . . . . . . . . . 42 98 6.1.1.10 DTEND and DURATION . . . . . . . . . . . . . . . . . . . 43 99 6.1.1.11 [NOT] LIKE . . . . . . . . . . . . . . . . . . . . . . . 45 100 6.1.1.12 Empty vs. NULL . . . . . . . . . . . . . . . . . . . . . 46 101 6.1.1.13 [NOT] IN . . . . . . . . . . . . . . . . . . . . . . . . 46 102 6.1.1.14 DATE-TIME and TIME values in a WHEN clause . . . . . . . 47 103 6.1.1.15 Multiple contained components . . . . . . . . . . . . . 48 104 6.1.1.16 Example, Query by UID . . . . . . . . . . . . . . . . . 48 105 6.1.1.17 Query by Date-Time range . . . . . . . . . . . . . . . . 49 106 6.1.1.18 Query for all Unprocessed Entries . . . . . . . . . . . 49 107 6.1.1.19 Query with Subset of Properties by Date/Time . . . . . . 50 108 6.1.1.20 Query with Components and Alarms In A Range . . . . . . 50 109 6.1.2 UPN Value Type . . . . . . . . . . . . . . . . . . . . . 51 110 6.1.3 UPN-FILTER Value . . . . . . . . . . . . . . . . . . . . 52 111 7. New Parameters . . . . . . . . . . . . . . . . . . . . . 55 112 7.1 ACTION Parameter . . . . . . . . . . . . . . . . . . . . 55 113 7.2 ENABLE Parameter . . . . . . . . . . . . . . . . . . . . 55 114 7.3 ID Parameter . . . . . . . . . . . . . . . . . . . . . . 56 115 7.4 LATENCY Parameter . . . . . . . . . . . . . . . . . . . 57 116 7.5 LOCAL Parameter . . . . . . . . . . . . . . . . . . . . 58 117 7.6 LOCALIZE Parameter . . . . . . . . . . . . . . . . . . . 58 118 7.7 OPTIONS Parameter . . . . . . . . . . . . . . . . . . . 59 119 8. New Properties . . . . . . . . . . . . . . . . . . . . . 61 120 8.1 ALLOW-CONFLICT Property . . . . . . . . . . . . . . . . 61 121 8.2 ATT-COUNTER Property . . . . . . . . . . . . . . . . . . 61 122 8.3 CALID Property . . . . . . . . . . . . . . . . . . . . . 62 123 8.4 CALMASTER Property . . . . . . . . . . . . . . . . . . . 63 124 8.5 CAP-VERSION Property . . . . . . . . . . . . . . . . . . 63 125 8.6 CARID Property . . . . . . . . . . . . . . . . . . . . . 64 126 8.7 CAR-LEVEL Property . . . . . . . . . . . . . . . . . . . 65 127 8.8 COMPONENTS Property . . . . . . . . . . . . . . . . . . 65 128 8.9 CSID Property . . . . . . . . . . . . . . . . . . . . . 67 129 8.10 DECREED Property . . . . . . . . . . . . . . . . . . . . 68 130 8.11 DEFAULT-CHARSET Property . . . . . . . . . . . . . . . . 68 131 8.12 DEFAULT-LOCALE Property . . . . . . . . . . . . . . . . 69 132 8.13 DEFAULT-TZID Property . . . . . . . . . . . . . . . . . 70 133 8.14 DEFAULT-VCARS Property . . . . . . . . . . . . . . . . . 71 134 8.15 DENY Property . . . . . . . . . . . . . . . . . . . . . 72 135 8.16 EXPAND property . . . . . . . . . . . . . . . . . . . . 72 136 8.17 GRANT Property . . . . . . . . . . . . . . . . . . . . . 73 137 8.18 ITIP-VERSION Property . . . . . . . . . . . . . . . . . 74 138 8.19 MAX-COMP-SIZE Property . . . . . . . . . . . . . . . . . 75 139 8.20 MAXDATE Property . . . . . . . . . . . . . . . . . . . . 75 140 8.21 MINDATE Property . . . . . . . . . . . . . . . . . . . . 76 141 8.22 MULTIPART Property . . . . . . . . . . . . . . . . . . . 77 142 8.23 NAME Property . . . . . . . . . . . . . . . . . . . . . 77 143 8.24 OWNER Property . . . . . . . . . . . . . . . . . . . . . 78 144 8.25 PERMISSION Property . . . . . . . . . . . . . . . . . . 79 145 8.26 QUERY property . . . . . . . . . . . . . . . . . . . . . 79 146 8.27 QUERYID property . . . . . . . . . . . . . . . . . . . . 80 147 8.28 REQUEST-STATUS property . . . . . . . . . . . . . . . . 81 148 8.29 QUERY-LEVEL Property . . . . . . . . . . . . . . . . . . 82 149 8.30 RECUR-ACCEPTED Property . . . . . . . . . . . . . . . . 83 150 8.31 RECUR-LIMIT Property . . . . . . . . . . . . . . . . . . 83 151 8.32 RECUR-EXPAND Property . . . . . . . . . . . . . . . . . 84 152 8.33 RESTRICTION Property . . . . . . . . . . . . . . . . . . 85 153 8.34 SCOPE Property . . . . . . . . . . . . . . . . . . . . . 86 154 8.35 STORES-EXPANDED Property . . . . . . . . . . . . . . . . 86 155 8.36 TARGET Property . . . . . . . . . . . . . . . . . . . . 87 156 8.37 TRANSP Property . . . . . . . . . . . . . . . . . . . . 88 157 9. New Components . . . . . . . . . . . . . . . . . . . . . 90 158 9.1 VAGENDA Component . . . . . . . . . . . . . . . . . . . 90 159 9.2 VCALSTORE Component . . . . . . . . . . . . . . . . . . 92 160 9.3 VCAR Component . . . . . . . . . . . . . . . . . . . . . 94 161 9.4 VRIGHT Component . . . . . . . . . . . . . . . . . . . . 97 162 9.5 VREPLY Component . . . . . . . . . . . . . . . . . . . . 98 163 9.6 VQUERY Component . . . . . . . . . . . . . . . . . . . . 98 164 10. Commands and Responses . . . . . . . . . . . . . . . . . 101 165 10.1 CAP Commands (CMD) . . . . . . . . . . . . . . . . . . . 101 166 10.1.1 Bounded Latency . . . . . . . . . . . . . . . . . . . . 102 167 10.1.2 ABORT Command . . . . . . . . . . . . . . . . . . . . . 105 168 10.1.3 CONTINUE Command . . . . . . . . . . . . . . . . . . . . 105 169 10.1.4 CREATE Command . . . . . . . . . . . . . . . . . . . . . 107 170 10.1.5 DELETE Command . . . . . . . . . . . . . . . . . . . . . 112 171 10.2 GENERATE-UID Command . . . . . . . . . . . . . . . . . . 115 172 10.3 GET-CAPABILITY Command . . . . . . . . . . . . . . . . . 117 173 10.4 IDENTIFY Command . . . . . . . . . . . . . . . . . . . . 120 174 10.5 MODIFY Command . . . . . . . . . . . . . . . . . . . . . 122 175 10.6 MOVE Command . . . . . . . . . . . . . . . . . . . . . . 127 176 10.7 REPLY Response to a Command . . . . . . . . . . . . . . 130 177 10.8 SEARCH Command . . . . . . . . . . . . . . . . . . . . . 131 178 10.9 SET-LOCALE Command . . . . . . . . . . . . . . . . . . . 134 179 10.10 TIMEOUT Command . . . . . . . . . . . . . . . . . . . . 136 180 10.11 Response Codes . . . . . . . . . . . . . . . . . . . . . 136 181 11. Object Registration . . . . . . . . . . . . . . . . . . 139 182 11.1 Registration of New and Modified Entities . . . . . . . 139 183 11.2 Post the item definition . . . . . . . . . . . . . . . . 139 184 11.3 Allow a comment period . . . . . . . . . . . . . . . . . 139 185 11.4 Release a new RFC . . . . . . . . . . . . . . . . . . . 139 186 12. BEEP and CAP . . . . . . . . . . . . . . . . . . . . . . 140 187 12.1 BEEP Profile Registration . . . . . . . . . . . . . . . 140 188 12.2 BEEP Exchange Styles . . . . . . . . . . . . . . . . . . 140 189 13. IANA Considerations . . . . . . . . . . . . . . . . . . 141 190 14. Security Considerations . . . . . . . . . . . . . . . . 142 191 Authors' Addresses . . . . . . . . . . . . . . . . . . . 143 192 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . 145 193 B. Bibliography . . . . . . . . . . . . . . . . . . . . . . 146 194 Full Copyright Statement . . . . . . . . . . . . . . . . 148 196 1. Introduction 198 This document specifies how a Calendar CUA interacts with a CS to 199 manage calendar information. In particular, it specifies how to 200 query, create, modify, and delete iCalendar components (e.g., events, 201 to-dos, or daily journal entries). It further specifies how to 202 search for available busy time information. Synchronization with 203 CUAs is not covered. 205 CAP is specified as a [BEEP] "profile". As such, many aspects of the 206 protocol (e.g., authentication and privacy) are provided within 207 [BEEP]. The protocol data units leverage the standard iCalendar 208 format [iCAL] to convey calendar related information. 210 CAP can also be used to store and fetch [iTIP] objects and when those 211 objects are used in this memo, they mean exactly the same as defined 212 in [iTIP]. When iCalendar objects are transferred between the CUA 213 and a CS, some additional properties and parameters may be added and 214 the CUA is responsible for correctly generating iCalendar objects to 215 non CAP processes. 217 The definition of new components, properties, parameter's, and value 218 types are broken into two parts. The first part summarizes and 219 defined the new objects. The second part provides the detail and any 220 ABNF for those objects. 222 1.1 Formatting Conventions 224 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 225 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this 226 document are to be interpreted as described in [RFCWORDS]. 228 Calendaring and scheduling roles are referred to in quoted-strings of 229 text with the first character of each word in upper case. For 230 example, "Organizer" refers to a role of a "Calendar User" (CU) 231 within the protocol defined by [iTIP]. Calendar components defined 232 by [iCAL] are referred to with capitalized, quoted-strings of text. 233 All iCalendar components should start with the letter "V". For 234 example, "VEVENT" refers to the event calendar component, "VTODO" 235 refers to the to-do component and "VJOURNAL" refers to the daily 236 journal component. 238 Scheduling methods defined by [iTIP], are referred to with 239 capitalized, quoted-strings of text. For example, "REPLY" refers to 240 the method for replying to a "REQUEST". 242 CAP commands are referred to by upper-case, quoted-strings of text, 243 followed by the word "command". For example, "CREATE" command refers 244 to the command for creating a calendar entry, "SEARCH" command refers 245 to the command for reading calendar components. CAP Commands are 246 named using the "CMD" property. 248 Properties defined by this memo are referred to with capitalized, 249 quoted-strings of text, followed by the word "property". For 250 example, "ATTENDEE" property refers to the iCalendar property used to 251 convey the calendar address that has been invited to a "VEVENT" or 252 "VTODO" component. 254 Property parameters defined by this memo are referred to with 255 capitalized, quoted-strings of text, followed by the word 256 "parameter". For example, "PARTSTAT" parameter refers to the 257 iCalendar property parameter used to specify the participation status 258 of an attendee. Enumerated values defined by this memo are referred 259 to with capitalized text, either alone or followed by the word 260 "value". 262 Object states defined by this memo are referred to with capitalized, 263 quoted-strings of text, followed by the word "state". For example, 264 "BOOKED" state refers to an object in the booked state. 266 Within a query, the different parts are referred to as a "clause" and 267 its value as "clause value" and the clause name will be in uppercase 268 enclosed in quotes. Example, The "SELECT" clause or if the "SELECT" 269 clause value contains ... 271 In tables, the quoted-string text is specified without quotes in 272 order to minimize the table length. 274 1.2 Related Documents 276 Implementers will need to be familiar with several other memos that, 277 along with this one, describe the Internet calendaring and scheduling 278 standards. These documents are: 280 [iCAL] - (RFC2445) Which specifies the objects, data types, 281 properties and property parameters used in the protocols, along 282 with the methods for representing and encoding them. 284 [iTIP] - (RFC2446) Which specifies an interoperability protocol for 285 scheduling between different installations. 287 [iMIP] - (RFC2447) Which specifies the Internet email binding for 288 [iTIP]. 290 [GUIDE] - (RFC3283), a guide to implementers and describes the 291 elements of a calendaring system, how they interact with each 292 other, how they interact with end users, and how the standards and 293 protocols are used. 295 This memo does not attempt to repeat the specification of concepts 296 and definitions from these other memos. Where possible, references 297 are made to the memo that provides for the specification of these 298 concepts and definitions. 300 1.3 Definitions 302 BOOKED - An object in the calendar store has one of three conceptual 303 states. It is in the "UNPROCESSED" state, "BOOKED" state, or 304 marked for deletion which is the "DELETED" state. How the 305 implementation stores the state of any object is not a protocol 306 issues and is not discussed. An object can be said to be booked, 307 unprocessed, or marked for delete. 309 1. An "UNPROCESSED" state scheduling object has been stored in 310 the calendar store but has not been acted on by a CU or CUA. 311 All scheduled entries are [iTIP] objects. All [iTIP] objects 312 in the store are not in the "BOOKED" state. To retrieve any 313 [iTIP] object, simply do a query asking for any objects that 314 were stored in the "UNPROCESSED" state. 316 2. A "BOOKED" state entry is stored with the "CREATE" command. 317 It is an object that has been acted on by a CU or CUA and 318 there has been a decision to store an object. To retrieve any 319 booked object, simply do a query asking for any objects that 320 were stored in the "BOOKED" state. 322 3. A "DELETED" state entry is created by sending a "DELETE" 323 command with the "OPTION" parameter value set to "MARK". To 324 retrieve any deleted object, simply do a query asking for any 325 objects that were stored in the "DELETED" state. By default 326 objects marked for delete are not returned. The CUA must 327 specifically ask for marked for delete objects. You can not 328 ask for components in the "DELETED" state and in other states 329 in the same "VQUERY" component, as there would be no way to 330 distinguish between them in the reply. 332 Calendar - A collection of logically related objects or entities 333 each of which may be associated with a calendar date and possibly 334 time of day. These entities can include calendar properties or 335 components. In addition, a calendar might be related to other 336 calendars with the "RELATED-TO" property. A calendar is 337 identified by its unique calendar identifier. The [iCAL] defines 338 the initial calendar properties, calendar components and 339 properties that make up the contents of a calendar. 341 Calendar Access Protocol (CAP) - The standard Internet protocol that 342 permits a CUA to access and manipulate calendars residing on a 343 Calendar Store. (this memo) 345 Calendar Access Rights (VCAR) - The mechanism for specifying the CAP 346 operations ("PERMISSION") that a particular calendar user ("UPN") 347 is granted or denied permission to perform on a given calendar 348 object ("SCOPE"). The calendar access rights are specified with a 349 "VCAR" component. (Section 9.3. 351 Calendar Address - Also See Calendar URL - they are one in the same 352 for CAP addresses. The calendar address can also be the value to 353 the "ATTENDEE" and "ORGANIZER" properties as defined in [iCAL]. 355 Calendar URL - A calendar URL is a URL defined in this memo that 356 specifies the address of a CS or Calendar. 358 Component- Any object that conforms to the iCalendar object format 359 and that is either defined in an internet draft, registered with 360 IANA, or is an experimental object that is prefixed with "x-". 361 Some types of components include calendars, events, to-dos, 362 journals, alarms, and time zones. A component consists of 363 properties and possibly other contained components. For example, 364 an event may contain an alarm component. 366 Container - This is a generic name for VCALSTORE or VAGENDA. 368 Properties - An attribute of a particular component. Some 369 properties are applicable to different types of components. For 370 example, the "DTSTART" property is applicable to the "VEVENT", 371 "VTODO", and "VJOURNAL" components. Other components are 372 applicable only to an individual type of calendar component. For 373 example, the "TZURL" property may only be applicable to the 374 "VTIMEZONE" components. 376 Calendar Identifier (CalID) - A globally unique identifier 377 associated with a calendar. Calendars reside within a CS. See 378 Qualified Calendar Identifier and Relative Calendar Identifier. 379 All CalIDs start with "cap:". 381 Calendar Policy - A CAP operational restriction on the access or 382 manipulation of a calendar. These may be outside of the scope of 383 the CAP protocol. An example of an implementation or site policy 384 is, "events MUST BE scheduled in unit intervals of one hour". 386 Calendar Property - An attribute of a calendar ("VAGENDA"). The 387 attribute applies to the calendar, as a whole. For example, the 388 "CALSCALE" property specifies the calendar scale (e.g., the 389 "GREGORIAN" value) for the all entries within the calendar. 391 Calendar Store (CS) - The data and service model definition for a 392 Calendar Store as defined in this memo. This memo does not 393 specify how the CS is implemented. 395 Calendar Server - An implementation of a Calendar Store (CS) that 396 manages one or more calendars. 398 Calendar Store Identifier (CSID) - The globally unique identifier 399 for an individual CS. A CSID consists of the host and port 400 portions of a "Common Internet Scheme Syntax" part of a URL, as 401 defined by [URL]. The CSID excludes any reference to a specific 402 calendar. (Section 8.9) 404 Calendar Store Components - Components maintained in a CS specify a 405 grouping of calendar store-wide information. 407 Calendar Store Properties - Properties maintained in a Calendar 408 Store calendar store-wide information. 410 Calendar User (CU) - An entity (often biological) that uses a 411 calendaring system. 413 Calendar User Agent (CUA) - The client application that a CU 414 utilizes to access and manipulate a calendar. 416 CAP Session - An open communication channel between a CUA and a CS. 417 If the CAP session is authenticated, the CU is "authenticated" and 418 it is an "authenticated CAP session". 420 Contained Component / Contained Properties - A component or property 421 that is contained inside of another component. A "VALARM" 422 component for example may be contained inside of a "VEVENT" 423 component. And a "TRIGGER" property could be a contained property 424 of a "VALARM" component. 426 Delegate - A CU (sometimes called the delegatee) who has been 427 assigned participation in a scheduled component (e.g., VEVENT) by 428 one of the attendees in the scheduled component (sometimes called 429 the delegator). An example of a delegate is a team member told to 430 go to a particular meeting in place of another Attendee who is 431 unable to attend. 433 Designate - A CU who is authorized to act on behalf of another CU. 435 An example of a designate is an assistant. 437 Experimental - The CUA and CS may implement experimental extensions 438 to the protocol. They also might have experimental components, 439 properties, and parameters. These extensions MUST start with "x-" 440 (or "X-") and should include a vendor prefix (such as "x-myvendor- 441 "). There is no guarantee that these experimental extensions will 442 interoperate with other implementations. There is no guarantee 443 that they will not interact in unpredictable ways with other 444 vendor experimental extensions. There is no guarantee that the 445 same specific experimental extension is not used my multiple 446 vendors in incompatible ways. Implementations should limit 447 sending those extensions to other implementations. 449 Object - A generic name for any component, property, parameter, or 450 value type to be used in iCalendar. 452 Overlapped Booking - A policy which indicates whether or not 453 components with a "TRANSP" property not set to "TRANSPARENT- 454 NOCONFLICT" or "OPAQUE-NOCONFLICT" value can overlap one another. 455 When the policy is applied to a calendar it indicates whether or 456 not the time span of any component (VEVENT, VTODO, ...) in the 457 calendar can overlap the time span of any other component in the 458 same calendar. When applied to an individual object, it indicates 459 whether or not any other component's time span can overlap that 460 individual component. If the CS does not allow overlapped 461 booking, then the CS is unwilling to allow any overlapped bookings 462 within any calendar in the CS. 464 Owner - One or more CUs or UGs that are listed in the "OWNER" 465 property in a calendar. There can be more than one owner. The " 467 Qualified Calendar Identifier (Qualified CalID) - A CalID in which 468 both the scheme and csid of the CAP URI are present. 470 Realm - A collection of calendar user accounts, identified by a 471 string. The name of the Realm is only used in UPNs. In order to 472 avoid namespace conflict, the Realm SHOULD be postfixed with an 473 appropriate DNS domain name. (e.g., the foobar Realm could be 474 called foobar.example.com). 476 Relative Calendar Identifier (Relative CalID) - An identifier for an 477 individual calendar in a calendar store. It MUST BE unique within 478 a calendar store. A Relative CalID consists of the "URL path" of 479 the "Common Internet Scheme Syntax" portion of a URL, as defined 480 by [URI] and [URLGUIDE]. 482 Session Identity - A UPN associated with a CAP session. A session 483 gains an identity after successful authentication. The identity 484 is used in combination with VCAR to determine access to data in 485 the CS. 487 User Group (UG) - A collection of Calendar Users and/or User Groups. 488 These groups are expanded by the CS and may reside either locally 489 or in an external database or directory. The group membership may 490 be fixed or dynamic over time. 492 Username - A name which denotes a Calendar User within a Realm. 493 This is part of a UPN. 495 User Principal Name (UPN) - A unique identifier that denotes a CU or 496 a group of CU. (Section 6.1.2) 498 2. Additions to iCalendar 500 Several new components, properties, parameters, and value types are 501 added in CAP. This section summarizes those new objects. 503 This memo extends the properties that can go into 'calprops' as 504 defined in [iCAL] section 4.6 page 51 to allow [iTIP] objects 505 transmitted between a CAP aware CUA and the CS to contain the 506 "TARGET" and "CMD" properties. This memo does not address how a CUA 507 transmits [iTIP] or [iMIP] objects to non CAP programs. 509 calprops = 2*( 511 ; 'prodid' and 'version' are both REQUIRED, 512 ; but MUST NOT occur more than once. 513 ; 514 prodid /version / 516 ; These are optional, but MUST NOT occur 517 ; more than once. 518 ; 519 calscale / 520 method / 521 cmd / 523 ; These are optional, and may occur more 524 ; than once. 525 ; 526 target / other-props ) 528 other-props = *(x-prop) *(iana-prop) *(x-prop) 530 iana-prop = ; Any property registered by IANA directly or 531 ; included in an RFC that may be applied to 532 ; the component and within the rules published. 534 x-prop = ; As defined in [iCAL] 536 Another change is that the 'component' part of the 'icalbody' ABNF as 537 described in [iCAL] section 4.6 is optional when sending a command as 538 shown in the following updated ABNF: 540 icalbody = calprops component 542 ; If the "VCALENDAR" component contains the "CMD" 543 ; property then the 'component' is optional: 544 ; 545 / calprops ; Which MUST include a "CMD" property 547 In addition a problem exists with the control of "VALARM" components 548 and their "TRIGGER" properties. A CU may wish to set their own alarm 549 (local alarms) on components. These local alarms are not to be 550 forwarded to other CUs, CUAs, or CSs as are the "SEQUENCE" property 551 and the "ENABLE" parameter. So for the protocol between a CUA and a 552 CS, the following changes apply to the CAP protocol from [iCAL] 553 section 4.6.6 page 67: 555 alarmc = "BEGIN" ":" "VALARM" CRLF 556 alarm-seq 557 other-props 558 (audioprop / dispprop / emailprop / procprop) 559 "END" ":" "VALARM" CRLF 561 alarm-seq = "SEQUENCE" alarmseqparams ":" posint0 CRLF 563 alarmseqparams = other-params [";" local-param] other-params 565 ; Where DIGIT is defined in [iCAL] 566 ; 567 posint0 = 1*DIGIT 568 posint1 = posintfirst 1*DIGIT 570 ; A number starting with 1 through 9. 571 ; 572 posintfirst = %x31-39 574 other-params = *(";" xparam) *(";" iana-params) *(";" xparam) 576 iana-params = ; Any parameter registered by IANA directly or 577 ; included in an RFC that may be applied to 578 ; the property and within the rules published. 580 The CUA adds a "SEQUENCE" property to each "VALARM" component as it 581 books the component. This property along with the "LOCAL" and 582 "ENABLE" parameters allow the CUA to uniquely identify any VALARM in 583 any component. The CUA should remove those before forwarding to non 584 CAP aware CUAs (including [iMIP] CUAs). 586 In addition, if a CUA wished to ignore a "TRIGGER" property in a 587 "VALARM" component that was supplied to it by the "Organizer", the 588 CUA needs a common way to tag that trigger as disabled. So for the 589 protocol between a CUA and a CS, the following is a modification to 590 [iCAL] section 4.8.6.3 page 127: 592 trigger = "TRIGGER" 1*(";" enable-param) (trigrel / trigabs) 594 Section 7.2 and Section 7.5. 596 These additions will be transmitted between a CS and a CAP aware CUA. 597 So the "VERSION" value will remain at "2.0" as no existing [iTIP] or 598 [iMIP] implementation will be effected. 600 2.1 New Value Types (summary) 602 UPN The UPN value type is text value type restricted to only UPN 603 values. (Section 6.1.2) 605 UPN-FILTER Like the UPN value type, but also includes filter rules 606 that allow wildcards. (Section 6.1.3) 608 CALQUERY The "CAL-QUERY" value type is a query syntax that is used by 609 the CUA to specify the rules that apply to a CAP command. 610 (Section 6.1.1) 612 2.1.1 New Parameters (summary) 614 ACTION - The "ACTION" parameter informs the endpoint if it should 615 abort or ask to continue on timeout. (Section 7.1). 617 ENABLE - The "ENABLE" parameter in CAP is used to tag a "TRIGGER" 618 property in a component as disabled or enabled. (Section 7.2). 620 ID - The "ID" parameter specifies a unique identifier to be used for 621 any outstanding commands. 623 LATENCY - The "LATENCY" parameter supplies the timeout value for 624 command completion to the other endpoint. (Section 7.4). 626 LOCAL - The "LOCAL" parameter in CAP is used to tag a "SEQUENCE" 627 property in a "VALARM" component to signify that a VALARM is local 628 or to be distributed. (Section 7.5). 630 LOCALIZE - The "LOCALIZE" parameter specifies the locale to be used 631 in error and warning messages. 633 OPTIONS - The "OPTIONS" parameter passes optional information for 634 the command being sent. 636 SEQUENCE - When the "SEQUENCE" parameter is used in a "VALARM" 637 component it uniquely identifies the instances of the "VALARM" 638 within a component. 640 2.1.2 New Properties (summary) 642 ALLOW-CONFLICT - Some entries in a calendar might not be valid if 643 other entries were allowed to overlap the same time span. 644 (Section 8.1) 646 ATT-COUNTER - When storing a "METHOD" property with the "COUNTER" 647 method, there needs to be a way to remember who sent the COUNTER. 648 (Section 8.2) 650 CAP-VERSIN - The version of CAP the implementation supports. 651 (Section 8.5) 653 CAR-LEVEL - The level of calendar access level supported. (Section 654 8.7) 656 COMPONENTS - The list of components supported. (Section 8.8) 658 CSID - The Calendar Store IDentifier (CSID) uniquely identifies a 659 CAP server. (Section 8.9) 661 CALID - Each calendar within a CS needs to be uniquely identifiable. 662 The "CALID" property identifies a unique calendar within a CS. It 663 can be a full CALID or a relative CALID. (Section 8.3) 665 CALMASTER - The "CALMASTER" property specifies the contact 666 information for the CS. (Section 8.4) 668 CARID - Access rights can be saved and fetched by unique ID - the 669 "CARID" property. (Section 8.6) 671 CMD - The CAP commands, as well as replies are transmitted using the 672 "CMD" property. (Section 10.1) 674 DECREED - Some access rights are not changeable by the CUA. When 675 that is the case, the "DECREED" property value in the "VCAR" 676 component will be TRUE. (Section 8.10) 678 DEFAULT-CHARSET - The list of charsets supported by the CS. The 679 first entry MUST BE the default for the CS. (Section 8.11) 681 DEFAULT-LOCALE - The list of locales supported by the CS. The first 682 entry in the list is the default locale. (Section 8.12) 684 DEFAULT-TZID - This is the list of known timezones supported. The 685 first entry is the default. (Section 8.13) 687 DEFAULT-VCARS - A list of the "CARID" properties that will be used 688 to create new calendars. (Section 8.14) 690 DENY - The UPNs listed in the "DENY" property of a "VCAR" component 691 will denied access as described in the "VRIGHT" component. 692 (Section 8.15) 694 EXPAND - This property tells the CS if the query reply should expand 695 components into multiple instances. The default is FALSE. 696 (Section 8.16) 698 GRANT - The UPNs listed in the "GRANT" property of a "VCAR" 699 component will allowed access as described in the "VRIGHT" 700 component. (Section 8.17) 702 ITIP-VERSION - The version of [iTIP] supported. (Section 8.18) 704 MAXDATE - The maximum date supported by the CS. (Section 8.20) 706 MAX-COMP-SIZE - The largest component size allowed in the 707 implementation including attachments. (Section 8.19) 709 MINDATE - The minimum date supported by the CS. (Section 8.21) 711 MULTIPART - Passed in the capability messages to indicate which MIME 712 multipart types the sender supports. (Section 8.22) 714 NAME - The "NAME" property is used to add locale specific 715 descriptions into components. (Section 8.23) 717 OWNER - Each calendar has at least one "OWNER" property. (xref 718 target="OWNER"/>) Related to the "CAL-OWNERS()" (Section 6.1.1.1) 719 query clause. 721 PERMISSION - This property specifies the permission being granted or 722 denied. Examples are the "SEARCH" and "MODIFY" values. (Section 723 8.25) 725 QUERY - Used to hold the CAL-QUERY (Section 8.26) for the component. 727 QUERYID - A unique id for a stored query. (Section 8.27) 729 QUERY-LEVEL - The level of the query language supported. (Section 730 8.29) 732 RECUR-ACCEPTED - If the implementation support recurrence rules. 733 (Section 8.30) 735 RECUR-EXPAND - If the implementation support expanding recurrence 736 rules. (Section 8.32) 738 RECUR-LIMIT - Any maximum limit on the number of instances the 739 implementation will expand recurring objects. (Section 8.31) 741 REQUEST-STATUS - The [iCAL] "REQUEST-STATUS" property is extended to 742 include new error numbers. (Section 8.28) 744 RESTRICTION - In the final check when granting calendar access 745 requests, the CS test the results to the value of the 746 "RESTRICTION" property in the corresponding "VRIGHT" component to 747 determine if the access meets that restriction. (Section 8.33) 749 SCOPE - The "SCOPE" property is used in "VRIGHT"s component to 750 select the subset of data that may be acted upon when checking 751 access rights. (Section 8.34) 753 STORES-EXPANDED - Specifies if the implementation stores recurring 754 object expanded or not. (Section 8.35) 756 TARGET - The new "VCALENDAR" component property "TARGET" (Section 757 8.36) is used to specify which calendar(s) will be the subject of 758 the CAP command. 760 TRANSP - This is a modification the [iCAL] "TRANSP" property and it 761 allows more values. The new values are related to conflict 762 control. (Section 8.37) 764 2.1.3 New Components (summary) 766 VAGENDA - CAP allows the fetching and storing of the entire contents 767 of a calendar. The "VCALENDAR" component is not sufficient to 768 encapsulate all of the needed data that describes a calendar. The 769 "VAGENDA" component is the encapsulating object for an entire 770 calendar. (Section 9.1) 772 VCALSTORE - Each CS contains one or more calendars (VAGENDAs), the 773 "VCALSTORE" component is the encapsulating object that can hold 774 all of the "VAGENDA" components along with any components and 775 properties that are unique to the store level. (Section 9.2) 777 VCAR - Calendar Access Rights are specified and encapsulated in the 778 new iCalendar "VCAR" component. The "VCAR" component holds some 779 new properties and at least one "VRIGHT" component. (Section 9.3) 781 VRIGHT - This component encapsulates a set of instructions to the CS 782 that define the rights or restrictions needed. (Section 9.4) 784 VREPLY - This component encapsulates a set of data that can consist 785 of an arbitrary amounts of properties and components. Its 786 contents is dependent on the command that was issued. (Section 787 9.5) 789 VQUERY - The search operation makes use of a new component, called 790 "VQUERY" and a new value type "CAL-QUERY" (Section 6.1.1). The 791 "VQUERY" component is used to fetch objects from the CS. (Section 792 9.6) 794 2.2 Relationship of RFC-2446 (ITIP) and CAP 796 [iTIP] describes scheduling methods which result in indirect 797 manipulation of components. In CAP, the "CREATE" command is used to 798 deposit entities into the store. Other CAP commands such as 799 "DELETE", "MODIFY" and "MOVE" command values provide direct 800 manipulation of components. In the CAP calendar store model, 801 scheduling messages are conceptually kept separate from other 802 components by their state. 804 All scheduling operations and are as define in [iTIP]. This memo 805 makes no changes to any of the workflow described in [iTIP]. In this 806 memo referring to the presence of the "METHOD" property in an object 807 is the same as saying an [iTIP] object. 809 A CUA may create a "BOOKED" state object by depositing an iCalendar 810 object into the store. This is done by depositing an object that 811 does not have a "METHOD" property. The CS then knows to set the 812 state of the object to the "BOOKED" state. If the object has a 813 "METHOD" property then the object is stored in the "UNPROCESSED" 814 state. 816 If existing "UNPROCESSED" state objects exist in the CS for the same 817 UID then a CUA may wish to consolidate the objects in to one "BOOKED" 818 state object. The CUA would fetch the "UNPROCESSED" state objects 819 for that UID and process them in the CUA as described in [iTIP]. 820 Then if the CUA wished to book the UID, the CUA would issue a 821 "CREATE" command to create the new "BOOKED" state object in the CS, 822 followed by a "DELETE" command to remove any related old [iTIP] 823 objects from the CS. And it might also involve having the CUA send 824 some [iMIP] objects or contacting other CS's and performing CAP 825 operations on those CSs. 827 The CUA could also decide not to book the object. In which case the 828 "UNPROCESSED" state objects could be removed from the CS or the CUA 829 could set those object to the marked for delete state. The CUA could 830 also ignore objects for later processing. 832 The marked for delete state is used to keep the object around so that 833 the CUA can process duplicate requests automatically. If a duplicate 834 [iTIP] object is deposited into the CS and there exists identical 835 marked for delete objects, then a CUA acting on behalf of the "OWNER" 836 can silently drop those duplicate entries. 838 Another purpose for the marked for delete state is so that when a CU 839 decides they do not wish to have the object show in their calendar, 840 the CUA can book the object; changing the "PARTSTAT" parameter to 841 "DECLINED" in the "ATTENDEE" property that corresponds to their UPN. 842 Perform an [iTIP] processing such as sending back a decline. Then 843 mark that object as marked for delete. Their CUA might be 844 configurable to automatically drop any updates for that object 845 knowing the CU has already declined. 847 When synchronizing with multiple CUAs, the marked for delete state 848 could be used to inform the synchronization process that an object is 849 to be deleted. How synchronization is done is not specified in this 850 memo. 852 Several "UNPROCESSED" state entries can be in the CS for the same 853 UID. However once consolidated, then only one object exists in the 854 CS and that is the booked object. The others MUST BE removed, or 855 have their state changed to "DELETED". 857 There MUST NOT BE more than one "BOOKED" state object in a calendar 858 for the same "UID". The "ADD" method value may create multiple 859 objects all in the "BOOKED" state for the same UID, however for the 860 purpose of this memo, they are the same object that simply have 861 multiple "VCALENDAR" components. 863 For example, if you were on vacation, you could have receive a 864 "REQUEST" method to attend a meeting and several updates to that 865 meeting. Your CUA would have to issue "SEARCH" commands to find them 866 in the CS using CAP, process them, determine what the final state of 867 the object from a possible combination of user input and programmed 868 logic. Then the CUA would instruct the CS to create a new booked 869 object from the consolidated results. Finally, the CUA could do a 870 "DELETE" command to remove the related "UNPROCESSED" state objects. 871 See [iTIP] for details on resolving multiple [iTIP] scheduling 872 entries. 874 3. CAP Design 876 3.1 System Model 878 The system model describes the high level components of a calendar 879 system and how they interact with each other. 881 CAP is used by a CUA to send commands to and receive responses from a 882 CS. 884 The CUA prepares a [MIME] encapsulated command, sends it to the CS, 885 and receives a [MIME] encapsulated response. The calendaring related 886 information within these messages are represented by iCalendar 887 objects. In addition the "GET-CAPABILITY" command can be sent from 888 the CS to the CUA. 890 There are two distinct protocols in operation to accomplish this 891 exchange. [BEEP] is the transport protocol is used to move these 892 encapsulations between a CUA and a CS. CAP's [BEEP] profile defines 893 the application protocol where the content and semantics of the 894 messages sent between the CUA and the CS are specified. 896 3.2 Calendar Store Object Model 898 [iCAL] describes components such as events, todos, alarms, and 899 timezones. [CAP] requires additional object infrastructure. In 900 particular, detailed definitions of the containers for events and 901 todos (calendars), access control objects, and a query language. 903 The conceptual model for a calendar store is shown below. The 904 calendar store (VCALSTORE - Section 9.2) contains "VCAR"s, "VQUERY"s, 905 "VTIMEZONE"s, "VAGENDA"s and calendar store properties. 907 Calendars (VAGENDAs) contain "VEVENT"s, "VTODO"s, "VJOURNAL"s, 908 "VCAR"s, "VTIMEZONE"s, "VFREEBUSY", "VQUERY"s and calendar 909 properties. 911 The component "VCALSTORE" is used to denote the a root of the 912 calendar store and contains all of the calendars. 914 Calendar Store 916 VCALSTORE 917 | 918 +-- properties 919 +-- VCARs 920 +-- VQUERYs 921 +-- VTIMEZONEs 922 +-- VAGENDA 923 | | 924 | +--properties 925 | +--VEVENTs 926 | | | 927 | | +--VALARMs 928 | +--VTODOs 929 | | | 930 | | +--VALARMs 931 | +--VJOURNALs 932 | +--VCARs 933 | +--VTIMEZONEs 934 | +--VQUERYs 935 | +--VFREEBUSYs 936 | | 937 | | ... 938 . 939 . 940 +-- VAGENDA 941 . . 942 . . 943 . . 945 Calendars within a Calendar Store are identified by their unique 946 Relative CALID. 948 3.3 Protocol Model 950 CAP uses beep as the transport and authentication protocol. 952 The initial charset MUST BE UTF-8 for the session in an unknown 953 locale. If the CS supplied the [BEEP] 'localize' attribute in the 954 [BEEP] 'greeting' then the CUA may tell the CS to switch locales for 955 the session by issuing the "SET-LOCALE" CAP command and supplying one 956 of the locales supplied by the [BEEP] 'localize' attribute. If 957 supplied the first locale supplied in the [BEEP] 'localize' attribute 958 MUST BE the default locale of the CS. The locale is switched only 959 after a successful reply. 961 The "DEFAULT-CHARSET" property of the CS contains the list of 962 charsets supported by the CS with the first value being the default 963 for new calendars. If the CUA wishes to switch to one of those 964 charsets for the session, the CUA issues the "SET-LOCALE" command. 965 The CUA would have to first perform a "GET-CAPABILITY" command on the 966 CS to get the list of charsets supported by the CS. The charset is 967 switched only after a successful reply. 969 The CUA may switch locales and charsets as needed. There is no 970 requirement that a CS support multiple locales or charsets. 972 3.3.1 Use of BEEP, MIME and iCalendar 974 CAP uses the [BEEP] application protocol over TCP. (refer to [BEEP] 975 and [BEEPTCP] for more information). The default port that the CS 976 listens for connections is on user port 1026. 978 The [BEEP] data exchanged in CAP is a iCalendar MIME content that 979 fully conforms to [iCAL] iCalendar format. 981 This example tells the CS to generate and return 10 UIDs to be used 982 by the CUA. Note throughout this memo, 'C:' refers to what the CUA 983 sends, 'S:' refers to what the CS sends, 'I:' refers to what the 984 initiator sends, and 'L:' refers to what the listener sends. Where 985 initiator and listener are used as defined in [BEEP]. 987 C: MSG 1 2 . 432 62 988 C: Content-Type: text/calendar 989 C: 990 C: BEGIN:VCALENDAR 991 C: VERSION:2.0 992 C: PRODID:-//someone's prodid 993 C: CMD;ID=unique-per-cua-123;OPTIONS=10:GENERATE-UID 994 C: END:VCALENDAR 996 NOTE: The following examples will not include the [BEEP] header and 997 footer information. Only the iCalendar objects that are sent between 998 the CUA and CS will be shown as the [BEEP] payload boundaries are 999 independent of CAP. 1001 The commands listed below are used to manipulate or access the data 1002 on the calendar store: 1004 ABORT - Sent to halt the processing of some of the commands. 1005 (Section 10.1.2) 1007 CONTINUE - Sent to continue processing a command that has had its 1008 specified timeout time reached. (Section 10.1.3) 1010 CREATE - Create a new object on the CS. This can be implied for 1011 [iTIP] objects. Initiated by the CUA only. (Section 10.1.4) 1013 SET-LOCALE - Tell the CS to use any named locale and charset 1014 supplied. Initiated by the CUA only. (Section 10.9) 1016 DELETE - Delete objects from the CS. Initiated by the CUA only. 1017 Can also be used to mark an object for deletion. (Section 10.1.5) 1019 GENERATE-UID - Generate one or more unique ids. Initiated by the 1020 CUA only. (Section 10.2) 1022 GET-CAPABILITY - Query the capabilities the other end point of the 1023 session. (Section 10.3) 1025 IDENTIFY - Set a new identity for the session. Initiated by the CUA 1026 only. (Section 10.4) 1028 MODIFY - Modify components. Initiated by the CUA only. (Section 1029 10.5) 1031 MOVE - Move components to another container. Initiated by the CUA 1032 only. (Section 10.6) 1034 REPLY - When replying to a command, the "CMD" value will be set to 1035 "REPLY" so that it will not be confused with a new command. 1036 (Section 10.7) 1038 SEARCH - Search for components. Initiated by the CUA only. 1039 (Section 10.8) 1041 TIMEOUT - Sent when a specified amount of time has lapsed and a 1042 command has not finished. (Section 10.10) 1044 4. Security Model 1046 The [BEEP] transport performs all session authentication. 1048 4.1 Calendar User and UPNs 1050 A CU is an entity that can be authenticated. It is represented in 1051 CAP as a UPN, which is a key part of access rights. The UPN 1052 representation is independent of the authentication mechanism used 1053 during a particular CUA/CS interaction. This is because UPNs are 1054 used within VCARs. If the UPN were dependent on the authentication 1055 mechanism, a VCAR could not be consistently evaluated. A CU may use 1056 one mechanism while using one CUA but the same CU may use a different 1057 authentication mechanism when using a different CUA, or while 1058 connecting from a different location. 1060 The user may also have multiple UPNs for various purposes. 1062 Note that the immutability of the user's UPN may be achieved by using 1063 SASL's authorization identity feature. (The transmitted 1064 authorization identity may be different than the identity in the 1065 client's authentication credentials.) [SASL, section 3]. This also 1066 permits a CU to authenticate using their own credentials, yet request 1067 the access privileges of the identity for which they are proxying 1068 SASL. Also, the form of authentication identity supplied by a 1069 service like TLS may not correspond to the UPNs used to express a 1070 server's access rights, requiring a server specific mapping to be 1071 done. The method by which a server determines a UPN, based on the 1072 authentication credentials supplied by a client, is implementation 1073 specific. See [BEEP] for authentication details; [BEEP] relies on 1074 SASL. 1076 4.1.1 UPNs and Certificates 1078 When using X.509 certificates for purposes of CAP authentication, the 1079 UPN should appear in the certificate. Unfortunately there is no 1080 single correct guideline for which field should contain the UPN. 1082 From RFC-2459, section 4.1.2.6 (Subject): 1084 If subject naming information is present only in the subjectAlt- 1085 Name extension (e.g., a key bound only to an email address or 1086 URI), then the subject name MUST be an empty sequence and the 1087 subjectAltName extension MUST BE critical. 1089 Implementations of this specification MAY use these comparison 1090 rules to process unfamiliar attribute types (i.e., for name 1091 chaining). This allows implementations to process certificates 1092 with unfamiliar attributes in the subject name. 1094 In addition, legacy implementations exist where an RFC 822 name is 1095 embedded in the subject distinguished name as an EmailAddress 1096 attribute. The attribute value for EmailAddress is of type 1097 IA5String to permit inclusion of the character '@', which is not 1098 part of the PrintableString character set. EmailAddress attribute 1099 values are not case sensitive (e.g., "fanfeedback@redsox.com" is 1100 the same as "FANFEEDBACK@REDSOX.COM"). 1102 Conforming implementations generating new certificates with 1103 electronic mail addresses MUST use the rfc822Name in the subject 1104 alternative name field (see sec. 4.2.1.7 of [X509CRL]) to 1105 describe such identities. Simultaneous inclusion of the 1106 EmailAddress attribute in the subject distinguished name to 1107 support legacy implementations is deprecated but permitted. 1109 Since no single method of including the UPN in the certificate will 1110 work in all cases, CAP implementations MUST support the ability to 1111 configure what the mapping will be by the CS administrator. 1112 Implementations MAY support multiple mapping definitions, for 1113 example, the UPN may be found in either the subject alternative name 1114 field, or the UPN may be embedded in the subject distinguished name 1115 as an EmailAddress attribute. 1117 Note: If a CS or CUA is validating data received via [iMIP], if the 1118 "ORGANIZER" or "ATTENDEE" properties said (e.g.) "ATTENDEE;CN=Joe 1119 Random User:MAILTO:juser@example.com" then the email address should 1120 be checked against the UPN. This is so the "ATTENDEE" property 1121 cannot be changed to something misleading like "ATTENDEE;CN=Joe 1122 Rictus User:MAILTO:jrictus@example.com" and have it pass validation. 1123 Note that it is the email addresses that miscompare, the CN 1124 miscompare is irrelevant. 1126 4.1.2 Anonymous Users and Authentication 1128 Anonymous access is often desirable. For example an organization may 1129 publish calendar information that does not require any access control 1130 for viewing or login. Conversely, a user may wish to view 1131 unrestricted calendar information without revealing their identity. 1133 4.1.3 User Groups 1135 A User Group is used to represent a collection of CUs or other UGs 1136 that can be referenced in VCARs. A UG is represented in CAP as a 1137 UPN. The CUA cannot distinguish between a UPN that represents a CU 1138 or a UG. 1140 UGs are expanded as necessary by the CS. The CS MAY expand a UG 1141 (including nested UGs) to obtain a list of unique CUs. Duplicate 1142 UPNs are filtered during expansion. 1144 How the UG expansion is maintained across commands is implementation 1145 specific. A UG may reference a static list of members, or it may 1146 represent a dynamic list. Operations SHOULD recognize changes to UG 1147 membership. 1149 CAP does not define commands or methods for managing UGs. 1151 4.2 Access Rights 1153 Access rights are used to grant or deny access to calendars, 1154 components, properties, and parameters in a CS to a CU. CAP defines 1155 a new component type called a Calendar Access Right (VCAR). 1156 Specifically, a "VCAR" component grants, or denies, UPNs the right to 1157 search and write components, properties, and parameters on calendars 1158 within a CS. 1160 The "VCAR" component model does not put any restriction on the 1161 sequence in which the object and access rights are created. That is, 1162 an object associated with a particular "VCAR" component might be 1163 created before or after the actual "VCAR" component is defined. In 1164 addition, the "VCAR" and "VEVENT" components might be created in the 1165 same iCalendar object and passed together in a single object. 1167 All rights MUST BE denied unless specifically granted. 1169 If two rights specified in "VCAR" components are in conflict, the 1170 right that denies access always takes precedence over the right that 1171 grants access. Any attempt to create a "VCAR" component that 1172 conflicts with an immutable "VCAR" components must fail. 1174 4.2.1 Access Control and NOCONFLICT 1176 The "TRANSP" property can take on values "TRANSPARENT-NOCONFLICT" and 1177 "OPAQUE-NOCONFLICT" that prohibit other components from overlapping 1178 it. This setting overrides access. The "ALLOW-CONFLICT" CS, 1179 Calendar or component setting may also prevent overlap, returning an 1180 error code "6.3". 1182 4.2.2 Predefined VCARs 1184 Predefined calendar access CARIDs that MUST BE implemented are: 1186 CARID:READBUSYTIMEINFO - Specifies the "GRANT" and "DENY" rules that 1187 allow UPNs to search "VFREEBUSY" components. An example 1188 definition for this VCAR is: 1190 BEGIN:VCAR 1191 CARID:READBUSYTIMEINFO 1192 BEGIN:VRIGHT 1193 GRANT:* 1194 PERMISSION:SEARCH 1195 SCOPE:SELECT * FROM VFREEBUSY 1196 END:VRIGHT 1197 END:VCAR 1199 CARID:REQUESTONLY - Specifies the "GRANT" and "DENY" rules to UPNs 1200 other than the owner of the calendar the ability to write new 1201 objects with the property "METHOD" property set to the "REQUEST" 1202 value. This CARID allows the owner to specify which UPNs are 1203 allowed to make scheduling requests. An example definition for 1204 this VCAR is: 1206 BEGIN:VCAR 1207 CARID:REQUESTONLY 1208 BEGIN:VRIGHT 1209 GRANT:NON CAL-OWNERS() 1210 PERMISSION:CREATE 1211 RESTRICTION:SELECT VEVENT FROM VAGENDA WHERE METHOD = 'REQUEST' 1212 RESTRICTION:SELECT VTODO FROM VAGENDA WHERE METHOD = 'REQUEST' 1213 RESTRICTION:SELECT VJOURNAL FROM VAGENDA WHERE METHOD = 'REQUEST' 1214 END:VRIGHT 1215 END:VCAR 1217 CARID:UPDATEPARTSTATUS - Grants to authenticated users the right to 1218 modify the instances of the "ATTENDEE" property set to one of 1219 their calendar addresses in any components for any booked 1220 component containing an "ATTENDEE" property. This allows (or 1221 denies) a CU the ability to update their own participation status 1222 in a calendar where they might not otherwise have "MODIFY" command 1223 access. They are not allowed to change the "ATTENDEE" property 1224 value. An example definition for this VCAR is (This example only 1225 affects the "VEVENT" components): 1227 BEGIN:VCAR 1228 CARID:UPDATEPARTSTATUS 1229 BEGIN:VRIGHT 1230 GRANT:* 1231 PERMISSION:MODIFY 1232 SCOPE:SELECT ATTENDEE FROM VEVENT 1233 WHERE ATTENDEE = SELF() 1234 AND ORGANIZER = CURRENT-TARGET() 1235 AND STATE() = 'BOOKED' 1236 RESTRICTION:SELECT * FROM VEVENT 1237 WHERE ATTENDEE = SELF() 1238 END:VRIGHT 1239 END:VCAR 1241 CARID:DEFAULTOWNER - Grants to any owner the permission they have 1242 for the target. An example definition for this VCAR is: 1244 BEGIN:VCAR 1245 CARID:DEFAULTOWNER 1246 BEGIN:VRIGHT 1247 GRANT:CAL-OWNERS() 1248 PERMISSION:* 1249 SCOPE:SELECT * FROM VAGENDA 1250 END:VRIGHT 1251 END:VCAR 1253 4.2.3 Decreed VCARs 1255 A CS MAY choose to implement and allow persistent immutable VCARs 1256 that may be configured by the CS administrator. A reply from the CS 1257 may dynamically create "VCAR" components that are decreed depending 1258 on the implementation. To the CUA any "VCAR" component with the 1259 "DECREED" property set to "TRUE" can not be changed by the currently 1260 authenticated UPN, and depending on the implementation and other 1261 "VCAR" components; might not be able to be changed by any UPN using 1262 CAP, and never when the CUA gets a "DECREED:TRUE" VCAR. 1264 When a user attempts to modify or override a decreed "VCAR" component 1265 rules an error will be returned indicating that the user has 1266 insufficient authorization to perform the operation. The reply to 1267 the CUA MUST BE the same as if a non-decreed VCAR caused the failure. 1269 The CAP protocol does not define the semantics used to initially 1270 create a decreed VCAR. This administrative task is outside the scope 1271 of the CAP protocol. 1273 For example; an implementation or a CS administrator may wish to 1274 define a VCAR that will always allow the calendar owners to have full 1275 access to their own calendars. 1277 Decreed "VCAR" components MUST BE readable by the calendar owner in 1278 standard "VCAR" component format. 1280 4.3 CAP Session Identity 1282 A [BEEP] session has an associated set of authentication credentials, 1283 from which is derived a UPN. This UPN is the identity of the CAP 1284 session, and is used to determine access rights for the session. 1286 The CUA may change the identity of a CAP session by calling the 1287 "IDENTIFY" command. The CS only permits the operation if the 1288 session's authentication credentials are good for the requested 1289 identity. The method of checking this permission is implementation 1290 dependent, but may be thought of as a mapping from authentication 1291 credentials to UPNs. The "IDENTIFY" command allows a single set of 1292 authentication credentials to choose from multiple identities, and 1293 allows multiple sets of authentication credentials to assume the same 1294 identity. 1296 For anonymous access the identity of the session is "@". A UPN with 1297 a null Username and null Realm is anonymous. A UPN with a null 1298 Username, but non-null Realm, such as "@foo.com" may be used to mean 1299 any identity from that Realm, which is useful to grant access rights 1300 to all users in a given Realm. A UPN with a non-null Username and 1301 null Realm, such as "bob@" could be a security risk and MUST NOT be 1302 used. 1304 Since the UPN includes Realm information it may be used to govern 1305 calendar store access rights across Realms. However, governing 1306 access rights across Realms is only useful if login access is 1307 available. This could be done through a trusted server relationship 1308 or a temporary account. Note that trusted server relationships are 1309 outside the scope of [CAP]. 1311 The "IDENTIFY" command also provides for a weak group implementation. 1312 By allowing multiple sets of authentication credentials belonging to 1313 different users to identify as the same UPN, that UPN essentially 1314 identifies a group of people, and may be used for group calendar 1315 ownership, or the granting of access rights to a group. 1317 5. CAP URL and Calendar Address 1319 The CAP URL scheme is used to designate calendar stores and calendars 1320 accessible using the CAP protocol. 1322 The CAP URL scheme conform to the generic URL syntax, defined in RFC 1323 2396, and follows the Guidelines for URL Schemes, set forth in RFC 1324 2718. 1326 A CAP URL begins with the protocol prefix "cap" and is defined by the 1327 following grammar. 1329 capurl = "cap://" csid [ "/" relcalid ] 1330 csid = hostport ; As defined in Section 3.2.2 of RFC 2396 1331 relcalid = *uric ; As defined in Section 2 of RFC 2396 1333 A 'relcalid' is an identifier that uniquely identifies a calendar on 1334 a particular calendar store. There is no implied structure in a 1335 Relative CALID. It may refer to the calendar of a user or of a 1336 resource such as a conference room. It MUST BE unique within the 1337 calendar store. 1339 Examples: 1341 cap://cal.example.com 1342 cap://cal.example.com/Company/Holidays 1343 cap://cal.example.com/abcd1234Usr 1345 Relative CAP URLs are permitted and are resolved according to the 1346 rules defined in Section 5 of RFC 2396. 1348 Examples of valid relative CAP URLs: 1350 opqaueXzz123String 1351 UserName/Personal 1353 A Calendar addresses can be described as qualified or relative CAP 1354 URLs. 1356 For a user currently authenticated to the CS on cal.example.com, 1357 these two example calendar addresses refer to the same calendar: 1359 cap://cal.example.com/abcd1234USR 1360 abcd1234USR 1362 6. New Value Types 1364 The following sections contains new components, properties, 1365 parameters, and value definitions. 1367 The purpose of these is to extend the iCalendar objects in a 1368 compatible way so that existing iCalendar "VERSION" property "2.0" 1369 value parsers can still parse the objects without modification. 1371 6.1 Property Value Data Types 1373 6.1.1 CAL-QUERY Value Type 1375 Subject: Registration of text/calendar MIME value type CAL-QUERY 1377 Value Name: CAL-QUERY 1379 Value Type Purpose: This value type is used to identify values and 1380 contains query statements targeted at locating those values. 1382 This is based on [SQL92] and [SQLCOM]. 1384 1. For the purpose of a query, all components should be handled as 1385 tables, and the properties of those components, should be handled 1386 as columns. 1388 2. All VAGENDAs and CS's look like tables for the purpose of a 1389 QUERY. And all of their properties look like columns in those 1390 tables. 1392 3. You CAN NOT do any cross component-type joins. And that means 1393 you can ONLY have one component, OR one "VAGENDA" component OR 1394 one "VCALSTORE" component in the "FROM" clause. 1396 4. Everything in the "SELECT" clause and "WHERE" clauses in MUST BE 1397 from the same component type, or "VAGENDA" component OR 1398 "VCALSTORE" component in the "FROM" clause. 1400 5. When multiple "QUERY" properties are supplied in a single 1401 "VQUERY" component, the results returned are the same as the 1402 results returned for multiple "VQUERY" components having each a 1403 single "QUERY" property. 1405 6. The '.' is used to separate the table name (component) and column 1406 name (property or component) when selecting a property that is 1407 contained inside of a component that is targeted in the TARGET 1408 property. 1410 7. A contained component without a '.' is not the same as 1411 "component-name.*". If given as "component-name" (no dot) the 1412 encapsulating BEGIN/END statement will be supplied for 1413 "component-name".: 1415 In this example the '.' is used to separate the "TRIGGER" property 1416 from its contained component (VALARM). Which is contained in any 1417 "VEVENT" component in the selected "TARGET" property value (a 1418 relcalid). All "TRIGGER" properties in any "VEVENT" component in 1419 relcalid would be returned. 1421 TARGET:relcalid 1422 QUERY:SELECT VALARM.TRIGGER FROM VEVENT 1424 SELECT VALARM FROM VEVENT WHERE UID = "123" 1426 This return one BEGIN/END "VALARM" component for each 1427 "VALARM" component in the matching "VEVENT" component. 1428 As there is no '.' (dot) in the VALARM after the SELECT above: 1430 BEGIN:VALARM 1431 TRIGGER;RELATED=END:PT5M 1432 REPEAT:4 1433 ... 1434 END:VALARM 1435 BEGIN:VALARM 1436 TRIGGER;RELATED=START:PT5M 1437 DURATION:PT10M 1438 ... 1439 END:VALARM 1440 ... 1441 ... 1443 If provided as "component-name.*", then only the properties and any 1444 contained components will be returned: 1446 SELECT VALARM.* FROM VEVENT WHERE UID = "123" 1448 Will return all of the properties in each "VALARM" component 1449 in the matching "VEVENT" component: 1451 TRIGGER;RELATED=END:PT5M 1452 REPEAT:4 1453 ... 1454 TRIGGER;RELATED=START:PT5M 1455 DURATION:PT10M 1456 ... 1457 ... 1459 (a) SELECT FROM VEVENT 1461 (b) SELECT VALARM FROM VEVENT 1463 (c) SELECT VALARM.* FROM VEVENT 1465 (d) SELECT * FROM VEVENT 1467 (e) SELECT * FROM VEVENT WHERE 1468 VALARM.TRIGGER < '20020201T000000Z' 1469 AND VALARM.TRIGGER > '20020101T000000Z' 1471 Note: 1472 (a) Selects all instances of 1473 from all "VEVENT" components. 1475 (b) and (c) Select all "VALARM" components from all 1476 "VEVENT" components. (b) would return then in 1477 BEGIN/END VALARM tags. (c) would return all 1478 of the properties without BEGIN/END VALARM tags. 1480 (d) Selects every property and every component 1481 that is in any "VEVENT" component. 1483 (e) Selects all properties and all contained 1484 components in all "VEVENT" components that have a "VALARM" 1485 component with a "TRIGGER" property value between 1486 the provided dates and times. 1488 NOT VALID: 1490 (f) SELECT VEVENT.VALARM.TRIGGER FROM VEVENT 1491 (g) SELECT DTSTART,UID FROM VEVENT WHERE 1492 VTODO.SUMMERY = "Fix typo in CAP" 1494 Note: (f) Is NOT valid because it contains 1495 two '.' characters in the "SELECT" clause. 1497 (g) Is NOT valid because it mixes VEVENT 1498 and VTODO properties in the same VQUERY. 1500 Formal Definition: The value type is defined by the following 1501 notation: 1503 cal-query = "SELECT" SP cap-val SP 1504 "FROM" SP comp-name SP 1505 "WHERE" SP cap-expr 1507 / "SELECT" SP cap-cols SP 1508 "FROM" SP comp-name 1510 cap-val = cap-cols / param 1511 / ( cap-val "," cap-val ) 1513 ; NOTE: there is NO space around the "," on 1514 ; the next line 1515 cap-cols = cap-col / ( cap-cols "," cap-col) 1516 / "*" 1518 ; A 'cap-col' is: 1519 ; 1520 ; Any property name ('cap-prop') found in the component 1521 ; named in the 'comp-name' used in the "FROM" clause. 1522 ; 1523 ; SELECT ORGANIZER FROM VEVENT ... 1524 ; 1525 ; OR 1526 ; 1527 ; A component name ('comp-name') of an existing component 1528 ; contained inside of the 'comp-name' used in the "FROM" 1529 ; clause. 1530 ; 1531 ; SELECT VALARM FROM VEVENT ... 1532 ; 1533 ; OR 1534 ; 1535 ; A component name ('comp-name') of an existing 1536 ; component contained inside of the 'comp-name' used 1537 ; in the "FROM" clause followed by a property 1538 ; name ('cap-prop') to be selected from that component. 1539 ; (comp-name "." cap-prop) 1540 ; 1541 ; SELECT VALARM.TRIGGER FROM VEVENT ... 1543 cap-col = comp-name 1544 / comp-name "." cap-prop 1546 comp-name = "VEVENT" / "VTODO" / "VJOURNAL" / "VFREEBUSY" 1547 / "VALARM" / "DAYLIGHT" / "STANDARD" / "VAGENDA" 1548 / "VCAR" / "VCALSTORE" / "VQUERY" / "VTIMEZONE" 1549 / x-comp / iana-comp 1551 cap-prop = ; A property that may be in the 'cap-comp' named 1552 ; in the "SELECT" clause. 1554 cap-expr = "(" cap-expr ")" 1555 / cap-term 1557 cap-term = cap-expr SP cap-logical SP cap-expr 1558 / cap-factor 1560 cap-logical= "AND" / "OR" 1562 cap-factor = cap-colval SP cap-oper SP col-value 1563 / cap-colval SP "NOT LIKE" SP col-value 1564 / cap-colval SP "LIKE" SP col-value 1565 / cap-colval SP "IS NULL" 1566 / cap-colval SP "IS NOT NULL" 1567 / col-value SP "NOT IN" cap-colval" 1568 / col-value SP "IN" cap-colval" 1569 / "STATE()" "=" ( "BOOKED" 1570 / "UNPROCESSED" 1571 / "DELETED" ) 1573 cap-colval = cap-col / param 1575 param = "PARAM(" cap-col "," cap-param ")" 1577 cap-param = ; Any parameter that may be contained in the cap-col 1578 ; in the supplied PARAM() function 1580 col-value = col-literal 1581 / "SELF()" 1582 / "CAL-OWNERS()" 1583 / "CAL-OWNERS(" cal-address ")" 1584 / "CURRENT-TARGET()" 1586 cal-address = ; A CALID as define by CAP 1588 col-literal = "'" literal-data "'" 1590 literal-data = ; Any data that matches the value type of the 1591 ; column that is being compared. That is you can 1592 ; not compare PRIORITY to "some string" because 1593 ; PRIORITY has a value type of integer. If it is 1594 ; not preceded by the LIKE element, any '%' and '_' 1595 ; characters in the literal data are not treated as 1596 ; wildcard characters and do not have to be backslash 1597 ; escaped. 1598 ; 1599 ; OR 1600 ; 1601 ; If the literal-data is preceded by the LIKE 1602 ; element it may also contain the '%' and '_' 1603 ; wildcard characters. And if the literal data 1604 ; that is comparing contains any '%' or '_' 1605 ; characters, they MUST BE backslash escaped as 1606 ; described in the notes below in order for them not 1607 ; to be treated as wildcard characters. 1609 cap-oper = "=" 1610 / "!=" 1611 / "<" 1612 / ">" 1613 / "<=" 1614 / ">=" 1616 SP = ; A single white space ASCII character 1617 ; (value in HEX %x20). 1619 x-comp = ; As defined in [iCAL] section 4.6 1621 iana-comp = ; As defined in [iCAL] section 4.6 1623 6.1.1.1 [NOT] CAL-OWNERS() 1625 This function returns the list of "OWNER" properties for the named 1626 calendar when used in the "SELECT" clause. 1628 If called as 'CAL-OWNERS()', it is equivalent to the comma separated 1629 list of all of the owners of the calendar that match the provided 1630 "TARGET" property value. If the target is a "VCALSTORE", it returns 1631 the "CALMASTER" property. 1633 If called as 'CAL-OWNERS(cal-address)', then it is the equivalent to 1634 the comma separated list of owners for the named calendar id. If 1635 'cal-address' is a CS, it returns the "CALMASTER" property. 1637 If used in the in the "WHERE" clause it then returns true if the 1638 currently authenticated UPN is an owner of the currently selected 1639 object matched in the provided "TARGET" property. Used in a CAL- 1640 QUERY "WHERE" clause and in the UPN-FILTER. 1642 6.1.1.2 CURRENT-TARGET() 1644 Is equivalent to the value of the "TARGET" property in the current 1645 command. Used in a CAL-QUERY "WHERE" clause. 1647 6.1.1.3 PARAM() 1649 Used in a CAL-QUERY. Returns the value of the named parameter from 1650 the named property. If there are multiple properties in the object, 1651 then PARAM() returns a comma separated list of parameter values. If 1652 needed each value can be quoted or contain backslash escaped 1653 contents. 1655 When used in a "SELECT" clause, it returns the entire property and 1656 all of that properties parameters (the result is not limited to the 1657 supplied parameter). If the property does not contain the named 1658 parameter, then the property is not returned (It could however be 1659 returned as a result of another "SELECT" clause value.) If multiple 1660 properties of the supplied name have the named parameter, all 1661 properties with that named parameter are returned. 1663 When used in the "WHERE" clause, a match is true when the parameter 1664 value is "IN" or "LIKE" compare clause according to the supplied 1665 WHERE values. If multiple named properties contain the named 1666 parameter, then each parameter value is compared to the condition and 1667 if any match, then the results would be true for that condition the 1668 same as if only one had existed. 1670 6.1.1.4 SELF() 1672 Used in a CAL-QUERY "WHERE" clause. Returns the UPN of the currently 1673 authenticated UPN. 1675 6.1.1.5 STATE() 1677 Returns one of three values, "BOOKED", "UNPROCESSED", or "DELETED" 1678 depending on the state of the object. Used in a CAL-QUERY "WHERE" 1679 clause. Where "DELETED" is a component in the marked for delete 1680 state. Components that have been removed from the store are never 1681 returned. 1683 6.1.1.6 Ordering of Results 1685 Sorting will take place in the order the columns are supplied in the 1686 QUERY command. The CS MUST sort at least the first column. The CS 1687 MAY sort additional columns. 1689 Float and integer values MUST BE sorted by their numeric value. This 1690 means the result of a sort on an integer value type will be: 1692 1, 2, 100, 1000 1694 and not 1696 1, 100, 1000, 2 1698 This means the result of a sort on an float value type will be: 1700 1.1, 2.23, 100.332, 1000.12 1702 and not 1704 1.1, 100.332, 1000.12, 2.23 1706 Date and date time values will be sorted by their equivalent value in 1707 UTC. No matter what the returned time zone in the result set 1708 returns. This is so that if multiple components are returned each in 1709 a unique time zone, the results will be sorted in UTC. This does not 1710 mean the values MUST BE converted to UTC in the data returned to the 1711 CUA. It means the CS must do the sort in UTC. 1713 All other values are sorted according to the locale sorting order as 1714 specified in the command. Or the calendar locale if known, or the CS 1715 locale if the calendar does not have any locale set. And the locale 1716 to use for the sort is determined in that order. 1718 6.1.1.7 Date sorting order 1720 If the cap-cols is only "*" and nothing else and the result set has a 1721 DTSTART, then: 1723 If EXPAND=FALSE sorting will be by the "DTSTART" property value 1724 ascending as if it were in UTC. 1726 If EXPAND=TRUE sorting will be by the "RECURRENCE-ID" property value 1727 ascending as if it were in UTC. 1729 If one or more "DTSTART" or "RECURRENCE-ID" property values in 1730 multiple components have exactly the same value, the order for those 1731 matching components is unspecified. 1733 If the selected component(s) do not contain a "DTSTART" property or a 1734 "RECURRENCE-ID" property, then the order is unspecified. 1736 If an instance does not have a "RECURRENCE-ID" property and the query 1737 compares "RECURRENCE-ID" properties (comparing a RECURRENCE-ID to the 1738 date or date/time of a single instance object), then the CS MUST 1739 compare the "DTSTART" property value as if it were a "RECURRENCE-ID" 1740 even for single instance objects that do not contain a "RECURRENCE- 1741 ID" property. 1743 A component with a DATE and no TIME value is returned before objects 1744 with both a DATE and TIME value when the dates of those two (or more) 1745 objects are the same, sorted by date. 1747 6.1.1.8 Use of single quote 1749 All literal values are surrounded by single quotes ('), not double 1750 quotes ("), and not without any quotes. If the value contains quotes 1751 or any other ESCAPED-CHAR, they MUST BE backslash escaped as 1752 described in section 4.3.11 "Text" of [iCAL]. Any "LIKE" clause 1753 wildcard characters that are part of any literal data that is 1754 preceded by a "LIKE" clause and is not intended to mean wildcard 1755 search, MUST BE escaped as described in note (7) below. 1757 6.1.1.9 Comparing DATE and DATE-TIME values 1759 When comparing "DATE-TIME" values to "DATE" values and when comparing 1760 "DATE" values to "DATE-TIME" values, the result will be true if the 1761 "DATE" value is on the same day as the "DATE-TIME" value. And they 1762 are compared in UTC no matter what time zone the data may actual have 1763 been stored in. 1765 VALUE-1 VALUE-2 Compare Results 1767 20020304 20020304T123456 TRUE 1768 (in UTC-3) (in UTC-3) 1770 20020304 20020304T003456 FALSE 1771 (in UTC) (in UTC-4) 1773 20020304T003456Z 20020205T003456 FALSE 1774 (in UTC-0) (in UTC-7) 1776 When the "DATE" value or "DATE-TIME" value is not associated with a 1777 time zone, then the CS will compare the value assuming that the no 1778 time zone values are in the calendars default time zone. 1780 When comparing "DATE" values and "DATE-TIME" values with the "LIKE" 1781 clause the comparison will be done as if the value is a [iCAL] DATE 1782 or DATE-TIME string value. 1784 LIKE '2002%' will match anything in the year 2002. 1786 LIKE '200201%' will match anything in January 2002. 1788 LIKE '%T000000' will match anything at midnight. 1790 LIKE '____01__T%' will match anything for any year or 1791 time that is in January. 1792 (Four '_', '01', two '_' 'T%'). 1794 Using a "LIKE" clause value of "%00%, would return any value that 1795 contained two consecutive zeros. 1797 All comparisons will be done in UTC. 1799 6.1.1.10 DTEND and DURATION 1801 When a "QUERY" property value contains a "DTEND" value, then the CS 1802 MUST also evaluate any existing "DURATION" property value and 1803 determine if it has an effective end time that matches the "QUERY" 1804 property supplied "DTEND" value or any range of values supplied by 1805 the "QUERY" property. 1807 When a "QUERY" property contains a "DURATION" value, then the CS MUST 1808 also evaluate any existing "DTEND" property values and determine if 1809 they have an effective duration that matches the "QUERY" property 1810 value supplied "DURATION" value or any range of values supplied by 1811 the "QUERY" property. 1813 As "DTEND" value is the first time that is excluded from a components 1814 time range, any "DURATION" value supplied by the "QUERY" property 1815 value that is exactly one second less than the "DTEND" property value 1816 MUST match the QUERY. And if the "DURATION" property value ends 1817 exactly at the computed DTEND it MUST NOT match. 1819 Any "DTEND" value supplied by the "QUERY" property that is exactly 1820 one second more than an end time computed from a DURATION MUST match 1821 the QUERY. Any end time that is computed from a DURATION that 1822 exactly matches the supplied DTEND MUST NOT match. 1824 Given a meeting room reserved with a component that contains (date- 1825 time-example-1): 1827 DTSTART:20020127T000000Z 1828 DTEND:20020127T010000Z 1830 The reservation is really from: 1832 January 27th, 2002 00:00:00 1833 To: 1835 January 27th, 2002,00:59:59 1837 Given another meeting room reserved with a component that contains 1838 (date-time-example-2): 1840 DTSTART:20020127T000000Z 1841 DURATION:P59M59S 1843 The reservation is really from: 1845 January 27th, 2002 00:00:00 1847 To: 1849 January 27th, 2002,00:59:59 1851 A QUERY that contains: 1853 ... VEVENT.DTSTART = '20020127T00000Z' 1854 AND VEVENT.DTEND = '20020127T010000Z' 1856 MUST match both (date-time-example-1) and (date-time-example-2) 1858 A QUERY that contains: 1860 ... VEVENT.DTSTART = '20020127T00000Z' 1861 AND DURATION = 'P59M59S' 1863 MUST match both (date-time-example-1) and (date-time-example-2) 1865 6.1.1.11 [NOT] LIKE 1867 The pattern matching characters are the '%' that matches zero or more 1868 characters, and '_' that matches exactly one character (where 1869 character does not always mean octet). 1871 "LIKE" clause pattern matches always cover the entire string. To 1872 match a pattern anywhere within a string, the pattern must start and 1873 end with a percent sign. 1875 To match a '%' or '_' in the data and not have it interpreted as a 1876 wildcard character, they MUST BE backslash escaped. That is to 1877 search for a '%' or '_' in the string: 1879 LIKE '%\%%' Matches any string with a '%' in it. 1880 LIKE '%\_%' Matches any string with a '_' in it. 1882 Strings compared using the "LIKE" clause MUST BE performed using case 1883 in-sensitive comparisons when the locale allows. (Example: in US- 1884 ASCII the compare assumes 'a' = 'A'). 1886 If the "LIKE" clause is preceded by 'NOT' then there is a match when 1887 the string compare fails. 1889 Some property values (such as the 'recur' value type), contain commas 1890 and are not multi valued. The CS must understand the objects being 1891 compared and understand how to determine how any multi valued or 1892 multi instances properties or parameter values are separated, quoted, 1893 and backslash escaped and perform the comparisons as if each value 1894 existed by itself and not quoted or backslash escaped when comparing 1895 using the IN element. 1897 See related examples in Section 6.1.1.13 1899 6.1.1.12 Empty vs. NULL 1901 When used in a CAL-QUERY value, "NULL" means that the property or 1902 parameter is not present in the object. 1904 If the property (or parameter) exists, but has no value then "NULL" 1905 MUST NOT match. 1907 If the property (or parameter) exists, but has no value then it 1908 matches the empty string '' (quote quote). 1910 6.1.1.13 [NOT] IN 1912 This is similar to the "LIKE" clause, except it does value matching 1913 and not string comparison matches. 1915 Some iCalendar objects can be multi instance and multi valued. The 1916 "IN" clause will return a match if the literal value supplied as part 1917 of the "IN" clause is contained in the value of any instance of the 1918 named property or parameter, or is in any of the multiple values in 1919 the named property or parameter. Unlike the "LIKE" clause, the '%' 1920 and '_' matching characters are not used with the "IN" clause and 1921 have no special meaning. 1923 BEGIN:A-COMPONENT 1924 a property:value1,value2 One property, two values. 1925 b property:"value1,value2" One property, one value. 1926 c property:parameter=1,2:x One parameter, two values. 1927 d property:parameter="1,2",3:y One parameter, one value. 1928 e property:parameter=",":z One parameter, one value. 1929 f property:x,y,z One property, three values 1930 END:A-COMPONENT 1932 'value1' IN property would match (a) only. 1933 'value1,value2' IN property would match (b) only. 1934 'value%' IN property would NOT match any. 1935 ',' IN property would NOT match any. 1936 '%,%' IN property would NOT match any. 1937 'x' IN property would match (f) and (c). 1938 '2' IN parameter would match (c) only. 1939 '1,2' IN parameter would match (d) only. 1940 ',' IN parameter would match (e) only. 1941 '%,%' IN parameter would NOT match any. 1943 property LIKE 'value1%' would match (a) and (b). 1944 property LIKE 'value%' would match (a) and (b). 1945 property LIKE 'x' would match (f) and (c). 1946 parameter LIKE '1%' would match (c) and (d). 1947 parameter LIKE '%2%' would match (c) and (d). 1948 parameter LIKE ',' would match (e) only. 1950 Some property values (such as the "RECUR" value type), contain commas 1951 and are not multi valued. The CS must understand the objects being 1952 compared and understand how to determine how any multi valued or 1953 multi instances properties or parameter values are separated, quoted, 1954 and backslash escaped and perform the comparisons as if each value 1955 existed by itself and not quoted or backslash escaped when comparing 1956 using the IN element. 1958 If the "IN" clause is preceded by 'NOT' then there is a match when 1959 the value does not exist in the property or parameter value. 1961 6.1.1.14 DATE-TIME and TIME values in a WHEN clause 1963 All "DATE-TIME" and "TIME" literal values supplied in a "WHEN" clause 1964 MUST BE terminated with 'Z'. That means that the CUA MUST supply the 1965 values in UTC. 1967 Valid: 1969 WHERE alarm.TRIGGER < '20020201T000000Z' 1970 AND alarm.TRIGGER > '20020101T000000Z' 1972 Not valid and it is a syntax error and the CS MUST reject the QUERY. 1974 WHERE alarm.TRIGGER < '20020201T000000' 1975 AND alarm.TRIGGER > '20020101T000000' 1977 6.1.1.15 Multiple contained components 1979 All comparisons MUST BE done from the same instance of a contained 1980 component or property and repeated for each instance. As in the 1981 following example that uses a "VALARM" component contained in a 1982 "VEVENT" component . If any instance of a "VALARM" component in any 1983 "VEVENT" component matches the query and the rest of the query is 1984 satisfied, then the "UID", "SUMMARY", and "DESCRIPTION" properties 1985 from all "VEVENT" components will be returned. If there were two 1986 "VALARM" components in a "VEVENT" component, then both "VALARM" 1987 components are tested and in this example only when the "VEVENT" 1988 component state is booked: 1990 BEGIN:VQUERY 1991 EXPAND:TRUE 1992 QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT 1993 WHERE VALARM.TRIGGER >= '20000101T030405Z' 1994 AND VALARM.TRIGGER <= '20001231T235959Z' 1995 AND STATE() = 'BOOKED' 1996 END:VQUERY 1998 6.1.1.16 Example, Query by UID 2000 The following example would match the entire content of a "VEVENT" or 2001 "VTODO" component with the "UID" property equal to "uid123" and not 2002 expand any multiple instances of the component. If the CUA does not 2003 know if "uid123" was a "VEVENT", "VTODO", "VJOURNAL", or any other 2004 component, then all components that the CUA supports MUST BE supplied 2005 in a QUERY property. This example assumes the CUA is only interested 2006 in "VTODO" and "VEVENT" components. 2008 If the results were empty it could also mean that "uid123" was a 2009 property in a component other than a VTODO or VEVENT. 2011 BEGIN:VQUERY 2012 QUERY:SELECT * FROM VTODO WHERE UID = 'uid123' 2013 QUERY:SELECT * FROM VEVENT WHERE UID = 'uid123' 2014 END:VQUERY 2016 6.1.1.17 Query by Date-Time range 2018 This query selects the entire content of every booked "VEVENT" 2019 component that has an instance greater than or equal to July 1st, 2020 2000 00:00:00 UTC and less than or equal to July 31st, 2000 23:59:59 2021 UTC. This includes single instance "VEVENT" components that do no 2022 explicitly contain a "RECURRENCE-ID" property. 2024 BEGIN:VQUERY 2025 EXPAND:TRUE 2026 QUERY:SELECT * FROM VEVENT 2027 WHERE RECURRENCE-ID >= '20000801T000000Z' 2028 AND RECURRENCE-ID <= '20000831T235959Z' 2029 AND STATE() = 'BOOKED' 2030 END:VQUERY 2032 6.1.1.18 Query for all Unprocessed Entries 2034 The following example selects the entire contents of all non-booked 2035 "VTODO" and "VEVENT" components in the "UNPROCESSED" state. The 2036 default for the "EXPAND" property is FALSE, so the recurrence rules 2037 will not be expanded. 2039 BEGIN:VQUERY 2040 QUERYID:Fetch VEVENT and VTODO iTIP components 2041 QUERY:SELECT * FROM VEVENT WHERE 2042 STATE() = 'UNPROCESSED' 2043 QUERY:SELECT * FROM VTODO WHERE 2044 STATE() = 'UNPROCESSED' 2045 END:VQUERY 2047 The following example fetches all "VEVENT" and "VTODO" components in 2048 the "BOOKED" state. 2050 BEGIN:VQUERY 2051 QUERYID:Fetch All Booked VEVENT and VTODO components 2052 QUERY:SELECT * FROM VEVENT WHERE STATE() = 'BOOKED' 2053 QUERY:SELECT * FROM VTODO WHERE STATE() = 'BOOKED' 2054 END:VQUERY 2056 The following fetches the "UID" property for all "VEVENT" and "VTODO" 2057 components that have been marked for delete. 2059 BEGIN:VQUERY 2060 QUERYID:Fetch UIDs of marked for delete VEVENTs and VTODOs 2061 QUERY:SELECT UID FROM VEVENT WHERE STATE() = 'DELETE' 2062 QUERY:SELECT UID FROM VTODO WHERE STATE() = 'DELETE' 2063 END:VQUERY 2065 In the examples above they were bunched into groups of similar 2066 queries. They could be performed all at once by having all of the 2067 "QUERY" properties in one BEGIN/END "VQUERY" component. 2069 6.1.1.19 Query with Subset of Properties by Date/Time 2071 In this example only the named properties will be selected and all 2072 booked and non-booked components will be selected that have a 2073 "DTSTART" value from February 1st to February 10th 2000 (in UTC). 2075 BEGIN:VQUERY 2076 QUERY:SELECT UID,DTSTART,DESCRIPTION,SUMMARY FROM VEVENT 2077 WHERE DTSTART >= '20000201T000000Z' 2078 AND DTSTART <= '20000210T235959Z' 2079 END:VQUERY 2081 6.1.1.20 Query with Components and Alarms In A Range 2083 This example fetches all booked "VEVENT" components with an alarm 2084 that triggers within the specified time range. In this case only the 2085 "UID", "SUMMARY", and "DESCRIPTION" properties will be selected for 2086 all booked "VEVENTS" components that have an alarm between the two 2087 date-times supplied. 2089 BEGIN:VQUERY 2090 EXPAND:TRUE 2091 QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT 2092 WHERE VALARM.TRIGGER >= '20000101T030405Z' 2093 AND VALARM.TRIGGER <= '20001231T235959Z' 2094 AND STATE() = 'BOOKED' 2095 END:VQUERY 2097 6.1.2 UPN Value Type 2099 Value Name: UPN 2101 Purpose: This value type is used to identify values that contain user 2102 principal name of CU or group of CU. 2104 Formal Definition: The value type is defined by the following 2105 notation: 2107 upn = "@" 2108 / [ dot-atom-text ] "@" dot-atom-text 2110 ; dot-atom-text is defined in RFC 2822 2112 Description: This data type is an identifier that denotes a CU or a 2113 group of CU. A UPN is a RFC 822 compliant email address, with 2114 exceptions listed below, and in most cases it is deliverable to the 2115 CU. In some cases it is identical to the CU's well known email 2116 address. A CU's UPN MUST never be an e-mail address that is 2117 deliverable to a different person as there is no requirement that a 2118 person's UPN MUST BE their e-mail address. A UPN is formatted as a 2119 user name followed by "@" followed by a Realm in the form of a valid, 2120 and unique, DNS domain name. The user name MUST BE unique within the 2121 Realm. In it's simplest form it looks like "user@example.com". 2123 In certain cases a UPN will not be RFC 822 compliant. When anonymous 2124 authentication is used, or anonymous authorization is being defined, 2125 the special UPN "@" will be used. When authentication MUST BE used, 2126 but unique identity MUST BE obscured, a UPN of the form @DNS-domain- 2127 name may be used. For example, "@example.com". 2129 Example: 2131 The following is a UPN for a CU: 2133 jdoe@example.com 2135 The following is a example of a UPN that could be for a group of CU: 2137 staff@example.com 2139 The following is a UPN for an anonymous CU belonging to a specific 2140 realm or when used as a UPN-FILTER it specifies that it applies to 2141 all UPNs in a specific realm: 2143 @example.com 2145 The following is a UPN for an anonymous CU: 2147 @ 2149 6.1.3 UPN-FILTER Value 2151 Value Name: UPN-FILTER 2153 Purpose: This value type is used to identify values that contain a 2154 user principal name filter. 2156 Formal Definition: The value type is defined by the following 2157 notation: 2159 ; NOTE: "CAL-OWNERS(cal-address)" 2160 ; and "NOT CAL-OWNERS(cal-address)" 2161 ; are both NOT allowed below. 2162 ; 2163 upn-filter = "CAL-OWNERS()" / 2165 "NOT CAL-OWNERS()" / 2166 "*" / 2167 [ "*" / dot-atom-text ] "@" ( "*" / dot-atom-text ) 2169 ; dot-atom-text is defined in RFC 2822 2171 Description: The value is used to match user principal names (UPNs). 2172 For "CAL-OWNERS()" and "NOT CAL-OWNERS()", see Section 8.24. 2174 * Matches all UPNs. 2176 @ Matches the UPN of anonymous CUs 2177 belonging to the null realm 2179 @* Matches the UPN of anonymous CUs 2180 belonging to any non-null realm 2182 @realm Matches the UPN of anonymous CUs 2183 belonging to the specified realm. 2185 *@* Matches the UPN of non-anonymous CUs 2186 belonging to any non-null realm 2188 *@realm Matches the UPN of non-anonymous CUs 2189 belonging to the specified realm 2191 user@realm Matches the UPN of the specified CU 2192 belonging to the specified realm 2194 user@* Not allowed. 2196 Example: The following are examples of this value type: 2198 DENY:NON CAL-OWNERS() 2199 DENY:@hackers.example.com 2200 GRANT:sam@example.com 2202 7. New Parameters 2204 7.1 ACTION Parameter 2206 Parameter Name: ACTION 2208 Purpose: This parameter indicates the action to be taken when a 2209 timeout occurs. 2211 Value Type: TEXT 2213 Conformance: This property can be specified in the "CMD" property. 2215 When present in a "CMD" property the "ACTION" parameter specifies the 2216 action to be taken when the command timeout expires. 2218 Formal Definition: The parameter is defined by the following 2219 notation: 2221 action-param = ";" "ACTION" "=" ( "ASK" / "ABORT" ) 2222 ; If 'action-param' is supplied then 2223 ; 'latency-param' MUST BE supplied. 2225 Example: The following is an example of this parameter: 2227 CMD;LATENCY=10;ACTION=ASK:CREATE 2229 7.2 ENABLE Parameter 2231 Parameter Name: ENABLE 2233 Purpose: This parameter indicates whether or not the "TRIGGER" 2234 property in a "VALARM" component should be ignored. 2236 Value Type: BOOLEAN 2238 Conformance: This property can be specified in the "TRIGGER" 2239 properties. 2241 Description: When a non owner sends an [iTIP] "REQUEST" to a calendar 2242 that object might contain a "VALARM" component. The owner may wish 2243 to have local control over their own CUA and when or how alarms are 2244 triggered. 2246 A CUA may add the "ENABLE" parameter to any "TRIGGER" property before 2247 booking the component. If the "ENABLE" parameter is set to "FALSE", 2248 then the alarm will be ignored by the CUA. If set to "TRUE", or if 2249 the "ENABLE" property is not in the "TRIGGER" property, the alarm is 2250 enabled. The CUA should remove the "ENABLE" parameter before 2251 forwarding the component to a non-CAP CUA. 2253 Formal Definition: The property is defined by the following notation: 2255 enable-param = "ENABLE" "=" boolean 2257 Example: The following is an example of this property for a "VAGENDA" 2258 component: 2260 TRIGGER;ENABLE=FALSE;RELATED=END:PT5M 2262 7.3 ID Parameter 2264 Parameter Name: ID 2266 Purpose: When used in a "CMD" component provides a unique identifier. 2268 Value Type: TEXT 2270 Conformance: This parameter can be specified in the "CMD" property. 2272 Description: If there is more than one command sent then the "ID" 2273 parameter is used to uniquely identify the command. 2275 A CUA may add the "ID" parameter to any "CMD" property before sending 2276 the command. There must not be more than one outstanding command 2277 tagged with the same "ID" parameter value. 2279 Formal Definition: The property is defined by the following notation: 2281 id-param = ";" "ID" "=" unique-id 2282 ; The text value supplied is a unique value 2283 ; shared between the CUA and CS to uniquely 2284 ; identify the instance of command in the 2285 ; the current CUA session. The value has 2286 ; no meaning to other CUAs or other sessions. 2288 unique-id = ; text 2290 Example: The following is an example of this parameter component: 2292 CMD;UD=some-unique-value:CREATE 2294 7.4 LATENCY Parameter 2296 Parameter Name: LATENCY 2298 Purpose: This parameter indicates time in seconds for when a timeout 2299 occurs. 2301 Value Type: TEXT 2303 Conformance: This property can be specified in the "CMD" property. 2305 When present in a "CMD" property the "LATENCY" parameter specifies 2306 the time in sections when the command timeout expires. 2308 Formal Definition: The parameter is defined by the following 2309 notation: 2311 latency-param = ";" "LATENCY" "=" latency-sec 2312 ; The value supplied in the time in seconds. 2313 ; If 'latency-param' is supplied then 2314 ; 'action-param' MUST BE supplied. 2316 latency-sec = posint1 2318 Example: The following is an example of this parameter: 2320 CMD;LATENCY=10;ACTION=ASK:CREATE 2322 7.5 LOCAL Parameter 2324 Parameter Name: LOCAL 2326 Purpose: Indicates if the "VALARM" component should be exported to 2327 any non-organizer calendar. 2329 Value Type: BOOLEAN 2331 Conformance: This parameter can be specified in the "SEQUENCE" 2332 properties in a "VALARM" component. 2334 Description: When a non owner sends an [iTIP] "REQUEST" to a calendar 2335 that object might contain a "VALARM" component. The owner may wish 2336 to have local control over their own CUA and when or how alarms are 2337 triggered. 2339 A CUA may add the "LOCAL" parameter to the "SEQUENCE" property before 2340 booking the component. If the "LOCAL" parameter is set to "FALSE", 2341 then the alarm MUST NOT be forwarded to any other calender. If set 2342 to "TRUE", or of the "LOCAL" property is not in the "SEQUENCE" 2343 property, the alarm is global. The CUA should remove the "LOCAL" 2344 parameter before forwarding the component to a non-cap CUA other 2345 calendars. 2347 Formal Definition: The property is defined by the following notation: 2349 local-param = "LOCAL" "=" boolean 2351 Example: The following is an example of this parameter: 2353 SEQUENCE;LOCAL=TRUE:4 2355 7.6 LOCALIZE Parameter 2357 Parameter Name: LOCALIZE 2359 Purpose: If provided the "LOCALIZE" parameter specifies the desired 2360 language for error and warning messages. 2362 Value Type: TEXT 2364 Conformance: This parameter can be specified in the "CMD" properties. 2366 When the "LOCALIZE" parameter is supplied then its value MUST BE one 2367 of the values listed in the initial [BEEP] greeting 'localize' 2368 attribute. 2370 A CUA may add the "LOCAL" parameter to the "LOCALIZE" parameter to 2371 the "CMD" property to specify the language of any error or warning 2372 messages. 2374 Formal Definition: The property is defined by the following notation: 2376 localize-param = ";" "LOCALIZE" "=" beep-localize 2377 ; The value supplied MUST BE one value from the initial 2378 ; [BEEP] greeting 'localize' attribute specifying 2379 ; the locale to use for error messages during 2380 ; this instance of the command sent. 2382 beep-localize = ; text 2384 Example: The following is an example of this parameter: 2386 CMD;LOCALIZE=fr_CA:CREATE 2388 7.7 OPTIONS Parameter 2390 Parameter Name: OPTIONS 2392 Purpose: If provided the "OPTIONS" parameter specifies some "CMD" 2393 property specific options. 2395 Value Type: TEXT 2397 Conformance: This parameter can be specified in the "CMD" properties. 2399 A CUA adds the "OPTIONS" parameter to the "LOCALIZE" parameter to the 2400 "CMD" property when the command needs extra values. 2402 Formal Definition: The property is defined by the following notation: 2404 option-param = ";" "OPTIONS" "=" cmd-specific 2406 cmd-specific = ; The value supplied is dependent on the 2407 ; CMD value. See the specific CMDs for the 2408 ; correct values to use for each CMD. 2410 Example: The following is an example of this parameter: 2412 CMD;OPTIONS=10:GENERATE-UID 2414 8. New Properties 2416 8.1 ALLOW-CONFLICT Property 2418 Property Name: ALLOW-CONFLICT 2420 Purpose: This property indicates whether or not the calendar and CS 2421 supports component conflicts. That is, whether or not any of the 2422 components in the calendar can overlap. 2424 Value Type: BOOLEAN 2426 Property Parameters: Non-standard property parameters can be 2427 specified on this property. 2429 Conformance: This property can be specified in "VAGENDA" and 2430 "VCALSTORE" component. 2432 Description: This property is used to indicate whether components may 2433 conflict. That is, if their expanded instances may share the same 2434 time or overlap the same time periods. If it has a value of TRUE, 2435 then conflicts are allowed. If FALSE, the no two components may 2436 conflict. 2438 If FALSE in the "VCALSTORE" component, then all "VAGENDA" component 2439 "ALLOW-CONFLICT" property values MUST BE false in the CS. 2441 Formal Definition: The property is defined by the following notation: 2443 allow-conflict = "ALLOW-CONFLICT" other-params ":" boolean CRLF 2445 Example: The following is an example of this property for a "VAGENDA" 2446 component: 2448 ALLOW-CONFLICT:FALSE 2450 8.2 ATT-COUNTER Property 2452 Property Name: ATT-COUNTER 2454 Property Parameters: Non-standard property parameters can be 2455 specified on this property. 2457 Conformance: This property MUST be specified in an iCalendar object 2458 that specifies counter proposal to a group scheduled calendar entity. 2459 When storing a "METHOD" property with the "COUNTER" method, there 2460 needs to be a way to remember who sent the COUNTER. The ATT-COUNTER 2461 property MUST BE added to all "COUNTER" [iTIP] components by the CUA 2462 before storing in a CS. 2464 Description: This property is used to identify the CAL-ADDRESS of the 2465 entity that sent the "COUNTER" [iTIP] object. 2467 Formal Definition: The property is defined by the following notation: 2469 attcounter = "ATT-COUNTER" other-params ":" cal-address CRLF 2471 Examples: 2473 ATT-COUNTER:cap:example.com/Doug 2474 ATT-COUNTER:mailto:Doug@Example.com 2476 8.3 CALID Property 2478 Property Name: CALID 2480 Property Parameters: Non-standard property parameters can be 2481 specified on this property. 2483 Conformance: This property can be specified in the "VAGENDA" 2484 component. 2486 Description: This property is used to specify a fully qualified 2487 calid. 2489 Formal Definition: The property is defined by the following notation: 2491 CALID = "CALID" other-params ":" calid CRLF 2493 Example: 2495 CALID:cap://cal.example.com/sdfifgty4321 2497 8.4 CALMASTER Property 2499 Property Name: CALMASTER 2501 Purpose: The property specifies an e-mail address of a person 2502 responsible for the calendar store. 2504 Value Type: URI 2506 Property Parameters: Non-standard property parameters can be 2507 specified on this property. 2509 Conformance: The property can be specified in a "VCALSTORE" 2510 component. 2512 Description: The parameter value SHOULD BE a MAILTO URI as defined in 2513 [URL]. It MUST BE a contact URI such as a MAILTO URI and not a home 2514 page or file URI that describes how to contact the calmasters. 2516 Formal Definition: The property is defined by the following notation: 2518 calmaster = "CALMASTER" other-params ":" uri CRLF 2520 uri = ; IANA registered uri as defined in [iCAL] 2522 Example: The following is an example of this property: 2524 CALMASTER:mailto:administrator@example.com 2526 8.5 CAP-VERSION Property 2528 Property Name: CAP-VERSION 2530 Purpose: This property specifies the version of CAP supported. 2532 Value Type: TEXT 2534 Property Parameters: Non-standard property parameters can be 2535 specified on this property. 2537 Conformance: This property is specified in the "VREPLY" component 2538 that is sent in response to a "GET-CAPABILITY" command. 2540 Description: This specifies the version of CAP that the endpoint 2541 supports. The list is a comma separated list of RFC numbers 2542 supported. The list MUST contain at least XXXX (NOTE 'XXXX' WILL BE 2543 REPLACED WITH THE RFC NUMBER OF THIS DOCUMENT). 2545 Formal Definition: The property is defined by the following notation: 2547 cap-version = "CAP-VERSION" other-params ":" text CRLF 2549 Example: The following are examples of this property: 2551 CAP-VERSION:XXXX 2553 8.6 CARID Property 2555 Property Name: CARID 2557 Purpose: This property specifies the identifier for an access right 2558 component. 2560 Value Type: TEXT 2562 Property Parameters: Non-standard property parameters can be 2563 specified on this property. 2565 Conformance: This property MUST BE specified once in a "VCAR" 2566 component. 2568 Description: This property is used in the "VCAR" component to specify 2569 an identifier. A "CARID" property value is unique per container. 2571 Formal Definition: The property is defined by the following notation: 2573 carid = "CARID" other-params ":" text CRLF 2575 Example: The following are examples of this property: 2577 CARID:xyzzy-007 2578 CARID:User Rights 2580 8.7 CAR-LEVEL Property 2582 Property Name: CAR-LEVEL 2584 Purpose: The property specifies the level of VCAR supported. 2586 Value Type: TEXT 2588 Property Parameters: Non-standard property parameters can be 2589 specified on this property. 2591 Conformance: The property can be specified in a "VREPLY" component 2592 that is sent in response to a "GET-CAPABILITY" command. 2594 Description: The value is one from a list of "CAR-NONE", "CAR-MIN", 2595 or "CAR-FULL-1". If "CAR-FULL-1" is supplied then "CAR-MIN" is also 2596 available. A "CAR-MIN" implementation only supported the "DEFAULT- 2597 VCARS" property values listed in the "VCALSTORE" component and a 2598 "CAR-MIN" implementation does not support the creation or 2599 modification of "VCAR" components from the CUA. 2601 Formal Definition: The property is defined by the following notation: 2603 car-level = "CAR-LEVEL" ":" other-params : car-level-values 2605 car-level-values = ( "CAR-NONE" / "CAR-MIN" / "CAR-FULL-1" 2606 / other-levels ) 2608 other-levels = ; Any name published in an RFC for a "CAR-LEVEL" 2609 ; property value. 2611 Example: The following is an example of this property: 2613 CAR-LEVEL:CAR-FULL-1 2615 8.8 COMPONENTS Property 2617 Property Name: COMPONENTS 2619 Purpose: The property specifies a the list of components supported by 2620 the endpoint. 2622 Value Type: TEXT 2623 Property Parameters: Non-standard property parameters can be 2624 specified on this property. 2626 Conformance: The property can be specified in a "VREPLY" component in 2627 response to a "GET-CAPABILITY" command. 2629 Description: A comma separated list of components supported by the 2630 endpoint. If not in the list sent from the endpoint then they are 2631 not supported by that endpoint. Sending an unsupported component 2632 results in unpredictable results. This includes any components 2633 inside of other components (VALARM for example). It MUST include at 2634 least VCALSTORE, VCALENDAR, VTIMEZONE, STANDARD, DAYLIGHT, VREPLY, 2635 and VAGENDA and at least one of VEVENT, VTODO, or VJOURNAL. The 2636 recommened list is "VCALSTORE,VCALENDAR,VREPLY,VAGENDA, 2637 VEVENT,VALARM,VTIMEZONE,VJOURNAL,VTODO, DAYLIGHT,STANDARD" 2639 Formal Definition: The property is defined by the following notation: 2641 components = "COMPONENTS" other-params ":" comp-list CRLF 2643 ; All of the following MUST BE supplied in any order. 2644 ; 2645 comp-list-req = "VCALSTORE" "," "VCALENDAR" "," "VTIMEZONE" "," 2646 "VREPLY", "VAGENDA", "STANDARD", "DAYLIGHT" 2648 ; At least one MUST BE supplied. The same value 2649 ; MUST NOT occur more than once. 2650 ; 2651 comp-list-min = ( "," "VEVENT") / ( "," "VTODO") / ( "," "VJOURNAL" ) 2653 ; The same value MUST NOT occur 2654 ; more than once. 2655 ; 2656 comp-list-opt = ( "," "VFREEBUSY" ) / ( "," "VALARM" ) 2657 ( "," "VCAR" ) / ( "," "VQUERY" ) 2658 ( "," x-comp ) / ( "," iana-comp ) 2660 comp-list = comp-list-req 1*3comp-list-min *comp-list-opt 2662 *("," comp-list-names) comp-name 2664 Example: The following is an example of this property: 2666 COMPONENTS:VCALSTORE,VCALENDAR,VREPLY,VAGENDA, 2667 VEVENT,VALARM,VTIMEZONE,VJOURNAL,VTODO, 2668 DAYLIGHT,STANDARD" 2670 8.9 CSID Property 2672 Property Name: CSID 2674 Purpose: The property specifies a the globally unique identifier for 2675 the calendar store. 2677 Value Type: URI 2679 Property Parameters: Non-standard property parameters can be 2680 specified on this property. 2682 Conformance: The property can be specified in a "VCALSTORE" 2683 component. 2685 Description: The identifier MUST BE globally unique. Each CS needs 2686 its own unique identifier. The "CSID" property is the official 2687 unique identifier for the CS. If the [BEEP] 'serverName' attribute 2688 was supplied in the [BEEP] 'start' message, then the CSID will be 2689 mapped to the virtual host name supplied and the host name part of 2690 the CSID MUST BE the same as the 'serverName' value. This allows one 2691 CS implementation to service multiple virtual hosts. CS's are not 2692 required to support virtual hosting. If a CS does not support 2693 virtual hosting then it must ignore the [BEEP] 'serverName' 2694 attribute. 2696 Formal Definition: The property is defined by the following notation: 2698 csid = "CSID" other-params ":" capurl CRLF 2700 Example: The following is an example of this property: 2702 CSID:cap://calendar.example.com 2704 8.10 DECREED Property 2706 Property Name: DECREED 2708 Purpose: This property specifies if an access right calendar 2709 component is decreed or not. 2711 Value Type: BOOLEAN 2713 Property Parameters: Non-standard property parameters can be 2714 specified on this property. 2716 Conformance: This property MAY be specified once in a "VCAR" 2717 component. 2719 Description: This property is used in the "VCAR" component to specify 2720 whether the component is decreed or not. If the "DECREED" property 2721 value is "true" then the CUA will be unable to change the contents of 2722 the "VCAR" component and any attempt will fail with an error. 2724 Formal Definition: The property is defined by the following notation: 2726 decreed = "DECREED" other-params ":" boolean CRLF 2728 Example: The following is an example of this property: 2730 DECREED:TRUE 2732 8.11 DEFAULT-CHARSET Property 2734 Property Name: DEFAULT-CHARSET 2736 Purpose: This property indicates the default charset. 2738 Value Type: TEXT 2740 Property Parameters: Non-standard property parameters can be 2741 specified on this property. 2743 Conformance: This property can be specified in "VAGENDA" and 2744 "VCALSTORE" calendar component. 2746 Description: In a "VAGENDA" component this property is used to 2747 indicate the charset of calendar. If not specified, the default is 2748 the first value in the "VCALSTORE" components "DEFAULT-CHARSET" 2749 property value list. The value MUST BE an IANA registered character 2750 set as defined in [CHARREG]. 2752 In a "VCALSTORE" component it is a comma separated list of charsets 2753 supported by the CS. The first entry is the default entry for all 2754 newly created "VAGENDA" components. The "UTF-8" value MUST BE in the 2755 "VCALSTORE" component "DEFAULT-CHARSET" property list. All compliant 2756 CAP implementations (CS and CUA) MUST support the "UTF-8" charset. 2758 If a charset name contains a comma (,), then that comma must be 2759 backslashed escaped in the value. 2761 Formal Definition: The property is defined by the following notation: 2763 default-charset = "DEFAULT-CHARSET" other-params ":" text 2764 *( "," text) CRLF 2766 Example: The following is an example of this property for a "VAGENDA" 2767 component: 2769 DEFAULT-CHARSET:Shift_JIS,UTF-8 2771 8.12 DEFAULT-LOCALE Property 2773 Property Name: DEFAULT-LOCALE 2775 Purpose: This property specifies the default language for text 2776 values. 2778 Value Type: TEXT 2780 Property Parameters: Non-standard property parameters can be 2781 specified on this property. 2783 Conformance: This property can be specified in "VAGENDA" and 2784 "VCALSTORE" components. 2786 Description: In a "VAGENDA" component, the "DEFAULT-LOCALE" property 2787 is used to indicate the locale of the calendar. The full locale 2788 SHOULD be used. The default and minimum locale is POSIX (aka the 'C' 2789 locale). 2791 In a "VCALSTORE" component it is a comma separated list of locales 2792 supported by the CS. The first value in the list is the default for 2793 all newly created VAGENDAs. "POSIX" MUST BE in the list. 2795 Formal Definition: The property is defined by the following notation: 2797 default-locale = "DEFAULT-LOCALE" other-params ":" language 2798 *( "," language) CRLF 2800 language = Text identifying a locale, as defined in [CHARPOL] 2802 Example: The following is an example of this property: 2804 DEFAULT-LOCALE:en-US.iso-8859-1,POSIX 2806 8.13 DEFAULT-TZID Property 2808 Property Name: DEFAULT-TZID 2810 Purpose: This property specifies the text value that specifies the 2811 time zones. 2813 Value Type: TEXT 2815 Property Parameters: Non-standard property parameters can be 2816 specified on this property. 2818 Conformance: This property may be specified once in a "VAGENDA" and 2819 "VCALSTORE" components. 2821 Description: A multi valued property that lists the known time zones. 2822 The first is the default. Where "TZID" property values are the same 2823 as the "TZID" property as defined in [iCAL]. 2825 If in a "VCALSTORE" component it is a comma separated list of TZIDs 2826 known to the CS. The entry is used as the default TZID list for all 2827 newly created calendars. The list MUST contain at least "UTC". A 2828 "VCALSTORE" components MUST have one "VTIMEZONE" component contained 2829 in it for each value in the "DEFAULT-TZID" property value. 2831 If in a "VAGENDA" component it is a comma separated list of "TZID" 2832 property values naming the time zones known to the calendar. The 2833 first time zone in the list is the default and is used as the 2834 localtime for objects that contain a date or date-time value without 2835 a time zone. All "VAGENDA" components MUST have one "VTIMEZONE" 2836 component contained for each value in the "DEFAULT-TZID" property 2837 value. 2839 If a "TZID" property value contains a comma (,), the comma must be 2840 backslash escaped. 2842 Formal Definition: This property is defined by the following 2843 notation: 2845 default-tzid = "DEFAULT-TZID" other-params 2846 ":" [tzidprefix] text 2847 *("," [tzidprefix] text) CRLF 2849 Example: The following is an example of this property: 2851 DEFAULT-TZID:US/Eastern,UTC 2853 8.14 DEFAULT-VCARS Property 2855 Property Name: DEFAULT-VCARS 2857 Purpose: This property is used to specify the "CARID" property ids of 2858 the default "VCAR" components for newly created "VAGENDA" components. 2860 Value Type: TEXT 2862 Property Parameters: Non-standard property parameters can be 2863 specified on this property. 2865 Conformance: This property MUST BE specified in "VCALSTORE" calendar 2866 component and MUST at least specify the following values: 2867 "READBUSYTIMEINFO", "REQUESTONLY", "UPDATEPARTSTATUS", and 2868 "DEFAULTOWNER". 2870 Description: This property is used in the "VCALSTORE" component to 2871 specify the "CARID" value of the "VCAR" components that MUST BE 2872 copied into now "VAGENDA" components at creation time by the CS. All 2873 "DEFAULT-VCAR" values must have "VCARS" components stored in the 2874 "VCALSTORE". 2876 Formal Definition: The property is defined by the following notation: 2878 def-vcars = "DEFAULT-VCARS" other-params ":" text 2879 *( "," text ) CRLF 2881 Example: The following is an example of this property: 2883 DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY, 2884 UPDATEPARTSTATUS,DEFAULTOWNER 2886 8.15 DENY Property 2888 Property Name: DENY 2890 Purpose: This property identifies the UPN(s) being denied access in 2891 the "VRIGHT" component. 2893 Value Type: UPN-FILTER 2895 Property Parameters: Non-standard property parameters can be 2896 specified on this property. 2898 Conformance: This property can be specified in "VRIGHT" components. 2900 Description: This property is used in the "VRIGHT" component to 2901 define the CU or UG being denied access. 2903 Formal Definition: The property is defined by the following notation: 2905 deny = "DENY" other-params ":" upn-filter CRLF 2907 Example: The following are examples of this property: 2909 DENY:* 2911 DENY:bob@example.com 2913 8.16 EXPAND property 2915 Property Name: EXPAND 2916 Purpose: This property is to notify the CS if it should or should not 2917 expand any component with recurrence rules into multiple instances in 2918 a query reply. 2920 Value Type: BOOLEAN 2922 Property Parameters: Non-standard property parameters can be 2923 specified on this property. 2925 Conformance: This property can be specified in "VQUERY" components. 2927 Description: If a CUA wishes to see all of the instances of a 2928 recurring component the CUA sets EXPAND=TRUE in the "VQUERY" 2929 component. If not specified, the default is FALSE. Note that if the 2930 CS has its "RECUR-EXPAND" CS property value set to false then the 2931 "EXPAND" property will be ignored and the result will be as if the 2932 "EXPAND" value was set to false. 2934 Formal Definition: The property is defined by the following notation: 2936 expand = "EXPAND" other-params ":" ("TRUE" / "FALSE") CRLF 2938 Example: The following are examples of this property: 2940 EXPAND:FALSE 2941 EXPAND:TRUE 2943 8.17 GRANT Property 2945 Property Name: GRANT 2947 Purpose: This property identifies the UPN(s) being granted access in 2948 the "VRIGHT" component. 2950 Value Type: UPN-FILTER 2952 Property Parameters: Non-standard property parameters can be 2953 specified on this property. 2955 Conformance: This property can be specified in "VRIGHT" calendar 2956 components. 2958 Description: This property is used in the "VRIGHT" component to 2959 specify the CU or UG being granted access. 2961 Formal Definition: The property is defined by the following notation: 2963 grant = "GRANT" other-params ":" upn-filter CRLF 2965 Example: The following are examples of this property: 2967 GRANT:* 2969 GRANT:bob@example.com 2971 8.18 ITIP-VERSION Property 2973 Property Name: ITIP-VERSION 2975 Purpose: This property specifies the version of ITIP supported. 2977 Value Type: TEXT 2979 Property Parameters: Non-standard property parameters can be 2980 specified on this property. 2982 Conformance: This property is specified in the "VREPLY" component 2983 that is sent in response to a "GET-CAPABILITY" command. 2985 Description: This specifies the version of ITIP that the endpoint 2986 supports. The list is a comma separated list of RFC numbers 2987 supported. The list MUST contain at least 2446. 2989 Formal Definition: The property is defined by the following notation: 2991 itip-version = "ITIP-VERSION" other-params ":" text CRLF 2993 Example: The following are examples of this property: 2995 ITIP-VERSION:2446 2997 8.19 MAX-COMP-SIZE Property 2999 Property Name: MAX-COMP-SIZE 3001 Purpose: This property specifies the largest size of any object 3002 accepted. 3004 Value Type: TEXT 3006 Property Parameters: Non-standard property parameters can be 3007 specified on this property. 3009 Conformance: This property is specified in the "VREPLY" component 3010 that is sent in response to a "GET-CAPABILITY" command. 3012 Description: A positive integer value that specifies the size of the 3013 largest iCalendar object that can be accepted in octets. Objects 3014 larger than this will be rejected. A value of zero (0) means no 3015 limit. This is also the maximum value of any [BEEP] payload that 3016 will be accepted or sent. 3018 Formal Definition: The property is defined by the following notation: 3020 max-comp-size = "MAX-COMP-SIZE" other-params ":" posint0 CRLF 3022 Example: The following are examples of this property: 3024 MAX-COMP-SIZE:1024 3026 8.20 MAXDATE Property 3028 Property Name: MAXDATE 3030 Purpose: This property specifies the date/time in the future beyond 3031 which the CS or CUA cannot represent. 3033 Value Type: DATE-TIME 3035 Property Parameters: Non-standard property parameters can be 3036 specified on this property. 3038 Conformance: The property can be specified in the "VCALSTORE" 3039 component. 3041 Description: The date and time MUST BE a UTC value and end with 'Z'. 3043 Formal Definition: The property is defined by the following notation: 3045 maxdate = "MAXDATE" other-params ":" date-time CRLF 3047 Example: The following is an example of this property: 3049 MAXDATE:20990101T000000Z 3051 8.21 MINDATE Property 3053 Property Name: MINDATE 3055 Purpose: This property specifies the date/time in the past prior to 3056 which the server cannot represent. 3058 Value Type: DATE-TIME 3060 Property Parameters: Non-standard property parameters can be 3061 specified on this property. 3063 Conformance: The property can be specified in the "VCALSTORE" 3064 component. 3066 Description: The date and time MUST BE a UTC value and end with 'Z'. 3068 Formal Definition: The property is defined by the following notation: 3070 mindate = "MINDATE" other-params ":" date-time CRLF 3072 Example: The following is an example of this property: 3074 MINDATE:19710101T000000Z 3076 8.22 MULTIPART Property 3078 Property Name: MULTIPART 3080 Purpose: This property provides a comma separated list of supported 3081 MIME multipart types supported by the sender. 3083 Value Type: TEXT 3085 Property Parameters: Non-standard property parameters can be 3086 specified on this property. 3088 Conformance: This property can be specified in a component. 3090 Description: This property is used in the in the "GET-CAPABILITY" 3091 command reply to indicated the MIME multipart types supported. A CS 3092 and CUA SHOULD support all registered MIME multipart types. 3094 Formal Definition: The property is defined by the following notation: 3096 name = "MULTIPART" other-params ":" text *( "," text) CRLF 3098 Example: The following is an example of this property: 3100 MULTIPART:related,alternate,mixed 3102 8.23 NAME Property 3104 Property Name: NAME 3106 Purpose: This property provides a localizable display name for a 3107 component. 3109 Value Type: TEXT 3111 Property Parameters: Non-standard property parameters can be 3112 specified on this property. 3114 Conformance: This property can be specified in a component. 3116 Description: This property is used in the in component to specify a 3117 localizable display name. If more than one "NAME" properties are in 3118 a component, then they MUST have unique "LANG" parameters. If the 3119 "LANG" parameter is not supplied, then it defaults to the "VAGENDA" 3120 default if the component is in a "VAGENDA", or the "VCALSTORE" 3121 default if the component is stored at the "VCALSTORE" level. 3123 Formal Definition: The property is defined by the following notation: 3125 name = "NAME" nameparam ":" text CRLF 3127 nameparam = other-params [ ";" languageparam ] other-params 3129 languageparam = ; As defined in [iCAL]. 3131 Example: The following is an example of this property: 3133 NAME:Restrict Guests From Creating VALARMs On VEVENTs 3135 8.24 OWNER Property 3137 Property Name: OWNER 3139 Purpose: The property specifies an owner of the component. 3141 Value Type: UPN 3143 Property Parameters: Non-standard, alternate text representation and 3144 language property parameters can be specified on this property. 3146 Conformance: The property MUST BE specified at in a "VAGENDA" 3147 component. 3149 Description: A multi-instanced property indicating the calendar 3150 owner. 3152 Formal Definition: The property is defined by the following notation: 3154 owner = "OWNER" other-params ":" upn CRLF 3156 Example: The following is an example of this property: 3158 OWNER:jsmith@example.com 3159 OWNER:jdough@example.com 3161 8.25 PERMISSION Property 3163 Property Name: PERMISSION 3165 Purpose: This property defines a permission that is granted or denied 3166 in a "VRIGHT" component. 3168 Value Type: TEXT 3170 Property Parameters: Non-standard property parameters can be 3171 specified on this property. 3173 Conformance: This property can be specified in "VRIGHT" components. 3175 Description: This property is used in the "VRIGHT" component to 3176 define a permission that is granted or denied. 3178 Formal Definition: The property is defined by the following notation: 3180 perm = "PERMISSION" other-params ":" permvalue CRLF 3182 permvalue = ( "SEARCH" / "CREATE" / "DELETE" / "MODIFY" / all ) 3184 all = "*" 3186 Example: The following is an example of this property: 3188 PERMISSION:SEARCH 3190 8.26 QUERY property 3192 Property Name: QUERY 3194 Purpose: Specifies the query for the component. 3196 Value Type: CAL-QUERY 3198 Property Parameters: Non-standard property parameters can be 3199 specified on this property. 3201 Conformance: This property can be specified in "VQUERY" components. 3203 Description: A "QUERY" is used to specify the "CAL-QUERY" (Section 3204 6.1.1 for the query. 3206 Formal Definition: The property is defined by the following notation: 3208 query = "QUERY" other-params ":" cal-query CRLF 3210 Example: The following is an example of this property: 3212 QUERY:SELECT * FROM VEVENT 3214 8.27 QUERYID property 3216 Property Name: QUERYID 3218 Purpose: Specifies a unique ID for a query in the targeted container. 3220 Value Type: TEXT 3222 Property Parameters: Non-standard property parameters are specified 3223 on this property. 3225 Conformance: This property can be specified in "VQUERY" components. 3227 Description: A "QUERYID" property is used to specify the unique id 3228 for a stored query. A "QUERYID" property value is unique per 3229 container. 3231 Formal Definition: The property is defined by the following notation: 3233 queryid = "QUERYID" other-params ":" text CRLF 3235 Example: The following are examples of this property: 3237 QUERYID:Any Text String 3238 QUERYID:fetchUnProcessed 3240 8.28 REQUEST-STATUS property 3242 This description is a revision of the "REQUEST-STATUS" property for 3243 VCALENDAR version 2.0. The 'statdesc' is optional and the 'extdata' 3244 may be included when 'statdesc' is not provided. 3246 rstatus = "REQUEST-STATUS" rstatparam ":" 3247 statcode ";" *(statdesc ) ";" *(extdata) 3249 rstatparam = other-params [";" languageparm] other-params 3251 statcode = 1*DIGIT *("." 1*DIGIT) 3252 ;Hierarchical, numeric return status code 3254 statdesc = text 3255 ;An optional textual status description, content is 3256 ;decided by the implementer. May be empty. 3258 extdata = text 3259 ; Textual exception data. For example, the offending 3260 ; property name and value or complete property line. 3262 Example: The following are some possible examples of this property. 3263 The COMMA and SEMICOLON separator characters in the property value 3264 are BACKSLASH character escaped because they appear in a text value. 3266 REQUEST-STATUS:2.0;Success 3268 REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01 3270 REQUEST-STATUS:2.8; Success\, repeating VEVENT ignored. Scheduled 3271 as a single VEVENT.;RRULE:FREQ=WEEKLY;INTERVAL=2 3273 REQUEST-STATUS:4.1;Time conflict. Date/time is busy. 3275 REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE: 3276 MAILTO:jsmith@example.com 3278 REQUEST-STATUS:3.7;;ATTENDEE:MAILTO:jsmith@example.com 3280 REQUEST-STATUS:10.4;Help! That really shouldn't have happened. 3282 8.29 QUERY-LEVEL Property 3284 Property Name: QUERY-LEVEL 3286 Purpose: This property specifies the level of query supported. 3288 Value Type: TEXT 3290 Property Parameters: Non-standard property parameters can be 3291 specified on this property. 3293 Conformance: The property can be specified in the "VREPLY" component 3294 in response to a "GET-CAPABILITY" command. 3296 Description: Indicates level of query support. CAL-QL-NONE is for 3297 CS's that allow ITIP methods only to be deposited and nothing else. 3299 Formal Definition: The property is defined by the following notation: 3301 query-level = "QUERY-LEVEL" other-params 3302 ":" ( "CAL-QL-1" / "CAL-QL-NONE") CRLF 3304 Example: The following is an example of this property: 3306 QUERY-LEVEL:CAL-QL-1 3308 8.30 RECUR-ACCEPTED Property 3310 Property Name: RECUR-ACCEPTED 3312 Purpose: This property specifies if the endpoint supports recurring 3313 instances. 3315 Value Type: BOOLEAN 3317 Property Parameters: Non-standard property parameters can be 3318 specified on this property. 3320 Conformance: The property can be specified in the "VREPLY" component 3321 in response to a "GET-CAPABILITY" command. 3323 Description: Indicates if recurrence rules are supported. If FALSE 3324 then the endpoint can not process any kind of recurring rules. 3326 Formal Definition: The property is defined by the following notation: 3328 recur-accepted = "RECUR-ACCEPTED" other-params ":" boolean CRLF 3330 Example: The following is an example of this property: 3332 RECUR-ACCEPTED:TRUE 3333 RECUR-ACCEPTED:FALSE 3335 8.31 RECUR-LIMIT Property 3337 Property Name: RECUR-LIMIT 3339 Purpose: This property specifies the maximum number of instances the 3340 endpoint will expand instances into at query or storage time. 3342 Value Type: posint1 3344 Property Parameters: Non-standard property parameters can be 3345 specified on this property. 3347 Conformance: The property can be specified in the "VREPLY" component 3348 in response to a "GET-CAPABILITY" command. 3350 Description: For implementations that have the "STORES-EXPANDED" 3351 value set to TRUE, then this value specifies the maximum number of 3352 instances that will be stored and fetched. For all implementations 3353 this is the maximum number of instances that will be returned when 3354 the "EXPAND" parameter is specified as TRUE and the results contain a 3355 infinite or large number of recurring instances. 3357 Formal Definition: The property is defined by the following notation: 3359 recur-limit = "RECUR-LIMIT" other-params ":" posint1 CRLF 3361 Example: The following is an example of this property: 3363 RECUR-LIMIT:1000 3365 8.32 RECUR-EXPAND Property 3367 Property Name: RECUR-EXPAND 3369 Purpose: This property specifies if the endpoint can expand 3370 recurrences into multiple objects. 3372 Value Type: BOOLEAN 3374 Property Parameters: Non-standard property parameters can be 3375 specified on this property. 3377 Conformance: The property can be specified in the "VREPLY" component 3378 in response to a "GET-CAPABILITY" command. 3380 Description: If TRUE then the endpoint can expand an object into 3381 multiple instances as defined by its recurrence rules when the 3382 "EXPAND" parameter is supplied. If FALSE then the endpoint ignores 3383 the "EXPAND" parameter. 3385 Formal Definition: The property is defined by the following notation: 3387 recur-expand = "RECUR-EXPAND" other-params ":" boolean CRLF 3389 Example: The following is an example of this property: 3391 RECUR-EXPAND:TRUE 3392 RECUR-EXPAND:FALSE 3394 8.33 RESTRICTION Property 3396 Property Name: RESTRICTION 3398 Purpose: This property defines restrictions on the result value of 3399 new or existing components. 3401 Value Type: CAL-QUERY 3403 Property Parameters: Non-standard property parameters can be 3404 specified on this property. 3406 Conformance: This property can be specified in "VRIGHT" components, 3407 but only when the "PERMISSION" property is set to "CREATE", "MODIFY", 3408 or "*" property value. 3410 Description: This property is used in the "VRIGHT" component to 3411 define restrictions on the components that can be written (i.e., by 3412 using the "CREATE" or "MOVE" commands) as well as on the values that 3413 may take existent calendar store properties, calendar properties, 3414 components, and properties (i.e., by using the "MODIFY" command). 3415 Accepted values MUST match any specified "RESTRICTION" property 3416 values. 3418 Formal Definition: The property is defined by the following notation: 3420 restrict = "RESTRICTION" other-params ":" cal-query CRLF 3422 Example: The following are examples of this property: 3424 RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST' 3426 RESTRICTION:SELECT * FROM VEVENT WHERE 3427 SELF() IN ORGANIZER 3429 RESTRICTION:SELECT * FROM VEVENT WHERE 'BUSINESS' IN 3430 CATEGORIES 3432 8.34 SCOPE Property 3434 Property Name: SCOPE 3436 Purpose: This property identifies the objects in the CS to which the 3437 access rights applies. 3439 Value Type: CAL-QUERY 3441 Property Parameters: Non-standard property parameters can be 3442 specified on this property. 3444 Conformance: This property can be specified in "VRIGHT" components. 3446 Description: This property is used in the "VRIGHT" component to 3447 define the set of objects subject to the access right being defined. 3449 Formal Definition: The property is defined by the following notation: 3451 scope = "SCOPE" other-params ":" cal-query CRLF 3453 Example: The following is an example of this property: 3455 SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC' 3457 8.35 STORES-EXPANDED Property 3459 Property Name: STORES-EXPANDED 3461 Purpose: This property specifies if the sending endpoint expands 3462 recurrence rules prior to storing them into the CS. Section 5. 3464 Value Type: BOOLEAN 3466 Property Parameters: Non-standard property parameters can be 3467 specified on this property. 3469 Conformance: This property can be specified in a "VREPLY" component 3470 in response to a "GET-CAPABILITY" command. 3472 Description: If the value is TRUE then the endpoint expands 3473 recurrence rules and then stores the results into the CS. If this is 3474 TRUE then the "RECUR-LIMIT" property is significant because an 3475 infinitely recurring appointment will be stored no more than "RECUR- 3476 LIMIT" property values into the CS and all other instances will be 3477 lost. 3479 Formal Definition: The property is specified by the following 3480 notation: 3482 stores-expanded = "STORES-EXPANDED" other-params ":" boolean CRLF 3484 The following is an example of this property: 3486 STORES-EXPANDED:TRUE 3487 STORES-EXPANDED:FALSE 3489 8.36 TARGET Property 3491 Property Name: TARGET 3493 Purpose: This property defines the container that the command that is 3494 issued will act upon. Its value is a capurl as defined in Section 5. 3496 Value Type: URI 3498 Property Parameters: Non-standard property parameters can be 3499 specified on this property. 3501 Conformance: This property can be specified in a command component. 3503 Description: This property value is used to specify the container 3504 that the command will effect. When used in a command, the command 3505 will be performed on the container which has a capurl matching the 3506 value. 3508 Formal Definition: The property is specified by the following 3509 notation: 3511 target = "TARGET" other-params ":" capurl CRLF 3512 The following is an example of this property: 3514 TARGET:cap://mycal.example.com 3515 TARGET:SomeRelCalid 3517 8.37 TRANSP Property 3519 Property Name: TRANSP 3521 Purpose: This property defines whether an component is transparent or 3522 not to busy time searches. This is a modification to [iCAL] "TRANSP" 3523 property in that it adds some values. 3525 Value Type: TEXT 3527 Property Parameters: Non-standard property parameters can be 3528 specified on this property. 3530 Conformance: This property can be specified in a component. 3532 Description: Time Transparency is the characteristic of an object 3533 that determines whether it appears to consume time on a calendar. 3534 Objects that consume actual time for the individual or resource 3535 associated with the calendar SHOULD be recorded as "OPAQUE", allowing 3536 them to be detected by free-busy time searches. Other objects, which 3537 do not take up the individual's (or resource's) time SHOULD be 3538 recorded as "TRANSPARENT", making them invisible to free-busy time 3539 searches. 3541 Formal Definition: The property is specified by the following 3542 notation: 3544 transp = "TRANSP" other-params ":" transvalue CRLF 3546 transvalue 3547 = "OPAQUE" ;Blocks or opaque on busy time searches. 3548 / "TRANSPARENT" ;Transparent on busy time searches. 3550 / "TRANSPARENT-NOCONFLICT" ; Transparent on busy time 3551 ; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects 3552 ; can overlap it. 3554 / "OPAQUE-NOCONFLICT" ; Opaque on busy time 3555 ; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects 3556 ; can overlap it. 3557 ; 3558 ;Default value is OPAQUE 3560 The following is an example of this property for an object that is 3561 opaque or blocks on free/busy time searches plus no other object can 3562 overlap it: 3564 TRANSP:OPAQUE-NOCONFLICT 3566 9. New Components 3568 9.1 VAGENDA Component 3570 Component Name: VAGENDA 3572 Purpose: Provide a grouping of properties that defines an agenda. 3574 Formal Definition: There are two formats of the "VAGENDA" component. 3575 (1) When it is being created, and (2) how it exists in the 3576 "VCALSTORE" component. 3578 A "VAGENDA" component in a "VCALSTORE" component is defined by the 3579 following notes and ABNF notation: 3581 CALSCALE - The value MUST BE from the "VCALSTORE" "CALSCALE" 3582 property list. The default is the first entry in the VCALSTORE 3583 CALSCALE list. 3585 CREATED - The timestamp of the calendar's create date. This is a 3586 READ ONLY property in a "VAGENDA". 3588 LAST-MODIFIED - The timestamp of any change to the "VAGENDA" 3589 properties or when any component was last created, modified, or 3590 deleted. 3592 agenda = "BEGIN" ":" "VAGENDA" CRLF 3593 agendaprop 3594 *(icalobject) ; as defined in [iCAL] 3595 "END" ":" "VAGENDA" CRLF 3597 agendaprop = *( 3598 ; The following MUST occur exactly once. 3599 ; 3600 allow-conflict / calid / calscale / created 3601 / default-charset / default-locale 3602 / default-tzid / last-modified / 3604 ; The following MUST occur at least once. 3605 ; and the value MUST NOT be empty. 3607 / owner 3609 ; The following are optional, 3610 ; and MAY occur more than once. 3612 / name / related-to / other-props / x-comp 3613 ) 3615 When creating a VAGENDA, use the following notation: 3617 agendac = "BEGIN" ":" "VAGENDA" CRLF 3618 agendacprop 3619 *(icalobject) ; as defined in [iCAL] 3620 "END" ":" "VAGENDA" CRLF 3622 agendacprop = *( 3623 ; The following MUST occur exactly once. 3624 ; 3625 allow-conflict / calid / calscale 3626 / default-charset / default-locale 3627 / default-tzid / 3629 ; The following MUST occur at least once. 3630 ; and the value MUST NOT be empty. 3631 ; 3632 / owner 3634 ; The following are optional, 3635 ; and MAY occur more than once. 3636 ; 3637 / name / related-to / other-props / x-comp 3638 ) 3640 To fetch all of the properties from the targeted "VAGENDA" component. 3641 This does not fetch any components: 3643 SELECT * FROM VAGENDA 3645 To fetch all of the properties from the targeted VAGENDA and all of 3646 the contained components, use the special '*.*' value: 3648 SELECT *.* FROM VAGENDA 3650 9.2 VCALSTORE Component 3652 Component Name: VCALSTORE 3654 Purpose: Provide a grouping of properties that defines a calendar 3655 store. 3657 Formal Definition: A "VCALSTORE" component is defined by the 3658 following table and ABNF notation. The creation of a "VCALSTORE" 3659 component is an administrative task and not part of the CAP protocol. 3661 The following are notes to some of the properties in the "VCALSTORE" 3662 component. 3664 CALSCALE - A comma separated list of CALSCALEs supported by this CS. 3665 All "VAGENDA" component calendar CALSCALE properties MUST BE from 3666 this list. This list MUST contain at least "GREGORIAN". The 3667 default for newly created "VAGENDA" components is the first entry. 3669 RELATED-TO - This is a multiple instance property. There must be a 3670 "RELATED-TO" property MUST for each of the "VAGENDA" components 3671 contained in the "VCALSTORE" component each with the "RELTYPE" 3672 parameter value set to "CHILD". Other "RELATED-TO" properties may 3673 be included. 3675 CREATED - The timestamp of the CS creation time. This is a READ 3676 ONLY property. 3678 CSID - The CSID of this calendar store. MUST NOT be empty. How 3679 this property is set in the VCALSTORE is an administrative or 3680 implementation specific issue and is not covered in CAP. This is 3681 a READ ONLY property. A suggested value is the fully qualified 3682 host name or a fully qualified virtual host name supported by the 3683 system. 3685 LAST-MODIFIED - The timestamp when the Properties of the "VCALSTORE" 3686 component were last updated or calendars were created or deleted. 3687 This is a READ ONLY PROPERTY. 3689 calstorec = "BEGIN" ":" "VCALSTORE" CRLF 3690 calstoreprop 3691 *(vagendac) 3692 "END" ":" "VCALSTORE" CRLF 3694 calstoreprop = *( 3696 ; the following MUST occur exactly once 3698 allow-conflict / calscale / calmaster 3699 / created / csid / default-charset 3700 / default-locale / default-vcars 3701 / default-tzid / last-modified 3703 ; the following are optional, 3704 ; and MAY occur more than once 3706 / name / related-to / other-props / x-comp 3707 ) 3709 To fetch all of the properties from the targeted VCALSTORE and not 3710 fetch the calendars that it contains: 3712 SELECT * FROM VCALSTORE 3714 To fetch all of the properties from the targeted "VCALSTORE" 3715 component and all of the contained calendars and all of those 3716 calendars contained properties and components, use the special '*.*' 3717 value: 3719 SELECT *.* FROM VCALSTORE 3721 9.3 VCAR Component 3723 Component Name: VCAR 3725 Purpose: Provide a grouping of calendar access rights. 3727 Formal Definition: A "VCAR" component is defined by the following 3728 notation: 3730 carc = "BEGIN" ":" "VCAR" CRLF 3731 carprop 1*rightc 3732 "END" ":" "VCAR" CRLF 3734 carprop = 1*( 3736 ; 'carid' is REQUIRED, 3737 ; but MUST NOT occur more than once 3739 carid / 3741 ; the following are OPTIONAL, 3742 ; and MAY occur more than once 3744 name / other-props 3745 ) 3747 Description: A "VCAR" component is a grouping of properties, and 3748 "VRIGHT" components, that represents access rights granted or denied 3749 to UPNs. 3751 The "CARID" property specifies the local identifier for the "VCAR" 3752 component. The "NAME" property specifies a localizable display name. 3754 Example: In the following example, the UPN "foo@example.com" is given 3755 search access to the "DTSTART" and "DTEND" VEVENT properties. No 3756 other access is specified: 3758 BEGIN:VCAR 3759 CARID:View Start and End Times 3760 NAME:View Start and End Times 3761 BEGIN:VRIGHT 3762 GRANT:foo@example.com 3763 PERMISSION:SEARCH 3764 SCOPE:SELECT DTSTART,DTEND FROM VEVENT 3765 END:VRIGHT 3766 END:VCAR 3768 In this example, all UPNs are given search access to "DTSTART" and 3769 "DTEND" properties of VEVENT components. "All CUs and UGs" are 3770 specified by the UPN value "*". Note that this enumerated UPN value 3771 is not in quotes: 3773 BEGIN:VCAR 3774 CARID:ViewStartEnd2 3775 NAME:View Start and End Times 2 3776 BEGIN:VRIGHT 3777 GRANT:* 3778 PERMISSION:SEARCH 3779 SCOPE:SELECT DTSTART,DTEND FROM VEVENT 3780 END:VRIGHT 3781 END:VCAR 3783 In these examples, full calendar access rights are given to the CAL- 3784 OWNERS(), and a hypothetical administrator is given access rights to 3785 specify calendar access rights. If no other rights are specified, 3786 only these two UPNs can specify calendar access rights: 3788 BEGIN:VCAR 3789 CARID:some-id-3 3790 NAME:Only OWNER or ADMIN Settable VCARs 3791 BEGIN:VRIGHT 3792 GRANT:CAL-OWNERS() 3793 PERMISSION:* 3794 SCOPE:SELECT * FROM VAGENDA 3795 END:VRIGHT 3796 BEGIN:VRIGHT 3797 GRANT:cal-admin@example.com 3798 PERMISSION:* 3799 SCOPE:SELECT * FROM VCAR 3800 RESTRICTION:SELECT * FROM VCAR 3801 END:VRIGHT 3802 END:VCAR 3804 In this example, rights to write, search, modify or delete calendar 3805 access rights are denied to all UPNs. This example would disable 3806 providing different access rights to the calendar store or calendar. 3807 This calendar access right should be specified with great care, as it 3808 removes the ability to change calendar access; even for the owner or 3809 administrator. It could be used by small devices that do not support 3810 the changing of any VCAR: 3812 BEGIN:VCAR 3813 CARID:VeryRestrictiveVCAR-2 3814 NAME:No CAR At All 3815 BEGIN:VRIGHT 3816 DENY:* 3817 PERMISSION:* 3818 SCOPE:SELECT * FROM VCAR 3819 END:VRIGHT 3820 END:VCAR 3822 9.4 VRIGHT Component 3824 Component Name: "VRIGHT" 3826 Purpose: Provide a grouping of properties that describe an access 3827 right (granted or denied). 3829 Formal Definition: A "VRIGHT" component is defined by the following 3830 notation: 3832 rightc = "BEGIN" ":" "VRIGHT" CRLF 3833 rightprop 3834 "END" ":" "VRIGHT" CRLF 3836 rightprop = 2*( 3838 ; either 'grant' or 'deny' MUST 3839 ; occur at least once 3840 ; and MAY occur more than once 3842 grant / deny / 3844 ; 'permission' MUST occur at least once 3845 ; and MAY occur more than once 3847 permission / 3849 ; the following are optional, 3850 ; and MAY occur more than once 3852 scope / restriction / other-props 3854 ) 3856 Description: A "VRIGHT" component is a grouping of calendar access 3857 right properties. 3859 The "GRANT" property specifies the UPN that is being granted access. 3860 The "DENY" property specifies the UPN is being denied access. The 3861 "PERMISSION" property specifies the actual permission being set. The 3862 "SCOPE" property identifies the calendar store properties, calendar 3863 properties, components, or properties to which the access right 3864 applies. The "RESTRICTION" property specifies restriction on the 3865 value that may take calendar store properties, calendar properties, 3866 calendar components, and properties after a "CREATE" or "MODIFY" 3867 command. Values MUST match all the instances of the "RESTRICTION" 3868 property to be valid. 3870 9.5 VREPLY Component 3872 Component Name: "VREPLY" 3874 Purpose: Provide a grouping of arbitrary properties and components 3875 that are the data set result from an issued command. 3877 Formal Definition: A "VREPLY" component is defined by the following 3878 notation: 3880 replyc = "BEGIN" ":" "VREPLY" CRLF 3881 any-prop-or-comp 3882 "END" ":" "VREPLY" CRLF 3884 any-prop-or-comp = ; Zero or more iana or experimental 3885 ; properties and components, in any order. 3887 Description: Provide a grouping of arbitrary properties and 3888 components that are the data set result from an issued command. 3890 A query can return a predictable set of arbitrary properties and 3891 components. This component is used by query and other commands to 3892 return data that does not fit into any other component. It may 3893 contain any valid property or component, even if they are not 3894 registered. 3896 9.6 VQUERY Component 3898 Component Name: VQUERY 3900 Purpose: A component to specify what is to be fetched from a CS. 3902 Formal Definition: A "VQUERY" component is defined by the following 3903 notation: 3905 queryc = "BEGIN" ":" "VQUERY" CRLF 3906 queryprop 3907 "END" ":" "VCAR" CRLF 3909 queryprop = 1*( 3911 ; 'queryid' is OPTIONAL but MUST NOT occur 3912 ; more than once. If the "TARGET" property 3913 ; is supplied then the "QUERYID" property 3914 ; MUST BE supplied. 3915 ; 3916 queryid / target 3918 ; 'expand' is OPTIONAL but MUST NOT occur 3919 ; more than once. 3921 expand 3923 ; the following are OPTIONAL, and MAY occur 3924 ; more than once 3925 ; 3926 / name / other-props 3928 ; the following MUST occur at least once. 3929 ; 3930 / query 3932 ) 3934 Description: A "VQUERY" contains properties that specify which 3935 properties and components the CS is requested to return during a 3936 SEARCH command. 3938 The "QUERYID" property specifies the local identifier for a stored 3939 "VQUERY" component. The "NAME" property specifies a localizable 3940 display name of a stored "VQUERY" component. Normally "NAME" and 3941 "QUERYID" properties are used when looking for a correct stored 3942 "VQUERY" component, or when storing a "VQUERY" component. 3944 For a search, if the "TARGET" property is supplied in a "VQUERY" 3945 component, then the CS is to search for the query in the calid 3946 supplied by the "TARGET" property value. 3948 For a create the "TARGET" property MUST NOT be supplied as the 3949 destination container is already supplied in the "TARGET" property of 3950 the "VCALENDAR" component. 3952 For examples, see Section 6.1.1. 3954 10. Commands and Responses 3956 CAP commands and responses are described in this section. 3958 10.1 CAP Commands (CMD) 3960 All commands are send using the CMD property. 3962 Property Name: CMD 3964 Purpose: The property defines the command to be sent. 3966 Value Type: TEXT 3968 Property Parameters: Non-standard, id, localize, latency, action or 3969 options. 3971 Conformance: This property is the method used to specify the commands 3972 to a CS and can exist in any object sent to the CS. 3974 Description: All of the command to the CS are supplied in this 3975 property. The "OPTIONS" parameter is overloaded and its meaning is 3976 dependent on the CMD value supplied. 3978 Formal Definition: The property is defined by the following notation: 3980 cmd = "CMD" ( 3981 / abort-cmd 3982 / continue-cmd 3983 / create-cmd 3984 / delete-cmd 3985 / generate-uid-cmd 3986 / get-capability-cmd 3987 / identify-cmd 3988 / modify-cmd 3989 / move-cmd 3990 / reply-cmd 3991 / search-cmd 3992 / set-locale-cmd 3993 / other-cmd 3994 ) CRLF 3996 other-cmd ; Any command published as an RFC or any 3997 ; vendor specific "x-" command. 3999 option-value = paramtext ; As defined in [iCAL] 4001 Calendaring commands allow a CUA to directly manipulate a calendar. 4003 Calendar access rights can be granted or denied for any commands. 4005 10.1.1 Bounded Latency 4007 A CAP command can have an associated maximum latency time by 4008 specifying the "LATENCY" parameter. If the command is unable to be 4009 completed in the specified amount of time (as specified by the 4010 "LATENCY" parameter value), then a "TIMEOUT" command MUST BE sent on 4011 the same channel to which there MUST BE a an "ABORT" or a "CONTINUE" 4012 command reply. If the CUA initiated the original command, then the 4013 CS would issue the "TIMEOUT" command and the CUA would then have to 4014 issue an "ABORT" or "CONTINUE" command. If the CS initiated the 4015 original command then the CUA would have to issue the "TIMEOUT" and 4016 the CS would send the "ABORT" or "CONTINUE". 4018 Upon receiving an "ABORT" command, the command must then be 4019 terminated. Only the "ABORT", "TIMEOUT", "REPLY, and "CONTINUE" 4020 commands can not be aborted. The "ABORT", "TIMEOUT", and "REPLY" 4021 commands MUST NOT have latency set. 4023 Upon receiving a "CONTINUE" command the work continues as if it had 4024 not been delayed or stopped. Note that a new latency time MAY BE 4025 included in a "CONTINUE" command indicating to continue the original 4026 command until the "LATENCY" parameter value expires or the results of 4027 the original command can be returned. 4029 Both the "LATENCY" parameter and the "ACTION" parameter MUST BE 4030 supplied to any "CMD" property, or nether can be added to the "CMD" 4031 property. The "LATENCY" parameter MUST BE set to the maximum latency 4032 time in seconds. The "ACTION" parameter accepts the following 4033 values: "ASK" and "ABORT" parameters. 4035 If the maximum latency time is exceeded and the "ACTION" parameter is 4036 set to the "ASK" value, then "TIMEOUT" command MUST BE sent. 4037 Otherwise if the "ACTION" parameter is set to the "ABORT" value then 4038 the command MUST BE terminated and return a REQUEST-STATUS code of 4039 2.0.3 for the original command. 4041 If a CS can both start sending the reply to a command and guarantee 4042 that all of the results can be sent from a command (short of 4043 something like network or power failure) prior to the "LATENCY" 4044 timeout value then the "LATENCY" time has not expired. 4046 Example: 4048 In this example the initiator asks for the listeners capabilities. 4050 I: Content-Type: text/calendar 4051 I: 4052 I: BEGIN:VCALENDAR 4053 I: VERSION:2.0 4054 I: PRODID:The CUA's PRODID 4055 I: CMD;ID=xyz12346;LATENCY=3;ACTION=ask:GET-CAPABILITY 4056 I: END:VCALENDAR 4058 # After 3 seconds 4060 L: Content-Type: text/calendar 4061 L: 4062 L: BEGIN:VCALENDAR 4063 L: PRODID:-//someone's prodid 4064 L: VERSION:2.0 4065 L: CMD;ID=xyz12346:TIMEOUT 4066 L: END:VCALENDAR 4068 In order to continue and give the CS more time then the CUA would 4069 issue a "CONTINUE" command: 4071 I: Content-Type: text/calendar 4072 I: 4073 I: BEGIN:VCALENDAR 4074 I: VERSION:2.0 4075 I: PRODID:-//someone's prodid 4076 I: CMD;ID=xyz12346;LATENCY=3;ACTION=ask:CONTINUE 4077 I: END:VCALENDAR 4079 L: Content-Type: text/calendar 4080 L: 4081 L: BEGIN:VCALENDAR 4082 L: VERSION:2.0 4083 L: PRODID:-//someone's prodid 4084 L: CMD;ID=xyz12346:REPLY 4085 L: BEGIN:VREPLY 4086 L: REQUEST-STATUS:2.0.3;Continued for 3 more seconds 4087 L: END:VREPLY 4088 L: END:VCALENDAR 4090 To abort the command and not wait any further then issue an "ABORT" 4091 command: 4093 I: Content-Type: text/calendar 4094 I: 4095 I: BEGIN:VCALENDAR 4096 I: VERSION:2.0 4097 I: PRODID:-//someone's prodid 4098 I: CMD;ID=xyz12346:ABORT 4099 I: END:VCALENDAR 4101 # Which would result in a 2.0.3 reply. 4103 L: Content-Type: text/calendar 4104 L: 4105 L: BEGIN:VCALENDAR 4106 L: VERSION:2.0 4107 L: PRODID:-//someone's prodid 4108 L: CMD;ID=xyz12346:REPLY 4109 L: BEGIN:VREPLY 4110 L: REQUEST-STATUS:2.0.3;Aborted As Requested. 4111 L: END:VREPLY 4112 L: END:VCALENDAR 4114 10.1.2 ABORT Command 4116 CMD: ABORT 4118 Purpose: The "ABORT" command is sent to request that the named or 4119 only in process command be aborted. Latency MUST not be supplied 4120 with the "ABORT" command. 4122 Formal Definition: An "ABORT" command is defined by the following 4123 notation: 4125 abort-cmd = abortparam ":" "ABORT" 4127 abortparam = *( 4129 ; the following are optional, 4130 ; but MUST NOT occur more than once 4132 id-param 4133 / localize-param 4135 ; the following is optional, 4136 ; and MAY occur more than once 4138 / other-params 4140 ) 4142 The REPLY of any "ABORT" command is: 4144 abort-reply = "BEGIN" ":" "VCALENDAR" CRLF 4145 calprops 4146 abort-vreply 4147 "END" ":" "VCALENDAR" CRLF 4149 abort-vreply = "BEGIN" ":" "VREPLY" CRLF 4150 request-status 4151 other-props 4152 "END" ":" "VREPLY" CRLF 4154 10.1.3 CONTINUE Command 4156 CMD: CONTINUE 4157 Purpose: The "CONTINUE" command is only sent after a "TIMEOUT" 4158 command has been received to inform the other end of the session to 4159 resume working on a command. 4161 Formal Definition: A "CONTINUE" command is defined by the following 4162 notation: 4164 continue-cmd = continueparam ":" "CONTINUE" 4166 continueparam = *( 4168 ; the following are optional, 4169 ; but MUST NOT occur more than once 4171 id-param 4172 / localize-param 4173 / latency-param 4175 ; the following MUST occur exactly once and only 4176 ; when the latency-param has been supplied and 4177 ; MUST NOT be supplied if the latency-param is 4178 ; not supplied. 4180 / action-param 4182 ; the following are optional, 4183 ; and MAY occur more than once 4185 / other-params 4186 ) 4188 The REPLY of any "CONTINUE" command is: 4190 continue-reply = "BEGIN" ":" "VCALENDAR" CRLF 4191 calprops 4192 continue-vreply 4193 "END" ":" "VCALENDAR" CRLF 4195 continue-vreply = "BEGIN" ":" "VREPLY" CRLF 4196 request-status 4197 other-props 4198 "END" ":" "VREPLY" CRLF 4200 10.1.4 CREATE Command 4202 CMD: CREATE 4204 Purpose: The "CREATE" command is used to create one or more 4205 iCalendar objects in the store in the "BOOKED" or "UNPROCESSED" 4206 state. 4208 A CUA MAY send a "CREATE" command to a CS. The "CREATE" command MUST 4209 BE implemented by all CSs. 4211 The CS MUST NOT send a "CREATE" command to any CUA. 4213 Formal Definition: A "CREATE" command is defined by the following 4214 notation: 4216 create-cmd = createparam ":" "CREATE" 4218 createparam = *( 4220 ; the following are optional, 4221 ; but MUST NOT occur more than once 4223 id-param 4224 / localize-param 4225 / latency-param 4227 ; the following MUST occur exactly once and only 4228 ; when the latency-param has been supplied and 4229 ; MUST NOT be supplied if the latency-param is 4230 ; not supplied. 4232 / action-param 4234 ; the following is optional, 4235 ; and MAY occur more than once 4237 / other-params 4238 ) 4240 Response: 4242 One iCalendar object per TARGET property MUST BE returned. 4244 The REPLY of any "CREATE" command is: 4246 Restriction Table for the iCalendar section of a reply that contains 4247 an iCalendar object is any valid [iTIP] response plus any from this 4248 ABNF: 4250 create-reply = "BEGIN" ":" "VCALENDAR" CRLF 4251 creply-props 4252 1*(create-vreply) 4253 "END" ":" "VCALENDAR" CRLF 4255 create-vreply = "BEGIN" ":" "VREPLY" CRLF 4256 created-id 4257 request-status 4258 other-props 4259 "END" ":" "VREPLY" CRLF 4261 ; Where the id is appropriate for the 4262 ; type of object created: 4263 ; 4264 ; VAGENDA = calid 4265 ; VALARM = sequence 4266 ; VCAR = carid 4267 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 4268 ; VQUERY = queryid 4269 ; VTIMEZONE = tzid 4270 ; x-component = x-id 4271 ; 4272 created-id = ( calid / carid / uid / queryid / 4273 tzid / sequence / x-id) 4275 x-id = ; An ID for an x-component. 4277 creply-props = 4*( 4278 ; These are REQUIRED and MUST NOT occur 4279 ; more than once. 4280 ; 4281 prodid /version / target / reply-cmd 4283 ; These are optional, and may occur more 4284 ; than once. 4285 ; 4286 other-props 4288 For a "CREATE" command the "TARGET" property specifies the containers 4289 where the components will be created. 4291 If the iCalendar object being created does not have a "METHOD" 4292 property, then is not an [iTIP] object, then its state will be 4293 "BOOKED". Use the "DELETE" command to set the state of an object to 4294 the "DELETED" state (tagged for deletion). A CUA can not use the 4295 "CREATE" command to create an object in the "DELETED" state. 4297 If the intention is to book an [iTIP] object then the "METHOD" 4298 property MUST NOT BE supplied. Otherwise any [iTIP] object MUST have 4299 a valid [iTIP] "METHOD" property value and it is a scheduling request 4300 being deposited into the CS and will have its state set to 4301 "UNPROCESSED" state. 4303 ABNF for a "CREATE" object is: 4305 create-object = "BEGIN" ":" "VCALENDAR" CRLF 4306 ; If 'calprops' contain the "METHOD" property 4307 ; then this 'create-object' component MUST 4308 ; conform to [iTIP] restrictions. 4309 ; 4310 ; calprops MUST include 'create-cmd' 4311 ; 4312 calprops 4313 other-props 4314 1*(create-comp) 4315 "END" ":" "VCALENDAR" CRLF 4317 ; NOTE: The 'VCALSTORE' component is not included in 4318 ; 'create-comp' as it is out of scope for CAP to create 4319 ; a new CS. 4320 ; 4321 create-comp = agendac / carc / queryc 4322 / timezonec / freebusyc 4323 / eventc / todoc / journalc 4324 / iana-comp / x-component 4326 In the following example two new top level "VAGENDA" components are 4327 created. Note that the "CSID" value of the server is 4328 cal.example.com which is where the new "VAGENDA" components are 4329 going to be created. 4331 C: Content-Type: text/calendar 4332 C: 4333 C: BEGIN:VCALENDAR 4334 C: PRODID:-//someone's prodid 4335 C: VERSION:2.0 4336 C: CMD;ID=creation01:CREATE 4337 C: TARGET:cal.example.com 4338 C: BEGIN:VAGENDA <- data for 1st new calendar 4339 C: CALID:relcalz1 4340 C: NAME;LANGUAGE=en_US:Bill's Soccer Team 4341 C: OWNER:bill 4342 C: CALMASTER:mailto:bill@example.com 4343 C: TZID:US/Pacific 4344 C: END:VAGENDA 4345 C: BEGIN:VAGENDA <- data for 2nd new calendar 4346 C: CALID:relcalz2 4347 C: NAME;LANGUAGE=EN-us:Mary's personal calendar 4348 C: OWNER:mary 4349 C: CALMASTER:mailto:mary@example.com 4350 C: TZID:US/Pacific 4351 C: END:VAGENDA 4352 C: END:VCALENDAR 4354 S: Content-Type: text/calendar 4355 S: 4356 S: BEGIN:VCALENDAR 4357 S: VERSION:2.0 4358 S: PRODID:-//someone's prodid 4359 S: CMD;ID=creation01:REPLY 4360 S: TARGET:cal.example.com 4361 S: BEGIN:VREPLY <- Reply for 1st calendar create 4362 S: CALID:relcalz1 4363 S: REQUEST-STATUS:2.0 4364 S: END:REPLY 4365 S: BEGIN:VREPLY <- Reply for 2nd calendar create 4366 S: CALID:relcalz2 4367 S: REQUEST-STATUS:2.0 4368 S: END:VREPLY 4369 S: END:VCALENDAR 4371 To create a new component in multiple containers simply name all of 4372 the containers in the "TARGET" in the create command. Here a new 4373 "VEVENT" component is created in two TARGET components. In this 4374 example, the "VEVENT" component is one new [iTIP] "REQUEST" to be 4375 stored in two calendars. The results would be iCalendar objects that 4376 conform to the [iTIP] replies as defined in [iTIP]. 4378 This example shows two [iTIP] "VEVENT" components being created in 4379 each of the two supplied "TARGET" properties and as it contains the 4380 "METHOD" property they will be stored in the "UNPROCESSED" state: 4382 C: Content-Type: text/calendar 4383 C: 4384 C: BEGIN:VCALENDAR 4385 C: VERSION:2.0 4386 C: PRODID:-//someone's prodid 4387 C: CMD;ID=creation02:CREATE 4388 C: METHOD:REQUEST 4389 C: TARGET:relcalz1 4390 C: TARGET:relcalz2 4391 C: BEGIN:VEVENT 4392 C: DTSTART:20030307T180000Z 4393 C: UID:FirstInThisExample-1 4394 C: DTEND:20030307T190000Z 4395 C: SUMMARY:Important Meeting 4396 C: END:VEVENT 4397 C: BEGIN:VEVENT 4398 C: DTSTART:20040307T180000Z 4399 C: UID:SecondInThisExample-2 4400 C: DTEND:20040307T190000Z 4401 C: SUMMARY:Important Meeting 4402 C: END:VEVENT 4403 C: END:VCALENDAR 4405 The CS could send the "VREPLY" commands in separate MIME objects, one 4406 per supplied "TARGET" property value. 4408 S: Content-Type: text/calendar 4409 S: 4410 S: BEGIN:VCALENDAR 4411 S: VERSION:2.0 4412 S: PRODID:-//someone's prodid 4413 S: CMD;ID=creation02:REPLY 4414 S: TARGET:relcalz1 <- 1st TARGET listed. 4415 S: BEGIN:REPLY <- Reply for 1st VEVENT create in 1st TARGET. 4416 S: UID:FirstInThisExample-1 4417 S: REQUEST-STATUS:2.0 4418 S: END:VREPLY 4419 S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 1st TARGET. 4420 S: UID:SecondInThisExample-2 4421 S: REQUEST-STATUS:2.0 4422 S: END:VREPLY 4423 S: END:VCALENDAR 4425 And the second reply for the 2nd TARGET: 4427 S: Content-Type: text/calendar 4428 S: 4429 S: BEGIN:VCALENDAR 4430 S: VERSION:2.0 4431 S: PRODID:-//someone's prodid 4432 S: CMD;ID=creation02:REPLY 4433 S: TARGET:relcalz2 <- 2nd TARGET listed 4434 S: BEGIN:REPLY <- Reply for 1st VEVENT create in 2nd TARGET. 4435 S: UID:FirstInThisExample-1 4436 S: REQUEST-STATUS:2.0 4437 S: END:VREPLY 4438 S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 2nd TARGET. 4439 S: UID:SecondInThisExample-2 4440 S: REQUEST-STATUS:2.0 4441 S: END:VREPLY 4442 S: END:VCALENDAR 4444 10.1.5 DELETE Command 4446 CMD: DELETE 4448 Purpose: The "DELETE" command physically removes the QUERY result 4449 from the store or marks it for deletion. 4451 A CUA MAY send a "DELETE" command to a CS. The "DELETE" command MUST 4452 BE implemented by all CSs. 4454 The CS MUST NOT send a "DELETE" command to any CUA. 4456 Formal Definition: A "DELETE" command is defined by the following 4457 notation: 4459 delete-cmd = deleteparam ":" "DELETE" 4461 deleteparam = *( 4463 ; the following are optional, 4464 ; but MUST NOT occur more than once 4465 ; 4466 id-param 4467 / localize-param 4468 / latency-param 4469 / option-param "MARK" 4471 ; The following MUST occur exactly once and only 4472 ; when the latency-param has been supplied and 4473 ; MUST NOT be supplied if the latency-param is 4474 ; not supplied. 4475 ; 4476 / action-param 4478 ; the following is optional, 4479 ; and MAY occur more than once 4480 ; 4481 / other-params 4482 ) 4484 The "DELETE" command is used to delete calendars or components. The 4485 included "VQUERY" component(s) specifies the container(s) to delete. 4487 If a component is to be marked for delete and not physically removed, 4488 then include the "OPTIONS" parameter with its value set to the "MARK" 4489 value in order to alter its state to "DELETED". 4491 When components are deleted, only the top most component "REQUEST- 4492 STATUS" properties are returned. No "REQUEST-STATUS" properties are 4493 returned for components inside of the selected components. There 4494 MUST BE one "VREPLY" component returned for each object that is 4495 deleted or marked for delete. Note that if no "VREPLY" components 4496 are returned then nothing matched and nothing was deleted. 4498 Restriction Table for the "REPLY" command for any "DELETE" command. 4500 delete-reply = "BEGIN" ":" "VCALENDAR" CRLF 4501 calprops ; MUST include 'reply-cmd' 4502 *(delete-vreply) 4503 "END" ":" "VCALENDAR" CRLF 4505 delete-vreply = "BEGIN" ":" "VREPLY" CRLF 4506 deleted-id 4507 request-status 4508 "END" ":" "VREPLY" CRLF 4510 ; Where the id is appropriate for the 4511 ; type of object deleted: 4512 ; 4513 ; VAGENDA = calid 4514 ; VCAR = carid 4515 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 4516 ; VQUERY = queryid 4517 ; ALARM = sequence 4518 ; VTIMEZONE = tzid 4519 ; x-component = x-id 4520 ; An instance = uid recurid 4521 ; 4522 deleted-id = ( calid / carid / uid / uid recurid 4523 / queryid / tzid / sequence / x-id ) 4525 Example to delete a "VEVENT" component with "UID" value of 4526 'abcd12345' from the calendar "relcald-22" from the current CS: 4528 C: Content-Type: text/calendar 4529 C: 4530 C: BEGIN:VCALENDAR 4531 C: TARGET:relcalid-22 4532 C: CMD;ID:"random but unique per CUA":DELETE 4533 C: BEGIN:VQUERY 4534 C: QUERY:SELECT VEVENT FROM VAGENDA WHERE UID = 'abcd12345' 4535 C: END:VQUERY 4536 C: END:VCALENDAR 4538 S: BEGIN:VCALENAR 4539 S: TARGET:relcalid-22 4540 S: CMD;ID:"random but unique per CUA":REPLY 4541 S: BEGIN:VREPLY 4542 S: UID:abcd12345 4543 S: REQUEST-STATUS:3.0 4544 S: END:VREPLY 4545 S: END:VCALENDAR 4547 One or more iCalendar objects will be returned that contain a 4548 "REQUEST-STATUS" properties for the deleted components. There could 4549 have been more than one component deleted, Any booked and any number 4550 of unprocessed [iTIP] scheduling components that matched the QUERY 4551 value in the above example. Each unique "METHOD" property value that 4552 was deleted from the store MUST BE in a separate iCalendar object. 4553 This is because only one "METHOD" property is allowed in a single 4554 "VCALENDAR" BEGIN/END block. 4556 10.2 GENERATE-UID Command 4558 CMD: GENERATE-UID 4560 Purpose: The "GENERATE-UID" command returns one or more unique 4561 identifiers which MUST BE globally unique. 4563 The "GENERATE-UID" command MAY BE sent to any CS. The "GENERATE-UID" 4564 command MUST BE implemented by all CSs. 4566 The "GENERATE-UID" command MUST NOT be sent to a CUA. 4568 Formal Definition: A "GENERATE-UID" command is defined by the 4569 following notation: 4571 generate-uid-cmd = genuidparam ":" "GENERATE-UID" 4573 genuidparam = *( 4574 ; The following are optional, 4575 ; but MUST NOT occur more than once. 4577 id-param 4578 / localize-param 4579 / latency-param 4581 ; The following MUST occur exactly once and only 4582 ; when the latency-param has been supplied and 4583 ; MUST NOT be supplied if the latency-param is 4584 ; not supplied. 4586 / action-param 4588 ; The following is optional, 4589 ; and MAY occur more than once. 4591 / other-params 4593 ; The following MUST BE supplied exactly once. 4594 ; The value specifies the number of UIDs to 4595 ; be returned. 4597 / option-param posint1 4599 ) 4601 Response: 4603 gen-reply = "BEGIN" ":" "VCALENDAR" CRLF 4604 calprops ; Which MUST include 'reply-cmd' 4605 1*(gen-vreply) 4606 "END" ":" "VCALENDAR" CRLF 4608 gen-vreply = "BEGIN" ":" "VREPLY" CRLF 4609 1*(uid) 4610 request-status 4611 "END" ":" "VREPLY" CRLF 4613 Example: 4615 C: BEGIN:VCALENDAR 4616 C: VERSION:2.0 4617 C: PRODID:-//someone's prodid 4618 C: CMD;ID=unique-per-cua-124;OPTIONS=5:GENERATE-UID 4619 C: END:VCALENDAR 4620 S: Content-Type: text/calendar 4621 S: 4622 S: BEGIN:VCALENDAR 4623 S: VERSION:2.0 4624 S: PRODID:-//someone's prodid 4625 S: CMD;ID=unique-per-cua-124:REPLY 4626 S: BEGIN:VREPLY 4627 S: UID:20011121T120000Z-12340@cal.example.com 4628 S: UID:20011121T120000Z-12341@cal.example.com 4629 S: UID:20011121T120000Z-12342@cal.example.com 4630 S: UID:20011121T120000Z-12343@cal.example.com 4631 S: UID:20011121T120000Z-12344@cal.example.com 4632 S: REQUEST-STATUS:2.0 4633 S: END:VREPLY 4634 S: END:VCALENDAR 4636 10.3 GET-CAPABILITY Command 4638 CMD: GET-CAPABILITY 4640 Purpose: The "GET-CAPABILITY" command returns the capabilities of the 4641 other end point of the session. 4643 A CUA MUST send a "GET-CAPABILITY" command to a CS after the initial 4644 connection. A CS MUST send a "GET-CAPABILITY" command to a CUA after 4645 the initial connection. The "GET-CAPABILITY" command and reply MUST 4646 BE implemented by all CSs and CUAs. 4648 Formal Definition: A "GET-CAPABILITY" command is defined by the 4649 following notation: 4651 get-capability-cmd = capibiltyparam ":" "GET-CAPABILITY" 4653 capibiltyparam = *( 4655 ; the following are optional, 4656 ; but MUST NOT occur more than once 4657 ; 4658 id-param / localize-param / latency-param 4660 ; the following MUST occur exactly once and only 4661 ; when the latency-param has been supplied and 4662 ; MUST NOT be supplied if the latency-param is 4663 ; not supplied. 4664 ; 4665 / action-param 4667 ; the following is optional, 4668 ; and MAY occur more than once 4669 ; 4670 / other-params 4671 ) 4673 Response: 4675 The "GET-CAPABILITY" command returns information about the Calendar 4676 other end of the session given the current state of the connection. 4677 The values returned may differ depending on current user identify and 4678 the security level of the connection. 4680 Client implementations SHOULD NOT require any capability element 4681 beyond those defined in this specification or future RFC publications 4682 , and MAY ignore any nonstandard, experimental capability elements. 4683 The "GET-CAPABILITY" reply may return different results depending on 4684 the UPN and if the UPN is authenticated. 4686 When sending a reply to a "GET-CAPABILITY" command, all of these MUST 4687 BE supplied. The following properties are returned in response to a 4688 "GET-CAPABILITY" command: 4690 cap-vreply = "BEGIN" ":" "VCALENDAR" CRLF 4691 ; The following properties may be in any order. 4692 ; 4693 prodid 4694 version 4695 reply-cmd 4696 other-props 4697 "BEGIN" ":" "VREPLY" CRLF 4698 ; The following properties may be in any order. 4699 ; 4700 cap-version 4701 car-level 4702 components 4703 stores-expanded 4704 maxdate 4705 mindate 4706 itip-version 4707 max-comp-size 4708 multipart 4709 query-level 4710 recur-accepted 4711 recur-expand 4712 recur-limit 4713 other-props 4714 "END" ":" "VREPLY" CRLF 4715 "END" ":" "VCALENDAR" CRLF 4717 Example: 4719 I: Content-Type: text/calendar 4720 I: 4721 I: BEGIN:VCALENDAR 4722 I: VERSION:2.0 4723 I: PRODID:-//someone's prodid 4724 I: CMD;ID=unique-per-cua-125:GET-CAPABILITY 4725 I: END:VCALENDAR 4727 L: Content-Type: text/calendar 4728 L: 4729 L: BEGIN:VCALENDAR 4730 L: VERSION:2.0 4731 L: PRODID:-//someone's prodid 4732 L: CMD;ID=unique-per-cua-125:REPLY 4733 L: BEGIN:VREPLY 4734 L: CAP-VERSION:1.0 4735 L: PRODID:The CS prodid 4736 L: QUERY-LEVEL:CAL-QL-1 4737 L: CAR-LEVEL:CAR-FULL-1 4738 L: MAXDATE:99991231T235959Z 4739 L: MINDATE:00000101T000000Z 4740 L: MAX-COMPONENT-SIZE:0 4741 L: COMPONENTS:VCALENDAR,VTODO,VJOURNAL,VEVENT,VCAR, 4742 L: VALARM,VFREEBUSY,VTIMEZONE,STANDARD,DAYLIGHT,VREPLY 4743 L: ITIP-VERSION:2446 4744 L: RECUR-ACCEPTED:TRUE 4745 L: RECUR-EXPAND:TRUE 4746 L: RECUR-LIMIT:0 4747 L: STORES-EXPANDED:FALSE 4748 L: X-INET-PRIVATE-COMMANDS:1.0 4749 L: END:VREPLY 4750 L: END:VCALENDAR 4752 10.4 IDENTIFY Command 4754 CMD: IDENTIFY 4756 Purpose: The "IDENTIFY" command allows the CUA to set a new identity 4757 to be used for calendar access. 4759 A CUA MAY send an "IDENTIFY" command to a CS. The "IDENTIFY" command 4760 MUST BE implemented by all CSs. A CS implementation MAY reject all 4761 "IDENTIFY" commands. 4763 The CS MUST NOT send a "IDENTIFY" command to any CUA. 4765 Formal Definition: A "IDENTIFY" command is defined by the following 4766 notation: 4768 identify-cmd = identifyparam ":" "IDENTIFY" 4770 identifyparam = *( 4772 ; the following are optional, 4773 ; but MUST NOT occur more than once 4775 id-param 4776 / localize-param 4777 / latency-param 4779 ; the following MUST occur exactly once and only 4780 ; when the latency-param has been supplied and 4781 ; MUST NOT be supplied if the latency-param is 4782 ; not supplied. 4784 / action-param 4786 ; the following is optional, 4787 ; and MAY occur more than once 4789 / other-params 4790 ; The value is the UPN of the requested 4791 ; identity. If not supplied it is a request 4792 ; to return to the original authenticated identity. 4794 / option-param upn 4796 ) 4798 Response: 4800 "REQUEST-STATUS" with only one of the following 4801 request-status codes: 4803 2.0 Successful. 4805 6.4 Identity not permitted. VCAR restriction. 4807 The CS determines through an internal mechanism if the credentials 4808 supplied at authentication permit the operation as the selected 4809 identity. If they do, the session assumes the new identity, 4810 otherwise a security error is returned. 4812 Example: 4814 C: Content-Type: text/calendar 4815 C: 4816 C: BEGIN:VCALENDAR 4817 C: VERSION:2.0 4818 C: PRODID:-//someone's prodid 4819 C: CMD;ID=unique-per-cua-999;OPTIONS=newUserId:IDENTIFY 4820 C: END:VCALENDAR 4822 S: Content-Type: text/calendar 4823 S: 4824 S: BEGIN:VCALENDAR 4825 S: VERSION:2.0 4826 S: PRODID:-//someone's prodid 4827 S: BEGIN:VREPLY 4828 S: REQUEST-STATUS:2.0;Request Approved 4829 S: END:VREPLY 4830 S: END:VCALENDAR 4832 Or if denied: 4834 S: Content-Type: text/calendar 4835 S: 4837 S: BEGIN:VCALENDAR 4838 S: PRODID:-//someone's prodid 4839 S: VERSION:2.0 4840 S: BEGIN:VREPLY 4841 S: REQUEST-STATUS:6.4;Request Denied 4842 S: END:VREPLY 4843 S: END:VCALENDAR 4845 And for the CUA to return to its original authenticated identity 4846 the OPTIONS parameter is omitted: 4848 C: Content-Type: text/calendar 4849 C: 4850 C: BEGIN:VCALENDAR 4851 C: VERSION:2.0 4852 C: PRODID:-//someone's prodid 4853 C: CMD;ID=unique-per-cua-995:IDENTIFY 4854 C: END:VCALENDAR 4856 The CS may accept (2.0) or deny (6.4) the request to return to the 4857 original identity. 4859 If a CS considers the "IDENTIFY" command an attempt to violate 4860 security, the CS MAY terminate the [BEEP] session without any further 4861 notice to the CUA after sending the "REQUEST-STATUS" 6.4 reply. 4863 10.5 MODIFY Command 4865 CMD: MODIFY 4867 Purpose: The "MODIFY" command is used to modify existing components. 4869 A CUA MAY send a "MODIFY" command to a CS. The "MODIFY" command MUST 4870 BE implemented by all CSs. 4872 The CS MUST NOT send a "MODIFY" command to any CUA. 4874 Formal Definition: A "MODIFY" command is defined by the following 4875 notation: 4877 modify-cmd = modifyparam ":" "MODIFY" 4879 modifyparam = *( 4881 ; the following are optional, 4882 ; but MUST NOT occur more than once 4884 id-param 4885 / localize-param 4886 / latency-param 4888 ; the following MUST occur exactly once and only 4889 ; when the latency-param has been supplied and 4890 ; MUST NOT be supplied if the latency-param is 4891 ; not supplied. 4893 / action-param 4895 ; the following is optional, 4896 ; and MAY occur more than once 4898 / other-params 4900 ) 4902 The "MODIFY" command is used to modify existing components. The 4903 TARGET property specifies the calendars where the components exist 4904 that are going to be modified. 4906 The format of the request is two components inside of "VCALENDAR" 4907 component: 4909 BEGIN:VCALENDAR 4910 ... 4911 BEGIN:VQUERY 4912 ... 4913 END:VQUERY 4914 BEGIN:XXX 4915 ...old-values... 4916 END:XXX 4917 BEGIN:XXX 4918 ...new-values... 4919 END:XXX 4920 END:CALENDAR 4922 The "VQUERY" component selects the components that are to be 4923 modified. 4925 Where "XXX" above is a named component type (VEVENT, VTODO, ...). 4926 Both the old and new components MUST BE of the same type. 4928 The old-values is a component and the contents of that component are 4929 going to change and may contain information that helps uniquely 4930 identify the original component (SEQUENCE in the example below). If 4931 the CS can not find a component that matches the QUERY and does not 4932 have at least all of the OLD-VALUES, then a 6.1 error is returned. 4934 The new-values is a component of the same type as old-values and new- 4935 values contains the new data for each selected component. Any data 4936 that is in old-values and not in new-values is deleted from the 4937 selected component. Any values in new-values that was not in old- 4938 values is added to the component. 4940 In this example the "VEVENT" component with a "UID" property value of 4941 'unique-58' has; the "LOCATION" property and "LAST-MODIFIED" property 4942 changed, the "VALARM" component with the "SEQUENCE" property with a 4943 value of "3" has its "TRIGGER" property disabled, the "X-LOCAL" 4944 property is removed from the "VEVENT" component, and a "COMMENT" 4945 property is added. 4947 Because "SEQUENCE" property is used to locate the "VALARM" component 4948 in this example, both the old-values and the new-values contain the 4949 "SEQUENCE" property with a value of "3" and if the "SEQUENCE" 4950 property were to be left out of new-values, it would have been 4951 deleted. 4953 Example: 4955 C: Content-Type: text/calendar 4956 C: 4957 C: BEGIN:VCALENDAR 4958 C: VERSION:2.0 4959 C: PRODID:-//someone's prodid 4960 C: TARGET:my-cal 4961 C: CMD:ID=unique-mod:MODIFY 4962 C: BEGIN:VQUERY <- Query to select data set. 4963 C: QUERY:SELECT * FROM VEVENT WHERE UID = 'unique-58' 4964 C: END:VQUERY 4965 C: BEGIN:VEVENT <- Start of old data. 4966 C: LOCATION:building 3 4967 C: LAST-MODIFIED:20020101T123456Z 4968 C: X-LOCAL:some private stuff 4969 C: BEGIN:VALARM 4970 C: SEQUENCE:3 4971 C: TRIGGER;RELATED=END:PT5M 4972 C: END:VALARM 4973 C: END:VEVENT 4974 C: BEGIN:VEVENT <- End of new data. 4975 C: LOCATION:building 4 4976 C: LAST-MODIFIED:20020202T010203Z 4977 C: COMMENT:Ignore global trigger. 4978 C: BEGIN:VALARM 4979 C: SEQUENCE:3 4980 C: TRIGGER;ENABLE=FALSE:RELATED=END:PT5M 4981 C: END:VALARM 4982 C: END:VEVENT 4984 The "X-LOCAL" property was not supplied in the new-values, so it was 4985 deleted. The "LOCATION" property value was altered, as was the 4986 "LAST-MODIFIED" value. The "VALARM" component with a "SEQUENCE" 4987 property value of "3" had its "TRIGGER" property disabled, and the 4988 "SEQUENCE" property value did not change so it was not effected. The 4989 "COMMENT" property was added. 4991 When it comes to inline ATTACHMENTs, the CUA only needs to uniquely 4992 identify the contents of the ATTACHMENT value in the old-values in 4993 order to delete them. When the CS compares the attachment data it is 4994 compared in its binary form. The ATTACHMENT value supplied by the 4995 CUA MUST BE valid encoded information. 4997 For example, to delete the same huge inline attachment from every 4998 VEVENT in 'my-cal' that has an "ATTACH" property value with the old- 4999 values: 5001 BEGIN:VCALENDAR 5002 VERSION:2.0 5003 PRODID:-//someone's prodid 5004 TARGET:my-cal 5005 CMD:MODIFY 5006 BEGIN:VQUERY 5007 QUERY:SELECT ATTACH FROM VEVENT 5008 END:VQUERY 5009 BEGIN:VEVENT 5010 ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY: 5011 MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U 5012 EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE 5013 ...< remainder of attachment data NOT supplied >.... 5014 END:VEVENT 5015 BEGIN:VEVENT 5016 END:VEVENT 5017 END:VCALENDAR 5019 Above the new-values is empty, so everything in the old-values is 5020 deleted. 5022 Furthermore, the following additional restrictions apply: 5024 1. One can not change the "UID" property of a component. 5026 2. If a contained component is changed inside of a selected 5027 component, and that contained component has multiple instances, 5028 then old-values MUST contain information that uniquely identifies 5029 the instance or instances that are changing. It is valid to 5030 change more than one. As all contained components that match 5031 old-values will be modified. In the first modify example above, 5032 if "SEQUENCE" properties were to be deleted from both the old- 5033 values and new-values, then all "TRIGGER" properties that matched 5034 the old-values in all "VALARM" components in the selected 5035 "VEVENT" components would be disabled. 5037 3. The result of the modify MUST BE a valid iCalendar object. 5039 Response: 5041 A "VCALENDAR" component is returns with one ore more "REQUEST-STATUS" 5042 property values. 5044 If any error occurred: 5046 No component will be changed at all. That is, it will appear just 5047 as it was prior to the modify and the CAP server SHOULD return a 5048 "REQUEST-STATUS" property for each error that occurred. 5050 There MUST BE at least one error reported. 5052 If multiple components are selected, then what uniquely identified 5053 the component MUST BE returned (UID, QUERYID, ...) if the component 5054 contains a unique identifier. If not, sufficient information to 5055 uniquely identify the modified components MUST BE returned in the 5056 reply. 5058 S: Content-Type: text/calendar 5059 S: 5060 S: BEGIN:VCALENDAR 5061 S: TARGET:relcalid 5062 S: CMD;ID=delete#1:REPLY 5063 S: BEGIN:VREPLY 5064 S: BEGIN:VEVENT 5065 S: UID:123 5066 S: REQUEST-STATUS:2.0 5067 S: END:VEVENT 5068 S: END:VREPLY 5069 S: END:VCALENDAR 5071 10.6 MOVE Command 5073 CMD: MOVE 5075 Purpose: The "MOVE" command is used to move components within the CS. 5077 A CUA MAY send a "MOVE" command to a CS. The "MOVE" command MUST BE 5078 implemented by all CSs. 5080 The CS MUST NOT send a "MOVE" command to any CUA. 5082 Formal Definition: A "MOVE" command is defined by the following 5083 notation: 5085 move-cmd = moveparam ":" "MOVE" 5087 moveparam = *( 5089 ; the following are optional, 5090 ; but MUST NOT occur more than once 5092 id-param 5093 / localize-param 5094 / latency-param 5096 ; the following MUST occur exactly once and only 5097 ; when the latency-param has been supplied and 5098 ; MUST NOT be supplied if the latency-param is 5099 ; not supplied. 5101 / action-param 5103 ; the following is optional, 5104 ; and MAY occur more than once 5106 / other-params 5108 ) 5110 Response: 5111 The REQUEST-STATUS in a VCALENDAR object. 5113 The content of each "result" is subject to the result restriction 5114 table defined below. 5116 The access control on the "VAGENDA" component after it has been moved 5117 to its new location in the calstore MUST BE at least as secure as it 5118 was prior to the move. If the CS is not able to ensure the same 5119 level of security, a permission denied "REQUEST-STATUS" property 5120 value MUST BE returned and the "MOVE" command not performed. 5122 The "TARGET" property value specifies the new location, and the 5123 "VQUERY" component specifies the old location. 5125 Restriction Table for the "REPLY" command of any "MOVE" command. 5127 move-reply = "BEGIN" ":" "VCALENDAR" CRLF 5128 calprops 5129 1*(move-vreply) 5130 "END" ":" "VCALENDAR" CRLF 5132 move-vreply = "BEGIN" ":" "VREPLY" CRLF 5133 move-id 5134 request-status 5135 "END" ":" "VREPLY" CRLF 5137 ; Where the id is appropriate for the 5138 ; type of object moved: 5139 ; 5140 ; VAGENDA = calid 5141 ; VCAR = carid 5142 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 5143 ; VQUERY = queryid 5144 ; ALARM = sequence 5145 ; An instance = uid recurid 5146 ; x-component = x-id 5147 ; 5148 move-id = ( calid / carid / uid / uid recurid 5149 / queryid / tzid / sequence / x-id) 5151 Example: moving the VAGENDA Nellis to Area-51 5152 C: Content-Type: text/calendar 5153 C: 5154 C: BEGIN:VCALENDAR 5155 C: VERSION:2.0 5156 C: PRODID:-//someone's prodid 5157 C: CMD:MOVE 5158 C: TARGET:Area-51 5159 C: BEGIN:VQUERY 5160 C: QUERY: SELECT * FROM VAGENDA WHERE CALID='Nellis' 5161 C: END:VQUERY 5162 C: END:VCALENDAR 5164 S: Content-Type: text/calendar 5165 S: 5166 S: BEGIN:VCALENDAR 5167 S: VERSION:2.0 5168 S: PRODID:-//someone's prodid 5169 S: TARGET:Area-51 5170 S: BEGIN:VREPLY 5171 S: CALID:Nellis 5172 S: REQUEST-STATUS: 2.0 5173 S: END:VREPLY 5174 S: END:VCALENDAR 5176 10.7 REPLY Response to a Command 5178 CMD: REPLY 5180 Purpose: The "REPLY" value to the "CMD" property is used to return 5181 the results of all other commands to the CUA. 5183 A CUA MUST send a "REPLY" command to a CS for any command a CS MAY 5184 send to the CUA. The "REPLY" command MUST BE implemented by all CUAs 5185 that support getting the "GET-CAPABILITY" command. 5187 A CS MUST send a "REPLY" command to a CUA for any command a CUA MAY 5188 send to the CS. The "REPLY" command MUST BE implemented by all CSs. 5190 Formal Definition: A "REPLY" command is defined by the following 5191 notation: 5193 reply-cmd = replyparam ":" "REPLY" 5195 replyparam = *( 5197 ; The 'id' parameter value MUST BE exactly the 5198 ; same as the value sent in the original 5199 ; CMD property. If the original CMD did 5200 ; not have an 'id' parameter, then the 'id' 5201 ; MUST NOT be supplied in the REPLY. 5203 id-param 5205 ; the following is optional, 5206 ; and MAY occur more than once 5208 / other-params 5210 ) 5212 10.8 SEARCH Command 5214 CMD: SEARCH 5216 Purpose: The "SEARCH" command is used to return selected components 5217 to the CUA. 5219 A CUA MAY send a "SEARCH" command to a CS. The "SEARCH" command MUST 5220 BE implemented by all CSs. 5222 The CS MUST NOT send a "SEARCH" command to any CUA. 5224 Formal Definition: A "SEARCH" command is defined by the following 5225 notation: 5227 search-cmd = searchparam ":" "SEARCH" 5229 searchparam = *( 5231 ; the following are optional, 5232 ; but MUST NOT occur more than once 5234 id-param 5235 / localize-param 5236 / latency-param 5238 ; the following MUST occur exactly once and only 5239 ; when the latency-param has been supplied and 5240 ; MUST NOT be supplied if the latency-param is 5241 ; not supplied. 5243 / action-param 5245 ; the following is optional, 5246 ; and MAY occur more than once 5248 / other-params 5250 ) 5252 Response: 5254 The data in each result contains an iCalendar object composed of all 5255 the selected components enclosed in a "VREPLY" component. Only 5256 "REQUEST-STATUS" property and the properties mentioned in the 5257 "SELECT" clause of the QUERY are included in the components. Each 5258 iCalendar object is tagged with the "TARGET" property. 5260 Searching for objects 5262 In the example below objects on March 10,1999 between 080000Z and 5263 190000Z are read. In this case only 4 properties for each objects 5264 are returned. Two calendars are specified. Only booked (vs 5265 scheduled) entries are to be returned (this example only selected 5266 VEVENT objects): 5268 C: Content-Type: text/calendar 5269 C: 5270 C: BEGIN:VCALENDAR 5271 C: VERSION:2.0 5272 C: PRODID:-//someone's prodid 5273 C: CMD:SEARCH 5274 C: TARGET:relcal2 5275 C: TARGET:relcal3 5276 C: BEGIN:VQUERY 5277 C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID 5278 C: FROM VEVENT 5279 C: WHERE DTEND >= '19990310T080000Z' 5280 C: AND DTSTART <= '19990310T190000Z' 5281 C: AND STATE() = 'BOOKED' 5282 C: END:VQUERY 5283 C: END:VCALENDAR 5285 The return values are subject to VCAR filtering. That is, if the 5286 request contains properties to which the UPN does not have access, 5287 those properties will not appear in the return values. If the UPN 5288 has access to at least one property of the component, but has been 5289 denied access to all properties called out in the request, the 5290 response will contain a single "REQUEST-STATUS" property indicating 5291 the error. 5293 Here the request was successful, but the "VEVENT" component contents 5294 were not accessible (4.1). 5296 S: Content-Type: text/calendar 5297 S: 5298 S: BEGIN:VCALENDAR 5299 S: TARGET:relcalid 5300 S: CMD:REPLY 5301 S: VERSION:2.0 5302 S: PRODID:-//someone's prodid 5303 S: BEGIN:VREPLY 5304 S: BEGIN:VEVENT 5305 S: REQUEST-STATUS:4.1 5306 S: END:VEVENT 5307 S: END:VREPLY 5308 S: END:VCALENDAR 5310 If the UPN has no access to any components at all, the response will 5311 simply be an empty data set. The response looks the same if there 5312 the particular components did not exist. 5314 S: Content-Type: text/calendar 5315 S: 5316 S: BEGIN:VCALENDAR 5317 S: VERSION:2.0 5318 S: PRODID:-//someone's prodid 5319 S: CMD:REPLY 5320 S: TARGET:ralcalid 5321 S: BEGIN:VREPLY 5322 S: REQUEST-STATUS:2.0 5323 S: END:VREPLY 5324 S: END:VCALENDAR 5326 If there are multiple targets, each iCalendar reply is contained 5327 within its own iCalendar object. 5329 Stored VQUERY can be used by specifying the property QUERYID instead 5330 of QUERY. 5332 10.9 SET-LOCALE Command 5334 CMD: SET-LOCALE 5336 Purpose: The "SET-LOCALE" command is used to select the locale that 5337 will be used in error codes used in the "REQUEST-STATUS" property. 5338 It also effect the locale sorting order for queries. 5340 A CUA MAY send a "SET-LOCALE" command to a CS. The SET-LOCALE 5341 command MUST BE implemented by all CSs. 5343 The CS MUST NOT send a "SET-LOCALE" command to any CUA. 5345 Formal Definition: A "SET-LOCALE" command is defined by the following 5346 notation: 5348 setlocale-cmd = setlocaleparam ":" "SET-LOCALE" 5350 setlocaleparam = *( 5352 ; the following are optional, 5353 ; but MUST NOT occur more than once 5355 id-param 5356 / localize-param 5357 / latency-param 5358 / setlocale-option 5360 ; the following MUST occur exactly once and only 5361 ; when the latency-param has been supplied and 5362 ; MUST NOT be supplied if the latency-param is 5363 ; not supplied. 5365 / action-param 5367 ; the following is optional, 5368 ; and MAY occur more than once 5370 / other-params 5372 setlocal-option = option-param newlocale 5374 newlocale = ; Any locale supplied in the initial [BEEP] 5375 ; "greeting" "localize" parameter and 5376 ; and any charset supported by the CS 5377 ; and listed in the DEFAULT-CHARSET property 5378 ; of the VCALSTORE. 5380 ) 5382 Examples: 5384 CMD:OPTIONS=en_US.UTF-8:SET-LOCALE 5385 CMD:OPTIONS=th_TH.ISO8859-11:SET-LOCALE 5386 CMD:OPTIONS=es_MX.ISO8859-1:SET-LOCALE 5388 Restriction Table for the "REPLY" command of any "SET-LOCALE" 5389 command. 5391 setlocale-reply = "BEGIN" ":" "VCALENDAR" CRLF 5392 calprops 5393 1*(setlocale-vreply) 5394 "END" ":" "VCALENDAR" CRLF 5396 setlocale-vreply = "BEGIN" ":" "VREPLY" CRLF 5397 request-status 5398 "END" ":" "VREPLY" CRLF 5400 10.10 TIMEOUT Command 5402 CMD: TIMEOUT 5404 Purpose: The "TIMEOUT" command is only sent after a command has been 5405 sent with a latency value set. When received it means the command 5406 could not be completed in the time allowed. 5408 Formal Definition: A "TIMEOUT" command is defined by the following 5409 notation: 5411 timeout-cmd = continueparam ":" "TIMEOUT" 5413 timeoutparam = *( 5415 ; the following are optional, 5416 ; but MUST NOT occur more than once 5418 id-param 5419 / localize-param 5421 / other-params 5423 ) 5425 10.11 Response Codes 5427 Numeric response codes are returned using the "REQUEST-STATUS" 5428 property. 5430 The format of these codes is described in [iCAL], and extend in 5431 [iTIP] and [iMIP]. The following describes new codes added to this 5432 set and how existing codes apply to CAP. 5434 At the application layer response codes are returned as the value of 5435 a "REQUEST-STATUS" property. The value type of this property is 5436 modified from that defined in [iCAL], in order to make the 5437 accompanying "REQUEST-STATUS" property text optional. 5439 Code Description 5440 -------------------------------------------------------------- 5441 2.0 Success. The parameters vary with the 5442 operation and are specified. 5444 2.0.3 In response to the client issuing an 5445 "abort" reply, this reply code indicates 5446 that any command currently underway was 5447 successfully aborted. 5449 3.1.4 Capability not supported. 5451 4.1 Calendar store access denied. 5453 6.1 Container not found. 5455 6.2 Attempt to create or modify an object 5456 such that it would overlap another object 5457 in either of the following two circumstances: 5459 (a) One of the objects has a TRANSP 5460 property set to OPAQUE-NOCONFLICT or 5461 TRANSPARENT-NOCONFLICT. 5463 (b) The calendar's ALLOW-CONFLICT 5464 property is set to FALSE. 5466 6.3 Bad args. 5468 6.4 Permission denied - VCAR restriction. 5469 A VCAR exists and the CS will not perform 5470 the operation. 5472 7.0 A timeout has occurred. The server was 5473 unable to complete the operation in the 5474 requested time. 5476 8.0 A failure has occurred in the CS 5477 that prevents the operation from 5478 succeeding. 5480 8.1 A query was performed and the query is 5481 too complex for the CS. The operation 5482 was not performed. 5484 8.2 Used to signal that an iCalendar object has 5485 exceeded the server's size limit 5487 8.3 A DATETIME value was too far in the future 5488 represented on this Calendar. 5490 8.4 A DATETIME value was too far in the past 5491 to be represented on this Calendar. 5493 8.5 An attempt was made to create a new 5494 object but the unique UID specified is 5495 already in use. 5497 9.0 An unrecognized command was received. 5498 Or an unsupported command was received. 5500 10.4 The operation has not been performed 5501 because it would cause the resources 5502 (memory, disk, CPU, etc) to exceed the 5503 allocated quota. 5505 -------------------------------------------------------------- 5507 11. Object Registration 5509 This section provides the process for registration of new or modified 5510 properties, parameters, commands, or other modifications, additions, 5511 or deletions to objects. 5513 11.1 Registration of New and Modified Entities 5515 New objects are registered by the publication of an IETF Request for 5516 Comment (RFC). Changes to a objects are registered by the 5517 publication of a revision to the RFC in a new RFC. 5519 11.2 Post the item definition 5521 The object description MUST BE posted to the new object discussion 5522 list: ietf-calendar@imc.org. 5524 11.3 Allow a comment period 5526 Discussion on a new object MUST BE allowed to take place on the list 5527 for a minimum of two weeks. Consensus MUST BE reached on the object 5528 before proceeding to the next step. 5530 11.4 Release a new RFC 5532 The new object will be submitted for publication as any other 5533 internet draft requesting RFC status. 5535 12. BEEP and CAP 5537 12.1 BEEP Profile Registration 5539 TBD 5541 12.2 BEEP Exchange Styles 5543 [BEEP] defines three styles of message exchange: 5545 MSG/ANS,ANS,...,NUL - For one to many exchanges. 5547 MSG/RPY - For one to one exchanges. 5549 MSG/ERR - For requests the cannot be processed due to an error. 5551 A CAP request, targeted at more than one containers, MAY use a one- 5552 to-many exchange, with a distinct answer associated with each target. 5553 CAP request targeted at a single container MAY use a one-to-one 5554 exchange or a one-to-many exchange. "MSG/ERR" MAY only be used when 5555 an error condition prevents the execution of the request on all the 5556 targeted calendars. 5558 13. IANA Considerations 5560 This memo defines IANA registered extensions to the attributes 5561 defined by iCalendar, as defined in [iCAL], and [iTIP]. 5563 IANA registration proposals for iCalendar and [iTIP] are to be mailed 5564 to the registration agent for the "text/calendar" [MIME] content- 5565 type, using the format defined in 5566 section 7 of [iCAL]. 5568 If the IESG approves this memo for publication, then the IANA 5569 registers the profile specified in Section 12.1, and selects an IANA- 5570 specific URI, e.g., http://iana.org/beep/cap/1.0. 5572 14. Security Considerations 5574 Access rights should be granted cautiously, consult Section 2.4.2 for 5575 a discussion of the subject. Without careful planning it is possible 5576 to open up access to a greater degree than desired. 5578 The "IDENTIFY" command should be carefully implemented as discussed 5579 in Section 6.1.3. 5581 In addition, since CAP is a profile of the [BEEP], consult [BEEP]'s 5582 Section 9 for a discussion of BEEP-specific security issues. 5584 Although service provisioning is a policy matter, at a minimum, all 5585 implementations must provide the following tuning profiles: 5587 for authentication: http://iana.org/beep/SASL/DIGEST-MD5 5589 for confidentiality: http://iana.org/beep/TLS (using the 5590 TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher) 5592 for both: http://iana.org/beep/TLS (using the 5593 TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher supporting client-side 5594 certificates) 5596 URIs 5598 [1] 5600 Authors' Addresses 5602 Doug Royer 5603 INET-Consulting.com 5604 1795 W. Broadway #266 5605 Idaho Falls, ID 83402 5606 US 5608 Phone: +1-866-594-8574 5609 Fax: +1-866-594-8574 5610 EMail: Doug@Royer.com 5611 URI: http://INET-Consulting.com 5613 George Babics 5614 Oracle 5615 2000 Peel Street 5616 Montreal, Quebec H3A 2W5 5617 CA 5619 Phone: +1-514-733-8500 x4201 5620 Fax: +1-514-733-8878 5621 EMail: George.Babics@Oracle.com 5623 Paul Hill 5624 Massachusetts Institute of Technology 5625 W92-172 5626 77 Massachusetts Avenue 5627 Cambridge, MA 02139 5628 US 5630 Phone: +1-617-253-0124 5631 Fax: +1-617-258-8736 5632 EMail: phb@mit.edu 5633 Steve Mansour 5634 AOL/Netscape 5635 466 Ellis Road 5636 Mountain View, CA 94043 5637 US 5639 Phone: +1-650-937-3351 5640 EMail: sman@netscape.com 5642 Appendix A. Acknowledgments 5644 The following have individuals were major contributors in the 5645 drafting and discussion of this memo: 5647 Harald Alvestrand, Christopher Apple, G. Barnes, ArentJan Banck, 5648 Martijn van Beers, Mario Bonin, Andrea Campi, Darryl Champagne, Damon 5649 Chaplin, Karen Chu, Shannon Clark, Andre Courtemanche, Dave Crocker, 5650 Alan Davies, Andrew Davison, Mark Davidson, Bernard Desruisseaux, 5651 Frank Dawson, Pat Egen, Greg FitzPatrick, illes Fortin, Ned Freed, 5652 Gary Frederick, Jagan Garimella, Graham Gilmore, Micah Gorrell, 5653 Lawrence Greenfield, Bertrand Guiheneuf, Olivier Gutknecht, Mike 5654 Hixson, Jeff Hodges, Paul Hoffman, Scott Hollenbeck, Alex Hoppman, 5655 Bruce Kahn, Lata Kannan, suchet singh khalsa, Dan Kohn, Patrice 5656 Lapierre, Jonathan Lennox, Lisa Lippert, Robert Lusardi, David Madeo, 5657 Bob Mahoney, Murata Makoto, Gary McGath, Libby Miller, Steve Miller, 5658 Bob Morgan, David Nicol, David Nusbaum, Pete O'Leary, Mark Paterson, 5659 Ralph Patterson, Eric R. Plamondon, Robert Ransdell, Jim Ray, 5660 Marshall Rose, JP Rosevear, Paul Sharpe, Richard Shusterman, Tony 5661 Small, John Smith, Benjamin Sonntag, John Stracke, Preston 5662 Stephenson, Alexander Taler, Peter Thompson, Steve Vinter, Mark Wahl, 5663 Dan Winship 5665 Appendix B. Bibliography 5667 [BEEP] Rose, M., "The Block Extensible Exchange Protocol Core", 5668 RFC 3080, March 2001 5669 ftp://ftp.isi.edu/in-notes/rfc3080.txt 5671 [BEEPTCP] Rose, M., "Mapping the BEEP Core onto TCP", RFC 3081, March 2001 5672 ftp://ftp.isi.edu/in-notes/rfc3081.txt 5674 [CHARREG] Freed, N., Postel, J., "IANA Charset Registration Procedures", 5675 RFC 2278, January 1998, 5676 ftp://ftp.isi.edu/in-notes/rfc2278.txt 5678 [CHARPOL] Alvestrand, H., "IETF Policy on Character Sets and Languages", 5679 RFC 2277, January 1998, 5680 ftp://ftp.isi.edu/in-notes/rfc2277.txt 5682 [GUIDE] Mahoney, B., Babics, G., Taler, A. "Guide to Internet 5683 Calendaring", RFC 3283, June 2002, 5684 ftp://ftp.isi.edu/in-notes/rfc3283.txt 5686 [iCAL] Dawson, F. and Stenerson, D., "Internet Calendaring and 5687 Scheduling Core Object Specification (iCalendar)", RFC 2445, 5688 November 1998 ftp://ftp.isi.edu/in-notes/rfc2245.txt 5690 [iTIP] Silverberg, S., Mansour, S., Dawson, F. and Hopson, R., 5691 "iCalendar Transport-Independent Interoperability Protocol 5692 (iTIP) Events, BusyTime, To-dos and Journal Entries", 5693 RFC 2446, November 1998 ftp://ftp.isi.edu/in-notes/rfc2446.txt 5695 [iMIP] Dawson, F., Mansour, S. and Silverberg, "iCalendar 5696 Message-Based Interoperability Protocol (iMIP)", RFC 2447, 5697 November 1998 ftp://ftp.isi.edu/in-notes/rfc2447.txt 5699 [MIME] Borenstein, N. and Freed, N., "Multipurpose Internet Mail 5700 Extensions (MIME) Part One: Format of Internet Message Bodies", 5701 RFC 2045, November 1996 5702 ftp://ftp.isi.edu/in-notes/rfc2045.txt 5704 [RFCWORDS] Bradner, S., "Key words for use in RFCs to Indicate 5705 Requirement Levels", RFC 2119, BCP 14, March 1997 5706 ftp://ftp.isi.edu/in-notes/rfc2119.txt 5708 [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", 5709 RFC 2222, October 1997 5710 ftp://ftp.isi.edu/in-notes/rfc2222.txt 5712 [SQL92] "Database Language SQL", ANSI/ISO/IEC 9075: 1992, 5713 aka ANSI X3.135-1992, aka FiPS PUB 127-2 5715 [SQLCOM] ANSI/ISO/IEC 9075:1992/TC-1-1995, Technical corrigendum 1 5716 to ISO/IEC 9075: 1992, also adopted as Amendment 1 to 5717 ANSI X3.135.1992 5719 [URLGUIDE] Masinter, L., Alvestrand, H., Zigmond, D., Petke, R., 5720 "Guidelines for new URL Schemes", RFC 2718, November 1999, 5721 ftp://ftp.isi.edu/in-notes/rfc2718.txt 5723 [URI] Berners-Lee, T., Fielding, R. and Masinter, L., "Uniform Resource 5724 Identifiers (URI): Generic Syntax", RFC 2396, August 1998 5725 ftp://ftp.isi.edu/in-notes/rfc2396.txt 5727 [URL] Berners-Lee, T, Masinter, L. and McCahil, M., "Uniform 5728 Resource Locators (URL)", RFC 1738, December 1994 5729 ftp://ftp.isi.edu/in-notes/rfc1738.txt 5731 [X509CRL] Housley, R., Ford, W., Polk, W., Solo, D. "Internet X.509 5732 Public Key Infrastructure, Certificate and CRL Profile", 5733 RFC 2459, January 1999, 5734 ftp://ftp.isi.edu/in-notes/rfc2459.txt 5736 Full Copyright Statement 5738 Copyright (C) The Internet Society (2003). All Rights Reserved. 5740 This document and translations of it may be copied and furnished to 5741 others, and derivative works that comment on or otherwise explain it 5742 or assist in its implementation may be prepared, copied, published 5743 and distributed, in whole or in part, without restriction of any 5744 kind, provided that the above copyright notice and this paragraph are 5745 included on all such copies and derivative works. However, this 5746 document itself may not be modified in any way, such as by removing 5747 the copyright notice or references to the Internet Society or other 5748 Internet organizations, except as needed for the purpose of 5749 developing Internet standards in which case the procedures for 5750 copyrights defined in the Internet Standards process must be 5751 followed, or as required to translate it into languages other than 5752 English. 5754 The limited permissions granted above are perpetual and will not be 5755 revoked by the Internet Society or its successors or assigns. 5757 This document and the information contained herein is provided on an 5758 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 5759 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 5760 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 5761 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 5762 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 5764 Acknowledgement 5766 Funding for the RFC Editor function is currently provided by the 5767 Internet Society.