idnits 2.17.1 draft-ietf-calsch-cap-12.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 19 instances of too long lines in the document, the longest one being 30 characters in excess of 72. ** There are 111 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 366: '... is, "events MUST BE scheduled in ...' RFC 2119 keyword, line 420: '... These extensions MUST start with "x-"...' RFC 2119 keyword, line 453: '...flict, the Realm SHOULD be postfixed w...' RFC 2119 keyword, line 458: '...lendar store. It MUST BE unique within...' RFC 2119 keyword, line 493: '...odid' and 'version' are both REQUIRED,...' (240 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 352 has weird spacing: '...able to diffe...' == Line 1873 has weird spacing: '...roperty woul...' == Line 1944 has weird spacing: '... know if "u...' == Line 2058 has weird spacing: '...alm. In it's ...' == Line 3367 has weird spacing: '...ts, and prope...' == (4 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 (January 12, 2004) is 7409 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 5717 looks like a reference -- Missing reference section? 'BEEP' on line 5786 looks like a reference -- Missing reference section? 'RFCWORDS' on line 5823 looks like a reference -- Missing reference section? 'GUIDE' on line 5801 looks like a reference -- Missing reference section? 'URL' on line 5846 looks like a reference -- Missing reference section? 'URI' on line 5842 looks like a reference -- Missing reference section? 'URLGUIDE' on line 5838 looks like a reference -- Missing reference section? 'MIME' on line 5818 looks like a reference -- Missing reference section? 'CAP' on line 1286 looks like a reference -- Missing reference section? 'BEEPTCP' on line 5790 looks like a reference -- Missing reference section? 'X509CRL' on line 5850 looks like a reference -- Missing reference section? 'SQL92' on line 5831 looks like a reference -- Missing reference section? 'SQLCOM' on line 5834 looks like a reference -- Missing reference section? 'NOT' on line 1850 looks like a reference -- Missing reference section? 'CHARREG' on line 5793 looks like a reference -- Missing reference section? '10' on line 5542 looks like a reference -- Missing reference section? 'CHARPOL' on line 5797 looks like a reference -- Missing reference section? 'SASL' on line 5827 looks like a reference Summary: 5 errors (**), 0 flaws (~~), 11 warnings (==), 21 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Calendaring and Scheduling D. Royer 3 Internet-Draft INET-Consulting 4 Expires: July 12, 2004 G. Babics 5 Oracle 6 P. Hill 7 Massachusetts Institute of 8 Technology 9 S. Mansour 10 AOL/Netscape 11 January 12, 2004 13 Calendar Access Protocol (CAP) 14 draft-ietf-calsch-cap-12 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 other 23 groups may also distribute working documents as Internet-Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at http:// 31 www.ietf.org/ietf/1id-abstracts.txt. 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 This Internet-Draft will expire on July 12, 2004. 38 Copyright Notice 40 Copyright (C) The Internet Society (2004). All Rights Reserved. 42 Abstract 44 The Calendar Access Protocol (CAP) is an Internet protocol described 45 in this memo that permits a Calendar User (CU) to utilize a Calendar 46 User Agent (CUA) to access an [iCAL] based Calendar Store (CS). 48 The CAP definition is based on requirements identified by the 49 Internet Engineering Task Force (IETF) Calendaring and Scheduling 50 (CALSCH) Working Group. More information about the IETF CALSCH 51 Working Group activities can be found on the IMC web site at http:// 52 www.imc.org/ietf-calendar and at the IETF web site at http:// 53 www.ietf.org/html.charters/calsch-charter.html [1]. Refer to the 54 references within this memo for further information on how to access 55 these various documents. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . 5 60 1.1 Formatting Conventions . . . . . . . . . . . . . . . . . 5 61 1.2 Related Documents . . . . . . . . . . . . . . . . . . . 6 62 1.3 Definitions . . . . . . . . . . . . . . . . . . . . . . 7 63 2. Additions to iCalendar . . . . . . . . . . . . . . . . . 12 64 2.1 New Value Types (summary) . . . . . . . . . . . . . . . 14 65 2.1.1 New Parameters (summary) . . . . . . . . . . . . . . . . 14 66 2.1.2 New Properties (summary) . . . . . . . . . . . . . . . . 15 67 2.1.3 New Components (summary) . . . . . . . . . . . . . . . . 17 68 2.2 Relationship of RFC-2446 (ITIP) and CAP . . . . . . . . 18 69 3. CAP Design . . . . . . . . . . . . . . . . . . . . . . . 20 70 3.1 System Model . . . . . . . . . . . . . . . . . . . . . . 20 71 3.2 Calendar Store Object Model . . . . . . . . . . . . . . 20 72 3.3 Protocol Model . . . . . . . . . . . . . . . . . . . . . 21 73 3.3.1 Use of BEEP, MIME and iCalendar . . . . . . . . . . . . 22 74 4. Security Model . . . . . . . . . . . . . . . . . . . . . 24 75 4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . . 24 76 4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . . 24 77 4.1.2 Anonymous Users and Authentication . . . . . . . . . . . 25 78 4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . . 25 79 4.2 Access Rights . . . . . . . . . . . . . . . . . . . . . 26 80 4.2.1 Access Control and NOCONFLICT . . . . . . . . . . . . . 26 81 4.2.2 Predefined VCARs . . . . . . . . . . . . . . . . . . . . 26 82 4.2.3 Decreed VCARs . . . . . . . . . . . . . . . . . . . . . 28 83 4.3 CAP Session Identity . . . . . . . . . . . . . . . . . . 29 84 5. CAP URL and Calendar Address . . . . . . . . . . . . . . 31 85 6. New Value Types . . . . . . . . . . . . . . . . . . . . 33 86 6.1 Property Value Data Types . . . . . . . . . . . . . . . 33 87 6.1.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . . . 33 88 6.1.2 UPN Value Type . . . . . . . . . . . . . . . . . . . . . 48 89 6.1.3 UPN-FILTER Value . . . . . . . . . . . . . . . . . . . . 49 90 7. New Parameters . . . . . . . . . . . . . . . . . . . . . 52 91 7.1 ACTION Parameter . . . . . . . . . . . . . . . . . . . . 52 92 7.2 ENABLE Parameter . . . . . . . . . . . . . . . . . . . . 52 93 7.3 ID Parameter . . . . . . . . . . . . . . . . . . . . . . 53 94 7.4 LATENCY Parameter . . . . . . . . . . . . . . . . . . . 54 95 7.5 LOCAL Parameter . . . . . . . . . . . . . . . . . . . . 55 96 7.6 LOCALIZE Parameter . . . . . . . . . . . . . . . . . . . 55 97 7.7 OPTIONS Parameter . . . . . . . . . . . . . . . . . . . 56 98 8. New Properties . . . . . . . . . . . . . . . . . . . . . 58 99 8.1 ALLOW-CONFLICT Property . . . . . . . . . . . . . . . . 58 100 8.2 ATT-COUNTER Property . . . . . . . . . . . . . . . . . . 58 101 8.3 CALID Property . . . . . . . . . . . . . . . . . . . . . 59 102 8.4 CALMASTER Property . . . . . . . . . . . . . . . . . . . 60 103 8.5 CAP-VERSION Property . . . . . . . . . . . . . . . . . . 60 104 8.6 CARID Property . . . . . . . . . . . . . . . . . . . . . 61 105 8.7 CAR-LEVEL Property . . . . . . . . . . . . . . . . . . . 61 106 8.8 COMPONENTS Property . . . . . . . . . . . . . . . . . . 62 107 8.9 CSID Property . . . . . . . . . . . . . . . . . . . . . 64 108 8.10 DECREED Property . . . . . . . . . . . . . . . . . . . . 64 109 8.11 DEFAULT-CHARSET Property . . . . . . . . . . . . . . . . 65 110 8.12 DEFAULT-LOCALE Property . . . . . . . . . . . . . . . . 66 111 8.13 DEFAULT-TZID Property . . . . . . . . . . . . . . . . . 67 112 8.14 DEFAULT-VCARS Property . . . . . . . . . . . . . . . . . 68 113 8.15 DENY Property . . . . . . . . . . . . . . . . . . . . . 69 114 8.16 EXPAND property . . . . . . . . . . . . . . . . . . . . 69 115 8.17 GRANT Property . . . . . . . . . . . . . . . . . . . . . 70 116 8.18 ITIP-VERSION Property . . . . . . . . . . . . . . . . . 71 117 8.19 MAX-COMP-SIZE Property . . . . . . . . . . . . . . . . . 71 118 8.20 MAXDATE Property . . . . . . . . . . . . . . . . . . . . 72 119 8.21 MINDATE Property . . . . . . . . . . . . . . . . . . . . 73 120 8.22 MULTIPART Property . . . . . . . . . . . . . . . . . . . 73 121 8.23 NAME Property . . . . . . . . . . . . . . . . . . . . . 74 122 8.24 OWNER Property . . . . . . . . . . . . . . . . . . . . . 75 123 8.25 PERMISSION Property . . . . . . . . . . . . . . . . . . 75 124 8.26 QUERY property . . . . . . . . . . . . . . . . . . . . . 76 125 8.27 QUERYID property . . . . . . . . . . . . . . . . . . . . 77 126 8.28 REQUEST-STATUS property . . . . . . . . . . . . . . . . 78 127 8.29 QUERY-LEVEL Property . . . . . . . . . . . . . . . . . . 79 128 8.30 RECUR-ACCEPTED Property . . . . . . . . . . . . . . . . 79 129 8.31 RECUR-LIMIT Property . . . . . . . . . . . . . . . . . . 80 130 8.32 RECUR-EXPAND Property . . . . . . . . . . . . . . . . . 81 131 8.33 RESTRICTION Property . . . . . . . . . . . . . . . . . . 81 132 8.34 SCOPE Property . . . . . . . . . . . . . . . . . . . . . 82 133 8.35 STORES-EXPANDED Property . . . . . . . . . . . . . . . . 83 134 8.36 TARGET Property . . . . . . . . . . . . . . . . . . . . 84 135 8.37 TRANSP Property . . . . . . . . . . . . . . . . . . . . 84 136 9. New Components . . . . . . . . . . . . . . . . . . . . . 86 137 9.1 VAGENDA Component . . . . . . . . . . . . . . . . . . . 86 138 9.2 VCALSTORE Component . . . . . . . . . . . . . . . . . . 88 139 9.3 VCAR Component . . . . . . . . . . . . . . . . . . . . . 89 140 9.4 VRIGHT Component . . . . . . . . . . . . . . . . . . . . 92 141 9.5 VREPLY Component . . . . . . . . . . . . . . . . . . . . 93 142 9.6 VQUERY Component . . . . . . . . . . . . . . . . . . . . 93 143 10. Commands and Responses . . . . . . . . . . . . . . . . . 95 144 10.1 CAP Commands (CMD) . . . . . . . . . . . . . . . . . . . 95 145 10.1.1 Bounded Latency . . . . . . . . . . . . . . . . . . . . 96 146 10.2 ABORT Command . . . . . . . . . . . . . . . . . . . . . 98 147 10.3 CONTINUE Command . . . . . . . . . . . . . . . . . . . . 99 148 10.4 CREATE Command . . . . . . . . . . . . . . . . . . . . . 100 149 10.5 DELETE Command . . . . . . . . . . . . . . . . . . . . . 105 150 10.6 GENERATE-UID Command . . . . . . . . . . . . . . . . . . 108 151 10.7 GET-CAPABILITY Command . . . . . . . . . . . . . . . . . 110 152 10.8 IDENTIFY Command . . . . . . . . . . . . . . . . . . . . 112 153 10.9 MODIFY Command . . . . . . . . . . . . . . . . . . . . . 115 154 10.10 MOVE Command . . . . . . . . . . . . . . . . . . . . . . 119 155 10.11 REPLY Response to a Command . . . . . . . . . . . . . . 121 156 10.12 SEARCH Command . . . . . . . . . . . . . . . . . . . . . 122 157 10.12.1 Searching for VFREEBUSY . . . . . . . . . . . . . . . . 125 158 10.13 SET-LOCALE Command . . . . . . . . . . . . . . . . . . . 126 159 10.14 TIMEOUT Command . . . . . . . . . . . . . . . . . . . . 127 160 10.15 Response Codes . . . . . . . . . . . . . . . . . . . . . 128 161 11. Object Registration . . . . . . . . . . . . . . . . . . 131 162 11.1 Registration of New and Modified Entities . . . . . . . 131 163 11.2 Post the item definition . . . . . . . . . . . . . . . . 131 164 11.3 Allow a comment period . . . . . . . . . . . . . . . . . 131 165 11.4 Release a new RFC . . . . . . . . . . . . . . . . . . . 131 166 12. BEEP and CAP . . . . . . . . . . . . . . . . . . . . . . 132 167 12.1 BEEP Profile Registration . . . . . . . . . . . . . . . 132 168 12.2 BEEP Exchange Styles . . . . . . . . . . . . . . . . . . 134 169 13. IANA Considerations . . . . . . . . . . . . . . . . . . 135 170 14. Security Considerations . . . . . . . . . . . . . . . . 136 171 Authors' Addresses . . . . . . . . . . . . . . . . . . . 137 172 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . 139 173 B. Bibliography . . . . . . . . . . . . . . . . . . . . . . 140 174 Intellectual Property and Copyright Statements . . . . . 142 176 1. Introduction 178 This document specifies how a Calendar CUA interacts with a CS to 179 manage calendar information. In particular, it specifies how to 180 query, create, modify, and delete iCalendar components (e.g., events, 181 to-dos, or daily journal entries). It further specifies how to search 182 for available busy time information. Synchronization with CUAs is not 183 covered and believed to be possible using CAP. 185 CAP is specified as a [BEEP] "profile". As such, many aspects of the 186 protocol (e.g., authentication and privacy) are provided within 187 [BEEP]. The protocol data units leverage the standard iCalendar 188 format [iCAL] to convey calendar related information. 190 CAP can also be used to store and fetch [iTIP] objects and when those 191 objects are used in this memo, they mean exactly the same as defined 192 in [iTIP]. When iCalendar objects are transferred between the CUA and 193 a CS, some additional properties and parameters may be added and the 194 CUA is responsible for correctly generating iCalendar objects to non 195 CAP processes. 197 The definition of new components, properties, parameter's, and value 198 types are broken into two parts. The first part summarizes and 199 defines the new objects. The second part provides the detail and any 200 ABNF for those objects. The ABNF in CAP as in other iCalendar 201 specifications is order independent. That is properties in a 202 component may occur in any order and parameters in any property may 203 occur in any order. 205 1.1 Formatting Conventions 207 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 208 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this 209 document are to be interpreted as described in [RFCWORDS]. 211 Calendaring and scheduling roles are referred to in quoted-strings of 212 text with the first character of each word in upper case. For 213 example, "Organizer" refers to a role of a "Calendar User" (CU) 214 within the protocol defined by [iTIP]. Calendar components defined by 215 [iCAL] are referred to with capitalized, quoted-strings of text. All 216 iCalendar components should start with the letter "V". For example, 217 "VEVENT" refers to the event calendar component, "VTODO" refers to 218 the to-do component and "VJOURNAL" refers to the daily journal 219 component. 221 Scheduling methods defined by [iTIP], are referred to with 222 capitalized, quoted-strings of text. For example, "REPLY" refers to 223 the method for replying to a "REQUEST". 225 CAP commands are referred to by upper-case, quoted-strings of text, 226 followed by the word "command". For example, "CREATE" command refers 227 to the command for creating a calendar entry, "SEARCH" command refers 228 to the command for reading calendar components. CAP Commands are 229 named using the "CMD" property. 231 Properties defined by this memo are referred to with capitalized, 232 quoted-strings of text, followed by the word "property". For example, 233 "ATTENDEE" property refers to the iCalendar property used to convey 234 the calendar address that has been invited to a "VEVENT" or "VTODO" 235 component. 237 Property parameters defined by this memo are referred to with 238 capitalized, quoted-strings of text, followed by the word 239 "parameter". For example, "PARTSTAT" parameter refers to the 240 iCalendar property parameter used to specify the participation status 241 of an attendee. Enumerated values defined by this memo are referred 242 to with capitalized text, either alone or followed by the word 243 "value". 245 Object states defined by this memo are referred to with capitalized, 246 quoted-strings of text, followed by the word "state". For example, 247 "BOOKED" state refers to an object in the booked state. 249 Within a query, the different parts are referred to as a "clause" and 250 its value as "clause value" and the clause name will be in uppercase 251 enclosed in quotes. Example, The "SELECT" clause or if the "SELECT" 252 clause value contains ... 254 In tables, the quoted-string text is specified without quotes in 255 order to minimize the table length. 257 1.2 Related Documents 259 Implementers will need to be familiar with several other memos that, 260 along with this one, describe the Internet calendaring and scheduling 261 standards. These documents are: 263 [iCAL] - (RFC2445) Which specifies the objects, data types, 264 properties and property parameters used in the protocols, along 265 with the methods for representing and encoding them. 267 [iTIP] - (RFC2446) Which specifies an interoperability protocol for 268 scheduling between different installations. 270 [iMIP] - (RFC2447) Which specifies the Internet email binding for 271 [iTIP]. 273 [GUIDE] - (RFC3283), a guide to implementers and describes the 274 elements of a calendaring system, how they interact with each 275 other, how they interact with end users, and how the standards and 276 protocols are used. 278 This memo does not attempt to repeat the specification of concepts 279 and definitions from these other memos. Where possible, references 280 are made to the memo that provides for the specification of these 281 concepts and definitions. 283 1.3 Definitions 285 BOOKED - An object in the calendar store has one of three conceptual 286 states. It is in the "UNPROCESSED" state, "BOOKED" state, or 287 marked for deletion which is the "DELETED" state. How the 288 implementation stores the state of any object is not a protocol 289 issues and is not discussed. An object can be said to be booked, 290 unprocessed, or marked for delete. 292 1. An "UNPROCESSED" state scheduling object has been stored in 293 the calendar store but has not been acted on by a CU or CUA. 294 All scheduled entries are [iTIP] objects. All [iTIP] objects 295 in the store are not in the "BOOKED" state. To retrieve any 296 [iTIP] object, simply do a query asking for any objects that 297 are stored in the "UNPROCESSED" state. 299 2. A "BOOKED" state entry is stored with the "CREATE" command. It 300 is an object that has been acted on by a CU or CUA and there 301 has been a decision to store an object. To retrieve any booked 302 object, simply do a query asking for any objects that were 303 stored in the "BOOKED" state. 305 3. A "DELETED" state entry is created by sending a "DELETE" 306 command with the "OPTION" parameter value set to "MARK". To 307 retrieve any deleted object, simply do a query asking for any 308 objects that were stored in the "DELETED" state. By default 309 objects marked for delete are not returned. The CUA must 310 specifically ask for marked for delete objects. You can not 311 ask for components in the "DELETED" state and in other states 312 in the same "VQUERY" component, as there would be no way to 313 distinguish between them in the reply. 315 Calendar - A collection of logically related objects or entities 316 each of which may be associated with a calendar date and possibly 317 time of day. These entities can include calendar properties or 318 components. In addition, a calendar might be related to other 319 calendars with the "RELATED-TO" property. A calendar is identified 320 by its unique calendar identifier. The [iCAL] defines the initial 321 calendar properties, calendar components and properties that make 322 up the contents of a calendar. 324 Calendar Access Protocol (CAP) - The standard Internet protocol that 325 permits a CUA to access and manipulate calendars residing on a 326 Calendar Store. (this memo) 328 Calendar Access Rights (VCAR) - The mechanism for specifying the CAP 329 operations ("PERMISSION") that a particular calendar user ("UPN") 330 is granted or denied permission to perform on a given calendar 331 object ("SCOPE"). The calendar access rights are specified with a 332 "VCAR" component. (Section 9.3.) 334 Calendar Address - Also See Calendar URL - they are one in the same 335 for CAP addresses. The calendar address can also be the value to 336 the "ATTENDEE" and "ORGANIZER" properties as defined in [iCAL]. 338 Calendar URL - A calendar URL is a URL defined in this memo that 339 specifies the address of a CS or Calendar. 341 Component- Any object that conforms to the iCalendar object format 342 and that is either defined in an internet draft, registered with 343 IANA, or is an experimental object that is prefixed with "x-". 344 Some types of components include calendars, events, to-dos, 345 journals, alarms, and time zones. A component consists of 346 properties and possibly other contained components. For example, 347 an event may contain an alarm component. 349 Container - This is a generic name for VCALSTORE or VAGENDA. 351 Properties - An attribute of a particular component. Some properties 352 are applicable to different types of components. For example, the 353 "DTSTART" property is applicable to the "VEVENT", "VTODO", and 354 "VJOURNAL" components. Other components are applicable only to an 355 individual type of calendar component. For example, the "TZURL" 356 property may only be applicable to the "VTIMEZONE" components. 358 Calendar Identifier (CALID) - A globally unique identifier 359 associated with a calendar. Calendars reside within a CS. See 360 Qualified Calendar Identifier and Relative Calendar Identifier. 361 All CALIDs start with "cap:". 363 Calendar Policy - A CAP operational restriction on the access or 364 manipulation of a calendar. These may be outside of the scope of 365 the CAP protocol. An example of an implementation or site policy 366 is, "events MUST BE scheduled in unit intervals of one hour". 368 Calendar Property - An attribute of a calendar ("VAGENDA"). The 369 attribute applies to the calendar, as a whole. For example, the 370 "CALSCALE" property specifies the calendar scale (e.g., the 371 "GREGORIAN" value) for the all entries within the calendar. 373 Calendar Store (CS) - The data and service model definition for a 374 Calendar Store as defined in this memo. This memo does not specify 375 how the CS is implemented. 377 Calendar Server - An implementation of a Calendar Store (CS) that 378 manages one or more calendars. 380 Calendar Store Identifier (CSID) - The globally unique identifier 381 for an individual CS. A CSID consists of the host and port 382 portions of a "Common Internet Scheme Syntax" part of a URL, as 383 defined by [URL]. The CSID excludes any reference to a specific 384 calendar. (Section 8.9) 386 Calendar Store Components - Components maintained in a CS specify a 387 grouping of calendar store-wide information. 389 Calendar Store Properties - Properties maintained in a Calendar 390 Store calendar store-wide information. 392 Calendar User (CU) - An entity (often biological) that uses a 393 calendaring system. 395 Calendar User Agent (CUA) - The client application that a CU 396 utilizes to access and manipulate a calendar. 398 CAP Session - An open communication channel between a CUA and a CS. 399 If the CAP session is authenticated, the CU is "authenticated" and 400 it is an "authenticated CAP session". 402 Contained Component / Contained Properties - A component or property 403 that is contained inside of another component. A "VALARM" 404 component for example may be contained inside of a "VEVENT" 405 component. And a "TRIGGER" property could be a contained property 406 of a "VALARM" component. 408 Delegate - A CU (sometimes called the delegatee) who has been 409 assigned participation in a scheduled component (e.g., VEVENT) by 410 one of the attendees in the scheduled component (sometimes called 411 the delegator). An example of a delegate is a team member told to 412 go to a particular meeting in place of another Attendee who is 413 unable to attend. 415 Designate - A CU who is authorized to act on behalf of another CU. 416 An example of a designate is an assistant. 418 Experimental - The CUA and CS may implement experimental extensions 419 to the protocol. They also might have experimental components, 420 properties, and parameters. These extensions MUST start with "x-" 421 (or "X-") and should include a vendor prefix (such as 422 "x-myvendor-"). There is no guarantee that these experimental 423 extensions will interoperate with other implementations. There is 424 no guarantee that they will not interact in unpredictable ways 425 with other vendor experimental extensions. There is no guarantee 426 that the same specific experimental extension is not used my 427 multiple vendors in incompatible ways. Implementations should 428 limit sending those extensions to other implementations. 430 Object - A generic name for any component, property, parameter, or 431 value type to be used in iCalendar. 433 Overlapped Booking - A policy which indicates whether or not 434 components with a "TRANSP" property not set to 435 "TRANSPARENT-NOCONFLICT" or "OPAQUE-NOCONFLICT" value can overlap 436 one another. When the policy is applied to a calendar it indicates 437 whether or not the time span of any component (VEVENT, VTODO, ...) 438 in the calendar can overlap the time span of any other component 439 in the same calendar. When applied to an individual object, it 440 indicates whether or not any other component's time span can 441 overlap that individual component. If the CS does not allow 442 overlapped booking, then the CS is unwilling to allow any 443 overlapped bookings within any calendar or entry in the CS. 445 Owner - One or more CUs or UGs that are listed in the "OWNER" 446 property in a calendar. There can be more than one owner. 448 Qualified Calendar Identifier (Qualified CALID) - A CALID in which 449 both the scheme and CSID of the CAP URI are present. 451 Realm - A collection of calendar user accounts, identified by a 452 string. The name of the Realm is only used in UPNs. In order to 453 avoid namespace conflict, the Realm SHOULD be postfixed with an 454 appropriate DNS domain name. (e.g., the foobar Realm could be 455 called foobar.example.com). 457 Relative Calendar Identifier (Relative CALID) - An identifier for an 458 individual calendar in a calendar store. It MUST BE unique within 459 a calendar store. A Relative CALID consists of the "URL path" of 460 the "Common Internet Scheme Syntax" portion of a URL, as defined 461 by [URI] and [URLGUIDE]. 463 Session Identity - A UPN associated with a CAP session. A session 464 gains an identity after successful authentication. The identity is 465 used in combination with VCAR to determine access to data in the 466 CS. 468 User Group (UG) - A collection of Calendar Users and/or User Groups. 469 These groups are expanded by the CS and may reside either locally 470 or in an external database or directory. The group membership may 471 be fixed or dynamic over time. 473 Username - A name which denotes a Calendar User within a Realm. This 474 is part of a UPN. 476 User Principal Name (UPN) - A unique identifier that denotes a CU or 477 a group of CU. (Section 6.1.2) 479 2. Additions to iCalendar 481 Several new components, properties, parameters, and value types are 482 added in CAP. This section summarizes those new objects. 484 This memo extends the properties that can go into 'calprops' as 485 defined in [iCAL] section 4.6 page 51 to allow [iTIP] objects 486 transmitted between a CAP aware CUA and the CS to contain the 487 "TARGET" and "CMD" properties. This memo also adds to the [iCAL] ABNF 488 to allow IANA and experimental extensions. This memo does not address 489 how a CUA transmits [iTIP] or [iMIP] objects to non CAP programs. 491 calprops = 2*( 493 ; 'prodid' and 'version' are both REQUIRED, 494 ; but MUST NOT occur more than once. 495 ; 496 prodid /version / 498 ; These are optional, but MUST NOT occur 499 ; more than once. 500 ; 501 calscale / 502 method / 503 cmd / 505 ; Target is optional, and may occur more 506 ; than once. 507 ; 508 target / other-props ) 510 other-props = *(x-prop) *(iana-prop) *(other-props) 512 iana-prop = ; Any property registered by IANA directly or 513 ; included in an RFC that may be applied to 514 ; the component and within the rules published. 516 x-prop = ; As defined in [iCAL] 518 Another change is that the 'component' part of the 'icalbody' ABNF as 519 described in [iCAL] section 4.6 is optional when sending a command as 520 shown in the following updated ABNF: 522 icalbody = calprops component 524 ; If the "VCALENDAR" component contains the "CMD" 525 ; property then the 'component' is optional: 526 ; 527 / calprops ; Which MUST include a "CMD" property 529 In addition a problem exists with the control of "VALARM" components 530 and their "TRIGGER" properties. A CU may wish to set their own alarm 531 (local alarms) on components. These local alarms are not to be 532 forwarded to other CUs, CUAs, or CSs as are the "SEQUENCE" property 533 and the "ENABLE" parameter. So for the protocol between a CUA and a 534 CS, the following changes apply to the CAP protocol from [iCAL] 535 section 4.6.6 page 67: 537 alarmc = "BEGIN" ":" "VALARM" CRLF 538 alarm-seq 539 other-props 540 (audioprop / dispprop / emailprop / procprop) 541 "END" ":" "VALARM" CRLF 543 alarm-seq = "SEQUENCE" alarmseqparams ":" posint0 CRLF 545 alarmseqparams = other-params [";" local-param] other-params 547 ; Where DIGIT is defined in [iCAL] 548 ; 549 posint0 = 1*DIGIT 550 posint1 = posintfirst 1*DIGIT 552 ; A number starting with 1 through 9. 553 ; 554 posintfirst = %x31-39 556 other-params = *(";" xparam) *(";" iana-params) *(";" other-param) 558 iana-params = ; Any parameter registered by IANA directly or 559 ; included in an RFC that may be applied to 560 ; the property and within the rules published. 562 xparam ; As defined in [iCAL] 564 The CUA adds a "SEQUENCE" property to each "VALARM" component as it 565 books the component. This property along with the "LOCAL" and 566 "ENABLE" parameters allow the CUA to uniquely identify any VALARM in 567 any component. The CUA should remove those before forwarding to non 568 CAP aware CUAs. 570 In addition, if a CUA wished to ignore a "TRIGGER" property in a 571 "VALARM" component that was supplied to it by the "Organizer", the 572 CUA needs a common way to tag that trigger as disabled. So the 573 following is a modification to [iCAL] section 4.8.6.3 page 127: 575 trigger = "TRIGGER" 1*(";" enable-param) (trigrel / trigabs) 577 Section 7.2 and Section 7.5. 579 2.1 New Value Types (summary) 581 UPN The UPN value type is text value type restricted to only UPN 582 values. (Section 6.1.2) 584 UPN-FILTER Like the UPN value type, but also includes filter rules 585 that allow wildcards. (Section 6.1.3) 587 CALQUERY The "CAL-QUERY" value type is a query syntax that is used by 588 the CUA to specify the rules that apply to a CAP command. (Section 589 6.1.1) 591 2.1.1 New Parameters (summary) 593 ACTION - The "ACTION" parameter informs the endpoint if it should 594 abort or ask to continue on timeout. (Section 7.1). 596 ENABLE - The "ENABLE" parameter in CAP is used to tag a property in 597 a component as disabled or enabled. (Section 7.2). 599 ID - The "ID" parameter specifies a unique identifier to be used for 600 any outstanding commands. 602 LATENCY - The "LATENCY" parameter supplies the timeout value for 603 command completion to the other endpoint. (Section 7.4). 605 LOCAL - The "LOCAL" parameter in CAP is used to tag a property in a 606 component to signify that the component is local or to be 607 distributed. (Section 7.5). 609 LOCALIZE - The "LOCALIZE" parameter specifies the locale to be used 610 in error and warning messages. 612 OPTIONS - The "OPTIONS" parameter passes optional information for 613 the command being sent. 615 2.1.2 New Properties (summary) 617 ALLOW-CONFLICT - Some entries in a calendar might not be valid if 618 other entries were allowed to overlap the same time span. (Section 619 8.1) 621 ATT-COUNTER - When storing a "METHOD" property with the "COUNTER" 622 method, there needs to be a way to remember the "ATTENDEE" value 623 that sent the COUNTER. (Section 8.2) 625 CAP-VERSION - The version of CAP the implementation supports. 626 (Section 8.5) 628 CAR-LEVEL - The level of calendar access level supported. (Section 629 8.7) 631 COMPONENTS - The list of components supported. (Section 8.8) 633 CSID - The Calendar Store IDentifier (CSID) uniquely identifies a 634 CAP server. (Section 8.9) 636 CALID - Each calendar within a CS needs to be uniquely identifiable. 637 The "CALID" property identifies a unique calendar within a CS. It 638 can be a full CALID or a relative CALID. (Section 8.3) 640 CALMASTER - The "CALMASTER" property specifies the contact 641 information for the CS. (Section 8.4) 643 CARID - Access rights can be saved and fetched by unique ID - the 644 "CARID" property. (Section 8.6) 646 CMD - The CAP commands, as well as replies are transmitted using the 647 "CMD" property. (Section 10.1) 649 DECREED - Some access rights are not changeable by the CUA. When 650 that is the case, the "DECREED" property value in the "VCAR" 651 component will be TRUE. (Section 8.10) 653 DEFAULT-CHARSET - The list of charsets supported by the CS. The 654 first entry is the default for the CS. (Section 8.11) 656 DEFAULT-LOCALE - The list of locales supported by the CS. The first 657 entry in the list is the default locale. (Section 8.12) 659 DEFAULT-TZID - This is the list of known timezones supported. The 660 first entry is the default. (Section 8.13) 662 DEFAULT-VCARS - A list of the "CARID" properties that will be used 663 to create new calendars. (Section 8.14) 665 DENY - The UPNs listed in the "DENY" property of a "VCAR" component 666 will denied access as described in the "VRIGHT" component. 667 (Section 8.15) 669 EXPAND - This property tells the CS if the query reply should expand 670 components into multiple instances. The default is FALSE and is 671 ignored for CSs that can not expand recurrence rules. (Section 672 8.16) 674 GRANT - The UPNs listed in the "GRANT" property of a "VCAR" 675 component will allowed access as described in the "VRIGHT" 676 component. (Section 8.17) 678 ITIP-VERSION - The version of [iTIP] supported. (Section 8.18) 680 MAXDATE - The maximum date supported by the CS. (Section 8.20) 682 MAX-COMP-SIZE - The largest component size allowed in the 683 implementation including attachments in octets. (Section 8.19) 685 MINDATE - The minimum date supported by the CS. (Section 8.21) 687 MULTIPART - Passed in the capability messages to indicate which MIME 688 multipart types the sender supports. (Section 8.22) 690 NAME - The "NAME" property is used to add locale specific 691 descriptions into components. (Section 8.23) 693 OWNER - Each calendar has at least one "OWNER" property. (xref 694 target="OWNER"/>) Related to the "CAL-OWNERS()" (Section 6.1.1.1) 695 query clause. 697 PERMISSION - This property specifies the permission being granted or 698 denied. Examples are the "SEARCH" and "MODIFY" values. (Section 699 8.25) 701 QUERY - Used to hold the CAL-QUERY (Section 8.26) for the component. 703 QUERYID - A unique id for a stored query. (Section 8.27) 705 QUERY-LEVEL - The level of the query language supported. (Section 706 8.29) 708 RECUR-ACCEPTED - If the implementation support recurrence rules. 709 (Section 8.30) 711 RECUR-EXPAND - If the implementation support expanding recurrence 712 rules. (Section 8.32) 714 RECUR-LIMIT - Any maximum limit on the number of instances the 715 implementation will expand recurring objects. (Section 8.31) 717 REQUEST-STATUS - The [iCAL] "REQUEST-STATUS" property is extended to 718 include new error numbers. (Section 8.28) 720 RESTRICTION - In the final check when granting calendar access 721 requests, the CS test the results to the value of the 722 "RESTRICTION" property in the corresponding "VRIGHT" component to 723 determine if the access meets that restriction. (Section 8.33) 725 SCOPE - The "SCOPE" property is used in "VRIGHT"s component to 726 select the subset of data that may be acted upon when checking 727 access rights. (Section 8.34) 729 SEQUENCE - When the "SEQUENCE" property is used in a "VALARM" 730 component it uniquely identifies the instances of the "VALARM" 731 within that component. 733 STORES-EXPANDED - Specifies if the implementation stores recurring 734 object expanded or not. (Section 8.35) 736 TARGET - The new "VCALENDAR" component property "TARGET" (Section 737 8.36) is used to specify which calendar(s) will be the subject of 738 the CAP command. 740 TRANSP - This is a modification the [iCAL] "TRANSP" property and it 741 allows more values. The new values are related to conflict 742 control. (Section 8.37) 744 2.1.3 New Components (summary) 746 VAGENDA - CAP allows the fetching and storing of the entire contents 747 of a calendar. The "VCALENDAR" component is not sufficient to 748 encapsulate all of the needed data that describes a calendar. The 749 "VAGENDA" component is the encapsulating object for an entire 750 calendar. (Section 9.1) 752 VCALSTORE - Each CS contains one or more calendars (VAGENDAs), the 753 "VCALSTORE" component is the encapsulating object that can hold 754 all of the "VAGENDA" components along with any components and 755 properties that are unique to the store level. (Section 9.2) 757 VCAR - Calendar Access Rights are specified and encapsulated in the 758 new iCalendar "VCAR" component. The "VCAR" component holds some 759 new properties and at least one "VRIGHT" component. (Section 9.3) 761 VRIGHT - This component encapsulates a set of instructions to the CS 762 that define the rights or restrictions needed. (Section 9.4) 764 VREPLY - This component encapsulates a set of data that can consist 765 of an arbitrary amounts of properties and components. Its contents 766 is dependent on the command that was issued. (Section 9.5) 768 VQUERY - The search operation makes use of a new component, called 769 "VQUERY" and a new value type "CAL-QUERY" (Section 6.1.1). The 770 "VQUERY" component is used to fetch objects from the CS. (Section 771 9.6) 773 2.2 Relationship of RFC-2446 (ITIP) and CAP 775 [iTIP] describes scheduling methods which result in indirect 776 manipulation of components. In CAP, the "CREATE" command is used to 777 deposit entities into the store. Other CAP commands such as "DELETE", 778 "MODIFY" and "MOVE" command values provide direct manipulation of 779 components. In the CAP calendar store model, scheduling messages are 780 conceptually kept separate from other components by their state. 782 All scheduling operations are as defined in [iTIP]. This memo makes 783 no changes to any of the methods or procedures described in [iTIP]. 784 In this memo referring to the presence of the "METHOD" property in an 785 object is the same as saying an [iTIP] object. 787 A CUA may create a "BOOKED" state object by depositing an iCalendar 788 object into the store. This is done by depositing an object that does 789 not have a "METHOD" property. The CS then knows to set the state of 790 the object to the "BOOKED" state. If the object has a "METHOD" 791 property then the object is stored in the "UNPROCESSED" state. 793 If existing "UNPROCESSED" state objects exist in the CS for the same 794 UID then a CUA may wish to consolidate the objects in to one "BOOKED" 795 state object. The CUA would fetch the "UNPROCESSED" state objects for 796 that UID and process them in the CUA as described in [iTIP]. Then if 797 the CUA wished to book the UID, the CUA would issue a "CREATE" 798 command to create the new "BOOKED" state object in the CS, followed 799 by a "DELETE" command to remove any related old [iTIP] objects from 800 the CS. And it might also involve having the CUA send some [iMIP] 801 objects or contacting other CSs and performing CAP operations on 802 those CSs. 804 The CUA could also decide not to book the object. In which case the 805 "UNPROCESSED" state objects could be removed from the CS or the CUA 806 could set those object to the marked for delete state. The CUA could 807 also ignore objects for later processing. 809 The marked for delete state is used to keep the object around so that 810 the CUA can process duplicate requests automatically. If a duplicate 811 [iTIP] object is deposited into the CS and there exists identical 812 marked for delete objects, then a CUA acting on behalf of the "OWNER" 813 can silently drop those duplicate entries. 815 Another purpose for the marked for delete state is so that when a CU 816 decides they do not wish to have the object show in their calendar, 817 the CUA can book the object; changing the "PARTSTAT" parameter to 818 "DECLINED" in the "ATTENDEE" property that corresponds to their UPN. 819 Then perform an [iTIP] processing such as sending back a decline. 820 Then mark that object as marked for delete. Their CUA might be 821 configurable to automatically drop any updates for that object 822 knowing the CU has already declined. 824 When synchronizing with multiple CUAs, the marked for delete state 825 could be used to inform the synchronization process that an object is 826 to be deleted. How synchronization is done is not specified in this 827 memo. 829 Several "UNPROCESSED" state entries can be in the CS for the same 830 UID. However once consolidated, then only one object exists in the CS 831 and that is the booked object. The others MUST BE removed, or have 832 their state changed to "DELETED". 834 There MUST NOT BE more than one "BOOKED" state object in a calendar 835 for the same "UID". The "ADD" method value may create multiple 836 objects all in the "BOOKED" state for the same UID, however for the 837 purpose of this memo, they are the same object that simply have 838 multiple "VCALENDAR" components. 840 For example, if you were on vacation, you could have received a 841 "REQUEST" method to attend a meeting and several updates to that 842 meeting. Your CUA would have to issue "SEARCH" commands to find them 843 in the CS using CAP, process them, determine what the final state of 844 the object from a possible combination of user input and programmed 845 logic. Then the CUA would instruct the CS to create a new booked 846 object from the consolidated results. Finally, the CUA could do a 847 "DELETE" command to remove the related "UNPROCESSED" state objects. 848 See [iTIP] for details on resolving multiple [iTIP] scheduling 849 entries. 851 3. CAP Design 853 3.1 System Model 855 The system model describes the high level components of a calendar 856 system and how they interact with each other. 858 CAP is used by a CUA to send commands to and receive responses from a 859 CS. 861 The CUA prepares a [MIME] encapsulated command, sends it to the CS, 862 and receives a [MIME] encapsulated response. The calendaring related 863 information within these messages are represented by iCalendar 864 objects. In addition the "GET-CAPABILITY" command can be sent from 865 the CS to the CUA. 867 There are two distinct protocols in operation to accomplish this 868 exchange. [BEEP] is the transport protocol used to move these 869 encapsulations between a CUA and a CS. CAP's [BEEP] profile defines 870 the application protocol where the content and semantics of the 871 messages sent between the CUA and the CS are specified. 873 3.2 Calendar Store Object Model 875 [iCAL] describes components such as events, todos, alarms, and 876 timezones. [CAP] requires additional object infrastructure. In 877 particular, detailed definitions of the containers for events and 878 todos (calendars), access control objects, and a query language. 880 The conceptual model for a calendar store is shown below. The 881 calendar store (VCALSTORE - Section 9.2) contains "VCAR"s, "VQUERY"s, 882 "VTIMEZONE"s, "VAGENDA"s and calendar store properties. 884 Calendars (VAGENDAs) contain "VEVENT"s, "VTODO"s, "VJOURNAL"s, 885 "VCAR"s, "VTIMEZONE"s, "VFREEBUSY", "VQUERY"s and calendar 886 properties. 888 The component "VCALSTORE" is used to denote the a root of the 889 calendar store and contains all of the calendars. 891 Calendar Store 893 VCALSTORE 894 | 895 +-- properties 896 +-- VCARs 897 +-- VQUERYs 898 +-- VTIMEZONEs 899 +-- VAGENDA 900 | | 901 | +--properties 902 | +--VEVENTs 903 | | | 904 | | +--VALARMs 905 | +--VTODOs 906 | | | 907 | | +--VALARMs 908 | +--VJOURNALs 909 | +--VCARs 910 | +--VTIMEZONEs 911 | +--VQUERYs 912 | +--VFREEBUSYs 913 | | 914 | | ... 915 . 916 . 917 +-- VAGENDA 918 . . 919 . . 920 . . 922 Calendars within a Calendar Store are identified by their unique 923 Relative CALID. 925 3.3 Protocol Model 927 CAP uses [BEEP] as the transport and authentication protocol. 929 The initial charset MUST BE UTF-8 for the session in an unknown 930 locale. If the CS supplied the [BEEP] 'localize' attribute in the 931 [BEEP] 'greeting' then the CUA may tell the CS to switch locales for 932 the session by issuing the "SET-LOCALE" CAP command and supplying one 933 of the locales supplied by the [BEEP] 'localize' attribute. If 934 supplied the first locale in the [BEEP] 'localize' attribute is the 935 default locale of the CS. The locale is switched only after a 936 successful reply. 938 The "DEFAULT-CHARSET" property of the CS contains the list of 939 charsets supported by the CS with the first value being the default 940 for new calendars. If the CUA wishes to switch to one of those 941 charsets for the session, the CUA issues the "SET-LOCALE" command. 942 The CUA would have to first perform a "GET-CAPABILITY" command on the 943 CS to get the list of charsets supported by the CS. The charset is 944 switched only after a successful reply. 946 The CUA may switch locales and charsets as needed. There is no 947 requirement that a CS support multiple locales or charsets. 949 3.3.1 Use of BEEP, MIME and iCalendar 951 CAP uses the [BEEP] application protocol over TCP. (refer to [BEEP] 952 and [BEEPTCP] for more information). The default port that the CS 953 listens for connections is on user port 1026. 955 The [BEEP] data exchanged in CAP is a iCalendar MIME content that 956 fully conforms to [iCAL] iCalendar format. 958 This example tells the CS to generate and return 10 UIDs to be used 959 by the CUA. Note throughout this memo, 'C:' refers to what the CUA 960 sends, 'S:' refers to what the CS sends, 'I:' refers to what the 961 initiator sends, and 'L:' refers to what the listener sends. Where 962 initiator and listener are used as defined in [BEEP]. 964 C: MSG 1 2 . 432 62 965 C: Content-Type: text/calendar 966 C: 967 C: BEGIN:VCALENDAR 968 C: VERSION:2.0 969 C: PRODID:-//someone's prodid 970 C: CMD;ID=unique-per-cua-123;OPTIONS=10:GENERATE-UID 971 C: END:VCALENDAR 973 NOTE: The following examples will not include the [BEEP] header and 974 footer information. Only the iCalendar objects that are sent between 975 the CUA and CS will be shown as the [BEEP] payload boundaries are 976 independent of CAP. 978 The commands listed below are used to manipulate or access the data 979 on the calendar store: 981 ABORT - Sent to halt the processing of some of the commands. 982 (Section 10.2) 984 CONTINUE - Sent to continue processing a command that has had its 985 specified timeout time reached. (Section 10.3) 987 CREATE - Create a new object on the CS. Initiated by the CUA only. 988 (Section 10.4) 990 SET-LOCALE - Tell the CS to use any named locale and charset 991 supplied. Initiated by the CUA only. (Section 10.13) 993 DELETE - Delete objects from the CS. Initiated by the CUA only. Can 994 also be used to mark an object for deletion. (Section 10.5) 996 GENERATE-UID - Generate one or more unique ids. Initiated by the CUA 997 only. (Section 10.6) 999 GET-CAPABILITY - Query the capabilities the other end point of the 1000 session. (Section 10.7) 1002 IDENTIFY - Set a new identity for the session. Initiated by the CUA 1003 only. (Section 10.8) 1005 MODIFY - Modify components. Initiated by the CUA only. (Section 1006 10.9) 1008 MOVE - Move components to another container. Initiated by the CUA 1009 only. (Section 10.10) 1011 REPLY - When replying to a command, the "CMD" value will be set to 1012 "REPLY" so that it will not be confused with a new command. 1013 (Section 10.11) 1015 SEARCH - Search for components. Initiated by the CUA only. (Section 1016 10.12) 1018 TIMEOUT - Sent when a specified amount of time has lapsed and a 1019 command has not finished. (Section 10.14) 1021 4. Security Model 1023 The [BEEP] transport performs all session authentication. 1025 4.1 Calendar User and UPNs 1027 A CU is an entity that can be authenticated. It is represented in CAP 1028 as a UPN, which is a key part of access rights. The UPN 1029 representation is independent of the authentication mechanism used 1030 during a particular CUA/CS interaction. This is because UPNs are used 1031 within VCARs. If the UPN were dependent on the authentication 1032 mechanism, a VCAR could not be consistently evaluated. A CU may use 1033 one mechanism while using one CUA but the same CU may use a different 1034 authentication mechanism when using a different CUA, or while 1035 connecting from a different location. 1037 The user may also have multiple UPNs for various purposes. 1039 Note that the immutability of the user's UPN may be achieved by using 1040 SASL's authorization identity feature. (The transmitted authorization 1041 identity may be different than the identity in the client's 1042 authentication credentials.) [SASL, section 3]. This also permits a 1043 CU to authenticate using their own credentials, yet request the 1044 access privileges of the identity for which they are proxying SASL. 1045 Also, the form of authentication identity supplied by a service like 1046 TLS may not correspond to the UPNs used to express a server's access 1047 rights, requiring a server specific mapping to be done. The method by 1048 which a server determines a UPN, based on the authentication 1049 credentials supplied by a client, is implementation specific. See 1050 [BEEP] for authentication details; [BEEP] relies on SASL. 1052 4.1.1 UPNs and Certificates 1054 When using X.509 certificates for purposes of CAP authentication, the 1055 UPN should appear in the certificate. Unfortunately there is no 1056 single correct guideline for which field should contain the UPN. 1058 From RFC-2459, section 4.1.2.6 (Subject): 1060 If subject naming information is present only in the 1061 subjectAlt-Name extension (e.g., a key bound only to an email 1062 address or URI), then the subject name MUST be an empty sequence 1063 and the subjectAltName extension MUST BE critical. 1065 Implementations of this specification MAY use these comparison 1066 rules to process unfamiliar attribute types (i.e., for name 1067 chaining). This allows implementations to process certificates 1068 with unfamiliar attributes in the subject name. 1070 In addition, legacy implementations exist where an RFC 2822 name 1071 is embedded in the subject distinguished name as an EmailAddress 1072 attribute. The attribute value for EmailAddress is of type 1073 IA5String to permit inclusion of the character '@', which is not 1074 part of the PrintableString character set. EmailAddress attribute 1075 values are not case sensitive (e.g., "fanfeedback@redsox.com" is 1076 the same as "FANFEEDBACK@REDSOX.COM"). 1078 Conforming implementations generating new certificates with 1079 electronic mail addresses MUST use the rfc822Name in the subject 1080 alternative name field (see sec. 4.2.1.7 of [X509CRL]) to describe 1081 such identities. Simultaneous inclusion of the EmailAddress 1082 attribute in the subject distinguished name to support legacy 1083 implementations is deprecated but permitted. 1085 Since no single method of including the UPN in the certificate will 1086 work in all cases, CAP implementations MUST support the ability to 1087 configure what the mapping will be by the CS administrator. 1088 Implementations MAY support multiple mapping definitions, for 1089 example, the UPN may be found in either the subject alternative name 1090 field, or the UPN may be embedded in the subject distinguished name 1091 as an EmailAddress attribute. 1093 Note: If a CS or CUA is validating data received via [iMIP], if the 1094 "ORGANIZER" or "ATTENDEE" properties said (e.g.) "ATTENDEE;CN=Joe 1095 Random User:MAILTO:juser@example.com" then the email address should 1096 be checked against the UPN. This is so the "ATTENDEE" property cannot 1097 be changed to something misleading like "ATTENDEE;CN=Joe Rictus 1098 User:MAILTO:jrictus@example.com" and have it pass validation. Note 1099 that it is the email addresses that miscompare, the CN miscompare is 1100 irrelevant. 1102 4.1.2 Anonymous Users and Authentication 1104 Anonymous access is often desirable. For example an organization may 1105 publish calendar information that does not require any access control 1106 for viewing or login. Conversely, a user may wish to view 1107 unrestricted calendar information without revealing their identity. 1109 4.1.3 User Groups 1111 A User Group is used to represent a collection of CUs or other UGs 1112 that can be referenced in VCARs. A UG is represented in CAP as a UPN. 1113 The CUA cannot distinguish between a UPN that represents a CU or a 1114 UG. 1116 UGs are expanded as necessary by the CS. The CS MAY expand a UG 1117 (including nested UGs) to obtain a list of unique CUs. Duplicate UPNs 1118 are filtered during expansion. 1120 How the UG expansion is maintained across commands is implementation 1121 specific. A UG may reference a static list of members, or it may 1122 represent a dynamic list. Operations SHOULD recognize changes to UG 1123 membership. 1125 CAP does not define commands or methods for managing UGs. 1127 4.2 Access Rights 1129 Access rights are used to grant or deny access to calendars, 1130 components, properties, and parameters in a CS to a CU. CAP defines a 1131 new component type called a Calendar Access Right (VCAR). 1132 Specifically, a "VCAR" component grants, or denies, UPNs the right to 1133 search and write components, properties, and parameters on calendars 1134 within a CS. 1136 The "VCAR" component model does not put any restriction on the 1137 sequence in which the object and access rights are created. That is, 1138 an object associated with a particular "VCAR" component might be 1139 created before or after the actual "VCAR" component is defined. In 1140 addition, the "VCAR" and "VEVENT" components might be created in the 1141 same iCalendar object and passed together in a single object. 1143 All rights MUST BE denied unless specifically granted. 1145 If two rights specified in "VCAR" components are in conflict, the 1146 right that denies access always takes precedence over the right that 1147 grants access. Any attempt to create a "VCAR" component that 1148 conflicts with a "VCAR" components with a "DECREED" property set to 1149 the "TRUE" value must fail. 1151 4.2.1 Access Control and NOCONFLICT 1153 The "TRANSP" property can take on values "TRANSPARENT-NOCONFLICT" and 1154 "OPAQUE-NOCONFLICT" that prohibit other components from overlapping 1155 it. This setting overrides access. The "ALLOW-CONFLICT" CS, Calendar 1156 or component setting may also prevent overlap, returning an error 1157 code "6.3". 1159 4.2.2 Predefined VCARs 1161 Predefined calendar access CARIDs that MUST BE implemented are: 1163 CARID:READBUSYTIMEINFO - Specifies the "GRANT" and "DENY" rules that 1164 allow UPNs to search "VFREEBUSY" components. An example definition 1165 for this VCAR is: 1167 BEGIN:VCAR 1168 CARID:READBUSYTIMEINFO 1169 BEGIN:VRIGHT 1170 GRANT:* 1171 PERMISSION:SEARCH 1172 SCOPE:SELECT * FROM VFREEBUSY WHERE STATE() = 'BOOKED' 1173 END:VRIGHT 1174 END:VCAR 1176 CARID:REQUESTONLY - Specifies the "GRANT" and "DENY" rules to UPNs 1177 other than the owner of the calendar the ability to write new 1178 objects with the property "METHOD" property set to the "REQUEST" 1179 value. This CARID allows the owner to specify which UPNs are 1180 allowed to make scheduling requests. An example definition for 1181 this VCAR is: 1183 BEGIN:VCAR 1184 CARID:REQUESTONLY 1185 BEGIN:VRIGHT 1186 GRANT:NON CAL-OWNERS() 1187 PERMISSION:CREATE 1188 RESTRICTION:SELECT VEVENT FROM VAGENDA WHERE METHOD = 'REQUEST' 1189 RESTRICTION:SELECT VTODO FROM VAGENDA WHERE METHOD = 'REQUEST' 1190 RESTRICTION:SELECT VJOURNAL FROM VAGENDA WHERE METHOD = 'REQUEST' 1191 END:VRIGHT 1192 END:VCAR 1194 CARID:UPDATEPARTSTATUS - Grants to authenticated users the right to 1195 modify the instances of the "ATTENDEE" property set to one of 1196 their calendar addresses in any components for any booked 1197 component containing an "ATTENDEE" property. This allows (or 1198 denies) a CU the ability to update their own participation status 1199 in a calendar where they might not otherwise have "MODIFY" command 1200 access. They are not allowed to change the "ATTENDEE" property 1201 value. An example definition for this VCAR is (This example only 1202 affects the "VEVENT" components): 1204 BEGIN:VCAR 1205 CARID:UPDATEPARTSTATUS 1206 BEGIN:VRIGHT 1207 GRANT:* 1208 PERMISSION:MODIFY 1209 SCOPE:SELECT ATTENDEE FROM VEVENT 1210 WHERE ATTENDEE = SELF() 1211 AND ORGANIZER = CURRENT-TARGET() 1212 AND STATE() = 'BOOKED' 1213 RESTRICTION:SELECT * FROM VEVENT 1214 WHERE ATTENDEE = SELF() 1215 END:VRIGHT 1216 END:VCAR 1218 CARID:DEFAULTOWNER - Grants to any owner the permission they have 1219 for the target. An example definition for this VCAR is: 1221 BEGIN:VCAR 1222 CARID:DEFAULTOWNER 1223 BEGIN:VRIGHT 1224 GRANT:CAL-OWNERS() 1225 PERMISSION:* 1226 SCOPE:SELECT * FROM VAGENDA 1227 END:VRIGHT 1228 END:VCAR 1230 4.2.3 Decreed VCARs 1232 A CS MAY choose to implement and allow persistent immutable VCARs 1233 that may be configured by the CS administrator. A reply from the CS 1234 may dynamically create "VCAR" components that are decreed depending 1235 on the implementation. To the CUA any "VCAR" component with the 1236 "DECREED" property set to "TRUE" can not be changed by the currently 1237 authenticated UPN, and depending on the implementation and other 1238 "VCAR" components; might not be able to be changed by any UPN using 1239 CAP, and never when the CUA gets a "DECREED:TRUE" VCAR. 1241 When a user attempts to modify or override a decreed "VCAR" component 1242 rules an error will be returned indicating that the user has 1243 insufficient authorization to perform the operation. The reply to the 1244 CUA MUST BE the same as if a non-decreed VCAR caused the failure. 1246 The CAP protocol does not define the semantics used to initially 1247 create a decreed VCAR. This administrative task is outside the scope 1248 of the CAP protocol. 1250 For example; an implementation or a CS administrator may wish to 1251 define a VCAR that will always allow the calendar owners to have full 1252 access to their own calendars. 1254 Decreed "VCAR" components MUST BE readable by the calendar owner in 1255 standard "VCAR" component format. 1257 4.3 CAP Session Identity 1259 A [BEEP] session has an associated set of authentication credentials, 1260 from which is derived a UPN. This UPN is the identity of the CAP 1261 session, and is used to determine access rights for the session. 1263 The CUA may change the identity of a CAP session by calling the 1264 "IDENTIFY" command. The CS only permits the operation if the 1265 session's authentication credentials are good for the requested 1266 identity. The method of checking this permission is implementation 1267 dependent, but may be thought of as a mapping from authentication 1268 credentials to UPNs. The "IDENTIFY" command allows a single set of 1269 authentication credentials to choose from multiple identities, and 1270 allows multiple sets of authentication credentials to assume the same 1271 identity. 1273 For anonymous access the identity of the session is "@". A UPN with a 1274 null Username and null Realm is anonymous. A UPN with a null 1275 Username, but non-null Realm, such as "@foo.com" may be used to mean 1276 any identity from that Realm, which is useful to grant access rights 1277 to all users in a given Realm. A UPN with a non-null Username and 1278 null Realm, such as "bob@" could be a security risk and MUST NOT be 1279 used. 1281 As the UPN includes Realm information it may be used to govern 1282 calendar store access rights across Realms. However, governing access 1283 rights across Realms is only useful if login access is available. 1284 This could be done through a trusted server relationship or a 1285 temporary account. Note that trusted server relationships are outside 1286 the scope of [CAP]. 1288 The "IDENTIFY" command also provides for a weak group implementation. 1289 By allowing multiple sets of authentication credentials belonging to 1290 different users to identify as the same UPN, that UPN essentially 1291 identifies a group of people, and may be used for group calendar 1292 ownership, or the granting of access rights to a group. 1294 5. CAP URL and Calendar Address 1296 The CAP URL scheme is used to designate calendar stores and calendars 1297 accessible using the CAP protocol. 1299 The CAP URL scheme conform to the generic URL syntax, defined in RFC 1300 2396, and follows the Guidelines for URL Schemes, set forth in RFC 1301 2718. 1303 A CAP URL begins with the protocol prefix "cap" and is defined by the 1304 following grammar. 1306 capurl = "cap://" csid [ "/" relcalid ] 1307 csid = hostport ; As defined in Section 3.2.2 of RFC 2396 1308 relcalid = *uric ; As defined in Section 2 of RFC 2396 1310 A 'relcalid' is an identifier that uniquely identifies a calendar on 1311 a particular calendar store. There is no implied structure in a 1312 Relative CALID (relcalid). It may refer to the calendar of a user or 1313 of a resource such as a conference room. It MUST BE unique within the 1314 calendar store. 1316 Examples: 1318 cap://cal.example.com 1319 cap://cal.example.com/Company/Holidays 1320 cap://cal.example.com/abcd1234Usr 1322 A 'relcalid' is permitted and is resolved according to the rules 1323 defined in Section 5 of RFC 2396. 1325 Examples of valid relative CAP URLs: 1327 opqaueXzz123String 1328 UserName/Personal 1330 A Calendar addresses can be described as qualified or relative CAP 1331 URLs. 1333 For a user currently authenticated to the CS on cal.example.com, 1334 these two example calendar addresses refer to the same calendar: 1336 cap://cal.example.com/abcd1234USR 1337 abcd1234USR 1339 6. New Value Types 1341 The following sections contains new components, properties, 1342 parameters, and value definitions. 1344 The purpose of these is to extend the iCalendar objects in a 1345 compatible way so that existing iCalendar "VERSION" property "2.0" 1346 value parsers can still parse the objects without modification. 1348 6.1 Property Value Data Types 1350 6.1.1 CAL-QUERY Value Type 1352 Subject: Registration of text/calendar MIME value type CAL-QUERY 1354 Value Name: CAL-QUERY 1356 Value Type Purpose: This value type is used to identify values and 1357 contains query statements targeted at locating those values. 1359 This is based on [SQL92] and [SQLCOM]. 1361 1. For the purpose of a query, all components should be handled as 1362 tables, and the properties of those components, should be handled 1363 as columns. 1365 2. All VAGENDAs and CSs look like tables for the purpose of a QUERY. 1366 And all of their properties look like columns in those tables. 1368 3. You CAN NOT do any cross component-type joins. And that means you 1369 can ONLY have one component, OR one "VAGENDA" component OR one 1370 "VCALSTORE" component in the "FROM" clause. 1372 4. Everything in the "SELECT" clause and "WHERE" clauses in MUST BE 1373 from the same component type, or "VAGENDA" component OR 1374 "VCALSTORE" component in the "FROM" clause. 1376 5. When multiple "QUERY" properties are supplied in a single 1377 "VQUERY" component, the results returned are the same as the 1378 results returned for multiple "VQUERY" components having each a 1379 single "QUERY" property. 1381 6. The '.' is used to separate the table name (component) and column 1382 name (property or component) when selecting a property that is 1383 contained inside of a component that is targeted in the TARGET 1384 property. 1386 7. A contained component without a '.' is not the same as 1387 "component-name.*". If given as "component-name" (no dot) the 1388 encapsulating BEGIN/END statement will be supplied for 1389 "component-name".: 1391 In this example the '.' is used to separate the "TRIGGER" property 1392 from its contained component (VALARM). Which is contained in any 1393 "VEVENT" component in the selected "TARGET" property value (a 1394 relcalid). All "TRIGGER" properties in any "VEVENT" component in 1395 relcalid would be returned. 1397 TARGET:relcalid 1398 QUERY:SELECT VALARM.TRIGGER FROM VEVENT 1400 SELECT VALARM FROM VEVENT WHERE UID = "123" 1402 This returns one BEGIN/END "VALARM" component for each 1403 "VALARM" component in the matching "VEVENT" component. 1404 As there is no '.' (dot) in the VALARM after the SELECT above: 1406 BEGIN:VALARM 1407 TRIGGER;RELATED=END:PT5M 1408 REPEAT:4 1409 ... 1410 END:VALARM 1411 BEGIN:VALARM 1412 TRIGGER;RELATED=START:PT5M 1413 DURATION:PT10M 1414 ... 1415 END:VALARM 1416 ... 1417 ... 1419 If provided as "component-name.*", then only the properties and any 1420 contained components will be returned: 1422 SELECT VALARM.* FROM VEVENT WHERE UID = "123" 1424 Will return all of the properties in each "VALARM" component 1425 in the matching "VEVENT" component: 1427 TRIGGER;RELATED=END:PT5M 1428 REPEAT:4 1429 ... 1430 TRIGGER;RELATED=START:PT5M 1431 DURATION:PT10M 1432 ... 1433 ... 1435 (a) SELECT FROM VEVENT 1437 (b) SELECT VALARM FROM VEVENT 1439 (c) SELECT VALARM.* FROM VEVENT 1441 (d) SELECT * FROM VEVENT 1443 (e) SELECT * FROM VEVENT WHERE 1444 VALARM.TRIGGER < '20020201T000000Z' 1445 AND VALARM.TRIGGER > '20020101T000000Z' 1447 Note: 1448 (a) Selects all instances of 1449 from all "VEVENT" components. 1451 (b) and (c) Select all "VALARM" components from all 1452 "VEVENT" components. (b) would return then in 1453 BEGIN/END VALARM tags. (c) would return all 1454 of the properties without BEGIN/END VALARM tags. 1456 (d) Selects every property and every component 1457 that is in any "VEVENT" component, with each "VEVENT" 1458 component wrapped in a BEGIN/END VALARM tags. 1460 (e) Selects all properties and all contained 1461 components in all "VEVENT" components that have a "VALARM" 1462 component with a "TRIGGER" property value between 1463 the provided dates and times, with each "VEVENT" 1464 component wrapped in a BEGIN/END VALARM tags. 1466 NOT VALID: 1468 (f) SELECT VEVENT.VALARM.TRIGGER FROM VEVENT 1470 (g) SELECT DTSTART,UID FROM VEVENT WHERE 1471 VTODO.SUMMERY = "Fix typo in CAP" 1472 Note: (f) Is NOT valid because it contains 1473 two '.' characters in the "SELECT" clause. 1475 (g) Is NOT valid because it mixes VEVENT 1476 and VTODO properties in the same VQUERY. 1478 Formal Definition: The value type is defined by the following 1479 notation: 1481 cal-query = "SELECT" SP cap-val SP 1482 "FROM" SP comp-name SP 1483 "WHERE" SP cap-expr 1485 / "SELECT" SP cap-cols SP 1486 "FROM" SP comp-name 1488 cap-val = cap-cols / param 1489 / ( cap-val "," cap-val ) 1491 ; NOTE: there is NO space around the "," on 1492 ; the next line 1493 cap-cols = cap-col / ( cap-cols "," cap-col) 1494 / "*" 1496 ; A 'cap-col' is: 1497 ; 1498 ; Any property name ('cap-prop') found in the component 1499 ; named in the 'comp-name' used in the "FROM" clause. 1500 ; 1501 ; SELECT ORGANIZER FROM VEVENT ... 1502 ; 1503 ; OR 1504 ; 1505 ; A component name ('comp-name') of an existing component 1506 ; contained inside of the 'comp-name' used in the "FROM" 1507 ; clause. 1508 ; 1509 ; SELECT VALARM FROM VEVENT ... 1510 ; 1511 ; OR 1512 ; 1513 ; A component name ('comp-name') of an existing 1514 ; component contained inside of the 'comp-name' used 1515 ; in the "FROM" clause followed by a property 1516 ; name ('cap-prop') to be selected from that component. 1518 ; (comp-name "." cap-prop) 1519 ; 1520 ; SELECT VALARM.TRIGGER FROM VEVENT ... 1522 cap-col = comp-name 1523 / comp-name "." cap-prop 1524 / cap-prop 1526 comp-name = "VEVENT" / "VTODO" / "VJOURNAL" / "VFREEBUSY" 1527 / "VALARM" / "DAYLIGHT" / "STANDARD" / "VAGENDA" 1528 / "VCAR" / "VCALSTORE" / "VQUERY" / "VTIMEZONE" 1529 / "VRIGHT" / x-comp / iana-comp 1531 cap-prop = ; A property that may be in the 'cap-comp' named 1532 ; in the "SELECT" clause. 1534 cap-expr = "(" cap-expr ")" 1535 / cap-term 1537 cap-term = cap-expr SP cap-logical SP cap-expr 1538 / cap-factor 1540 cap-logical= "AND" / "OR" 1542 cap-factor = cap-colval SP cap-oper SP col-value 1543 / cap-colval SP "LIKE" SP col-value 1544 / cap-colval SP "NOT LIKE" SP col-value 1545 / cap-colval SP "IS NULL" 1546 / cap-colval SP "IS NOT NULL" 1547 / col-value SP "IN" cap-colval" 1548 / col-value SP "NOT IN" cap-colval" 1549 / "STATE()" "=" ( "BOOKED" 1550 / "UNPROCESSED" 1551 / "DELETED" 1552 / iana-state 1553 / x-state ) 1555 iana-state = ; Any state registered by IANA directly or 1556 ; included in an RFC that may be applied to 1557 ; the component and within the rules published. 1559 x-state = ; Any experimental state that starts with 1560 ; "x-" or "X-". 1562 cap-colval = cap-col / param 1564 param = "PARAM(" cap-col "," cap-param ")" 1565 cap-param = ; Any parameter that may be contained in the cap-col 1566 ; in the supplied PARAM() function 1568 col-value = col-literal 1569 / "SELF()" 1570 / "CAL-OWNERS()" 1571 / "CAL-OWNERS(" cal-address ")" 1572 / "CURRENT-TARGET()" 1574 cal-address = ; A CALID as define by CAP 1576 col-literal = "'" literal-data "'" 1578 literal-data = ; Any data that matches the value type of the 1579 ; column that is being compared. That is you can 1580 ; not compare PRIORITY to "some string" because 1581 ; PRIORITY has a value type of integer. If it is 1582 ; not preceded by the LIKE element, any '%' and '_' 1583 ; characters in the literal data are not treated as 1584 ; wildcard characters and do not have to be backslash 1585 ; escaped. 1586 ; 1587 ; OR 1588 ; 1589 ; If the literal-data is preceded by the LIKE 1590 ; element it may also contain the '%' and '_' 1591 ; wildcard characters. And if the literal data 1592 ; that is comparing contains any '%' or '_' 1593 ; characters, they MUST BE backslash escaped as 1594 ; described in the notes below in order for them not 1595 ; to be treated as wildcard characters. 1596 ; 1597 ; And if the literal data contains any characters 1598 ; that would have to be backslash escaped if 1599 ; a property or parameter value then they must 1600 ; be backslash escaped in the literal-data. 1601 ; PLUS the quote character (') must be backslash 1602 ; escaped. Example: 1603 ; 1604 ; ... WHERE SUBJECT = 'It\'s time to ski' 1605 ; 1607 cap-oper = "=" 1608 / "!=" 1609 / "<" 1610 / ">" 1611 / "<=" 1612 / ">=" 1613 SP = ; A single white space ASCII character 1614 ; (value in HEX %x20). 1616 x-comp = ; As defined in [iCAL] section 4.6 1618 iana-comp = ; As defined in [iCAL] section 4.6 1620 6.1.1.1 [NOT] CAL-OWNERS() 1622 This function returns the list of "OWNER" properties for the named 1623 calendar when used in the "SELECT" clause. 1625 If called as 'CAL-OWNERS()', it is equivalent to the comma separated 1626 list of all of the owners of the calendar that match the provided 1627 "TARGET" property value. If the target is a "VCALSTORE", it returns 1628 the "CALMASTER" property. 1630 If called as 'CAL-OWNERS(cal-address)', then it is the equivalent to 1631 the comma separated list of owners for the named calendar id. If 1632 'cal-address' is a CS, it returns the "CALMASTER" property. 1634 If used in the "WHERE" clause it then returns true if the currently 1635 authenticated UPN is an owner of the currently selected object 1636 matched in the provided "TARGET" property. Used in a CAL-QUERY 1637 "WHERE" clause and in the UPN-FILTER. 1639 6.1.1.2 CURRENT-TARGET() 1641 Is equivalent to the value of the "TARGET" property in the current 1642 command. Used in a CAL-QUERY "WHERE" clause. 1644 6.1.1.3 PARAM() 1646 Used in a CAL-QUERY. Returns or tests for the value of the named 1647 parameter from the named property. 1649 6.1.1.3.1 PARAM() in SELECT 1651 When used in a "SELECT" clause, it returns the entire property and 1652 all of that properties parameters (the result is not limited to the 1653 supplied parameter). If the property does not contain the named 1654 parameter, then the property is not returned (It could however be 1655 returned as a result of another "SELECT" clause value.) If multiple 1656 properties of the supplied name have the named parameter, all 1657 properties with that named parameter are returned. If multiple 1658 PARAM() clauses in a single "SELECT" CLAUSE match the same property, 1659 then the single matching property is returned only once. 1661 Also note that many parameters have default values defined in [iCAL] 1662 that must be treated as existing with their default value in the 1663 properties as defined in [iCAL} even when not explicitly present. So 1664 for example if a query were performed with PARAM(ATTENDEE,ROLE) then 1665 ALL "ATTENDEE" properties would match because even when they do not 1666 explicitly contain the "ROLE" parameter, it has a default value and 1667 therefore must match. 1669 So when PARAM() is used in a "SELECT" clause, then it is more 1670 accurate to say that it means return the property if it contains the 1671 named parameter explicitly in the property or simply because the 1672 parameter has a default for that property. 1674 6.1.1.3.2 PARAM() in WHERE 1676 When used in the "WHERE" clause, a match is true when the parameter 1677 value matches the compare clause according to the supplied WHERE 1678 values. If multiple named properties contain the named parameter, 1679 then each parameter value is compared in turn to the condition and if 1680 any match, then the results would be true for that condition the same 1681 as if only one had existed. Each matching properties or components 1682 are returned only once. 1684 As a parameter may be multivalued then the comparison might need to 1685 be done with an "IN" or "NOT IN" comparator. 1687 Given the following query: 1689 ATTENDEE;PARTSTAT=ACCEPTED:cap://host.com/joe 1691 SELECT VEVENT FROM VAGENDA 1692 WHERE PARAM(ATTENDEE,PARTSTAT) = 'ACCEPTED' 1694 Then all "VEVENT" components that contain one or more "ATTENDEE" 1695 properties that have a "PARTSTAT" parameter with a "ACCEPTED" value 1696 would be returned. And each uniquely matching VEVENT would only be 1697 returned once no matter how many "ATTENDEE" properties had matching 1698 roles in each unique "VEVENT" component. 1700 Also note that many parameters have default values defined in [iCAL]. 1701 So if the following query were performed on the "ATTENDEE" property 1702 in the above example: 1704 SELECT VEVENT FROM VAGENDA 1705 WHERE PARAM(ATTENDEE,ROLE) = 'REQ-PARTICIPANT' 1707 It would return the "ATTENDEE" property exampled above because the 1708 default value for the "ROLE" parameter is "REQ-PARTICIPANT". 1710 6.1.1.4 SELF() 1712 Used in a CAL-QUERY "WHERE" clause. Returns the UPN of the currently 1713 authenticated UPN or their current UPN as a result of an IDENTIFY 1714 command. 1716 6.1.1.5 STATE() 1718 Returns one of three values, "BOOKED", "UNPROCESSED", or "DELETED" 1719 depending on the state of the object. Where "DELETED" is a component 1720 in the marked for delete state. Components that have been removed 1721 from the store are never returned. 1723 If not specified in a query then both "BOOKED" and "UNPROCESSED" data 1724 is returned. Each unique "METHOD" property must be in a separate MIME 1725 object per the [iCAL] section 3.2 restriction. 1727 6.1.1.6 Use of single quote 1729 All literal values are surrounded by single quotes ('), not double 1730 quotes ("), and not without any quotes. If the value contains quotes 1731 or any other ESCAPED-CHAR, they MUST BE backslash escaped as 1732 described in section 4.3.11 "Text" of [iCAL]. Any "LIKE" clause 1733 wildcard characters that are part of any literal data that is 1734 preceded by a "LIKE" clause or "NOT LIKE" clause and is not intended 1735 to mean wildcard search MUST BE escaped as described in note (7) 1736 below. 1738 6.1.1.7 Comparing DATE and DATE-TIME values 1740 When comparing "DATE-TIME" values to "DATE" values and when comparing 1741 "DATE" values to "DATE-TIME" values, the result will be true if the 1742 "DATE" value is on the same day as the "DATE-TIME" value. And they 1743 are compared in UTC no matter what time zone the data may actual have 1744 been stored in. 1746 Local time event as descibed in section 4.2.19 of [iCAL] must be 1747 considered to be in the CUA default timezone that was supplied by the 1748 CUA in the "CAPABILITY" exchange. 1750 VALUE-1 VALUE-2 Compare Results 1752 20020304 20020304T123456 TRUE 1753 (in UTC-3) (in UTC-3) 1754 20020304 20020304T003456 FALSE 1755 (in UTC) (in UTC-4) 1757 20020304T003456Z 20020205T003456 FALSE 1758 (in UTC-0) (in UTC-7) 1760 When comparing "DATE" values and "DATE-TIME" values with the "LIKE" 1761 clause the comparison will be done as if the value is a [iCAL] DATE 1762 or DATE-TIME string value. 1764 LIKE '2002%' will match anything in the year 2002. 1766 LIKE '200201%' will match anything in January 2002. 1768 LIKE '%T000000' will match anything at midnight. 1770 LIKE '____01__T%' will match anything for any year or 1771 time that is in January. 1772 (Four '_', '01', two '_' 'T%'). 1774 Using a "LIKE" clause value of "%00%, would return any value that 1775 contained two consecutive zeros. 1777 All comparisons will be done in UTC. 1779 6.1.1.8 DTEND and DURATION 1781 The "DTEND" property value is not included in the time occupied by 1782 the component. That is a "DTEND" property value of 20030614T12000 1783 includes all of the time up to but not including noon on that day. 1785 The "DURATION" property value end time is also not inclusive. So an 1786 object with a "DTSTART" property value of 20030514T110000 and a 1787 "DURATION" property value of "1H" does not include noon on that day. 1789 When a "QUERY" property value contains a "DTEND" value, then the CS 1790 MUST also evaluate any existing "DURATION" property value and 1791 determine if it has an effective end time that matches the "QUERY" 1792 property supplied "DTEND" value or any range of values supplied by 1793 the "QUERY" property. 1795 When a "QUERY" property contains a "DURATION" value, then the CS MUST 1796 also evaluate any existing "DTEND" property values and determine if 1797 they have an effective duration that matches the "QUERY" property 1798 value supplied "DURATION" value or any range of values supplied by 1799 the "QUERY" property. 1801 6.1.1.9 [NOT] LIKE 1803 The pattern matching characters are the '%' that matches zero or more 1804 characters, and '_' that matches exactly one character (where 1805 character does not always mean octet). 1807 "LIKE" clause pattern matches always cover the entire string. To 1808 match a pattern anywhere within a string, the pattern must start and 1809 end with a percent sign. 1811 To match a '%' or '_' in the data and not have it interpreted as a 1812 wildcard character, they MUST BE backslash escaped. That is to search 1813 for a '%' or '_' in the string: 1815 LIKE '%\%%' Matches any string with a '%' in it. 1816 LIKE '%\_%' Matches any string with a '_' in it. 1818 Strings compared using the "LIKE" clause MUST BE performed using case 1819 in-sensitive comparisons when the locale allows. (Example: in 1820 US-ASCII the compare assumes 'a' = 'A'). 1822 If the "LIKE" clause is preceded by 'NOT' then there is a match when 1823 the string compare fails. 1825 Some property values (such as the 'recur' value type), contain commas 1826 and are not multi valued. The CS must understand the objects being 1827 compared and understand how to determine how any multi valued or 1828 multi instances properties or parameter values are separated, quoted, 1829 and backslash escaped and perform the comparisons as if each value 1830 existed by itself and not quoted or backslash escaped when comparing 1831 using the LIKE element. 1833 See related examples in Section 6.1.1.11 1835 6.1.1.10 Empty vs. NULL 1837 When used in a CAL-QUERY value, "NULL" means that the property or 1838 parameter is not present in the object. Paramaters that are not 1839 provided and have a default value in the property are considered to 1840 exist with their default value and will not be "NULL". 1842 If the property exists but has no value then "NULL" MUST NOT match. 1843 If the parameter exists but has no value then "NULL" MUST NOT match. 1844 If the parameter not present and has a default value then "NULL" MUST 1845 NOT match. 1847 If the property (or parameter) exists, but has no value then it 1848 matches the empty string '' (quote quote). 1850 6.1.1.11 [NOT] IN 1852 This is similar to the "LIKE" clause, except it does value matching 1853 and not string comparison matches. 1855 Some iCalendar objects can be multi instance and multi valued. The 1856 "IN" clause will return a match if the literal value supplied as part 1857 of the "IN" clause is contained in the value of any instance of the 1858 named property or parameter, or is in any of the multiple values in 1859 the named property or parameter. Unlike the "LIKE" clause, the '%' 1860 and '_' matching characters are not used with the "IN" clause and 1861 have no special meaning. 1863 BEGIN:A-COMPONENT 1864 a property:value1,value2 One property, two values. 1865 b property:"value1,value2" One property, one value. 1866 c property:parameter=1,2:x One parameter, two values. 1867 d property:parameter="1,2",3:y One parameter, one value. 1868 e property:parameter=",":z One parameter, one value. 1869 f property:x,y,z One property, three values 1870 END:A-COMPONENT 1872 'value1' IN property would match (a) only. 1873 'value1,value2' IN property would match (b) only. 1874 'value%' IN property would NOT match any. 1875 ',' IN property would NOT match any. 1876 '%,%' IN property would NOT match any. 1877 'x' IN property would match (f) and (c). 1878 '2' IN parameter would match (c) only. 1879 '1,2' IN parameter would match (d) only. 1880 ',' IN parameter would match (e) only. 1881 '%,%' IN parameter would NOT match any. 1883 property LIKE 'value1%' would match (a) and (b). 1884 property LIKE 'value%' would match (a) and (b). 1885 property LIKE 'x' would match (f) and (c). 1886 parameter LIKE '1%' would match (c) and (d). 1887 parameter LIKE '%2%' would match (c) and (d). 1888 parameter LIKE ',' would match (e) only. 1890 Some property values (such as the "RECUR" value type), contain commas 1891 and are not multi valued. The CS must understand the objects being 1892 compared and understand how to determine how any multi valued or 1893 multi instances properties or parameter values are separated, quoted, 1894 and backslash escaped and perform the comparisons as if each value 1895 existed by itself and not quoted or backslash escaped when comparing 1896 using the IN element. 1898 If the "IN" clause is preceded by 'NOT' then there is a match when 1899 the value does not exist in the property or parameter value. 1901 6.1.1.12 DATE-TIME and TIME values in a WHERE clause 1903 All "DATE-TIME" and "TIME" literal values supplied in a "WHERE" 1904 clause MUST BE terminated with 'Z'. That means that the CUA MUST 1905 supply the values in UTC. 1907 Valid: 1909 WHERE alarm.TRIGGER < '20020201T000000Z' 1910 AND alarm.TRIGGER > '20020101T000000Z' 1912 Not valid and it is a syntax error and the CS MUST reject the QUERY. 1914 WHERE alarm.TRIGGER < '20020201T000000' 1915 AND alarm.TRIGGER > '20020101T000000' 1917 6.1.1.13 Multiple contained components 1919 If a query references a component and a component or property 1920 contained in the component, any clauses referring to the contained 1921 component or property must be evaluated on all of the contained 1922 components or properties. If any of the contained components or 1923 properties match the query, and the conditions on the containing 1924 component are also true, the component matches the query. 1926 For example, in the query below, if a BOOKED VEVENT contains multiple 1927 VALARMs, and the VALARM.TRIGGER clause is true for any of the VALARMs 1928 in the VEVENT, then the UID, SUMMARY, and DESCRIPTION of this VEVENT 1929 would be included in the QUERY results. 1931 BEGIN:VQUERY 1932 EXPAND:TRUE 1933 QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT 1934 WHERE VALARM.TRIGGER >= '20000101T030405Z' 1935 AND VALARM.TRIGGER <= '20001231T235959Z' 1936 AND STATE() = 'BOOKED' 1937 END:VQUERY 1939 6.1.1.14 Example, Query by UID 1941 The following example would match the entire content of a "VEVENT" or 1942 "VTODO" component with the "UID" property equal to "uid123" and not 1943 expand any multiple instances of the component. If the CUA does not 1944 know if "uid123" was a "VEVENT", "VTODO", "VJOURNAL", or any other 1945 component, then all components that the CUA supports MUST BE supplied 1946 in a QUERY property. This example assumes the CUA is only interested 1947 in "VTODO" and "VEVENT" components. 1949 If the results were empty it could also mean that "uid123" was a 1950 property in a component other than a VTODO or VEVENT. 1952 BEGIN:VQUERY 1953 QUERY:SELECT * FROM VTODO WHERE UID = 'uid123' 1954 QUERY:SELECT * FROM VEVENT WHERE UID = 'uid123' 1955 END:VQUERY 1957 6.1.1.15 Query by Date-Time range 1959 This query selects the entire content of every booked "VEVENT" 1960 component that has an instance greater than or equal to July 1st, 1961 2000 00:00:00 UTC and less than or equal to July 30st, 2000 23:59:59 1962 UTC. This includes single instance "VEVENT" components that do no 1963 explicitly contain any recurence properties or "RECURRENCE-ID" 1964 properties. This works only for CSs that have the "RECUR-EXPAND" 1965 property value set to "TRUE" in the "GET-CAPABILITY" exchange. 1967 BEGIN:VQUERY 1968 EXPAND:TRUE 1969 QUERY:SELECT * FROM VEVENT 1970 WHERE RECURRENCE-ID >= '20000701T000000Z' 1971 AND RECURRENCE-ID <= '20000730T235959Z' 1972 AND STATE() = 'BOOKED' 1973 END:VQUERY 1975 6.1.1.16 Query for all Unprocessed Entries 1977 The following example selects the entire contents of all non-booked 1978 "VTODO" and "VEVENT" components in the "UNPROCESSED" state. The 1979 default for the "EXPAND" property is FALSE, so the recurrence rules 1980 will not be expanded. 1982 BEGIN:VQUERY 1983 QUERYID:Fetch VEVENT and VTODO iTIP components 1984 QUERY:SELECT * FROM VEVENT WHERE STATE() = 'UNPROCESSED' 1985 QUERY:SELECT * FROM VTODO WHERE STATE() = 'UNPROCESSED' 1986 END:VQUERY 1988 The following example fetches all "VEVENT" and "VTODO" components in 1989 the "BOOKED" state. 1991 BEGIN:VQUERY 1992 QUERYID:Fetch All Booked VEVENT and VTODO components 1993 QUERY:SELECT * FROM VEVENT WHERE STATE() = 'BOOKED' 1994 QUERY:SELECT * FROM VTODO WHERE STATE() = 'BOOKED' 1995 END:VQUERY 1997 The following fetches the "UID" property for all "VEVENT" and "VTODO" 1998 components that have been marked for delete. 2000 BEGIN:VQUERY 2001 QUERYID:Fetch UIDs of marked for delete VEVENTs and VTODOs 2002 QUERY:SELECT UID FROM VEVENT WHERE STATE() = 'DELETE' 2003 QUERY:SELECT UID FROM VTODO WHERE STATE() = 'DELETE' 2004 END:VQUERY 2006 6.1.1.17 Query with Subset of Properties by Date/Time 2008 In this example only the named properties will be selected and all 2009 booked and non-booked components will be selected that have a 2010 "DTSTART" value from February 1st to February 10th 2000 (in UTC). 2012 BEGIN:VQUERY 2013 QUERY:SELECT UID,DTSTART,DESCRIPTION,SUMMARY FROM VEVENT 2014 WHERE DTSTART >= '20000201T000000Z' 2015 AND DTSTART <= '20000210T235959Z' 2016 END:VQUERY 2018 6.1.1.18 Query with Components and Alarms In A Range 2020 This example fetches all booked "VEVENT" components with an alarm 2021 that triggers within the specified time range. In this case only the 2022 "UID", "SUMMARY", and "DESCRIPTION" properties will be selected for 2023 all booked "VEVENTS" components that have an alarm between the two 2024 date-times supplied. 2026 BEGIN:VQUERY 2027 EXPAND:TRUE 2028 QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT 2029 WHERE VALARM.TRIGGER >= '20000101T030405Z' 2030 AND VALARM.TRIGGER <= '20001231T235959Z' 2031 AND STATE() = 'BOOKED' 2032 END:VQUERY 2034 6.1.2 UPN Value Type 2036 Value Name: UPN 2038 Purpose: This value type is used to identify values that contain user 2039 principal name of CU or group of CU. 2041 Formal Definition: The value type is defined by the following 2042 notation: 2044 upn = "@" 2045 / [ dot-atom-text ] "@" dot-atom-text 2047 ; dot-atom-text is defined in RFC 2822 2049 Description: This data type is an identifier that denotes a CU or a 2050 group of CU. A UPN is a RFC 2822 compliant email address, with 2051 exceptions listed below, and in most cases it is deliverable to the 2052 CU. In some cases it is identical to the CU's well known email 2053 address. A CU's UPN MUST never be an e-mail address that is 2054 deliverable to a different person. And there is no requirement that a 2055 person's UPN MUST BE their e-mail address. A UPN is formatted as a 2056 user name followed by "@" followed by a Realm in the form of a valid, 2057 and unique, DNS domain name. The user name MUST BE unique within the 2058 Realm. In it's simplest form it looks like "user@example.com". 2060 In certain cases a UPN will not be RFC 2822 compliant. When anonymous 2061 authentication is used, or anonymous authorization is being defined, 2062 the special UPN "@" will be used. When authentication MUST BE used, 2063 but unique identity MUST BE obscured, a UPN of the form 2064 @DNS-domain-name may be used. For example, "@example.com". 2066 Example: 2068 The following is a UPN for a CU: 2070 jdoe@example.com 2072 The following is a example of a UPN that could be for a group of CU: 2074 staff@example.com 2076 The following is a UPN for an anonymous CU belonging to a specific 2077 realm or when used as a UPN-FILTER it specifies that it applies to 2078 all UPNs in a specific realm: 2080 @example.com 2082 The following is a UPN for an anonymous CU: 2084 @ 2086 6.1.3 UPN-FILTER Value 2088 Value Name: UPN-FILTER 2090 Purpose: This value type is used to identify values that contain a 2091 user principal name filter. 2093 Formal Definition: The value type is defined by the following 2094 notation: 2096 ; NOTE: "CAL-OWNERS(cal-address)" 2097 ; and "NOT CAL-OWNERS(cal-address)" 2098 ; are both NOT allowed below. 2099 ; 2100 upn-filter = "CAL-OWNERS()" / 2102 "NOT CAL-OWNERS()" / 2103 "*" / 2104 [ "*" / dot-atom-text ] "@" ( "*" / dot-atom-text ) 2106 ; dot-atom-text is defined in RFC 2822 2108 Description: The value is used to match user principal names (UPNs). 2109 For "CAL-OWNERS()" and "NOT CAL-OWNERS()", see Section 8.24. 2111 * Matches all UPNs. 2113 @ Matches the UPN of anonymous CUs 2114 belonging to the null realm 2116 @* Matches the UPN of anonymous CUs 2117 belonging to any non-null realm 2119 @realm Matches the UPN of anonymous CUs 2120 belonging to the specified realm. 2122 *@* Matches the UPN of non-anonymous CUs 2123 belonging to any non-null realm 2125 *@realm Matches the UPN of non-anonymous CUs 2126 belonging to the specified realm 2128 user@realm Matches the UPN of the specified CU 2129 belonging to the specified realm 2131 user@* Not allowed. 2133 user@ Not allowed. 2135 Example: The following are examples of this value type: 2137 DENY:NON CAL-OWNERS() 2138 DENY:@hackers.example.com 2139 DENY:*@hackers.example.com 2140 GRANT:sam@example.com 2142 7. New Parameters 2144 7.1 ACTION Parameter 2146 Parameter Name: ACTION 2148 Purpose: This parameter indicates the action to be taken when a 2149 timeout occurs. 2151 Value Type: TEXT 2153 Conformance: This property can be specified in the "CMD" property. 2155 When present in a "CMD" property the "ACTION" parameter specifies the 2156 action to be taken when the command timeout expires. 2158 Formal Definition: The parameter is defined by the following 2159 notation: 2161 action-param = ";" "ACTION" "=" ( "ASK" / "ABORT" ) 2162 ; If 'action-param' is supplied then 2163 ; 'latency-param' MUST BE supplied. 2165 Example: The following is an example of this parameter: 2167 CMD;LATENCY=10;ACTION=ASK:CREATE 2169 7.2 ENABLE Parameter 2171 Parameter Name: ENABLE 2173 Purpose: This parameter indicates whether or not the property should 2174 be ignored. Example if a "TRIGGER" property in a "VALARM" component 2175 should be ignored. 2177 Value Type: BOOLEAN 2179 Conformance: This property can be specified in the "TRIGGER" 2180 properties. 2182 Description: When a non owner sends an [iTIP] "REQUEST" to a calendar 2183 that object might contain a "VALARM" component. The owner may wish to 2184 have local control over their own CUA and when or how alarms are 2185 triggered. 2187 A CUA may add the "ENABLE" parameter to any "TRIGGER" property before 2188 booking the component. If the "ENABLE" parameter is set to "FALSE", 2189 then the alarm will be ignored by the CUA. If set to "TRUE", or if 2190 the "ENABLE" property is not in the "TRIGGER" property, the alarm is 2191 enabled. This parameter may not be known by pre-CAP implementations 2192 and should not be an issue as it conforms to an 'ianaparam' as 2193 defined in [iCAL]. 2195 Formal Definition: The property is defined by the following notation: 2197 enable-param = "ENABLE" "=" boolean 2199 Example: The following is an example of this property for a "VAGENDA" 2200 component: 2202 TRIGGER;ENABLE=FALSE;RELATED=END:PT5M 2204 7.3 ID Parameter 2206 Parameter Name: ID 2208 Purpose: When used in a "CMD" component provides a unique identifier. 2210 Value Type: TEXT 2212 Conformance: This parameter can be specified in the "CMD" property. 2214 Description: If there is more than one command sent then the "ID" 2215 parameter is used to uniquely identify the command. 2217 A CUA may add the "ID" parameter to any "CMD" property before sending 2218 the command. There must not be more than one outstanding command 2219 tagged with the same "ID" parameter value. 2221 Formal Definition: The property is defined by the following notation: 2223 id-param = ";" "ID" "=" unique-id 2224 ; The text value supplied is a unique value 2225 ; shared between the CUA and CS to uniquely 2226 ; identify the instance of command in the 2227 ; the current CUA session. The value has 2228 ; no meaning to other CUAs or other sessions. 2230 unique-id = ; text 2232 text = ; As defined in [iCAL]. 2234 Example: The following is an example of this parameter component: 2236 CMD;UD=some-unique-value:CREATE 2238 7.4 LATENCY Parameter 2240 Parameter Name: LATENCY 2242 Purpose: This parameter indicates time in seconds for when a timeout 2243 occurs. 2245 Value Type: TEXT 2247 Conformance: This property can be specified in the "CMD" property. 2249 When present in a "CMD" property the "LATENCY" parameter specifies 2250 the time in sections when the command timeout expires. 2252 Formal Definition: The parameter is defined by the following 2253 notation: 2255 latency-param = ";" "LATENCY" "=" latency-sec 2256 ; The value supplied in the time in seconds. 2257 ; If 'latency-param' is supplied then 2258 ; 'action-param' MUST BE supplied. 2260 latency-sec = posint1 2262 ; Default is zero (0) meaning no timeout. 2264 Example: The following is an example of this parameter: 2266 CMD;LATENCY=10;ACTION=ASK:CREATE 2268 7.5 LOCAL Parameter 2270 Parameter Name: LOCAL 2272 Purpose: Indicates if the named component should be exported to any 2273 non-organizer calendar. 2275 Value Type: BOOLEAN 2277 Conformance: This parameter can be specified in the "SEQUENCE" 2278 properties in a "VALARM" component. 2280 Description: When a non owner sends an [iTIP] "REQUEST" to a calendar 2281 that object might contain a "VALARM" component. The owner may wish to 2282 have local control over their own CUA and when or how alarms are 2283 triggered. 2285 A CUA may add the "LOCAL" parameter to the "SEQUENCE" property before 2286 booking the component. If the "LOCAL" parameter is set to "TRUE", 2287 then the alarm MUST NOT be forwarded to any other calender. If set to 2288 "FALSE", or if the "LOCAL" parameter is not in the "SEQUENCE" 2289 property, the alarm is global. 2291 Formal Definition: The property is defined by the following notation: 2293 local-param = "LOCAL" "=" boolean 2295 Example: The following is an example of this parameter: 2297 SEQUENCE;LOCAL=TRUE:4 2299 7.6 LOCALIZE Parameter 2301 Parameter Name: LOCALIZE 2303 Purpose: If provided the "LOCALIZE" parameter specifies the desired 2304 language for error and warning messages. 2306 Value Type: TEXT 2307 Conformance: This parameter can be specified in the "CMD" properties. 2309 When the "LOCALIZE" parameter is supplied then its value MUST BE one 2310 of the values listed in the initial [BEEP] greeting 'localize' 2311 attribute. 2313 A CUA may add the "LOCALIZE" parameter to the "CMD" property to 2314 specify the language of any error or warning messages. 2316 Formal Definition: The property is defined by the following notation: 2318 localize-param = ";" "LOCALIZE" "=" beep-localize 2320 beep-localize = text ; As defined in [BEEP] 2321 ; The value supplied MUST BE one value from the initial 2322 ; [BEEP] greeting 'localize' attribute specifying 2323 ; the locale to use for error messages during 2324 ; this instance of the command sent. 2326 Example: The following is an example of this parameter: 2328 CMD;LOCALIZE=fr_CA:CREATE 2330 7.7 OPTIONS Parameter 2332 Parameter Name: OPTIONS 2334 Purpose: If provided the "OPTIONS" parameter specifies some "CMD" 2335 property specific options. 2337 Value Type: TEXT 2339 Conformance: This parameter can be specified in the "CMD" properties. 2341 A CUA adds the "OPTIONS" parameter to the "CMD" property when the 2342 command needs extra values. 2344 Formal Definition: The property is defined by the following notation: 2346 option-param = ";" "OPTIONS" "=" cmd-specific 2348 cmd-specific = ; The value supplied is dependent on the 2349 ; CMD value. See the specific CMDs for the 2350 ; correct values to use for each CMD. 2352 Example: The following is an example of this parameter: 2354 CMD;OPTIONS=10:GENERATE-UID 2356 8. New Properties 2358 8.1 ALLOW-CONFLICT Property 2360 Property Name: ALLOW-CONFLICT 2362 Purpose: This property indicates whether or not the calendar and CS 2363 supports component conflicts. That is, whether or not any of the 2364 components in the calendar can overlap. 2366 Value Type: BOOLEAN 2368 Property Parameters: Non-standard property parameters can be 2369 specified on this property. 2371 Conformance: This property can be specified in "VAGENDA" and 2372 "VCALSTORE" component. 2374 Description: This property is used to indicate whether components may 2375 conflict. That is, if their expanded instances may share the same 2376 time or overlap the same time periods. If it has a value of TRUE, 2377 then conflicts are allowed. If FALSE, the no two components may 2378 conflict. 2380 If FALSE in the "VCALSTORE" component, then all "VAGENDA" component 2381 "ALLOW-CONFLICT" property values MUST BE false in the CS. 2383 Formal Definition: The property is defined by the following notation: 2385 allow-conflict = "ALLOW-CONFLICT" other-params ":" boolean CRLF 2387 Example: The following is an example of this property for a "VAGENDA" 2388 component: 2390 ALLOW-CONFLICT:FALSE 2392 8.2 ATT-COUNTER Property 2394 Property Name: ATT-COUNTER 2396 Property Parameters: Non-standard property parameters can be 2397 specified on this property. 2399 Conformance: This property MUST be specified in an iCalendar object 2400 that specifies counter proposal to a group scheduled calendar entity. 2401 When storing a "METHOD" property with the "COUNTER" method, there 2402 needs to be a way to remember who sent the COUNTER. The ATT-COUNTER 2403 property MUST BE added to all "COUNTER" [iTIP] components by the CUA 2404 before storing in a CS. 2406 Description: This property is used to identify the CAL-ADDRESS of the 2407 entity that sent the "COUNTER" [iTIP] object. 2409 Formal Definition: The property is defined by the following notation: 2411 attcounter = "ATT-COUNTER" other-params ":" cal-address CRLF 2413 Examples: 2415 ATT-COUNTER:cap:example.com/Doug 2416 ATT-COUNTER:mailto:Doug@Example.com 2418 8.3 CALID Property 2420 Property Name: CALID 2422 Property Parameters: Non-standard property parameters can be 2423 specified on this property. 2425 Conformance: This property can be specified in the "VAGENDA" 2426 component. 2428 Description: This property is used to specify a fully qualified 2429 CALID. 2431 Formal Definition: The property is defined by the following notation: 2433 CALID = "CALID" other-params ":" relcalid CRLF 2435 Example: 2437 CALID:cap://cal.example.com/sdfifgty4321 2439 8.4 CALMASTER Property 2441 Property Name: CALMASTER 2443 Purpose: The property specifies an e-mail address of a person 2444 responsible for the calendar store. 2446 Value Type: URI 2448 Property Parameters: Non-standard property parameters can be 2449 specified on this property. 2451 Conformance: The property can be specified in a "VCALSTORE" 2452 component. 2454 Description: The parameter value SHOULD BE a MAILTO URI as defined in 2455 [URL]. It MUST BE a contact URI such as a MAILTO URI and not a home 2456 page or file URI that describes how to contact the calmasters. 2458 Formal Definition: The property is defined by the following notation: 2460 calmaster = "CALMASTER" other-params ":" uri CRLF 2462 uri = ; IANA registered uri as defined in [iCAL] 2464 Example: The following is an example of this property: 2466 CALMASTER:mailto:administrator@example.com 2468 8.5 CAP-VERSION Property 2470 Property Name: CAP-VERSION 2472 Purpose: This property specifies the version of CAP supported. 2474 Value Type: TEXT 2476 Property Parameters: Non-standard property parameters can be 2477 specified on this property. 2479 Conformance: This property is specified in the "VREPLY" component 2480 that is sent in response to a "GET-CAPABILITY" command. 2482 Description: This specifies the version of CAP that the endpoint 2483 supports. The list is a comma separated list of RFC numbers 2484 supported. The list MUST contain at least XXXX (NOTE 'XXXX' WILL BE 2485 REPLACED WITH THE RFC NUMBER OF THIS DOCUMENT). 2487 Formal Definition: The property is defined by the following notation: 2489 cap-version = "CAP-VERSION" other-params ":" text CRLF 2491 Example: The following are examples of this property: 2493 CAP-VERSION:XXXX 2495 8.6 CARID Property 2497 Property Name: CARID 2499 Purpose: This property specifies the identifier for an access right 2500 component. 2502 Value Type: TEXT 2504 Property Parameters: Non-standard property parameters can be 2505 specified on this property. 2507 Conformance: This property MUST BE specified once in a "VCAR" 2508 component. 2510 Description: This property is used in the "VCAR" component to specify 2511 an identifier. A "CARID" property value is unique per container. 2513 Formal Definition: The property is defined by the following notation: 2515 carid = "CARID" other-params ":" text CRLF 2517 Example: The following are examples of this property: 2519 CARID:xyzzy-007 2520 CARID:User Rights 2522 8.7 CAR-LEVEL Property 2524 Property Name: CAR-LEVEL 2525 Purpose: The property specifies the level of VCAR supported. 2527 Value Type: TEXT 2529 Property Parameters: Non-standard property parameters can be 2530 specified on this property. 2532 Conformance: The property can be specified in a "VREPLY" component 2533 that is sent in response to a "GET-CAPABILITY" command. 2535 Description: The value is one from a list of "CAR-NONE", "CAR-MIN", 2536 or "CAR-FULL-1". If "CAR-FULL-1" is supplied then "CAR-MIN" is also 2537 available. A "CAR-MIN" implementation only supported the 2538 "DEFAULT-VCARS" property values listed in the "VCALSTORE" component 2539 and a "CAR-MIN" implementation does not support the creation or 2540 modification of "VCAR" components from the CUA. 2542 Formal Definition: The property is defined by the following notation: 2544 car-level = "CAR-LEVEL" ":" other-params : car-level-values 2546 car-level-values = ( "CAR-NONE" / "CAR-MIN" / "CAR-FULL-1" 2547 / other-levels ) 2549 other-levels = ; Any name published in an RFC for a "CAR-LEVEL" 2550 ; property value. 2552 Example: The following is an example of this property: 2554 CAR-LEVEL:CAR-FULL-1 2556 8.8 COMPONENTS Property 2558 Property Name: COMPONENTS 2560 Purpose: The property specifies a the list of components supported by 2561 the endpoint. 2563 Value Type: TEXT 2565 Property Parameters: Non-standard property parameters can be 2566 specified on this property. 2568 Conformance: The property can be specified in a "VREPLY" component in 2569 response to a "GET-CAPABILITY" command. 2571 Description: A comma separated list of components supported by the 2572 endpoint. If not in the list sent from the endpoint then they are not 2573 supported by that endpoint. Sending an unsupported component results 2574 in unpredictable results. This includes any components inside of 2575 other components (VALARM for example). The recommended list is 2576 "VCALSTORE,VCALENDAR,VREPLY,VAGENDA, 2577 VEVENT,VALARM,VTIMEZONE,VJOURNAL,VTODO,VALARM 2578 DAYLIGHT,STANDARD,VCAR,VRIGHT,VQUERY" 2580 Formal Definition: The property is defined by the following notation: 2582 components = "COMPONENTS" other-params ":" comp-list CRLF 2584 ; All of these MUST BE supplied only once. 2585 ; 2586 comp-list-req = "VCALSTORE" "," "VCALENDAR" "," "VTIMEZONE" "," 2587 "VREPLY" "," "VAGENDA" "," "STANDARD" "," 2588 "DAYLIGHT" 2590 ; At least one MUST BE supplied. The same value 2591 ; MUST NOT occur more than once. 2592 ; 2593 comp-list-min = ( "," "VEVENT") / ( "," "VTODO") / ( "," "VJOURNAL" ) 2595 ; The same value MUST NOT occur 2596 ; more than once. If "VCAR" is supplied then 2597 ' "VRIGHT" must be supplied. 2598 ; 2599 comp-list-opt = ( "," "VFREEBUSY" ) / ( "," "VALARM" ) 2600 / ( "," "VCAR" ) / ( "," "VRIGHT" ) 2601 / ( "," "VQUERY") / ( "," x-comp ) 2602 / ( "," iana-comp ) 2604 comp-list = comp-list-req 1*3comp-list-min *(comp-list-opt) 2606 Example: The following is an example of this property: 2608 COMPONENTS:VCALSTORE,VCALENDAR,VREPLY,VAGENDA, 2609 VEVENT,VALARM,VTIMEZONE,VJOURNAL,VTODO, 2610 DAYLIGHT,STANDARD,VFREEBUSY,VCAR,VRIGHT,VQUERY 2612 8.9 CSID Property 2614 Property Name: CSID 2616 Purpose: The property specifies a the globally unique identifier for 2617 the calendar store. 2619 Value Type: URI 2621 Property Parameters: Non-standard property parameters can be 2622 specified on this property. 2624 Conformance: The property can be specified in a "VCALSTORE" 2625 component. 2627 Description: The identifier MUST BE globally unique. Each CS needs 2628 its own unique identifier. The "CSID" property is the official unique 2629 identifier for the CS. If the [BEEP] 'serverName' attribute was 2630 supplied in the [BEEP] 'start' message, then the CSID will be mapped 2631 to the virtual host name supplied and the host name part of the CSID 2632 MUST BE the same as the 'serverName' value. This allows one CS 2633 implementation to service multiple virtual hosts. CS's are not 2634 required to support virtual hosting. If a CS does not support virtual 2635 hosting then it must ignore the [BEEP] 'serverName' attribute. 2637 Formal Definition: The property is defined by the following notation: 2639 csid = "CSID" other-params ":" capurl CRLF 2641 Example: The following is an example of this property: 2643 CSID:cap://calendar.example.com 2645 8.10 DECREED Property 2647 Property Name: DECREED 2649 Purpose: This property specifies if an access right calendar 2650 component is decreed or not. 2652 Value Type: BOOLEAN 2654 Property Parameters: Non-standard property parameters can be 2655 specified on this property. 2657 Conformance: This property MAY be specified once in a "VCAR" 2658 component. 2660 Description: This property is used in the "VCAR" component to specify 2661 whether the component is decreed or not. If the "DECREED" property 2662 value is "true" then the CUA will be unable to change the contents of 2663 the "VCAR" component and any attempt will fail with an error. 2665 Formal Definition: The property is defined by the following notation: 2667 decreed = "DECREED" other-params ":" boolean CRLF 2669 Example: The following is an example of this property: 2671 DECREED:TRUE 2673 8.11 DEFAULT-CHARSET Property 2675 Property Name: DEFAULT-CHARSET 2677 Purpose: This property indicates the default charset. 2679 Value Type: TEXT 2681 Property Parameters: Non-standard property parameters can be 2682 specified on this property. 2684 Conformance: This property can be specified in "VAGENDA" and 2685 "VCALSTORE" calendar component. 2687 Description: In a "VAGENDA" component this property is used to 2688 indicate the charset of calendar. If not specified, the default is 2689 the first value in the "VCALSTORE" components "DEFAULT-CHARSET" 2690 property value list. The value MUST BE an IANA registered character 2691 set as defined in [CHARREG]. 2693 In a "VCALSTORE" component it is a comma separated list of charsets 2694 supported by the CS. The first entry is the default entry for all 2695 newly created "VAGENDA" components. The "UTF-8" value MUST BE in the 2696 "VCALSTORE" component "DEFAULT-CHARSET" property list. All compliant 2697 CAP implementations (CS and CUA) MUST support at least the "UTF-8" 2698 charset. 2700 If a charset name contains a comma (,), then that comma must be 2701 backslashed escaped in the value. 2703 Formal Definition: The property is defined by the following notation: 2705 default-charset = "DEFAULT-CHARSET" other-params ":" text 2706 *( "," text) CRLF 2708 Example: The following is an example of this property for a "VAGENDA" 2709 component: 2711 DEFAULT-CHARSET:Shift_JIS,UTF-8 2713 8.12 DEFAULT-LOCALE Property 2715 Property Name: DEFAULT-LOCALE 2717 Purpose: This property specifies the default language for text 2718 values. 2720 Value Type: TEXT 2722 Property Parameters: Non-standard property parameters can be 2723 specified on this property. 2725 Conformance: This property can be specified in "VAGENDA" and 2726 "VCALSTORE" components. 2728 Description: In a "VAGENDA" component, the "DEFAULT-LOCALE" property 2729 is used to indicate the locale of the calendar. The full locale 2730 SHOULD be used. The default and minimum locale is POSIX (aka the 'C' 2731 locale). 2733 In a "VCALSTORE" component it is a comma separated list of locales 2734 supported by the CS. The first value in the list is the default for 2735 all newly created VAGENDAs. "POSIX" MUST BE in the list. 2737 Formal Definition: The property is defined by the following notation: 2739 default-locale = "DEFAULT-LOCALE" other-params ":" language 2740 *( "," language) CRLF 2742 language = Text identifying a locale, as defined in [CHARPOL] 2744 Example: The following is an example of this property: 2746 DEFAULT-LOCALE:en-US.iso-8859-1,POSIX 2748 8.13 DEFAULT-TZID Property 2750 Property Name: DEFAULT-TZID 2752 Purpose: This property specifies the text value that specifies the 2753 time zones. 2755 Value Type: TEXT 2757 Property Parameters: Non-standard property parameters can be 2758 specified on this property. 2760 Conformance: This property may be specified once in a "VAGENDA" and 2761 "VCALSTORE" components. 2763 Description: A multi valued property that lists the known time zones. 2764 The first is the default. Where "TZID" property values are the same 2765 as the "TZID" property as defined in [iCAL]. 2767 If in a "VCALSTORE" component it is a comma separated list of TZIDs 2768 known to the CS. The entry is used as the default TZID list for all 2769 newly created calendars. The list MUST contain at least "UTC". A 2770 "VCALSTORE" components MUST have one "VTIMEZONE" component contained 2771 in it for each value in the "DEFAULT-TZID" property value. 2773 If in a "VAGENDA" component it is a comma separated list of "TZID" 2774 property values naming the time zones known to the calendar. The 2775 first time zone in the list is the default and is used as the 2776 localtime for objects that contain a date or date-time value without 2777 a time zone. All "VAGENDA" components MUST have one "VTIMEZONE" 2778 component contained for each value in the "DEFAULT-TZID" property 2779 value. 2781 If a "TZID" property value contains a comma (,), the comma must be 2782 backslash escaped. 2784 Formal Definition: This property is defined by the following 2785 notation: 2787 default-tzid = "DEFAULT-TZID" other-params 2788 ":" [tzidprefix] text 2789 *("," [tzidprefix] text) CRLF 2791 Example: The following is an example of this property: 2793 DEFAULT-TZID:US/Mountain,UTC 2795 8.14 DEFAULT-VCARS Property 2797 Property Name: DEFAULT-VCARS 2799 Purpose: This property is used to specify the "CARID" property ids of 2800 the default "VCAR" components for newly created "VAGENDA" components. 2802 Value Type: TEXT 2804 Property Parameters: Non-standard property parameters can be 2805 specified on this property. 2807 Conformance: This property MUST BE specified in "VCALSTORE" calendar 2808 component and MUST at least specify the following values: 2809 "READBUSYTIMEINFO", "REQUESTONLY", "UPDATEPARTSTATUS", and 2810 "DEFAULTOWNER". 2812 Description: This property is used in the "VCALSTORE" component to 2813 specify the "CARID" value of the "VCAR" components that MUST BE 2814 copied into now "VAGENDA" components at creation time by the CS. All 2815 "DEFAULT-VCAR" values must have "VCARS" components stored in the 2816 "VCALSTORE". 2818 Formal Definition: The property is defined by the following notation: 2820 def-vcars = "DEFAULT-VCARS" other-params ":" text 2821 *( "," text ) CRLF 2823 Example: The following is an example of this property: 2825 DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY, 2826 UPDATEPARTSTATUS,DEFAULTOWNER 2828 8.15 DENY Property 2830 Property Name: DENY 2832 Purpose: This property identifies the UPN(s) being denied access in 2833 the "VRIGHT" component. 2835 Value Type: UPN-FILTER 2837 Property Parameters: Non-standard property parameters can be 2838 specified on this property. 2840 Conformance: This property can be specified in "VRIGHT" components. 2842 Description: This property is used in the "VRIGHT" component to 2843 define the CU or UG being denied access. 2845 Formal Definition: The property is defined by the following notation: 2847 deny = "DENY" other-params ":" upn-filter CRLF 2849 Example: The following are examples of this property: 2851 DENY:* 2853 DENY:bob@example.com 2855 8.16 EXPAND property 2857 Property Name: EXPAND 2859 Purpose: This property is to notify the CS if it should or should not 2860 expand any component with recurrence rules into multiple instances in 2861 a query reply. 2863 Value Type: BOOLEAN 2865 Property Parameters: Non-standard property parameters can be 2866 specified on this property. 2868 Conformance: This property can be specified in "VQUERY" components. 2870 Description: If a CUA wishes to see all of the instances of a 2871 recurring component the CUA sets EXPAND=TRUE in the "VQUERY" 2872 component. If not specified, the default is FALSE. Note that if the 2873 CS has its "RECUR-EXPAND" CS property value set to false then the 2874 "EXPAND" property will be ignored and the result will be as if the 2875 "EXPAND" value was set to false. The results will be bounded by any 2876 date range or other limits in the query. 2878 Formal Definition: The property is defined by the following notation: 2880 expand = "EXPAND" other-params ":" ("TRUE" / "FALSE") CRLF 2882 Example: The following are examples of this property: 2884 EXPAND:FALSE 2885 EXPAND:TRUE 2887 8.17 GRANT Property 2889 Property Name: GRANT 2891 Purpose: This property identifies the UPN(s) being granted access in 2892 the "VRIGHT" component. 2894 Value Type: UPN-FILTER 2896 Property Parameters: Non-standard property parameters can be 2897 specified on this property. 2899 Conformance: This property can be specified in "VRIGHT" calendar 2900 components. 2902 Description: This property is used in the "VRIGHT" component to 2903 specify the CU or UG being granted access. 2905 Formal Definition: The property is defined by the following notation: 2907 grant = "GRANT" other-params ":" upn-filter CRLF 2908 Example: The following are examples of this property: 2910 GRANT:* 2912 GRANT:bob@example.com 2914 8.18 ITIP-VERSION Property 2916 Property Name: ITIP-VERSION 2918 Purpose: This property specifies the version of ITIP supported. 2920 Value Type: TEXT 2922 Property Parameters: Non-standard property parameters can be 2923 specified on this property. 2925 Conformance: This property is specified in the "VREPLY" component 2926 that is sent in response to a "GET-CAPABILITY" command. 2928 Description: This specifies the version of ITIP that the endpoint 2929 supports. The list is a comma separated list of RFC numbers 2930 supported. The list MUST contain at least 2446 to mean [iTIP] 2932 Formal Definition: The property is defined by the following notation: 2934 itip-version = "ITIP-VERSION" other-params ":" text CRLF 2936 Example: The following are examples of this property: 2938 ITIP-VERSION:2446 2940 8.19 MAX-COMP-SIZE Property 2942 Property Name: MAX-COMP-SIZE 2944 Purpose: This property specifies the largest size of any object 2945 accepted. 2947 Value Type: TEXT 2948 Property Parameters: Non-standard property parameters can be 2949 specified on this property. 2951 Conformance: This property is specified in the "VREPLY" component 2952 that is sent in response to a "GET-CAPABILITY" command. 2954 Description: A positive integer value that specifies the size of the 2955 largest iCalendar object that can be accepted in octets. Objects 2956 larger than this will be rejected. A value of zero (0) means no 2957 limit. This is also the maximum value of any [BEEP] payload that will 2958 be accepted or sent. 2960 Formal Definition: The property is defined by the following notation: 2962 max-comp-size = "MAX-COMP-SIZE" other-params ":" posint0 CRLF 2964 Example: The following are examples of this property: 2966 MAX-COMP-SIZE:1024 2968 8.20 MAXDATE Property 2970 Property Name: MAXDATE 2972 Purpose: This property specifies the date/time in the future beyond 2973 which the CS or CUA cannot represent. 2975 Value Type: DATE-TIME 2977 Property Parameters: Non-standard property parameters can be 2978 specified on this property. 2980 Conformance: The property can be specified in the "VCALSTORE" 2981 component. 2983 Description: The date and time MUST BE a UTC value and end with 'Z'. 2985 Formal Definition: The property is defined by the following notation: 2987 maxdate = "MAXDATE" other-params ":" date-time CRLF 2988 Example: The following is an example of this property: 2990 MAXDATE:20990101T000000Z 2992 8.21 MINDATE Property 2994 Property Name: MINDATE 2996 Purpose: This property specifies the date/time in the past prior to 2997 which the server cannot represent. 2999 Value Type: DATE-TIME 3001 Property Parameters: Non-standard property parameters can be 3002 specified on this property. 3004 Conformance: The property can be specified in the "VCALSTORE" 3005 component. 3007 Description: The date and time MUST BE a UTC value and end with 'Z'. 3009 Formal Definition: The property is defined by the following notation: 3011 mindate = "MINDATE" other-params ":" date-time CRLF 3013 Example: The following is an example of this property: 3015 MINDATE:19710101T000000Z 3017 8.22 MULTIPART Property 3019 Property Name: MULTIPART 3021 Purpose: This property provides a comma separated list of supported 3022 MIME multipart types supported by the sender. 3024 Value Type: TEXT 3026 Property Parameters: Non-standard property parameters can be 3027 specified on this property. 3029 Conformance: This property is specified in the "VREPLY" component 3030 that is sent in response to a "GET-CAPABILITY" command. 3032 Description: This property is used in the in the "GET-CAPABILITY" 3033 command reply to indicated the MIME multipart types supported. A CS 3034 and CUA SHOULD support all registered MIME multipart types. 3036 Formal Definition: The property is defined by the following notation: 3038 mname = "MULTIPART" other-params ":" text *( "," text) CRLF 3040 Example: The following is an example of this property: 3042 MULTIPART:related,alternate,mixed 3044 8.23 NAME Property 3046 Property Name: NAME 3048 Purpose: This property provides a localizable display name for a 3049 component. 3051 Value Type: TEXT 3053 Property Parameters: Non-standard property parameters can be 3054 specified on this property. 3056 Conformance: This property can be specified in a component. 3058 Description: This property is used in the in component to specify a 3059 localizable display name. If more than one "NAME" properties are in a 3060 component, then they MUST have unique "LANG" parameters. If the 3061 "LANG" parameter is not supplied, then it defaults to the "VAGENDA" 3062 components "DEFAULT-LOCALE" first value as the default. If the 3063 component is a "VAGENDA" then the default value is the "VAGENDA"s 3064 components "DEFAULT-LOCALE" first value as the default. A "VCALSTORE" 3065 components "DEFAULT-LOCALE" first value is the default if the 3066 component is stored at the "VCALSTORE" level. 3068 Formal Definition: The property is defined by the following notation: 3070 name = "NAME" nameparam ":" text CRLF 3071 nameparam = other-params [ ";" languageparam ] other-params 3073 languageparam = ; As defined in [iCAL]. 3075 Example: The following is an example of this property: 3077 NAME:Restrict Guests From Creating VALARMs On VEVENTs 3079 8.24 OWNER Property 3081 Property Name: OWNER 3083 Purpose: The property specifies an owner of the component. 3085 Value Type: UPN 3087 Property Parameters: Non-standard, alternate text representation and 3088 language property parameters can be specified on this property. 3090 Conformance: The property MUST BE specified at in a "VAGENDA" 3091 component. 3093 Description: A multi-instanced property indicating the calendar 3094 owner. 3096 Formal Definition: The property is defined by the following notation: 3098 owner = "OWNER" other-params ":" upn CRLF 3100 Example: The following is an example of this property: 3102 OWNER:jsmith@example.com 3103 OWNER:jdough@example.com 3105 8.25 PERMISSION Property 3107 Property Name: PERMISSION 3109 Purpose: This property defines a permission that is granted or denied 3110 in a "VRIGHT" component. 3112 Value Type: TEXT 3114 Property Parameters: Non-standard property parameters can be 3115 specified on this property. 3117 Conformance: This property can be specified in "VRIGHT" components. 3119 Description: This property is used in the "VRIGHT" component to 3120 define a permission that is granted or denied. 3122 Formal Definition: The property is defined by the following notation: 3124 perm = "PERMISSION" other-params ":" permvalue CRLF 3126 permvalue = ( "SEARCH" / "CREATE" / "DELETE" 3127 / "MODIFY" / "MOVE" / all 3128 / iana-cmd / x-cmd ) 3130 all = "*" 3132 iana-cmd = ; Any command registered by IANA directly or 3133 ; included in an RFC that may be applied as 3134 ; a command. 3136 x-cmd = ; Any experimental command that starts with 3137 ; "x-" or "X-". 3139 Example: The following is an example of this property: 3141 PERMISSION:SEARCH 3143 8.26 QUERY property 3145 Property Name: QUERY 3147 Purpose: Specifies the query for the component. 3149 Value Type: CAL-QUERY 3151 Property Parameters: Non-standard property parameters can be 3152 specified on this property. 3154 Conformance: This property can be specified in "VQUERY" components. 3156 Description: A "QUERY" is used to specify the "CAL-QUERY" (Section 3157 6.1.1 for the query. 3159 Formal Definition: The property is defined by the following notation: 3161 query = "QUERY" other-params ":" cal-query CRLF 3163 Example: The following is an example of this property: 3165 QUERY:SELECT * FROM VEVENT 3167 8.27 QUERYID property 3169 Property Name: QUERYID 3171 Purpose: Specifies a unique ID for a query in the targeted container. 3173 Value Type: TEXT 3175 Property Parameters: Non-standard property parameters are specified 3176 on this property. 3178 Conformance: This property can be specified in "VQUERY" components. 3180 Description: A "QUERYID" property is used to specify the unique id 3181 for a query. A "QUERYID" property value is unique per container. 3183 Formal Definition: The property is defined by the following notation: 3185 queryid = "QUERYID" other-params ":" text CRLF 3187 Example: The following are examples of this property: 3189 QUERYID:Any Text String 3190 QUERYID:fetchUnProcessed 3192 8.28 REQUEST-STATUS property 3194 This description is a revision of the "REQUEST-STATUS" property for 3195 [iCAL] objects with a "VCALENDAR" component "VERSION" property that 3196 includes a value of "2.0" or newer. The 'statdesc' is optional and 3197 the 'extdata' may be included when 'statdesc' is not provided. 3199 rstatus = "REQUEST-STATUS" rstatparam ":" 3200 statcode ";" [ statdesc ] ";" [ extdata ] 3202 rstatparam = other-params [";" languageparam] other-params 3204 statcode = 1*DIGIT *("." 1*DIGIT) 3205 ;Hierarchical, numeric return status code 3207 statdesc = text 3208 ;An optional textual status description, content is 3209 ;decided by the implementer. May be empty. 3211 extdata = text 3212 ; Textual exception data. For example, the offending 3213 ; property name and value or complete property line. 3215 Example: The following are some possible examples of this property. 3216 The COMMA and SEMICOLON separator characters in the property value 3217 are BACKSLASH character escaped because they appear in a text value. 3219 REQUEST-STATUS:2.0;Success 3221 REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01 3223 REQUEST-STATUS:2.8; Success\, repeating VEVENT ignored. Scheduled 3224 as a single VEVENT.;RRULE:FREQ=WEEKLY;INTERVAL=2 3226 REQUEST-STATUS:4.1;Time conflict. Date/time is busy. 3228 REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE: 3229 MAILTO:jsmith@example.com 3231 REQUEST-STATUS:3.7;;ATTENDEE:MAILTO:jsmith@example.com 3233 REQUEST-STATUS:10.4;Help! That really shouldn't have happened. 3235 8.29 QUERY-LEVEL Property 3237 Property Name: QUERY-LEVEL 3239 Purpose: This property specifies the level of query supported. 3241 Value Type: TEXT 3243 Property Parameters: Non-standard property parameters can be 3244 specified on this property. 3246 Conformance: The property can be specified in the "VREPLY" component 3247 in response to a "GET-CAPABILITY" command. 3249 Description: Indicates level of query support. CAL-QL-NONE is for 3250 CS's that allow ITIP methods only to be deposited and nothing else. 3252 Formal Definition: The property is defined by the following notation: 3254 query-level = "QUERY-LEVEL" other-params 3255 ":" ( "CAL-QL-1" / "CAL-QL-NONE") CRLF 3257 Example: The following is an example of this property: 3259 QUERY-LEVEL:CAL-QL-1 3261 8.30 RECUR-ACCEPTED Property 3263 Property Name: RECUR-ACCEPTED 3265 Purpose: This property specifies if the endpoint supports recurring 3266 instances. 3268 Value Type: BOOLEAN 3270 Property Parameters: Non-standard property parameters can be 3271 specified on this property. 3273 Conformance: The property can be specified in the "VREPLY" component 3274 in response to a "GET-CAPABILITY" command. 3276 Description: Indicates if recurrence rules are supported. If FALSE 3277 then the endpoint can not process any kind of recurring rules. 3279 Formal Definition: The property is defined by the following notation: 3281 recur-accepted = "RECUR-ACCEPTED" other-params ":" boolean CRLF 3283 Example: The following is an example of this property: 3285 RECUR-ACCEPTED:TRUE 3286 RECUR-ACCEPTED:FALSE 3288 8.31 RECUR-LIMIT Property 3290 Property Name: RECUR-LIMIT 3292 Purpose: This property specifies the maximum number of instances the 3293 endpoint will expand instances into at query or storage time. 3295 Value Type: INTEGER 3297 Property Parameters: Non-standard property parameters can be 3298 specified on this property. 3300 Conformance: The property can be specified in the "VREPLY" component 3301 in response to a "GET-CAPABILITY" command. 3303 Description: For implementations that have the "STORES-EXPANDED" 3304 value set to TRUE, then this value specifies the maximum number of 3305 instances that will be stored and fetched. For all implementations 3306 this is the maximum number of instances that will be returned when 3307 the "EXPAND" parameter is specified as TRUE and the results contain a 3308 infinite or large number of recurring instances. 3310 Formal Definition: The property is defined by the following notation: 3312 recur-limit = "RECUR-LIMIT" other-params ":" posint1 CRLF 3314 Example: The following is an example of this property: 3316 RECUR-LIMIT:1000 3318 8.32 RECUR-EXPAND Property 3320 Property Name: RECUR-EXPAND 3322 Purpose: This property specifies if the endpoint can expand 3323 recurrences into multiple objects. 3325 Value Type: BOOLEAN 3327 Property Parameters: Non-standard property parameters can be 3328 specified on this property. 3330 Conformance: The property can be specified in the "VREPLY" component 3331 in response to a "GET-CAPABILITY" command. 3333 Description: If TRUE then the endpoint can expand an object into 3334 multiple instances as defined by its recurrence rules when the 3335 "EXPAND" property is supplied. If FALSE then the endpoint ignores the 3336 "EXPAND" property. 3338 Formal Definition: The property is defined by the following notation: 3340 recur-expand = "RECUR-EXPAND" other-params ":" boolean CRLF 3342 Example: The following is an example of this property: 3344 RECUR-EXPAND:TRUE 3345 RECUR-EXPAND:FALSE 3347 8.33 RESTRICTION Property 3349 Property Name: RESTRICTION 3351 Purpose: This property defines restrictions on the result value of 3352 new or existing components. 3354 Value Type: CAL-QUERY 3356 Property Parameters: Non-standard property parameters can be 3357 specified on this property. 3359 Conformance: This property can be specified in "VRIGHT" components, 3360 but only when the "PERMISSION" property is set to "CREATE", "MODIFY", 3361 or "*" property value. 3363 Description: This property is used in the "VRIGHT" component to 3364 define restrictions on the components that can be written (i.e., by 3365 using the "CREATE" or "MOVE" commands) as well as on the values that 3366 may take existent calendar store properties, calendar properties, 3367 components, and properties (i.e., by using the "MODIFY" command). 3368 Accepted values MUST match any specified "RESTRICTION" property 3369 values. 3371 Formal Definition: The property is defined by the following notation: 3373 restrict = "RESTRICTION" other-params ":" cal-query CRLF 3375 Example: The following are examples of this property: 3377 RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST' 3379 RESTRICTION:SELECT * FROM VEVENT WHERE 3380 SELF() IN ORGANIZER 3382 RESTRICTION:SELECT * FROM VEVENT WHERE 'BUSINESS' IN 3383 CATEGORIES 3385 8.34 SCOPE Property 3387 Property Name: SCOPE 3389 Purpose: This property identifies the objects in the CS to which the 3390 access rights applies. 3392 Value Type: CAL-QUERY 3394 Property Parameters: Non-standard property parameters can be 3395 specified on this property. 3397 Conformance: This property can be specified in "VRIGHT" components. 3399 Description: This property is used in the "VRIGHT" component to 3400 define the set of objects subject to the access right being defined. 3402 Formal Definition: The property is defined by the following notation: 3404 scope = "SCOPE" other-params ":" cal-query CRLF 3406 Example: The following is an example of this property: 3408 SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC' 3410 8.35 STORES-EXPANDED Property 3412 Property Name: STORES-EXPANDED 3414 Purpose: This property specifies if the sending endpoint expands 3415 recurrence rules prior to storing them into the CS. 3417 Value Type: BOOLEAN 3419 Property Parameters: Non-standard property parameters can be 3420 specified on this property. 3422 Conformance: This property can be specified in a "VREPLY" component 3423 in response to a "GET-CAPABILITY" command. 3425 Description: If the value is TRUE then the endpoint expands 3426 recurrence rules and then stores the results into the CS. If this is 3427 TRUE then the "RECUR-LIMIT" property is significant because an 3428 infinitely recurring appointment will be stored no more than 3429 "RECUR-LIMIT" property values into the CS and all other instances 3430 will be lost. 3432 Formal Definition: The property is specified by the following 3433 notation: 3435 stores-expanded = "STORES-EXPANDED" other-params ":" boolean CRLF 3437 The following is an example of this property: 3439 STORES-EXPANDED:TRUE 3440 STORES-EXPANDED:FALSE 3442 8.36 TARGET Property 3444 Property Name: TARGET 3446 Purpose: This property defines the container that the command that is 3447 issued will act upon. Its value is a capurl as defined in Section 5. 3449 Value Type: URI 3451 Property Parameters: Non-standard property parameters can be 3452 specified on this property. 3454 Conformance: This property can be specified in a command component. 3456 Description: This property value is used to specify the container 3457 that the command will effect. When used in a command, the command 3458 will be performed on the container which has a capurl matching the 3459 value. 3461 Formal Definition: The property is specified by the following 3462 notation: 3464 target = "TARGET" other-params ":" ( capurl / relcalid ) CRLF 3466 The following is an example of this property: 3468 TARGET:cap://mycal.example.com 3469 TARGET:SomeRelCalid 3471 8.37 TRANSP Property 3473 Property Name: TRANSP 3475 Purpose: This property defines whether an component is transparent or 3476 not to busy time searches. This is a modification to [iCAL] "TRANSP" 3477 property in that it adds some values. 3479 Value Type: TEXT 3481 Property Parameters: Non-standard property parameters can be 3482 specified on this property. 3484 Conformance: This property can be specified in a component. 3486 Description: Time Transparency is the characteristic of an object 3487 that determines whether it appears to consume time on a calendar. 3488 Objects that consume actual time for the individual or resource 3489 associated with the calendar SHOULD be recorded as "OPAQUE", allowing 3490 them to be detected by free-busy time searches. Other objects, which 3491 do not take up the individual's (or resource's) time SHOULD be 3492 recorded as "TRANSPARENT", making them invisible to free-busy time 3493 searches. 3495 Formal Definition: The property is specified by the following 3496 notation: 3498 transp = "TRANSP" other-params ":" transvalue CRLF 3500 transvalue 3501 = "OPAQUE" ;Blocks or opaque on busy time searches. 3502 / "TRANSPARENT" ;Transparent on busy time searches. 3504 / "TRANSPARENT-NOCONFLICT" ; Transparent on busy time 3505 ; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects 3506 ; can overlap it. 3508 / "OPAQUE-NOCONFLICT" ; Opaque on busy time 3509 ; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects 3510 ; can overlap it. 3511 ; 3512 ;Default value is OPAQUE 3514 The following is an example of this property for an object that is 3515 opaque or blocks on free/busy time searches plus no other object can 3516 overlap it: 3518 TRANSP:OPAQUE-NOCONFLICT 3520 9. New Components 3522 9.1 VAGENDA Component 3524 Component Name: VAGENDA 3526 Purpose: Provide a grouping of properties that defines an agenda. 3528 Formal Definition: There are two formats of the "VAGENDA" component. 3529 (1) When it is being created, and (2) how it exists in the 3530 "VCALSTORE" component. 3532 A "VAGENDA" component in a "VCALSTORE" component is defined by the 3533 following notes and ABNF notation: 3535 CALSCALE - The value MUST BE from the "VCALSTORE" "CALSCALE" 3536 property list. The default is the first entry in the VCALSTORE 3537 CALSCALE list. 3539 CREATED - The timestamp of the calendar's create date. This is a 3540 READ ONLY property in a "VAGENDA". 3542 LAST-MODIFIED - The timestamp of any change to the "VAGENDA" 3543 properties or when any component was last created, modified, or 3544 deleted. 3546 agenda = "BEGIN" ":" "VAGENDA" CRLF 3547 agendaprop 3548 *(icalobject) ; as defined in [iCAL] 3549 "END" ":" "VAGENDA" CRLF 3551 agendaprop = *( 3552 ; The following MUST occur exactly once. 3553 ; 3554 allow-conflict / relcalid / calscale / created 3555 / default-charset / default-locale 3556 / default-tzid / last-mod / 3558 ; The following MUST occur at least once. 3559 ; and the value MUST NOT be empty. 3561 / owner 3563 ; The following are optional, 3564 ; and MAY occur more than once. 3566 / name / related-to / other-props / x-comp 3567 ) 3569 When creating a VAGENDA, use the following notation: 3571 agendac = "BEGIN" ":" "VAGENDA" CRLF 3572 agendacprop 3573 *(icalobject) ; as defined in [iCAL] 3574 "END" ":" "VAGENDA" CRLF 3576 agendacprop = *( 3577 ; The following MUST occur exactly once. 3578 ; 3579 allow-conflict / relcalid / calscale 3580 / default-charset / default-locale 3581 / default-tzid / 3583 ; The following MUST occur at least once. 3584 ; and the value MUST NOT be empty. 3585 ; 3586 / owner 3588 ; The following are optional, 3589 ; and MAY occur more than once. 3590 ; 3591 / name / related-to / other-props / x-comp 3592 ) 3594 To fetch all of the properties from the targeted "VAGENDA" component. 3595 This does not fetch any components: 3597 SELECT * FROM VAGENDA 3599 To fetch all of the properties from the targeted VAGENDA and all of 3600 the contained components, use the special '*.*' value: 3602 SELECT *.* FROM VAGENDA 3604 9.2 VCALSTORE Component 3606 Component Name: VCALSTORE 3608 Purpose: Provide a grouping of properties that defines a calendar 3609 store. 3611 Formal Definition: A "VCALSTORE" component is defined by the 3612 following table and ABNF notation. The creation of a "VCALSTORE" 3613 component is an administrative task and not part of the CAP protocol. 3615 The following are notes to some of the properties in the "VCALSTORE" 3616 component. 3618 CALSCALE - A comma separated list of CALSCALEs supported by this CS. 3619 All "VAGENDA" component calendar CALSCALE properties MUST BE from 3620 this list. This list MUST contain at least "GREGORIAN". The 3621 default for newly created "VAGENDA" components is the first entry. 3623 RELATED-TO - This is a multiple instance property. There must be a 3624 "RELATED-TO" property MUST for each of the "VAGENDA" components 3625 contained in the "VCALSTORE" component each with the "RELTYPE" 3626 parameter value set to "CHILD". Other "RELATED-TO" properties may 3627 be included. 3629 CREATED - The timestamp of the CS creation time. This is a READ ONLY 3630 property. 3632 CSID - The CSID of this calendar store. MUST NOT be empty. How this 3633 property is set in the VCALSTORE is an administrative or 3634 implementation specific issue and is not covered in CAP. This is a 3635 READ ONLY property. A suggested value is the fully qualified host 3636 name or a fully qualified virtual host name supported by the 3637 system. 3639 LAST-MODIFIED - The timestamp when the Properties of the "VCALSTORE" 3640 component were last updated or calendars were created or deleted. 3641 This is a READ ONLY PROPERTY. 3643 calstorec = "BEGIN" ":" "VCALSTORE" CRLF 3644 calstoreprop 3645 *(vagendac) 3646 "END" ":" "VCALSTORE" CRLF 3648 calstoreprop = *( 3649 ; the following MUST occur exactly once 3650 allow-conflict / calscale / calmaster 3651 / created / csid / default-charset 3652 / default-locale / default-vcars 3653 / default-tzid / last-mod / maxdate / mindate 3655 ; the following are optional, 3656 ; and MAY occur more than once 3658 / name / related-to / other-props / x-comp 3659 ) 3661 last-mod = ; As defined in [iCAL]. 3663 To fetch all of the properties from the targeted VCALSTORE and not 3664 fetch the calendars that it contains: 3666 SELECT * FROM VCALSTORE 3668 To fetch all of the properties from the targeted "VCALSTORE" 3669 component and all of the contained calendars and all of those 3670 calendars contained properties and components, use the special '*.*' 3671 value: 3673 SELECT *.* FROM VCALSTORE 3675 9.3 VCAR Component 3677 Component Name: VCAR 3679 Purpose: Provide a grouping of calendar access rights. 3681 Formal Definition: A "VCAR" component is defined by the following 3682 notation: 3684 carc = "BEGIN" ":" "VCAR" CRLF 3685 carprop 1*rightc 3686 "END" ":" "VCAR" CRLF 3688 carprop = 1*( 3689 ; 'carid' is REQUIRED, 3690 ; but MUST NOT occur more than once 3692 carid / 3694 ; the following are OPTIONAL, 3695 ; and MAY occur more than once 3697 name / decreed / other-props 3698 ) 3700 Description: A "VCAR" component is a grouping of properties, and 3701 "VRIGHT" components, that represents access rights granted or denied 3702 to UPNs. 3704 The "CARID" property specifies the local identifier for the "VCAR" 3705 component. The "NAME" property specifies a localizable display name. 3707 Example: In the following example, the UPN "foo@example.com" is given 3708 search access to the "DTSTART" and "DTEND" VEVENT properties. No 3709 other access is specified: 3711 BEGIN:VCAR 3712 CARID:View Start and End Times 3713 NAME:View Start and End Times 3714 BEGIN:VRIGHT 3715 GRANT:foo@example.com 3716 PERMISSION:SEARCH 3717 SCOPE:SELECT DTSTART,DTEND FROM VEVENT 3718 END:VRIGHT 3719 END:VCAR 3721 In this example, all UPNs are given search access to "DTSTART" and 3722 "DTEND" properties of VEVENT components. "All CUs and UGs" are 3723 specified by the UPN value "*". Note that this enumerated UPN value 3724 is not in quotes: 3726 BEGIN:VCAR 3727 CARID:ViewStartEnd2 3728 NAME:View Start and End Times 2 3729 BEGIN:VRIGHT 3730 GRANT:* 3731 PERMISSION:SEARCH 3732 SCOPE:SELECT DTSTART,DTEND FROM VEVENT 3733 END:VRIGHT 3734 END:VCAR 3736 In these examples, full calendar access rights are given to the 3737 CAL-OWNERS(), and a hypothetical administrator is given access rights 3738 to specify calendar access rights. If no other rights are specified, 3739 only these two UPNs can specify calendar access rights: 3741 BEGIN:VCAR 3742 CARID:some-id-3 3743 NAME:Only OWNER or ADMIN Settable VCARs 3744 BEGIN:VRIGHT 3745 GRANT:CAL-OWNERS() 3746 PERMISSION:* 3747 SCOPE:SELECT * FROM VAGENDA 3748 END:VRIGHT 3749 BEGIN:VRIGHT 3750 GRANT:cal-admin@example.com 3751 PERMISSION:* 3752 SCOPE:SELECT * FROM VCAR 3753 RESTRICTION:SELECT * FROM VCAR 3754 END:VRIGHT 3755 END:VCAR 3757 In this example, rights to write, search, modify or delete calendar 3758 access rights are denied to all UPNs. This example would disable 3759 providing different access rights to the calendar store or calendar. 3760 This calendar access right should be specified with great care, as it 3761 removes the ability to change calendar access; even for the owner or 3762 administrator. It could be used by small devices that do not support 3763 the changing of any VCAR: 3765 BEGIN:VCAR 3766 CARID:VeryRestrictiveVCAR-2 3767 NAME:No CAR At All 3768 BEGIN:VRIGHT 3769 DENY:* 3770 PERMISSION:* 3771 SCOPE:SELECT * FROM VCAR 3772 END:VRIGHT 3773 END:VCAR 3775 9.4 VRIGHT Component 3777 Component Name: "VRIGHT" 3779 Purpose: Provide a grouping of properties that describe an access 3780 right (granted or denied). 3782 Formal Definition: A "VRIGHT" component is defined by the following 3783 notation: 3785 rightc = "BEGIN" ":" "VRIGHT" CRLF 3786 rightprop 3787 "END" ":" "VRIGHT" CRLF 3789 rightprop = 2*( 3791 ; either 'grant' or 'deny' MUST 3792 ; occur at least once 3793 ; and MAY occur more than once 3795 grant / deny / 3797 ; 'permission' MUST occur at least once 3798 ; and MAY occur more than once 3800 permission / 3802 ; the following are optional, 3803 ; and MAY occur more than once 3805 scope / restriction / other-props 3807 ) 3809 Description: A "VRIGHT" component is a grouping of calendar access 3810 right properties. 3812 The "GRANT" property specifies the UPN that is being granted access. 3813 The "DENY" property specifies the UPN is being denied access. The 3814 "PERMISSION" property specifies the actual permission being set. The 3815 "SCOPE" property identifies the calendar store properties, calendar 3816 properties, components, or properties to which the access right 3817 applies. The "RESTRICTION" property specifies restriction on the 3818 value that may take calendar store properties, calendar properties, 3819 calendar components, and properties after a "CREATE" or "MODIFY" 3820 command. Values MUST match all the instances of the "RESTRICTION" 3821 property to be valid. 3823 9.5 VREPLY Component 3825 Component Name: "VREPLY" 3827 Purpose: Provide a grouping of arbitrary properties and components 3828 that are the data set result from an issued command. 3830 Formal Definition: A "VREPLY" component is defined by the following 3831 notation: 3833 replyc = "BEGIN" ":" "VREPLY" CRLF 3834 any-prop-or-comp 3835 "END" ":" "VREPLY" CRLF 3837 any-prop-or-comp = ; Zero or more iana or experimental 3838 ; properties and components, in any order. 3840 Description: Provide a grouping of arbitrary properties and 3841 components that are the data set result from an issued command. 3843 A query can return a predictable set of arbitrary properties and 3844 components. This component is used by query and other commands to 3845 return data that does not fit into any other component. It may 3846 contain any valid property or component, even if they are not 3847 registered. 3849 9.6 VQUERY Component 3851 Component Name: VQUERY 3853 Purpose: A component describes a set of objects to be acted upon. 3855 Formal Definition: A "VQUERY" component is defined by the following 3856 notation: 3858 queryc = "BEGIN" ":" "VQUERY" CRLF 3859 queryprop 3860 "END" ":" "VCAR" CRLF 3862 queryprop = 1*( 3864 ; 'queryid' is OPTIONAL but MUST NOT occur 3865 ; more than once. If the "TARGET" property 3866 ; is supplied then the "QUERYID" property 3867 ; MUST BE supplied. 3868 ; 3869 queryid / target 3871 ; 'expand' is OPTIONAL but MUST NOT occur 3872 ; more than once. 3874 expand 3876 ; the following are OPTIONAL, and MAY occur 3877 ; more than once 3878 ; 3879 / name / other-props 3881 ; the following MUST occur at least once if 3882 ; queryid is not supplied. 3883 ; 3884 / query 3886 ) 3888 Description: A "VQUERY" contains properties that describe which 3889 properties and components the CS is requested to act upon. 3891 The "QUERYID" property specifies the local identifier for a "VQUERY" 3892 component. 3894 For a search, if the "TARGET" property is supplied in a "VQUERY" 3895 component, then the CS is to search for the query in the CALID 3896 supplied by the "TARGET" property value. 3898 For a create the "TARGET" property MUST NOT be supplied as the 3899 destination container is already supplied in the "TARGET" property of 3900 the "VCALENDAR" component. 3902 For examples, see Section 6.1.1. 3904 10. Commands and Responses 3906 CAP commands and responses are described in this section. 3908 10.1 CAP Commands (CMD) 3910 All commands are send using the CMD property. 3912 Property Name: CMD 3914 Purpose: The property defines the command to be sent. 3916 Value Type: TEXT 3918 Property Parameters: Non-standard, id, localize, latency, action or 3919 options. 3921 Conformance: This property is the method used to specify the commands 3922 to a CS and can exist in any object sent to the CS. 3924 Description: All of the commands to the CS are supplied in this 3925 property. The "OPTIONS" parameter is overloaded and its meaning is 3926 dependent on the CMD value supplied. 3928 Formal Definition: The property is defined by the following notation: 3930 cmd = "CMD" ( 3931 / abort-cmd 3932 / continue-cmd 3933 / create-cmd 3934 / delete-cmd 3935 / generate-uid-cmd 3936 / get-capability-cmd 3937 / identify-cmd 3938 / modify-cmd 3939 / move-cmd 3940 / reply-cmd 3941 / search-cmd 3942 / set-locale-cmd 3943 / iana-cmd 3944 / x-cmd 3945 ) CRLF 3947 option-value = paramtext ; As defined in [iCAL] 3949 Calendaring commands allow a CUA to directly manipulate a calendar. 3951 Calendar access rights can be granted or denied for any commands. 3953 10.1.1 Bounded Latency 3955 A CAP command can have an associated maximum latency time by 3956 specifying the "LATENCY" parameter. If the command is unable to be 3957 completed in the specified amount of time (as specified by the 3958 "LATENCY" parameter value with an "ACTION" parameter set to the "ASK" 3959 value), then a "TIMEOUT" command MUST BE sent on the same channel" to 3960 which there MUST BE a an "ABORT" or a "CONTINUE" command reply. If 3961 the CUA initiated the original command, then the CS would issue the 3962 "TIMEOUT" command and the CUA would then have to issue an "ABORT" or 3963 "CONTINUE" command. If the CS initiated the original command then the 3964 CUA would have to issue the "TIMEOUT" and the CS would send the 3965 "ABORT" or "CONTINUE". 3967 Upon receiving an "ABORT" command, the command must then be 3968 terminated. Only the "ABORT", "TIMEOUT", "REPLY, and "CONTINUE" 3969 commands can not be aborted. The "ABORT", "TIMEOUT", and "REPLY" 3970 commands MUST NOT have latency set. 3972 Upon receiving a "CONTINUE" command the work continues as if it had 3973 not been delayed or stopped. Note that a new latency time MAY BE 3974 included in a "CONTINUE" command indicating to continue the original 3975 command until the "LATENCY" parameter value expires or the results of 3976 the original command can be returned. 3978 Both the "LATENCY" parameter and the "ACTION" parameter MUST BE 3979 supplied to any "CMD" property, or nether can be added to the "CMD" 3980 property. The "LATENCY" parameter MUST BE set to the maximum latency 3981 time in seconds. The "ACTION" parameter accepts the following 3982 values: "ASK" and "ABORT" parameters. 3984 If the maximum latency time is exceeded and the "ACTION" parameter is 3985 set to the "ASK" value, then "TIMEOUT" command MUST BE sent. 3986 Otherwise if the "ACTION" parameter is set to the "ABORT" value then 3987 the command MUST BE terminated and return a REQUEST-STATUS code of 3988 2.0.3 for the original command. 3990 If a CS can both start sending the reply to a command and guarantee 3991 that all of the results can be sent from a command (short of 3992 something like network or power failure) prior to the "LATENCY" 3993 timeout value then the "LATENCY" time has not expired. 3995 Example: 3997 In this example the initiator asks for the listeners capabilities. 3999 I: Content-Type: text/calendar 4000 I: 4001 I: BEGIN:VCALENDAR 4002 I: VERSION:2.0 4003 I: PRODID:The CUA's PRODID 4004 I: CMD;ID=xyz12346;LATENCY=3;ACTION=ask:GET-CAPABILITY 4005 I: END:VCALENDAR 4007 # After 3 seconds 4009 L: Content-Type: text/calendar 4010 L: 4011 L: BEGIN:VCALENDAR 4012 L: PRODID:-//someone's prodid 4013 L: VERSION:2.0 4014 L: CMD;ID=xyz12346:TIMEOUT 4015 L: END:VCALENDAR 4017 In order to continue and give the CS more time then the CUA would 4018 issue a "CONTINUE" command: 4020 I: Content-Type: text/calendar 4021 I: 4022 I: BEGIN:VCALENDAR 4023 I: VERSION:2.0 4024 I: PRODID:-//someone's prodid 4025 I: CMD;ID=xyz12346;LATENCY=3;ACTION=ask:CONTINUE 4026 I: END:VCALENDAR 4028 L: Content-Type: text/calendar 4029 L: 4030 L: BEGIN:VCALENDAR 4031 L: VERSION:2.0 4032 L: PRODID:-//someone's prodid 4033 L: CMD;ID=xyz12346:REPLY 4034 L: BEGIN:VREPLY 4035 L: REQUEST-STATUS:2.0.3;Continued for 3 more seconds 4036 L: END:VREPLY 4037 L: END:VCALENDAR 4039 Above the "2.0.3" status is returend because it is not an error, it 4040 is a progress status sent in reply to the "CONTINUE" command. 4042 To abort the command and not wait any further then issue an "ABORT" 4043 command: 4045 I: Content-Type: text/calendar 4046 I: 4047 I: BEGIN:VCALENDAR 4048 I: VERSION:2.0 4049 I: PRODID:-//someone's prodid 4050 I: CMD;ID=xyz12346:ABORT 4051 I: END:VCALENDAR 4053 # Which would result in a 2.0.3 reply. 4055 L: Content-Type: text/calendar 4056 L: 4057 L: BEGIN:VCALENDAR 4058 L: VERSION:2.0 4059 L: PRODID:-//someone's prodid 4060 L: CMD;ID=xyz12346:REPLY 4061 L: BEGIN:VREPLY 4062 L: REQUEST-STATUS:2.0.3;Aborted As Requested. 4063 L: END:VREPLY 4064 L: END:VCALENDAR 4066 If the "ACTION" value had been set to "ABORT", then the listiner 4067 would send a "7.0" error on timeout in the reply to the command that 4068 initiated the command that timed out. 4070 10.2 ABORT Command 4072 CMD: ABORT 4074 Purpose: The "ABORT" command is sent to request that the named or 4075 only in process command be aborted. Latency MUST not be supplied with 4076 the "ABORT" command. 4078 Formal Definition: An "ABORT" command is defined by the following 4079 notation: 4081 abort-cmd = abortparam ":" "ABORT" 4083 abortparam = *( 4085 ; the following are optional, 4086 ; but MUST NOT occur more than once 4088 id-param 4089 / localize-param 4090 ; the following is optional, 4091 ; and MAY occur more than once 4093 / other-params 4095 ) 4097 The REPLY of any "ABORT" command is: 4099 abort-reply = "BEGIN" ":" "VCALENDAR" CRLF 4100 calprops 4101 abort-vreply 4102 "END" ":" "VCALENDAR" CRLF 4104 abort-vreply = "BEGIN" ":" "VREPLY" CRLF 4105 request-status 4106 other-props 4107 "END" ":" "VREPLY" CRLF 4109 10.3 CONTINUE Command 4111 CMD: CONTINUE 4113 Purpose: The "CONTINUE" command is only sent after a "TIMEOUT" 4114 command has been received to inform the other end of the session to 4115 resume working on a command. 4117 Formal Definition: A "CONTINUE" command is defined by the following 4118 notation: 4120 continue-cmd = continueparam ":" "CONTINUE" 4122 continueparam = *( 4124 ; the following are optional, 4125 ; but MUST NOT occur more than once 4127 id-param 4128 / localize-param 4129 / latency-param 4131 ; the following MUST occur exactly once and only 4132 ; when the latency-param has been supplied and 4133 ; MUST NOT be supplied if the latency-param is 4134 ; not supplied. 4136 / action-param 4138 ; the following are optional, 4139 ; and MAY occur more than once 4141 / other-params 4142 ) 4144 The REPLY of any "CONTINUE" command is: 4146 continue-reply = "BEGIN" ":" "VCALENDAR" CRLF 4147 calprops 4148 continue-vreply 4149 "END" ":" "VCALENDAR" CRLF 4151 continue-vreply = "BEGIN" ":" "VREPLY" CRLF 4152 request-status 4153 other-props 4154 "END" ":" "VREPLY" CRLF 4156 10.4 CREATE Command 4158 CMD: CREATE 4160 Purpose: The "CREATE" command is used to create one or more 4161 iCalendar objects in the store in the "BOOKED" or "UNPROCESSED" 4162 state. 4164 A CUA MAY send a "CREATE" command to a CS. The "CREATE" command MUST 4165 BE implemented by all CSs. 4167 The CS MUST NOT send a "CREATE" command to any CUA. 4169 Formal Definition: A "CREATE" command is defined by the following 4170 notation and the hierarchy restrictions as defined in Section 3.2: 4172 create-cmd = createparam ":" "CREATE" 4174 createparam = *( 4176 ; the following are optional, 4177 ; but MUST NOT occur more than once 4178 id-param 4179 / localize-param 4180 / latency-param 4182 ; the following MUST occur exactly once and only 4183 ; when the latency-param has been supplied and 4184 ; MUST NOT be supplied if the latency-param is 4185 ; not supplied. 4187 / action-param 4189 ; the following is optional, 4190 ; and MAY occur more than once 4192 / other-params 4193 ) 4195 Response: 4197 One iCalendar object per TARGET property MUST BE returned. 4199 The REPLY of any "CREATE" command is: 4201 Restriction Table for the iCalendar section of a reply that contains 4202 an iCalendar object is any valid [iTIP] response plus any from this 4203 ABNF: 4205 create-reply = "BEGIN" ":" "VCALENDAR" CRLF 4206 creply-props 4207 1*(create-vreply) 4208 "END" ":" "VCALENDAR" CRLF 4210 create-vreply = "BEGIN" ":" "VREPLY" CRLF 4211 created-id 4212 request-status 4213 other-props 4214 "END" ":" "VREPLY" CRLF 4216 ; Where the id is appropriate for the 4217 ; type of object created: 4218 ; 4219 ; VAGENDA = relcalid 4220 ; VALARM = sequence 4221 ; VCAR = carid 4222 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 4223 ; VQUERY = queryid 4224 ; VTIMEZONE = tzid 4225 ; x-component = x-id 4226 ; 4227 created-id = ( relcalid / carid / uid / queryid / 4228 tzid / sequence / x-id) 4230 x-id = ; An ID for an x-component. 4232 creply-props = 4*( 4233 ; These are REQUIRED and MUST NOT occur 4234 ; more than once. 4235 ; 4236 prodid /version / target / reply-cmd 4238 ; These are optional, and may occur more 4239 ; than once. 4240 ; 4241 other-props 4243 For a "CREATE" command the "TARGET" property specifies the containers 4244 where the components will be created. 4246 If the iCalendar object being created does not have a "METHOD" 4247 property, then is not an [iTIP] object, then its state will be 4248 "BOOKED". Use the "DELETE" command to set the state of an object to 4249 the "DELETED" state (tagged for deletion). A CUA can not use the 4250 "CREATE" command to create an object in the "DELETED" state. 4252 If the intention is to book an [iTIP] object then the "METHOD" 4253 property MUST NOT BE supplied. Otherwise any [iTIP] object MUST have 4254 a valid [iTIP] "METHOD" property value and it is a scheduling request 4255 being deposited into the CS and will have its state set to 4256 "UNPROCESSED" state. 4258 ABNF for a "CREATE" object is: 4260 create-object = "BEGIN" ":" "VCALENDAR" CRLF 4261 ; If 'calprops' contain the "METHOD" property 4262 ; then this 'create-object' component MUST 4263 ; conform to [iTIP] restrictions. 4264 ; 4265 ; calprops MUST include 'create-cmd' 4266 ; 4267 calprops 4268 other-props 4269 1*(create-comp) 4270 "END" ":" "VCALENDAR" CRLF 4272 ; NOTE: The 'VCALSTORE' component is not included in 4273 ; 'create-comp' as it is out of scope for CAP to create 4274 ; a new CS. 4275 ; 4276 create-comp = agendac / carc / queryc 4277 / timezonec / freebusyc 4278 / eventc / todoc / journalc 4279 / iana-comp / x-component 4281 In the following example two new top level "VAGENDA" components are 4282 created. Note that the "CSID" value of the server is cal.example.com 4283 which is where the new "VAGENDA" components are going to be created. 4285 C: Content-Type: text/calendar 4286 C: 4287 C: BEGIN:VCALENDAR 4288 C: PRODID:-//someone's prodid 4289 C: VERSION:2.0 4290 C: CMD;ID=creation01:CREATE 4291 C: TARGET:cal.example.com 4292 C: BEGIN:VAGENDA <- data for 1st new calendar 4293 C: CALID:relcalz1 4294 C: NAME;LANGUAGE=en_US:Bill's Soccer Team 4295 C: OWNER:bill 4296 C: CALMASTER:mailto:bill@example.com 4297 C: TZID:US/Pacific 4298 C: END:VAGENDA 4299 C: BEGIN:VAGENDA <- data for 2nd new calendar 4300 C: CALID:relcalz2 4301 C: NAME;LANGUAGE=EN-us:Mary's personal calendar 4302 C: OWNER:mary 4303 C: CALMASTER:mailto:mary@example.com 4304 C: TZID:US/Pacific 4305 C: END:VAGENDA 4306 C: END:VCALENDAR 4308 S: Content-Type: text/calendar 4309 S: 4310 S: BEGIN:VCALENDAR 4311 S: VERSION:2.0 4312 S: PRODID:-//someone's prodid 4313 S: CMD;ID=creation01:REPLY 4314 S: TARGET:cal.example.com 4315 S: BEGIN:VREPLY <- Reply for 1st calendar create 4316 S: CALID:relcalz1 4317 S: REQUEST-STATUS:2.0 4318 S: END:REPLY 4319 S: BEGIN:VREPLY <- Reply for 2nd calendar create 4320 S: CALID:relcalz2 4321 S: REQUEST-STATUS:2.0 4322 S: END:VREPLY 4323 S: END:VCALENDAR 4325 To create a new component in multiple containers simply name all of 4326 the containers in the "TARGET" in the create command. Here a new 4327 "VEVENT" component is created in two TARGET components. In this 4328 example, the "VEVENT" component is one new [iTIP] "REQUEST" to be 4329 stored in two calendars. The results would be iCalendar objects that 4330 conform to the [iTIP] replies as defined in [iTIP]. 4332 This example shows two [iTIP] "VEVENT" components being created in 4333 each of the two supplied "TARGET" properties and as it contains the 4334 "METHOD" property they will be stored in the "UNPROCESSED" state: 4336 C: Content-Type: text/calendar 4337 C: 4338 C: BEGIN:VCALENDAR 4339 C: VERSION:2.0 4340 C: PRODID:-//someone's prodid 4341 C: CMD;ID=creation02:CREATE 4342 C: METHOD:REQUEST 4343 C: TARGET:relcalz1 4344 C: TARGET:relcalz2 4345 C: BEGIN:VEVENT 4346 C: DTSTART:20030307T180000Z 4347 C: UID:FirstInThisExample-1 4348 C: DTEND:20030307T190000Z 4349 C: SUMMARY:Important Meeting 4350 C: END:VEVENT 4351 C: BEGIN:VEVENT 4352 C: DTSTART:20040307T180000Z 4353 C: UID:SecondInThisExample-2 4354 C: DTEND:20040307T190000Z 4355 C: SUMMARY:Important Meeting 4356 C: END:VEVENT 4357 C: END:VCALENDAR 4359 The CS sends the "VREPLY" commands in separate MIME objects, one per 4360 supplied "TARGET" property value. 4362 S: Content-Type: text/calendar 4363 S: 4364 S: BEGIN:VCALENDAR 4365 S: VERSION:2.0 4366 S: PRODID:-//someone's prodid 4367 S: CMD;ID=creation02:REPLY 4368 S: TARGET:relcalz1 <- 1st TARGET listed. 4369 S: BEGIN:REPLY <- Reply for 1st VEVENT create in 1st TARGET. 4370 S: UID:FirstInThisExample-1 4371 S: REQUEST-STATUS:2.0 4372 S: END:VREPLY 4373 S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 1st TARGET. 4374 S: UID:SecondInThisExample-2 4375 S: REQUEST-STATUS:2.0 4376 S: END:VREPLY 4377 S: END:VCALENDAR 4379 And the second reply for the 2nd TARGET: 4381 S: Content-Type: text/calendar 4382 S: 4383 S: BEGIN:VCALENDAR 4384 S: VERSION:2.0 4385 S: PRODID:-//someone's prodid 4386 S: CMD;ID=creation02:REPLY 4387 S: TARGET:relcalz2 <- 2nd TARGET listed 4388 S: BEGIN:REPLY <- Reply for 1st VEVENT create in 2nd TARGET. 4389 S: UID:FirstInThisExample-1 4390 S: REQUEST-STATUS:2.0 4391 S: END:VREPLY 4392 S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 2nd TARGET. 4393 S: UID:SecondInThisExample-2 4394 S: REQUEST-STATUS:2.0 4395 S: END:VREPLY 4396 S: END:VCALENDAR 4398 10.5 DELETE Command 4400 CMD: DELETE 4402 Purpose: The "DELETE" command physically removes the QUERY result 4403 from the store or marks it for deletion. 4405 A CUA MAY send a "DELETE" command to a CS. The "DELETE" command MUST 4406 BE implemented by all CSs. 4408 The CS MUST NOT send a "DELETE" command to any CUA. 4410 Formal Definition: A "DELETE" command is defined by the following 4411 notation: 4413 delete-cmd = deleteparam ":" "DELETE" 4415 deleteparam = *( 4417 ; the following are optional, 4418 ; but MUST NOT occur more than once 4419 ; 4420 id-param 4421 / localize-param 4422 / latency-param 4423 / option-param "MARK" 4425 ; The following MUST occur exactly once and only 4426 ; when the latency-param has been supplied and 4427 ; MUST NOT be supplied if the latency-param is 4428 ; not supplied. 4429 ; 4430 / action-param 4432 ; the following is optional, 4433 ; and MAY occur more than once 4434 ; 4435 / other-params 4436 ) 4438 The "DELETE" command is used to delete calendars or components. The 4439 included "VQUERY" component(s) specifies the container(s) to delete. 4441 If a component is to be marked for delete and not physically removed, 4442 then include the "OPTIONS" parameter with its value set to the "MARK" 4443 value in order to alter its state to "DELETED". 4445 When components are deleted, only the top most component 4446 "REQUEST-STATUS" properties are returned. No "REQUEST-STATUS" 4447 properties are returned for components inside of the selected 4448 components. There MUST BE one "VREPLY" component returned for each 4449 object that is deleted or marked for delete. Note that if no "VREPLY" 4450 components are returned then nothing matched and nothing was deleted. 4452 Restriction Table for the "REPLY" command for any "DELETE" command. 4454 delete-reply = "BEGIN" ":" "VCALENDAR" CRLF 4455 calprops ; MUST include 'reply-cmd' 4456 *(delete-vreply) 4457 "END" ":" "VCALENDAR" CRLF 4459 delete-vreply = "BEGIN" ":" "VREPLY" CRLF 4460 deleted-id 4461 request-status 4462 "END" ":" "VREPLY" CRLF 4464 ; Where the id is appropriate for the 4465 ; type of object deleted: 4466 ; 4467 ; VAGENDA = relcalid 4468 ; VCAR = carid 4469 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 4470 ; VQUERY = queryid 4471 ; ALARM = sequence 4472 ; VTIMEZONE = tzid 4473 ; x-component = x-id 4474 ; An instance = uid recurid 4475 ; 4476 deleted-id = ( relcalid / carid / uid / uid recurid 4477 / queryid / tzid / sequence / x-id ) 4479 Example to delete a "VEVENT" component with "UID" value of 4480 'abcd12345' from the calendar "relcald-22" from the current CS: 4482 C: Content-Type: text/calendar 4483 C: 4484 C: BEGIN:VCALENDAR 4485 C: TARGET:relcalid-22 4486 C: CMD;ID:"random but unique per CUA":DELETE 4487 C: BEGIN:VQUERY 4488 C: QUERY:SELECT VEVENT FROM VAGENDA WHERE UID = 'abcd12345' 4489 C: END:VQUERY 4490 C: END:VCALENDAR 4492 S: BEGIN:VCALENAR 4493 S: TARGET:relcalid-22 4494 S: CMD;ID:"random but unique per CUA":REPLY 4495 S: BEGIN:VREPLY 4496 S: UID:abcd12345 4497 S: REQUEST-STATUS:3.0 4498 S: END:VREPLY 4499 S: END:VCALENDAR 4501 One or more iCalendar objects will be returned that contain a 4502 "REQUEST-STATUS" properties for the deleted components. There could 4503 have been more than one component deleted. Any booked and any number 4504 of unprocessed [iTIP] scheduling components that matched the QUERY 4505 value in the above example. Each unique "METHOD" property value that 4506 was deleted from the store MUST BE in a separate iCalendar object. 4507 This is because only one "METHOD" property is allowed in a single 4508 "VCALENDAR" BEGIN/END block. 4510 10.6 GENERATE-UID Command 4512 CMD: GENERATE-UID 4514 Purpose: The "GENERATE-UID" command returns one or more unique 4515 identifiers which MUST BE globally unique. 4517 The "GENERATE-UID" command MAY BE sent to any CS. The "GENERATE-UID" 4518 command MUST BE implemented by all CSs. 4520 The "GENERATE-UID" command MUST NOT be sent to a CUA. 4522 Formal Definition: A "GENERATE-UID" command is defined by the 4523 following notation: 4525 generate-uid-cmd = genuidparam ":" "GENERATE-UID" 4527 genuidparam = *( 4529 ; The following are optional, 4530 ; but MUST NOT occur more than once. 4532 id-param 4533 / localize-param 4534 / latency-param 4536 ; The following MUST occur exactly once and only 4537 ; when the latency-param has been supplied and 4538 ; MUST NOT be supplied if the latency-param is 4539 ; not supplied. 4541 / action-param 4542 ; The following is optional, 4543 ; and MAY occur more than once. 4545 / other-params 4547 ; The following MUST BE supplied exactly once. 4548 ; The value specifies the number of UIDs to 4549 ; be returned. 4551 / option-param posint1 4553 ) 4555 Response: 4557 gen-reply = "BEGIN" ":" "VCALENDAR" CRLF 4558 calprops ; Which MUST include 'reply-cmd' 4559 1*(gen-vreply) 4560 "END" ":" "VCALENDAR" CRLF 4562 gen-vreply = "BEGIN" ":" "VREPLY" CRLF 4563 1*(uid) 4564 request-status 4565 "END" ":" "VREPLY" CRLF 4567 Example: 4569 C: BEGIN:VCALENDAR 4570 C: VERSION:2.0 4571 C: PRODID:-//someone's prodid 4572 C: CMD;ID=unique-per-cua-124;OPTIONS=5:GENERATE-UID 4573 C: END:VCALENDAR 4575 S: Content-Type: text/calendar 4576 S: 4577 S: BEGIN:VCALENDAR 4578 S: VERSION:2.0 4579 S: PRODID:-//someone's prodid 4580 S: CMD;ID=unique-per-cua-124:REPLY 4581 S: BEGIN:VREPLY 4582 S: UID:20011121T120000Z-12340@cal.example.com 4583 S: UID:20011121T120000Z-12341@cal.example.com 4584 S: UID:20011121T120000Z-12342@cal.example.com 4585 S: UID:20011121T120000Z-12343@cal.example.com 4586 S: UID:20011121T120000Z-12344@cal.example.com 4587 S: REQUEST-STATUS:2.0 4588 S: END:VREPLY 4589 S: END:VCALENDAR 4591 10.7 GET-CAPABILITY Command 4593 CMD: GET-CAPABILITY 4595 Purpose: The "GET-CAPABILITY" command returns the capabilities of the 4596 other end point of the session. 4598 A CUA MUST send a "GET-CAPABILITY" command to a CS after the initial 4599 connection. A CS MUST send a "GET-CAPABILITY" command to a CUA after 4600 the initial connection. The "GET-CAPABILITY" command and reply MUST 4601 BE implemented by all CSs and CUAs. 4603 Formal Definition: A "GET-CAPABILITY" command is defined by the 4604 following notation: 4606 get-capability-cmd = capibiltyparam ":" "GET-CAPABILITY" 4608 capibiltyparam = *( 4610 ; the following are optional, 4611 ; but MUST NOT occur more than once 4612 ; 4613 id-param / localize-param / latency-param 4615 ; the following MUST occur exactly once and only 4616 ; when the latency-param has been supplied and 4617 ; MUST NOT be supplied if the latency-param is 4618 ; not supplied. 4619 ; 4620 / action-param 4622 ; the following is optional, 4623 ; and MAY occur more than once 4624 ; 4625 / other-params 4626 ) 4628 Response: 4630 The "GET-CAPABILITY" command returns information about the Calendar 4631 other end of the session given the current state of the connection. 4632 The values returned may differ depending on current user identify and 4633 the security level of the connection. 4635 Client implementations SHOULD NOT require any capability element 4636 beyond those defined in this specification or future RFC publications 4637 , and MAY ignore any nonstandard, experimental capability elements. 4638 The "GET-CAPABILITY" reply may return different results depending on 4639 the UPN and if the UPN is authenticated. 4641 When sending a reply to a "GET-CAPABILITY" command, all of these MUST 4642 BE supplied. The following properties are returned in response to a 4643 "GET-CAPABILITY" command: 4645 cap-vreply = "BEGIN" ":" "VCALENDAR" CRLF 4646 ; The following properties may be in any order. 4647 ; 4648 prodid 4649 version 4650 reply-cmd 4651 other-props 4652 "BEGIN" ":" "VREPLY" CRLF 4653 ; The following properties may be in any order. 4654 ; 4655 cap-version 4656 car-level 4657 components 4658 stores-expanded 4659 maxdate 4660 mindate 4661 itip-version 4662 max-comp-size 4663 multipart 4664 query-level 4665 recur-accepted 4666 recur-expand 4667 recur-limit 4668 other-props 4669 "END" ":" "VREPLY" CRLF 4670 "END" ":" "VCALENDAR" CRLF 4672 Example: 4674 I: Content-Type: text/calendar 4675 I: 4676 I: BEGIN:VCALENDAR 4677 I: VERSION:2.0 4678 I: PRODID:-//someone's prodid 4679 I: CMD;ID=unique-per-cua-125:GET-CAPABILITY 4680 I: END:VCALENDAR 4682 L: Content-Type: text/calendar 4683 L: 4684 L: BEGIN:VCALENDAR 4685 L: VERSION:2.0 4686 L: PRODID:-//someone's prodid 4687 L: CMD;ID=unique-per-cua-125:REPLY 4688 L: BEGIN:VREPLY 4689 L: CAP-VERSION:1.0 4690 L: PRODID:The CS prodid 4691 L: QUERY-LEVEL:CAL-QL-1 4692 L: CAR-LEVEL:CAR-FULL-1 4693 L: MAXDATE:99991231T235959Z 4694 L: MINDATE:00000101T000000Z 4695 L: MAX-COMPONENT-SIZE:0 4696 L: COMPONENTS:VCALENDAR,VTODO,VJOURNAL,VEVENT,VCAR, 4697 L: VALARM,VFREEBUSY,VTIMEZONE,STANDARD,DAYLIGHT,VREPLY 4698 L: ITIP-VERSION:2446 4699 L: RECUR-ACCEPTED:TRUE 4700 L: RECUR-EXPAND:TRUE 4701 L: RECUR-LIMIT:0 4702 L: STORES-EXPANDED:FALSE 4703 L: X-INET-PRIVATE-COMMANDS:1.0 4704 L: END:VREPLY 4705 L: END:VCALENDAR 4707 10.8 IDENTIFY Command 4709 CMD: IDENTIFY 4711 Purpose: The "IDENTIFY" command allows the CUA to set a new identity 4712 to be used for calendar access. 4714 A CUA MAY send an "IDENTIFY" command to a CS. The "IDENTIFY" command 4715 MUST BE implemented by all CSs. A CS implementation MAY reject all 4716 "IDENTIFY" commands. 4718 The CS MUST NOT send a "IDENTIFY" command to any CUA. 4720 Formal Definition: A "IDENTIFY" command is defined by the following 4721 notation: 4723 identify-cmd = identifyparam ":" "IDENTIFY" 4725 identifyparam = *( 4727 ; the following are optional, 4728 ; but MUST NOT occur more than once 4730 id-param 4731 / localize-param 4732 / latency-param 4734 ; the following MUST occur exactly once and only 4735 ; when the latency-param has been supplied and 4736 ; MUST NOT be supplied if the latency-param is 4737 ; not supplied. 4739 / action-param 4741 ; the following is optional, 4742 ; and MAY occur more than once 4744 / other-params 4746 ; The value is the UPN of the requested 4747 ; identity. If option is not supplied it is 4748 ; a request to return to the original authenticated 4749 ; identity. 4751 / option-param upn 4753 ) 4755 Response: 4757 A "REQUEST-STATUS" property wrapped in a "VREPLY" component with only one of the following 4758 request-status codes: 4760 2.0 Successful. 4762 6.4 Identity not permitted. VCAR restriction. 4764 The CS determines through an internal mechanism if the credentials 4765 supplied at authentication permit the operation as the selected 4766 identity. If they do, the session assumes the new identity, otherwise 4767 a security error is returned. 4769 Example: 4771 C: Content-Type: text/calendar 4772 C: 4773 C: BEGIN:VCALENDAR 4774 C: VERSION:2.0 4775 C: PRODID:-//someone's prodid 4776 C: CMD;ID=unique-per-cua-999;OPTIONS=newUserId:IDENTIFY 4777 C: END:VCALENDAR 4779 S: Content-Type: text/calendar 4780 S: 4781 S: BEGIN:VCALENDAR 4782 S: VERSION:2.0 4783 S: PRODID:-//someone's prodid 4784 S: BEGIN:VREPLY 4785 S: REQUEST-STATUS:2.0;Request Approved 4786 S: END:VREPLY 4787 S: END:VCALENDAR 4789 Or if denied: 4791 S: Content-Type: text/calendar 4792 S: 4793 S: BEGIN:VCALENDAR 4794 S: PRODID:-//someone's prodid 4795 S: VERSION:2.0 4796 S: BEGIN:VREPLY 4797 S: REQUEST-STATUS:6.4;Request Denied 4798 S: END:VREPLY 4799 S: END:VCALENDAR 4801 And for the CUA to return to its original authenticated identity 4802 the OPTIONS parameter is omitted: 4804 C: Content-Type: text/calendar 4805 C: 4806 C: BEGIN:VCALENDAR 4807 C: VERSION:2.0 4808 C: PRODID:-//someone's prodid 4809 C: CMD;ID=unique-per-cua-995:IDENTIFY 4810 C: END:VCALENDAR 4812 The CS may accept (2.0) or deny (6.4) the request to return to the 4813 original identity. 4815 If a CS considers the "IDENTIFY" command an attempt to violate 4816 security, the CS MAY terminate the [BEEP] session without any further 4817 notice to the CUA after sending the "REQUEST-STATUS" 6.4 reply. 4819 10.9 MODIFY Command 4821 CMD: MODIFY 4823 Purpose: The "MODIFY" command is used to modify existing components. 4825 A CUA MAY send a "MODIFY" command to a CS. The "MODIFY" command MUST 4826 BE implemented by all CSs. 4828 The CS MUST NOT send a "MODIFY" command to any CUA. 4830 Formal Definition: A "MODIFY" command is defined by the following 4831 notation: 4833 modify-cmd = modifyparam ":" "MODIFY" 4835 modifyparam = *( 4837 ; the following are optional, 4838 ; but MUST NOT occur more than once 4840 id-param 4841 / localize-param 4842 / latency-param 4844 ; the following MUST occur exactly once and only 4845 ; when the latency-param has been supplied and 4846 ; MUST NOT be supplied if the latency-param is 4847 ; not supplied. 4849 / action-param 4851 ; the following is optional, 4852 ; and MAY occur more than once 4854 / other-params 4856 ) 4858 The "MODIFY" command is used to modify existing components. The 4859 TARGET property specifies the calendars where the components exist 4860 that are going to be modified. 4862 The format of the request is three components inside of "VCALENDAR" 4863 component: 4865 BEGIN:VCALENDAR 4866 ... 4867 BEGIN:VQUERY 4868 ... 4869 END:VQUERY 4870 BEGIN:XXX 4871 ...old-values... 4872 END:XXX 4873 BEGIN:XXX 4874 ...new-values... 4875 END:XXX 4876 END:VCALENDAR 4878 The "VQUERY" component selects the components that are to be 4879 modified. 4881 Where "XXX" above is a named component type (VEVENT, VTODO, ...). 4882 Both the old and new components MUST BE of the same type. 4884 The old-values is a component and the contents of that component are 4885 going to change and may contain information that helps uniquely 4886 identify the original component (SEQUENCE in the example below). If 4887 the CS can not find a component that matches the QUERY and does not 4888 have at least all of the OLD-VALUES, then a 6.1 error is returned. 4890 The new-values is a component of the same type as old-values and 4891 new-values contains the new data for each selected component. Any 4892 data that is in old-values and not in new-values is deleted from the 4893 selected component. Any values in new-values that was not in 4894 old-values is added to the component. 4896 In this example the "VEVENT" component with a "UID" property value of 4897 'unique-58' has; the "LOCATION" property and "LAST-MODIFIED" property 4898 changed, the "VALARM" component with the "SEQUENCE" property with a 4899 value of "3" has its "TRIGGER" property disabled, the "X-LOCAL" 4900 property is removed from the "VEVENT" component, and a "COMMENT" 4901 property is added. 4903 Because "SEQUENCE" property is used to locate the "VALARM" component 4904 in this example, both the old-values and the new-values contain the 4905 "SEQUENCE" property with a value of "3" and if the "SEQUENCE" 4906 property were to be left out of new-values, it would have been 4907 deleted. 4909 Example: 4911 C: Content-Type: text/calendar 4912 C: 4913 C: BEGIN:VCALENDAR 4914 C: VERSION:2.0 4915 C: PRODID:-//someone's prodid 4916 C: TARGET:my-cal 4917 C: CMD:ID=unique-mod:MODIFY 4918 C: BEGIN:VQUERY <- Query to select data set. 4919 C: QUERY:SELECT * FROM VEVENT WHERE UID = 'unique-58' 4920 C: END:VQUERY 4921 C: BEGIN:VEVENT <- Start of old data. 4922 C: LOCATION:building 3 4923 C: LAST-MODIFIED:20020101T123456Z 4924 C: X-LOCAL:some private stuff 4925 C: BEGIN:VALARM 4926 C: SEQUENCE:3 4927 C: TRIGGER;RELATED=END:PT5M 4928 C: END:VALARM 4929 C: END:VEVENT <- End of old data. 4930 C: BEGIN:VEVENT <- Start of new data. 4931 C: LOCATION:building 4 4932 C: LAST-MODIFIED:20020202T010203Z 4933 C: COMMENT:Ignore global trigger. 4934 C: BEGIN:VALARM 4935 C: SEQUENCE:3 4936 C: TRIGGER;ENABLE=FALSE:RELATED=END:PT5M 4937 C: END:VALARM 4938 C: END:VEVENT <- End of new data. 4939 C: END:VCALENDAR 4941 The "X-LOCAL" property was not supplied in the new-values, so it was 4942 deleted. The "LOCATION" property value was altered, as was the 4943 "LAST-MODIFIED" value. The "VALARM" component with a "SEQUENCE" 4944 property value of "3" had its "TRIGGER" property disabled, and the 4945 "SEQUENCE" property value did not change so it was not effected. The 4946 "COMMENT" property was added. 4948 When it comes to inline ATTACHMENTs, the CUA only needs to uniquely 4949 identify the contents of the ATTACHMENT value in the old-values in 4950 order to delete them. When the CS compares the attachment data it is 4951 compared in its binary form. The ATTACHMENT value supplied by the CUA 4952 MUST BE valid encoded information. 4954 For example, to delete the same huge inline attachment from every 4955 VEVENT in 'my-cal' that has an "ATTACH" property value with the 4956 old-values: 4958 BEGIN:VCALENDAR 4959 VERSION:2.0 4960 PRODID:-//someone's prodid 4961 TARGET:my-cal 4962 CMD:MODIFY 4963 BEGIN:VQUERY 4964 QUERY:SELECT ATTACH FROM VEVENT 4965 END:VQUERY 4966 BEGIN:VEVENT 4967 ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY: 4968 MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U 4969 EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE 4970 ...< remainder of attachment data NOT supplied >.... 4971 END:VEVENT 4972 BEGIN:VEVENT 4973 END:VEVENT 4974 END:VCALENDAR 4976 Above the new-values is empty, so everything in the old-values is 4977 deleted. 4979 Furthermore, the following additional restrictions apply: 4981 1. One can not change the "UID" property of a component. 4983 2. If a contained component is changed inside of a selected 4984 component, and that contained component has multiple instances, 4985 then old-values MUST contain information that uniquely identifies 4986 the instance or instances that are changing. It is valid to 4987 change more than one. As all contained components that match 4988 old-values will be modified. In the first modify example above, 4989 if "SEQUENCE" properties were to be deleted from both the 4990 old-values and new-values, then all "TRIGGER" properties that 4991 matched the old-values in all "VALARM" components in the selected 4992 "VEVENT" components would be disabled. 4994 3. The result of the modify MUST BE a valid iCalendar object. 4996 Response: 4998 A "VCALENDAR" component is returned with one ore more 4999 "REQUEST-STATUS" property values. 5001 If any error occurred: 5003 No component will be changed at all. That is, it will appear just 5004 as it was prior to the modify and the CAP server SHOULD return a 5005 "REQUEST-STATUS" property for each error that occurred. 5007 There MUST BE at least one error reported. 5009 If multiple components are selected, then what uniquely identified 5010 the component MUST BE returned (UID, QUERYID, ...) if the component 5011 contains a unique identifier. If not, sufficient information to 5012 uniquely identify the modified components MUST BE returned in the 5013 reply. 5015 S: Content-Type: text/calendar 5016 S: 5017 S: BEGIN:VCALENDAR 5018 S: TARGET:relcalid 5019 S: CMD;ID=delete#1:REPLY 5020 S: BEGIN:VREPLY 5021 S: BEGIN:VEVENT 5022 S: UID:123 5023 S: REQUEST-STATUS:2.0 5024 S: END:VEVENT 5025 S: END:VREPLY 5026 S: END:VCALENDAR 5028 10.10 MOVE Command 5030 CMD: MOVE 5032 Purpose: The "MOVE" command is used to move components within the CS. 5034 A CUA MAY send a "MOVE" command to a CS. The "MOVE" command MUST BE 5035 implemented by all CSs. 5037 The CS MUST NOT send a "MOVE" command to any CUA. 5039 Formal Definition: A "MOVE" command is defined by the following 5040 notation: 5042 move-cmd = moveparam ":" "MOVE" 5044 moveparam = *( 5046 ; the following are optional, 5047 ; but MUST NOT occur more than once 5048 id-param 5049 / localize-param 5050 / latency-param 5052 ; the following MUST occur exactly once and only 5053 ; when the latency-param has been supplied and 5054 ; MUST NOT be supplied if the latency-param is 5055 ; not supplied. 5057 / action-param 5059 ; the following is optional, 5060 ; and MAY occur more than once 5062 / other-params 5064 ) 5066 Response: 5067 The REQUEST-STATUS in a VCALENDAR object. 5069 The content of each "result" is subject to the result restriction 5070 table defined below. 5072 The access control on the "VAGENDA" component after it has been moved 5073 to its new location in the calstore MUST BE at least as secure as it 5074 was prior to the move. If the CS is not able to ensure the same level 5075 of security, a permission denied "REQUEST-STATUS" property value MUST 5076 BE returned and the "MOVE" command not performed. 5078 The "TARGET" property value specifies the new location, and the 5079 "VQUERY" component specifies the old location. 5081 Restriction Table for the "REPLY" command of any "MOVE" command. 5083 move-reply = "BEGIN" ":" "VCALENDAR" CRLF 5084 calprops 5085 1*(move-vreply) 5086 "END" ":" "VCALENDAR" CRLF 5088 move-vreply = "BEGIN" ":" "VREPLY" CRLF 5089 move-id 5090 request-status 5091 "END" ":" "VREPLY" CRLF 5092 ; Where the id is appropriate for the 5093 ; type of object moved: 5094 ; 5095 ; VAGENDA = relcalid 5096 ; VCAR = carid 5097 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 5098 ; VQUERY = queryid 5099 ; ALARM = sequence 5100 ; An instance = uid recurid 5101 ; x-component = x-id 5102 ; 5103 move-id = ( relcalid / carid / uid / uid recurid 5104 / queryid / tzid / sequence / x-id) 5106 Example: moving the VAGENDA Nellis to Area-51 5108 C: Content-Type: text/calendar 5109 C: 5110 C: BEGIN:VCALENDAR 5111 C: VERSION:2.0 5112 C: PRODID:-//someone's prodid 5113 C: CMD:MOVE 5114 C: TARGET:Area-51 5115 C: BEGIN:VQUERY 5116 C: QUERY: SELECT * FROM VAGENDA WHERE CALID='Nellis' 5117 C: END:VQUERY 5118 C: END:VCALENDAR 5120 S: Content-Type: text/calendar 5121 S: 5122 S: BEGIN:VCALENDAR 5123 S: VERSION:2.0 5124 S: PRODID:-//someone's prodid 5125 S: TARGET:Area-51 5126 S: BEGIN:VREPLY 5127 S: CALID:Nellis 5128 S: REQUEST-STATUS: 2.0 5129 S: END:VREPLY 5130 S: END:VCALENDAR 5132 10.11 REPLY Response to a Command 5134 CMD: REPLY 5135 Purpose: The "REPLY" value to the "CMD" property is used to return 5136 the results of all other commands to the CUA. 5138 A CUA MUST send a "REPLY" command to a CS for any command a CS MAY 5139 send to the CUA. The "REPLY" command MUST BE implemented by all CUAs 5140 that support getting the "GET-CAPABILITY" command. 5142 A CS MUST send a "REPLY" command to a CUA for any command a CUA MAY 5143 send to the CS. The "REPLY" command MUST BE implemented by all CSs. 5145 Formal Definition: A "REPLY" command is defined by the following 5146 notation: 5148 reply-cmd = replyparam ":" "REPLY" 5150 replyparam = *( 5152 ; The 'id' parameter value MUST BE exactly the 5153 ; same as the value sent in the original 5154 ; CMD property. If the original CMD did 5155 ; not have an 'id' parameter, then the 'id' 5156 ; MUST NOT be supplied in the REPLY. 5158 id-param 5160 ; the following is optional, 5161 ; and MAY occur more than once 5163 / other-params 5165 ) 5167 10.12 SEARCH Command 5169 CMD: SEARCH 5171 Purpose: The "SEARCH" command is used to return selected components 5172 to the CUA. 5174 A CUA MAY send a "SEARCH" command to a CS. The "SEARCH" command MUST 5175 BE implemented by all CSs. 5177 The CS MUST NOT send a "SEARCH" command to any CUA. 5179 Formal Definition: A "SEARCH" command is defined by the following 5180 notation: 5182 search-cmd = searchparam ":" "SEARCH" 5184 searchparam = *( 5186 ; the following are optional, 5187 ; but MUST NOT occur more than once 5189 id-param 5190 / localize-param 5191 / latency-param 5193 ; the following MUST occur exactly once and only 5194 ; when the latency-param has been supplied and 5195 ; MUST NOT be supplied if the latency-param is 5196 ; not supplied. 5198 / action-param 5200 ; the following is optional, 5201 ; and MAY occur more than once 5203 / other-params 5205 ) 5207 The format of the request is the search command (search-cmd) followed 5208 by one or more (query) "VQUERY" components 5210 Response: 5212 The data in each result set contains one or more iCalendar components 5213 composed of all the selected results enclosed in a single "VREPLY" 5214 component per "QUERY". 5216 Only "REQUEST-STATUS" property and the properties mentioned in the 5217 "SELECT" clause of the QUERY are included in the components. Each 5218 "VCALENDAR" component is tagged with the "TARGET" property. 5220 Searching for objects 5222 In the example below objects on March 10,1999 between 080000Z and 5223 190000Z are read. In this case only 4 properties for each objects are 5224 returned. Two calendars are specified. Only booked (vs scheduled) 5225 entries are to be returned (this example only selected VEVENT 5226 objects): 5228 C: Content-Type: text/calendar 5229 C: 5230 C: BEGIN:VCALENDAR 5231 C: VERSION:2.0 5232 C: PRODID:-//someone's prodid 5233 C: CMD:SEARCH 5234 C: TARGET:relcal2 5235 C: TARGET:relcal3 5236 C: BEGIN:VQUERY 5237 C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID 5238 C: FROM VEVENT 5239 C: WHERE DTEND >= '19990310T080000Z' 5240 C: AND DTSTART <= '19990310T190000Z' 5241 C: AND STATE() = 'BOOKED' 5242 C: END:VQUERY 5243 C: END:VCALENDAR 5245 The return values are subject to VCAR filtering. That is, if the 5246 request contains properties to which the UPN does not have access, 5247 those properties will not appear in the return values. If the UPN has 5248 access to at least one property of the component, but has been denied 5249 access to all properties called out in the request, the response will 5250 contain a single "REQUEST-STATUS" property indicating the error. 5252 Here the request was successful, however one of the "VEVENT" 5253 components contents were not accessible (4.1). 5255 S: Content-Type: text/calendar 5256 S: 5257 S: BEGIN:VCALENDAR 5258 S: TARGET:relcalid 5259 S: CMD:REPLY 5260 S: VERSION:2.0 5261 S: PRODID:-//someone's prodid 5262 S: BEGIN:VREPLY 5263 S: BEGIN:VEVENT 5264 S: REQUEST-STATUS:4.1 5265 S: END:VEVENT 5266 S: BEGIN:VEVENT 5267 S: REQUEST-STATUS:2.0 5268 S: UID:123 5269 S: DTEND:19990310T080000Z 5270 S: DSTART:19990310T190000Z 5271 S: SUMMARY: Big meeting 5272 S: END:VEVENT 5273 S: END:VREPLY 5274 S: END:VCALENDAR 5276 If the UPN has no access to any components at all, the response will 5277 simply be an empty data set. The response looks the same if there 5278 the particular components did not exist. 5280 S: Content-Type: text/calendar 5281 S: 5282 S: BEGIN:VCALENDAR 5283 S: VERSION:2.0 5284 S: PRODID:-//someone's prodid 5285 S: CMD:REPLY 5286 S: TARGET:ralcalid 5287 S: BEGIN:VREPLY 5288 S: REQUEST-STATUS:2.0 5289 S: END:VREPLY 5290 S: END:VCALENDAR 5292 If there are multiple targets, each iCalendar reply is contained 5293 within its own iCalendar object. 5295 10.12.1 Searching for VFREEBUSY 5297 If a CS sets the "RECUR-EXPAND" property to "TRUE" and contains the 5298 "VFREEBUSY" component in the "COMPONENTS" value in a reply to the 5299 "GET-CAPABILITY" command, then it is the CS's responsibility and not 5300 the CUA's responsibility to provide the correct "VFREEBUSY" 5301 information for a calendar. 5303 If a CUA issues a "CREATE" "VFREEBUSY", such a CS MUST return success 5304 and not store the "VFREEBUSY" component as the results would never be 5305 used. 5307 Such a CS MUST dynamically create the results of a search for 5308 "VFREEBUSY" components at search time when searching for STATE() = 5309 'BOOKED' items. 5311 If a CUA searches for "VFREEBUSY" components with STATE() = 5312 'UNPROCESSED', such a CS MUST return a "VREPLY" with no components. 5314 If a CUA searches for "VFREEBUSY" components without specifying the 5315 STATE, such a CS MUST return the same result as if STATE()='BOOKED' 5316 had been specified. 5318 For CSs that set the "CAPABILITY" "RECUR-EXPAND" property to "FALSE" 5319 and have the "VFREEBUSY" component in the "COMPONENTS" value in the 5320 "CAPABILITY" reply, a CUA MAY store the "VFREEBUSY" information on 5321 the CS. These CSs then MUST return a "VFREEBUSY" component calculated 5322 from the stored components. If no "VFREEBUSY" information is 5323 available for the "TARGET" calendar, then a "VFREEBUSY" with no 5324 blocked out time will be returned with a success code. A CUA sets the 5325 "VFREEBUSY" time on a those calendars by creating a "VFREEBUSY" 5326 component without a "METHOD" creating a "BOOKED" entry. 5328 If a CS does not set the "VFREEBUSY" value in the "COMPONENTS" 5329 "CAPABILITY" value, the CS does not support the "VFREEBUSY" component 5330 and all creation and searching for a "VFREEBUSY" component MUST fail. 5331 Examples of calendars that may be in this category are public event 5332 calendars that will never require scheduling with other UPNs. 5334 10.13 SET-LOCALE Command 5336 CMD: SET-LOCALE 5338 Purpose: The "SET-LOCALE" command is used to select the locale that 5339 will be used in error codes used in the "REQUEST-STATUS" property. 5341 A CUA MAY send a "SET-LOCALE" command to a CS. The SET-LOCALE command 5342 MUST BE implemented by all CSs. 5344 The CS MUST NOT send a "SET-LOCALE" command to any CUA. 5346 Formal Definition: A "SET-LOCALE" command is defined by the following 5347 notation: 5349 setlocale-cmd = setlocaleparam ":" "SET-LOCALE" 5351 setlocaleparam = *( 5353 ; the following are optional, 5354 ; but MUST NOT occur more than once 5356 id-param 5357 / localize-param 5358 / latency-param 5359 / setlocale-option 5361 ; the following MUST occur exactly once and only 5362 ; when the latency-param has been supplied and 5363 ; MUST NOT be supplied if the latency-param is 5364 ; not supplied. 5366 / action-param 5368 ; the following is optional, 5369 ; and MAY occur more than once 5371 / other-params 5373 setlocal-option = option-param newlocale 5375 newlocale = ; Any locale supplied in the initial [BEEP] 5376 ; "greeting" "localize" parameter and 5377 ; and any charset supported by the CS 5378 ; and listed in the DEFAULT-CHARSET property 5379 ; of the VCALSTORE. 5381 ) 5383 Examples: 5385 CMD:OPTIONS=en_US.UTF-8:SET-LOCALE 5386 CMD:OPTIONS=th_TH.ISO8859-11:SET-LOCALE 5387 CMD:OPTIONS=es_MX.ISO8859-1:SET-LOCALE 5389 Restriction Table for the "REPLY" command of any "SET-LOCALE" 5390 command. 5392 setlocale-reply = "BEGIN" ":" "VCALENDAR" CRLF 5393 calprops 5394 1*(setlocale-vreply) 5395 "END" ":" "VCALENDAR" CRLF 5397 setlocale-vreply = "BEGIN" ":" "VREPLY" CRLF 5398 request-status 5399 "END" ":" "VREPLY" CRLF 5401 10.14 TIMEOUT Command 5403 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 = timeoutparam ":" "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.15 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 publication 5517 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 Beep replies will be one to one (1:1 MSG/RPY) if possible and one to 5540 many (1:many MSG/ANS) when the TARGET changes. 5542 Profile Identification: specify a URI [10] that authoritatively 5543 identifies this profile. 5545 http://iana.org/beep/cap/1.0 5547 Message Exchanged during Channel Creation: 5549 CUAs SHOULD supply the BEEP "localize" attributes in the BEEP 5550 "greeting" messages. 5552 CSs SHOULD supply the BEEP "localize" attributes in the BEEP 5553 "greeting" messages. 5555 CUAs SHOULD supply the BEEP "serverName" attribute at channel 5556 creation time to the CS so that if the CS is performing virtual 5557 hosting the CS can determine the intended virtual host. CSs that do 5558 not support virtual hosting may ignore the BEEP "serverName" 5559 attribute. 5561 Messages starting one-to-one exchanges: 5563 The initial message each direction MUST BE single "text/calendar" 5564 object containing a CAP "CAPABILITY" CMD and must not be part of a 5565 MIME multipart message. 5567 After the initial message then a BEEP "MSG" may contain one or more 5568 MIME objects at least one of which MUST be "text/calendar" and each 5569 "text/calendar" MIME object MUST contain a CAP "CMD" property. 5571 Multiple iCal objects may be sent in a single BEEP message by either 5572 representing them as separate MIME text/calendar parts contained 5573 within a MIME multipart/mixed part or by simple concatenation within 5574 a single text/calendar MIME object. 5576 In either case, all iCal objects transmitted together must have the 5577 same TARGET property. 5579 The sending of multipart MIME entities over BEEP is not permitted for 5580 CAP unless the other endpoint has indicated its ability to accept 5581 them via the appropriate CAPABILITY. 5583 Messages in positive replies: 5585 After the initial message then a BEEP "RPY" may contain one or more 5586 MIME objects at least one of which MUST be "text/calendar" and each 5587 "text/calendar" MIME object MUST contain a CAP "CMD" property. All 5588 "text/calendar" MIME objects in a single BEEP "RPY" messages MUST 5589 have the same "TARGET" property value. 5591 Multiple iCal objects may be sent in a single BEEP message by either 5592 representing them as separate MIME text/calendar parts contained 5593 within a MIME multipart/mixed part or by simple concatenation within 5594 a single text/calendar MIME object. 5596 In either case, all iCal objects transmitted together must have the 5597 same TARGET property. 5599 The sending of multipart MIME entities over BEEP is not permitted for 5600 CAP unless the other endpoint has indicated its ability to accept 5601 them via the appropriate CAPABILITY. 5603 Messages in negative replies: 5605 Any valid "text/calendar" MIME object that contains CAP 5606 "REQUEST-STATUS" property and a CAP "CMD" property with a property 5607 value of "REPLY". And where the CS has determined the requested 5608 operation to be a fatal error. And when the CS has performed NO 5609 operation that effected the contents of any part of the CS or any 5610 calendar controlled by the CS. 5612 Messages in one-to-many exchanges: 5614 After the initial message then a BEEP "MSG" may contain one or more 5615 MIME objects at least one of which MUST be "text/calendar" and each 5616 "text/calendar" MIME object MUST contain a CAP "CMD" property. 5618 The BEEP "MSG" messages can only contain MIME "multipart" MIME 5619 objects if the other endpoint has received a CAP "CAPABILITY" 5620 indicating the other endpoint supports multipart MIME objects. This 5621 does not prevent the endpoint from sending multiple [iCAL] 5622 'icalobject' objects in a single BEEP "MSG" so long as all of them 5623 have the same "TARGET" property value. 5625 Multiple iCal objects may be sent in a single BEEP message by either 5626 representing them as separate MIME text/calendar parts contained 5627 within a MIME multipart/mixed part or by simple concatenation within 5628 a single text/calendar MIME object. 5630 In either case, all iCal objects transmitted together must have the 5631 same TARGET property. 5633 The sending of multipart MIME entities over BEEP is not permitted for 5634 CAP unless the other endpoint has indicated its ability to accept 5635 them via the appropriate CAPABILITY. 5637 Message Syntax: 5639 They are CAP "text/calendar" MIME objects as specified in this memo. 5640 (Remember this text will be part of CAP). 5642 Message Semantics: 5644 As defined in this memo. (Remember this will be part of CAP). 5646 12.2 BEEP Exchange Styles 5648 [BEEP] defines three styles of message exchange: 5650 MSG/ANS,ANS,...,NUL - For one to many exchanges. 5652 MSG/RPY - For one to one exchanges. 5654 MSG/ERR - For requests the cannot be processed due to an error. 5656 A CAP request targeted at more than one containers, MAY use a one- 5657 to-many exchange, with a distinct answer associated with each target. 5658 CAP request targeted at a single container MAY use a one-to-one 5659 exchange or a one-to-many exchange. "MSG/ERR" MAY only be used when 5660 an error condition prevents the execution of the request on all the 5661 targeted calendars. 5663 13. IANA Considerations 5665 This memo defines IANA registered extensions to the attributes 5666 defined by iCalendar, as defined in [iCAL], and [iTIP]. 5668 IANA registration proposals for iCalendar and [iTIP] are to be mailed 5669 to the registration agent for the "text/calendar" [MIME] 5670 content-type, using the format 5671 defined in section 7 of [iCAL]. 5673 If the IESG approves this memo for publication, then the IANA 5674 registers the profile specified in Section 12.1, and selects an 5675 IANA-specific URI, e.g., http://iana.org/beep/cap/1.0. 5677 14. Security Considerations 5679 Access rights should be granted cautiously. Without careful planning 5680 it is possible to open up access to a greater degree than desired. 5682 The "IDENTIFY" command should be carefully implemented. 5684 In addition, since CAP is a profile of [BEEP], consult [BEEP]'s 5685 Section 9 for a discussion of BEEP-specific security issues. 5687 There are risks of allowing anonymous UPNs to deposit REQUEST and 5688 REFRESH objects. (calendar spam and deninal of service for example) 5689 So implementations should consider methods to restrict anonymous 5690 requests to within acceptable usages. 5692 CS implementations might consider automatically creating VCARs that 5693 allow CAP ATTENDEEs in booked objects to deposit REFRESH and REPLY 5694 objects for those UIDs if they otherwise do not have access rather 5695 then opening up world access. And they may consider also allowing 5696 COUNTER objects for those ATTENDEEs. 5698 When an object is booked by a CUA the CS reply may wish to include 5699 warning messages to the CUA for ATTENDEEs that have CAP urls that do 5700 not have local UPNs as those ATTENDEES may be unable to REPLY or 5701 REFRESH. Some CSs may wish this to be an error. 5703 Although service provisioning is a policy matter, at a minimum, all 5704 implementations must provide the following tuning profiles: 5706 for authentication: http://iana.org/beep/SASL/DIGEST-MD5 5708 for confidentiality: http://iana.org/beep/TLS (using the 5709 TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher) 5711 for both: http://iana.org/beep/TLS (using the 5712 TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher supporting client-side 5713 certificates) 5715 URIs 5717 [1] 5719 Authors' Addresses 5721 Doug Royer 5722 INET-Consulting.com 5723 1795 W. Broadway #266 5724 Idaho Falls, ID 83402 5725 US 5727 Phone: +1-866-594-8574 5728 Fax: +1-866-594-8574 5729 EMail: Doug@Royer.com 5730 URI: http://INET-Consulting.com 5732 George Babics 5733 Oracle 5734 2000 Peel Street 5735 Montreal, Quebec H3A 2W5 5736 CA 5738 Phone: +1-514-733-8500 x4201 5739 Fax: +1-514-733-8878 5740 EMail: George.Babics@Oracle.com 5742 Paul Hill 5743 Massachusetts Institute of Technology 5744 W92-172 5745 77 Massachusetts Avenue 5746 Cambridge, MA 02139 5747 US 5749 Phone: +1-617-253-0124 5750 Fax: +1-617-258-8736 5751 EMail: phb@mit.edu 5752 Steve Mansour 5753 AOL/Netscape 5754 466 Ellis Road 5755 Mountain View, CA 94043 5756 US 5758 Phone: +1-650-937-3351 5759 EMail: sman@netscape.com 5761 Appendix A. Acknowledgments 5763 The following have individuals were major contributors in the 5764 drafting and discussion of this memo: 5766 Harald Alvestrand, Christopher Apple, G. Barnes, ArentJan Banck, 5767 Martijn van Beers, Mario Bonin, Andrea Campi, Darryl Champagne, Damon 5768 Chaplin, Karen Chu, Shannon Clark, Andre Courtemanche, Dave Crocker, 5769 Alan Davies, Andrew Davison, Mark Davidson, Bernard Desruisseaux, 5770 Frank Dawson, Pat Egen, Greg FitzPatrick, illes Fortin, Ned Freed, 5771 Gary Frederick, Jagan Garimella, Graham Gilmore, Micah Gorrell, 5772 Lawrence Greenfield, Bertrand Guiheneuf, Olivier Gutknecht, Mike 5773 Hixson, Jeff Hodges, Paul Hoffman, Scott Hollenbeck, Alex Hoppman, 5774 Bruce Kahn, Lata Kannan, suchet singh khalsa, Dan Kohn, Patrice 5775 Lapierre, Jonathan Lennox, Lisa Lippert, Robert Lusardi, David Madeo, 5776 Bob Mahoney, Murata Makoto, Gary McGath, Libby Miller, Steve Miller, 5777 Bob Morgan, David Nicol, David Nusbaum, Pete O'Leary, Mark Paterson, 5778 Ralph Patterson, Eric R. Plamondon, Robert Ransdell, Jim Ray, 5779 Marshall Rose, JP Rosevear, Paul Sharpe, Richard Shusterman, Tony 5780 Small, John Smith, Benjamin Sonntag, John Stracke, Preston 5781 Stephenson, Alexander Taler, Peter Thompson, Steve Vinter, Mark Wahl, 5782 Dan Winship 5784 Appendix B. Bibliography 5786 [BEEP] Rose, M., "The Block Extensible Exchange Protocol Core", 5787 RFC 3080, March 2001 5788 ftp://ftp.isi.edu/in-notes/rfc3080.txt 5790 [BEEPTCP] Rose, M., "Mapping the BEEP Core onto TCP", RFC 3081, March 2001 5791 ftp://ftp.isi.edu/in-notes/rfc3081.txt 5793 [CHARREG] Freed, N., Postel, J., "IANA Charset Registration Procedures", 5794 RFC 2278, January 1998, 5795 ftp://ftp.isi.edu/in-notes/rfc2278.txt 5797 [CHARPOL] Alvestrand, H., "IETF Policy on Character Sets and Languages", 5798 RFC 2277, January 1998, 5799 ftp://ftp.isi.edu/in-notes/rfc2277.txt 5801 [GUIDE] Mahoney, B., Babics, G., Taler, A. "Guide to Internet 5802 Calendaring", RFC 3283, June 2002, 5803 ftp://ftp.isi.edu/in-notes/rfc3283.txt 5805 [iCAL] Dawson, F. and Stenerson, D., "Internet Calendaring and 5806 Scheduling Core Object Specification (iCalendar)", RFC 2445, 5807 November 1998 ftp://ftp.isi.edu/in-notes/rfc2445.txt 5809 [iTIP] Silverberg, S., Mansour, S., Dawson, F. and Hopson, R., 5810 "iCalendar Transport-Independent Interoperability Protocol 5811 (iTIP) Events, BusyTime, To-dos and Journal Entries", 5812 RFC 2446, November 1998 ftp://ftp.isi.edu/in-notes/rfc2446.txt 5814 [iMIP] Dawson, F., Mansour, S. and Silverberg, "iCalendar 5815 Message-Based Interoperability Protocol (iMIP)", RFC 2447, 5816 November 1998 ftp://ftp.isi.edu/in-notes/rfc2447.txt 5818 [MIME] Borenstein, N. and Freed, N., "Multipurpose Internet Mail 5819 Extensions (MIME) Part One: Format of Internet Message Bodies", 5820 RFC 2045, November 1996 5821 ftp://ftp.isi.edu/in-notes/rfc2045.txt 5823 [RFCWORDS] Bradner, S., "Key words for use in RFCs to Indicate 5824 Requirement Levels", RFC 2119, BCP 14, March 1997 5825 ftp://ftp.isi.edu/in-notes/rfc2119.txt 5827 [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", 5828 RFC 2222, October 1997 5829 ftp://ftp.isi.edu/in-notes/rfc2222.txt 5831 [SQL92] "Database Language SQL", ANSI/ISO/IEC 9075: 1992, 5832 aka ANSI X3.135-1992, aka FiPS PUB 127-2 5834 [SQLCOM] ANSI/ISO/IEC 9075:1992/TC-1-1995, Technical corrigendum 1 5835 to ISO/IEC 9075: 1992, also adopted as Amendment 1 to 5836 ANSI X3.135.1992 5838 [URLGUIDE] Masinter, L., Alvestrand, H., Zigmond, D., Petke, R., 5839 "Guidelines for new URL Schemes", RFC 2718, November 1999, 5840 ftp://ftp.isi.edu/in-notes/rfc2718.txt 5842 [URI] Berners-Lee, T., Fielding, R. and Masinter, L., "Uniform Resource 5843 Identifiers (URI): Generic Syntax", RFC 2396, August 1998 5844 ftp://ftp.isi.edu/in-notes/rfc2396.txt 5846 [URL] Berners-Lee, T, Masinter, L. and McCahil, M., "Uniform 5847 Resource Locators (URL)", RFC 1738, December 1994 5848 ftp://ftp.isi.edu/in-notes/rfc1738.txt 5850 [X509CRL] Housley, R., Ford, W., Polk, W., Solo, D. "Internet X.509 5851 Public Key Infrastructure, Certificate and CRL Profile", 5852 RFC 2459, January 1999, 5853 ftp://ftp.isi.edu/in-notes/rfc2459.txt 5855 Intellectual Property Statement 5857 The IETF takes no position regarding the validity or scope of any 5858 intellectual property or other rights that might be claimed to 5859 pertain to the implementation or use of the technology described in 5860 this document or the extent to which any license under such rights 5861 might or might not be available; neither does it represent that it 5862 has made any effort to identify any such rights. Information on the 5863 IETF's procedures with respect to rights in standards-track and 5864 standards-related documentation can be found in BCP-11. Copies of 5865 claims of rights made available for publication and any assurances of 5866 licenses to be made available, or the result of an attempt made to 5867 obtain a general license or permission for the use of such 5868 proprietary rights by implementors or users of this specification can 5869 be obtained from the IETF Secretariat. 5871 The IETF invites any interested party to bring to its attention any 5872 copyrights, patents or patent applications, or other proprietary 5873 rights which may cover technology that may be required to practice 5874 this standard. Please address the information to the IETF Executive 5875 Director. 5877 Full Copyright Statement 5879 Copyright (C) The Internet Society (2004). All Rights Reserved. 5881 This document and translations of it may be copied and furnished to 5882 others, and derivative works that comment on or otherwise explain it 5883 or assist in its implementation may be prepared, copied, published 5884 and distributed, in whole or in part, without restriction of any 5885 kind, provided that the above copyright notice and this paragraph are 5886 included on all such copies and derivative works. However, this 5887 document itself may not be modified in any way, such as by removing 5888 the copyright notice or references to the Internet Society or other 5889 Internet organizations, except as needed for the purpose of 5890 developing Internet standards in which case the procedures for 5891 copyrights defined in the Internet Standards process must be 5892 followed, or as required to translate it into languages other than 5893 English. 5895 The limited permissions granted above are perpetual and will not be 5896 revoked by the Internet Society or its successors or assignees. 5898 This document and the information contained herein is provided on an 5899 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 5900 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 5901 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 5902 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 5903 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 5905 Acknowledgment 5907 Funding for the RFC Editor function is currently provided by the 5908 Internet Society.