idnits 2.17.1 draft-ietf-calsch-cap-11.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 110 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,...' (228 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 1868 has weird spacing: '...roperty woul...' == Line 1918 has weird spacing: '...mponent match...' == Line 1938 has weird spacing: '... know if "u...' == Line 2052 has weird spacing: '...alm. In it's ...' == (5 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 (July 27, 2003) is 7579 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 5574 looks like a reference -- Missing reference section? 'BEEP' on line 5643 looks like a reference -- Missing reference section? 'RFCWORDS' on line 5680 looks like a reference -- Missing reference section? 'GUIDE' on line 5658 looks like a reference -- Missing reference section? 'URL' on line 5703 looks like a reference -- Missing reference section? 'URI' on line 5699 looks like a reference -- Missing reference section? 'URLGUIDE' on line 5695 looks like a reference -- Missing reference section? 'MIME' on line 5675 looks like a reference -- Missing reference section? 'CAP' on line 1286 looks like a reference -- Missing reference section? 'BEEPTCP' on line 5647 looks like a reference -- Missing reference section? 'X509CRL' on line 5707 looks like a reference -- Missing reference section? 'SQL92' on line 5688 looks like a reference -- Missing reference section? 'SQLCOM' on line 5691 looks like a reference -- Missing reference section? 'NOT' on line 1845 looks like a reference -- Missing reference section? 'CHARREG' on line 5650 looks like a reference -- Missing reference section? 'CHARPOL' on line 5654 looks like a reference -- Missing reference section? 'SASL' on line 5684 looks like a reference Summary: 5 errors (**), 0 flaws (~~), 11 warnings (==), 20 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Calendaring and Scheduling D. Royer 3 Internet-Draft INET-Consulting 4 Expires: January 25, 2004 G. Babics 5 Oracle 6 P. Hill 7 Massachusetts Institute of 8 Technology 9 S. Mansour 10 AOL/Netscape 11 July 27, 2003 13 Calendar Access Protocol (CAP) 14 draft-ietf-calsch-cap-11.txt 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 January 25, 2004. 38 Copyright Notice 40 Copyright (C) The Internet Society (2003). 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 . . . . . . . . . . . . . . . . . . . . . . . . 21 70 3.1 System Model . . . . . . . . . . . . . . . . . . . . . . . 21 71 3.2 Calendar Store Object Model . . . . . . . . . . . . . . . 21 72 3.3 Protocol Model . . . . . . . . . . . . . . . . . . . . . . 22 73 3.3.1 Use of BEEP, MIME and iCalendar . . . . . . . . . . . . . 23 74 4. Security Model . . . . . . . . . . . . . . . . . . . . . . 25 75 4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . . . 25 76 4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . . . 25 77 4.1.2 Anonymous Users and Authentication . . . . . . . . . . . . 26 78 4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . . . 26 79 4.2 Access Rights . . . . . . . . . . . . . . . . . . . . . . 27 80 4.2.1 Access Control and NOCONFLICT . . . . . . . . . . . . . . 27 81 4.2.2 Predefined VCARs . . . . . . . . . . . . . . . . . . . . . 27 82 4.2.3 Decreed VCARs . . . . . . . . . . . . . . . . . . . . . . 29 83 4.3 CAP Session Identity . . . . . . . . . . . . . . . . . . . 30 84 5. CAP URL and Calendar Address . . . . . . . . . . . . . . . 32 85 6. New Value Types . . . . . . . . . . . . . . . . . . . . . 34 86 6.1 Property Value Data Types . . . . . . . . . . . . . . . . 34 87 6.1.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . . . . 34 88 6.1.2 UPN Value Type . . . . . . . . . . . . . . . . . . . . . . 49 89 6.1.3 UPN-FILTER Value . . . . . . . . . . . . . . . . . . . . . 50 90 7. New Parameters . . . . . . . . . . . . . . . . . . . . . . 53 91 7.1 ACTION Parameter . . . . . . . . . . . . . . . . . . . . . 53 92 7.2 ENABLE Parameter . . . . . . . . . . . . . . . . . . . . . 53 93 7.3 ID Parameter . . . . . . . . . . . . . . . . . . . . . . . 54 94 7.4 LATENCY Parameter . . . . . . . . . . . . . . . . . . . . 55 95 7.5 LOCAL Parameter . . . . . . . . . . . . . . . . . . . . . 56 96 7.6 LOCALIZE Parameter . . . . . . . . . . . . . . . . . . . . 56 97 7.7 OPTIONS Parameter . . . . . . . . . . . . . . . . . . . . 57 98 8. New Properties . . . . . . . . . . . . . . . . . . . . . . 59 99 8.1 ALLOW-CONFLICT Property . . . . . . . . . . . . . . . . . 59 100 8.2 ATT-COUNTER Property . . . . . . . . . . . . . . . . . . . 59 101 8.3 CALID Property . . . . . . . . . . . . . . . . . . . . . . 60 102 8.4 CALMASTER Property . . . . . . . . . . . . . . . . . . . . 61 103 8.5 CAP-VERSION Property . . . . . . . . . . . . . . . . . . . 61 104 8.6 CARID Property . . . . . . . . . . . . . . . . . . . . . . 62 105 8.7 CAR-LEVEL Property . . . . . . . . . . . . . . . . . . . . 62 106 8.8 COMPONENTS Property . . . . . . . . . . . . . . . . . . . 63 107 8.9 CSID Property . . . . . . . . . . . . . . . . . . . . . . 65 108 8.10 DECREED Property . . . . . . . . . . . . . . . . . . . . . 65 109 8.11 DEFAULT-CHARSET Property . . . . . . . . . . . . . . . . . 66 110 8.12 DEFAULT-LOCALE Property . . . . . . . . . . . . . . . . . 67 111 8.13 DEFAULT-TZID Property . . . . . . . . . . . . . . . . . . 68 112 8.14 DEFAULT-VCARS Property . . . . . . . . . . . . . . . . . . 69 113 8.15 DENY Property . . . . . . . . . . . . . . . . . . . . . . 70 114 8.16 EXPAND property . . . . . . . . . . . . . . . . . . . . . 70 115 8.17 GRANT Property . . . . . . . . . . . . . . . . . . . . . . 71 116 8.18 ITIP-VERSION Property . . . . . . . . . . . . . . . . . . 72 117 8.19 MAX-COMP-SIZE Property . . . . . . . . . . . . . . . . . . 72 118 8.20 MAXDATE Property . . . . . . . . . . . . . . . . . . . . . 73 119 8.21 MINDATE Property . . . . . . . . . . . . . . . . . . . . . 74 120 8.22 MULTIPART Property . . . . . . . . . . . . . . . . . . . . 74 121 8.23 NAME Property . . . . . . . . . . . . . . . . . . . . . . 75 122 8.24 OWNER Property . . . . . . . . . . . . . . . . . . . . . . 76 123 8.25 PERMISSION Property . . . . . . . . . . . . . . . . . . . 76 124 8.26 QUERY property . . . . . . . . . . . . . . . . . . . . . . 77 125 8.27 QUERYID property . . . . . . . . . . . . . . . . . . . . . 78 126 8.28 REQUEST-STATUS property . . . . . . . . . . . . . . . . . 78 127 8.29 QUERY-LEVEL Property . . . . . . . . . . . . . . . . . . . 79 128 8.30 RECUR-ACCEPTED Property . . . . . . . . . . . . . . . . . 80 129 8.31 RECUR-LIMIT Property . . . . . . . . . . . . . . . . . . . 81 130 8.32 RECUR-EXPAND Property . . . . . . . . . . . . . . . . . . 82 131 8.33 RESTRICTION Property . . . . . . . . . . . . . . . . . . . 82 132 8.34 SCOPE Property . . . . . . . . . . . . . . . . . . . . . . 83 133 8.35 STORES-EXPANDED Property . . . . . . . . . . . . . . . . . 84 134 8.36 TARGET Property . . . . . . . . . . . . . . . . . . . . . 85 135 8.37 TRANSP Property . . . . . . . . . . . . . . . . . . . . . 85 136 9. New Components . . . . . . . . . . . . . . . . . . . . . . 87 137 9.1 VAGENDA Component . . . . . . . . . . . . . . . . . . . . 87 138 9.2 VCALSTORE Component . . . . . . . . . . . . . . . . . . . 89 139 9.3 VCAR Component . . . . . . . . . . . . . . . . . . . . . . 90 140 9.4 VRIGHT Component . . . . . . . . . . . . . . . . . . . . . 93 141 9.5 VREPLY Component . . . . . . . . . . . . . . . . . . . . . 94 142 9.6 VQUERY Component . . . . . . . . . . . . . . . . . . . . . 94 143 10. Commands and Responses . . . . . . . . . . . . . . . . . . 96 144 10.1 CAP Commands (CMD) . . . . . . . . . . . . . . . . . . . . 96 145 10.1.1 Bounded Latency . . . . . . . . . . . . . . . . . . . . . 97 146 10.1.2 ABORT Command . . . . . . . . . . . . . . . . . . . . . . 99 147 10.1.3 CONTINUE Command . . . . . . . . . . . . . . . . . . . . . 100 148 10.1.4 CREATE Command . . . . . . . . . . . . . . . . . . . . . . 101 149 10.1.5 DELETE Command . . . . . . . . . . . . . . . . . . . . . . 106 150 10.2 GENERATE-UID Command . . . . . . . . . . . . . . . . . . . 109 151 10.3 GET-CAPABILITY Command . . . . . . . . . . . . . . . . . . 111 152 10.4 IDENTIFY Command . . . . . . . . . . . . . . . . . . . . . 113 153 10.5 MODIFY Command . . . . . . . . . . . . . . . . . . . . . . 116 154 10.6 MOVE Command . . . . . . . . . . . . . . . . . . . . . . . 120 155 10.7 REPLY Response to a Command . . . . . . . . . . . . . . . 122 156 10.8 SEARCH Command . . . . . . . . . . . . . . . . . . . . . . 123 157 10.8.1 Searching for VFREEBUSY . . . . . . . . . . . . . . . . . 126 158 10.9 SET-LOCALE Command . . . . . . . . . . . . . . . . . . . . 127 159 10.10 TIMEOUT Command . . . . . . . . . . . . . . . . . . . . . 128 160 10.11 Response Codes . . . . . . . . . . . . . . . . . . . . . . 129 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 . . . . . . . . . . . . . . . . . . . 132 169 13. IANA Considerations . . . . . . . . . . . . . . . . . . . 133 170 14. Security Considerations . . . . . . . . . . . . . . . . . 134 171 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 135 172 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 137 173 B. Bibliography . . . . . . . . . . . . . . . . . . . . . . . 138 174 Intellectual Property and Copyright Statements . . . . . . 140 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 defined 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. The " 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 SEQUENCE - When the "SEQUENCE" parameter is used in a "VALARM" 616 component it uniquely identifies the instances of the "VALARM" 617 within that component. 619 2.1.2 New Properties (summary) 621 ALLOW-CONFLICT - Some entries in a calendar might not be valid if 622 other entries were allowed to overlap the same time span. (Section 623 8.1) 625 ATT-COUNTER - When storing a "METHOD" property with the "COUNTER" 626 method, there needs to be a way to remember the "ATTENDEE" value 627 that sent the COUNTER. (Section 8.2) 629 CAP-VERSION - The version of CAP the implementation supports. 630 (Section 8.5) 632 CAR-LEVEL - The level of calendar access level supported. (Section 633 8.7) 635 COMPONENTS - The list of components supported. (Section 8.8) 637 CSID - The Calendar Store IDentifier (CSID) uniquely identifies a 638 CAP server. (Section 8.9) 640 CALID - Each calendar within a CS needs to be uniquely identifiable. 641 The "CALID" property identifies a unique calendar within a CS. It 642 can be a full CALID or a relative CALID. (Section 8.3) 644 CALMASTER - The "CALMASTER" property specifies the contact 645 information for the CS. (Section 8.4) 647 CARID - Access rights can be saved and fetched by unique ID - the 648 "CARID" property. (Section 8.6) 650 CMD - The CAP commands, as well as replies are transmitted using the 651 "CMD" property. (Section 10.1) 653 DECREED - Some access rights are not changeable by the CUA. When 654 that is the case, the "DECREED" property value in the "VCAR" 655 component will be TRUE. (Section 8.10) 657 DEFAULT-CHARSET - The list of charsets supported by the CS. The 658 first entry is the default for the CS. (Section 8.11) 660 DEFAULT-LOCALE - The list of locales supported by the CS. The first 661 entry in the list is the default locale. (Section 8.12) 663 DEFAULT-TZID - This is the list of known timezones supported. The 664 first entry is the default. (Section 8.13) 666 DEFAULT-VCARS - A list of the "CARID" properties that will be used 667 to create new calendars. (Section 8.14) 669 DENY - The UPNs listed in the "DENY" property of a "VCAR" component 670 will denied access as described in the "VRIGHT" component. 671 (Section 8.15) 673 EXPAND - This property tells the CS if the query reply should expand 674 components into multiple instances. The default is FALSE and is 675 ignored for CSs that can not expand recurrence rules. (Section 676 8.16) 678 GRANT - The UPNs listed in the "GRANT" property of a "VCAR" 679 component will allowed access as described in the "VRIGHT" 680 component. (Section 8.17) 682 ITIP-VERSION - The version of [iTIP] supported. (Section 8.18) 684 MAXDATE - The maximum date supported by the CS. (Section 8.20) 686 MAX-COMP-SIZE - The largest component size allowed in the 687 implementation including attachments in octets. (Section 8.19) 689 MINDATE - The minimum date supported by the CS. (Section 8.21) 691 MULTIPART - Passed in the capability messages to indicate which MIME 692 multipart types the sender supports. (Section 8.22) 694 NAME - The "NAME" property is used to add locale specific 695 descriptions into components. (Section 8.23) 697 OWNER - Each calendar has at least one "OWNER" property. (xref 698 target="OWNER"/>) Related to the "CAL-OWNERS()" (Section 6.1.1.1) 699 query clause. 701 PERMISSION - This property specifies the permission being granted or 702 denied. Examples are the "SEARCH" and "MODIFY" values. (Section 703 8.25) 705 QUERY - Used to hold the CAL-QUERY (Section 8.26) for the component. 707 QUERYID - A unique id for a stored query. (Section 8.27) 709 QUERY-LEVEL - The level of the query language supported. (Section 710 8.29) 712 RECUR-ACCEPTED - If the implementation support recurrence rules. 713 (Section 8.30) 715 RECUR-EXPAND - If the implementation support expanding recurrence 716 rules. (Section 8.32) 718 RECUR-LIMIT - Any maximum limit on the number of instances the 719 implementation will expand recurring objects. (Section 8.31) 721 REQUEST-STATUS - The [iCAL] "REQUEST-STATUS" property is extended to 722 include new error numbers. (Section 8.28) 724 RESTRICTION - In the final check when granting calendar access 725 requests, the CS test the results to the value of the 726 "RESTRICTION" property in the corresponding "VRIGHT" component to 727 determine if the access meets that restriction. (Section 8.33) 729 SCOPE - The "SCOPE" property is used in "VRIGHT"s component to 730 select the subset of data that may be acted upon when checking 731 access rights. (Section 8.34) 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 and are as define in [iTIP]. This memo 783 makes no changes to any of the methods or procedures described in 784 [iTIP]. In this memo referring to the presence of the "METHOD" 785 property in an 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 Perform an [iTIP] processing such as sending back a decline. Then 820 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 receive 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 is 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 supplied in the [BEEP] 'localize' attribute 935 is the 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.1.2) 984 CONTINUE - Sent to continue processing a command that has had its 985 specified timeout time reached. (Section 10.1.3) 987 CREATE - Create a new object on the CS. This can be implied for 988 [iTIP] objects. Initiated by the CUA only. (Section 10.1.4) 990 SET-LOCALE - Tell the CS to use any named locale and charset 991 supplied. Initiated by the CUA only. (Section 10.9) 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.1.5) 996 GENERATE-UID - Generate one or more unique ids. Initiated by the CUA 997 only. (Section 10.2) 999 GET-CAPABILITY - Query the capabilities the other end point of the 1000 session. (Section 10.3) 1002 IDENTIFY - Set a new identity for the session. Initiated by the CUA 1003 only. (Section 10.4) 1005 MODIFY - Modify components. Initiated by the CUA only. (Section 1006 10.5) 1008 MOVE - Move components to another container. Initiated by the CUA 1009 only. (Section 10.6) 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.7) 1015 SEARCH - Search for components. Initiated by the CUA only. (Section 1016 10.8) 1018 TIMEOUT - Sent when a specified amount of time has lapsed and a 1019 command has not finished. (Section 10.10) 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. It may refer to the calendar of a user or of a 1313 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 Relative CAP URLs are permitted and are resolved according to the 1323 rules 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 return 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 in the "WHERE" clause it then returns true if the 1635 currently authenticated UPN is an owner of the currently selected 1636 object 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 6.1.1.6 Use of single quote 1725 All literal values are surrounded by single quotes ('), not double 1726 quotes ("), and not without any quotes. If the value contains quotes 1727 or any other ESCAPED-CHAR, they MUST BE backslash escaped as 1728 described in section 4.3.11 "Text" of [iCAL]. Any "LIKE" clause 1729 wildcard characters that are part of any literal data that is 1730 preceded by a "LIKE" clause or "NOT LIKE" clause and is not intended 1731 to mean wildcard search MUST BE escaped. 1733 6.1.1.7 Comparing DATE and DATE-TIME values 1735 When comparing "DATE-TIME" values to "DATE" values and when comparing 1736 "DATE" values to "DATE-TIME" values, the result will be true if the 1737 "DATE" value is on the same day as the "DATE-TIME" value. And they 1738 are compared in UTC no matter what time zone the data may actual have 1739 been stored in. 1741 Local time event as descibed in section 4.2.19 of [iCAL] must be 1742 considered to be in the CUA default timezone that was supplied by the 1743 CUA in the "CAPABILITY" exchange. 1745 VALUE-1 VALUE-2 Compare Results 1747 20020304 20020304T123456 TRUE 1748 (in UTC-3) (in UTC-3) 1750 20020304 20020304T003456 FALSE 1751 (in UTC) (in UTC-4) 1752 20020304T003456Z 20020205T003456 FALSE 1753 (in UTC-0) (in UTC-7) 1755 When comparing "DATE" values and "DATE-TIME" values with the "LIKE" 1756 clause the comparison will be done as if the value is a [iCAL] DATE 1757 or DATE-TIME string value. 1759 LIKE '2002%' will match anything in the year 2002. 1761 LIKE '200201%' will match anything in January 2002. 1763 LIKE '%T000000' will match anything at midnight. 1765 LIKE '____01__T%' will match anything for any year or 1766 time that is in January. 1767 (Four '_', '01', two '_' 'T%'). 1769 Using a "LIKE" clause value of "%00%, would return any value that 1770 contained two consecutive zeros. 1772 All comparisons will be done in UTC. 1774 6.1.1.8 DTEND and DURATION 1776 The "DTEND" property value is not included in the time occupied by 1777 the component. That is a "DTEND" property value of 20030614T12000 1778 includes all of the time up to but not including noon on that day. 1780 The "DURATION" property value end time is also not inclusive. So an 1781 object with a "DTSTART" property value of 20030514T110000 and a 1782 "DURATION" property value of "1H" does not include noon on that day. 1784 When a "QUERY" property value contains a "DTEND" value, then the CS 1785 MUST also evaluate any existing "DURATION" property value and 1786 determine if it has an effective end time that matches the "QUERY" 1787 property supplied "DTEND" value or any range of values supplied by 1788 the "QUERY" property. 1790 When a "QUERY" property contains a "DURATION" value, then the CS MUST 1791 also evaluate any existing "DTEND" property values and determine if 1792 they have an effective duration that matches the "QUERY" property 1793 value supplied "DURATION" value or any range of values supplied by 1794 the "QUERY" property. 1796 6.1.1.9 [NOT] LIKE 1798 The pattern matching characters are the '%' that matches zero or more 1799 characters, and '_' that matches exactly one character (where 1800 character does not always mean octet). 1802 "LIKE" clause pattern matches always cover the entire string. To 1803 match a pattern anywhere within a string, the pattern must start and 1804 end with a percent sign. 1806 To match a '%' or '_' in the data and not have it interpreted as a 1807 wildcard character, they MUST BE backslash escaped. That is to search 1808 for a '%' or '_' in the string: 1810 LIKE '%\%%' Matches any string with a '%' in it. 1811 LIKE '%\_%' Matches any string with a '_' in it. 1813 Strings compared using the "LIKE" clause MUST BE performed using case 1814 in-sensitive comparisons when the locale allows. (Example: in 1815 US-ASCII the compare assumes 'a' = 'A'). 1817 If the "LIKE" clause is preceded by 'NOT' then there is a match when 1818 the string compare fails. 1820 Some property values (such as the 'recur' value type), contain commas 1821 and are not multi valued. The CS must understand the objects being 1822 compared and understand how to determine how any multi valued or 1823 multi instances properties or parameter values are separated, quoted, 1824 and backslash escaped and perform the comparisons as if each value 1825 existed by itself and not quoted or backslash escaped when comparing 1826 using the LIKE element. 1828 See related examples in Section 6.1.1.11 1830 6.1.1.10 Empty vs. NULL 1832 When used in a CAL-QUERY value, "NULL" means that the property or 1833 parameter is not present in the object. Paramaters that are not 1834 provided and have a default value in the property are considered to 1835 exist with their default value and will not be "NULL". 1837 If the property exists but has no value then "NULL" MUST NOT match. 1838 If the parameter exists but has no value then "NULL" MUST NOT match. 1839 If the parameter not present and has a default value then "NULL" MUST 1840 NOT match. 1842 If the property (or parameter) exists, but has no value then it 1843 matches the empty string '' (quote quote). 1845 6.1.1.11 [NOT] IN 1847 This is similar to the "LIKE" clause, except it does value matching 1848 and not string comparison matches. 1850 Some iCalendar objects can be multi instance and multi valued. The 1851 "IN" clause will return a match if the literal value supplied as part 1852 of the "IN" clause is contained in the value of any instance of the 1853 named property or parameter, or is in any of the multiple values in 1854 the named property or parameter. Unlike the "LIKE" clause, the '%' 1855 and '_' matching characters are not used with the "IN" clause and 1856 have no special meaning. 1858 BEGIN:A-COMPONENT 1859 a property:value1,value2 One property, two values. 1860 b property:"value1,value2" One property, one value. 1861 c property:parameter=1,2:x One parameter, two values. 1862 d property:parameter="1,2",3:y One parameter, one value. 1863 e property:parameter=",":z One parameter, one value. 1864 f property:x,y,z One property, three values 1865 END:A-COMPONENT 1867 'value1' IN property would match (a) only. 1868 'value1,value2' IN property would match (b) only. 1869 'value%' IN property would NOT match any. 1870 ',' IN property would NOT match any. 1871 '%,%' IN property would NOT match any. 1872 'x' IN property would match (f) and (c). 1873 '2' IN parameter would match (c) only. 1874 '1,2' IN parameter would match (d) only. 1875 ',' IN parameter would match (e) only. 1876 '%,%' IN parameter would NOT match any. 1878 property LIKE 'value1%' would match (a) and (b). 1879 property LIKE 'value%' would match (a) and (b). 1880 property LIKE 'x' would match (f) and (c). 1881 parameter LIKE '1%' would match (c) and (d). 1882 parameter LIKE '%2%' would match (c) and (d). 1883 parameter LIKE ',' would match (e) only. 1885 Some property values (such as the "RECUR" value type), contain commas 1886 and are not multi valued. The CS must understand the objects being 1887 compared and understand how to determine how any multi valued or 1888 multi instances properties or parameter values are separated, quoted, 1889 and backslash escaped and perform the comparisons as if each value 1890 existed by itself and not quoted or backslash escaped when comparing 1891 using the IN element. 1893 If the "IN" clause is preceded by 'NOT' then there is a match when 1894 the value does not exist in the property or parameter value. 1896 6.1.1.12 DATE-TIME and TIME values in a WHEN clause 1898 All "DATE-TIME" and "TIME" literal values supplied in a "WHEN" clause 1899 MUST BE terminated with 'Z'. That means that the CUA MUST supply the 1900 values in UTC. 1902 Valid: 1904 WHERE alarm.TRIGGER < '20020201T000000Z' 1905 AND alarm.TRIGGER > '20020101T000000Z' 1907 Not valid and it is a syntax error and the CS MUST reject the QUERY. 1909 WHERE alarm.TRIGGER < '20020201T000000' 1910 AND alarm.TRIGGER > '20020101T000000' 1912 6.1.1.13 Multiple contained components 1914 All comparisons MUST BE done from the same instance of a contained 1915 component or property and repeated for each instance. As in the 1916 following example that uses a "VALARM" component contained in a 1917 "VEVENT" component . If any instance of a "VALARM" component in any 1918 "VEVENT" component matches the query and the rest of the query is 1919 satisfied, then the "UID", "SUMMARY", and "DESCRIPTION" properties 1920 from all "VEVENT" components will be returned. If there were two 1921 "VALARM" components in a "VEVENT" component, then both "VALARM" 1922 components are tested and in this example only when the "VEVENT" 1923 component state is booked: 1925 BEGIN:VQUERY 1926 EXPAND:TRUE 1927 QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT 1928 WHERE VALARM.TRIGGER >= '20000101T030405Z' 1929 AND VALARM.TRIGGER <= '20001231T235959Z' 1930 AND STATE() = 'BOOKED' 1931 END:VQUERY 1933 6.1.1.14 Example, Query by UID 1935 The following example would match the entire content of a "VEVENT" or 1936 "VTODO" component with the "UID" property equal to "uid123" and not 1937 expand any multiple instances of the component. If the CUA does not 1938 know if "uid123" was a "VEVENT", "VTODO", "VJOURNAL", or any other 1939 component, then all components that the CUA supports MUST BE supplied 1940 in a QUERY property. This example assumes the CUA is only interested 1941 in "VTODO" and "VEVENT" components. 1943 If the results were empty it could also mean that "uid123" was a 1944 property in a component other than a VTODO or VEVENT. 1946 BEGIN:VQUERY 1947 QUERY:SELECT * FROM VTODO WHERE UID = 'uid123' 1948 QUERY:SELECT * FROM VEVENT WHERE UID = 'uid123' 1949 END:VQUERY 1951 6.1.1.15 Query by Date-Time range 1953 This query selects the entire content of every booked "VEVENT" 1954 component that has an instance greater than or equal to July 1st, 1955 2000 00:00:00 UTC and less than or equal to July 31st, 2000 23:59:59 1956 UTC. This includes single instance "VEVENT" components that do no 1957 explicitly contain any recurence properties or "RECURRENCE-ID" 1958 properties. This works only for CSs that have the "RECUR-EXPAND" 1959 property value set to "TRUE" in the "CAPABILITY" exchange. 1961 BEGIN:VQUERY 1962 EXPAND:TRUE 1963 QUERY:SELECT * FROM VEVENT 1964 WHERE RECURRENCE-ID >= '20000801T000000Z' 1965 AND RECURRENCE-ID <= '20000831T235959Z' 1966 AND STATE() = 'BOOKED' 1967 END:VQUERY 1969 6.1.1.16 Query for all Unprocessed Entries 1971 The following example selects the entire contents of all non-booked 1972 "VTODO" and "VEVENT" components in the "UNPROCESSED" state. The 1973 default for the "EXPAND" property is FALSE, so the recurrence rules 1974 will not be expanded. 1976 BEGIN:VQUERY 1977 QUERYID:Fetch VEVENT and VTODO iTIP components 1978 QUERY:SELECT * FROM VEVENT WHERE STATE() = 'UNPROCESSED' 1979 QUERY:SELECT * FROM VTODO WHERE STATE() = 'UNPROCESSED' 1980 END:VQUERY 1982 The following example fetches all "VEVENT" and "VTODO" components in 1983 the "BOOKED" state. 1985 BEGIN:VQUERY 1986 QUERYID:Fetch All Booked VEVENT and VTODO components 1987 QUERY:SELECT * FROM VEVENT WHERE STATE() = 'BOOKED' 1988 QUERY:SELECT * FROM VTODO WHERE STATE() = 'BOOKED' 1989 END:VQUERY 1991 The following fetches the "UID" property for all "VEVENT" and "VTODO" 1992 components that have been marked for delete. 1994 BEGIN:VQUERY 1995 QUERYID:Fetch UIDs of marked for delete VEVENTs and VTODOs 1996 QUERY:SELECT UID FROM VEVENT WHERE STATE() = 'DELETE' 1997 QUERY:SELECT UID FROM VTODO WHERE STATE() = 'DELETE' 1998 END:VQUERY 2000 6.1.1.17 Query with Subset of Properties by Date/Time 2002 In this example only the named properties will be selected and all 2003 booked and non-booked components will be selected that have a 2004 "DTSTART" value from February 1st to February 10th 2000 (in UTC). 2006 BEGIN:VQUERY 2007 QUERY:SELECT UID,DTSTART,DESCRIPTION,SUMMARY FROM VEVENT 2008 WHERE DTSTART >= '20000201T000000Z' 2009 AND DTSTART <= '20000210T235959Z' 2010 END:VQUERY 2012 6.1.1.18 Query with Components and Alarms In A Range 2014 This example fetches all booked "VEVENT" components with an alarm 2015 that triggers within the specified time range. In this case only the 2016 "UID", "SUMMARY", and "DESCRIPTION" properties will be selected for 2017 all booked "VEVENTS" components that have an alarm between the two 2018 date-times supplied. 2020 BEGIN:VQUERY 2021 EXPAND:TRUE 2022 QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT 2023 WHERE VALARM.TRIGGER >= '20000101T030405Z' 2024 AND VALARM.TRIGGER <= '20001231T235959Z' 2025 AND STATE() = 'BOOKED' 2026 END:VQUERY 2028 6.1.2 UPN Value Type 2030 Value Name: UPN 2032 Purpose: This value type is used to identify values that contain user 2033 principal name of CU or group of CU. 2035 Formal Definition: The value type is defined by the following 2036 notation: 2038 upn = "@" 2039 / [ dot-atom-text ] "@" dot-atom-text 2041 ; dot-atom-text is defined in RFC 2822 2043 Description: This data type is an identifier that denotes a CU or a 2044 group of CU. A UPN is a RFC 2822 compliant email address, with 2045 exceptions listed below, and in most cases it is deliverable to the 2046 CU. In some cases it is identical to the CU's well known email 2047 address. A CU's UPN MUST never be an e-mail address that is 2048 deliverable to a different person as there is no requirement that a 2049 person's UPN MUST BE their e-mail address. A UPN is formatted as a 2050 user name followed by "@" followed by a Realm in the form of a valid, 2051 and unique, DNS domain name. The user name MUST BE unique within the 2052 Realm. In it's simplest form it looks like "user@example.com". 2054 In certain cases a UPN will not be RFC 2822 compliant. When anonymous 2055 authentication is used, or anonymous authorization is being defined, 2056 the special UPN "@" will be used. When authentication MUST BE used, 2057 but unique identity MUST BE obscured, a UPN of the form 2058 @DNS-domain-name may be used. For example, "@example.com". 2060 Example: 2062 The following is a UPN for a CU: 2064 jdoe@example.com 2066 The following is a example of a UPN that could be for a group of CU: 2068 staff@example.com 2070 The following is a UPN for an anonymous CU belonging to a specific 2071 realm or when used as a UPN-FILTER it specifies that it applies to 2072 all UPNs in a specific realm: 2074 @example.com 2076 The following is a UPN for an anonymous CU: 2078 @ 2080 6.1.3 UPN-FILTER Value 2082 Value Name: UPN-FILTER 2084 Purpose: This value type is used to identify values that contain a 2085 user principal name filter. 2087 Formal Definition: The value type is defined by the following 2088 notation: 2090 ; NOTE: "CAL-OWNERS(cal-address)" 2091 ; and "NOT CAL-OWNERS(cal-address)" 2092 ; are both NOT allowed below. 2093 ; 2094 upn-filter = "CAL-OWNERS()" / 2096 "NOT CAL-OWNERS()" / 2097 "*" / 2098 [ "*" / dot-atom-text ] "@" ( "*" / dot-atom-text ) 2100 ; dot-atom-text is defined in RFC 2822 2102 Description: The value is used to match user principal names (UPNs). 2103 For "CAL-OWNERS()" and "NOT CAL-OWNERS()", see Section 8.24. 2105 * Matches all UPNs. 2107 @ Matches the UPN of anonymous CUs 2108 belonging to the null realm 2110 @* Matches the UPN of anonymous CUs 2111 belonging to any non-null realm 2113 @realm Matches the UPN of anonymous CUs 2114 belonging to the specified realm. 2116 *@* Matches the UPN of non-anonymous CUs 2117 belonging to any non-null realm 2119 *@realm Matches the UPN of non-anonymous CUs 2120 belonging to the specified realm 2122 user@realm Matches the UPN of the specified CU 2123 belonging to the specified realm 2125 user@* Not allowed. 2127 user@ Not allowed. 2129 Example: The following are examples of this value type: 2131 DENY:NON CAL-OWNERS() 2132 DENY:@hackers.example.com 2133 DENY:*@hackers.example.com 2134 GRANT:sam@example.com 2136 7. New Parameters 2138 7.1 ACTION Parameter 2140 Parameter Name: ACTION 2142 Purpose: This parameter indicates the action to be taken when a 2143 timeout occurs. 2145 Value Type: TEXT 2147 Conformance: This property can be specified in the "CMD" property. 2149 When present in a "CMD" property the "ACTION" parameter specifies the 2150 action to be taken when the command timeout expires. 2152 Formal Definition: The parameter is defined by the following 2153 notation: 2155 action-param = ";" "ACTION" "=" ( "ASK" / "ABORT" ) 2156 ; If 'action-param' is supplied then 2157 ; 'latency-param' MUST BE supplied. 2159 Example: The following is an example of this parameter: 2161 CMD;LATENCY=10;ACTION=ASK:CREATE 2163 7.2 ENABLE Parameter 2165 Parameter Name: ENABLE 2167 Purpose: This parameter indicates whether or not the property should 2168 be ignored. Example if a "TRIGGER" property in a "VALARM" component 2169 should be ignored. 2171 Value Type: BOOLEAN 2173 Conformance: This property can be specified in the "TRIGGER" 2174 properties. 2176 Description: When a non owner sends an [iTIP] "REQUEST" to a calendar 2177 that object might contain a "VALARM" component. The owner may wish to 2178 have local control over their own CUA and when or how alarms are 2179 triggered. 2181 A CUA may add the "ENABLE" parameter to any "TRIGGER" property before 2182 booking the component. If the "ENABLE" parameter is set to "FALSE", 2183 then the alarm will be ignored by the CUA. If set to "TRUE", or if 2184 the "ENABLE" property is not in the "TRIGGER" property, the alarm is 2185 enabled. This parameter may not be known by pre-CAP implementations 2186 and should not be an issue as it conforms to an 'ianaparam' as 2187 defined in [iCAL]. 2189 Formal Definition: The property is defined by the following notation: 2191 enable-param = "ENABLE" "=" boolean 2193 Example: The following is an example of this property for a "VAGENDA" 2194 component: 2196 TRIGGER;ENABLE=FALSE;RELATED=END:PT5M 2198 7.3 ID Parameter 2200 Parameter Name: ID 2202 Purpose: When used in a "CMD" component provides a unique identifier. 2204 Value Type: TEXT 2206 Conformance: This parameter can be specified in the "CMD" property. 2208 Description: If there is more than one command sent then the "ID" 2209 parameter is used to uniquely identify the command. 2211 A CUA may add the "ID" parameter to any "CMD" property before sending 2212 the command. There must not be more than one outstanding command 2213 tagged with the same "ID" parameter value. 2215 Formal Definition: The property is defined by the following notation: 2217 id-param = ";" "ID" "=" unique-id 2218 ; The text value supplied is a unique value 2219 ; shared between the CUA and CS to uniquely 2220 ; identify the instance of command in the 2221 ; the current CUA session. The value has 2222 ; no meaning to other CUAs or other sessions. 2224 unique-id = ; text 2226 Example: The following is an example of this parameter component: 2228 CMD;UD=some-unique-value:CREATE 2230 7.4 LATENCY Parameter 2232 Parameter Name: LATENCY 2234 Purpose: This parameter indicates time in seconds for when a timeout 2235 occurs. 2237 Value Type: TEXT 2239 Conformance: This property can be specified in the "CMD" property. 2241 When present in a "CMD" property the "LATENCY" parameter specifies 2242 the time in sections when the command timeout expires. 2244 Formal Definition: The parameter is defined by the following 2245 notation: 2247 latency-param = ";" "LATENCY" "=" latency-sec 2248 ; The value supplied in the time in seconds. 2249 ; If 'latency-param' is supplied then 2250 ; 'action-param' MUST BE supplied. 2252 latency-sec = posint1 2254 ; Default is zero (0) meaning no timeout. 2256 Example: The following is an example of this parameter: 2258 CMD;LATENCY=10;ACTION=ASK:CREATE 2260 7.5 LOCAL Parameter 2262 Parameter Name: LOCAL 2264 Purpose: Indicates if the named component should be exported to any 2265 non-organizer calendar. 2267 Value Type: BOOLEAN 2269 Conformance: This parameter can be specified in the "SEQUENCE" 2270 properties in a "VALARM" component. 2272 Description: When a non owner sends an [iTIP] "REQUEST" to a calendar 2273 that object might contain a "VALARM" component. The owner may wish to 2274 have local control over their own CUA and when or how alarms are 2275 triggered. 2277 A CUA may add the "LOCAL" parameter to the "SEQUENCE" property before 2278 booking the component. If the "LOCAL" parameter is set to "FALSE", 2279 then the alarm MUST NOT be forwarded to any other calender. If set to 2280 "TRUE", or of the "LOCAL" property is not in the "SEQUENCE" property, 2281 the alarm is global. 2283 Formal Definition: The property is defined by the following notation: 2285 local-param = "LOCAL" "=" boolean 2287 Example: The following is an example of this parameter: 2289 SEQUENCE;LOCAL=TRUE:4 2291 7.6 LOCALIZE Parameter 2293 Parameter Name: LOCALIZE 2295 Purpose: If provided the "LOCALIZE" parameter specifies the desired 2296 language for error and warning messages. 2298 Value Type: TEXT 2300 Conformance: This parameter can be specified in the "CMD" properties. 2302 When the "LOCALIZE" parameter is supplied then its value MUST BE one 2303 of the values listed in the initial [BEEP] greeting 'localize' 2304 attribute. 2306 A CUA may add the "LOCAL" parameter to the "LOCALIZE" parameter to 2307 the "CMD" property to specify the language of any error or warning 2308 messages. 2310 Formal Definition: The property is defined by the following notation: 2312 localize-param = ";" "LOCALIZE" "=" beep-localize 2314 beep-localize = text ; As defined in [iCAL] 2315 ; The value supplied MUST BE one value from the initial 2316 ; [BEEP] greeting 'localize' attribute specifying 2317 ; the locale to use for error messages during 2318 ; this instance of the command sent. 2320 Example: The following is an example of this parameter: 2322 CMD;LOCALIZE=fr_CA:CREATE 2324 7.7 OPTIONS Parameter 2326 Parameter Name: OPTIONS 2328 Purpose: If provided the "OPTIONS" parameter specifies some "CMD" 2329 property specific options. 2331 Value Type: TEXT 2333 Conformance: This parameter can be specified in the "CMD" properties. 2335 A CUA adds the "OPTIONS" parameter to the "LOCALIZE" parameter to the 2336 "CMD" property when the command needs extra values. 2338 Formal Definition: The property is defined by the following notation: 2340 option-param = ";" "OPTIONS" "=" cmd-specific 2342 cmd-specific = ; The value supplied is dependent on the 2343 ; CMD value. See the specific CMDs for the 2344 ; correct values to use for each CMD. 2346 Example: The following is an example of this parameter: 2348 CMD;OPTIONS=10:GENERATE-UID 2350 8. New Properties 2352 8.1 ALLOW-CONFLICT Property 2354 Property Name: ALLOW-CONFLICT 2356 Purpose: This property indicates whether or not the calendar and CS 2357 supports component conflicts. That is, whether or not any of the 2358 components in the calendar can overlap. 2360 Value Type: BOOLEAN 2362 Property Parameters: Non-standard property parameters can be 2363 specified on this property. 2365 Conformance: This property can be specified in "VAGENDA" and 2366 "VCALSTORE" component. 2368 Description: This property is used to indicate whether components may 2369 conflict. That is, if their expanded instances may share the same 2370 time or overlap the same time periods. If it has a value of TRUE, 2371 then conflicts are allowed. If FALSE, the no two components may 2372 conflict. 2374 If FALSE in the "VCALSTORE" component, then all "VAGENDA" component 2375 "ALLOW-CONFLICT" property values MUST BE false in the CS. 2377 Formal Definition: The property is defined by the following notation: 2379 allow-conflict = "ALLOW-CONFLICT" other-params ":" boolean CRLF 2381 Example: The following is an example of this property for a "VAGENDA" 2382 component: 2384 ALLOW-CONFLICT:FALSE 2386 8.2 ATT-COUNTER Property 2388 Property Name: ATT-COUNTER 2390 Property Parameters: Non-standard property parameters can be 2391 specified on this property. 2393 Conformance: This property MUST be specified in an iCalendar object 2394 that specifies counter proposal to a group scheduled calendar entity. 2395 When storing a "METHOD" property with the "COUNTER" method, there 2396 needs to be a way to remember who sent the COUNTER. The ATT-COUNTER 2397 property MUST BE added to all "COUNTER" [iTIP] components by the CUA 2398 before storing in a CS. 2400 Description: This property is used to identify the CAL-ADDRESS of the 2401 entity that sent the "COUNTER" [iTIP] object. 2403 Formal Definition: The property is defined by the following notation: 2405 attcounter = "ATT-COUNTER" other-params ":" cal-address CRLF 2407 Examples: 2409 ATT-COUNTER:cap:example.com/Doug 2410 ATT-COUNTER:mailto:Doug@Example.com 2412 8.3 CALID Property 2414 Property Name: CALID 2416 Property Parameters: Non-standard property parameters can be 2417 specified on this property. 2419 Conformance: This property can be specified in the "VAGENDA" 2420 component. 2422 Description: This property is used to specify a fully qualified 2423 CALID. 2425 Formal Definition: The property is defined by the following notation: 2427 CALID = "CALID" other-params ":" calid CRLF 2429 Example: 2431 CALID:cap://cal.example.com/sdfifgty4321 2433 8.4 CALMASTER Property 2435 Property Name: CALMASTER 2437 Purpose: The property specifies an e-mail address of a person 2438 responsible for the calendar store. 2440 Value Type: URI 2442 Property Parameters: Non-standard property parameters can be 2443 specified on this property. 2445 Conformance: The property can be specified in a "VCALSTORE" 2446 component. 2448 Description: The parameter value SHOULD BE a MAILTO URI as defined in 2449 [URL]. It MUST BE a contact URI such as a MAILTO URI and not a home 2450 page or file URI that describes how to contact the calmasters. 2452 Formal Definition: The property is defined by the following notation: 2454 calmaster = "CALMASTER" other-params ":" uri CRLF 2456 uri = ; IANA registered uri as defined in [iCAL] 2458 Example: The following is an example of this property: 2460 CALMASTER:mailto:administrator@example.com 2462 8.5 CAP-VERSION Property 2464 Property Name: CAP-VERSION 2466 Purpose: This property specifies the version of CAP supported. 2468 Value Type: TEXT 2470 Property Parameters: Non-standard property parameters can be 2471 specified on this property. 2473 Conformance: This property is specified in the "VREPLY" component 2474 that is sent in response to a "GET-CAPABILITY" command. 2476 Description: This specifies the version of CAP that the endpoint 2477 supports. The list is a comma separated list of RFC numbers 2478 supported. The list MUST contain at least XXXX (NOTE 'XXXX' WILL BE 2479 REPLACED WITH THE RFC NUMBER OF THIS DOCUMENT). 2481 Formal Definition: The property is defined by the following notation: 2483 cap-version = "CAP-VERSION" other-params ":" text CRLF 2485 Example: The following are examples of this property: 2487 CAP-VERSION:XXXX 2489 8.6 CARID Property 2491 Property Name: CARID 2493 Purpose: This property specifies the identifier for an access right 2494 component. 2496 Value Type: TEXT 2498 Property Parameters: Non-standard property parameters can be 2499 specified on this property. 2501 Conformance: This property MUST BE specified once in a "VCAR" 2502 component. 2504 Description: This property is used in the "VCAR" component to specify 2505 an identifier. A "CARID" property value is unique per container. 2507 Formal Definition: The property is defined by the following notation: 2509 carid = "CARID" other-params ":" text CRLF 2511 Example: The following are examples of this property: 2513 CARID:xyzzy-007 2514 CARID:User Rights 2516 8.7 CAR-LEVEL Property 2518 Property Name: CAR-LEVEL 2519 Purpose: The property specifies the level of VCAR supported. 2521 Value Type: TEXT 2523 Property Parameters: Non-standard property parameters can be 2524 specified on this property. 2526 Conformance: The property can be specified in a "VREPLY" component 2527 that is sent in response to a "GET-CAPABILITY" command. 2529 Description: The value is one from a list of "CAR-NONE", "CAR-MIN", 2530 or "CAR-FULL-1". If "CAR-FULL-1" is supplied then "CAR-MIN" is also 2531 available. A "CAR-MIN" implementation only supported the 2532 "DEFAULT-VCARS" property values listed in the "VCALSTORE" component 2533 and a "CAR-MIN" implementation does not support the creation or 2534 modification of "VCAR" components from the CUA. 2536 Formal Definition: The property is defined by the following notation: 2538 car-level = "CAR-LEVEL" ":" other-params : car-level-values 2540 car-level-values = ( "CAR-NONE" / "CAR-MIN" / "CAR-FULL-1" 2541 / other-levels ) 2543 other-levels = ; Any name published in an RFC for a "CAR-LEVEL" 2544 ; property value. 2546 Example: The following is an example of this property: 2548 CAR-LEVEL:CAR-FULL-1 2550 8.8 COMPONENTS Property 2552 Property Name: COMPONENTS 2554 Purpose: The property specifies a the list of components supported by 2555 the endpoint. 2557 Value Type: TEXT 2559 Property Parameters: Non-standard property parameters can be 2560 specified on this property. 2562 Conformance: The property can be specified in a "VREPLY" component in 2563 response to a "GET-CAPABILITY" command. 2565 Description: A comma separated list of components supported by the 2566 endpoint. If not in the list sent from the endpoint then they are not 2567 supported by that endpoint. Sending an unsupported component results 2568 in unpredictable results. This includes any components inside of 2569 other components (VALARM for example). The recommended list is 2570 "VCALSTORE,VCALENDAR,VREPLY,VAGENDA, 2571 VEVENT,VALARM,VTIMEZONE,VJOURNAL,VTODO,VALARM 2572 DAYLIGHT,STANDARD,VCAR,VRIGHT,VQUERY" 2574 Formal Definition: The property is defined by the following notation: 2576 components = "COMPONENTS" other-params ":" comp-list CRLF 2578 ; All of these MUST BE supplied only once. 2579 ; 2580 comp-list-req = "VCALSTORE" "," "VCALENDAR" "," "VTIMEZONE" "," 2581 "VREPLY" "," "VAGENDA" "," "STANDARD" "," 2582 "DAYLIGHT" 2584 ; At least one MUST BE supplied. The same value 2585 ; MUST NOT occur more than once. 2586 ; 2587 comp-list-min = ( "," "VEVENT") / ( "," "VTODO") / ( "," "VJOURNAL" ) 2589 ; The same value MUST NOT occur 2590 ; more than once. If "VCAR" is supplied then 2591 ' "VRIGHT" must be supplied. 2592 ; 2593 comp-list-opt = ( "," "VFREEBUSY" ) / ( "," "VALARM" ) 2594 / ( "," "VCAR" ) / ( "," "VRIGHT" ) 2595 / ( "," "VQUERY") / ( "," x-comp ) 2596 / ( "," iana-comp ) 2598 comp-list = comp-list-req 1*3comp-list-min *(comp-list-opt) 2600 Example: The following is an example of this property: 2602 COMPONENTS:VCALSTORE,VCALENDAR,VREPLY,VAGENDA, 2603 VEVENT,VALARM,VTIMEZONE,VJOURNAL,VTODO, 2604 DAYLIGHT,STANDARD,VFREEBUSY,VCAR,VRIGHT,VQUERY 2606 8.9 CSID Property 2608 Property Name: CSID 2610 Purpose: The property specifies a the globally unique identifier for 2611 the calendar store. 2613 Value Type: URI 2615 Property Parameters: Non-standard property parameters can be 2616 specified on this property. 2618 Conformance: The property can be specified in a "VCALSTORE" 2619 component. 2621 Description: The identifier MUST BE globally unique. Each CS needs 2622 its own unique identifier. The "CSID" property is the official unique 2623 identifier for the CS. If the [BEEP] 'serverName' attribute was 2624 supplied in the [BEEP] 'start' message, then the CSID will be mapped 2625 to the virtual host name supplied and the host name part of the CSID 2626 MUST BE the same as the 'serverName' value. This allows one CS 2627 implementation to service multiple virtual hosts. CS's are not 2628 required to support virtual hosting. If a CS does not support virtual 2629 hosting then it must ignore the [BEEP] 'serverName' attribute. 2631 Formal Definition: The property is defined by the following notation: 2633 csid = "CSID" other-params ":" capurl CRLF 2635 Example: The following is an example of this property: 2637 CSID:cap://calendar.example.com 2639 8.10 DECREED Property 2641 Property Name: DECREED 2643 Purpose: This property specifies if an access right calendar 2644 component is decreed or not. 2646 Value Type: BOOLEAN 2648 Property Parameters: Non-standard property parameters can be 2649 specified on this property. 2651 Conformance: This property MAY be specified once in a "VCAR" 2652 component. 2654 Description: This property is used in the "VCAR" component to specify 2655 whether the component is decreed or not. If the "DECREED" property 2656 value is "true" then the CUA will be unable to change the contents of 2657 the "VCAR" component and any attempt will fail with an error. 2659 Formal Definition: The property is defined by the following notation: 2661 decreed = "DECREED" other-params ":" boolean CRLF 2663 Example: The following is an example of this property: 2665 DECREED:TRUE 2667 8.11 DEFAULT-CHARSET Property 2669 Property Name: DEFAULT-CHARSET 2671 Purpose: This property indicates the default charset. 2673 Value Type: TEXT 2675 Property Parameters: Non-standard property parameters can be 2676 specified on this property. 2678 Conformance: This property can be specified in "VAGENDA" and 2679 "VCALSTORE" calendar component. 2681 Description: In a "VAGENDA" component this property is used to 2682 indicate the charset of calendar. If not specified, the default is 2683 the first value in the "VCALSTORE" components "DEFAULT-CHARSET" 2684 property value list. The value MUST BE an IANA registered character 2685 set as defined in [CHARREG]. 2687 In a "VCALSTORE" component it is a comma separated list of charsets 2688 supported by the CS. The first entry is the default entry for all 2689 newly created "VAGENDA" components. The "UTF-8" value MUST BE in the 2690 "VCALSTORE" component "DEFAULT-CHARSET" property list. All compliant 2691 CAP implementations (CS and CUA) MUST support at least the "UTF-8" 2692 charset. 2694 If a charset name contains a comma (,), then that comma must be 2695 backslashed escaped in the value. 2697 Formal Definition: The property is defined by the following notation: 2699 default-charset = "DEFAULT-CHARSET" other-params ":" text 2700 *( "," text) CRLF 2702 Example: The following is an example of this property for a "VAGENDA" 2703 component: 2705 DEFAULT-CHARSET:Shift_JIS,UTF-8 2707 8.12 DEFAULT-LOCALE Property 2709 Property Name: DEFAULT-LOCALE 2711 Purpose: This property specifies the default language for text 2712 values. 2714 Value Type: TEXT 2716 Property Parameters: Non-standard property parameters can be 2717 specified on this property. 2719 Conformance: This property can be specified in "VAGENDA" and 2720 "VCALSTORE" components. 2722 Description: In a "VAGENDA" component, the "DEFAULT-LOCALE" property 2723 is used to indicate the locale of the calendar. The full locale 2724 SHOULD be used. The default and minimum locale is POSIX (aka the 'C' 2725 locale). 2727 In a "VCALSTORE" component it is a comma separated list of locales 2728 supported by the CS. The first value in the list is the default for 2729 all newly created VAGENDAs. "POSIX" MUST BE in the list. 2731 Formal Definition: The property is defined by the following notation: 2733 default-locale = "DEFAULT-LOCALE" other-params ":" language 2734 *( "," language) CRLF 2736 language = Text identifying a locale, as defined in [CHARPOL] 2738 Example: The following is an example of this property: 2740 DEFAULT-LOCALE:en-US.iso-8859-1,POSIX 2742 8.13 DEFAULT-TZID Property 2744 Property Name: DEFAULT-TZID 2746 Purpose: This property specifies the text value that specifies the 2747 time zones. 2749 Value Type: TEXT 2751 Property Parameters: Non-standard property parameters can be 2752 specified on this property. 2754 Conformance: This property may be specified once in a "VAGENDA" and 2755 "VCALSTORE" components. 2757 Description: A multi valued property that lists the known time zones. 2758 The first is the default. Where "TZID" property values are the same 2759 as the "TZID" property as defined in [iCAL]. 2761 If in a "VCALSTORE" component it is a comma separated list of TZIDs 2762 known to the CS. The entry is used as the default TZID list for all 2763 newly created calendars. The list MUST contain at least "UTC". A 2764 "VCALSTORE" components MUST have one "VTIMEZONE" component contained 2765 in it for each value in the "DEFAULT-TZID" property value. 2767 If in a "VAGENDA" component it is a comma separated list of "TZID" 2768 property values naming the time zones known to the calendar. The 2769 first time zone in the list is the default and is used as the 2770 localtime for objects that contain a date or date-time value without 2771 a time zone. All "VAGENDA" components MUST have one "VTIMEZONE" 2772 component contained for each value in the "DEFAULT-TZID" property 2773 value. 2775 If a "TZID" property value contains a comma (,), the comma must be 2776 backslash escaped. 2778 Formal Definition: This property is defined by the following 2779 notation: 2781 default-tzid = "DEFAULT-TZID" other-params 2782 ":" [tzidprefix] text 2783 *("," [tzidprefix] text) CRLF 2785 Example: The following is an example of this property: 2787 DEFAULT-TZID:US/Mountain,UTC 2789 8.14 DEFAULT-VCARS Property 2791 Property Name: DEFAULT-VCARS 2793 Purpose: This property is used to specify the "CARID" property ids of 2794 the default "VCAR" components for newly created "VAGENDA" components. 2796 Value Type: TEXT 2798 Property Parameters: Non-standard property parameters can be 2799 specified on this property. 2801 Conformance: This property MUST BE specified in "VCALSTORE" calendar 2802 component and MUST at least specify the following values: 2803 "READBUSYTIMEINFO", "REQUESTONLY", "UPDATEPARTSTATUS", and 2804 "DEFAULTOWNER". 2806 Description: This property is used in the "VCALSTORE" component to 2807 specify the "CARID" value of the "VCAR" components that MUST BE 2808 copied into now "VAGENDA" components at creation time by the CS. All 2809 "DEFAULT-VCAR" values must have "VCARS" components stored in the 2810 "VCALSTORE". 2812 Formal Definition: The property is defined by the following notation: 2814 def-vcars = "DEFAULT-VCARS" other-params ":" text 2815 *( "," text ) CRLF 2817 Example: The following is an example of this property: 2819 DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY, 2820 UPDATEPARTSTATUS,DEFAULTOWNER 2822 8.15 DENY Property 2824 Property Name: DENY 2826 Purpose: This property identifies the UPN(s) being denied access in 2827 the "VRIGHT" component. 2829 Value Type: UPN-FILTER 2831 Property Parameters: Non-standard property parameters can be 2832 specified on this property. 2834 Conformance: This property can be specified in "VRIGHT" components. 2836 Description: This property is used in the "VRIGHT" component to 2837 define the CU or UG being denied access. 2839 Formal Definition: The property is defined by the following notation: 2841 deny = "DENY" other-params ":" upn-filter CRLF 2843 Example: The following are examples of this property: 2845 DENY:* 2847 DENY:bob@example.com 2849 8.16 EXPAND property 2851 Property Name: EXPAND 2853 Purpose: This property is to notify the CS if it should or should not 2854 expand any component with recurrence rules into multiple instances in 2855 a query reply. 2857 Value Type: BOOLEAN 2859 Property Parameters: Non-standard property parameters can be 2860 specified on this property. 2862 Conformance: This property can be specified in "VQUERY" components. 2864 Description: If a CUA wishes to see all of the instances of a 2865 recurring component the CUA sets EXPAND=TRUE in the "VQUERY" 2866 component. If not specified, the default is FALSE. Note that if the 2867 CS has its "RECUR-EXPAND" CS property value set to false then the 2868 "EXPAND" property will be ignored and the result will be as if the 2869 "EXPAND" value was set to false. 2871 Formal Definition: The property is defined by the following notation: 2873 expand = "EXPAND" other-params ":" ("TRUE" / "FALSE") CRLF 2875 Example: The following are examples of this property: 2877 EXPAND:FALSE 2878 EXPAND:TRUE 2880 8.17 GRANT Property 2882 Property Name: GRANT 2884 Purpose: This property identifies the UPN(s) being granted access in 2885 the "VRIGHT" component. 2887 Value Type: UPN-FILTER 2889 Property Parameters: Non-standard property parameters can be 2890 specified on this property. 2892 Conformance: This property can be specified in "VRIGHT" calendar 2893 components. 2895 Description: This property is used in the "VRIGHT" component to 2896 specify the CU or UG being granted access. 2898 Formal Definition: The property is defined by the following notation: 2900 grant = "GRANT" other-params ":" upn-filter CRLF 2901 Example: The following are examples of this property: 2903 GRANT:* 2905 GRANT:bob@example.com 2907 8.18 ITIP-VERSION Property 2909 Property Name: ITIP-VERSION 2911 Purpose: This property specifies the version of ITIP supported. 2913 Value Type: TEXT 2915 Property Parameters: Non-standard property parameters can be 2916 specified on this property. 2918 Conformance: This property is specified in the "VREPLY" component 2919 that is sent in response to a "GET-CAPABILITY" command. 2921 Description: This specifies the version of ITIP that the endpoint 2922 supports. The list is a comma separated list of RFC numbers 2923 supported. The list MUST contain at least 2446 to mean [iTIP] 2925 Formal Definition: The property is defined by the following notation: 2927 itip-version = "ITIP-VERSION" other-params ":" text CRLF 2929 Example: The following are examples of this property: 2931 ITIP-VERSION:2446 2933 8.19 MAX-COMP-SIZE Property 2935 Property Name: MAX-COMP-SIZE 2937 Purpose: This property specifies the largest size of any object 2938 accepted. 2940 Value Type: TEXT 2941 Property Parameters: Non-standard property parameters can be 2942 specified on this property. 2944 Conformance: This property is specified in the "VREPLY" component 2945 that is sent in response to a "GET-CAPABILITY" command. 2947 Description: A positive integer value that specifies the size of the 2948 largest iCalendar object that can be accepted in octets. Objects 2949 larger than this will be rejected. A value of zero (0) means no 2950 limit. This is also the maximum value of any [BEEP] payload that will 2951 be accepted or sent. 2953 Formal Definition: The property is defined by the following notation: 2955 max-comp-size = "MAX-COMP-SIZE" other-params ":" posint0 CRLF 2957 Example: The following are examples of this property: 2959 MAX-COMP-SIZE:1024 2961 8.20 MAXDATE Property 2963 Property Name: MAXDATE 2965 Purpose: This property specifies the date/time in the future beyond 2966 which the CS or CUA cannot represent. 2968 Value Type: DATE-TIME 2970 Property Parameters: Non-standard property parameters can be 2971 specified on this property. 2973 Conformance: The property can be specified in the "VCALSTORE" 2974 component. 2976 Description: The date and time MUST BE a UTC value and end with 'Z'. 2978 Formal Definition: The property is defined by the following notation: 2980 maxdate = "MAXDATE" other-params ":" date-time CRLF 2981 Example: The following is an example of this property: 2983 MAXDATE:20990101T000000Z 2985 8.21 MINDATE Property 2987 Property Name: MINDATE 2989 Purpose: This property specifies the date/time in the past prior to 2990 which the server cannot represent. 2992 Value Type: DATE-TIME 2994 Property Parameters: Non-standard property parameters can be 2995 specified on this property. 2997 Conformance: The property can be specified in the "VCALSTORE" 2998 component. 3000 Description: The date and time MUST BE a UTC value and end with 'Z'. 3002 Formal Definition: The property is defined by the following notation: 3004 mindate = "MINDATE" other-params ":" date-time CRLF 3006 Example: The following is an example of this property: 3008 MINDATE:19710101T000000Z 3010 8.22 MULTIPART Property 3012 Property Name: MULTIPART 3014 Purpose: This property provides a comma separated list of supported 3015 MIME multipart types supported by the sender. 3017 Value Type: TEXT 3019 Property Parameters: Non-standard property parameters can be 3020 specified on this property. 3022 Conformance: This property can be specified in a component. 3024 Description: This property is used in the in the "GET-CAPABILITY" 3025 command reply to indicated the MIME multipart types supported. A CS 3026 and CUA SHOULD support all registered MIME multipart types. 3028 Formal Definition: The property is defined by the following notation: 3030 name = "MULTIPART" other-params ":" text *( "," text) CRLF 3032 Example: The following is an example of this property: 3034 MULTIPART:related,alternate,mixed 3036 8.23 NAME Property 3038 Property Name: NAME 3040 Purpose: This property provides a localizable display name for a 3041 component. 3043 Value Type: TEXT 3045 Property Parameters: Non-standard property parameters can be 3046 specified on this property. 3048 Conformance: This property can be specified in a component. 3050 Description: This property is used in the in component to specify a 3051 localizable display name. If more than one "NAME" properties are in a 3052 component, then they MUST have unique "LANG" parameters. If the 3053 "LANG" parameter is not supplied, then it defaults to the "VAGENDA" 3054 default if the component is in a "VAGENDA", or the "VCALSTORE" 3055 default if the component is stored at the "VCALSTORE" level. 3057 Formal Definition: The property is defined by the following notation: 3059 name = "NAME" nameparam ":" text CRLF 3061 nameparam = other-params [ ";" languageparam ] other-params 3063 languageparam = ; As defined in [iCAL]. 3065 Example: The following is an example of this property: 3067 NAME:Restrict Guests From Creating VALARMs On VEVENTs 3069 8.24 OWNER Property 3071 Property Name: OWNER 3073 Purpose: The property specifies an owner of the component. 3075 Value Type: UPN 3077 Property Parameters: Non-standard, alternate text representation and 3078 language property parameters can be specified on this property. 3080 Conformance: The property MUST BE specified at in a "VAGENDA" 3081 component. 3083 Description: A multi-instanced property indicating the calendar 3084 owner. 3086 Formal Definition: The property is defined by the following notation: 3088 owner = "OWNER" other-params ":" upn CRLF 3090 Example: The following is an example of this property: 3092 OWNER:jsmith@example.com 3093 OWNER:jdough@example.com 3095 8.25 PERMISSION Property 3097 Property Name: PERMISSION 3099 Purpose: This property defines a permission that is granted or denied 3100 in a "VRIGHT" component. 3102 Value Type: TEXT 3104 Property Parameters: Non-standard property parameters can be 3105 specified on this property. 3107 Conformance: This property can be specified in "VRIGHT" components. 3109 Description: This property is used in the "VRIGHT" component to 3110 define a permission that is granted or denied. 3112 Formal Definition: The property is defined by the following notation: 3114 perm = "PERMISSION" other-params ":" permvalue CRLF 3116 permvalue = ( "SEARCH" / "CREATE" / "DELETE" 3117 / "MODIFY" / "MOVE" / all 3118 / iana-cmd / x-cmd ) 3120 all = "*" 3122 iana-cmd = ; Any command registered by IANA directly or 3123 ; included in an RFC that may be applied as 3124 ; a command. 3126 x-cmd = ; Any experimental command that starts with 3127 ; "x-" or "X-". 3129 Example: The following is an example of this property: 3131 PERMISSION:SEARCH 3133 8.26 QUERY property 3135 Property Name: QUERY 3137 Purpose: Specifies the query for the component. 3139 Value Type: CAL-QUERY 3141 Property Parameters: Non-standard property parameters can be 3142 specified on this property. 3144 Conformance: This property can be specified in "VQUERY" components. 3146 Description: A "QUERY" is used to specify the "CAL-QUERY" (Section 3147 6.1.1 for the query. 3149 Formal Definition: The property is defined by the following notation: 3151 query = "QUERY" other-params ":" cal-query CRLF 3153 Example: The following is an example of this property: 3155 QUERY:SELECT * FROM VEVENT 3157 8.27 QUERYID property 3159 Property Name: QUERYID 3161 Purpose: Specifies a unique ID for a query in the targeted container. 3163 Value Type: TEXT 3165 Property Parameters: Non-standard property parameters are specified 3166 on this property. 3168 Conformance: This property can be specified in "VQUERY" components. 3170 Description: A "QUERYID" property is used to specify the unique id 3171 for a stored query. A "QUERYID" property value is unique per 3172 container. 3174 Formal Definition: The property is defined by the following notation: 3176 queryid = "QUERYID" other-params ":" text CRLF 3178 Example: The following are examples of this property: 3180 QUERYID:Any Text String 3181 QUERYID:fetchUnProcessed 3183 8.28 REQUEST-STATUS property 3185 This description is a revision of the "REQUEST-STATUS" property for 3186 [iCAL] objects with a "VCALENDAR" component "VERSION" property that 3187 includes a value of "2.0" or newer. The 'statdesc' is optional and 3188 the 'extdata' may be included when 'statdesc' is not provided. 3190 rstatus = "REQUEST-STATUS" rstatparam ":" 3191 statcode ";" *(statdesc ) ";" *(extdata) 3193 rstatparam = other-params [";" languageparam] other-params 3195 statcode = 1*DIGIT *("." 1*DIGIT) 3196 ;Hierarchical, numeric return status code 3198 statdesc = text 3199 ;An optional textual status description, content is 3200 ;decided by the implementer. May be empty. 3202 extdata = text 3203 ; Textual exception data. For example, the offending 3204 ; property name and value or complete property line. 3206 Example: The following are some possible examples of this property. 3207 The COMMA and SEMICOLON separator characters in the property value 3208 are BACKSLASH character escaped because they appear in a text value. 3210 REQUEST-STATUS:2.0;Success 3212 REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01 3214 REQUEST-STATUS:2.8; Success\, repeating VEVENT ignored. Scheduled 3215 as a single VEVENT.;RRULE:FREQ=WEEKLY;INTERVAL=2 3217 REQUEST-STATUS:4.1;Time conflict. Date/time is busy. 3219 REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE: 3220 MAILTO:jsmith@example.com 3222 REQUEST-STATUS:3.7;;ATTENDEE:MAILTO:jsmith@example.com 3224 REQUEST-STATUS:10.4;Help! That really shouldn't have happened. 3226 8.29 QUERY-LEVEL Property 3228 Property Name: QUERY-LEVEL 3229 Purpose: This property specifies the level of query supported. 3231 Value Type: TEXT 3233 Property Parameters: Non-standard property parameters can be 3234 specified on this property. 3236 Conformance: The property can be specified in the "VREPLY" component 3237 in response to a "GET-CAPABILITY" command. 3239 Description: Indicates level of query support. CAL-QL-NONE is for 3240 CS's that allow ITIP methods only to be deposited and nothing else. 3242 Formal Definition: The property is defined by the following notation: 3244 query-level = "QUERY-LEVEL" other-params 3245 ":" ( "CAL-QL-1" / "CAL-QL-NONE") CRLF 3247 Example: The following is an example of this property: 3249 QUERY-LEVEL:CAL-QL-1 3251 8.30 RECUR-ACCEPTED Property 3253 Property Name: RECUR-ACCEPTED 3255 Purpose: This property specifies if the endpoint supports recurring 3256 instances. 3258 Value Type: BOOLEAN 3260 Property Parameters: Non-standard property parameters can be 3261 specified on this property. 3263 Conformance: The property can be specified in the "VREPLY" component 3264 in response to a "GET-CAPABILITY" command. 3266 Description: Indicates if recurrence rules are supported. If FALSE 3267 then the endpoint can not process any kind of recurring rules. 3269 Formal Definition: The property is defined by the following notation: 3271 recur-accepted = "RECUR-ACCEPTED" other-params ":" boolean CRLF 3273 Example: The following is an example of this property: 3275 RECUR-ACCEPTED:TRUE 3276 RECUR-ACCEPTED:FALSE 3278 8.31 RECUR-LIMIT Property 3280 Property Name: RECUR-LIMIT 3282 Purpose: This property specifies the maximum number of instances the 3283 endpoint will expand instances into at query or storage time. 3285 Value Type: posint1 3287 Property Parameters: Non-standard property parameters can be 3288 specified on this property. 3290 Conformance: The property can be specified in the "VREPLY" component 3291 in response to a "GET-CAPABILITY" command. 3293 Description: For implementations that have the "STORES-EXPANDED" 3294 value set to TRUE, then this value specifies the maximum number of 3295 instances that will be stored and fetched. For all implementations 3296 this is the maximum number of instances that will be returned when 3297 the "EXPAND" parameter is specified as TRUE and the results contain a 3298 infinite or large number of recurring instances. 3300 Formal Definition: The property is defined by the following notation: 3302 recur-limit = "RECUR-LIMIT" other-params ":" posint1 CRLF 3304 Example: The following is an example of this property: 3306 RECUR-LIMIT:1000 3308 8.32 RECUR-EXPAND Property 3310 Property Name: RECUR-EXPAND 3312 Purpose: This property specifies if the endpoint can expand 3313 recurrences into multiple objects. 3315 Value Type: BOOLEAN 3317 Property Parameters: Non-standard property parameters can be 3318 specified on this property. 3320 Conformance: The property can be specified in the "VREPLY" component 3321 in response to a "GET-CAPABILITY" command. 3323 Description: If TRUE then the endpoint can expand an object into 3324 multiple instances as defined by its recurrence rules when the 3325 "EXPAND" parameter is supplied. If FALSE then the endpoint ignores 3326 the "EXPAND" parameter. 3328 Formal Definition: The property is defined by the following notation: 3330 recur-expand = "RECUR-EXPAND" other-params ":" boolean CRLF 3332 Example: The following is an example of this property: 3334 RECUR-EXPAND:TRUE 3335 RECUR-EXPAND:FALSE 3337 8.33 RESTRICTION Property 3339 Property Name: RESTRICTION 3341 Purpose: This property defines restrictions on the result value of 3342 new or existing components. 3344 Value Type: CAL-QUERY 3346 Property Parameters: Non-standard property parameters can be 3347 specified on this property. 3349 Conformance: This property can be specified in "VRIGHT" components, 3350 but only when the "PERMISSION" property is set to "CREATE", "MODIFY", 3351 or "*" property value. 3353 Description: This property is used in the "VRIGHT" component to 3354 define restrictions on the components that can be written (i.e., by 3355 using the "CREATE" or "MOVE" commands) as well as on the values that 3356 may take existent calendar store properties, calendar properties, 3357 components, and properties (i.e., by using the "MODIFY" command). 3358 Accepted values MUST match any specified "RESTRICTION" property 3359 values. 3361 Formal Definition: The property is defined by the following notation: 3363 restrict = "RESTRICTION" other-params ":" cal-query CRLF 3365 Example: The following are examples of this property: 3367 RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST' 3369 RESTRICTION:SELECT * FROM VEVENT WHERE 3370 SELF() IN ORGANIZER 3372 RESTRICTION:SELECT * FROM VEVENT WHERE 'BUSINESS' IN 3373 CATEGORIES 3375 8.34 SCOPE Property 3377 Property Name: SCOPE 3379 Purpose: This property identifies the objects in the CS to which the 3380 access rights applies. 3382 Value Type: CAL-QUERY 3384 Property Parameters: Non-standard property parameters can be 3385 specified on this property. 3387 Conformance: This property can be specified in "VRIGHT" components. 3389 Description: This property is used in the "VRIGHT" component to 3390 define the set of objects subject to the access right being defined. 3392 Formal Definition: The property is defined by the following notation: 3394 scope = "SCOPE" other-params ":" cal-query CRLF 3396 Example: The following is an example of this property: 3398 SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC' 3400 8.35 STORES-EXPANDED Property 3402 Property Name: STORES-EXPANDED 3404 Purpose: This property specifies if the sending endpoint expands 3405 recurrence rules prior to storing them into the CS. Section 5. 3407 Value Type: BOOLEAN 3409 Property Parameters: Non-standard property parameters can be 3410 specified on this property. 3412 Conformance: This property can be specified in a "VREPLY" component 3413 in response to a "GET-CAPABILITY" command. 3415 Description: If the value is TRUE then the endpoint expands 3416 recurrence rules and then stores the results into the CS. If this is 3417 TRUE then the "RECUR-LIMIT" property is significant because an 3418 infinitely recurring appointment will be stored no more than 3419 "RECUR-LIMIT" property values into the CS and all other instances 3420 will be lost. 3422 Formal Definition: The property is specified by the following 3423 notation: 3425 stores-expanded = "STORES-EXPANDED" other-params ":" boolean CRLF 3427 The following is an example of this property: 3429 STORES-EXPANDED:TRUE 3430 STORES-EXPANDED:FALSE 3432 8.36 TARGET Property 3434 Property Name: TARGET 3436 Purpose: This property defines the container that the command that is 3437 issued will act upon. Its value is a capurl as defined in Section 5. 3439 Value Type: URI 3441 Property Parameters: Non-standard property parameters can be 3442 specified on this property. 3444 Conformance: This property can be specified in a command component. 3446 Description: This property value is used to specify the container 3447 that the command will effect. When used in a command, the command 3448 will be performed on the container which has a capurl matching the 3449 value. 3451 Formal Definition: The property is specified by the following 3452 notation: 3454 target = "TARGET" other-params ":" capurl CRLF 3456 The following is an example of this property: 3458 TARGET:cap://mycal.example.com 3459 TARGET:SomeRelCalid 3461 8.37 TRANSP Property 3463 Property Name: TRANSP 3465 Purpose: This property defines whether an component is transparent or 3466 not to busy time searches. This is a modification to [iCAL] "TRANSP" 3467 property in that it adds some values. 3469 Value Type: TEXT 3471 Property Parameters: Non-standard property parameters can be 3472 specified on this property. 3474 Conformance: This property can be specified in a component. 3476 Description: Time Transparency is the characteristic of an object 3477 that determines whether it appears to consume time on a calendar. 3478 Objects that consume actual time for the individual or resource 3479 associated with the calendar SHOULD be recorded as "OPAQUE", allowing 3480 them to be detected by free-busy time searches. Other objects, which 3481 do not take up the individual's (or resource's) time SHOULD be 3482 recorded as "TRANSPARENT", making them invisible to free-busy time 3483 searches. 3485 Formal Definition: The property is specified by the following 3486 notation: 3488 transp = "TRANSP" other-params ":" transvalue CRLF 3490 transvalue 3491 = "OPAQUE" ;Blocks or opaque on busy time searches. 3492 / "TRANSPARENT" ;Transparent on busy time searches. 3494 / "TRANSPARENT-NOCONFLICT" ; Transparent on busy time 3495 ; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects 3496 ; can overlap it. 3498 / "OPAQUE-NOCONFLICT" ; Opaque on busy time 3499 ; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects 3500 ; can overlap it. 3501 ; 3502 ;Default value is OPAQUE 3504 The following is an example of this property for an object that is 3505 opaque or blocks on free/busy time searches plus no other object can 3506 overlap it: 3508 TRANSP:OPAQUE-NOCONFLICT 3510 9. New Components 3512 9.1 VAGENDA Component 3514 Component Name: VAGENDA 3516 Purpose: Provide a grouping of properties that defines an agenda. 3518 Formal Definition: There are two formats of the "VAGENDA" component. 3519 (1) When it is being created, and (2) how it exists in the 3520 "VCALSTORE" component. 3522 A "VAGENDA" component in a "VCALSTORE" component is defined by the 3523 following notes and ABNF notation: 3525 CALSCALE - The value MUST BE from the "VCALSTORE" "CALSCALE" 3526 property list. The default is the first entry in the VCALSTORE 3527 CALSCALE list. 3529 CREATED - The timestamp of the calendar's create date. This is a 3530 READ ONLY property in a "VAGENDA". 3532 LAST-MODIFIED - The timestamp of any change to the "VAGENDA" 3533 properties or when any component was last created, modified, or 3534 deleted. 3536 agenda = "BEGIN" ":" "VAGENDA" CRLF 3537 agendaprop 3538 *(icalobject) ; as defined in [iCAL] 3539 "END" ":" "VAGENDA" CRLF 3541 agendaprop = *( 3542 ; The following MUST occur exactly once. 3543 ; 3544 allow-conflict / calid / calscale / created 3545 / default-charset / default-locale 3546 / default-tzid / last-modified / 3548 ; The following MUST occur at least once. 3549 ; and the value MUST NOT be empty. 3551 / owner 3553 ; The following are optional, 3554 ; and MAY occur more than once. 3556 / name / related-to / other-props / x-comp 3557 ) 3559 When creating a VAGENDA, use the following notation: 3561 agendac = "BEGIN" ":" "VAGENDA" CRLF 3562 agendacprop 3563 *(icalobject) ; as defined in [iCAL] 3564 "END" ":" "VAGENDA" CRLF 3566 agendacprop = *( 3567 ; The following MUST occur exactly once. 3568 ; 3569 allow-conflict / calid / calscale 3570 / default-charset / default-locale 3571 / default-tzid / 3573 ; The following MUST occur at least once. 3574 ; and the value MUST NOT be empty. 3575 ; 3576 / owner 3578 ; The following are optional, 3579 ; and MAY occur more than once. 3580 ; 3581 / name / related-to / other-props / x-comp 3582 ) 3584 To fetch all of the properties from the targeted "VAGENDA" component. 3585 This does not fetch any components: 3587 SELECT * FROM VAGENDA 3589 To fetch all of the properties from the targeted VAGENDA and all of 3590 the contained components, use the special '*.*' value: 3592 SELECT *.* FROM VAGENDA 3594 9.2 VCALSTORE Component 3596 Component Name: VCALSTORE 3598 Purpose: Provide a grouping of properties that defines a calendar 3599 store. 3601 Formal Definition: A "VCALSTORE" component is defined by the 3602 following table and ABNF notation. The creation of a "VCALSTORE" 3603 component is an administrative task and not part of the CAP protocol. 3605 The following are notes to some of the properties in the "VCALSTORE" 3606 component. 3608 CALSCALE - A comma separated list of CALSCALEs supported by this CS. 3609 All "VAGENDA" component calendar CALSCALE properties MUST BE from 3610 this list. This list MUST contain at least "GREGORIAN". The 3611 default for newly created "VAGENDA" components is the first entry. 3613 RELATED-TO - This is a multiple instance property. There must be a 3614 "RELATED-TO" property MUST for each of the "VAGENDA" components 3615 contained in the "VCALSTORE" component each with the "RELTYPE" 3616 parameter value set to "CHILD". Other "RELATED-TO" properties may 3617 be included. 3619 CREATED - The timestamp of the CS creation time. This is a READ ONLY 3620 property. 3622 CSID - The CSID of this calendar store. MUST NOT be empty. How this 3623 property is set in the VCALSTORE is an administrative or 3624 implementation specific issue and is not covered in CAP. This is a 3625 READ ONLY property. A suggested value is the fully qualified host 3626 name or a fully qualified virtual host name supported by the 3627 system. 3629 LAST-MODIFIED - The timestamp when the Properties of the "VCALSTORE" 3630 component were last updated or calendars were created or deleted. 3631 This is a READ ONLY PROPERTY. 3633 calstorec = "BEGIN" ":" "VCALSTORE" CRLF 3634 calstoreprop 3635 *(vagendac) 3636 "END" ":" "VCALSTORE" CRLF 3638 calstoreprop = *( 3639 ; the following MUST occur exactly once 3640 allow-conflict / calscale / calmaster 3641 / created / csid / default-charset 3642 / default-locale / default-vcars 3643 / default-tzid / last-modified 3645 ; the following are optional, 3646 ; and MAY occur more than once 3648 / name / related-to / other-props / x-comp 3649 ) 3651 To fetch all of the properties from the targeted VCALSTORE and not 3652 fetch the calendars that it contains: 3654 SELECT * FROM VCALSTORE 3656 To fetch all of the properties from the targeted "VCALSTORE" 3657 component and all of the contained calendars and all of those 3658 calendars contained properties and components, use the special '*.*' 3659 value: 3661 SELECT *.* FROM VCALSTORE 3663 9.3 VCAR Component 3665 Component Name: VCAR 3667 Purpose: Provide a grouping of calendar access rights. 3669 Formal Definition: A "VCAR" component is defined by the following 3670 notation: 3672 carc = "BEGIN" ":" "VCAR" CRLF 3673 carprop 1*rightc 3674 "END" ":" "VCAR" CRLF 3676 carprop = 1*( 3678 ; 'carid' is REQUIRED, 3679 ; but MUST NOT occur more than once 3681 carid / 3683 ; the following are OPTIONAL, 3684 ; and MAY occur more than once 3686 name / other-props 3687 ) 3689 Description: A "VCAR" component is a grouping of properties, and 3690 "VRIGHT" components, that represents access rights granted or denied 3691 to UPNs. 3693 The "CARID" property specifies the local identifier for the "VCAR" 3694 component. The "NAME" property specifies a localizable display name. 3696 Example: In the following example, the UPN "foo@example.com" is given 3697 search access to the "DTSTART" and "DTEND" VEVENT properties. No 3698 other access is specified: 3700 BEGIN:VCAR 3701 CARID:View Start and End Times 3702 NAME:View Start and End Times 3703 BEGIN:VRIGHT 3704 GRANT:foo@example.com 3705 PERMISSION:SEARCH 3706 SCOPE:SELECT DTSTART,DTEND FROM VEVENT 3707 END:VRIGHT 3708 END:VCAR 3710 In this example, all UPNs are given search access to "DTSTART" and 3711 "DTEND" properties of VEVENT components. "All CUs and UGs" are 3712 specified by the UPN value "*". Note that this enumerated UPN value 3713 is not in quotes: 3715 BEGIN:VCAR 3716 CARID:ViewStartEnd2 3717 NAME:View Start and End Times 2 3718 BEGIN:VRIGHT 3719 GRANT:* 3720 PERMISSION:SEARCH 3721 SCOPE:SELECT DTSTART,DTEND FROM VEVENT 3722 END:VRIGHT 3723 END:VCAR 3725 In these examples, full calendar access rights are given to the 3726 CAL-OWNERS(), and a hypothetical administrator is given access rights 3727 to specify calendar access rights. If no other rights are specified, 3728 only these two UPNs can specify calendar access rights: 3730 BEGIN:VCAR 3731 CARID:some-id-3 3732 NAME:Only OWNER or ADMIN Settable VCARs 3733 BEGIN:VRIGHT 3734 GRANT:CAL-OWNERS() 3735 PERMISSION:* 3736 SCOPE:SELECT * FROM VAGENDA 3737 END:VRIGHT 3738 BEGIN:VRIGHT 3739 GRANT:cal-admin@example.com 3740 PERMISSION:* 3741 SCOPE:SELECT * FROM VCAR 3742 RESTRICTION:SELECT * FROM VCAR 3743 END:VRIGHT 3744 END:VCAR 3746 In this example, rights to write, search, modify or delete calendar 3747 access rights are denied to all UPNs. This example would disable 3748 providing different access rights to the calendar store or calendar. 3749 This calendar access right should be specified with great care, as it 3750 removes the ability to change calendar access; even for the owner or 3751 administrator. It could be used by small devices that do not support 3752 the changing of any VCAR: 3754 BEGIN:VCAR 3755 CARID:VeryRestrictiveVCAR-2 3756 NAME:No CAR At All 3757 BEGIN:VRIGHT 3758 DENY:* 3759 PERMISSION:* 3760 SCOPE:SELECT * FROM VCAR 3761 END:VRIGHT 3762 END:VCAR 3764 9.4 VRIGHT Component 3766 Component Name: "VRIGHT" 3768 Purpose: Provide a grouping of properties that describe an access 3769 right (granted or denied). 3771 Formal Definition: A "VRIGHT" component is defined by the following 3772 notation: 3774 rightc = "BEGIN" ":" "VRIGHT" CRLF 3775 rightprop 3776 "END" ":" "VRIGHT" CRLF 3778 rightprop = 2*( 3780 ; either 'grant' or 'deny' MUST 3781 ; occur at least once 3782 ; and MAY occur more than once 3784 grant / deny / 3786 ; 'permission' MUST occur at least once 3787 ; and MAY occur more than once 3789 permission / 3791 ; the following are optional, 3792 ; and MAY occur more than once 3794 scope / restriction / other-props 3796 ) 3798 Description: A "VRIGHT" component is a grouping of calendar access 3799 right properties. 3801 The "GRANT" property specifies the UPN that is being granted access. 3802 The "DENY" property specifies the UPN is being denied access. The 3803 "PERMISSION" property specifies the actual permission being set. The 3804 "SCOPE" property identifies the calendar store properties, calendar 3805 properties, components, or properties to which the access right 3806 applies. The "RESTRICTION" property specifies restriction on the 3807 value that may take calendar store properties, calendar properties, 3808 calendar components, and properties after a "CREATE" or "MODIFY" 3809 command. Values MUST match all the instances of the "RESTRICTION" 3810 property to be valid. 3812 9.5 VREPLY Component 3814 Component Name: "VREPLY" 3816 Purpose: Provide a grouping of arbitrary properties and components 3817 that are the data set result from an issued command. 3819 Formal Definition: A "VREPLY" component is defined by the following 3820 notation: 3822 replyc = "BEGIN" ":" "VREPLY" CRLF 3823 any-prop-or-comp 3824 "END" ":" "VREPLY" CRLF 3826 any-prop-or-comp = ; Zero or more iana or experimental 3827 ; properties and components, in any order. 3829 Description: Provide a grouping of arbitrary properties and 3830 components that are the data set result from an issued command. 3832 A query can return a predictable set of arbitrary properties and 3833 components. This component is used by query and other commands to 3834 return data that does not fit into any other component. It may 3835 contain any valid property or component, even if they are not 3836 registered. 3838 9.6 VQUERY Component 3840 Component Name: VQUERY 3842 Purpose: A component to specify what is to be fetched from a CS. 3844 Formal Definition: A "VQUERY" component is defined by the following 3845 notation: 3847 queryc = "BEGIN" ":" "VQUERY" CRLF 3848 queryprop 3849 "END" ":" "VCAR" CRLF 3851 queryprop = 1*( 3853 ; 'queryid' is OPTIONAL but MUST NOT occur 3854 ; more than once. If the "TARGET" property 3855 ; is supplied then the "QUERYID" property 3856 ; MUST BE supplied. 3857 ; 3858 queryid / target 3860 ; 'expand' is OPTIONAL but MUST NOT occur 3861 ; more than once. 3863 expand 3865 ; the following are OPTIONAL, and MAY occur 3866 ; more than once 3867 ; 3868 / name / other-props 3870 ; the following MUST occur at least once. 3871 ; 3872 / query 3874 ) 3876 Description: A "VQUERY" contains properties that specify which 3877 properties and components the CS is requested to return during a 3878 SEARCH command. 3880 The "QUERYID" property specifies the local identifier for a stored 3881 "VQUERY" component. The "NAME" property specifies a localizable 3882 display name of a stored "VQUERY" component. Normally "NAME" and 3883 "QUERYID" properties are used when looking for a correct stored 3884 "VQUERY" component, or when storing a "VQUERY" component. 3886 For a search, if the "TARGET" property is supplied in a "VQUERY" 3887 component, then the CS is to search for the query in the CALID 3888 supplied by the "TARGET" property value. 3890 For a create the "TARGET" property MUST NOT be supplied as the 3891 destination container is already supplied in the "TARGET" property of 3892 the "VCALENDAR" component. 3894 For examples, see Section 6.1.1. 3896 10. Commands and Responses 3898 CAP commands and responses are described in this section. 3900 10.1 CAP Commands (CMD) 3902 All commands are send using the CMD property. 3904 Property Name: CMD 3906 Purpose: The property defines the command to be sent. 3908 Value Type: TEXT 3910 Property Parameters: Non-standard, id, localize, latency, action or 3911 options. 3913 Conformance: This property is the method used to specify the commands 3914 to a CS and can exist in any object sent to the CS. 3916 Description: All of the command to the CS are supplied in this 3917 property. The "OPTIONS" parameter is overloaded and its meaning is 3918 dependent on the CMD value supplied. 3920 Formal Definition: The property is defined by the following notation: 3922 cmd = "CMD" ( 3923 / abort-cmd 3924 / continue-cmd 3925 / create-cmd 3926 / delete-cmd 3927 / generate-uid-cmd 3928 / get-capability-cmd 3929 / identify-cmd 3930 / modify-cmd 3931 / move-cmd 3932 / reply-cmd 3933 / search-cmd 3934 / set-locale-cmd 3935 / iana-cmd 3936 / x-cmd 3937 ) CRLF 3939 option-value = paramtext ; As defined in [iCAL] 3941 Calendaring commands allow a CUA to directly manipulate a calendar. 3943 Calendar access rights can be granted or denied for any commands. 3945 10.1.1 Bounded Latency 3947 A CAP command can have an associated maximum latency time by 3948 specifying the "LATENCY" parameter. If the command is unable to be 3949 completed in the specified amount of time (as specified by the 3950 "LATENCY" parameter value), then a "TIMEOUT" command MUST BE sent on 3951 the same channel to which there MUST BE a an "ABORT" or a "CONTINUE" 3952 command reply. If the CUA initiated the original command, then the CS 3953 would issue the "TIMEOUT" command and the CUA would then have to 3954 issue an "ABORT" or "CONTINUE" command. If the CS initiated the 3955 original command then the CUA would have to issue the "TIMEOUT" and 3956 the CS would send the "ABORT" or "CONTINUE". 3958 Upon receiving an "ABORT" command, the command must then be 3959 terminated. Only the "ABORT", "TIMEOUT", "REPLY, and "CONTINUE" 3960 commands can not be aborted. The "ABORT", "TIMEOUT", and "REPLY" 3961 commands MUST NOT have latency set. 3963 Upon receiving a "CONTINUE" command the work continues as if it had 3964 not been delayed or stopped. Note that a new latency time MAY BE 3965 included in a "CONTINUE" command indicating to continue the original 3966 command until the "LATENCY" parameter value expires or the results of 3967 the original command can be returned. 3969 Both the "LATENCY" parameter and the "ACTION" parameter MUST BE 3970 supplied to any "CMD" property, or nether can be added to the "CMD" 3971 property. The "LATENCY" parameter MUST BE set to the maximum latency 3972 time in seconds. The "ACTION" parameter accepts the following 3973 values: "ASK" and "ABORT" parameters. 3975 If the maximum latency time is exceeded and the "ACTION" parameter is 3976 set to the "ASK" value, then "TIMEOUT" command MUST BE sent. 3977 Otherwise if the "ACTION" parameter is set to the "ABORT" value then 3978 the command MUST BE terminated and return a REQUEST-STATUS code of 3979 2.0.3 for the original command. 3981 If a CS can both start sending the reply to a command and guarantee 3982 that all of the results can be sent from a command (short of 3983 something like network or power failure) prior to the "LATENCY" 3984 timeout value then the "LATENCY" time has not expired. 3986 Example: 3988 In this example the initiator asks for the listeners capabilities. 3990 I: Content-Type: text/calendar 3991 I: 3992 I: BEGIN:VCALENDAR 3993 I: VERSION:2.0 3994 I: PRODID:The CUA's PRODID 3995 I: CMD;ID=xyz12346;LATENCY=3;ACTION=ask:GET-CAPABILITY 3996 I: END:VCALENDAR 3998 # After 3 seconds 4000 L: Content-Type: text/calendar 4001 L: 4002 L: BEGIN:VCALENDAR 4003 L: PRODID:-//someone's prodid 4004 L: VERSION:2.0 4005 L: CMD;ID=xyz12346:TIMEOUT 4006 L: END:VCALENDAR 4008 In order to continue and give the CS more time then the CUA would 4009 issue a "CONTINUE" command: 4011 I: Content-Type: text/calendar 4012 I: 4013 I: BEGIN:VCALENDAR 4014 I: VERSION:2.0 4015 I: PRODID:-//someone's prodid 4016 I: CMD;ID=xyz12346;LATENCY=3;ACTION=ask:CONTINUE 4017 I: END:VCALENDAR 4019 L: Content-Type: text/calendar 4020 L: 4021 L: BEGIN:VCALENDAR 4022 L: VERSION:2.0 4023 L: PRODID:-//someone's prodid 4024 L: CMD;ID=xyz12346:REPLY 4025 L: BEGIN:VREPLY 4026 L: REQUEST-STATUS:2.0.3;Continued for 3 more seconds 4027 L: END:VREPLY 4028 L: END:VCALENDAR 4030 To abort the command and not wait any further then issue an "ABORT" 4031 command: 4033 I: Content-Type: text/calendar 4034 I: 4035 I: BEGIN:VCALENDAR 4036 I: VERSION:2.0 4037 I: PRODID:-//someone's prodid 4038 I: CMD;ID=xyz12346:ABORT 4039 I: END:VCALENDAR 4041 # Which would result in a 2.0.3 reply. 4043 L: Content-Type: text/calendar 4044 L: 4045 L: BEGIN:VCALENDAR 4046 L: VERSION:2.0 4047 L: PRODID:-//someone's prodid 4048 L: CMD;ID=xyz12346:REPLY 4049 L: BEGIN:VREPLY 4050 L: REQUEST-STATUS:2.0.3;Aborted As Requested. 4051 L: END:VREPLY 4052 L: END:VCALENDAR 4054 10.1.2 ABORT Command 4056 CMD: ABORT 4058 Purpose: The "ABORT" command is sent to request that the named or 4059 only in process command be aborted. Latency MUST not be supplied with 4060 the "ABORT" command. 4062 Formal Definition: An "ABORT" command is defined by the following 4063 notation: 4065 abort-cmd = abortparam ":" "ABORT" 4067 abortparam = *( 4069 ; the following are optional, 4070 ; but MUST NOT occur more than once 4072 id-param 4073 / localize-param 4075 ; the following is optional, 4076 ; and MAY occur more than once 4078 / other-params 4079 ) 4081 The REPLY of any "ABORT" command is: 4083 abort-reply = "BEGIN" ":" "VCALENDAR" CRLF 4084 calprops 4085 abort-vreply 4086 "END" ":" "VCALENDAR" CRLF 4088 abort-vreply = "BEGIN" ":" "VREPLY" CRLF 4089 request-status 4090 other-props 4091 "END" ":" "VREPLY" CRLF 4093 10.1.3 CONTINUE Command 4095 CMD: CONTINUE 4097 Purpose: The "CONTINUE" command is only sent after a "TIMEOUT" 4098 command has been received to inform the other end of the session to 4099 resume working on a command. 4101 Formal Definition: A "CONTINUE" command is defined by the following 4102 notation: 4104 continue-cmd = continueparam ":" "CONTINUE" 4106 continueparam = *( 4108 ; the following are optional, 4109 ; but MUST NOT occur more than once 4111 id-param 4112 / localize-param 4113 / latency-param 4115 ; the following MUST occur exactly once and only 4116 ; when the latency-param has been supplied and 4117 ; MUST NOT be supplied if the latency-param is 4118 ; not supplied. 4120 / action-param 4122 ; the following are optional, 4123 ; and MAY occur more than once 4125 / other-params 4126 ) 4128 The REPLY of any "CONTINUE" command is: 4130 continue-reply = "BEGIN" ":" "VCALENDAR" CRLF 4131 calprops 4132 continue-vreply 4133 "END" ":" "VCALENDAR" CRLF 4135 continue-vreply = "BEGIN" ":" "VREPLY" CRLF 4136 request-status 4137 other-props 4138 "END" ":" "VREPLY" CRLF 4140 10.1.4 CREATE Command 4142 CMD: CREATE 4144 Purpose: The "CREATE" command is used to create one or more 4145 iCalendar objects in the store in the "BOOKED" or "UNPROCESSED" 4146 state. 4148 A CUA MAY send a "CREATE" command to a CS. The "CREATE" command MUST 4149 BE implemented by all CSs. 4151 The CS MUST NOT send a "CREATE" command to any CUA. 4153 Formal Definition: A "CREATE" command is defined by the following 4154 notation: 4156 create-cmd = createparam ":" "CREATE" 4158 createparam = *( 4160 ; the following are optional, 4161 ; but MUST NOT occur more than once 4163 id-param 4164 / localize-param 4165 / latency-param 4166 ; the following MUST occur exactly once and only 4167 ; when the latency-param has been supplied and 4168 ; MUST NOT be supplied if the latency-param is 4169 ; not supplied. 4171 / action-param 4173 ; the following is optional, 4174 ; and MAY occur more than once 4176 / other-params 4177 ) 4179 Response: 4181 One iCalendar object per TARGET property MUST BE returned. 4183 The REPLY of any "CREATE" command is: 4185 Restriction Table for the iCalendar section of a reply that contains 4186 an iCalendar object is any valid [iTIP] response plus any from this 4187 ABNF: 4189 create-reply = "BEGIN" ":" "VCALENDAR" CRLF 4190 creply-props 4191 1*(create-vreply) 4192 "END" ":" "VCALENDAR" CRLF 4194 create-vreply = "BEGIN" ":" "VREPLY" CRLF 4195 created-id 4196 request-status 4197 other-props 4198 "END" ":" "VREPLY" CRLF 4200 ; Where the id is appropriate for the 4201 ; type of object created: 4202 ; 4203 ; VAGENDA = calid 4204 ; VALARM = sequence 4205 ; VCAR = carid 4206 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 4207 ; VQUERY = queryid 4208 ; VTIMEZONE = tzid 4209 ; x-component = x-id 4210 ; 4211 created-id = ( calid / carid / uid / queryid / 4212 tzid / sequence / x-id) 4214 x-id = ; An ID for an x-component. 4216 creply-props = 4*( 4217 ; These are REQUIRED and MUST NOT occur 4218 ; more than once. 4219 ; 4220 prodid /version / target / reply-cmd 4222 ; These are optional, and may occur more 4223 ; than once. 4224 ; 4225 other-props 4227 For a "CREATE" command the "TARGET" property specifies the containers 4228 where the components will be created. 4230 If the iCalendar object being created does not have a "METHOD" 4231 property, then is not an [iTIP] object, then its state will be 4232 "BOOKED". Use the "DELETE" command to set the state of an object to 4233 the "DELETED" state (tagged for deletion). A CUA can not use the 4234 "CREATE" command to create an object in the "DELETED" state. 4236 If the intention is to book an [iTIP] object then the "METHOD" 4237 property MUST NOT BE supplied. Otherwise any [iTIP] object MUST have 4238 a valid [iTIP] "METHOD" property value and it is a scheduling request 4239 being deposited into the CS and will have its state set to 4240 "UNPROCESSED" state. 4242 ABNF for a "CREATE" object is: 4244 create-object = "BEGIN" ":" "VCALENDAR" CRLF 4245 ; If 'calprops' contain the "METHOD" property 4246 ; then this 'create-object' component MUST 4247 ; conform to [iTIP] restrictions. 4248 ; 4249 ; calprops MUST include 'create-cmd' 4250 ; 4251 calprops 4252 other-props 4253 1*(create-comp) 4254 "END" ":" "VCALENDAR" CRLF 4256 ; NOTE: The 'VCALSTORE' component is not included in 4257 ; 'create-comp' as it is out of scope for CAP to create 4258 ; a new CS. 4259 ; 4260 create-comp = agendac / carc / queryc 4261 / timezonec / freebusyc 4262 / eventc / todoc / journalc 4263 / iana-comp / x-component 4265 In the following example two new top level "VAGENDA" components are 4266 created. Note that the "CSID" value of the server is cal.example.com 4267 which is where the new "VAGENDA" components are going to be created. 4269 C: Content-Type: text/calendar 4270 C: 4271 C: BEGIN:VCALENDAR 4272 C: PRODID:-//someone's prodid 4273 C: VERSION:2.0 4274 C: CMD;ID=creation01:CREATE 4275 C: TARGET:cal.example.com 4276 C: BEGIN:VAGENDA <- data for 1st new calendar 4277 C: CALID:relcalz1 4278 C: NAME;LANGUAGE=en_US:Bill's Soccer Team 4279 C: OWNER:bill 4280 C: CALMASTER:mailto:bill@example.com 4281 C: TZID:US/Pacific 4282 C: END:VAGENDA 4283 C: BEGIN:VAGENDA <- data for 2nd new calendar 4284 C: CALID:relcalz2 4285 C: NAME;LANGUAGE=EN-us:Mary's personal calendar 4286 C: OWNER:mary 4287 C: CALMASTER:mailto:mary@example.com 4288 C: TZID:US/Pacific 4289 C: END:VAGENDA 4290 C: END:VCALENDAR 4292 S: Content-Type: text/calendar 4293 S: 4294 S: BEGIN:VCALENDAR 4295 S: VERSION:2.0 4296 S: PRODID:-//someone's prodid 4297 S: CMD;ID=creation01:REPLY 4298 S: TARGET:cal.example.com 4299 S: BEGIN:VREPLY <- Reply for 1st calendar create 4300 S: CALID:relcalz1 4301 S: REQUEST-STATUS:2.0 4302 S: END:REPLY 4303 S: BEGIN:VREPLY <- Reply for 2nd calendar create 4304 S: CALID:relcalz2 4305 S: REQUEST-STATUS:2.0 4306 S: END:VREPLY 4307 S: END:VCALENDAR 4309 To create a new component in multiple containers simply name all of 4310 the containers in the "TARGET" in the create command. Here a new 4311 "VEVENT" component is created in two TARGET components. In this 4312 example, the "VEVENT" component is one new [iTIP] "REQUEST" to be 4313 stored in two calendars. The results would be iCalendar objects that 4314 conform to the [iTIP] replies as defined in [iTIP]. 4316 This example shows two [iTIP] "VEVENT" components being created in 4317 each of the two supplied "TARGET" properties and as it contains the 4318 "METHOD" property they will be stored in the "UNPROCESSED" state: 4320 C: Content-Type: text/calendar 4321 C: 4322 C: BEGIN:VCALENDAR 4323 C: VERSION:2.0 4324 C: PRODID:-//someone's prodid 4325 C: CMD;ID=creation02:CREATE 4326 C: METHOD:REQUEST 4327 C: TARGET:relcalz1 4328 C: TARGET:relcalz2 4329 C: BEGIN:VEVENT 4330 C: DTSTART:20030307T180000Z 4331 C: UID:FirstInThisExample-1 4332 C: DTEND:20030307T190000Z 4333 C: SUMMARY:Important Meeting 4334 C: END:VEVENT 4335 C: BEGIN:VEVENT 4336 C: DTSTART:20040307T180000Z 4337 C: UID:SecondInThisExample-2 4338 C: DTEND:20040307T190000Z 4339 C: SUMMARY:Important Meeting 4340 C: END:VEVENT 4341 C: END:VCALENDAR 4343 The CS sends the "VREPLY" commands in separate MIME objects, one per 4344 supplied "TARGET" property value. 4346 S: Content-Type: text/calendar 4347 S: 4349 S: BEGIN:VCALENDAR 4350 S: VERSION:2.0 4351 S: PRODID:-//someone's prodid 4352 S: CMD;ID=creation02:REPLY 4353 S: TARGET:relcalz1 <- 1st TARGET listed. 4354 S: BEGIN:REPLY <- Reply for 1st VEVENT create in 1st TARGET. 4355 S: UID:FirstInThisExample-1 4356 S: REQUEST-STATUS:2.0 4357 S: END:VREPLY 4358 S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 1st TARGET. 4359 S: UID:SecondInThisExample-2 4360 S: REQUEST-STATUS:2.0 4361 S: END:VREPLY 4362 S: END:VCALENDAR 4364 And the second reply for the 2nd TARGET: 4366 S: Content-Type: text/calendar 4367 S: 4368 S: BEGIN:VCALENDAR 4369 S: VERSION:2.0 4370 S: PRODID:-//someone's prodid 4371 S: CMD;ID=creation02:REPLY 4372 S: TARGET:relcalz2 <- 2nd TARGET listed 4373 S: BEGIN:REPLY <- Reply for 1st VEVENT create in 2nd TARGET. 4374 S: UID:FirstInThisExample-1 4375 S: REQUEST-STATUS:2.0 4376 S: END:VREPLY 4377 S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 2nd TARGET. 4378 S: UID:SecondInThisExample-2 4379 S: REQUEST-STATUS:2.0 4380 S: END:VREPLY 4381 S: END:VCALENDAR 4383 10.1.5 DELETE Command 4385 CMD: DELETE 4387 Purpose: The "DELETE" command physically removes the QUERY result 4388 from the store or marks it for deletion. 4390 A CUA MAY send a "DELETE" command to a CS. The "DELETE" command MUST 4391 BE implemented by all CSs. 4393 The CS MUST NOT send a "DELETE" command to any CUA. 4395 Formal Definition: A "DELETE" command is defined by the following 4396 notation: 4398 delete-cmd = deleteparam ":" "DELETE" 4400 deleteparam = *( 4402 ; the following are optional, 4403 ; but MUST NOT occur more than once 4404 ; 4405 id-param 4406 / localize-param 4407 / latency-param 4408 / option-param "MARK" 4410 ; The following MUST occur exactly once and only 4411 ; when the latency-param has been supplied and 4412 ; MUST NOT be supplied if the latency-param is 4413 ; not supplied. 4414 ; 4415 / action-param 4417 ; the following is optional, 4418 ; and MAY occur more than once 4419 ; 4420 / other-params 4421 ) 4423 The "DELETE" command is used to delete calendars or components. The 4424 included "VQUERY" component(s) specifies the container(s) to delete. 4426 If a component is to be marked for delete and not physically removed, 4427 then include the "OPTIONS" parameter with its value set to the "MARK" 4428 value in order to alter its state to "DELETED". 4430 When components are deleted, only the top most component 4431 "REQUEST-STATUS" properties are returned. No "REQUEST-STATUS" 4432 properties are returned for components inside of the selected 4433 components. There MUST BE one "VREPLY" component returned for each 4434 object that is deleted or marked for delete. Note that if no "VREPLY" 4435 components are returned then nothing matched and nothing was deleted. 4437 Restriction Table for the "REPLY" command for any "DELETE" command. 4439 delete-reply = "BEGIN" ":" "VCALENDAR" CRLF 4440 calprops ; MUST include 'reply-cmd' 4441 *(delete-vreply) 4442 "END" ":" "VCALENDAR" CRLF 4444 delete-vreply = "BEGIN" ":" "VREPLY" CRLF 4445 deleted-id 4446 request-status 4447 "END" ":" "VREPLY" CRLF 4449 ; Where the id is appropriate for the 4450 ; type of object deleted: 4451 ; 4452 ; VAGENDA = calid 4453 ; VCAR = carid 4454 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 4455 ; VQUERY = queryid 4456 ; ALARM = sequence 4457 ; VTIMEZONE = tzid 4458 ; x-component = x-id 4459 ; An instance = uid recurid 4460 ; 4461 deleted-id = ( calid / carid / uid / uid recurid 4462 / queryid / tzid / sequence / x-id ) 4464 Example to delete a "VEVENT" component with "UID" value of 4465 'abcd12345' from the calendar "relcald-22" from the current CS: 4467 C: Content-Type: text/calendar 4468 C: 4469 C: BEGIN:VCALENDAR 4470 C: TARGET:relcalid-22 4471 C: CMD;ID:"random but unique per CUA":DELETE 4472 C: BEGIN:VQUERY 4473 C: QUERY:SELECT VEVENT FROM VAGENDA WHERE UID = 'abcd12345' 4474 C: END:VQUERY 4475 C: END:VCALENDAR 4477 S: BEGIN:VCALENAR 4478 S: TARGET:relcalid-22 4479 S: CMD;ID:"random but unique per CUA":REPLY 4480 S: BEGIN:VREPLY 4481 S: UID:abcd12345 4482 S: REQUEST-STATUS:3.0 4483 S: END:VREPLY 4484 S: END:VCALENDAR 4486 One or more iCalendar objects will be returned that contain a 4487 "REQUEST-STATUS" properties for the deleted components. There could 4488 have been more than one component deleted, Any booked and any number 4489 of unprocessed [iTIP] scheduling components that matched the QUERY 4490 value in the above example. Each unique "METHOD" property value that 4491 was deleted from the store MUST BE in a separate iCalendar object. 4492 This is because only one "METHOD" property is allowed in a single 4493 "VCALENDAR" BEGIN/END block. 4495 10.2 GENERATE-UID Command 4497 CMD: GENERATE-UID 4499 Purpose: The "GENERATE-UID" command returns one or more unique 4500 identifiers which MUST BE globally unique. 4502 The "GENERATE-UID" command MAY BE sent to any CS. The "GENERATE-UID" 4503 command MUST BE implemented by all CSs. 4505 The "GENERATE-UID" command MUST NOT be sent to a CUA. 4507 Formal Definition: A "GENERATE-UID" command is defined by the 4508 following notation: 4510 generate-uid-cmd = genuidparam ":" "GENERATE-UID" 4512 genuidparam = *( 4514 ; The following are optional, 4515 ; but MUST NOT occur more than once. 4517 id-param 4518 / localize-param 4519 / latency-param 4521 ; The following MUST occur exactly once and only 4522 ; when the latency-param has been supplied and 4523 ; MUST NOT be supplied if the latency-param is 4524 ; not supplied. 4526 / action-param 4528 ; The following is optional, 4529 ; and MAY occur more than once. 4531 / other-params 4533 ; The following MUST BE supplied exactly once. 4534 ; The value specifies the number of UIDs to 4535 ; be returned. 4537 / option-param posint1 4539 ) 4541 Response: 4543 gen-reply = "BEGIN" ":" "VCALENDAR" CRLF 4544 calprops ; Which MUST include 'reply-cmd' 4545 1*(gen-vreply) 4546 "END" ":" "VCALENDAR" CRLF 4548 gen-vreply = "BEGIN" ":" "VREPLY" CRLF 4549 1*(uid) 4550 request-status 4551 "END" ":" "VREPLY" CRLF 4553 Example: 4555 C: BEGIN:VCALENDAR 4556 C: VERSION:2.0 4557 C: PRODID:-//someone's prodid 4558 C: CMD;ID=unique-per-cua-124;OPTIONS=5:GENERATE-UID 4559 C: END:VCALENDAR 4561 S: Content-Type: text/calendar 4562 S: 4563 S: BEGIN:VCALENDAR 4564 S: VERSION:2.0 4565 S: PRODID:-//someone's prodid 4566 S: CMD;ID=unique-per-cua-124:REPLY 4567 S: BEGIN:VREPLY 4568 S: UID:20011121T120000Z-12340@cal.example.com 4569 S: UID:20011121T120000Z-12341@cal.example.com 4570 S: UID:20011121T120000Z-12342@cal.example.com 4571 S: UID:20011121T120000Z-12343@cal.example.com 4572 S: UID:20011121T120000Z-12344@cal.example.com 4573 S: REQUEST-STATUS:2.0 4574 S: END:VREPLY 4575 S: END:VCALENDAR 4577 10.3 GET-CAPABILITY Command 4579 CMD: GET-CAPABILITY 4581 Purpose: The "GET-CAPABILITY" command returns the capabilities of the 4582 other end point of the session. 4584 A CUA MUST send a "GET-CAPABILITY" command to a CS after the initial 4585 connection. A CS MUST send a "GET-CAPABILITY" command to a CUA after 4586 the initial connection. The "GET-CAPABILITY" command and reply MUST 4587 BE implemented by all CSs and CUAs. 4589 Formal Definition: A "GET-CAPABILITY" command is defined by the 4590 following notation: 4592 get-capability-cmd = capibiltyparam ":" "GET-CAPABILITY" 4594 capibiltyparam = *( 4596 ; the following are optional, 4597 ; but MUST NOT occur more than once 4598 ; 4599 id-param / localize-param / latency-param 4601 ; the following MUST occur exactly once and only 4602 ; when the latency-param has been supplied and 4603 ; MUST NOT be supplied if the latency-param is 4604 ; not supplied. 4605 ; 4606 / action-param 4608 ; the following is optional, 4609 ; and MAY occur more than once 4610 ; 4611 / other-params 4612 ) 4614 Response: 4616 The "GET-CAPABILITY" command returns information about the Calendar 4617 other end of the session given the current state of the connection. 4619 The values returned may differ depending on current user identify and 4620 the security level of the connection. 4622 Client implementations SHOULD NOT require any capability element 4623 beyond those defined in this specification or future RFC publications 4624 , and MAY ignore any nonstandard, experimental capability elements. 4625 The "GET-CAPABILITY" reply may return different results depending on 4626 the UPN and if the UPN is authenticated. 4628 When sending a reply to a "GET-CAPABILITY" command, all of these MUST 4629 BE supplied. The following properties are returned in response to a 4630 "GET-CAPABILITY" command: 4632 cap-vreply = "BEGIN" ":" "VCALENDAR" CRLF 4633 ; The following properties may be in any order. 4634 ; 4635 prodid 4636 version 4637 reply-cmd 4638 other-props 4639 "BEGIN" ":" "VREPLY" CRLF 4640 ; The following properties may be in any order. 4641 ; 4642 cap-version 4643 car-level 4644 components 4645 stores-expanded 4646 maxdate 4647 mindate 4648 itip-version 4649 max-comp-size 4650 multipart 4651 query-level 4652 recur-accepted 4653 recur-expand 4654 recur-limit 4655 other-props 4656 "END" ":" "VREPLY" CRLF 4657 "END" ":" "VCALENDAR" CRLF 4659 Example: 4661 I: Content-Type: text/calendar 4662 I: 4663 I: BEGIN:VCALENDAR 4664 I: VERSION:2.0 4665 I: PRODID:-//someone's prodid 4666 I: CMD;ID=unique-per-cua-125:GET-CAPABILITY 4667 I: END:VCALENDAR 4669 L: Content-Type: text/calendar 4670 L: 4671 L: BEGIN:VCALENDAR 4672 L: VERSION:2.0 4673 L: PRODID:-//someone's prodid 4674 L: CMD;ID=unique-per-cua-125:REPLY 4675 L: BEGIN:VREPLY 4676 L: CAP-VERSION:1.0 4677 L: PRODID:The CS prodid 4678 L: QUERY-LEVEL:CAL-QL-1 4679 L: CAR-LEVEL:CAR-FULL-1 4680 L: MAXDATE:99991231T235959Z 4681 L: MINDATE:00000101T000000Z 4682 L: MAX-COMPONENT-SIZE:0 4683 L: COMPONENTS:VCALENDAR,VTODO,VJOURNAL,VEVENT,VCAR, 4684 L: VALARM,VFREEBUSY,VTIMEZONE,STANDARD,DAYLIGHT,VREPLY 4685 L: ITIP-VERSION:2446 4686 L: RECUR-ACCEPTED:TRUE 4687 L: RECUR-EXPAND:TRUE 4688 L: RECUR-LIMIT:0 4689 L: STORES-EXPANDED:FALSE 4690 L: X-INET-PRIVATE-COMMANDS:1.0 4691 L: END:VREPLY 4692 L: END:VCALENDAR 4694 10.4 IDENTIFY Command 4696 CMD: IDENTIFY 4698 Purpose: The "IDENTIFY" command allows the CUA to set a new identity 4699 to be used for calendar access. 4701 A CUA MAY send an "IDENTIFY" command to a CS. The "IDENTIFY" command 4702 MUST BE implemented by all CSs. A CS implementation MAY reject all 4703 "IDENTIFY" commands. 4705 The CS MUST NOT send a "IDENTIFY" command to any CUA. 4707 Formal Definition: A "IDENTIFY" command is defined by the following 4708 notation: 4710 identify-cmd = identifyparam ":" "IDENTIFY" 4711 identifyparam = *( 4713 ; the following are optional, 4714 ; but MUST NOT occur more than once 4716 id-param 4717 / localize-param 4718 / latency-param 4720 ; the following MUST occur exactly once and only 4721 ; when the latency-param has been supplied and 4722 ; MUST NOT be supplied if the latency-param is 4723 ; not supplied. 4725 / action-param 4727 ; the following is optional, 4728 ; and MAY occur more than once 4730 / other-params 4732 ; The value is the UPN of the requested 4733 ; identity. If option is not supplied it is 4734 ; a request to return to the original authenticated 4735 ; identity. 4737 / option-param upn 4739 ) 4741 Response: 4743 A "REQUEST-STATUS" property wrapped in a "VREPLY" component with only one of the following 4744 request-status codes: 4746 2.0 Successful. 4748 6.4 Identity not permitted. VCAR restriction. 4750 The CS determines through an internal mechanism if the credentials 4751 supplied at authentication permit the operation as the selected 4752 identity. If they do, the session assumes the new identity, otherwise 4753 a security error is returned. 4755 Example: 4757 C: Content-Type: text/calendar 4758 C: 4759 C: BEGIN:VCALENDAR 4760 C: VERSION:2.0 4761 C: PRODID:-//someone's prodid 4762 C: CMD;ID=unique-per-cua-999;OPTIONS=newUserId:IDENTIFY 4763 C: END:VCALENDAR 4765 S: Content-Type: text/calendar 4766 S: 4767 S: BEGIN:VCALENDAR 4768 S: VERSION:2.0 4769 S: PRODID:-//someone's prodid 4770 S: BEGIN:VREPLY 4771 S: REQUEST-STATUS:2.0;Request Approved 4772 S: END:VREPLY 4773 S: END:VCALENDAR 4775 Or if denied: 4777 S: Content-Type: text/calendar 4778 S: 4779 S: BEGIN:VCALENDAR 4780 S: PRODID:-//someone's prodid 4781 S: VERSION:2.0 4782 S: BEGIN:VREPLY 4783 S: REQUEST-STATUS:6.4;Request Denied 4784 S: END:VREPLY 4785 S: END:VCALENDAR 4787 And for the CUA to return to its original authenticated identity 4788 the OPTIONS parameter is omitted: 4790 C: Content-Type: text/calendar 4791 C: 4792 C: BEGIN:VCALENDAR 4793 C: VERSION:2.0 4794 C: PRODID:-//someone's prodid 4795 C: CMD;ID=unique-per-cua-995:IDENTIFY 4796 C: END:VCALENDAR 4798 The CS may accept (2.0) or deny (6.4) the request to return to the 4799 original identity. 4801 If a CS considers the "IDENTIFY" command an attempt to violate 4802 security, the CS MAY terminate the [BEEP] session without any further 4803 notice to the CUA after sending the "REQUEST-STATUS" 6.4 reply. 4805 10.5 MODIFY Command 4807 CMD: MODIFY 4809 Purpose: The "MODIFY" command is used to modify existing components. 4811 A CUA MAY send a "MODIFY" command to a CS. The "MODIFY" command MUST 4812 BE implemented by all CSs. 4814 The CS MUST NOT send a "MODIFY" command to any CUA. 4816 Formal Definition: A "MODIFY" command is defined by the following 4817 notation: 4819 modify-cmd = modifyparam ":" "MODIFY" 4821 modifyparam = *( 4823 ; the following are optional, 4824 ; but MUST NOT occur more than once 4826 id-param 4827 / localize-param 4828 / latency-param 4830 ; the following MUST occur exactly once and only 4831 ; when the latency-param has been supplied and 4832 ; MUST NOT be supplied if the latency-param is 4833 ; not supplied. 4835 / action-param 4837 ; the following is optional, 4838 ; and MAY occur more than once 4840 / other-params 4842 ) 4844 The "MODIFY" command is used to modify existing components. The 4845 TARGET property specifies the calendars where the components exist 4846 that are going to be modified. 4848 The format of the request is two components inside of "VCALENDAR" 4849 component: 4851 BEGIN:VCALENDAR 4852 ... 4853 BEGIN:VQUERY 4854 ... 4855 END:VQUERY 4856 BEGIN:XXX 4857 ...old-values... 4858 END:XXX 4859 BEGIN:XXX 4860 ...new-values... 4861 END:XXX 4862 END:CALENDAR 4864 The "VQUERY" component selects the components that are to be 4865 modified. 4867 Where "XXX" above is a named component type (VEVENT, VTODO, ...). 4868 Both the old and new components MUST BE of the same type. 4870 The old-values is a component and the contents of that component are 4871 going to change and may contain information that helps uniquely 4872 identify the original component (SEQUENCE in the example below). If 4873 the CS can not find a component that matches the QUERY and does not 4874 have at least all of the OLD-VALUES, then a 6.1 error is returned. 4876 The new-values is a component of the same type as old-values and 4877 new-values contains the new data for each selected component. Any 4878 data that is in old-values and not in new-values is deleted from the 4879 selected component. Any values in new-values that was not in 4880 old-values is added to the component. 4882 In this example the "VEVENT" component with a "UID" property value of 4883 'unique-58' has; the "LOCATION" property and "LAST-MODIFIED" property 4884 changed, the "VALARM" component with the "SEQUENCE" property with a 4885 value of "3" has its "TRIGGER" property disabled, the "X-LOCAL" 4886 property is removed from the "VEVENT" component, and a "COMMENT" 4887 property is added. 4889 Because "SEQUENCE" property is used to locate the "VALARM" component 4890 in this example, both the old-values and the new-values contain the 4891 "SEQUENCE" property with a value of "3" and if the "SEQUENCE" 4892 property were to be left out of new-values, it would have been 4893 deleted. 4895 Example: 4897 C: Content-Type: text/calendar 4898 C: 4899 C: BEGIN:VCALENDAR 4900 C: VERSION:2.0 4901 C: PRODID:-//someone's prodid 4902 C: TARGET:my-cal 4903 C: CMD:ID=unique-mod:MODIFY 4904 C: BEGIN:VQUERY <- Query to select data set. 4905 C: QUERY:SELECT * FROM VEVENT WHERE UID = 'unique-58' 4906 C: END:VQUERY 4907 C: BEGIN:VEVENT <- Start of old data. 4908 C: LOCATION:building 3 4909 C: LAST-MODIFIED:20020101T123456Z 4910 C: X-LOCAL:some private stuff 4911 C: BEGIN:VALARM 4912 C: SEQUENCE:3 4913 C: TRIGGER;RELATED=END:PT5M 4914 C: END:VALARM 4915 C: END:VEVENT 4916 C: BEGIN:VEVENT <- End of new data. 4917 C: LOCATION:building 4 4918 C: LAST-MODIFIED:20020202T010203Z 4919 C: COMMENT:Ignore global trigger. 4920 C: BEGIN:VALARM 4921 C: SEQUENCE:3 4922 C: TRIGGER;ENABLE=FALSE:RELATED=END:PT5M 4923 C: END:VALARM 4924 C: END:VEVENT 4926 The "X-LOCAL" property was not supplied in the new-values, so it was 4927 deleted. The "LOCATION" property value was altered, as was the 4928 "LAST-MODIFIED" value. The "VALARM" component with a "SEQUENCE" 4929 property value of "3" had its "TRIGGER" property disabled, and the 4930 "SEQUENCE" property value did not change so it was not effected. The 4931 "COMMENT" property was added. 4933 When it comes to inline ATTACHMENTs, the CUA only needs to uniquely 4934 identify the contents of the ATTACHMENT value in the old-values in 4935 order to delete them. When the CS compares the attachment data it is 4936 compared in its binary form. The ATTACHMENT value supplied by the CUA 4937 MUST BE valid encoded information. 4939 For example, to delete the same huge inline attachment from every 4940 VEVENT in 'my-cal' that has an "ATTACH" property value with the 4941 old-values: 4943 BEGIN:VCALENDAR 4944 VERSION:2.0 4945 PRODID:-//someone's prodid 4946 TARGET:my-cal 4947 CMD:MODIFY 4948 BEGIN:VQUERY 4949 QUERY:SELECT ATTACH FROM VEVENT 4950 END:VQUERY 4951 BEGIN:VEVENT 4952 ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY: 4953 MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U 4954 EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE 4955 ...< remainder of attachment data NOT supplied >.... 4956 END:VEVENT 4957 BEGIN:VEVENT 4958 END:VEVENT 4959 END:VCALENDAR 4961 Above the new-values is empty, so everything in the old-values is 4962 deleted. 4964 Furthermore, the following additional restrictions apply: 4966 1. One can not change the "UID" property of a component. 4968 2. If a contained component is changed inside of a selected 4969 component, and that contained component has multiple instances, 4970 then old-values MUST contain information that uniquely identifies 4971 the instance or instances that are changing. It is valid to 4972 change more than one. As all contained components that match 4973 old-values will be modified. In the first modify example above, 4974 if "SEQUENCE" properties were to be deleted from both the 4975 old-values and new-values, then all "TRIGGER" properties that 4976 matched the old-values in all "VALARM" components in the selected 4977 "VEVENT" components would be disabled. 4979 3. The result of the modify MUST BE a valid iCalendar object. 4981 Response: 4983 A "VCALENDAR" component is returns with one ore more "REQUEST-STATUS" 4984 property values. 4986 If any error occurred: 4988 No component will be changed at all. That is, it will appear just 4989 as it was prior to the modify and the CAP server SHOULD return a 4990 "REQUEST-STATUS" property for each error that occurred. 4992 There MUST BE at least one error reported. 4994 If multiple components are selected, then what uniquely identified 4995 the component MUST BE returned (UID, QUERYID, ...) if the component 4996 contains a unique identifier. If not, sufficient information to 4997 uniquely identify the modified components MUST BE returned in the 4998 reply. 5000 S: Content-Type: text/calendar 5001 S: 5002 S: BEGIN:VCALENDAR 5003 S: TARGET:relcalid 5004 S: CMD;ID=delete#1:REPLY 5005 S: BEGIN:VREPLY 5006 S: BEGIN:VEVENT 5007 S: UID:123 5008 S: REQUEST-STATUS:2.0 5009 S: END:VEVENT 5010 S: END:VREPLY 5011 S: END:VCALENDAR 5013 10.6 MOVE Command 5015 CMD: MOVE 5017 Purpose: The "MOVE" command is used to move components within the CS. 5019 A CUA MAY send a "MOVE" command to a CS. The "MOVE" command MUST BE 5020 implemented by all CSs. 5022 The CS MUST NOT send a "MOVE" command to any CUA. 5024 Formal Definition: A "MOVE" command is defined by the following 5025 notation: 5027 move-cmd = moveparam ":" "MOVE" 5029 moveparam = *( 5031 ; the following are optional, 5032 ; but MUST NOT occur more than once 5033 id-param 5034 / localize-param 5035 / latency-param 5037 ; the following MUST occur exactly once and only 5038 ; when the latency-param has been supplied and 5039 ; MUST NOT be supplied if the latency-param is 5040 ; not supplied. 5042 / action-param 5044 ; the following is optional, 5045 ; and MAY occur more than once 5047 / other-params 5049 ) 5051 Response: 5052 The REQUEST-STATUS in a VCALENDAR object. 5054 The content of each "result" is subject to the result restriction 5055 table defined below. 5057 The access control on the "VAGENDA" component after it has been moved 5058 to its new location in the calstore MUST BE at least as secure as it 5059 was prior to the move. If the CS is not able to ensure the same level 5060 of security, a permission denied "REQUEST-STATUS" property value MUST 5061 BE returned and the "MOVE" command not performed. 5063 The "TARGET" property value specifies the new location, and the 5064 "VQUERY" component specifies the old location. 5066 Restriction Table for the "REPLY" command of any "MOVE" command. 5068 move-reply = "BEGIN" ":" "VCALENDAR" CRLF 5069 calprops 5070 1*(move-vreply) 5071 "END" ":" "VCALENDAR" CRLF 5073 move-vreply = "BEGIN" ":" "VREPLY" CRLF 5074 move-id 5075 request-status 5076 "END" ":" "VREPLY" CRLF 5077 ; Where the id is appropriate for the 5078 ; type of object moved: 5079 ; 5080 ; VAGENDA = calid 5081 ; VCAR = carid 5082 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 5083 ; VQUERY = queryid 5084 ; ALARM = sequence 5085 ; An instance = uid recurid 5086 ; x-component = x-id 5087 ; 5088 move-id = ( calid / carid / uid / uid recurid 5089 / queryid / tzid / sequence / x-id) 5091 Example: moving the VAGENDA Nellis to Area-51 5093 C: Content-Type: text/calendar 5094 C: 5095 C: BEGIN:VCALENDAR 5096 C: VERSION:2.0 5097 C: PRODID:-//someone's prodid 5098 C: CMD:MOVE 5099 C: TARGET:Area-51 5100 C: BEGIN:VQUERY 5101 C: QUERY: SELECT * FROM VAGENDA WHERE CALID='Nellis' 5102 C: END:VQUERY 5103 C: END:VCALENDAR 5105 S: Content-Type: text/calendar 5106 S: 5107 S: BEGIN:VCALENDAR 5108 S: VERSION:2.0 5109 S: PRODID:-//someone's prodid 5110 S: TARGET:Area-51 5111 S: BEGIN:VREPLY 5112 S: CALID:Nellis 5113 S: REQUEST-STATUS: 2.0 5114 S: END:VREPLY 5115 S: END:VCALENDAR 5117 10.7 REPLY Response to a Command 5119 CMD: REPLY 5120 Purpose: The "REPLY" value to the "CMD" property is used to return 5121 the results of all other commands to the CUA. 5123 A CUA MUST send a "REPLY" command to a CS for any command a CS MAY 5124 send to the CUA. The "REPLY" command MUST BE implemented by all CUAs 5125 that support getting the "GET-CAPABILITY" command. 5127 A CS MUST send a "REPLY" command to a CUA for any command a CUA MAY 5128 send to the CS. The "REPLY" command MUST BE implemented by all CSs. 5130 Formal Definition: A "REPLY" command is defined by the following 5131 notation: 5133 reply-cmd = replyparam ":" "REPLY" 5135 replyparam = *( 5137 ; The 'id' parameter value MUST BE exactly the 5138 ; same as the value sent in the original 5139 ; CMD property. If the original CMD did 5140 ; not have an 'id' parameter, then the 'id' 5141 ; MUST NOT be supplied in the REPLY. 5143 id-param 5145 ; the following is optional, 5146 ; and MAY occur more than once 5148 / other-params 5150 ) 5152 10.8 SEARCH Command 5154 CMD: SEARCH 5156 Purpose: The "SEARCH" command is used to return selected components 5157 to the CUA. 5159 A CUA MAY send a "SEARCH" command to a CS. The "SEARCH" command MUST 5160 BE implemented by all CSs. 5162 The CS MUST NOT send a "SEARCH" command to any CUA. 5164 Formal Definition: A "SEARCH" command is defined by the following 5165 notation: 5167 search-cmd = searchparam ":" "SEARCH" 5169 searchparam = *( 5171 ; the following are optional, 5172 ; but MUST NOT occur more than once 5174 id-param 5175 / localize-param 5176 / latency-param 5178 ; the following MUST occur exactly once and only 5179 ; when the latency-param has been supplied and 5180 ; MUST NOT be supplied if the latency-param is 5181 ; not supplied. 5183 / action-param 5185 ; the following is optional, 5186 ; and MAY occur more than once 5188 / other-params 5190 ) 5192 Response: 5194 The data in each result set contains one or more iCalendar components 5195 composed of all the selected results enclosed in a single "VREPLY" 5196 component per "QUERY". 5198 Only "REQUEST-STATUS" property and the properties mentioned in the 5199 "SELECT" clause of the QUERY are included in the components. Each 5200 "VCALENDAR" component is tagged with the "TARGET" property. 5202 Searching for objects 5204 In the example below objects on March 10,1999 between 080000Z and 5205 190000Z are read. In this case only 4 properties for each objects are 5206 returned. Two calendars are specified. Only booked (vs scheduled) 5207 entries are to be returned (this example only selected VEVENT 5208 objects): 5210 C: Content-Type: text/calendar 5211 C: 5212 C: BEGIN:VCALENDAR 5213 C: VERSION:2.0 5214 C: PRODID:-//someone's prodid 5215 C: CMD:SEARCH 5216 C: TARGET:relcal2 5217 C: TARGET:relcal3 5218 C: BEGIN:VQUERY 5219 C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID 5220 C: FROM VEVENT 5221 C: WHERE DTEND >= '19990310T080000Z' 5222 C: AND DTSTART <= '19990310T190000Z' 5223 C: AND STATE() = 'BOOKED' 5224 C: END:VQUERY 5225 C: END:VCALENDAR 5227 The return values are subject to VCAR filtering. That is, if the 5228 request contains properties to which the UPN does not have access, 5229 those properties will not appear in the return values. If the UPN has 5230 access to at least one property of the component, but has been denied 5231 access to all properties called out in the request, the response will 5232 contain a single "REQUEST-STATUS" property indicating the error. 5234 Here the request was successful, however one of the "VEVENT" 5235 components contents were not accessible (4.1). 5237 S: Content-Type: text/calendar 5238 S: 5239 S: BEGIN:VCALENDAR 5240 S: TARGET:relcalid 5241 S: CMD:REPLY 5242 S: VERSION:2.0 5243 S: PRODID:-//someone's prodid 5244 S: BEGIN:VREPLY 5245 S: BEGIN:VEVENT 5246 S: REQUEST-STATUS:4.1 5247 S: END:VEVENT 5248 S: BEGIN:VEVENT 5249 S: REQUEST-STATUS:2.0 5250 S: UID:123 5251 S: DTEND:19990310T080000Z 5252 S: DSTART:19990310T190000Z 5253 S: SUMMARY: Big meeting 5254 S: END:VEVENT 5255 S: END:VREPLY 5256 S: END:VCALENDAR 5258 If the UPN has no access to any components at all, the response will 5259 simply be an empty data set. The response looks the same if there 5260 the particular components did not exist. 5262 S: Content-Type: text/calendar 5263 S: 5264 S: BEGIN:VCALENDAR 5265 S: VERSION:2.0 5266 S: PRODID:-//someone's prodid 5267 S: CMD:REPLY 5268 S: TARGET:ralcalid 5269 S: BEGIN:VREPLY 5270 S: REQUEST-STATUS:2.0 5271 S: END:VREPLY 5272 S: END:VCALENDAR 5274 If there are multiple targets, each iCalendar reply is contained 5275 within its own iCalendar object. 5277 Stored VQUERY can be used by specifying the property QUERYID instead 5278 of QUERY. 5280 10.8.1 Searching for VFREEBUSY 5282 For CSs that set the "CAPABILITY" "RECUR-EXPAND" property to "TRUE" 5283 and have the "VFREEBUSY" component in the "COMPONENTS" value in the 5284 "CAPABILITY" reply, the CS MUST dynamically create the results of a 5285 search for the "VFREEBUSY" component at search time when searching 5286 for STATE() = 'BOOKED' items. If searching for STATE() = 5287 'UNPROCESSED' items then the [iTIP] object are returned. For these 5288 CSs it is the the CS is responsibility and not the CUAs 5289 responsibility to provide the correct "VFREEBUSY" information for a 5290 calendar. If a CUA performs a "CREATE" "VFREEBUSY" the CS MUST 5291 return success and not store the "VFREEBUSY" component. 5293 For CSs that set the "CAPABILITY" "RECUR-EXPAND" property to "FALSE" 5294 and have the "VFREEBUSY" component in the "COMPONENTS" value in the 5295 "CAPABILITY" reply, a CUA MAY store the "VFREEBUSY" information on 5296 the CS. These CSs then MUST return a "VFREEBUSY" component calculated 5297 from the stored components. If no "VFREEBUSY" information is 5298 available for the "TARGET" calendar, then a "VFREEBUSY" with no 5299 blocked out time will be returned with a success code. A CUA sets the 5300 "VFREEBUSY" time on a those calendars by creating a "VFREEBUSY" 5301 component without a "METHOD" creating a "BOOKED" entry. 5303 If a CS does not set the "VFREEBUSY" value in the "COMPONENTS" 5304 "CAPABILITY" value, the CS does not support the "VFREEBUSY" component 5305 and all creation and searching for a "VFREEBUSY" component MUST fail. 5306 Examples of calendars that may be in this category are public event 5307 calendars that will never require scheduling with other UPNs. 5309 10.9 SET-LOCALE Command 5311 CMD: SET-LOCALE 5313 Purpose: The "SET-LOCALE" command is used to select the locale that 5314 will be used in error codes used in the "REQUEST-STATUS" property. 5316 A CUA MAY send a "SET-LOCALE" command to a CS. The SET-LOCALE command 5317 MUST BE implemented by all CSs. 5319 The CS MUST NOT send a "SET-LOCALE" command to any CUA. 5321 Formal Definition: A "SET-LOCALE" command is defined by the following 5322 notation: 5324 setlocale-cmd = setlocaleparam ":" "SET-LOCALE" 5326 setlocaleparam = *( 5328 ; the following are optional, 5329 ; but MUST NOT occur more than once 5331 id-param 5332 / localize-param 5333 / latency-param 5334 / setlocale-option 5336 ; the following MUST occur exactly once and only 5337 ; when the latency-param has been supplied and 5338 ; MUST NOT be supplied if the latency-param is 5339 ; not supplied. 5341 / action-param 5343 ; the following is optional, 5344 ; and MAY occur more than once 5346 / other-params 5348 setlocal-option = option-param newlocale 5350 newlocale = ; Any locale supplied in the initial [BEEP] 5351 ; "greeting" "localize" parameter and 5352 ; and any charset supported by the CS 5353 ; and listed in the DEFAULT-CHARSET property 5354 ; of the VCALSTORE. 5356 ) 5358 Examples: 5360 CMD:OPTIONS=en_US.UTF-8:SET-LOCALE 5361 CMD:OPTIONS=th_TH.ISO8859-11:SET-LOCALE 5362 CMD:OPTIONS=es_MX.ISO8859-1:SET-LOCALE 5364 Restriction Table for the "REPLY" command of any "SET-LOCALE" 5365 command. 5367 setlocale-reply = "BEGIN" ":" "VCALENDAR" CRLF 5368 calprops 5369 1*(setlocale-vreply) 5370 "END" ":" "VCALENDAR" CRLF 5372 setlocale-vreply = "BEGIN" ":" "VREPLY" CRLF 5373 request-status 5374 "END" ":" "VREPLY" CRLF 5376 10.10 TIMEOUT Command 5378 CMD: TIMEOUT 5380 Purpose: The "TIMEOUT" command is only sent after a command has been 5381 sent with a latency value set. When received it means the command 5382 could not be completed in the time allowed. 5384 Formal Definition: A "TIMEOUT" command is defined by the following 5385 notation: 5387 timeout-cmd = continueparam ":" "TIMEOUT" 5389 timeoutparam = *( 5391 ; the following are optional, 5392 ; but MUST NOT occur more than once 5394 id-param 5395 / localize-param 5397 / other-params 5399 ) 5401 10.11 Response Codes 5403 Numeric response codes are returned using the "REQUEST-STATUS" 5404 property. 5406 The format of these codes is described in [iCAL], and extend in 5407 [iTIP] and [iMIP]. The following describes new codes added to this 5408 set and how existing codes apply to CAP. 5410 At the application layer response codes are returned as the value of 5411 a "REQUEST-STATUS" property. The value type of this property is 5412 modified from that defined in [iCAL], in order to make the 5413 accompanying "REQUEST-STATUS" property text optional. 5415 Code Description 5416 -------------------------------------------------------------- 5417 2.0 Success. The parameters vary with the 5418 operation and are specified. 5420 2.0.3 In response to the client issuing an 5421 "abort" reply, this reply code indicates 5422 that any command currently underway was 5423 successfully aborted. 5425 3.1.4 Capability not supported. 5427 4.1 Calendar store access denied. 5429 6.1 Container not found. 5431 6.2 Attempt to create or modify an object 5432 such that it would overlap another object 5433 in either of the following two circumstances: 5435 (a) One of the objects has a TRANSP 5436 property set to OPAQUE-NOCONFLICT or 5437 TRANSPARENT-NOCONFLICT. 5439 (b) The calendar's ALLOW-CONFLICT 5440 property is set to FALSE. 5442 6.3 Bad args. 5444 6.4 Permission denied - VCAR restriction. 5445 A VCAR exists and the CS will not perform 5446 the operation. 5448 7.0 A timeout has occurred. The server was 5449 unable to complete the operation in the 5450 requested time. 5452 8.0 A failure has occurred in the CS 5453 that prevents the operation from 5454 succeeding. 5456 8.1 A query was performed and the query is 5457 too complex for the CS. The operation 5458 was not performed. 5460 8.2 Used to signal that an iCalendar object has 5461 exceeded the server's size limit 5463 8.3 A DATETIME value was too far in the future 5464 represented on this Calendar. 5466 8.4 A DATETIME value was too far in the past 5467 to be represented on this Calendar. 5469 8.5 An attempt was made to create a new 5470 object but the unique UID specified is 5471 already in use. 5473 9.0 An unrecognized command was received. 5474 Or an unsupported command was received. 5476 10.4 The operation has not been performed 5477 because it would cause the resources 5478 (memory, disk, CPU, etc) to exceed the 5479 allocated quota. 5481 -------------------------------------------------------------- 5483 11. Object Registration 5485 This section provides the process for registration of new or modified 5486 properties, parameters, commands, or other modifications, additions, 5487 or deletions to objects. 5489 11.1 Registration of New and Modified Entities 5491 New objects are registered by the publication of an IETF Request for 5492 Comment (RFC). Changes to a objects are registered by the publication 5493 of a revision to the RFC in a new RFC. 5495 11.2 Post the item definition 5497 The object description MUST BE posted to the new object discussion 5498 list: ietf-calendar@imc.org. 5500 11.3 Allow a comment period 5502 Discussion on a new object MUST BE allowed to take place on the list 5503 for a minimum of two weeks. Consensus MUST BE reached on the object 5504 before proceeding to the next step. 5506 11.4 Release a new RFC 5508 The new object will be submitted for publication as any other 5509 internet draft requesting RFC status. 5511 12. BEEP and CAP 5513 12.1 BEEP Profile Registration 5515 TBD 5517 12.2 BEEP Exchange Styles 5519 [BEEP] defines three styles of message exchange: 5521 MSG/ANS,ANS,...,NUL - For one to many exchanges. 5523 MSG/RPY - For one to one exchanges. 5525 MSG/ERR - For requests the cannot be processed due to an error. 5527 A CAP request, targeted at more than one containers, MAY use a one- 5528 to-many exchange, with a distinct answer associated with each target. 5529 CAP request targeted at a single container MAY use a one-to-one 5530 exchange or a one-to-many exchange. "MSG/ERR" MAY only be used when 5531 an error condition prevents the execution of the request on all the 5532 targeted calendars. 5534 13. IANA Considerations 5536 This memo defines IANA registered extensions to the attributes 5537 defined by iCalendar, as defined in [iCAL], and [iTIP]. 5539 IANA registration proposals for iCalendar and [iTIP] are to be mailed 5540 to the registration agent for the "text/calendar" [MIME] 5541 content-type, using the format 5542 defined in section 7 of [iCAL]. 5544 If the IESG approves this memo for publication, then the IANA 5545 registers the profile specified in Section 12.1, and selects an 5546 IANA-specific URI, e.g., http://iana.org/beep/cap/1.0. 5548 14. Security Considerations 5550 Access rights should be granted cautiously, consult Section 2.4.2 for 5551 a discussion of the subject. Without careful planning it is possible 5552 to open up access to a greater degree than desired. 5554 The "IDENTIFY" command should be carefully implemented as discussed 5555 in Section 6.1.3. 5557 In addition, since CAP is a profile of the [BEEP], consult [BEEP]'s 5558 Section 9 for a discussion of BEEP-specific security issues. 5560 Although service provisioning is a policy matter, at a minimum, all 5561 implementations must provide the following tuning profiles: 5563 for authentication: http://iana.org/beep/SASL/DIGEST-MD5 5565 for confidentiality: http://iana.org/beep/TLS (using the 5566 TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher) 5568 for both: http://iana.org/beep/TLS (using the 5569 TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher supporting client-side 5570 certificates) 5572 URIs 5574 [1] 5576 Authors' Addresses 5578 Doug Royer 5579 INET-Consulting.com 5580 1795 W. Broadway #266 5581 Idaho Falls, ID 83402 5582 US 5584 Phone: +1-866-594-8574 5585 Fax: +1-866-594-8574 5586 EMail: Doug@Royer.com 5587 URI: http://INET-Consulting.com 5589 George Babics 5590 Oracle 5591 2000 Peel Street 5592 Montreal, Quebec H3A 2W5 5593 CA 5595 Phone: +1-514-733-8500 x4201 5596 Fax: +1-514-733-8878 5597 EMail: George.Babics@Oracle.com 5599 Paul Hill 5600 Massachusetts Institute of Technology 5601 W92-172 5602 77 Massachusetts Avenue 5603 Cambridge, MA 02139 5604 US 5606 Phone: +1-617-253-0124 5607 Fax: +1-617-258-8736 5608 EMail: phb@mit.edu 5609 Steve Mansour 5610 AOL/Netscape 5611 466 Ellis Road 5612 Mountain View, CA 94043 5613 US 5615 Phone: +1-650-937-3351 5616 EMail: sman@netscape.com 5618 Appendix A. Acknowledgments 5620 The following have individuals were major contributors in the 5621 drafting and discussion of this memo: 5623 Harald Alvestrand, Christopher Apple, G. Barnes, ArentJan Banck, 5624 Martijn van Beers, Mario Bonin, Andrea Campi, Darryl Champagne, Damon 5625 Chaplin, Karen Chu, Shannon Clark, Andre Courtemanche, Dave Crocker, 5626 Alan Davies, Andrew Davison, Mark Davidson, Bernard Desruisseaux, 5627 Frank Dawson, Pat Egen, Greg FitzPatrick, illes Fortin, Ned Freed, 5628 Gary Frederick, Jagan Garimella, Graham Gilmore, Micah Gorrell, 5629 Lawrence Greenfield, Bertrand Guiheneuf, Olivier Gutknecht, Mike 5630 Hixson, Jeff Hodges, Paul Hoffman, Scott Hollenbeck, Alex Hoppman, 5631 Bruce Kahn, Lata Kannan, suchet singh khalsa, Dan Kohn, Patrice 5632 Lapierre, Jonathan Lennox, Lisa Lippert, Robert Lusardi, David Madeo, 5633 Bob Mahoney, Murata Makoto, Gary McGath, Libby Miller, Steve Miller, 5634 Bob Morgan, David Nicol, David Nusbaum, Pete O'Leary, Mark Paterson, 5635 Ralph Patterson, Eric R. Plamondon, Robert Ransdell, Jim Ray, 5636 Marshall Rose, JP Rosevear, Paul Sharpe, Richard Shusterman, Tony 5637 Small, John Smith, Benjamin Sonntag, John Stracke, Preston 5638 Stephenson, Alexander Taler, Peter Thompson, Steve Vinter, Mark Wahl, 5639 Dan Winship 5641 Appendix B. Bibliography 5643 [BEEP] Rose, M., "The Block Extensible Exchange Protocol Core", 5644 RFC 3080, March 2001 5645 ftp://ftp.isi.edu/in-notes/rfc3080.txt 5647 [BEEPTCP] Rose, M., "Mapping the BEEP Core onto TCP", RFC 3081, March 2001 5648 ftp://ftp.isi.edu/in-notes/rfc3081.txt 5650 [CHARREG] Freed, N., Postel, J., "IANA Charset Registration Procedures", 5651 RFC 2278, January 1998, 5652 ftp://ftp.isi.edu/in-notes/rfc2278.txt 5654 [CHARPOL] Alvestrand, H., "IETF Policy on Character Sets and Languages", 5655 RFC 2277, January 1998, 5656 ftp://ftp.isi.edu/in-notes/rfc2277.txt 5658 [GUIDE] Mahoney, B., Babics, G., Taler, A. "Guide to Internet 5659 Calendaring", RFC 3283, June 2002, 5660 ftp://ftp.isi.edu/in-notes/rfc3283.txt 5662 [iCAL] Dawson, F. and Stenerson, D., "Internet Calendaring and 5663 Scheduling Core Object Specification (iCalendar)", RFC 2445, 5664 November 1998 ftp://ftp.isi.edu/in-notes/rfc2445.txt 5666 [iTIP] Silverberg, S., Mansour, S., Dawson, F. and Hopson, R., 5667 "iCalendar Transport-Independent Interoperability Protocol 5668 (iTIP) Events, BusyTime, To-dos and Journal Entries", 5669 RFC 2446, November 1998 ftp://ftp.isi.edu/in-notes/rfc2446.txt 5671 [iMIP] Dawson, F., Mansour, S. and Silverberg, "iCalendar 5672 Message-Based Interoperability Protocol (iMIP)", RFC 2447, 5673 November 1998 ftp://ftp.isi.edu/in-notes/rfc2447.txt 5675 [MIME] Borenstein, N. and Freed, N., "Multipurpose Internet Mail 5676 Extensions (MIME) Part One: Format of Internet Message Bodies", 5677 RFC 2045, November 1996 5678 ftp://ftp.isi.edu/in-notes/rfc2045.txt 5680 [RFCWORDS] Bradner, S., "Key words for use in RFCs to Indicate 5681 Requirement Levels", RFC 2119, BCP 14, March 1997 5682 ftp://ftp.isi.edu/in-notes/rfc2119.txt 5684 [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", 5685 RFC 2222, October 1997 5686 ftp://ftp.isi.edu/in-notes/rfc2222.txt 5688 [SQL92] "Database Language SQL", ANSI/ISO/IEC 9075: 1992, 5689 aka ANSI X3.135-1992, aka FiPS PUB 127-2 5691 [SQLCOM] ANSI/ISO/IEC 9075:1992/TC-1-1995, Technical corrigendum 1 5692 to ISO/IEC 9075: 1992, also adopted as Amendment 1 to 5693 ANSI X3.135.1992 5695 [URLGUIDE] Masinter, L., Alvestrand, H., Zigmond, D., Petke, R., 5696 "Guidelines for new URL Schemes", RFC 2718, November 1999, 5697 ftp://ftp.isi.edu/in-notes/rfc2718.txt 5699 [URI] Berners-Lee, T., Fielding, R. and Masinter, L., "Uniform Resource 5700 Identifiers (URI): Generic Syntax", RFC 2396, August 1998 5701 ftp://ftp.isi.edu/in-notes/rfc2396.txt 5703 [URL] Berners-Lee, T, Masinter, L. and McCahil, M., "Uniform 5704 Resource Locators (URL)", RFC 1738, December 1994 5705 ftp://ftp.isi.edu/in-notes/rfc1738.txt 5707 [X509CRL] Housley, R., Ford, W., Polk, W., Solo, D. "Internet X.509 5708 Public Key Infrastructure, Certificate and CRL Profile", 5709 RFC 2459, January 1999, 5710 ftp://ftp.isi.edu/in-notes/rfc2459.txt 5712 Intellectual Property Statement 5714 The IETF takes no position regarding the validity or scope of any 5715 intellectual property or other rights that might be claimed to 5716 pertain to the implementation or use of the technology described in 5717 this document or the extent to which any license under such rights 5718 might or might not be available; neither does it represent that it 5719 has made any effort to identify any such rights. Information on the 5720 IETF's procedures with respect to rights in standards-track and 5721 standards-related documentation can be found in BCP-11. Copies of 5722 claims of rights made available for publication and any assurances of 5723 licenses to be made available, or the result of an attempt made to 5724 obtain a general license or permission for the use of such 5725 proprietary rights by implementors or users of this specification can 5726 be obtained from the IETF Secretariat. 5728 The IETF invites any interested party to bring to its attention any 5729 copyrights, patents or patent applications, or other proprietary 5730 rights which may cover technology that may be required to practice 5731 this standard. Please address the information to the IETF Executive 5732 Director. 5734 Full Copyright Statement 5736 Copyright (C) The Internet Society (2003). All Rights Reserved. 5738 This document and translations of it may be copied and furnished to 5739 others, and derivative works that comment on or otherwise explain it 5740 or assist in its implementation may be prepared, copied, published 5741 and distributed, in whole or in part, without restriction of any 5742 kind, provided that the above copyright notice and this paragraph are 5743 included on all such copies and derivative works. However, this 5744 document itself may not be modified in any way, such as by removing 5745 the copyright notice or references to the Internet Society or other 5746 Internet organizations, except as needed for the purpose of 5747 developing Internet standards in which case the procedures for 5748 copyrights defined in the Internet Standards process must be 5749 followed, or as required to translate it into languages other than 5750 English. 5752 The limited permissions granted above are perpetual and will not be 5753 revoked by the Internet Society or its successors or assignees. 5755 This document and the information contained herein is provided on an 5756 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 5757 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 5758 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 5759 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 5760 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 5762 Acknowledgment 5764 Funding for the RFC Editor function is currently provided by the 5765 Internet Society.