idnits 2.17.1 draft-ietf-calsch-cap-08.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 84 instances of too long lines in the document, the longest one being 7 characters in excess of 72. ** There is 1 instance 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 is 1 instance of lines with non-RFC2606-compliant FQDNs in the document. == There is 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 353: '... is, "events MUST BE scheduled in ...' RFC 2119 keyword, line 407: '... These extensions MUST start with "x-"...' RFC 2119 keyword, line 438: '...flict, the Realm SHOULD be postfixed w...' RFC 2119 keyword, line 443: '...endar store. It MUST BE unique within...' RFC 2119 keyword, line 465: '...ess. A CU's UPN MUST never be an e-ma...' (245 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 292 has weird spacing: '...hat has been ...' == Line 338 has weird spacing: '...able to diffe...' == Line 470 has weird spacing: '...lm. In it's ...' == Line 1856 has weird spacing: '...roperty woul...' == Line 1924 has weird spacing: '... know if "u...' == (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 (June 30, 2002) is 7970 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 5130 looks like a reference -- Missing reference section? 'BEEP' on line 5075 looks like a reference -- Missing reference section? 'RFC2119' on line 5200 looks like a reference -- Missing reference section? 'GUIDE' on line 265 looks like a reference -- Missing reference section? 'RFC1738' on line 5191 looks like a reference -- Missing reference section? 'RFC396' on line 446 looks like a reference -- Missing reference section? 'RFC2718' on line 446 looks like a reference -- Missing reference section? 'MIME' on line 5096 looks like a reference -- Missing reference section? 'CAP' on line 1250 looks like a reference -- Missing reference section? 'BEEPTCP' on line 909 looks like a reference -- Missing reference section? 'RFC 2459' on line 1039 looks like a reference -- Missing reference section? 'SQL92' on line 1323 looks like a reference -- Missing reference section? 'SQLCOM' on line 5243 looks like a reference -- Missing reference section? 'NOT' on line 1833 looks like a reference -- Missing reference section? 'RFC 2278' on line 2359 looks like a reference -- Missing reference section? 'RFC1521' on line 5187 looks like a reference -- Missing reference section? 'RFC2045' on line 5195 looks like a reference -- Missing reference section? 'RFC2222' on line 5204 looks like a reference -- Missing reference section? 'RFC2246' on line 5208 looks like a reference -- Missing reference section? 'RFC2392' on line 5212 looks like a reference -- Missing reference section? 'RFC2396' on line 5216 looks like a reference -- Missing reference section? 'RFC3080' on line 5233 looks like a reference -- Missing reference section? 'RFC3081' on line 5237 looks like a reference -- Missing reference section? 'SQL' on line 5240 looks like a reference -- Missing reference section? 'UNICODE' on line 5247 looks like a reference -- Missing reference section? 'US-ASCII' on line 5250 looks like a reference -- Missing reference section? 'CharEncoding' on line 5253 looks like a reference Summary: 5 errors (**), 0 flaws (~~), 11 warnings (==), 30 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Royer 3 Internet-Draft INET-Consulting 4 Expires: December 29, 2002 G. Babics 5 Steltor 6 P. Hill 7 MIT 8 S. Mansour 9 AOL/Netscape 10 June 30, 2002 12 Calendar Access Protocol (CAP) 13 draft-ietf-calsch-cap-08 15 Status of this Memo 17 This document is an Internet-Draft and is in full conformance with 18 all provisions of Section 10 of RFC2026. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 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 December 29, 2002. 38 Copyright Notice 40 Copyright (C) The Internet Society (2002). 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) . . . . . . . . . . . . . . . 13 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 . . . . . . . . 17 69 3. CAP Design . . . . . . . . . . . . . . . . . . . . . . . 20 70 3.1 System Model . . . . . . . . . . . . . . . . . . . . . . 20 71 3.2 Calendar Store Object Model . . . . . . . . . . . . . . 20 72 3.3 Protocol Model . . . . . . . . . . . . . . . . . . . . . 21 73 3.3.1 Use of BEEP, MIME and iCalendar . . . . . . . . . . . . 22 74 4. Security Model . . . . . . . . . . . . . . . . . . . . . 24 75 4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . . 24 76 4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . . 24 77 4.1.2 Anonymous Users and Authentication . . . . . . . . . . . 25 78 4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . . 25 79 4.2 Access Rights . . . . . . . . . . . . . . . . . . . . . 26 80 4.2.1 Access Control and NOCONFLICT . . . . . . . . . . . . . 26 81 4.2.2 Calendar Access Right (VCAR) . . . . . . . . . . . . . . 26 82 4.2.3 Predefined VCARs . . . . . . . . . . . . . . . . . . . . 27 83 4.2.4 Decreed VCARs . . . . . . . . . . . . . . . . . . . . . 28 84 4.3 CAP Session Identity . . . . . . . . . . . . . . . . . . 29 85 5. CAP URL and Calendar Address . . . . . . . . . . . . . . 31 86 6. New Components, Properties, Parameters, and Values . . . 33 87 6.1 Property Value Data Types . . . . . . . . . . . . . . . 33 88 6.1.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . . . 33 89 6.1.1.1 CAL-OWNERS() . . . . . . . . . . . . . . . . . . . . . . 39 90 6.1.1.2 CURRENT-TARGET() . . . . . . . . . . . . . . . . . . . . 39 91 6.1.1.3 [NOT] OWNER() . . . . . . . . . . . . . . . . . . . . . 39 92 6.1.1.4 SELF() . . . . . . . . . . . . . . . . . . . . . . . . . 39 93 6.1.1.5 STATE() . . . . . . . . . . . . . . . . . . . . . . . . 39 94 6.1.1.6 Ordering of Results . . . . . . . . . . . . . . . . . . 39 95 6.1.1.7 Date sorting order . . . . . . . . . . . . . . . . . . . 40 96 6.1.1.8 Use of single quote . . . . . . . . . . . . . . . . . . 41 97 6.1.1.9 Comparing DATE and DATE-TIME values . . . . . . . . . . 41 98 6.1.1.10 DTEND and DURATION . . . . . . . . . . . . . . . . . . . 42 99 6.1.1.11 [NOT] LIKE . . . . . . . . . . . . . . . . . . . . . . . 44 100 6.1.1.12 Empty vs. NULL . . . . . . . . . . . . . . . . . . . . . 44 101 6.1.1.13 [NOT] IN . . . . . . . . . . . . . . . . . . . . . . . . 45 102 6.1.1.14 DATE-TIME and TIME values in a WHEN clause . . . . . . . 46 103 6.1.1.15 Multiple contained components . . . . . . . . . . . . . 46 104 6.1.1.16 Example, Query by UID . . . . . . . . . . . . . . . . . 47 105 6.1.1.17 Query by Date-Time range . . . . . . . . . . . . . . . . 47 106 6.1.1.18 Query for all Unprocessed Entries . . . . . . . . . . . 47 107 6.1.1.19 Query with Subset of Properties by Date/Time . . . . . . 48 108 6.1.1.20 Query with Components and Alarms In A Range . . . . . . 49 109 6.1.2 UPN Value Type . . . . . . . . . . . . . . . . . . . . . 49 110 6.1.3 UPN-FILTER Value . . . . . . . . . . . . . . . . . . . . 50 111 6.2 New Parameter . . . . . . . . . . . . . . . . . . . . . 51 112 6.2.1 ENABLE Parameter . . . . . . . . . . . . . . . . . . . . 51 113 6.2.2 LOCAL Parameter . . . . . . . . . . . . . . . . . . . . 52 114 7. New Properties . . . . . . . . . . . . . . . . . . . . . 54 115 7.1 ALLOW-CONFLICT Property . . . . . . . . . . . . . . . . 54 116 7.2 CALID Property . . . . . . . . . . . . . . . . . . . . . 54 117 7.3 CALMASTER Property . . . . . . . . . . . . . . . . . . . 55 118 7.4 CARID Property . . . . . . . . . . . . . . . . . . . . . 56 119 7.5 CSID Property . . . . . . . . . . . . . . . . . . . . . 56 120 7.6 DECREED Property . . . . . . . . . . . . . . . . . . . . 57 121 7.7 DEFAULT-CHARSET Property . . . . . . . . . . . . . . . . 58 122 7.8 DEFAULT-LOCALE Property . . . . . . . . . . . . . . . . 58 123 7.9 DEFAULT-TZID Property . . . . . . . . . . . . . . . . . 59 124 7.10 DEFAULT-VCARS Property . . . . . . . . . . . . . . . . . 60 125 7.11 DENY Property . . . . . . . . . . . . . . . . . . . . . 61 126 7.12 EXPAND property . . . . . . . . . . . . . . . . . . . . 62 127 7.13 GRANT Property . . . . . . . . . . . . . . . . . . . . . 62 128 7.14 MAXDATE Property . . . . . . . . . . . . . . . . . . . . 63 129 7.15 MINDATE Property . . . . . . . . . . . . . . . . . . . . 64 130 7.16 NAME Property . . . . . . . . . . . . . . . . . . . . . 64 131 7.17 OWNER Property . . . . . . . . . . . . . . . . . . . . . 65 132 7.18 PERMISSION Property . . . . . . . . . . . . . . . . . . 66 133 7.19 QUERY property . . . . . . . . . . . . . . . . . . . . . 67 134 7.20 QUERYID property . . . . . . . . . . . . . . . . . . . . 67 135 7.21 REQUEST-STATUS property . . . . . . . . . . . . . . . . 68 136 7.22 RESTRICTION Property . . . . . . . . . . . . . . . . . . 69 137 7.23 SCOPE Property . . . . . . . . . . . . . . . . . . . . . 70 138 7.24 TARGET Property . . . . . . . . . . . . . . . . . . . . 71 139 7.25 TRANSP Property . . . . . . . . . . . . . . . . . . . . 71 140 8. New Components . . . . . . . . . . . . . . . . . . . . . 73 141 8.1 VAGENDA Component . . . . . . . . . . . . . . . . . . . 73 142 8.2 VCALSTORE Component . . . . . . . . . . . . . . . . . . 75 143 8.3 VCAR Component . . . . . . . . . . . . . . . . . . . . . 78 144 8.4 VRIGHT Component . . . . . . . . . . . . . . . . . . . . 81 145 8.5 VREPLY Component . . . . . . . . . . . . . . . . . . . . 82 146 8.6 VQUERY Component . . . . . . . . . . . . . . . . . . . . 82 147 9. Commands and Responses . . . . . . . . . . . . . . . . . 84 148 9.1 CAP Commands (CMD) . . . . . . . . . . . . . . . . . . . 84 149 9.1.1 Bounded Latency . . . . . . . . . . . . . . . . . . . . 85 150 9.1.2 ABORT Command . . . . . . . . . . . . . . . . . . . . . 88 151 9.1.3 CONTINUE Command . . . . . . . . . . . . . . . . . . . . 88 152 9.1.4 CREATE Command . . . . . . . . . . . . . . . . . . . . . 90 153 9.1.5 DELETE Command . . . . . . . . . . . . . . . . . . . . . 96 154 9.2 GENERATE-UID Command . . . . . . . . . . . . . . . . . . 99 155 9.3 GET-CAPABILITY Command . . . . . . . . . . . . . . . . . 101 156 9.4 IDENTIFY Command . . . . . . . . . . . . . . . . . . . . 105 157 9.5 MODIFY Command . . . . . . . . . . . . . . . . . . . . . 107 158 9.6 MOVE Command . . . . . . . . . . . . . . . . . . . . . . 112 159 9.7 REPLY Response to a Command . . . . . . . . . . . . . . 115 160 9.8 SEARCH Command . . . . . . . . . . . . . . . . . . . . . 116 161 9.9 SET-LOCALE Command . . . . . . . . . . . . . . . . . . . 119 162 9.10 TIMEOUT Command . . . . . . . . . . . . . . . . . . . . 121 163 9.11 Response Codes . . . . . . . . . . . . . . . . . . . . . 121 164 10. Object Registration . . . . . . . . . . . . . . . . . . 124 165 10.1 Registration of New and Modified Entities . . . . . . . 124 166 10.2 Post the item definition . . . . . . . . . . . . . . . . 124 167 10.3 Allow a comment period . . . . . . . . . . . . . . . . . 124 168 10.4 Release a new RFC . . . . . . . . . . . . . . . . . . . 124 169 11. BEEP and CAP . . . . . . . . . . . . . . . . . . . . . . 125 170 11.1 BEEP Profile Registration . . . . . . . . . . . . . . . 125 171 11.2 BEEP Exchange Styles . . . . . . . . . . . . . . . . . . 125 172 12. IANA Considerations . . . . . . . . . . . . . . . . . . 126 173 13. Security Considerations . . . . . . . . . . . . . . . . 127 174 Authors' Addresses . . . . . . . . . . . . . . . . . . . 128 175 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . 130 176 B. Bibliography . . . . . . . . . . . . . . . . . . . . . . 131 177 Full Copyright Statement . . . . . . . . . . . . . . . . 133 179 1. Introduction 181 This document specifies how a Calendar CUA interacts with a CS to 182 manage calendar information. In particular, it specifies how to 183 query, create, modify, and delete iCalendar components (e.g., events, 184 to-dos, or daily journal entries). It further specifies how to 185 search for available busy time information. Synchronization with 186 CUAs is not covered. 188 CAP is specified as a BEEP "profile". As such, many aspects of the 189 protocol (e.g., authentication and privacy) are provided within 190 [BEEP]. The protocol data units leverage the standard iCalendar 191 format [iCAL] to convey calendar related information. 193 CAP can also be used to store and fetch [iTIP] objects and when those 194 objects are used in this memo, they mean exactly the same as defined 195 in [iTIP]. When iCalendar objects are transfered between the 196 calendar user agent and a calendar server, some additional properties 197 and parameters may be added and the calendar user agent is 198 responsible for correctly generating iCalendar objects to non CAP 199 processes. 201 The definition of new components, properties, parameter's, and value 202 types are broken into two parts. The first part summarizes and 203 defined the new objects. The second part provides the detail and any 204 ABNF for those objects. 206 1.1 Formatting Conventions 208 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 209 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this 210 document are to be interpreted as described in [RFC2119]. 212 Calendaring and scheduling roles are referred to in quoted-strings of 213 text with the first character of each word in upper case. For 214 example, "Organizer" refers to a role of a "Calendar User" (CU) 215 within the protocol defined by [iTIP]. Calendar components defined 216 by [iCAL] are referred to with capitalized, quoted-strings of text. 217 All iCalendar components should start with the letter "V". For 218 example, "VEVENT" refers to the event calendar component, "VTODO" 219 refers to the to-do component and "VJOURNAL" refers to the daily 220 journal component. 222 Scheduling methods defined by [iTIP], are referred to with 223 capitalized, quoted-strings of text. For example, "REPLY" refers to 224 the method for replying to a "REQUEST". 226 CAP commands are referred to by upper-case, quoted-strings of text, 227 followed by the word "command". For example, "CREATE" command refers 228 to the command for creating a calendar entry, "SEARCH" command refers 229 to the command for reading calendar components. CAP Commands are 230 named using the "CMD" property. 232 Properties defined by this memo are referred to with capitalized, 233 quoted-strings of text, followed by the word "property". For 234 example, "ATTENDEE" property refers to the iCalendar property used to 235 convey the calendar address that has been invited to a "VEVENT" or 236 "VTODO" component. 238 Property parameters defined by this memo are referred to with 239 capitalized, quoted-strings of text, followed by the word 240 "parameter". For example, "PARTSTAT" parameter refers to the 241 iCalendar property parameter used to specify the participation status 242 of an attendee. Enumerated values defined by this memo are referred 243 to with capitalized text, either alone or followed by the word 244 "value". 246 In tables, the quoted-string text is specified without quotes in 247 order to minimize the table length. 249 1.2 Related Documents 251 Implementers will need to be familiar with several other memos that, 252 along with this one, describe the Internet calendaring and scheduling 253 standards. These documents are: 255 [iCAL] - (RFC2445) Which specifies the objects, data types, 256 properties and property parameters used in the protocols, along 257 with the methods for representing and encoding them. 259 [iTIP] - (RFC2446) Which specifies an interoperability protocol for 260 scheduling between different installations. 262 [iMIP] - (RFC2447) Which specifies the Internet email binding for 263 [iTIP]. 265 [GUIDE] - (draft/rfc...), a guide to implementers and describes the 266 elements of a calendaring system, how they interact with each 267 other, how they interact with end users, and how the standards and 268 protocols are used. 270 This memo does not attempt to repeat the specification of concepts 271 and definitions from these other memos. Where possible, references 272 are made to the memo that provides for the specification of these 273 concepts and definitions. 275 1.3 Definitions 277 BOOKED - An entry in the calendar store has one of three conceptual 278 states. It is "UNPROCESSED", "BOOKED" or marked as "DELETED". 279 How the implementation stores the state of any object is not a 280 protocol issues and is not discussed. An object can be said to be 281 booked, unprocessed, or marked for delete. 283 1. A "UNPROCESSED" scheduling entry has been stored in the 284 calendar store but has not been acted on by a Calendar User 285 (CU) or Calendar User Agent (CUA). All scheduled entries are 286 [iTIP] objects. All [iTIP] objects in the store are not 287 booked. To retrieve any [iTIP] object, simply do a query 288 asking for any objects that were stored with its state set to 289 "UNPROCESSED". 291 2. A booked entry is stored with the CREATE command. It is an 292 entry that has been acted on by a CU or CUA and there has 293 been a decision to store an object. To retrieve any booked 294 object, simply do a query asking for any objects that were 295 stored with its state set to "BOOKED". 297 3. A marked for delete component has its state set to DELETE. To 298 retrieve any deleted object, simply do a query asking for any 299 objects that were stored with its state set to "DELETED". By 300 default objects marked for delete are not returned. The CUA 301 must specifically ask for marked for delete objects. 303 Calendar - A collection of logically related objects or entities 304 each of which may be associated with a calendar date and possibly 305 time of day. These entities can include calendar properties or 306 components. In addition, a calendar might be related to other 307 calendars with the "RELATED-TO" property. A calendar is 308 identified by its unique calendar identifier. The [iCAL] defines 309 the initial calendar properties, calendar components and 310 properties that make up the contents of a calendar. 312 Calendar Access Protocol (CAP) - The standard Internet protocol that 313 permits a CUA to access and manipulate calendars residing on a 314 Calendar Store. (this memo) 316 Calendar Access Rights (VCAR) - The mechanism for specifying the CAP 317 operations ("PERMISSION") that a particular calendar user ("UPN") 318 is granted or denied permission to perform on a given calendar 319 object ("SCOPE"). The calendar access rights are specified with 320 the "VCAR" calendar components within a CS and calendar. 322 Calendar Address - Also See Calendar URL - they are one in the same 323 for CAP addresses. The calendar address can also be the value to 324 the "ATTENDEE" and "ORGANIZER" properties as defined in [iCAL]. 326 Calendar URL - A calendar URL is a URL defined in this memo that 327 specifies the address of a CS or Calendar. 329 Component- Any object that conforms to the iCalendar object format 330 and that is either defined in an internet draft, registered with 331 IANA, or is an experimental object that is prefixed with "x-". 332 Some types of components include calendars, events, to-dos, 333 journals, alarms, and time zones. A component consists of 334 properties and possibly other contained components. For example, 335 an event may contain an alarm component. 337 Properties - An attribute of a particular component. Some 338 properties are applicable to different types of components. For 339 example, the "DTSTART" property is applicable to "VEVENT", 340 "VTODO", "VJOURNAL" components. Other components are applicable 341 only to an individual type of calendar component. For example, 342 the "TZURL" property may only applicable to "VTIMEZONE" 343 components. 345 Calendar Identifier (CalID) - A globally unique identifier 346 associated with a calendar. Calendars reside within a CS. See 347 Qualified Calendar Identifier and Relative Calendar Identifier. 348 All CalIDs start with "cap:". 350 Calendar Policy - A CAP operational restriction on the access or 351 manipulation of a calendar. These may be outside of the scope of 352 the CAP protocol. An example of an implementation or site policy 353 is, "events MUST BE scheduled in unit intervals of one hour". 355 Calendar Property - An attribute of a calendar ("VAGENDA"). The 356 attribute applies to the calendar, as a whole. For example, the 357 "CALSCALE" property specifies the calendar scale (e.g., the 358 "GREGORIAN" value) for the whole calendar. 360 Calendar Server - An implementation of a Calendar Store that manages 361 one or more calendars. 363 Calendar Store (CS) - The data and service model definition for a 364 Calendar Store as defined in this memo. This memo does not 365 specify how the CS is implemented. 367 Calendar Store Identifier (CSID) - The globally unique identifier 368 for an individual CS. A CSID consists of the host and port 369 portions of a "Common Internet Scheme Syntax" part of a URL, as 370 defined by [RFC1738]. The CSID excludes any reference to a 371 specific calendar. 373 Calendar Store Components - Components maintained in a CS specify a 374 grouping of calendar store-wide information. 376 Calendar Store Properties - Properties maintained in a Calendar 377 Store calendar store-wide information. 379 Calendar User (CU) - An entity (often biological) that uses a 380 calendaring system. 382 Calendar User Agent (CUA) - The client application that a CU 383 utilizes to access and manipulate a calendar. 385 CAP Session - An open communication channel between a CUA and a 386 Calendar Server. If the CAP session is authenticated, the the CU 387 is "authenticated" and it is an "authenticated CAP session". 389 Contained Component / Contained Properties - A component or property 390 that is contained inside of another component. A "VALARM" 391 component for example may be contained inside of a "VEVENT" 392 component. And a "TRIGGER" property could be a contained property 393 of a "VALARM" component. 395 Delegate - A calendar user (sometimes called the delegatee) who has 396 been assigned participation in a scheduled component (e.g., 397 VEVENT) by one of the attendees in the scheduled component 398 (sometimes called the delegator). An example of a delegate is a 399 team member told to go to a particular meeting in place of another 400 Attendee who is unable to attend. 402 Designate - A calendar user who is authorized to act on behalf of 403 another calendar user. An example of a designate is an assistant. 405 Experiential - The CUA and CS may implement experimental extensions 406 to the protocol. They also might have experimental components, 407 properties, and parameters. These extensions MUST start with "x-" 408 (or "X-") and should include a vendor prefix (such as "x-myvendor- 409 "). There is no guarantee that these experimental extensions will 410 interoperate with other implementations. There is no guarantee 411 that they will not interact in unpredictable ways with other 412 vendor experimental extensions. Implementations should limit 413 sending those extensions to other implementations. 415 Object - A generic name for any component, property, parameter, or 416 value type to be used in iCalendar. 418 Overlapped Booking - A policy which indicates whether or not 419 components with a "TRANSP" property not set to "TRANSPARENT- 420 NOCONFLICT" or "OPAQUE-NOCONFLICT" value can overlap one another. 421 When the policy is applied to a calendar it indicates whether or 422 not the time span of any component (VEVENT, VTODO, ...) in the 423 calendar can overlap the time span of any other component in the 424 same calendar. When applied to an individual entry, it indicates 425 whether or not any other component's time span can overlap that 426 individual component. If the CS does not allow overlapped 427 booking, then the CS is unwilling to allow any overlapped bookings 428 within any calendar in the CS. 430 Owner - One or more CUs or UGs that are listed in the "OWNER" 431 property in a calendar. There can be more than one owner. The " 433 Qualified Calendar Identifier (Qualified CalID) - A CalID in which 434 both the scheme and csid of the CAP URI are present. 436 Realm - A collection of calendar user accounts, identified by a 437 string. The name of the Realm is only used in UPNs. In order to 438 avoid namespace conflict, the Realm SHOULD be postfixed with an 439 appropriate DNS domain name. (e.g., the foobar Realm could be 440 called foobar.example.com). 442 Relative Calendar Identifier (Relative CalID) - An identifier for an 443 individual calendar in a calendar store. It MUST BE unique within 444 a calendar store. A Relative CalID consists of the "URL path" of 445 the "Common Internet Scheme Syntax" portion of a URL, as defined 446 by [RFC396] and [RFC2718]. 448 Session Identity - A UPN associated with a CAP session. A session 449 gains an identity after successful authentication. The identity 450 is used in combination with VCAR to determine access to data in 451 the CS. 453 User Group (UG) - A collection of Calendar Users and/or User Groups. 454 These groups are expanded by the CS and may reside either locally 455 or in an external database or directory. The group membership may 456 be fixed or dynamic over time. 458 Username - A name which denotes a Calendar User within a Realm. 459 This is part of a UPN. 461 User Principal Name (UPN) - A unique identifier that denotes a CU or 462 a group of CU. A UPN is a RFC 822 compliant email address, with 463 exceptions listed below, and in most cases it is deliverable to 464 the CU. In some cases it is identical to the CU's well known 465 email address. A CU's UPN MUST never be an e-mail address that is 466 deliverable to a different person as there is no requirement that 467 a person's UPN MUST BE their e-mail address. A UPN is formatted 468 as a user name followed by "@" followed by a Realm in the form of 469 a valid, and unique, DNS domain name. The user name MUST BE 470 unique within the Realm. In it's simplest form it looks like 471 "user@example.com". 473 In certain cases a UPN will not be RFC 822 compliant. When 474 anonymous authentication is used, or anonymous authorization is 475 being defined, the special UPN "@" will be used. When 476 authentication MUST BE used, but unique identity MUST BE obscured, 477 a UPN of the form @DNS-domain-name may be used. For example, 478 "@example.com". 480 2. Additions to iCalendar 482 Several new components, properties, parameters, and value types are 483 added in CAP. This section summarizes those new objects. 485 This memo extends the properties that can go into 'calprops' as 486 defined in [iCAL] section 4.6 page 51 to allow iTIP objects 487 transmitted between a CAP aware CUA and the CS to contain the 488 "TARGET" and "CMD" properties. This memo does not address how a CUA 489 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 target / 504 iana-prop / 505 cmd / 507 ; These are optional, and may occur more 508 ; than once. 509 ; 510 x-prop 512 In addition a problem exists with the control of "VALARM" components 513 and their "TRIGGER" properties. A CU may wish to set their own alarm 514 (local alarms) on components. These local alarms are not to be 515 forwarded to other CUs, CUAs, or CSs as are the "SEQUENCE" property 516 and the "ENABLE" parameter. So for the protocol between a CUA and a 517 CS, the following changes apply to the CAP protocol from [iCAL] 518 section "4.6.6" page 67: 520 alarmc = "BEGIN" ":" "VALARM" CRLF 521 alarm-seq 522 iana-prop 523 (audioprop / dispprop / emailprop / procprop) 524 "END" ":" "VALARM" CRLF 526 alarm-seq = "SEQUENCE" alarmseqparam ":" integer CRLF 528 alarmseqparam = *( ";" xparam) 529 / ";" local-param 531 The CUA adds a "SEQUENCE" property to each "VALARM" component as it 532 books the component. This property along with the "LOCAL" and 533 "ENABLE" parameters allow the CUA to uniquely identify any VALARM in 534 any component. The CUA should remove those before forwarding to non 535 CAP aware CUAs (including iMIP CUAs). 537 In addition, if a CUA wished to ignore a "TRIGGER" property in a 538 "VALARM" that was supplied to it by the ORGANIZER, the CUA needs a 539 common way to tag that trigger as disabled. So for the protocol 540 between a CUA and a CS, the following is a modification to [iCAL] 541 section "4.8.6.3" page 127: 543 trigger = "TRIGGER" 1*(";" enable-param) (trigrel / trigabs) 545 Section 6.2.1 and Section 6.2.2. 547 These additions will be transmitted between a CS and a CAP aware CUA. 548 So the VERSION value will remain at "2.0" as no existing iTIP or iMIP 549 implementation will be effected. 551 2.1 New Value Types (summary) 553 UPN The UPN value type is text value type restricted to only UPN 554 values. (Section 6.1.2) 556 UPN-FILTER Like the UPN value type, but also includes filter rules 557 that allow wildcards. (Section 6.1.3) 559 CALQUERY The "CAL-QUERY" (Section 6.1.1) value type is a query syntax 560 that is used by the CUA to specify the rules that apply to a CAP 561 command. In the case of "SEARCH", the query language is used to 562 fetch objects from the CS. When used with "DELETE", the selected 563 objects are deleted from the CS. "CAL-QUERY" can also be used 564 with "MOVE" and "MODIFY". 566 2.1.1 New Parameters (summary) 568 ENABLE - 570 The "ENABLE" parameter in CAP is used to tag a "TRIGGER" property 571 in a component as disabled or enabled. This is used when a 572 scheduling request arrives and the CU wishes to ignore the trigger 573 time included. (Section 6.2.1). 575 Formal Definition: The "ENABLE" parameter is defined by the 576 following notation: 578 enable-param = "ENABLE" "=" ("TRUE" / "FALSE") 580 LOCAL - 582 The "LOCAL" parameter in CAP is used to tag a "SEQUENCE" property 583 in a "VALARM" to signify that a VALARM is local or to be 584 distributed. (Section 6.2.2). 586 For example, when inviting others to an event, the ORGANIZERs 587 booked VEVENT might contain VALARMs, and those VALARMS might be 588 'alarm be 5 minutes before the meeting'. However other ATTENDEEs, 589 may have to set their own VALARMs for the same event (assuming 590 they reply that they will be attending). So, by tagging the 591 VALARM as local the CUA MUST never forward those local VALARMs to 592 other CS's or CUAs. 594 The CUA can not simply delete any VALARMs from components where 595 the CU is not the ORGANIZER. If it did, any [iTIP] "COUNTER" 596 would result in the ORGANIZER thinking that the ATTENDEE wished to 597 also counter with removing those VALARMs. And in addition, any 598 update to an existing component would re-create those VALARMs in 599 the ATTENDEEs CS. 601 Formal Definition: The "LOCAL" parameter is defined by the 602 following notation: 604 local-param = "LOCAL" "=" ("TRUE" / "FALSE") 606 2.1.2 New Properties (summary) 608 ALLOW-CONFLICT - Some entries in a calendar might not be valid if 609 other entries were to allowed to overlap the same time span. 610 Renting a car for example. It would not make sense to allow two 611 reservations for the same car at the same time. The "ALLOW- 612 CONFLICT" property takes a boolean value. If FALSE, then 613 conflicts are not allowed. (Section 7.1) 615 CSID - Each CS needs its own unique identifier. The "CSID" property 616 is the official unique identifier for the CS. If the BEEP 617 'serverName' attribute was suppled in the BEEP 'start' message, 618 then the CSID will be mapped to the virtual host name supplied and 619 the host name part of the CSID MUST BE the same as the 620 'serverName' value. This allows one CS implementation to service 621 multiple virtual hosts. CS's are not required to support virtual 622 hosting. If a CS does not support virtual hosting then it must 623 ignore the BEEP 'serverName'. (Section 7.5) 625 CALID - Each calendar within a CS needs to be uniquely identifiable. 626 The "CALID" property identifies a unique calendar within a CS. It 627 can be a full CALID or a relative CALID. (Section 7.2) 629 CALMASTER - The "CALMASTER" property specifies the contact 630 information for the CS. (Section 7.3) 632 CARID - Access rights can be saved and fetched by unique ID - the 633 "CARID". (Section 7.4) 635 CMD - The enumerated list of CAP commands and the options for those 636 commands, as well as replies are transmitted using the "CMD" 637 property. (Section 9.1) 639 DECREED - Some access rights are not changeable by the CUA. When 640 that is the case, the "DECREED" property value in the "VCAR" will 641 be TRUE. (Section 7.6) 643 DEFAULT-CHARSET - The list of charsets supported by the CS. The 644 first entry MUST BE the default for the CS. (Section 7.7) 646 DEFAULT-LOCALE - The list of locales supported by the CS. The first 647 entry in the list is the default locale. (Section 7.8) 649 DEFAULT-TZID - This is the list of known timezones supported. The 650 first entry is the default. (Section 7.9) 652 DEFAULT-VCARS - A list of the CARIDs that will be used to create new 653 calendars. (Section 7.10) 655 DENY - The UPNs listed in the "DENY" property of a "VCAR" will 656 denied access as described in the "VRIGHT" component. (Section 657 7.11) 659 EXPAND - This property tells the CS if the query reply should expand 660 components into multiple instances. The default is FALSE. 661 (Section 7.12) 663 GRANT - The UPNs listed in the "GRANT" property of a "VCAR" will 664 allowed access as described in the "VRIGHT" component. (Section 665 7.13) 667 MAXDATE - The maximum date supported by the CS. (Section 7.14) 669 MINDATE - The minimum date supported by the CS. (Section 7.15) 671 NAME - Several storeable components such as "VCAR" and "VQUERY" may 672 have the "NAME" property contained in them to describe in a 673 various locals the purpose of the component. Components may have 674 multiple "NAME" properties. (Section 7.16) 676 OWNER - Each calendar has at least one "OWNER". (xref 677 target="OWNER"/>) Related to the "OWNER()" (Section 6.1.3) query 678 clause. 680 PERMISSION - This property specifies the permission being granted or 681 denied. Examples are "READ" and "MODIFY". (Section 7.18) 683 QUERY - Use to hold the CAL-QUERY (Section 7.19) for the component. 685 QUERYID - A unique id for a stored query. (Section 7.20) 687 REQUEST-STATUS - The [iCAL] "REQUEST-STATUS" property is extended to 688 include new error numbers. (Section 7.21) 690 RESTRICTION - In the final check when granting calendar access 691 requests, the CS test the results to the value of the 692 "RESTRICTION" property in the corresponding "VRIGHT" component to 693 determine if the access meets that restriction. (Section 7.22) 695 SCOPE - The "SCOPE" property is used in "VRIGHT"s component to 696 select the subset of data that may be acted upon when checking 697 access rights. (Section 7.23) 699 TARGET - The new VCALENDAR property "TARGET" (Section 7.24) used to 700 specify which calendar(s) will be the subject of the CAP command. 702 TRANSP - This is a modification the the [iCAL] TRANSP property and 703 it allows more values. (Section 7.25) 705 2.1.3 New Components (summary) 707 VAGENDA - CAP allows the fetching and storing of the entire contents 708 of a calendar. The "VCALENDAR" object is not sufficient to 709 encapsulate all of the needed data that describes a calendar. The 710 VAGENDA object is the encapsulating object for an entire calendar. 711 (Section 8.1) 713 VCALSTORE - Each CS contains one or more calendars (VAGENDAs), the 714 VCALSTORE object is the encapsulating object that can hold all of 715 the "VAGENDA"s along with any components and properties that are 716 unique to the store level. (Section 8.2) 718 VCAR - Calendar Access Rights are specified and encapsulated in the 719 new iCalendar "VCAR" (Section 8.3) component. The "VCAR" 720 component holds some new properties and at least one "VRIGHT" 721 component. 723 VRIGHT - (Section 8.4) This component encapsulates a set of 724 instructions to the CS that define the rights or restrictions 725 needed. 727 VREPLY - (Section 8.5) This component encapsulates a set of data 728 that can consist of an arbitrary amounts of properties and 729 components. Its contents is dependent on the command that was 730 issued. 732 VQUERY - The search operation makes use of a new component, called 733 "VQUERY" (Section 8.6) and a new value type "CAL-QUERY" (Section 734 6.1.1). "VQUERY" is used to fetch objects from the CS. 736 2.2 Relationship of RFC-2446 (ITIP) and CAP 738 [iTIP] describes scheduling methods which result in indirect 739 manipulation of components. In CAP, the "CREATE" command is used to 740 deposit entities into the store. Other CAP commands such as 741 "DELETE", "MODIFY" and "MOVE" provide direct manipulation of 742 components. In the CAP calendar store model, scheduling messages are 743 conceptually kept separate from other components by their state. 745 All scheduling operations and are as define in [iTIP]. This memo 746 makes no changes to any of the workflow described in [iTIP]. In this 747 memo when referring to the presence of the "METHOD" property in an 748 object is the same as saying an [iTIP] object. 750 A CUA may create a "BOOKED" entry by depositing a iCalendar object 751 into the store. This is done by depositing an object that does not 752 have a "METHOD" property. The CS then knows to set the state of the 753 object to "BOOKED". If the object has a "METHOD" property then the 754 object is stored in the "UNPROCESSED" state. 756 If existing "UNPROCESSED" objects exist in the CS for the same UID 757 then a CUA may wish to consolidate the objects in to one "BOOKED" 758 object. The CUA would fetch the "UNPROCESSED" objects for that UID 759 and process them in the CUA as described in [iTIP]. Then if the CUA 760 wished to book the UID, then the CUA would issue a "CREATE" command 761 to create the new "BOOKED" object in the CS, followed by a "DELETE" 762 command to remove any related old [iTIP] objects from the CS. And it 763 might also involve having the CUA send some [iMIP] objects or 764 contacting other CS's and performing CAP operations on those CSs. 766 The CUA could also decide not to book the object. In which case the 767 "UNPROCESSED" objects could be deleted from the CS. Or the CUA could 768 set those object to the marked for delete. 770 The marked for delete state is used to keep the object around so that 771 the CUA can process duplicate requests automatically. If a duplicate 772 [iTIP] object is deposited into the CS and there exists identical 773 marked for delete objects, then a CUA acting on behalf of the "OWNER" 774 can silently drop those duplicate entries. 776 Another purpose for the marked for delete state is so that when a CU 777 decides they do not wish to have the object show in their calendar, 778 the CUA can book the object, changing the PARTSTAT parameter to 779 "DECLINED" in the "ATTENDEE" property that corresponds to their UPN. 780 Perform an iTIP processing such as sending back a decline. Then mark 781 that object as marked for delete. Their CUA might be configurable to 782 automatically drop any updates for that object knowing the CU has 783 already declined. 785 When synchronizing with multiple CUAs, the marked for delete state 786 could be used to inform the synchronization process that an object is 787 to be deleted. How synchronization is done is not specified in this 788 memo. 790 Several "UNPROCESSED" entries can be in the CS for the same UID. 791 However once consolidated, then only one entry exists in the CS and 792 that is the booked object. The others MUST BE removed, or have their 793 state changed to "DELETED". 795 There MUST NOT BE more than one "BOOKED" entry in a calendar for the 796 same "UID". 798 For example, if you were on vacation, you could have a REQUEST to 799 attend a meeting and several updates to that meeting. Your CUA would 800 have to "SEARCH" them out of the CS using CAP, process them, 801 determine what the final state of the object from a possible 802 combination of user input and programmed logic. Then the CUA would 803 instruct the CS to create a new booked entry from the consolidated 804 results. Finally, the CUA could do a "DELETE" or change their state 805 to "DELETED" for all of these now old scheduling requests in the CS. 806 See [iTIP] for details on resolving multiple [iTIP] scheduling 807 entries. 809 3. CAP Design 811 3.1 System Model 813 The system model describes the high level components of a calendar 814 system and how they interact with each other. 816 CAP is used by a "Calendar User Agent" (CUA) to send commands to and 817 receive responses from a "Calendar Server" (CS). 819 The CUA prepares a [MIME] encapsulated command, sends it to the CS, 820 and receives a [MIME] encapsulated response. The calendaring related 821 information within these messages are represented by iCalendar 822 objects. 824 There are two distinct protocols in operation to accomplish this 825 exchange. [BEEP] is the transport protocol is used to move these 826 encapsulations between a CUA and a CS. CAP's [BEEP] profile defines 827 the application protocol where the content and semantics of the 828 messages sent between the CUA and the CS are specified. 830 3.2 Calendar Store Object Model 832 [iCAL] describes components such as events, todos, alarms, and 833 timezones. [CAP] requires additional object infrastructure. In 834 particular, detailed definitions of the containers for events and 835 todos (calendars), access control objects, and a query language. 837 The conceptual model for a calendar store is shown below. The 838 calendar store (VCALSTORE - Section 8.2) contains "VCAR"s, "VQUERY"s, 839 "VTIMEZONE"s, "VAGENDA"s and calendar store properties. 841 Calendars (VAGENDAs) contain "VEVENT"s, "VTODO"s, "VJOURNAL"s, 842 "VCAR"s, "VTIMEZONE"s, "VFREEBUSY", "VQUERY"s and calendar 843 properties. 845 The component "VCALSTORE" is used to denote the a root of the 846 calendar store and contains all of the calendars. 848 Calendar Store 850 VCALSTORE 851 | 852 +-- properties 853 +-- VCARs 854 +-- VQUERYs 855 +-- VTIMEZONEs 856 +-- VAGENDAs 857 | | 858 | +--properties 859 | +--VEVENTs 860 | | | 861 | | +--VALARMs 862 | +--VTODOs 863 | | | 864 | | +--VALARMs 865 | +--VJOURNALs 866 | +--VCARs 867 | +--VTIMEZONEs 868 | +--VQUERYs 869 | +--VFREEBUSY 870 | | 871 | | ... 872 . 873 . 874 +-- VAGENDAs 875 . . 876 . . 877 . . 879 Calendars within a Calendar Store are identified by their unique 880 Relative CALID. 882 3.3 Protocol Model 884 CAP uses beep as the transport and authentication protocol. 886 The initial charset MUST BE UTF-8 for the session in an unknown 887 locale. If the CS supplied the BEEP 'localize' attribute in the BEEP 888 'greeting' then the CUA may tell the CS to switch locales for the 889 session by issuing the "SET-LOCALE" CAP command and supplying one of 890 the locales supplied by the BEEP 'localize' attribute. If supplied 891 the first locale supplied in the BEEP 'localize' attribute MUST BE 892 the default locale of the CS. The locale is switched only after a 893 successful reply. 895 The "DEFAULT-CHARSET" property of the CS contains the list of 896 charsets supported by the CS with the first value being the default 897 for new calendars. If the CUA wishes to switch to one of those 898 charsets for the session, the CUA issues the "SET-LOCALE" CAP 899 command. The CUA would have to first perform a "GET-CAPABILITY" 900 command on the CS to get the list of charsets supported by the CS. 901 The charset is switched only after a successful reply. 903 The CUA may switch locales and charsets as needed. There is no 904 requirement that a CS support multiple locales or charsets. 906 3.3.1 Use of BEEP, MIME and iCalendar 908 CAP uses the BEEP application protocol over TCP. (refer to [BEEP] 909 and [BEEPTCP] for more information). The default port that the 910 Calendar Server listens for connections is on user port 1026. 912 The BEEP data exchanged in CAP is a iCalendar MIME content that fully 913 conforms to [iCAL] iCalendar format. 915 This example tells the CS to generate and return 10 UIDs to be used 916 by the CUA. (Note throughout this memo, 'C:' refers to what the CUA 917 sends, 'S:' refers to what the CS sends, 'I:' refers to what the 918 initiator sends, and 'L:' refers to what the listener sends. Where 919 initiator and responder are used as defined in [BEEP].) 921 C: MSG 1 2 . 432 62 922 C: Content-Type: text/calendar 923 C: 924 C: BEGIN:VCALENDAR 925 C: VERSION:2.0 926 C: PRODID:-//someone's prodid 927 C: CMD;ID=unique-per-cua-123;OPTIONS=10:GENERATE-UID 928 C: END:VCALENDAR 929 C: END 931 NOTE: The following examples will not include the BEEP header and 932 footer information. Only the iCalendar objects that are sent between 933 the CUA and CS will be shown as the BEEP payload boundaries are 934 independent of CAP. 936 The commands listed below are used to manipulate or access the data 937 on the calendar store: 939 ABORT - Sent to halt the processing of any command except ABORT. 940 (Section 9.1.2) 942 CONTINUE - Sent to continue processing a command that has had its 943 specified timeout time reached. (Section 9.1.3) 945 CREATE - Create a new object on the CS. This can be implied for 946 iTIP objects. Initiated by the CUA only. (Section 9.1.4) 948 SET-LOCALE - Tell the CS to use any named locale and charset 949 supplied. Initiated by the CUA only. (Section 9.9) 951 DELETE - Delete objects from the CS. Initiated by the CUA only. 952 Can also be used to mark a object for deletion. (Section 9.1.5) 954 GENERATE-UID - Generate one or more unique ids. Initiated by the 955 CUA only. (Section 9.2) 957 GET-CAPABILITY - Query the capabilities the other end point of the 958 session. (Section 9.3) 960 IDENTIFY - Set a new identity for the session. Initiated by the CUA 961 only. (Section 9.4) 963 MODIFY - Modify components. Initiated by the CUA only. (Section 964 9.5) 966 MOVE - Move components to another container. Initiated by the CUA 967 only. (Section 9.6) 969 REPLY - When replying to a command, the "CMD" value will be set to 970 "REPLY" so that it will not be confused with a new command. 971 (Section 9.7) 973 SEARCH - Search for components. Initiated by the CUA only. 974 (Section 9.8) 976 TIMEOUT - Sent when a specified amount of time has lapsed and a 977 command has not finished. (Section 9.10) 979 4. Security Model 981 The BEEP transport performs all session authentication. 983 4.1 Calendar User and UPNs 985 A Calendar User (CU) is an entity that can be authenticated. It is 986 represented in CAP as a UPN, which is a key part of access rights. 987 The UPN representation is independent of the authentication mechanism 988 used during a particular CUA/CS interaction. This is because UPNs 989 are used within VCARs. If the UPN were dependent on the 990 authentication mechanism, a VCAR could not be consistently evaluated. 991 A CU may use one mechanism while using one CUA but the same CU may 992 use a different authentication mechanism when using a different CUA, 993 or while connecting from a different location. 995 The user may also have multiple UPNs for various purposes. 997 Note that the immutability of the user's UPN may be achieved by using 998 SASL's authorization identity feature. (The transmitted 999 authorization identity may be different than the identity in the 1000 client's authentication credentials.) [SASL, section 3]. This also 1001 permits a CU to authenticate using their own credentials, yet request 1002 the access privileges of the identity for which they are proxying 1003 SASL. Also, the form of authentication identity supplied by a 1004 service like TLS may not correspond to the UPNs used to express a 1005 server's access rights, requiring a server specific mapping to be 1006 done. The method by which a server determines a UPN, based on the 1007 authentication credentials supplied by a client, is implementation 1008 specific. See [BEEP] for authentication details; [BEEP] relies on 1009 SASL. 1011 4.1.1 UPNs and Certificates 1013 When using X.509 certificates for purposes of CAP authentication, the 1014 UPN should appear in the certificate. Unfortunately there is no 1015 single correct guideline for which field should contain the UPN. 1017 From RFC-2459, section 4.1.2.6 (Subject): 1019 If subject naming information is present only in the subjectAlt- 1020 Name extension (e.g., a key bound only to an email address or 1021 URI), then the subject name MUST be an empty sequence and the 1022 subjectAltName extension MUST BE critical. 1024 Implementations of this specification MAY use these comparison 1025 rules to process unfamiliar attribute types (i.e., for name 1026 chaining). This allows implementations to process certificates 1027 with unfamiliar attributes in the subject name. 1029 In addition, legacy implementations exist where an RFC 822 name is 1030 embedded in the subject distinguished name as an EmailAddress 1031 attribute. The attribute value for EmailAddress is of type 1032 IA5String to permit inclusion of the character '@', which is not 1033 part of the PrintableString character set. EmailAddress attribute 1034 values are not case sensitive (e.g., "fanfeedback@redsox.com" is 1035 the same as "FANFEEDBACK@REDSOX.COM"). 1037 Conforming implementations generating new certificates with 1038 electronic mail addresses MUST use the rfc822Name in the subject 1039 alternative name field (see sec. 4.2.1.7 of [RFC 2459]) to 1040 describe such identities. Simultaneous inclusion of the 1041 EmailAddress attribute in the subject distinguished name to 1042 support legacy implementations is deprecated but permitted. 1044 Since no single method of including the UPN in the certificate will 1045 work in all cases, CAP implementations MUST support the ability to 1046 configure what the mapping will be by the CS administrator. 1047 Implementations MAY support multiple mapping definitions, for 1048 example, the UPN may be found in either the subject alternative name 1049 field, or the UPN may be embedded in the subject distinguished name 1050 as an EmailAddress attribute. 1052 Note: If a CS or CUA is validating data received via iMIP, if the 1053 "ORGANIZER" or "ATTENDEE" property said (e.g.) "ATTENDEE;CN=Joe 1054 Random User:MAILTO:juser@example.com" then the email address should 1055 be checked against the UPN. This is so the "ATTENDEE" property 1056 cannot be changed to something misleading like "ATTENDEE;CN=Joe 1057 Rictus User:MAILTO:jrictus@example.com" and have it pass validation. 1058 Note that it is the email addresses that miscompare, the CN 1059 miscompare is irrelevant. 1061 4.1.2 Anonymous Users and Authentication 1063 Anonymous access is often desirable. For example an organization may 1064 publish calendar information that does not require any access control 1065 for viewing or login. Conversely, a user may wish to view 1066 unrestricted calendar information without revealing their identity. 1068 4.1.3 User Groups 1070 A User Group is used to represent a collection of CUs or other UGs 1071 that can be referenced in VCARs. A UG is represented in CAP as a 1072 UPN. The CUA cannot distinguish between a UPN that represents a CU 1073 or a UG. 1075 UGs are expanded as necessary by the CS. The CS MAY expand a UG 1076 (including nested UGs) to obtain a list of unique CUs. Duplicate 1077 UPNs are filtered during expansion. 1079 How the UG expansion is maintained across commands is implementation 1080 specific. A UG may reference a static list of members, or it may 1081 represent a dynamic list. Operations SHOULD recognize changes to UG 1082 membership. 1084 CAP does not define commands or methods for managing UGs. 1086 4.2 Access Rights 1088 Access rights are used to grant or deny access to calendars, 1089 components, properties, and parameters in a CS to a CU. CAP defines 1090 a new component type called a Calendar Access Right (VCAR). 1091 Specifically, a "VCAR" component grants, or denies, UPNs the right to 1092 read and write components, properties, and parameters on calendars 1093 within a CS. 1095 The VCAR model does not put any restriction on the sequence in which 1096 the object and access rights are created. That is, an object 1097 associated with a particular VCAR might be created before or after 1098 the actual VCAR is defined. In addition, the VCAR and VEVENT 1099 definition might be created in the same iCalendar object and passed 1100 together in a single object. 1102 All rights MUST BE denied unless specifically granted. 1104 If two rights specified in VCAR components are in conflict, the right 1105 that denies access always takes precedence over the right that grants 1106 access. Any attempt to create a VCAR that conflicts with an 1107 immutable VCAR must fail. 1109 4.2.1 Access Control and NOCONFLICT 1111 The TRANSP property can take on values "TRANSPARENT-NOCONFLICT" and 1112 "OPAQUE-NOCONFLICT" that prohibit other components from overlapping 1113 it. This setting overrides access. The "ALLOW-CONFLICT" CS, 1114 Calendar or component setting may also prevent overlap, returning an 1115 error code "6.3". 1117 4.2.2 Calendar Access Right (VCAR) 1119 Access rights within CAP are specified with the "VCAR" component, 1120 "RIGHTS" value type and the "GRANT", "DENY" and "CARID" properties. 1122 Properties within an iCalendar object are unordered. This also is 1123 the case for the "VCAR" properties. 1125 4.2.3 Predefined VCARs 1127 Predefined calendar access CARIDs that MUST BE implemented are: 1129 CARID:READBUSYTIMEINFO - Specifies the "GRANT" and "DENY" rules that 1130 allow UPNs to read "VFREEBUSY" components. An example definition 1131 for this VCAR is: 1133 BEGIN:VCAR 1134 CARID:READBUSYTIMEINFO 1135 BEGIN:VRIGHT 1136 GRANT:* 1137 PERMISSION:READ 1138 SCOPE:SELECT * FROM VFREEBUSY 1139 END:VRIGHT 1140 END:VCAR 1142 CARID:REQUESTONLY - Specifies the "GRANT" and "DENY" rules to UPNs 1143 other than the owner of the calendar the ability to write new 1144 objects with the property "METHOD" property set to the "REQUEST" 1145 value. This CARID allows the owner to specify which UPNs are 1146 allowed to make scheduling requests. An example definition for 1147 this VCAR is: 1149 BEGIN:VCAR 1150 CARID:REQUESTONLY 1151 BEGIN:VRIGHT 1152 GRANT:NON OWNER() 1153 PERMISSION:CREATE 1154 RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST' 1155 END:VRIGHT 1156 END:VCAR 1158 CARID:UPDATEPARTSTATUS - Grants to authenticated users the right to 1159 modify the instances of the "ATTENDEE" property set to one of 1160 their calendar addresses in any components for any booked 1161 component containing a "ATTENDEE" property. This allows (or 1162 denies) a CU the ability to update their own participation status 1163 in a calendar where they might not otherwise have MODIFY access. 1164 They are not allowed to change the "ATTENDEE" property value. An 1165 example definition for this VCAR is (This example only effects the 1166 "VEVENT" components): 1168 BEGIN:VCAR 1169 CARID:UPDATEPARTSTATUS 1170 BEGIN:VRIGHT 1171 GRANT:* 1172 PERMISSION:MODIFY 1173 SCOPE:SELECT ATTENDEE FROM VEVENT 1174 WHERE ATTENDEE = SELF() 1175 AND ORGANIZER = CURRENT-TARGET() 1176 AND STATE() = 'BOOKED' 1177 RESTRICTION:SELECT * FROM VEVENT 1178 WHERE ATTENDEE = SELF() 1179 END:VRIGHT 1180 END:VCAR 1182 CARID:DEFAULTOWNER - Grants to any owner the permission they have 1183 for the target. An example definition for this VCAR is: 1185 BEGIN:VCAR 1186 CARID:DEFAULTOWNER 1187 BEGIN:VRIGHT 1188 GRANT:OWNER() 1189 PERMISSION:* 1190 SCOPE:SELECT * FROM VAGENDA 1191 END:VRIGHT 1192 END:VCAR 1194 4.2.4 Decreed VCARs 1196 A CS MAY choose to implement and allow persistent immutable VCARs 1197 that may be configured by the CS administrator. A reply from the CS 1198 may dynamically create VCARs that are decreed depending on the 1199 implementation. To the CUA any "VCAR" component with the "DECREED" 1200 property set to "TRUE" can not be changed by the currently 1201 authenticated UPN, and depending on the implementation and other 1202 VCARs; might not be able to be changed by any UPN using CAP, and 1203 never when the CUA gets a "DECREED:TRUE" VCAR. 1205 When a user attempts to modify or override a decreed VCAR an error 1206 will be returned indicating that the user has insufficient 1207 authorization to perform the operation. The reply to the CUA MUST BE 1208 the same as if a non-decreed VCAR caused the failure. 1210 The CAP protocol does not define the semantics used to initially 1211 create a decreed VCAR. This administrative task is outside the scope 1212 of the CAP protocol. 1214 For example; an implementation or a CS administrator may wish to 1215 define a VCAR that will always allow the calendar owners to have full 1216 access to their own calendars. 1218 Decreed VCARs MUST BE readable by the calendar owner in standard VCAR 1219 format. 1221 4.3 CAP Session Identity 1223 A BEEP session has an associated set of authentication credentials, 1224 from which is derived a UPN. This UPN is the identity of the CAP 1225 session, and is used to determine access rights for the session. 1227 The CUA may change the identity of a CAP session by calling the 1228 "IDENTIFY" command. The Calendar Server only permits the operation 1229 if the session's authentication credentials are good for the 1230 requested identity. The method of checking this permission is 1231 implementation dependent, but may be thought of as a mapping from 1232 authentication credentials to UPNs. The "IDENTIFY" command allows a 1233 single set of authentication credentials to choose from multiple 1234 identities, and allows multiple sets of authentication credentials to 1235 assume the same identity. 1237 For anonymous access the identity of the session is "@". A UPN with 1238 a null Username and null Realm is anonymous. A UPN with a null 1239 Username, but non-null Realm, such as "@foo.com" may be used to mean 1240 any identity from that Realm, which is useful to grant access rights 1241 to all users in a given Realm. A UPN with a non-null Username and 1242 null Realm, such as "bob@" could be a security risk and MUST NOT be 1243 used. 1245 Since the UPN includes Realm information it may be used to govern 1246 calendar store access rights across Realms. However, governing 1247 access rights across Realms is only useful if login access is 1248 available. This could be done through a trusted server relationship 1249 or a temporary account. Note that trusted server relationships are 1250 outside the scope of [CAP]. 1252 The "IDENTIFY" command also provides for a weak group implementation. 1253 By allowing multiple sets of authentication credentials belonging to 1254 different users to identify as the same UPN, that UPN essentially 1255 identifies a group of people, and may be used for group calendar 1256 ownership, or the granting of access rights to a group. 1258 5. CAP URL and Calendar Address 1260 The CAP URL scheme is used to designate calendar stores and calendars 1261 accessible using the CAP protocol. 1263 The CAP URL scheme conform to the generic URL syntax, defined in RFC 1264 2396, and follows the Guidelines for URL Schemes, set forth in RFC 1265 2718. 1267 A CAP URL begins with the protocol prefix "cap" and is defined by the 1268 following grammar. 1270 capurl = "cap://" csid [ "/" relcalid ] 1271 csid = hostport ; As defined in Section 3.2.2 of RFC 2396 1272 relcalid = *uric ; As defined in Section 2 of RFC 2396 1274 'relcalid' is an identifier that uniquely identifies a calendar on a 1275 particular calendar store. There is no implied structure in a 1276 Relative CALID. It may refer to the calendar of a user or of a 1277 resource such as a conference room. It MUST BE unique within the 1278 calendar store. 1280 Examples: 1282 cap://cal.example.com 1283 cap://cal.example.com/Company/Holidays 1284 cap://cal.example.com/abcd1234Usr 1286 Relative CAP URLs are permitted and are resolved according to the 1287 rules defined in Section 5 of RFC 2396. 1289 Examples of valid relative CAP URLs: 1291 opqaueXzz123String 1292 UserName/Personal 1294 A Calendar addresses can be described as qualified or relative CAP 1295 URLs. 1297 For a user currently authenticated to the CS on cal.example.com, 1298 these two example calendar addresses refer to the same calendar: 1300 cap://cal.example.com/abcd1234USR 1301 abcd1234USR 1303 6. New Components, Properties, Parameters, and Values 1305 The following sections contains new components, properties, 1306 parameters, and value definitions. 1308 The purpose of these is to extend the iCalendar objects in a 1309 compatible way so that existing iCalendar VERSION 2.0 parsers can 1310 still parse the objects without modification. 1312 6.1 Property Value Data Types 1314 6.1.1 CAL-QUERY Value Type 1316 Subject: Registration of text/calendar MIME value type CAL-QUERY 1318 Value Name: CAL-QUERY 1320 Value Type Purpose: This value type is used to identify values and 1321 contains query statements targeted at locating those values. 1323 This is based on [SQL92] and [SQLCOM]. 1325 1. For the purpose of a query, all components should be handled as 1326 tables, and the properties of those components, should be handled 1327 as columns. 1329 2. All VAGENDAs and CS's look like tables for the purpose of a 1330 QUERY. And all of their properties look like columns in those 1331 tables. 1333 3. You CAN NOT do any cross component-type joins. And that means 1334 you can ONLY have one component, OR one VAGENDA OR one VCALSTORE 1335 in the the FROM clause. 1337 4. Everything in the SELECT and WHERE clauses MUST BE from the same 1338 component type, or VAGENDA OR VCALSTORE in the FROM clause. 1340 5. When multiple QUERY properties are supplied in a single VQUERY 1341 component, the results returned are the same as the results 1342 returned for multiple VQUERY components having each a single 1343 QUERY property and the results are return in the same order as 1344 the VQUERYs were specified in the original command. 1346 6. The '.' is used to separate the table name (component) and column 1347 name (property or component) when selecting a property that is 1348 contained inside of a component that is targeted in the TARGET 1349 property. 1351 7. A contained component without a '.' is not the same as 1352 "component-name.*". If given as "component-name" (no dot) the 1353 the encapsulating BEGIN/END statement will be supplied for 1354 "component-name".: 1356 In this example the '.' is used to separate the TRIGGER property from 1357 its contained component (VALARM) which is contained in any VEVENT in 1358 the selected TARGET (relcalid). All TRIGGER values in any VEVENT in 1359 relcalid would be returned. 1361 TARGET:relcalid 1362 QUERY:SELECT VALARM.TRIGGER FROM VEVENT 1364 SELECT VALARM FROM VEVENT WHERE UID = "123" 1366 This return one BEGIN/END VALARM for each VALARM in the VEVENT 1367 as there is no '.' (dot) in the VALARM: 1369 BEGIN:VALARM 1370 TRIGGER;RELATED=END:PT5M 1371 REPEAT:4 1372 ... 1373 END:VALARM 1374 BEGIN:VALARM 1375 TRIGGER;RELATED=START:PT5M 1376 DURATION:PT10M 1377 ... 1378 END:VALARM 1379 ... 1380 ... 1382 If provided as "component-name.*", then only the properties and any 1383 contained components will be returned: 1385 SELECT VALARM.* FROM VEVENT WHERE UID = "123" 1387 Will return the properties in each VALARM in the VEVENT: 1389 TRIGGER;RELATED=END:PT5M 1390 REPEAT:4 1391 ... 1392 TRIGGER;RELATED=START:PT5M 1393 DURATION:PT10M 1394 ... 1395 ... 1397 (a) SELECT VEVENT. FROM VEVENT 1399 (b) SELECT VALARM FROM VEVENT 1401 (c) SELECT VALARM.* FROM VEVENT 1403 (d) SELECT * FROM VEVENT 1405 (e) SELECT * FROM VEVENT WHERE 1406 VALARM.TRIGGER < '20020201T000000Z' 1407 AND VALARM.TRIGGER > '20020101T000000Z' 1409 Note: (a) Selects all instances of 1410 from all VEVENT components. 1412 (b) and (c) Select all VALARM components from all 1413 VEVENT components. (b) would return then in 1414 BEGIN/END VALARM tags. (c) would return all 1415 of the properties without BEGIN/END VALARM tags. 1417 (d) Selects every property and every component 1418 that is in any VEVENT component. 1420 (e) Selects all properties and all contained 1421 components in all VEVENT components that have a VALARM 1422 with a TRIGGER property value between the provided 1423 dates and times. 1425 NOT VALID: 1427 (f) SELECT VEVENET.VALARM.TRIGGER FROM VEVENT 1429 (g) SELECT DTSTART,UID FROM VEVENT WHERE 1430 VTODO.SUMMERY = "Fix typo in CAP" 1432 Note: (f) Is NOT valid because it contains 1433 two '.' characters in the SELECT clause. 1435 (g) Is NOT valid because it mixes VEVENT 1436 and VTODO properties in the same VQUERY. 1438 Formal Definition: The value type is defined by the following 1439 notation: 1441 comp-name = "VEVENT" / "VTODO" / "VJOURNAL" 1442 / "VTIMEZONE" / "VALARM" / "VFREEBUSY" 1443 / "VAGENDA" / "VCAR" / "VCALSTORE" 1444 / "VQUERY" / iana-name / x-comp 1446 querycomp = queries 1448 ; These next three property types 1449 ; may be in any order. 1450 ; 1451 / ( queryid *(name) queries) 1453 ; Only when using an existing stored query 1454 ; can query or queries be omitted. 1455 ; 1456 / queryid 1458 queries = query 1459 / queries query 1461 ; NOTE: There is exactly one space separating 1462 ; the various parts of cal-query 1463 ; 1464 cal-query = "SELECT" SP cap-cols SP 1465 "FROM" SP comp-name SP 1466 *(cauprops SP / capcprops SP) 1467 "WHERE" SP cap-expr 1469 / "SELECT" SP cap-cols SP 1470 "FROM" SP comp-name 1472 uprop-list = (cap-col SP cap-local) 1473 / uprop-list SP cap-col SP cap-local 1475 cprop-list = (cap-comp cap-local) 1476 / cprop-list SP cap-col SP cap-local 1478 cap-col = ; Any property name found in the component 1479 ; named in the comp-tbl used in the FROM clause. 1480 ; 1481 ; SELECT ORGANIZER FROM VEVENT ... 1482 ; 1483 ; OR 1484 ; 1485 ; A component name of an existing component contained 1486 ; inside of the cmp-tbl used in the FROM clause. 1487 ; 1488 ; SELECT VALARM FROM VEVENT ... 1490 ; NOTE: there is NO space around the "," on 1491 ; the next line 1492 cap-cols = cap-col / ( cap-cols "," cap-col) 1493 / "*" 1494 / 1495 cap-param = ; Any parameter that may be contained in the cap-col 1496 ; in the supplied PARAM() function 1498 cap-local = ; Any string that is composed of the characters 1499 ; that could be a cap-col name, but is not any 1500 ; cap-col name. It is suggested that the 1501 ; string start with "my-" to ensure it does not 1502 ; conflict with any existing or future cap-col name. 1503 ; This name MUST BE defined in the cap-using and 1504 ; can only be used in cap-expr of the same query. 1505 ; And this name is only known and valid for the 1506 ; provided query and only for the lifetime of 1507 ; the query. If multiple QUERY properties exist 1508 ; in the same component, it is only valid and usable 1509 ; in the same QUERY property where it was supplied. 1511 col-value = col-literal 1512 / "STATE()" 1513 / "SELF()" 1514 / "CAL-OWNERS()" 1515 / "CAL-OWNERS(" cal-address ")" 1516 / "CURRENT-TARGET()" 1518 cal-address = ; A CALID as define by CAP 1520 col-literal = "'" literal-data "'" 1522 literal-data = ; Any data that matches the value type of the 1523 ; column that is being compared. That is you can 1524 ; not compare PRIORITY to "some string" because 1525 ; PRIORITY has a value type of integer. If it is 1526 ; not preceded by the LIKE element, any '%' and '_' 1527 ; characters in the literal data are not treated as 1528 ; wildcard characters and do not have to be backslash 1529 ; escaped. 1530 ; 1531 ; OR 1532 ; 1533 ; If the literal-data is preceded by the LIKE 1534 ; element it may also contain the '%' and '_' 1535 ; wildcard characters. And if the literal data 1536 ; that is comparing contains any '%' or '_' 1537 ; characters, they MUST BE backslash escaped as 1538 ; described in the notes below in order for them not 1539 ; to be treated as wildcard characters. 1541 cap-ucol = cap-col / cap-local 1543 cap-expr = "(" cap-expr ")" 1544 / cap-term 1546 cap-term = cap-expr SP cap-logical SP cap-expr 1547 / cap-factor 1549 cap-factor = cap-colval SP cap-oper SP col-value 1550 / cap-colval SP "NOT LIKE" SP col-value 1551 / cap-colval SP "LIKE" SP col-value 1552 / cap-colval SP "IS NULL" 1553 / cap-colval SP "IS NOT NULL" 1554 / col-value SP "NOT IN" cap-colval" 1555 / col-value SP "IN" cap-colval" 1557 cap-colval = cap-ucolq 1558 / "PARAM(" cap-ucol "," cap-param ")" 1560 cap-oper = "=" 1561 / "!=" 1562 / "<" 1563 / ">" 1564 / "<=" 1565 / ">=" 1567 cap-logical = "AND" / "OR" 1569 SP = ; A single white space ascii character 1570 ; (value in HEX %x20). 1572 CRLF = ; As defined in RFC 2445. 1574 xparam = ; As defined in RFC 2445. 1576 x-prop = ; As defined in RFC 2445. 1578 x-comp = ; As defined in RFC 2445. 1580 6.1.1.1 CAL-OWNERS() 1582 This function returns the list of "OWNERS" for the named calendar. 1584 If called as 'CAL-OWNERS()', it is equivalent to the comma separated 1585 list of all of the owners of the current "TARGET" calendar. If the 1586 target is a "VAGENDA", it returns the "CALMASTER" value. 1588 If called as 'CAL-OWNERS(cal-address)', then it is the equivalent to 1589 the comma separated list of owners for the named calendar id. 1591 6.1.1.2 CURRENT-TARGET() 1593 Is equivalent to the value of the "TARGET" property in the current 1594 command. Used in a CAL-QUERY 'WHERE' clause. 1596 6.1.1.3 [NOT] OWNER() 1598 Returns true if the current UPN is an owner of the current "TARGET". 1599 Used in a CAL-QUERY 'WHERE' clause and in the UPN-FILTER. 1601 6.1.1.4 SELF() 1603 Used in a CAL-QUERY 'WHERE' clause. Returns the UPN of the currently 1604 authenticated CU. 1606 6.1.1.5 STATE() 1608 Returns one of three values, 'BOOKED', 'UNPROCESSED', or 'DELETED' 1609 depending on the state of the object. Used in a CAL-QUERY 'WHERE' 1610 clause. 1612 6.1.1.6 Ordering of Results 1614 Sorting will take place in the order the columns are supplied in the 1615 QUERY command. The CS MUST sort at least the first column. The CS 1616 MAY sort additional columns. 1618 Float and integer values MUST BE sorted by their numeric value. This 1619 means the result of a sort on an integer value type will be: 1621 1, 2, 100, 1000 1623 and not 1625 1, 100, 1000, 2 1627 This means the result of a sort on an float value type will be: 1629 1.1, 2.23, 100.332, 1000.12 1631 and not 1633 1.1, 100.332, 1000.12, 2.23 1635 Date and date time values will be sorted by their equivalent value in 1636 UTC. No matter what the returned time zone in the result set 1637 returns. This is so that if multiple components are returned each in 1638 a unique time zone, the results will be sorted in UTC. This does not 1639 mean the values MUST BE converted to UTC in the data returned to the 1640 CUA. It means the CS must do the sort in UTC. 1642 All other values are sorted according to the locale sorting order as 1643 specified in the command. Or the calendar locale if known, or the CS 1644 locale if the calendar does not have any locale set. And the locale 1645 to use for the sort is determined in that order. 1647 6.1.1.7 Date sorting order 1649 If the cap-cols is only "*" and nothing else and the result set has a 1650 DTSTART, then: 1652 If EXPAND=FALSE sorting will be by the DTSTART value ascending as if 1653 it were in UTC. 1655 If EXPAND=TRUE sorting will be by the RECURRENCE-ID value ascending 1656 as if it were in UTC. 1658 If one or more DTSTART or RECURRENCE-ID components have exactly the 1659 same value, the order for those matching components is unspecified. 1661 If the selected component(s) do not contain a DTSTART or a 1662 RECURRENCE-ID, then the order is unspecified. 1664 If an instance does not have a RECURRENCE-ID and the query compares 1665 RECURRENCE-IDs (comparing a RECURRENCE-ID to the date or date/time of 1666 a single instance object), then the CS MUST compare the DTSTART value 1667 as if it were a RECURRENCE-ID even for single instance objects that 1668 do not contain a RECURRENCE-ID. 1670 A component with a DATE and no TIME value is returned before objects 1671 with both a DATE and TIME value when the dates of those two (or more) 1672 objects are the same, sorted by date. 1674 6.1.1.8 Use of single quote 1676 All literal values are surrounded by single quotes ('), not double 1677 quotes ("), and not without any quotes. If the value contains quotes 1678 or any other ESCAPED-CHAR, they MUST BE backslash escaped as 1679 described in section "4.3.11 Text" of RFC2445. Any LIKE wildcard 1680 characters that are part of any literal data that is preceded by a 1681 LIKE clause and is not intended to mean wildcard search, MUST BE 1682 escaped as described in note (7) below. 1684 6.1.1.9 Comparing DATE and DATE-TIME values 1686 When comparing DATE-TIME to DATE value types and when comparing DATE 1687 to DATE-TIME value types, the result will be true if the DATE value 1688 is on the same day as the DATE-TIME value. And they are compared in 1689 UTC no matter what time zone the data may actual have been stored in. 1691 VALUE-1 VALUE-2 Compare Results 1693 20020304 20020304T123456 TRUE 1694 (in UTC-3) (in UTC-3) 1696 20020304 20020304T003456 FALSE 1697 (in UTC) (in UTC-4) 1699 20020304T003456Z 20020205T003456 FALSE 1700 (in UTC-0) (in UTC-7) 1702 When the DATE or DATE-TIME value is not associated with a time zone, 1703 then the CS will compare the value assuming that the no time zone 1704 values are in the calendars default time zone. 1706 When comparing DATE and DATE-TIME values with the LIKE clause the 1707 comparison will be done as if the value is a RFC2445 DATE or DATE- 1708 TIME string value. 1710 LIKE '2002%' will match anything in the year 2002. 1712 LIKE '200201%' will match anything in January 2002. 1714 LIKE '%T000000' will match anything at midnight. 1716 LIKE '____01__T%' will match anything for any year or 1717 time that is in January. 1718 (Four '_', '01', two '_' 'T%'). 1720 Using a LIKE value of "%00%, would return any value that contained 1721 two consecutive zeros. 1723 Again all comparisons will be done in UTC. 1725 6.1.1.10 DTEND and DURATION 1727 When a QUERY contains a DTEND value, then the CS MUST also evaluate 1728 any existing DURATION property value and determine if it has an 1729 effective end time that matches the QUERY supplied DTEND value or any 1730 range of values supplied by the QUERY. 1732 When a QUERY contains a DURATION value, then the CS MUST also 1733 evaluate any existing DTEND property value and determine if it has an 1734 effective duration that matches the QUERY supplied DURATION value or 1735 any range of values supplied by the QUERY. 1737 As DTEND is the first time that is excluded from a components time 1738 range, any DURATION supplied by the QUERY that is exactly one second 1739 less than DTEND MUST match the QUERY. And if the DURATION ends 1740 exactly at the computed DTEND it MUST NOT match. 1742 Any DTEND supplied by the QUERY that is exactly one second more than 1743 an end time computed from a DURATION MUST match the QUERY. Any end 1744 time that is computed from a DURATION that exactly matches the 1745 supplied DTEND MUST NOT match. 1747 Given a meeting room reserved with a component that contains (date- 1748 time-example-1): 1750 DTSTART:20020127T000000Z 1751 DTEND:20020127T010000Z 1753 The reservation is really from: 1755 January 27th, 2002 00:00:00 1756 To: 1758 January 27th, 2002,00:59:59 1760 Given another meeting room reserved with a component that contains 1761 (date-time-example-2): 1763 DTSTART:20020127T000000Z 1764 DURATION:P59M59S 1766 The reservation is really from: 1768 January 27th, 2002 00:00:00 1770 To: 1772 January 27th, 2002,00:59:59 1774 A QUERY that contains: 1776 ... VEVENT.DTSTART = '20020127T00000Z' 1777 AND VEVENT.DTEND = '20020127T010000Z' 1779 MUST match both (date-time-example-1) and (date-time-example-2) 1781 A QUERY that contains: 1783 ... VEVENT.DTSTART = '20020127T00000Z' 1784 AND DURATION = 'P59M59S' 1786 MUST match both (date-time-example-1) and (date-time-example-2) 1788 6.1.1.11 [NOT] LIKE 1790 The pattern matching characters are the '%' that matches zero or more 1791 characters, and '_' that matches exactly one character (where 1792 character does not always mean octet). 1794 LIKE pattern matches always cover the entire string. To match a 1795 pattern anywhere within a string, the pattern must start and end with 1796 a percent sign. 1798 To match a '%' or '_' in the data and not have it interpreted as a 1799 wildcard character, they MUST BE backslash escaped. That is to 1800 search for a '%' or '_' in the string: 1802 LIKE '%\%%' Matches any string with a '%' in it. 1803 LIKE '%\_%' Matches any string with a '_' in it. 1805 Strings compared using the LIKE clause MUST BE performed using case 1806 in-sensitive comparisons when the locale allows. (Example: in US- 1807 ASCII the compare assumes 'a' = 'A'). 1809 If LIKE is preceded by 'NOT' then there is a match when the string 1810 compare fails. 1812 Some property values (such as the 'recur' value type), contain commas 1813 and are not multi valued. The CS must understand the objects being 1814 compared and understand how to determine how any multi valued or 1815 multi instances properties or parameter values are separated, quoted, 1816 and backslash escaped and perform the comparisons as if each value 1817 existed by itself and not quoted or backslash escaped when comparing 1818 using the IN element. 1820 And see the examples in the next section (IN). 1822 6.1.1.12 Empty vs. NULL 1824 When used in a CAL-QUERY value, "NULL" means that the property or 1825 parameter is not present in the object. 1827 If the property (or parameter) exists, but has no value then "NULL" 1828 MUST NOT match. 1830 If the property (or parameter) exists, but has no value then it 1831 matches the empty string '' (quote quote). 1833 6.1.1.13 [NOT] IN 1835 This is similar to the LIKE element, except it does value matching 1836 and not string comparison matches. 1838 Some iCalendar objects can be multi instance and multi valued. The 1839 IN operator will return a match if the literal value supplied as part 1840 of the 'IN' clause is contained in the value of any instance of the 1841 named property or parameter, or is in any of the multiple values in 1842 the named property or parameter. Unlike the 'LIKE' clause, the '%' 1843 and '_' matching characters are not used with the 'IN' clause and 1844 have no special meaning. 1846 BEGIN:A-COMPONENT 1847 a property:value1,value2 One property, two values. 1848 b property:"value1,value2" One property, one value. 1849 c FOO:parameter=1,2:x One parameter, two values. 1850 d FOO:parameter="1,2",3:y One parameter, one value. 1851 e FOO:parameter=",":z One parameter, one value. 1852 f property:x,y,z One property, three values 1853 END:A-COMPONENT 1855 'value1' IN property would match (a) only. 1856 'value1,value2' IN property would match (b) only. 1857 'value%' IN property would NOT match any. 1858 ',' IN property would NOT match any. 1859 '%,%' IN property would NOT match any. 1860 'x' IN property would match (f) and (c). 1861 '2' IN parameter would match (c) only. 1862 '1,2' IN parameter would match (d) only. 1863 ',' IN parameter would match (e) only. 1864 '%,%' IN parameter would NOT match any. 1866 property LIKE 'value1%' would match (a) and (b) 1867 property LIKE 'value%' would match (a) and (b) 1868 property LIKE 'x' would match (f) and (c). 1869 parameter LIKE '1%' would match (c) and (d) 1870 parameter LIKE '%2%' would match (c) and (d) 1871 parameter LIKE ',' would match (e) only. 1873 Some property values (such as the 'recur' value type), contain commas 1874 and are not multi valued. The CS must understand the objects being 1875 compared and understand how to determine how any multi valued or 1876 multi instances properties or parameter values are separated, quoted, 1877 and backslash escaped and perform the comparisons as if each value 1878 existed by itself and not quoted or backslash escaped when comparing 1879 using the IN element. 1881 If IN is preceded by 'NOT' then there is a match when the value does 1882 not exist in the property or parameter value. 1884 6.1.1.14 DATE-TIME and TIME values in a WHEN clause 1886 All DATE-TIME and TIME literal values supplied in a WHEN clause MUST 1887 BE terminated with 'Z'. That means that the CUA MUST supply the 1888 values in UTC. 1890 Valid: 1892 WHERE alarm.TRIGGER < '20020201T000000Z' 1893 AND alarm.TRIGGER > '20020101T000000Z' 1895 Not valid and it is a syntax error and the CS MUST reject the QUERY. 1897 WHERE alarm.TRIGGER < '20020201T000000' 1898 AND alarm.TRIGGER > '20020101T000000' 1900 6.1.1.15 Multiple contained components 1902 All comparisons MUST BE done from the same instance of a contained 1903 component or property and repeated for each instance. As in the 1904 following example that uses a VALARM component contained in a VEVENT. 1905 If any instance of VALARM in VEVENT matches the query and the rest of 1906 the query is satisfied, then the UID, SUMMARY, and DESCRIPTION from 1907 the VEVENT will be returned. If there were two VALARMs in a VEVENT, 1908 then both VALARMs are tested and in this example only when the VEVENT 1909 state is booked: 1911 BEGIN:VQUERY 1912 EXPAND:TRUE 1913 QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT 1914 WHERE VALARM.TRIGGER >= '20000101T030405Z' 1915 AND VALARM.TRIGGER <= '20001231T235959Z' 1916 AND STATE() = 'BOOKED' 1917 END:VQUERY 1919 6.1.1.16 Example, Query by UID 1921 The following example would match the entire content of a "VEVENT" or 1922 "VTODO" component with the "UID" property equal to "uid123" and not 1923 expand any multiple instances of the component. If the CUA does not 1924 know if "uid123" was a "VEVENT", "VTODO", "VJOURNAL", or any other 1925 component, then all components that the CUA supports MUST BE supplied 1926 in a QUERY property. This example assumes the CUA is only interested 1927 in "VTODO" and "VEVENT" components. 1929 If the results were empty it could also mean that "uid123" was a 1930 property in a component other than a VTODO or VEVENT. 1932 BEGIN:VQUERY 1933 QUERY:SELECT * FROM VTODO WHERE UID = 'uid123' 1934 QUERY:SELECT * FROM VEVENT WHERE UID = 'uid123' 1935 END:VQUERY 1937 6.1.1.17 Query by Date-Time range 1939 This query selects the entire content of every booked VEVENT that has 1940 an instance greater than or equal to July 1st, 2000 00:00:00 UTC and 1941 less than or equal to July 31st, 2000 23:59:59 UTC. This includes 1942 single instance VEVENT objects that do no explicitly contain a 1943 RECURRENCE-ID. 1945 BEGIN:VQUERY 1946 EXPAND:TRUE 1947 QUERY:SELECT * FROM VEVENT 1948 WHERE RECURRENCE-ID >= '20000801T000000Z' 1949 AND RECURRENCE-ID <= '20000831T235959Z' 1950 AND STATE() = 'BOOKED' 1951 END:VQUERY 1953 6.1.1.18 Query for all Unprocessed Entries 1955 The following example selects the entire contents of all non-booked 1956 "VTODO" and "VEVENT" components with their state of 'UNPROCESSED". 1957 The default for EXPAND is FALSE, so the recurrence rules will not be 1958 expanded. 1960 BEGIN:VQUERY 1961 QUERYID:Fetch VEVENT and VTODO iTIP components 1962 QUERY:SELECT * FROM VEVENT WHERE 1963 STATE() = 'UNPROCESSED' 1964 QUERY:SELECT * FROM VTODO WHERE 1965 STATE() = 'UNPROCESSED' 1966 END:VQUERY 1968 The following example fetches all "VEVENT" and "VTODO" components 1969 that are booked from the CS. 1971 BEGIN:VQUERY 1972 QUERYID:Fetch All Booked VEVENT and VTODO components 1973 QUERY:SELECT * FROM VEVENT WHERE STATE() = 'BOOKED' 1974 QUERY:SELECT * FROM VTODO WHERE STATE() = 'BOOKED' 1975 END:VQUERY 1977 The following fetches the UID for all VEVENT and VTODO components 1978 that have been marked for delete). 1980 BEGIN:VQUERY 1981 QUERYID:Fetch UIDs of marked for delete VEVENTs and VTODOs 1982 QUERY:SELECT UID FROM VEVENT WHERE STATE() = 'DELETE' 1983 QUERY:SELECT UID FROM VTODO WHERE STATE() = 'DELETE' 1984 END:VQUERY 1986 In the examples above they were bunched into groups of similar 1987 queries. They could be performed all at once by having all of the 1988 QUERY property in one BEGIN/END VQUERY component. 1990 6.1.1.19 Query with Subset of Properties by Date/Time 1992 In this example only the named properties will be selected and all 1993 booked and non-booked components will be selected that have a DTSTART 1994 from February 1st to February 10th 2000 (in UTC). 1996 BEGIN:VQUERY 1997 QUERY:SELECT UID,DTSTART,DESCRIPTION,SUMMARY FROM VEVENT 1998 WHERE DTSTART >= '20000201T000000Z' 1999 AND DTSTART <= '20000210T235959Z' 2000 END:VQUERY 2002 6.1.1.20 Query with Components and Alarms In A Range 2004 This example fetches all booked "VEVENT" components with an alarm 2005 that triggers within the specified time range. In this case only the 2006 "UID", "SUMMARY", and "DESCRIPTION" properties will be selected for 2007 all booked "VEVENTS" components that have an alarm between the two 2008 date-times supplied. 2010 BEGIN:VQUERY 2011 EXPAND:TRUE 2012 QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT 2013 WHERE VALARM.TRIGGER >= '20000101T030405Z' 2014 AND VALARM.TRIGGER <= '20001231T235959Z' 2015 AND STATE() = 'BOOKED' 2016 END:VQUERY 2018 6.1.2 UPN Value Type 2020 Value Name: UPN 2022 Purpose: This value type is used to identify values that contain user 2023 principal name of CU or group of CU. 2025 Formal Definition: The value type is defined by the following 2026 notation: 2028 upn = "@" 2029 / [ dot-atom-text ] "@" dot-atom-text 2031 ; dot-atom-text is defined in RFC 2822 2033 Description: This data type is an identifier that denotes a CU or a 2034 group of CU. 2036 Example: 2038 The following is a UPN for a CU: 2040 jdoe@acme.com 2042 The following is a UPN for a group of CU: 2044 staff@acme.com 2046 The following is a UPN for an anonymous CU belonging to a specific 2047 realm: 2049 @acme.com 2051 The following is a UPN for an anonymous CU: 2053 @ 2055 6.1.3 UPN-FILTER Value 2057 Value Name: UPN-FILTER 2059 Purpose: This value type is used to identify values that contain a 2060 user principal name filter. 2062 Formal Definition: The value type is defined by the following 2063 notation: 2065 upn-filter = "OWNER()" / 2066 "NOT OWNER()" / 2067 "*" / 2068 [ "*" / dot-atom-text ] "@" ( "*" / dot-atom-text ) 2070 ; dot-atom-text is defined in RFC 2822 2072 Description: The value is used to match user principal names (UPNs). 2073 For "OWNER()" and "NOT OWNER()", see Section 6.1.1.3. 2075 * Matches all UPNs. 2077 @ Matches the UPN of anonymous CUs 2078 belonging to the null realm 2080 @* Matches the UPN of anonymous CUs 2081 belonging to any non-null realm 2083 @realm Matches the UPN of anonymous CUs 2084 belonging to the specified realm. 2086 *@* Matches the UPN of non-anonymous CUs 2087 belonging to any non-null realm 2089 *@realm Matches the UPN of non-anonymous CUs 2090 belonging to the specified realm 2092 user@realm Matches the UPN of the specified CU 2093 belonging to the specified realm 2095 user@* Not allowed. 2097 Example: The following are examples of this value type: 2099 DENY:NON OWNER() 2101 6.2 New Parameter 2103 6.2.1 ENABLE Parameter 2105 Parameter Name: ENABLE 2107 Purpose: This parameter indicates whether or not the "TRIGGER" 2108 property in a "VALARM" component should be ignored. 2110 Value Type: BOOLEAN 2112 Conformance: This property can be specified in the "TRIGGER" 2113 properties. 2115 Description: When a non owner sends an iTIP "REQUEST" to a calendar 2116 that object might contain a "VALARM" component. The owner may wish 2117 to have local control over their own CUA and when or how alarms are 2118 triggered. 2120 A CUA may add the "ENABLE" parameter to any "TRIGGER" property before 2121 booking the component. If the "ENABLE" parameter is set to "FALSE", 2122 then the alarm will be ignored by the CUA. If set to "TRUE", or of 2123 the "ENABLE" property is not in the "TRIGGER" property, the alarm is 2124 enabled. The CUA should remove the "ENABLE" parameter before 2125 forwarding the component to a non-cap CUA. 2127 If FALSE in the "VCALSTORE", then all "VAGENDA" ALLOW-CONFLICT values 2128 MUST BE false in the CS. 2130 Format Definition: The property is defined by the following notation: 2132 allow-conflict = "ALLOW-CONFLICT" 2133 *(";" xparam) ":" boolean CRLF 2135 Example: The following is an example of this property for a "VAGENDA" 2136 component: 2138 ALLOW-CONFLICT:FALSE 2140 6.2.2 LOCAL Parameter 2142 Parameter Name: LOCAL 2144 Purpose: Indicates if the VALARM should be exported to any non- 2145 organizer calendar. 2147 Value Type: BOOLEAN 2149 Conformance: This property can be specified in the "SEQUENCE" 2150 properties in a "VALARM" component. 2152 Description: When a non owner sends an iTIP "REQUEST" to a calendar 2153 that object might contain a "VALARM" component. The owner may wish 2154 to have local control over their own CUA and when or how alarms are 2155 triggered. 2157 A CUA may add the "LOCAL" parameter to the "SEQUENCE" property before 2158 booking the component. If the "LOCAL" parameter is set to "FALSE", 2159 then the alarm MUST NOT be forwarded to any non organizer calendar. 2160 If set to "TRUE", or of the "LOCAL" property is not in the "SEQUENCE" 2161 property, the alarm is global. The CUA should remove the "LOCAL" 2162 parameter before forwarding the component to a non-cap CUA and to non 2163 organizer calendars. 2165 If FALSE in the "VCALSTORE", then all "VAGENDA" ALLOW-CONFLICT values 2166 MUST BE false in the CS. 2168 Format Definition: The property is defined by the following notation: 2170 allow-conflict = "ALLOW-CONFLICT" 2171 *(";" xparam) ":" boolean CRLF 2173 Example: The following is an example of this property for a "VAGENDA" 2174 component: 2176 ALLOW-CONFLICT:FALSE 2178 7. New Properties 2180 7.1 ALLOW-CONFLICT Property 2182 Property Name: ALLOW-CONFLICT 2184 Purpose: This property indicates whether or not the calendar and CS 2185 supports component conflicts. That is, whether or not any of the 2186 components in the calendar can overlap. 2188 Value Type: BOOLEAN 2190 Property Parameters: Non-standard property parameters can be 2191 specified on this property. 2193 Conformance: This property can be specified in "VAGENDA" and 2194 "VCALSTORE" component. 2196 Description: This property is used to indicate whether components may 2197 conflict. That is, if their expanded instances may share the same 2198 time or overlap the same time periods. If it has a value of TRUE, 2199 then conflicts are allowed. If FALSE, the no two components may 2200 conflict. 2202 If FALSE in the "VCALSTORE", then all "VAGENDA" ALLOW-CONFLICT values 2203 MUST BE false in the CS. 2205 Format Definition: The property is defined by the following notation: 2207 allow-conflict = "ALLOW-CONFLICT" 2208 *(";" xparam) ":" boolean CRLF 2210 Example: The following is an example of this property for a "VAGENDA" 2211 component: 2213 ALLOW-CONFLICT:FALSE 2215 7.2 CALID Property 2217 Property Name: CALID 2219 Property Parameters: Non-standard property parameters can be 2220 specified on this property. 2222 Conformance: This property can be specified in the "VAGENDA". 2224 Description: This property is used to specify a fully qualified 2225 calid. 2227 Format Definition: The property is defined by the following notation: 2229 CALID = "CALID" *(";" xparam) ":" calid CRLF 2231 Example: 2233 CALID:cap://cal.example.com/sdfifgty4321 2235 7.3 CALMASTER Property 2237 Property Name: CALMASTER 2239 Purpose: The property specifies an e-mail address of a person 2240 responsible for the calendar store. 2242 Value Type: URI 2244 Property Parameters: Non-standard property parameters can be 2245 specified on this property. 2247 Conformance: The property can be specified in a "VCALSTORE" 2248 component. 2250 Description: The parameter value SHOULD BE a MAILTO URI as defined in 2251 [RFC1738]. It MUST BE a contact URI such as a MAILTO URI and not a 2252 home page or file URI that describes how to contact the calmasters. 2254 Format Definition: The property is defined by the following notation: 2256 calmaster = "CALMASTER" *(";" xparam) ":" uri CRLF 2258 uri = IANA registered uri and defined by RFC 2445 2260 Example: The following is an example of this property: 2262 CALMASTER:mailto:administrator@example.com 2264 7.4 CARID Property 2266 Property Name: CARID 2268 Purpose: This property specifies the identifier for an access right 2269 component. 2271 Value Type: TEXT 2273 Property Parameters: Non-standard property parameters can be 2274 specified on this property. 2276 Conformance: This property MUST BE specified once in a "VCAR" 2277 component. 2279 Description: This property is used in the "VCAR" component to specify 2280 an identifier. 2282 Format Definition: The property is defined by the following notation: 2284 carid = "CARID" *(";" xparam) ":" text CRLF 2286 Example: The following are examples of this property: 2288 CARID:xyzzy-007 2289 CARID:User Rights 2291 7.5 CSID Property 2293 Property Name: CSID 2295 Purpose: The property specifies a the globally unique identifier for 2296 the calendar store. 2298 Value Type: URI 2300 Property Parameters: Non-standard property parameters can be 2301 specified on this property. 2303 Conformance: The property can be specified in a "VCALSTORE" 2304 component. 2306 Description: The identifier MUST BE globally unique. 2308 Format Definition: The property is defined by the following notation: 2310 csid = "CSID" *(";" xparam) ":" capurl CRLF 2312 Example: The following is an example of this property: 2314 CSID:cap://calendar.example.com 2316 7.6 DECREED Property 2318 Property Name: DECREED 2320 Purpose: This property specifies if an access right calendar 2321 component is decreed or not. 2323 Value Type: BOOLEAN 2325 Property Parameters: Non-standard property parameters can be 2326 specified on this property. 2328 Conformance: This property MAY be specified once in a "VCAR" 2329 component. 2331 Description: This property is used in the "VCAR" component to specify 2332 whether the component is decreed or not. 2334 Format Definition: The property is defined by the following notation: 2336 decreed = "DECREED" *(";" xparam) ":" boolean CRLF 2338 Example: The following is an example of this property: 2340 DECREED:TRUE 2342 7.7 DEFAULT-CHARSET Property 2344 Property Name: DEFAULT-CHARSET 2346 Purpose: This property indicates the default charset. 2348 Value Type: TEXT 2350 Property Parameters: Non-standard property parameters can be 2351 specified on this property. 2353 Conformance: This property can be specified in "VAGENDA" and 2354 "VCALSTORE" calendar component. 2356 Description: In a "VAGENDA", this property is used to indicate the 2357 charset of calendar. If not specified, the default the first value 2358 in the "VCALSTORE" DEFAULT-CHARSET list. The value MUST BE an IANA 2359 registered character set as defined in [RFC 2278]. 2361 In a "VCALSTORE" it is a comma separated list of charsets supported 2362 by the CS. The first entry is the default entry for all newly 2363 created "VAGENDA"s. "UTF-8" MUST BE in the "VCALSTORE" DEFAULT- 2364 CHARSET list. 2366 If a charset name contains a comma (,), then that comma must be 2367 backslashed escaped in the value. 2369 Format Definition: The property is defined by the following notation: 2371 default-charset = "DEFAULT-CHARSET" *(";" xparam) 2372 ":" text CRLF 2374 Example: The following is an example of this property for a "VAGENDA" 2375 component: 2377 DEFAULT-CHARSET:Shift_JIS,UTF-8 2379 7.8 DEFAULT-LOCALE Property 2381 Property Name: DEFAULT-LOCALE 2383 Purpose: This property specifies the default language for text 2384 values. 2386 Value Type: TEXT 2388 Property Parameters: Non-standard property parameters can be 2389 specified on this property. 2391 Conformance: This property can be specified in "VAGENDA" and 2392 "VCALSTORE" components. 2394 Description: In a "VAGENDA", this property is used to indicate the 2395 locale of the calendar. The full locale SHOULD be used. The default 2396 and minimum locale is POSIX. 2398 In a "VCALSTORE" it is a comma separated list of locales supported by 2399 the CS. The first value in the list is the default for all newly 2400 created VAGENDAs. POSIX MUST BE in the list. 2402 Format Definition: The property is defined by the following notation: 2404 default-locale = "DEFAULT-LOCALE" *(";" xparam) 2405 ":" language CRLF 2407 language = Text identifying a locale, as defined in [RFC 2277] 2409 Example: The following is an example of this property: 2411 DEFAULT-LOCALE:en-US.iso-8859-1,POSIX 2413 7.9 DEFAULT-TZID Property 2415 Property Name: DEFAULT-TZID 2417 Purpose: This property specifies the text value that specifies the 2418 default time zone for a calendar. 2420 Value Type: TEXT 2422 Property Parameters: Non-standard property parameters can be 2423 specified on this property. 2425 Conformance: This property may be specified once in a "VAGENDA" and 2426 "VCALSTORE" components. 2428 Description: In a "VAGENDA" it is the value of the time zone for the 2429 calendar. This time zone is used when as the localtime for object 2430 that contain a date or date-time value without a time zone. 2432 In a "VCALSTORE" it is a comma separated list of TZIDs known to the 2433 CS. Where TZID values are the same as the TZID property as defined 2434 in [iCAL]. The first entry in the list is used as the default TZID 2435 for all newly created calendars. The list MUST contain at least UTC. 2437 If the TZID contains a comma (,), the comma must be backslash 2438 escaped. 2440 Format Definition: This property is defined by the following 2441 notation: 2443 default-tzid = "DEFAULT-TZID" *(";" xparam) 2444 ":" [tzidprefix] text CRLF 2446 Example: The following is an example of this property: 2448 DEFAULT-TZID:US/Eastern,UTC 2450 7.10 DEFAULT-VCARS Property 2452 Property Name: DEFAULT-VCARS 2454 Purpose: This property is used to specify the CARIDs of the default 2455 VCAR components for newly created VAGENDA components. 2457 Value Type: TEXT 2459 Property Parameters: Non-standard property parameters can be 2460 specified on this property. 2462 Conformance: This property MUST BE specified in "VCALSTORE" calendar 2463 component and MUST at least specify the following values: 2464 READBUSYTIMEINFO, REQUESTONLY, UPDATEPARTSTATUS, and DEFAULTOWNER. 2466 Description: This property is used in the "VCALSTORE" calendar 2467 component to specify the CARID of the VCAR components that MUST BE 2468 copied in VAGENDA at creation time by the CS. These VCARS components 2469 MUST BE stored in the "VCALSTORE". 2471 Format Definition: The property is defined by the following notation: 2473 def-vcars = "DEFAULT-VCARS" *(";" xparam) ":" text 2474 *( "," text ) CRLF 2476 Example: The following is an example of this property: 2478 DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY, 2479 UPDATEPARTSTATUS,DEFAULTOWNER 2481 7.11 DENY Property 2483 Property Name: DENY 2485 Purpose: This property identifies the UPN(s) being denied access in 2486 the VRIGHT component. 2488 Value Type: UPN-FILTER 2490 Property Parameters: Non-standard property parameters can be 2491 specified on this property. 2493 Conformance: This property can be specified in "VRIGHT" calendar 2494 components. 2496 Description: This property is used in the "VRIGHT" component to 2497 define the CU or UG being denied access. 2499 Format Definition: The property is defined by the following notation: 2501 deny = "DENY" *(";" xparam) ":" upn-filter CRLF 2503 Example: The following are examples of this property: 2505 DENY:* 2507 DENY:bob@example.com 2509 7.12 EXPAND property 2511 Property Name: EXPAND 2513 Purpose: This property is to notify the CS if it should or should not 2514 expand any component with recurrence rules into multiple instances in 2515 a query reply. 2517 Value Type: BOOLEAN 2519 Property Parameters: Non-standard property parameters can be 2520 specified on this property. 2522 Conformance: This property can be specified in "VQUERY" calendar 2523 components. 2525 Description: If a CUA wishes to see all of the instances of a 2526 recurring component the CUA sets EXPAND=TRUE in the VQUERY component. 2527 If not specified, the default is FALSE. 2529 Format Definition: The property is defined by the following notation: 2531 expand = "EXPAND" *(";" xparam) ":" ("TRUE" / "FALSE") CRLF 2533 Example: The following are examples of this property: 2535 EXPAND:FALSE 2536 EXPAND:TRUE 2538 7.13 GRANT Property 2540 Property Name: GRANT 2542 Purpose: This property identifies the UPN(s) being granted access in 2543 the VRIGHT component. 2545 Value Type: UPN-FILTER 2547 Property Parameters: Non-standard property parameters can be 2548 specified on this property. 2550 Conformance: This property can be specified in "VRIGHT" calendar 2551 components. 2553 Description: This property is used in the "VRIGHT" component to 2554 specify the CU or UG being granted access. 2556 Format Definition: The property is defined by the following notation: 2558 grant = "GRANT" *(";" xparam) ":" upn-filter CRLF 2560 Example: The following are examples of this property: 2562 GRANT:* 2564 GRANT:bob@example.com 2566 7.14 MAXDATE Property 2568 Property Name: MAXDATE 2570 Purpose: This property specifies the date/time in the future beyond 2571 which the CS cannot represent. 2573 Value Type: DATE-TIME 2575 Property Parameters: Non-standard property parameters can be 2576 specified on this property. 2578 Conformance: The property can be specified in the "VCALSTORE". 2580 Description: The date and time MUST BE a UTC value and end with 'Z'. 2582 Format Definition: The property is defined by the following notation: 2584 maxdate = "MAXDATE" *(";" xparam) ":" date-time CRLF 2586 Example: The following is an example of this property: 2588 MAXDATE:20990101T000000Z 2590 7.15 MINDATE Property 2592 Property Name: MINDATE 2594 Purpose: This property specifies the date/time in the past prior to 2595 which the server cannot represent. 2597 Value Type: DATE-TIME 2599 Property Parameters: Non-standard property parameters can be 2600 specified on this property. 2602 Conformance: The property can be specified in the "VCALSTORE". 2604 Description: The date and time MUST BE a UTC value and end with 'Z'. 2606 Format Definition: The property is defined by the following notation: 2608 mindate = "MINDATE" *(";" xparam) ":" date-time CRLF 2610 Example: The following is an example of this property: 2612 MINDATE:19710101T000000Z 2614 7.16 NAME Property 2616 Property Name: NAME 2618 Purpose: This property provides a localizeable display name for a 2619 component. 2621 Value Type: TEXT 2623 Property Parameters: Non-standard property parameters can be 2624 specified on this property. 2626 Conformance: This property can be specified in a component. 2628 Description: This property is used in the in component to specify a 2629 localizeable display name. If more than one NAME property is in a 2630 component, then they MUST have unique LANG parameters. If the LANG 2631 parameter is not supplied, then it defaults to the VAGENDAs default 2632 if the component is in a VAGENDA, or the VCALSTORE default if the 2633 component is stored at the VCALSTORE level. 2635 Format Definition: The property is defined by the following notation: 2637 name = "NAME" nameparam ":" text CRLF 2639 nameparam = *( 2640 ; the following is optional, 2641 ; but MUST NOT occur more than once 2643 ( ";" languageparam ) / 2645 ; the following is optional, 2646 ; and MAY occur more than once 2648 ( ";" xparam ) 2649 ) 2651 languageparam = ; As defined in [iCAL]. 2653 Example: The following is an example of this property: 2655 NAME:Restrict Guests From Creating VALARMs On VEVENTs 2657 7.17 OWNER Property 2659 Property Name: OWNER 2661 Purpose: The property specifies an owner of the component. 2663 Value Type: UPN 2665 Property Parameters: Non-standard, alternate text representation and 2666 language property parameters can be specified on this property. 2668 Conformance: The property MUST BE specified at in a "VAGENDA" 2669 component. 2671 Description: A multi-instanced property indicating the calendar 2672 owner. 2674 Format Definition: The property is defined by the following notation: 2676 owner = "OWNER" *(";" xparam) ":" upn CRLF 2678 Example: The following is an example of this property: 2680 OWNER:jsmith@acme.com 2681 OWNER:jdoe@acme.com 2683 7.18 PERMISSION Property 2685 Property Name: PERMISSION 2687 Purpose: This property defines a permission that is granted or denied 2688 in a VRIGHT component. 2690 Value Type: TEXT 2692 Property Parameters: Non-standard property parameters can be 2693 specified on this property. 2695 Conformance: This property can be specified in "VRIGHT" calendar 2696 components. 2698 Description: This property is used in the "VRIGHT" component to 2699 define a permission that is granted or denied. 2701 Format Definition: The property is defined by the following notation: 2703 perm = "PERMISSION" *(";" xparam) ":" permvalue CRLF 2705 permvalue = ( "READ" / "CREATE" / "DELETE" / "MODIFY" / all ) 2707 all = "*" 2709 Example: The following is an example of this property: 2711 PERMISSION:READ 2713 7.19 QUERY property 2715 Property Name: QUERY 2717 Purpose: Specifies the query for the component. 2719 Value Type: CAL-QUERY 2721 Property Parameters: Non-standard property parameters can be 2722 specified on this property. 2724 Conformance: This property can be specified in "VQUERY" components. 2726 Description: A "QUERY" is used to specify the CAL-QUERY (Section 2727 6.1.1 for the query. 2729 Format Definition: The property is defined by the following notation: 2731 query = "QUERY" *(";" xparam) ":" cal-query CRLF 2733 Example: The following is an example of this property: 2735 QUERY:SELECT * FROM VEVENT 2737 7.20 QUERYID property 2739 Property Name: QUERYID 2741 Purpose: Specifies a unique ID for a query in the targeted container. 2743 Value Type: TEXT 2745 Property Parameters: Non-standard property parameters are specified 2746 on this property. 2748 Conformance: This property can be specified in "VQUERY" components. 2750 Description: A "QUERYID" is used to specify the unique id for a 2751 stored query. 2753 Format Definition: The property is defined by the following notation: 2755 queryid = "QUERYID" *(";" xparam) ":" text CRLF 2757 Example: The following are examples of this property: 2759 QUERYID:Any Text String 2760 QUERYID:fetchUnProcessed 2762 7.21 REQUEST-STATUS property 2764 This description is a revision of the REQUEST-STATUS property for 2765 VCALENDAR version 2.0. The 'statdesc' is optional and the 'extdata' 2766 may be included when 'statdesc' is not provided. 2768 rstatus = "REQUEST-STATUS" rstatparam ":" 2769 statcode ";" *(statdesc ) ";" *(extdata) 2771 rstatparam = *( 2772 ; the following is optional, 2773 ; but MUST NOT occur more than once 2775 (";" languageparm) / 2777 ; the following is optional, 2778 ; and MAY occur more than once 2780 (";" xparam) 2782 ) 2784 statcode = 1*DIGIT *("." 1*DIGIT) 2785 ;Hierarchical, numeric return status code 2787 statdesc = text 2788 ;An optional textual status description, content is 2789 ;decided by the implementor. May be empty. 2791 extdata = text 2792 ; Textual exception data. For example, the offending 2793 ; property name and value or complete property line. 2795 Example: The following are some possible examples of this property. 2796 The COMMA and SEMICOLON separator characters in the property value 2797 are BACKSLASH character escaped because they appear in a text value. 2799 REQUEST-STATUS:2.0;Success 2801 REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01 2803 REQUEST-STATUS:2.8; Success\, repeating VEVENT ignored. Scheduled 2804 as a single VEVENT.;RRULE:FREQ=WEEKLY;INTERVAL=2 2806 REQUEST-STATUS:4.1;Time conflict. Date/time is busy. 2808 REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE: 2809 MAILTO:jsmith@example.com 2811 REQUEST-STATUS:3.7;;ATTENDEE:MAILTO:jsmith@example.com 2813 REQUEST-STATUS:10.4;Help! That really shouldn't have happened. 2815 7.22 RESTRICTION Property 2817 Property Name: RESTRICTION 2819 Purpose: This property defines restrictions on the result value of 2820 new or existing components. 2822 Value Type: CAL-QUERY 2824 Property Parameters: Non-standard property parameters can be 2825 specified on this property. 2827 Conformance: This property can be specified in "VRIGHT" calendar 2828 components, but only when the PERMISSION property is set to "CREATE", 2829 "MODIFY", or "*". 2831 Description: This property is used in the "VRIGHT" component to 2832 define restrictions on the components that can be written (i.e., by 2833 using the "CREATE" or "MOVE" commands) as well as on the values that 2834 may take existent calendar store properties, calendar properties, 2835 components, and properties (i.e., by using the "MODIFY" command). 2836 Accepted values MUST match the specified RESTRICTION. 2838 Format Definition: The property is defined by the following notation: 2840 restrict = "RESTRICTION" *(";" xparam) ":" cal-query CRLF 2842 Example: The following are examples of this property: 2844 RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST' 2846 RESTRICTION:SELECT * FROM VEVENT WHERE 2847 SELF() IN CAL-OWNERS(ORGANIZER) 2849 RESTRICTION:SELECT * FROM VEVENT WHERE 'BUSINESS' IN 2850 CATEGORIES 2852 7.23 SCOPE Property 2854 Property Name: SCOPE 2856 Purpose: This property identifies the objects in the CS to which the 2857 access rights applies. 2859 Value Type: CAL-QUERY 2861 Property Parameters: Non-standard property parameters can be 2862 specified on this property. 2864 Conformance: This property can be specified in "VRIGHT" calendar 2865 components. 2867 Description: This property is used in the "VRIGHT" component to 2868 define the set of objects subject to the access right being defined. 2870 Format Definition: The property is defined by the following notation: 2872 scope = "SCOPE" *(";" xparam) ":" cal-query CRLF 2874 Example: The following is an example of this property: 2876 SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC' 2878 7.24 TARGET Property 2880 Property Name: TARGET 2882 Purpose: This property defines the container that the command that is 2883 issued will act upon. It its value is a capurl as defended in 2884 Section 5. 2886 Value Type: URI 2888 Property Parameters: Non-standard property parameters can be 2889 specified on this property. 2891 Conformance: This property can be specified in a command component. 2893 Description: This properties value is used to specify the container 2894 that the command will effect. When used in a command, the command 2895 will be performed on the container which has a capurl matching the 2896 value. 2898 Format Definition: The property is specified by the following 2899 notation: 2901 target = "TARGET" *(";" xparam) ":" capurl CRLF 2903 The following is an example of this property: 2905 TARGET:cap://mycal.example.com 2906 TARGET:SomeRelCalid 2908 7.25 TRANSP Property 2910 Property Name: TRANSP 2912 Purpose: This property defines whether an component is transparent or 2913 not to busy time searches. This is a modification to [iCAL] TRANSP 2914 in that it adds some values. 2916 Value Type: TEXT 2918 Property Parameters: Non-standard property parameters can be 2919 specified on this property. 2921 Conformance: This property can be specified in a component. 2923 Description: Time Transparency is the characteristic of an object 2924 that determines whether it appears to consume time on a calendar. 2925 Objects that consume actual time for the individual or resource 2926 associated with the calendar SHOULD be recorded as OPAQUE, allowing 2927 them to be detected by free-busy time searches. Other objects, which 2928 do not take up the individual's (or resource's) time SHOULD be 2929 recorded as TRANSPARENT, making them invisible to free-busy time 2930 searches. 2932 Format Definition: The property is specified by the following 2933 notation: 2935 transp = "TRANSP" *(";" xparam) ":" transvalue CRLF 2937 transvalue = "OPAQUE" ;Blocks or opaque on busy time searches. 2938 / "TRANSPARENT" ;Transparent on busy time searches. 2940 / "TRANSPARENT-NOCONFLICT" ; Transparent on busy time 2941 ; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects 2942 ; can overlap it. 2944 / "OPAQUE-NOCONFLICT" ; Opaque on busy time 2945 ; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects 2946 ; can overlap it. 2947 ; 2948 ;Default value is OPAQUE 2950 The following is an example of this property for an object that is 2951 opaque or blocks on free/busy time searches plus no other object can 2952 overlap it: 2954 TRANSP:OPAQUE-NOCONFLICT 2956 8. New Components 2958 8.1 VAGENDA Component 2960 Component Name: VAGENDA 2962 Purpose: Provide a grouping of properties that defines an agenda. 2964 Formal Definition: There are two formats of a VAGENDA. (1) When it 2965 is being created, and (2) how it exists in the VCALSTORE. A 2966 "VAGENDA" component in the VCALSTORE is defined by the following 2967 notation table and ABNF notation. 2969 The following is a summary of the properties of a calendar. 2971 Name Read Description 2972 Only 2973 ------------------------------------------------------------------ 2974 ALLOW-CONFLICT N This boolean value indicates whether or not 2975 the calendar supports object conflicts. That 2976 is, whether or not any of the components in 2977 the calendar can have a time overlap. MUST BE 2978 FALSE if VCALSTORE ALLOW-CONFLICT is FALSE. 2980 CALID N A unique identifier within the VCALSTORE for 2981 the calendar. MUST NOT BE empty. MUST BE a 2982 relative calid in a VAGENDA. 2984 CALSCALE N The CALSCALE for this calendar. MUST BE from 2985 the VCALSTORE CALSCALE list. The default is 2986 the first entry in the VCALSTORE CALSCALE 2987 list. 2989 CREATED Y timestamp of the calendar's create date. 2991 DEFAULT-CHARSET N The charset for this calendar. MUST BE from 2992 the VCALSTORE DEFAULT-CHARSET list. If empty 2993 then it is the first entry in the VCALSTORE 2994 DEFAULT-CHARSET list. 2996 DEFAULT-LOCALE 2997 N The locale for this calendar. MUST BE from 2998 the VCALSTORE DEFAULT-LOCALE list. If empty 2999 then it is the first entry in the VCALSTORE 3000 DEFAULT-CHARSET list. 3002 DEFAULT-TZID N The id of the timezone associated with this 3003 calendar. If empty it is the first entry 3004 in VCALSTORE DEFAULT-TZID. 3006 LAST-MODIFIED Y The timestamp when the properties of the 3007 calendar were last updated. 3009 NAME N Optional display name for this calendar. It 3010 is a localizeable string. May be multiple 3011 instance and no two instances may have the 3012 same LANG parameter. All instances MUST have 3013 the LANG parameter. 3015 OWNER N A multi-instanced property indicating the 3016 calendar owner. Each entry returned will be a 3017 UPN. There MUST BE at least one owner. 3019 RELATED-TO N An optional multi-instance property indicating 3020 any relationship to other CALIDs and their CALIDs. 3022 agenda = "BEGIN" ":" "VAGENDA" CRLF 3023 agendaprop 3024 "END" ":" "VAGENDA" CRLF 3026 agendaprop = *( 3027 ; The following MUST occur exactly once. 3029 allow-conflict / calid / calscale / created 3030 / default-charset / default-locale 3031 / default-tzid / last-modified / 3033 ; The following MUST occur at least once. 3034 ; and the value MUST NOT be empty. 3036 / owner 3038 ; The following are optional, 3039 ; and MAY occur more than once. 3041 / name / related-to / iana-token / x-prop / x-comp 3042 ) 3044 When creating a VAGENDA, use the following notation: 3046 agendac = "BEGIN" ":" "VAGENDA" CRLF 3047 agendacprop 3048 "END" ":" "VAGENDA" CRLF 3050 agendacprop = *( 3051 ; The following MUST occur exactly once. 3053 allow-conflict / calid / calscale 3054 / default-charset / default-locale 3055 / default-tzid / 3057 ; The following MUST occur at least once. 3058 ; and the value MUST NOT be empty. 3060 / owner 3062 ; The following are optional, 3063 ; and MAY occur more than once. 3065 / name / related-to / iana-token / x-prop / x-comp 3066 ) 3068 To fetch all of the properties from the targeted VAGENDA. This does 3069 not fetch any components: 3071 SELECT * FROM VAGENDA 3073 To fetch all of the properties from the targeted VAGENDA and all of 3074 the contained components, use the special '*.*' value: 3076 SELECT *.* FROM VAGENDA 3078 8.2 VCALSTORE Component 3080 Component Name: VCALSTORE 3082 Purpose: Provide a grouping of properties that defines a calendar 3083 store. 3085 Formal Definition: A "VCALSTORE" component is defined by the 3086 following table and ABNF notation. The creation of a VCALSTORE is an 3087 administrative task and not part of the CAP protocol. 3089 The following is a summary of the properties of the calendar store. 3091 Name Read Description 3092 Only 3093 ------------------------------------------------------------------- 3094 ALLOW-CONFLICT Y This boolean value indicates Whether or not 3095 the VCALSTORE supports object conflicts. That 3096 is, whether or not any of the objects in any 3097 calendar can overlap. If FALSE, then the CS 3098 does not allow conflicts for any entry in any 3099 calendar. How this property is set in the 3100 VCALSTORE is an administrative or implementation 3101 specific issue and is not covered in CAP. 3103 CALSCALE Y A comma separated list of CALSCALEs supported 3104 by this CS. All Calendar CALSCALE properties 3105 MUST BE from this list. MUST contain at least 3106 "GREGORIAN". The default for newly created 3107 calendars is the first entry. How this property 3108 is set in the VCALSTORE is an administrative 3109 or implementation specific issue and is not 3110 covered in CAP. 3112 CALMASTER N URL of contact address for person responsible. 3113 SHOULD BE mailto URL. MUST BE an IANA registered 3114 URL scheme. This is to allow external entities a 3115 contact point for the CS. 3117 CHILDREN N A multi instance property that lists all of the 3118 calendars in this VCALSTORE. The values are the 3119 relative CSID for each calendar. 3121 CREATED Y The timestamp of the CS creation time. 3123 CSID Y The CSID of this calendar store. MUST NOT be 3124 empty. How this property is set in the VCALSTORE 3125 is an administrative or implementation specific 3126 issue and is not covered in CAP. 3128 DEFAULT-CHARSET Y A comma separated lists of charsets supported 3129 by this CS. MUST contain at least "UTF-8". 3130 The first is the default for all newly created 3131 calendars. How this property is set in the 3132 VCALSTORE is an administrative or implementation 3133 specific issue and is not covered in CAP. 3135 DEFAULT-LOCALE Y A comma separated list of locales supported 3136 by this CS. MUST contain at least one entry. 3137 ("en_US" for example). The first is the default 3138 for all newly created calendars. There is 3139 no default for this property in the VCALSTORE. 3141 DEFAULT-VCARS N A multivalued property containing the CARID's for 3142 the default VCARs for newly created top level 3143 calendars. It MUST include at a minimum 3144 READBUSYTIMEINFO, REQUESTONLY, UPDATEPARTSTATUS, 3145 and DEFAULTOWNER. 3147 DEFAULT-TZID N A comma separated list of TZID's supported by 3148 the CS. These will be known across all calendars. 3149 Calendar entries take precedence if they exist 3150 in both the CS and calendar. MUST include at least 3151 UTC. First entry is default for all newly created 3152 calendars. 3154 LAST-MODIFIED Y The timestamp when the Properties of the CS 3155 were last updated or calendars were created 3156 or deleted. 3158 NAME N Optional, multi instance display names for 3159 this CS. It is a localizeable string. May 3160 be multiple instance and no two instances may 3161 have the same LANG parameter. All instances 3162 MUST have the LANG parameter in the VCALSTORE. 3164 RELATED-TO N An optional multi-instance property indicating 3165 any relationship to other CSs and those CALIDs. 3167 calstorec = "BEGIN" ":" "VCALSTORE" CRLF 3168 calstoreprop 3169 "END" ":" "VCALSTORE" CRLF 3171 calstoreprop = *( 3173 ; the following MUST occur exactly once 3175 allow-conflict / calscale / calmaster 3176 / created / csid / default-charset 3177 / default-locale / default-vcars 3178 / default-tzid / last-modified 3180 ; the following are optional, 3181 ; and MAY occur more than once 3183 / children / name / related-to 3185 ) 3187 To fetch all of the properties from the targeted VCALSTORE and not 3188 fetch the calendars that it contains: 3190 SELECT * FROM VCALSTORE 3192 To fetch all of the properties from the targeted VCALSTORE and all of 3193 the contained calendars and all of those calendars contained 3194 properties and components, use the special '*.*' value: 3196 SELECT *.* FROM VCALSTORE 3198 8.3 VCAR Component 3200 Component Name: VCAR 3202 Purpose: Provide a grouping of calendar access rights. 3204 Format Definition: A "VCAR" component is defined by the following 3205 notation: 3207 carc = "BEGIN" ":" "VCAR" CRLF 3208 carprop 1*rightc 3209 "END" ":" "VCAR" CRLF 3211 carprop = 1*( 3213 ; 'carid' is REQUIRED, 3214 ; but MUST NOT occur more than once 3216 carid / 3218 ; the following are OPTIONAL, 3219 ; and MAY occur more than once 3221 name / x-prop / iana-prop 3222 ) 3224 Description: A "VCAR" component is a grouping of properties, and 3225 "VRIGHT" components, that represents access rights granted or denied 3226 to UPNs. 3228 The "CARID" property specifies the local identifier for the "VCAR" 3229 component. The "NAME" property specifies a localizeable display 3230 name. 3232 Example: In the following example, the UPN "foo@example.com" is given 3233 read access to the "DTSTART" and "DTEND" VEVENT properties. No other 3234 access is specified: 3236 BEGIN:VCAR 3237 CARID:Veiw Start and End Times 3238 NAME:View Start and End Times 3239 BEGIN:VRIGHT 3240 GRANT:foo@example.com 3241 PERMISSION:READ 3242 SCOPE:SELECT DTSTART,DTEND FROM VEVENT 3243 END:VRIGHT 3244 END:VCAR 3246 In this example, all UPNs are given read access to "DTSTART" and 3247 "DTEND" properties of VEVENT components. "All CUs and UGs" are 3248 specified by the UPN value "*". Note that this enumerated UPN value 3249 is not in quotes: 3251 BEGIN:VCAR 3252 CARID:ViewStartEnd2 3253 NAME:View Start and End Times 2 3254 BEGIN:VRIGHT 3255 GRANT:* 3256 PERMISSION:READ 3257 SCOPE:SELECT DTSTART,DTEND FROM VEVENT 3258 END:VRIGHT 3259 END:VCAR 3261 In these examples, full calendar access rights are given to the 3262 OWNER(), and a hypothetical administrator is given access rights to 3263 specify calendar access rights. If no other rights are specified, 3264 only these two UPNs can specify calendar access rights: 3266 BEGIN:VCAR 3267 CARID:some-id-3 3268 NAME:Only OWNER or ADMIN Settable VCARs 3269 BEGIN:VRIGHT 3270 GRANT:OWNER() 3271 PERMISSION:* 3272 SCOPE:SELECT * FROM VAGENDA 3273 END:VRIGHT 3274 BEGIN:VRIGHT 3275 GRANT:cal-admin@example.com 3276 PERMISSION:* 3277 SCOPE:SELECT * FROM VCAR 3278 RESTRICTION:SELECT * FROM VCAR 3279 END:VRIGHT 3280 END:VCAR 3282 In this example, rights to write, read, modify or delete calendar 3283 access rights are denied to all UPNs. This example would disable 3284 providing different access rights to the calendar store or calendar. 3285 This calendar access right should be specified with great care, as it 3286 removes the ability to change calendar access; even for the owner or 3287 administrator. It could be used by small devices that do not support 3288 the changing of any VCAR: 3290 BEGIN:VCAR 3291 CARID:VeryRestrictiveVCAR-2 3292 NAME:No CAR At All 3293 BEGIN:VRIGHT 3294 DENY:* 3295 PERMISSION:* 3296 SCOPE:SELECT * FROM VCAR 3297 END:VRIGHT 3298 END:VCAR 3300 8.4 VRIGHT Component 3302 Component Name: "VRIGHT" 3304 Purpose: Provide a grouping of properties that describe an access 3305 right (granted or denied). 3307 Format Definition: A "VRIGHT" component is defined by the following 3308 notation: 3310 rightc = "BEGIN" ":" "VRIGHT" CRLF 3311 rightprop 3312 "END" ":" "VRIGHT" CRLF 3314 rightprop = 2*( 3316 ; either 'grant' or 'deny' MUST 3317 ; occur at least once 3318 ; and MAY occur more than once 3320 grant / deny / 3322 ; 'permission' MUST occur at least once 3323 ; and MAY occur more than once 3325 permission / 3327 ; the following are optional, 3328 ; and MAY occur more than once 3330 scope / restriction / x-prop / iana-prop 3332 ) 3334 Description: A "VRIGHT" component is a grouping of calendar access 3335 right properties. 3337 The "GRANT" property specifies the UPN that is being granted access. 3338 The "DENY" property specifies the UPN is being denied access. The 3339 "PERMISSION" property specifies the actual permission being set. The 3340 "SCOPE" property identifies the calendar store properties, calendar 3341 properties, components, or properties to which the access right 3342 applies. The "RESTRICTION" property specifies restriction on the 3343 value that may take calendar store properties, calendar properties, 3344 calendar components, and properties after a CREATE or MODIFY 3345 operation. Values MUST match all the instances of the RESTRICTION 3346 property to be valid. 3348 8.5 VREPLY Component 3350 Component Name: "VREPLY" 3352 Purpose: Provide a grouping of arbitrary properties and components 3353 that are the data set result from an issued command. 3355 Format Definition: A "VREPLY" component is defined by the following 3356 notation: 3358 replyc = "BEGIN" ":" "VREPLY" CRLF 3359 any-prop-or-comp 3360 "END" ":" "VREPLY" CRLF 3362 any-prop-or-comp = ; Zero or more iana or experimental 3363 ; properties and components, in any order. 3365 Description: Provide a grouping of arbitrary properties and 3366 components that are the data set result from an issued command. 3368 A query can return a predictable set of arbitrary properties and 3369 components. This container is used by query and other commands to 3370 return data that does not fit into any other container. It may 3371 contain any valid property or component, even if they are not 3372 registered. 3374 8.6 VQUERY Component 3376 Component Name: VQUERY 3378 Purpose: A container to specify what is to be fetched from a CS. 3380 Format Definition: A "VQUERY" component is defined by the following 3381 notation: 3383 queryc = "BEGIN" ":" "VQUERY" CRLF 3384 queryprop 3385 "END" ":" "VCAR" CRLF 3387 queryprop = 1*( 3389 ; 'queryid' is OPTIONAL but MUST NOT occur 3390 ; more than once 3391 ; 3392 queryid 3394 ; the following are OPTIONAL, and MAY occur 3395 ; more than once 3396 ; 3397 / name / x-prop / iana-prop 3399 ; the following MUST occur at least once. 3400 ; 3401 / query 3403 ) 3405 Description: A "VQUERY" contains properties that specify which 3406 properties and components the CS is requested to return during a 3407 SEARCH command. 3409 The "QUERYID" property specifies the local identifier for a stored 3410 "VQUERY" component. The "NAME" property specifies a localizeable 3411 display name of a stored "VQUERY" component. Normally "NAME" and 3412 "QUERYID" are used when looking for a correct stored "VQUERY" 3413 component, or when storing a "VQUERY" component. 3415 For examples, see Section 6.1.1. 3417 9. Commands and Responses 3419 CAP commands and responses are described in this section. 3421 9.1 CAP Commands (CMD) 3423 All commands are send using the CMD property. 3425 Property Name: CMD 3427 Purpose: The property defines the command to be sent. 3429 Value Type: TEXT 3431 Property Parameters: Non-standard, id, localize, latency, action or 3432 options. 3434 Conformance: This property is the method used to specify the commands 3435 to a CS and can exist in any object sent to the CS. 3437 Description: All of the command to the CS are supplied in this 3438 property. The OPTIONS parameter is overloaded and its meaning is 3439 dependent on the CMD value supplied. 3441 Format Definition: The property is defined by the following notation: 3443 cmd = "CMD" ( 3444 / abort-cmd 3445 / continue-cmd 3446 / create-cmd 3447 / delete-cmd 3448 / generate-uid-cmd 3449 / get-capability-cmd 3450 / identify-cmd 3451 / modify-cmd 3452 / move-cmd 3453 / reply-cmd 3454 / search-cmd 3455 / set-locale-cmd 3456 ) CRLF 3458 id-param = ";" "ID" "=" unique-id 3459 ; The text value supplied is a unique value 3460 ; shared between the CUA and CS to uniquely 3461 ; identify the instance of command in the 3462 ; the current CUA session. The value has 3463 ; no meaning to other CUAs or other sessions. 3465 unique-id = ; text 3467 localize-param = ";" "LOCALIZE" "=" beep-localize 3468 ; The value supplied MUST BE one value from the initial 3469 ; BEEP greeting 'localize' attribute specifying 3470 ; the locale to use for error messages during 3471 ; this instance of the command sent. 3473 beep-localize = ; text 3475 latency-param = ";" "LATENCY" "=" latency-sec 3476 ; The value supplied in the time in seconds. 3477 ; If latency is supplied then action MUST BE 3478 ; supplied. 3480 latency-sec = integer 3482 action-parm = ";" "ACTION" "=" ( "ASK" / "ABORT" ) 3483 ; If latency is supplied then action MUST BE 3484 ; supplied. 3486 option-param = ";" "OPTIONS" "=" cmd-specific 3488 cmd-specific = ; The value supplied is dependent on the 3489 ; CMD value. See the specific CMDs below 3490 ; for the correct values to use for each 3491 ; CMD. 3493 option-value = paramtext 3495 Calendaring commands allow a CUA to directly manipulate a calendar. 3497 Calendar access rights can be granted or denied for any commands. 3499 9.1.1 Bounded Latency 3501 A CAP command can have an associated maximum latency time by 3502 specifying the "LATENCY" parameter. If the command is unable to be 3503 completed in the specified amount of time (as specified by the 3504 "LATENCY" parameter value), then a "TIMEOUT" command MUST BE sent on 3505 the same channel to which there MUST BE a an "ABORT" or a "CONTINUE" 3506 command reply. If the CUA initiated the original command, then the 3507 CS would issue the "TIMEOUT" command and the CUA would then have to 3508 issue an "ABORT" or "CONTINUE" command. If the CS initiated the 3509 original command then the CUA would have to issue the "TIMEOUT" and 3510 the CS would send the "ABORT" or "CONTINUE". 3512 Upon receiving an "ABORT" command, the command must then be 3513 terminated. Only the "ABORT", "TIMEOUT", "REPLY, and "CONTINUE" 3514 commands can not be aborted. The "ABORT", "TIMEOUT", and "REPLY" 3515 commands MUST NOT have latency set. 3517 Upon receiving a "CONTINUE" command the work continues. Note that a 3518 new latency time MAY BE included in a "CONTINUE" command indicating 3519 to continue the original command until the "LATENCY" parameter value 3520 expires or the results of the original command can be returned. 3522 Both the "LATENCY" parameter and the "ACTION" parameter MUST BE 3523 supplied to any "CMD" property, or nether can be added to the "CMD" 3524 property. The "LATENCY" parameter MUST BE set to the maximum latency 3525 time in seconds. The "ACTION" parameter accepts the following 3526 values: "ASK" and "ABORT". 3528 If the maximum latency time is exceeded and the "ACTION" parameter is 3529 set to the "ASK" value, then "TIMEOUT" command MUST BE sent. 3530 Otherwise if the "ACTION" parameter is set to the "ABORT" value then 3531 the command MUST BE terminated and return a REQUEST-STATUS code of 3532 2.0.3 for the original command. 3534 Example: 3536 In this example the initiator asks for the listeners capabilities. 3538 I: Content-Type: text/calendar 3539 I: 3540 I: BEGIN:VCALENDAR 3541 I: VERSION:2.0 3542 I: PRODID:The CUA's PRODID 3543 I: CMD;ID=xyz12346:GET-CAPABILITY 3544 I: END:VCALENDAR 3546 # After 3 seconds 3548 L: Content-Type: text/calendar 3549 L: 3550 L: BEGIN:VCALENDAR 3551 L: VERSION:2.0 3552 L: CMD;ID=xyz12346:TIMEOUT 3553 L: END:VCALENDAR 3555 In order to continue and give the CS more time then the CUA would 3556 issue a "CONTINUE" command: 3558 I: Content-Type: text/calendar 3559 I: 3560 I: BEGIN:VCALENDAR 3561 I: VERSION:2.0 3562 I: CMD;ID=xyz12346;LATENCY=3;ACTION=ask:CONTINUE 3563 I: END:VCALENDAR 3565 L: Content-Type: text/calendar 3566 L: 3567 L: BEGIN:VCALENDAR 3568 L: VERSION:2.0 3569 L: CMD;ID=xyz12346:REPLY 3570 L: BEGIN:VREPLY 3571 L: REQUEST-STATUS:2.0.3;Continued for 3 more seconds 3572 L: END:VREPLY 3573 L: END:VCALENDAR 3575 To abort the command and not wait any further then issue an "ABORT" 3576 command: 3578 I: Content-Type: text/calendar 3579 I: 3580 I: BEGIN:VCALENDAR 3581 I: VERSION:2.0 3582 I: CMD;ID=xyz12346:ABORT 3583 I: END:VCALENDAR 3585 # Which would result in a 2.0.3 reply. 3587 L: Content-Type: text/calendar 3588 L: 3589 L: BEGIN:VCALENDAR 3590 L: VERSION:2.0 3591 L: CMD;ID=xyz12346:REPLY 3592 L: BEGIN:VREPLY 3593 L: REQUEST-STATUS:2.0.3;Aborted As Requested. 3594 L: END:VREPLY 3595 L: END:VCALENDAR 3597 9.1.2 ABORT Command 3599 CMD: ABORT 3601 Purpose: The "ABORT" command is sent to request that the named or 3602 only in process command be aborted. Latency MUST not be supplied 3603 with the "ABORT" command. 3605 Formal Definition: An "ABORT" command is defined by the following 3606 notation: 3608 abort-cmd = abortparam ":" "ABORT" 3610 abortparam = *( 3612 ; the following are optional, 3613 ; but MUST NOT occur more than once 3615 id-param 3616 / localize-param 3618 ; the following is optional, 3619 ; and MAY occur more than once 3621 / (";" xparam) 3623 ) 3625 The REPLY of any "ABORT" command is: 3627 abort-reply = "BEGIN" ":" "VCALENDAR" CRLF 3628 calprops 3629 abort-vreply 3630 "END" ":" "VCALENDAR" CRLF 3632 abort-vreply = "BEGIN" ":" "VREPLY" CRLF 3633 request-status 3634 *(x-prop) 3635 "END" ":" "VREPLY" CRLF 3637 9.1.3 CONTINUE Command 3639 CMD: CONTINUE 3640 Purpose: The "CONTINUE" command is only sent after a "TIMEOUT" 3641 command has been received to inform the other end of the session to 3642 resume working on a command. 3644 Formal Definition: A "CONTINUE" command is defined by the following 3645 notation: 3647 continue-cmd = continueparam ":" "CONTINUE" 3649 continueparam = *( 3651 ; the following are optional, 3652 ; but MUST NOT occur more than once 3654 id-param 3655 / localize-param 3656 / latency-param 3658 ; the following MUST occur exactly once and only 3659 ; when the latency-param has been supplied and 3660 ; MUST NOT be supplied if the latency-param is 3661 ; not supplied. 3663 / action-param 3665 ; the following is optional, 3666 ; and MAY occur more than once 3668 / (";" xparam) 3670 ) 3672 The REPLY of any "CONTINUE" command is: 3674 continue-reply = "BEGIN" ":" "VCALENDAR" CRLF 3675 calprops 3676 continue-vreply 3677 "END" ":" "VCALENDAR" CRLF 3679 continue-vreply = "BEGIN" ":" "VREPLY" CRLF 3680 request-status 3681 *(x-prop) 3682 "END" ":" "VREPLY" CRLF 3684 9.1.4 CREATE Command 3686 CMD: CREATE 3688 Purpose: The "CREATE" command is used to create one or more 3689 iCalendar objects in the store in the "BOOKED" or "UNPROCESSED" 3690 state. 3692 A CUA MAY send a CREATE command to a CS. The CREATE command MUST BE 3693 implemented by all CSs. 3695 The CS MUST NOT send a CREATE command to any CUA. 3697 Formal Definition: A "CREATE" command is defined by the following 3698 notation: 3700 create-cmd = createparam ":" "CREATE" 3702 createparam = *( 3704 ; the following are optional, 3705 ; but MUST NOT occur more than once 3707 id-param 3708 / localize-param 3709 / latency-param 3711 ; the following MUST occur exactly once and only 3712 ; when the latency-param has been supplied and 3713 ; MUST NOT be supplied if the latency-param is 3714 ; not supplied. 3715 n 3716 / action-param 3718 ; the following is optional, 3719 ; and MAY occur more than once 3721 / (";" xparam) 3723 ) 3725 Response: 3727 One iCalendar object per TARGET property MUST BE 3728 returned. 3730 The REPLY of any "CREATE" command is: 3732 create-reply = "BEGIN" ":" "VCALENDAR" CRLF 3733 calprops 3734 1*(create-vreply) 3735 "END" ":" "VCALENDAR" CRLF 3737 create-vreply = "BEGIN" ":" "VREPLY" CRLF 3738 created-id 3739 request-status 3740 *(x-prop) 3741 "END" ":" "VREPLY" CRLF 3743 ; Where the id is appropriate for the 3744 ; type of object created: 3745 ; 3746 ; VAGENDA = calid 3747 ; VCAR = carid 3748 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 3749 ; VQUERY = queryid 3750 ; ALARM = sequence 3751 ; x-component = x-id 3752 ; 3753 created-id = ( calid / carid / uid / uid dtstamp 3754 / queryid / tzid / sequence / x-id) 3756 The TARGET property specify the containers where the component(s) 3757 will be created. This can be a CSID, or a CALID. 3759 The iCalendar portion of the command can be any valid [iTIP] object 3760 or any valid CAP object using the following restriction table. There 3761 MUST BE at least one component inside of the VCALENDAR object. 3763 If the iCalendar object being created does not have a "METHOD" 3764 property, then is not an iTIP object, then its state will be 3765 "BOOKED". Use the "DELETE" command to set the state of an object to 3766 the "DELETED" state. A CUA can not use the "CREATE" command to 3767 create an object in the "DELETED" state. 3769 If an iTIP object is being booked, then the "METHOD" property MUST 3770 NOT BE supplied". Otherwise any iTIP object MUST BE have valid iTIP 3771 METHOD value and it is a scheduling request being deposited into the 3772 CS and will have its state set to "UNPROCESSED". 3774 Restriction table for the CREATE command: 3776 create-minumum = "BEGIN" ":" "VCALENDAR" CRLF 3777 calprops 3778 *(iana-prop) 3779 *(x-prop) 3780 1*(create-comp) 3781 "END" ":" "VCALENDAR" CRLF 3783 ; If The following contain the "METHOD" 3784 ; property they MUST conform to [iTIP]. 3785 ; 3786 create-comp = agendac / carc / queryc 3787 / timezonec / freebusyc 3788 / eventc / todoc / journalc 3789 / iana-component / x-component 3791 Restriction Table for the iCalendar section of a reply that contains 3792 an iCalendar object is any valid [iTIP] response plus any from this 3793 restriction table: 3795 create-reply = "BEGIN" ":" "VCALENDAR" CRLF 3796 calprops 3797 *(iana-prop) 3798 *(x-prop) 3799 1*(create-comp-vreply) 3800 "END" ":" "VCALENDAR" CRLF 3802 create-vreply = "BEGIN" ":" "VREPLY" CRLF 3803 created-id 3804 request-status 3805 "END" ":" "VREPLY" CRLF 3807 ; Where the id is appropriate for the 3808 ; type of object created: 3809 ; 3810 ; VAGENDA = calid 3811 ; VCAR = carid 3812 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 3813 ; VQUERY = queryid 3814 ; ALARM = sequence 3815 ; x-component = x-id 3816 ; 3817 created-id = ( calid / carid / uid / uid dtstamp 3818 / queryid / tzid / sequence / x-id) 3820 In the following example, two new top level VAGENDAs are created. 3822 Note that the CSID of the server is cal.example.com which is where 3823 the new VAGENDAs are going to be created. 3825 C: Content-Type: text/calendar 3826 C: 3827 C: BEGIN:VCALENDAR 3828 C: VERSION:2.0 3829 C: CMD;ID=creation01:CREATE 3830 C: TARGET:cal.example.com 3831 C: BEGIN:VAGENDA <- data for 1st new calendar 3832 C: CALID:relcalz1 3833 C: NAME;LANGUAGE=en_US:Bill's Soccer Team 3834 C: OWNER:bill 3835 C: CALMASTER:mailto:bill@example.com 3836 C: TZID:US/Pacific 3837 C: END:VAGENDA 3838 C: BEGIN:VAGENDA <- data for 2nd new calendar 3839 C: CALID:relcalz2 3840 C: NAME;LANGUAGE=EN-us:Mary's personal calendar 3841 C: OWNER:mary 3842 C: CALMASTER:mailto:mary@example.com 3843 C: TZID:US/Pacific 3844 C: END:VAGENDA 3845 C: END:VCALENDAR 3847 When there are multiple TARGET values in the original command object 3848 then the replies MUST BE in the exact same order as they were 3849 provided to the CS. The same is true for the objects created, their 3850 responses MUST BE in the exact same order as they were supplied to 3851 the CS. 3853 S: Content-Type: text/calendar 3854 S: 3855 S: BEGIN:VCALENDAR 3856 S: VERSION:2.0 3857 S: CMD;ID=creation01:REPLY 3858 S: TARGET:cal.example.com 3859 S: BEGIN:REPLY <- Reply for 1st calendar create 3860 S: CALID:relcalz1 3861 S: REQUEST-STATUS:2.0 3862 S: END:REPLY 3863 S: BEGIN:VREPLY <- Reply for 2nd calendar create 3864 S: CALID:relcalz2 3865 S: REQUEST-STATUS:2.0 3866 S: END:VREPLY 3867 S: END:VCALENDAR 3869 To create a new component in multiple containers simply name all of 3870 the containers in the TARGET in the create command. Here a new 3871 VEVENT is created in two TARGETs. In this example, the VEVENT is one 3872 new iTIP REQUEST object in two calendars. The results would be 3873 iCalendar object that conform to the iTIP replies as defined in iTIP. 3875 The "VREPLY" components MUST always be returned in the same order 3876 that the objects were listed in the original "CREATE" command. If 3877 there are multiple "TARGET" and components in the same create command 3878 then the reply is first listed by the "TARGET" order of the original 3879 create command, then component replies within that "TARGET" are 3880 ordered the same as in the original create command. 3882 This example shows two VEVENTs being created in each of two TARGETs: 3884 C: Content-Type: text/calendar 3885 C: 3886 C: BEGIN:VCALENDAR 3887 C: VERSION:2.0 3888 C: CMD;ID=creation02:CREATE 3889 C: METHOD:REQUEST 3890 C: TARGET:relcalz1 3891 C: TARGET:relcalz2 3892 C: BEGIN:VEVENT 3893 C: DTSTART:20030307T180000Z 3894 C: UID:FirstInThisExample-1 3895 C: DTEND:20030307T190000Z 3896 C: SUMMARY:Important Meeting 3897 C: END:VEVENT 3898 C: BEGIN:VEVENT 3899 C: DTSTART:20040307T180000Z 3900 C: UID:SecondInThisExample-2 3901 C: DTEND:20040307T190000Z 3902 C: SUMMARY:Important Meeting 3903 C: END:VEVENT 3904 C: END:VCALENDAR 3906 The CS would sends the REPLY in separate MIME objects, one per 3907 TARGET. 3909 S: Content-Type: text/calendar 3910 S: 3911 S: BEGIN:VCALENDAR 3912 S: VERSION:2.0 3913 S: CMD;ID=creation02:REPLY 3914 S: TARGET:relcalz1 <- 1st TARGET listed 3915 S: BEGIN:REPLY <- Reply for 1st VEVENT create in 1st TARGET. 3916 S: UID:FirstInThisExample-1 3917 S: REQUEST-STATUS:2.0 3918 S: END:VREPLY 3919 S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 1st TARGET. 3920 S: UID:SecondInThisExample-2 3921 S: REQUEST-STATUS:2.0 3922 S: END:VREPLY 3923 S: END:VCALENDAR 3925 And would send the second part of the reply later: 3927 S: Content-Type: text/calendar 3928 S: 3929 S: BEGIN:VCALENDAR 3930 S: VERSION:2.0 3931 S: CMD;ID=creation02:REPLY 3932 S: TARGET:relcalz2 <- 2nd TARGET listed 3933 S: BEGIN:REPLY <- Reply for 1st VEVENT create in 2nd TARGET. 3934 S: UID:FirstInThisExample-1 3935 S: REQUEST-STATUS:2.0 3936 S: END:VREPLY 3937 S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 2nd TARGET. 3938 S: UID:SecondInThisExample-2 3939 S: REQUEST-STATUS:2.0 3940 S: END:VREPLY 3941 S: END:VCALENDAR 3943 9.1.5 DELETE Command 3945 CMD: DELETE 3947 Purpose: The DELETE command physically removes the QUERY result from 3948 the store or marks it for deletion. 3950 A CUA MAY send a DELETE command to a CS. The DELETE command MUST BE 3951 implemented by all CSs. 3953 The CS MUST NOT send a DELETE command to any CUA. 3955 Formal Definition: A "DELETE" command is defined by the following 3956 notation: 3958 delete-cmd = deleteparam ":" "DELETE" 3960 deleteparam = *( 3962 ; the following are optional, 3963 ; but MUST NOT occur more than once 3965 id-param 3966 / localize-param 3967 / latency-param 3968 / option-param "MARK" 3970 ; The following MUST occur exactly once and only 3971 ; when the latency-param has been supplied and 3972 ; MUST NOT be supplied if the latency-param is 3973 ; not supplied. 3975 / action-param 3977 ; the following is optional, 3978 ; and MAY occur more than once 3980 / (";" xparam) 3982 ) 3984 The DELETE command is used to delete calendars or components. The 3985 included "VQUERY" component(s) specifies the container(s) to delete. 3987 If a component is to be marked for delete and not physically removed, 3988 then include the "OPTIONS" parameter with its value set to "MARK" to 3989 alter its state to "DELETED". 3991 When components are deleted, only the top most component REQUEST- 3992 STATUS is returned. No REQUEST-STATUS is returned for components 3993 inside of the selected components. There MUST BE one "VREPLY" 3994 component returned for each object that is deleted or marked for 3995 delete. 3997 Restriction Table for the REPLY of any DELETE command. 3999 delete-reply = "BEGIN" ":" "VCALENDAR" CRLF 4000 calprops 4001 1*(delete-vreply) 4002 "END" ":" "VCALENDAR" CRLF 4004 delete-vreply = "BEGIN" ":" "VREPLY" CRLF 4005 deleted-id 4006 request-status 4007 "END" ":" "VREPLY" CRLF 4009 ; Where the id is appropriate for the 4010 ; type of object deleted: 4011 ; 4012 ; VAGENDA = calid 4013 ; VCAR = carid 4014 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 4015 ; VQUERY = queryid 4016 ; ALARM = sequence 4017 ; x-component = x-id 4018 ; 4019 deleted-id = ( calid / carid / uid / uid dtstamp 4020 / queryid / tzid / sequence / x-id) 4022 Example to delete a VEVENT with VEVENT UID 'abcd12345' from the 4023 calendar "relcald-22" from the current CS: 4025 C: Content-Type: text/calendar 4026 C: 4027 C: BEGIN:VCALENDAR 4028 C: TARGET:relcalid-22 4029 C: CMD;ID:"random but unique per CUA":DELETE 4030 C: BEGIN:VQUERY 4031 C: QUERY:SELECT * FROM VEVENT WHERE UID = 'abcd12345' 4032 C: END:VQUERY 4033 C: END:VCALENDAR 4035 S: BEGIN:VCALENAR 4036 S: TARGET:relcalid-22 4037 S: CMD;ID:"random but unique per CUA":REPLY 4038 S: BEGIN:VREPLY 4039 S: UID:abcd12345 4040 S: REQUEST-STATUS:3.0 4041 S: END:VREPLY 4042 S: END:VCALENDAR 4044 One or more iCalendar objects will be returned that contain a 4045 REQUEST-STATUS for the deleted components. There could have been 4046 more than one component deleted, Any booked and any number of 4047 unprocessed iTIP scheduling components that matched the QUERY value 4048 in the above example. Each unique "METHOD" property value that was 4049 deleted from the store MUST BE in a separate iCalendar object. This 4050 is because only one "METHOD" property is allowed in a single 4051 "VCALENDAR" BEGIN/END block. 4053 9.2 GENERATE-UID Command 4055 CMD: GENERATE-UID 4057 Purpose: The GENERATE-UID command returns one or more unique 4058 identifiers which MUST BE globally unique. 4060 The GENERATE-UID command MAY BE sent to any CS. The GENERATE-UID 4061 command MUST BE implemented by all CSs. 4063 The GENERATE-UID command MUST NOT be sent to a CUA. 4065 Formal Definition: A "GENERATE-UID" command is defined by the 4066 following notation: 4068 generate-uid-cmd = genuidparam ":" "GENERATE-UID" 4070 genuidparam = *( 4071 ; The following are optional, 4072 ; but MUST NOT occur more than once. 4074 id-param 4075 / localize-param 4076 / latency-param 4078 ; The following MUST occur exactly once and only 4079 ; when the latency-param has been supplied and 4080 ; MUST NOT be supplied if the latency-param is 4081 ; not supplied. 4083 / action-param 4085 ; The following is optional, 4086 ; and MAY occur more than once. 4088 / (";" xparam) 4090 ; The following MUST BE supplied exactly once. 4091 ; The value specifies the number of UIDs to 4092 ; be returned. 4094 / option-param integer 4096 ) 4098 Response: 4100 gen-reply = "BEGIN" ":" "VCALENDAR" CRLF 4101 calprops 4102 1*(delete-vreply) 4103 "END" ":" "VCALENDAR" CRLF 4105 gen-vreply = "BEGIN" ":" "VREPLY" CRLF 4106 *(uid) 4107 request-status 4108 "END" ":" "VREPLY" CRLF 4110 Example: 4112 C: BEGIN:VCALENDAR 4113 C: VERSION:2.0 4114 C: PRODID:-//someone's prodid 4115 C: CMD;ID=unique-per-cua-124;OPTIONS=5:GENERATE-UID 4116 C: END:VCALENDAR 4117 S: Content-Type: text/calendar 4118 S: 4119 S: BEGIN:VCALENDAR 4120 S: VERSION:2.0 4121 S: CMD;ID=unique-per-cua-124:REPLY 4122 S: BEGIN:VREPLY 4123 S: UID:20011121T120000Z-12340@cal.example.com 4124 S: UID:20011121T120000Z-12341@cal.example.com 4125 S: UID:20011121T120000Z-12342@cal.example.com 4126 S: UID:20011121T120000Z-12343@cal.example.com 4127 S: UID:20011121T120000Z-12344@cal.example.com 4128 S: END:VREPLY 4129 S: END:VCALENDAR 4131 9.3 GET-CAPABILITY Command 4133 CMD: GET-CAPABILITY 4135 Purpose: The GET-CAPABILITY command returns the capabilities of the 4136 other end of the session. 4138 A CUA MAY send a GET-CAPABILITY command to a CS. The GET-CAPABILITY 4139 command MUST BE implemented by all CSs. 4141 The CS MAY send a GET-CAPABILITY command to any CUA. The GET- 4142 CAPABILITY command MAY be implemented by a CUA. 4144 Formal Definition: A "GET-CAPABILITY" command is defined by the 4145 following notation: 4147 get-capability-cmd = capibiltyparam ":" "GET-CAPABILITY" 4149 genuidparam = *( 4151 ; the following are optional, 4152 ; but MUST NOT occur more than once 4154 id-param 4155 / localize-param 4156 / latency-param 4158 ; the following MUST occur exactly once and only 4159 ; when the latency-param has been supplied and 4160 ; MUST NOT be supplied if the latency-param is 4161 ; not supplied. 4163 / action-param 4165 ; the following is optional, 4166 ; and MAY occur more than once 4168 / (";" xparam) 4170 ) 4172 Response: 4174 The GET-CAPABILITY command returns information about the Calendar 4175 other end of the session given the current state of the connection. 4176 The values returned may differ depending on current user identify and 4177 the security level of the connection. 4179 Client implementations SHOULD NOT require any capability element 4180 beyond those defined in this specification, and MAY ignore any 4181 nonstandard, experimental capability elements. The GET-CAPABILITY 4182 reply may return different results depending on the UPN and if the 4183 UPN is authenticated. 4185 The following CS properties are returned in response to a GET- 4186 CAPABILITY command: 4188 Name Occurs Description 4190 ------------------------------------------------------------------ 4191 CAP-VERSION 1 Version of CAP. MUST include at least "1.0" for 4192 this version of CAP. Like the "VERSION" property, 4193 it may have a range. Uses the exact same 4194 syntax as the "VERSION" property value. 4196 PRODID 1 The product id of the CS. If supplied 4197 in the "VCALENDAR" component, the values 4198 MUST BE identical when originated from the CS. 4200 QUERY-LEVEL 1 Indicates level of SQL support. CAL-QL-1 or NONE. 4201 (NONE is for CS's that allow ITIP methods only 4202 to be deposited and nothing else). If set to 4203 NONE, then the 'car' capability MUST BE set 4204 to NONE. 4206 CAR-LEVEL 1 Indicates level of CAR support. CAR-NONE, 4207 CAR-MIN or CAR-FULL-1. If CAR-FULL-1 is 4208 supplied then CAR-MIN MUST BE assumed. 4209 CAR = NONE MUST BE used when query-level 4210 of NONE is supplied. A CAR-MIN implementation 4211 only supports the DEFAULT-VCARS listed in 4212 the VCALSTORE and does not support the 4213 creation or modification of VCARS. 4215 DATE-MAX 1 The datetime value in UTC beyond which the 4216 server cannot accept. The maximum value 4217 allowed is 99991231T235959Z. 4219 DATE-MIN 1 The datetime value in UTC prior to which 4220 the server cannot accept. The minimum value 4221 allowed is 00000101T000000Z. 4223 MAX-COMPONENT-SIZE 4224 1 A positive integer value that specifies 4225 the size of the largest iCalendar 4226 object that the server will accept in 4227 octets. Objects larger than this will be 4228 rejected. The absence of this attribute 4229 indicates no limit. This is also the 4230 maximum value of any BEEP payload 4231 the CS will accept or send. 4233 COMPONENTS 1 A comma separated list of the names of 4234 components that this CS supports. This 4235 includes any components inside of 4236 other components (VALARM for example). 4237 MUST include at least VCALSTORE, VCALENDAR, 4238 VREPLY, and VAGENDA and at least one of VEVENT, 4239 VTODO, VTIMEZONE, or VJOURNAL. 4241 VERSION 1 Versions of iCalendar support. MUST BE at 4242 least "2.0". This is the same property as 4243 defined in [iCAL]. 4245 RECUR-ACCEPTED 1 Whether the CS accepts recurrence rules. 4246 TRUE or FALSE. 4248 RECUR-EXPAND 1 Whether or not the CS supports the expansion 4249 of recurrence rules. TRUE or FALSE 4251 RECUR-LIMIT 1 The maximum number of occurrences or a 4252 recurrence rule that are expanded by the CS. 4253 Zero means unlimited. 4255 CS-STORES-EXPANDED 4256 1 If TRUE then the CS expands and stores multiple 4257 instances separately when they are booked. 4258 If FALSE then the CS expands instances dynamically 4259 during query. 4261 ITIP-VERSION 1 Version(s) of ITIP, MUST include at least "2447" 4262 to specify RFC-2447 support. Comma separated list. 4264 X-... 0+ May include zero or more experimental properties. 4266 ------------------------------------------------------- 4268 Example: 4270 I: Content-Type: text/calendar 4271 I: 4272 I: BEGIN:VCALENDAR 4273 I: VERSION:2.0 4274 I: PRODID:The CUA's PRODID 4275 I: CMD;ID=unique-per-cua-125:GET-CAPABILITY 4276 I: END:VCALENDAR 4278 L: Content-Type: text/calendar 4279 L: 4280 L: BEGIN:VCALENDAR 4281 L: VERSION:2.0 4282 L: CMD;ID=unique-per-cua-125:REPLY 4283 L: BEGIN:VREPLY 4284 L: CAP-VERSION:1.0 4285 L: PRODID:The CS prodid 4286 L: QUERY-LEVEL:CAL-QL-1 4287 L: CAR-LEVEL:CAR-FULL-1 4288 L: DATE-MAX:99991231T235959Z 4289 L: DATE-MIN:00000101T000000Z 4290 L: MAX-COMPONENT-SIZE:0 4291 L: COMPONENTS:VCALENDAR,VTODO,VJOURNAL,VEVENT,VCAR, 4292 L: VALARM,VFREEBUSY,VTIMEZONE,STANDARD,DAYLIGHT,VREPLY 4293 L: ITIP-VERSION:2447 4294 L: RECUR-ACCEPTED:TRUE 4295 L: RECUR-EXPAND:TRUE 4296 L: RECUR-LIMIT:0 4297 L: CS-STORES-EXPANDED:FALSE 4298 L: X-INET-PRIVATE-COMMANDS:1.0 4299 L: END:VREPLY 4300 L: END:VCALENDAR 4302 9.4 IDENTIFY Command 4304 CMD: IDENTIFY 4306 Purpose: The IDENTIFY command allows the CUA to set a new identity to 4307 be used for calendar access. 4309 A CUA MAY send an IDENTIFY command to a CS. The IDENTIFY command 4310 MUST BE implemented by all CSs. A CS implementation MAY reject all 4311 IDENTIFY commands. 4313 The CS MUST NOT send a IDENTIFY command to any CUA. 4315 Formal Definition: A "IDENTIFY" command is defined by the following 4316 notation: 4318 identify-cmd = identifyparam ":" "IDENTIFY" 4320 identifyparam = *( 4322 ; the following are optional, 4323 ; but MUST NOT occur more than once 4325 id-param 4326 / localize-param 4327 / latency-param 4329 ; the following MUST occur exactly once and only 4330 ; when the latency-param has been supplied and 4331 ; MUST NOT be supplied if the latency-param is 4332 ; not supplied. 4334 / action-param 4336 ; the following is optional, 4337 ; and MAY occur more than once 4339 / (";" xparam) 4341 ; The value is the UPN of the requested 4342 ; identity. If not supplied it is a request 4343 ; to return to the original authenticated identity. 4345 / option-param upn 4347 ) 4349 Response: 4351 "REQUEST-STATUS" with only one of the following 4352 request-status codes: 4354 2.0 Successful. 4356 6.4 Identity not permitted. VCAR restriction. 4358 The CS determines through an internal mechanism if the credentials 4359 supplied at authentication permit the operation as the selected 4360 identity. If they do, the session assumes the new identity, 4361 otherwise a security error is returned. 4363 Example: 4365 C: Content-Type: text/calendar 4366 C: 4367 C: BEGIN:VCALENDAR 4368 C: VERSION:2.0 4369 C: PRODID:-//someone's prodid 4370 C: CMD;ID=unique-per-cua-999;OPTIONS=newUserId:IDENTIFY 4371 C: END:VCALENDAR 4373 S: Content-Type: text/calendar 4374 S: 4375 S: BEGIN:VCALENDAR 4376 S: VERSION:2.0 4377 S: REQUEST-STATUS:2.0;Request Approved 4378 S: END:VCALENDAR 4380 Or if denied: 4382 S: Content-Type: text/calendar 4383 S: 4384 S: BEGIN:VCALENDAR 4385 S: VERSION:2.0 4386 S: REQUEST-STATUS:6.4;Request Denied 4387 S: END:VCALENDAR 4389 And for the CUA to return to its original authenticated identity 4390 the OPTIONS parameter is omitted: 4392 C: Content-Type: text/calendar 4393 C: 4394 C: BEGIN:VCALENDAR 4395 C: VERSION:2.0 4396 C: PRODID:-//someone's prodid 4397 C: CMD;ID=unique-per-cua-995:IDENTIFY 4398 C: END:VCALENDAR 4400 The CS may accept (2.0) or deny (6.4) the request to return to the 4401 original identity. 4403 If a CS considers the IDENTIFY command an attempt to violate 4404 security, the CS MAY terminate the BEEP session without any further 4405 notice to the CUA after sending the REQUEST-STATUS 6.4 reply. 4407 9.5 MODIFY Command 4409 CMD: MODIFY 4411 Purpose: The "MODIFY" command is used to modify existing components. 4413 A CUA MAY send a MODIFY command to a CS. The MODIFY command MUST BE 4414 implemented by all CSs. 4416 The CS MUST NOT send a MODIFY command to any CUA. 4418 Formal Definition: A "MODIFY" command is defined by the following 4419 notation: 4421 modify-cmd = modifyparam ":" "MODIFY" 4423 modifyparam = *( 4425 ; the following are optional, 4426 ; but MUST NOT occur more than once 4428 id-param 4429 / localize-param 4430 / latency-param 4432 ; the following MUST occur exactly once and only 4433 ; when the latency-param has been supplied and 4434 ; MUST NOT be supplied if the latency-param is 4435 ; not supplied. 4437 / action-param 4439 ; the following is optional, 4440 ; and MAY occur more than once 4442 / (";" xparam) 4444 ) 4446 Response: 4448 The "MODIFY" command is used to modify existing components. The 4449 TARGET property specifies the calendars were the components exist 4450 that are going to be modified. 4452 The format of the request is two containers inside of VCALENDAR 4453 container object: 4455 BEGIN:VCALENDAR 4456 ... 4457 BEGIN:VQUERY 4458 ... 4459 END:VQUERY 4460 BEGIN:XXX 4461 ...old-values... 4462 END:XXX 4463 BEGIN:XXX 4464 ...new-values... 4465 END:XXX 4466 END:CALENDAR 4468 The VQUERY selects the components that are to be modified. 4470 Where "XXX" above is a named component type (VEVENT, VTODO, ...). 4471 Both the old and new components MUST BE of the same type. 4473 The old-values is a component and the contents of that component are 4474 going to change and may contain information that helps uniquely 4475 identify the original component (SEQUENCE in the example below). If 4476 the CS can not find a component that matches the QUERY and does not 4477 have at least all of the OLD-VALUES, then a 6.1 error is returned. 4479 The new-values is a component of the same type as old-values and new- 4480 values contains the new data for each selected component. Any data 4481 that is in old-values and not in new-values is deleted from the 4482 selected component. Any values in new-values that was not in old- 4483 values is added to the component. 4485 In this example the VEVENT with UID:unique-58 has; the LOCATION and 4486 LAST-MODIFIED changed, the VALARM with SEQUENCE:3 has its TRIGGER 4487 disabled, the X-LOCAL property is removed from the VEVENT, and a 4488 COMMENT is added. 4490 Because SEQUENCE is used to locate the VALARM in this example, both 4491 the old-values and the new-values contains SEQUENCE:3 and if SEQUENCE 4492 was left out of new-values - it would have been deleted. 4494 Example: 4496 C: Content-Type: text/calendar 4497 C: 4498 C: BEGIN:VCALENDAR 4499 C: VERSION:2.0 4500 C: TARGET:my-cal 4501 C: CMD:ID=unique-mod:MODIFY 4502 C: BEGIN:VQUERY <- Query to select data set. 4503 C: QUERY:SELECT * FROM VEVENT WHERE UID = 'unique-58' 4504 C: END:VQUERY 4505 C: BEGIN:VEVENT <- Start of old data. 4506 C: LOCATION:building 3 4507 C: LAST-MODIFIED:20020101T123456Z 4508 C: X-LOCAL:some private stuff 4509 C: BEGIN:VALARM 4510 C: SEQUENCE:3 4511 C: TRIGGER;RELATED=END:PT5M 4512 C: END:VALARM 4513 C: END:VEVENT 4514 C: BEGIN:VEVENT <- End of new data. 4515 C: LOCATION:building 4 4516 C: LAST-MODIFIED:20020202T010203Z 4517 C: COMMENT:Ignore global trigger. 4518 C: BEGIN:VALARM 4519 C: SEQUENCE:3 4520 C: TRIGGER;ENABLE=FALSE:RELATED=END:PT5M 4521 C: END:VALARM 4522 C: END:VEVENT 4524 X-LOCAL was not supplied in the new-values, so it was deleted. 4525 LOCATION was altered, as was LAST-MODIFIED. The VALARM with 4526 SEQUENCE:3 had its TRIGGER disabled, and SEQUENCE did not change so 4527 it was not effected. COMMENT was added. 4529 When it comes to inline ATTACHMENTs, the CUA only needs to uniquely 4530 identify the contents of the ATTACHMENT value in the old-values in 4531 order to delete them. When the CS compares the attachment data it is 4532 compared in its binary form. The ATTACHMENT value supplied by the 4533 CUA MUST BE valid encoded information. 4535 For example, to delete the same huge inline attachment from every 4536 VEVENT in 'my-cal' that has an ATTACH with the old-values: 4538 BEGIN:VCALENDAR 4539 VERSION:2.0 4540 TARGET:my-cal 4541 CMD:MODIFY 4542 BEGIN:VQUERY 4543 QUERY:SELECT ATTACH FROM VEVENT 4544 END:VQUERY 4545 BEGIN:VEVENT 4546 ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY: 4547 MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U 4548 EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE 4549 ...< remainder of attachment data NOT supplied >.... 4550 END:VEVENT 4551 BEGIN:VEVENT 4552 END:VEVENT 4553 END:VCALENDAR 4555 Above the new-values is empty, so everything in the old-values is 4556 deleted. 4558 Furthermore, the following additional restrictions apply: 4560 1. One can not change the "UID" property of a component. 4562 2. If a contained component is changed inside of a selected 4563 component, and that contained component has multiple instances, 4564 then old-values MUST contain information that uniquely identifies 4565 the instance or instances that are changing. It is valid to 4566 change more than one. As all contained components that match 4567 old-values will be modified. In the first modify example above, 4568 if SEQUENCE were to be deleted from both the old-values and new- 4569 values, then all TRIGGERs that matched the old-values in all 4570 VALARM in the selected VEVENTs would be disabled. 4572 3. The result of the modify MUST BE a valid iCalendar object. 4574 If the REQUEST-STATUS is 2.0, then the entire modification was 4575 successful. 4577 If any error occurred: 4579 No component will be changed at all. That is, it will appear just 4580 as it was prior to the modify and the CAP server SHOULD return a 4581 REQUEST-STATUS for each error that occurred. 4583 There MUST BE at least one error reported. 4585 If multiple components are selected, then what uniquely identified 4586 the component MUST BE returned (UID, QUERYID, ...) if the component 4587 contains a unique identifier. If not sufficient information to 4588 uniquely identify the modified components MUST BE returned in the 4589 reply. 4591 S: Content-Type: text/calendar 4592 S: 4593 S: BEGIN:VCALENDAR 4594 S: TARGET:relcalid 4595 S: CMD;ID=delete#1:REPLY 4596 S: BEGIN:VREPLY 4597 S: BEGIN:VEVENT 4598 S: UID:123 4599 S: REQUEST-STATUS:2.0 4600 S: END:VEVENT 4601 S: END:VREPLY 4602 S: END:VCALENDAR 4604 9.6 MOVE Command 4606 CMD: MOVE 4608 Purpose: The MOVE command is used to move components within the CS. 4610 A CUA MAY send a MOVE command to a CS. The MOVE command MUST BE 4611 implemented by all CSs. 4613 The CS MUST NOT send a MOVE command to any CUA. 4615 Formal Definition: A "MOVE" command is defined by the following 4616 notation: 4618 move-cmd = moveparam ":" "MOVE" 4620 moveparam = *( 4622 ; the following are optional, 4623 ; but MUST NOT occur more than once 4625 id-param 4626 / localize-param 4627 / latency-param 4629 ; the following MUST occur exactly once and only 4630 ; when the latency-param has been supplied and 4631 ; MUST NOT be supplied if the latency-param is 4632 ; not supplied. 4634 / action-param 4636 ; the following is optional, 4637 ; and MAY occur more than once 4639 / (";" xparam) 4641 ) 4643 Response: 4644 The REQUEST-STATUS in a VCALENDAR object. 4646 The content of each "result" is subject to the result restriction 4647 table defined below. 4649 The access control on the VAGENDA after it has been moved to its new 4650 location in the calstore MUST BE at least as secure as it was prior 4651 to the move. If the CS is not able to ensure the same level of 4652 security, a permission denied REQUEST-STATUS MUST BE returned and the 4653 MOVE operation not performed. 4655 The TARGET property specifies the new location, and the VQUERY 4656 property specifies the old location. 4658 Restriction Table for the "REPLY": 4660 move-reply = "BEGIN" ":" "VCALENDAR" CRLF 4661 calprops 4662 1*(move-vreply) 4663 "END" ":" "VCALENDAR" CRLF 4665 move-vreply = "BEGIN" ":" "VREPLY" CRLF 4666 move-id 4667 request-status 4668 "END" ":" "VREPLY" CRLF 4670 ; Where the id is appropriate for the 4671 ; type of object moved: 4672 ; 4673 ; VAGENDA = calid 4674 ; VCAR = carid 4675 ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid 4676 ; VQUERY = queryid 4677 ; ALARM = sequence 4678 ; x-component = x-id 4679 ; 4680 move-id = ( calid / carid / uid / uid dtstamp 4681 / queryid / tzid / sequence / x-id) 4683 Example: moving the VAGENDA Nellis to Area-51 4684 C: Content-Type: text/calendar 4685 C: 4686 C: BEGIN:VCALENDAR 4687 C: VERSION:2.0 4688 C: CMD:MOVE 4689 C: TARGET:Area-51 4690 C: BEGIN:VQUERY 4691 C: QUERY: SELECT * FROM VAGENDA WHERE CALID='Nellis' 4692 C: END:VQUERY 4693 C: END:VCALENDAR 4695 S: Content-Type: text/calendar 4696 S: 4697 S: BEGIN:VCALENDAR 4698 S: VERSION:2.0 4699 S: TARGET:Area-51 4700 S: BEGIN:VREPLY 4701 S: CALID:Nellis 4702 S: REQUEST-STATUS: 2.0 4703 S: END:VREPLY 4704 S: END:VCALENDAR 4706 9.7 REPLY Response to a Command 4708 CMD: REPLY 4710 Purpose: The "REPLY" value to the "CMD" property is used to return 4711 the results of all other commands to the CUA. 4713 A CUA MUST send a REPLY command to a CS for any command a CS MAY send 4714 to the CUA. The REPLY command MUST BE implemented by all CUAs that 4715 support getting the GET-CAPABILITY command. 4717 A CS MUST send a REPLY command to a CUA for any command a CUA MAY 4718 send to the CS. The REPLY command MUST BE implemented by all CSs. 4720 Formal Definition: A "REPLY" command is defined by the following 4721 notation: 4723 reply-cmd = replyparam ":" "REPLY" 4725 replyparam = *( 4727 ; The 'id' parameter value MUST BE exactly the 4728 ; same as the value sent in the original 4729 ; CMD property. If the original CMD did 4730 ; not have an 'id' parameter, then the 'id' 4731 ; MUST NOT be supplied in the REPLY. 4733 id-param 4735 ; the following is optional, 4736 ; and MAY occur more than once 4738 / (";" xparam) 4740 ) 4742 9.8 SEARCH Command 4744 CMD: SEARCH 4746 Purpose: The "SEARCH" command is used to return selected components 4747 to the CUA. 4749 A CUA MAY send a SEARCH command to a CS. The SEARCH command MUST BE 4750 implemented by all CSs. 4752 The CS MUST NOT send a SEARCH command to any CUA. 4754 Formal Definition: A "SEARCH" command is defined by the following 4755 notation: 4757 search-cmd = searchparam ":" "SEARCH" 4759 searchparam = *( 4761 ; the following are optional, 4762 ; but MUST NOT occur more than once 4764 id-param 4765 / localize-param 4766 / latency-param 4768 ; the following MUST occur exactly once and only 4769 ; when the latency-param has been supplied and 4770 ; MUST NOT be supplied if the latency-param is 4771 ; not supplied. 4773 / action-param 4775 ; the following is optional, 4776 ; and MAY occur more than once 4778 / (";" xparam) 4780 ) 4782 Response: 4784 The data in each result contains an iCalendar object composed of all 4785 the selected components enclosed in a "VREPLY" component. Only 4786 "REQUEST-STATUS" and the properties mentioned in the "SELECT" clause 4787 of the QUERY are included in the components. Each iCalendar object 4788 is tagged with the TARGET property and optional CMD property. 4790 Searching for objects 4792 In the example below objects on March 10,1999 between 080000Z and 4793 190000Z are read. In this case only 4 properties for each objects 4794 are returned. Two calendars are specified. Only booked (vs 4795 scheduled) entries are to be returned (this example only selecte 4796 VEVENT objects): 4798 C: Content-Type: text/calendar 4799 C: 4800 C: BEGIN:VCALENDAR 4801 C: VERSION:2.0 4802 C: CMD:SEARCH 4803 C: TARGET:relcal2 4804 C: TARGET:relcal3 4805 C: BEGIN:VQUERY 4806 C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID 4807 C: FROM VEVENT 4808 C: WHERE DTEND >= '19990310T080000Z' 4809 C: AND DTSTART <= '19990310T190000Z' 4810 C: AND STATE() = 'BOOKED' 4811 C: END:VQUERY 4812 C: END:VCALENDAR 4814 The return values are subject to VCAR filtering. That is, if the 4815 request contains properties to which the UPN does not have access, 4816 those properties will not appear in the return values. If the UPN 4817 has access to at least one property of the component, but has been 4818 denied access to all properties called out in the request, the 4819 response will contain a single REQUEST-STATUS property indicating the 4820 error. 4822 Here the request was successful, but the VEVENT contents were not 4823 accessible (4.1). 4825 S: Content-Type: text/calendar 4826 S: 4827 S: BEGIN:VCALENDAR 4828 S: TARGET:relcalid 4829 S: CMD:REPLY 4830 S: VERSION:2.0 4831 S: BEGIN:VREPLY 4832 S: BEGIN:VEVENT 4833 S: REQUEST-STATUS:4.1 4834 S: END:VEVENT 4835 S: END:VREPLY 4836 S: END:VCALENDAR 4838 If the UPN has no access to any components at all, the response will 4839 simply be an empty data set. The response looks the same if there 4840 the particular components did not exist. 4842 S: Content-Type: text/calendar 4843 S: 4844 S: BEGIN:VCALENDAR 4845 S: VERSION:2.0 4846 S: CMD:REPLY 4847 S: TARGET:ralcalid 4848 S: BEGIN:VREPLY 4849 S: REQUEST-STATUS:2.0 4850 S: END:VREPLY 4851 S: END:VCALENDAR 4853 If there are multiple targets, each iCalendar reply is contained 4854 within its own iCalendar object. 4856 Stored VQUERY can be used by specifying the property QUERYID instead 4857 of QUERY. 4859 9.9 SET-LOCALE Command 4861 CMD: SET-LOCALE 4863 Purpose: The "SET-LOCALE" command is used to select the locale that 4864 will be used in error codes used int the "REQUEST-STATUS" property. 4865 It also effect the locale sorting order for queries. 4867 A CUA MAY send a "SET-LOCALE" command to a CS. The SET-LOCALE 4868 command MUST BE implemented by all CSs. 4870 The CS MUST NOT send a "SET-LOCALE" command to any CUA. 4872 Formal Definition: A "SET-LOCALE" command is defined by the following 4873 notation: 4875 setlocale-cmd = searchparam ":" "SET-LOCALE" 4877 setlocaleparam = *( 4879 ; the following are optional, 4880 ; but MUST NOT occur more than once 4882 id-param 4883 / localize-param 4884 / latency-param 4885 / setlocale-option 4887 ; the following MUST occur exactly once and only 4888 ; when the latency-param has been supplied and 4889 ; MUST NOT be supplied if the latency-param is 4890 ; not supplied. 4892 / action-param 4894 ; the following is optional, 4895 ; and MAY occur more than once 4897 / (";" xparam) 4899 setlocal-option = option-param newlocale 4901 newlocale = ; Any locale supplied in the initial BEEP 4902 ; "greeting" "localize" parameter and 4903 ; and any charset supported by the CS 4904 ; and listed in the DEFAULT-CHARSET property 4905 ; of the VCALSTORE. 4907 ) 4909 Restriction Table for the REPLY of any SET-LOCALE command. 4911 setlocale-reply = "BEGIN" ":" "VCALENDAR" CRLF 4912 calprops 4913 1*(setlocale-vreply) 4914 "END" ":" "VCALENDAR" CRLF 4916 setlocale-vreply = "BEGIN" ":" "VREPLY" CRLF 4917 request-status 4918 "END" ":" "VREPLY" CRLF 4920 9.10 TIMEOUT Command 4922 CMD: TIMEOUT 4924 Purpose: The "TIMEOUT" command is only sent after a command has been 4925 sent with a latency value set. When received it means the command 4926 could not be completed in the time allowed. 4928 Formal Definition: A "CONTINUE" command is defined by the following 4929 notation: 4931 continue-cmd = continueparam ":" "CONTINUE" 4933 continueparam = *( 4935 ; the following are optional, 4936 ; but MUST NOT occur more than once 4938 id-param 4939 / localize-param 4941 / (";" xparam) 4943 ) 4945 The REPLY of any "TIMEOUT" command is: 4947 timeout-reply = "BEGIN" ":" "VCALENDAR" CRLF 4948 calprops 4949 timeout-vreply 4950 "END" ":" "VCALENDAR" CRLF 4952 timeout-vreply = "BEGIN" ":" "VREPLY" CRLF 4953 request-status 4954 *(x-prop) 4955 "END" ":" "VREPLY" CRLF 4957 9.11 Response Codes 4959 Numeric response codes are returned using the REQUEST-STATUS 4960 property. 4962 The format of these codes is described in [iCAL], and extend in 4963 [iTIP] and [iMIP]. The following describes new codes added to this 4964 set and how existing codes apply to CAP. 4966 At the application layer response codes are returned as the value of 4967 a "REQUEST-STATUS" property. The value type of this property is 4968 modified from that defined in [iCAL], in order to make the 4969 accompanying REQUEST-STATUS text optional. 4971 Code Description 4972 -------------------------------------------------------------- 4973 2.0 Success. The parameters vary with the 4974 operation and are specified. 4976 2.0.3 In response to the client issuing an 4977 "abort" reply, this reply code indicates 4978 that any command currently underway was 4979 successfully aborted. 4981 3.1.4 Capability not supported. 4983 4.1 Calendar store access denied. 4985 6.1 Container not found. 4987 6.2 Attempt to create or modify an object 4988 such that it would overlap another object 4989 in either of the following two circumstances: 4991 (a) One of the objects has a TRANSP 4992 property set to OPAQUE-NOCONFLICT or 4993 TRANSPARENT-NOCONFLICT. 4995 (b) The calendar's ALLOW-CONFLICT 4996 property is set to FALSE. 4998 6.3 Bad args. 5000 6.4 Permission denied - VCAR restriction. 5001 A VCAR exists and the CS will not perform 5002 the operation. 5004 7.0 A timeout has occurred. The server was 5005 unable to complete the operation in the 5006 requested time. 5008 8.0 A failure has occurred in the Calendar Server 5009 that prevents the operation from 5010 succeeding. 5012 8.1 A query was performed and the query is 5013 too complex for the CS. The operation 5014 was not performed. 5016 8.2 Used to signal that an iCalendar object has 5017 exceeded the server's size limit 5019 8.3 A DATETIME value was too far in the future 5020 represented on this Calendar. 5022 8.4 A DATETIME value was too far in the past 5023 to be represented on this Calendar. 5025 8.5 An attempt was made to create a new 5026 object but the unique UID specified is 5027 already in use. 5029 9.0 An unrecognized command was received. 5030 Or an unsupported command was received. 5032 10.4 The operation has not been performed 5033 because it would cause the resources 5034 (memory, disk, CPU, etc) to exceed the 5035 allocated quota. 5037 -------------------------------------------------------------- 5039 10. Object Registration 5041 This section provides the process for registration of new or modified 5042 properties, parameters, commands, or other modifications, additions, 5043 or deletions to objects. 5045 10.1 Registration of New and Modified Entities 5047 New objects are registered by the publication of an IETF Request for 5048 Comment (RFC). Changes to a objects are registered by the 5049 publication of a revision to the RFC in a new RFC. 5051 10.2 Post the item definition 5053 The object description MUST BE posted to the new object discussion 5054 list: ietf-calendar@imc.org. 5056 10.3 Allow a comment period 5058 Discussion on a new object MUST BE allowed to take place on the list 5059 for a minimum of two weeks. Consensus MUST BE reached on the object 5060 before proceeding to the next step. 5062 10.4 Release a new RFC 5064 The new object will be submitted for publication as any other 5065 internet draft requesting RFC status. 5067 11. BEEP and CAP 5069 11.1 BEEP Profile Registration 5071 TBD 5073 11.2 BEEP Exchange Styles 5075 [BEEP] defines three styles of message exchange: 5077 MSG/ANS,ANS,...,NUL - For one to many exchanges. 5079 MSG/RPY - For one to one exchanges. 5081 MSG/ERR - For requests the cannot be processed due to an error. 5083 A CAP request, targeted at more than one containers, MAY use a one- 5084 to-many exchange, with a distinct answer associated with each target. 5085 CAP request targeted at a single container MAY use a one-to-one 5086 exchange or a one-to-many exchange. "MSG/ERR" MAY only be used when 5087 an error condition prevents the execution of the request on all the 5088 targeted calendars. 5090 12. IANA Considerations 5092 This memo defines IANA registered extensions to the attributes 5093 defined by iCalendar, as defined in [iCAL], and [iTIP]. 5095 IANA registration proposals for iCalendar and iTIP are to be mailed 5096 to the registration agent for the "text/calendar" [MIME] content- 5097 type, using the format defined in 5098 section 7 of [iCAL]. 5100 If the IESG approves this memo for publication, then the IANA 5101 registers the profile specified in Section 11.1, and selects an IANA- 5102 specific URI, e.g., http://iana.org/beep/cap/1.0. 5104 13. Security Considerations 5106 Access rights should be granted cautiously, consult Section 2.4.2 for 5107 a discussion of the subject. Without careful planning it is possible 5108 to open up access to a greater degree than desired. 5110 The "IDENTIFY" command should be carefully implemented as discussed 5111 in Section 6.1.3. 5113 In addition, since CAP is a profile of the BEEP, consult [BEEP]'s 5114 Section 9 for a discussion of BEEP-specific security issues. 5116 Although service provisioning is a policy matter, at a minimum, all 5117 implementations must provide the following tuning profiles: 5119 for authentication: http://iana.org/beep/SASL/DIGEST-MD5 5121 for confidentiality: http://iana.org/beep/TLS (using the 5122 TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher) 5124 for both: http://iana.org/beep/TLS (using the 5125 TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher supporting client-side 5126 certificates) 5128 URIs 5130 [1] 5132 Authors' Addresses 5134 Doug Royer 5135 INET-Consulting.com 5136 1795 W. Broadway #266 5137 Idaho Falls, ID 83402 5138 US 5140 Phone: +1-866-594-8574 5141 Fax: +1-866-594-8574 5142 EMail: Doug@Royer.com 5143 URI: http://INET-Consulting.com 5145 George Babics 5146 Steltor 5147 2000 Peel Street 5148 Montreal, Quebec H3A 2W5 5149 CA 5151 Phone: +1-514-733-8500 x4201 5152 Fax: +1-514-733-8878 5153 EMail: georgeb@steltor.com 5155 Paul Hill 5156 Massachusetts Institute of Technology 5157 W92-172 5158 77 Massachusetts Avenue 5159 Cambridge, MA 02139 5160 US 5162 Phone: +1-617-253-0124 5163 Fax: +1-617-258-8736 5164 EMail: phb@mit.edu 5165 Steve Mansour 5166 AOL/Netscape 5167 466 Ellis Road 5168 Mountain View, CA 94043 5169 US 5171 Phone: +1-650-937-3351 5172 EMail: sman@netscape.com 5174 Appendix A. Acknowledgments 5176 The following have individuals were major contributors in the 5177 drafting and discussion of this memo: 5179 Harald Alvestrand, Mario Bonin, Andre Courtemanche, Dave Crocker, 5180 Bernard Desruisseaux, Pat Egen, Gilles Fortin, Jeff Hodges, Alex 5181 Hoppman, Bruce Kahn, Patrice Lapierre, Lisa Lippert, David Madeo, Bob 5182 Mahoney, Bob Morgan, Pete O'Leary, Richard Shusterman, Tony Small, 5183 John Stracke, Alexander Taler, Mark Wahl. 5185 Appendix B. Bibliography 5187 [RFC1521] Borenstein, N., Freed, N., "Specifying and Describing the 5188 Format of Internet Message Bodies", RFC 1521, September 1993 5189 ftp://ftp.isi.edu/in-notes/rfc1521.txt 5191 [RFC1738] Berners-Lee, T, Masinter, L. and McCahil, M., "Uniform 5192 Resource Locators (URL)", RFC 1738, December 1994 5193 ftp://ftp.isi.edu/in-notes/rfc1738.txt 5195 [RFC2045] Borenstein, N. and Freed, N., "Multipurpose Internet Mail 5196 Extensions (MIME) Part One: Format of Internet Message Bodies", 5197 RFC 2045, November 1996 5198 ftp://ftp.isi.edu/in-notes/rfc2045.txt 5200 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 5201 Requirement Levels", RFC 2119, BCP 14, March 1997 5202 ftp://ftp.isi.edu/in-notes/rfc2119.txt 5204 [RFC2222] Myers, J., "Simple Authentication and Security Layer (SASL)", 5205 RFC 2222, October 1997 5206 ftp://ftp.isi.edu/in-notes/rfc2222.txt 5208 [RFC2246] Dierks, T. and Allen, C., "The TLS Protocol Version 1.0", 5209 RFC 2246, January 1999 5210 ftp://ftp.isi.edu/in-notes/rfc2246.txt 5212 [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource 5213 Locators", RFC 2392, August 1998 5214 ftp://ftp.isi.edu/in-notes/rfc2392.txt 5216 [RFC2396] Berners-Lee, T, Fielding, R. and Masinter, L., "Uniform Resource 5217 Identifiers (URI): Generic Syntax", RFC 2396, August 1998 5218 ftp://ftp.isi.edu/in-notes/rfc2396.txt 5220 [iCAL] Dawson, F. and Stenerson, D., "Internet Calendaring and 5221 Scheduling Core Object Specification (iCalendar)", RFC 2445, 5222 November 1998 ftp://ftp.isi.edu/in-notes/rfc2245.txt 5224 [iTIP] Silverberg, S., Mansour, S., Dawson, F. and Hopson, R., 5225 "iCalendar Transport-Independent Interoperability Protocol 5226 (iTIP) Events, BusyTime, To-dos and Journal Entries", 5227 RFC 2446, November 1998 ftp://ftp.isi.edu/in-notes/rfc2446.txt 5229 [iMIP] Dawson, F., Mansour, S. and Silverberg, "iCalendar 5230 Message-Based Interoperability Protocol (iMIP)", RFC 2447, 5231 November 1998 ftp://ftp.isi.edu/in-notes/rfc2447.txt 5233 [RFC3080] Rose, M., "The Block Extensible Exchange Protocol Core", 5234 RFC 3080, March 2001 5235 ftp://ftp.isi.edu/in-notes/rfc3080.txt 5237 [RFC3081] Rose, M., "Mapping the BEEP Core onto TCP", RFC 3081, March 2001 5238 ftp://ftp.isi.edu/in-notes/rfc3081.txt 5240 [SQL] "Database Language SQL", ANSI/ISO/IEC 9075: 1992, 5241 aka ANSI X3.135-1992, aka FiPS PUB 127-2 5243 [SQLCOM] ANSI/ISO/IEC 9075:1992/TC-1-1995, Technical corrigendum 1 5244 to ISO/IEC 9075: 1992, also adopted as Amendment 1 to 5245 ANSI X3.135.1992 5247 [UNICODE] The Unicode Consortium, "The Unicode Standard, Version 3.1" 5248 http://www.unicode.org/unicode/standard/standard.html 5250 [US-ASCII] Coded Character Set -- 7-bit American Standard Code for 5251 Information Interchange, ANSI X3.4-1986. 5253 [CharEncoding] "Worldwide Character Encoding -- Version 1.0", 5254 Addison-Wesley, Volume 1, 1991, Volume 2, 1992. 5255 UTF-8 is described in Unicode Technical Report #4. 5257 Full Copyright Statement 5259 Copyright (C) The Internet Society (2002). All Rights Reserved. 5261 This document and translations of it may be copied and furnished to 5262 others, and derivative works that comment on or otherwise explain it 5263 or assist in its implementation may be prepared, copied, published 5264 and distributed, in whole or in part, without restriction of any 5265 kind, provided that the above copyright notice and this paragraph are 5266 included on all such copies and derivative works. However, this 5267 document itself may not be modified in any way, such as by removing 5268 the copyright notice or references to the Internet Society or other 5269 Internet organizations, except as needed for the purpose of 5270 developing Internet standards in which case the procedures for 5271 copyrights defined in the Internet Standards process must be 5272 followed, or as required to translate it into languages other than 5273 English. 5275 The limited permissions granted above are perpetual and will not be 5276 revoked by the Internet Society or its successors or assigns. 5278 This document and the information contained herein is provided on an 5279 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 5280 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 5281 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 5282 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 5283 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 5285 Acknowledgement 5287 Funding for the RFC Editor function is currently provided by the 5288 Internet Society.