idnits 2.17.1 draft-ietf-calsch-cap-07.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 208 instances of too long lines in the document, the longest one being 31 characters in excess of 72. ** The abstract seems to contain references ([RFC2445], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? RFC 2119 keyword, line 327: '...example, "events MUST be scheduled in ...' RFC 2119 keyword, line 415: '...flict, the Realm SHOULD be postfixed w...' RFC 2119 keyword, line 422: '... It MUST BE unique within a ca...' RFC 2119 keyword, line 452: '... CU's UPN MUST never be an e-ma...' RFC 2119 keyword, line 614: '...then the subject name MUST be an empty...' (157 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 456 has weird spacing: '...me. In it's ...' == Line 484 has weird spacing: '...used to move...' == Line 2995 has weird spacing: '...et with brave...' -- 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 (March 01, 2002) is 8084 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? 'RFC2445' on line 4933 looks like a reference -- Missing reference section? '1' on line 4846 looks like a reference -- Missing reference section? 'BEEP' on line 974 looks like a reference -- Missing reference section? 'RFC2119' on line 4915 looks like a reference -- Missing reference section? 'GUIDE' on line 247 looks like a reference -- Missing reference section? 'RFC1738' on line 4907 looks like a reference -- Missing reference section? 'MIME' on line 4836 looks like a reference -- Missing reference section? 'CAP' on line 852 looks like a reference -- Missing reference section? 'BEEPTCP' on line 969 looks like a reference -- Missing reference section? 'SQL92' on line 1133 looks like a reference -- Missing reference section? 'SQLCOM' on line 4958 looks like a reference -- Missing reference section? 'NOT' on line 1809 looks like a reference -- Missing reference section? 'ITIP' on line 2373 looks like a reference -- Missing reference section? 'IANA-PROP' on line 2363 looks like a reference -- Missing reference section? 'RFC 2278' on line 3965 looks like a reference -- Missing reference section? 'RFC 2277' on line 4009 looks like a reference -- Missing reference section? 'RFC 1738' on line 4134 looks like a reference -- Missing reference section? 'RFC1521' on line 4903 looks like a reference -- Missing reference section? 'RFC2045' on line 4911 looks like a reference -- Missing reference section? 'RFC2222' on line 4919 looks like a reference -- Missing reference section? 'RFC2246' on line 4922 looks like a reference -- Missing reference section? 'RFC2392' on line 4925 looks like a reference -- Missing reference section? 'RFC2396' on line 4929 looks like a reference -- Missing reference section? 'RFC2446' on line 4937 looks like a reference -- Missing reference section? 'RFC2447' on line 4942 looks like a reference -- Missing reference section? 'RFC3080' on line 4946 looks like a reference -- Missing reference section? 'RFC3081' on line 4949 looks like a reference -- Missing reference section? 'RFC3087' on line 4952 looks like a reference -- Missing reference section? 'SQL' on line 4956 looks like a reference -- Missing reference section? 'UNICODE' on line 4961 looks like a reference -- Missing reference section? 'US-ASCII' on line 4964 looks like a reference Summary: 4 errors (**), 0 flaws (~~), 7 warnings (==), 34 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Mansour 3 Internet-Draft AOL/Netscape 4 Expires: August 30, 2002 D. Royer 5 INET-Consulting LLC 6 G. Babics 7 Steltor 8 P. Hill 9 Massachusetts Institute of 10 Technology 11 March 01, 2002 13 Calendar Access Protocol (CAP) 14 draft-ietf-calsch-cap-07 16 Status of this Memo 18 This document is an Internet-Draft and is in full conformance with 19 all provisions of Section 10 of RFC2026. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at http:// 32 www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This Internet-Draft will expire on August 30, 2002. 39 Copyright Notice 41 Copyright (C) The Internet Society (2002). All Rights Reserved. 43 Abstract 45 The Calendar Access Protocol (CAP) is an Internet protocol that 46 permits a Calendar User (CU) to utilize a Calendar User Agent (CUA) 47 to access an [RFC2445] based Calendar Store (CS). This memo defines 48 the CAP specification. 50 The CAP definition is based on requirements identified by the 51 Internet Engineering Task Force (IETF) Calendaring and Scheduling 52 (CALSCH) Working Group. More information about the IETF CALSCH 53 Working Group activities can be found on the IMC web site at http:// 54 www.imc.org/ietf-calendar and at the IETF web site at http:// 55 www.ietf.org/html.charters/calsch-charter.html [1]. Refer to the 56 references within this memo for further information on how to access 57 these various documents. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . 5 62 1.1 Formatting Conventions . . . . . . . . . . . . . . . . 5 63 1.2 Related Documents . . . . . . . . . . . . . . . . . . 6 64 1.3 Definitions . . . . . . . . . . . . . . . . . . . . . 6 65 2. CAP Design . . . . . . . . . . . . . . . . . . . . . . 12 66 2.1 System Model . . . . . . . . . . . . . . . . . . . . . 12 67 2.2 Calendar Store Object Model . . . . . . . . . . . . . 12 68 2.3 Protocol Model . . . . . . . . . . . . . . . . . . . . 13 69 2.4 Security Model . . . . . . . . . . . . . . . . . . . . 14 70 2.4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . 14 71 2.4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . 14 72 2.4.1.2 Anonymous Users and Authentication . . . . . . . . . . 15 73 2.4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . 16 74 2.4.2 Access Rights - Summary . . . . . . . . . . . . . . . 16 75 2.4.2.1 Calendar Access Right (VCAR) . . . . . . . . . . . . . 16 76 2.4.2.2 Predefined VCARs . . . . . . . . . . . . . . . . . . . 17 77 2.4.2.3 Decreed VCARs . . . . . . . . . . . . . . . . . . . . 18 78 2.4.3 CAP Session Identity . . . . . . . . . . . . . . . . . 19 79 2.5 Roles . . . . . . . . . . . . . . . . . . . . . . . . 20 80 2.6 CAP URL . . . . . . . . . . . . . . . . . . . . . . . 20 81 2.7 Calendar Addresses . . . . . . . . . . . . . . . . . . 21 82 2.8 Extensions to iCalendar . . . . . . . . . . . . . . . 21 83 2.9 Relationship of RFC 2446 (ITIP) to CAP . . . . . . . . 21 84 3. Protocol Framework . . . . . . . . . . . . . . . . . . 23 85 3.1 BEEP Exchange Styles . . . . . . . . . . . . . . . . . 23 86 3.2 Use BEEP, MIME and iCalendar . . . . . . . . . . . . . 23 87 3.3 Bounded Latency . . . . . . . . . . . . . . . . . . . 24 88 4. New Value Types . . . . . . . . . . . . . . . . . . . 27 89 4.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . . 27 90 4.1.1 CAP-QL notes . . . . . . . . . . . . . . . . . . . . . 31 91 4.2 CAP-QL notes . . . . . . . . . . . . . . . . . . . . . 37 92 4.3 Example, Query by UID . . . . . . . . . . . . . . . . 42 93 4.4 Query by Date-Time range . . . . . . . . . . . . . . . 42 94 4.5 Query for all Non-Booked Entries . . . . . . . . . . . 43 95 4.6 Query with Subset of Properties by Date/Time . . . . . 44 96 4.7 Components With Alarms In A Range . . . . . . . . . . 44 97 5. Access Rights . . . . . . . . . . . . . . . . . . . . 45 98 5.1 Access Control and NOCONFLICT . . . . . . . . . . . . 45 99 6. Commands and Responses . . . . . . . . . . . . . . . . 46 100 6.1 Session Commands . . . . . . . . . . . . . . . . . . . 46 101 6.1.1 "generate-uid" Command . . . . . . . . . . . . . . . . 46 102 6.1.2 "get-capability" Command . . . . . . . . . . . . . . . 47 103 6.1.3 "identify" Command . . . . . . . . . . . . . . . . . . 49 104 6.1.4 "noop" Command . . . . . . . . . . . . . . . . . . . . 50 105 6.2 Calendaring and Scheduling Commands . . . . . . . . . 51 106 6.2.1 Restriction Tables . . . . . . . . . . . . . . . . . . 51 107 6.2.2 Calendaring Commands . . . . . . . . . . . . . . . . . 52 108 6.2.2.1 "create" Command . . . . . . . . . . . . . . . . . . . 52 109 6.2.2.2 "move" Command . . . . . . . . . . . . . . . . . . . . 57 110 6.2.2.3 "delete" Command . . . . . . . . . . . . . . . . . . . 60 111 6.2.2.4 "modify" Command . . . . . . . . . . . . . . . . . . . 62 112 6.2.2.5 "search" Command . . . . . . . . . . . . . . . . . . . 66 113 6.2.2.6 Response Codes . . . . . . . . . . . . . . . . . . . . 71 114 7. Initial Registrations . . . . . . . . . . . . . . . . 73 115 7.1 BEEP Profile Registration . . . . . . . . . . . . . . 73 116 7.2 Registration: The System (Well-Known) TCP port number 117 for CAP . . . . . . . . . . . . . . . . . . . . . . . 73 118 8. CAP DTD . . . . . . . . . . . . . . . . . . . . . . . 75 119 9. Properties . . . . . . . . . . . . . . . . . . . . . . 76 120 9.1 Calendar Store Properties . . . . . . . . . . . . . . 76 121 9.2 Calendar Properties . . . . . . . . . . . . . . . . . 77 122 10. Security Considerations . . . . . . . . . . . . . . . 80 123 11. Extensions To iCalendar . . . . . . . . . . . . . . . 81 124 11.1 Property Value Data Types . . . . . . . . . . . . . . 81 125 11.1.1 UPN . . . . . . . . . . . . . . . . . . . . . . . . . 81 126 11.1.2 UPN Filter . . . . . . . . . . . . . . . . . . . . . . 82 127 11.2 Calendar Components . . . . . . . . . . . . . . . . . 83 128 11.2.1 Agenda Component . . . . . . . . . . . . . . . . . . . 83 129 11.2.2 Calendar Store Component . . . . . . . . . . . . . . . 84 130 11.2.3 Calendar Access Right Component . . . . . . . . . . . 85 131 11.2.4 VRIGHT Calendar Component . . . . . . . . . . . . . . 88 132 11.3 Component Properties . . . . . . . . . . . . . . . . . 89 133 11.3.1 Allow-Conflict Component Property . . . . . . . . . . 89 134 11.3.2 Charset Component Property . . . . . . . . . . . . . . 90 135 11.3.3 Default Locale Component Property . . . . . . . . . . 91 136 11.3.4 Default Time Zone Property . . . . . . . . . . . . . . 91 137 11.3.5 Owner Component Property . . . . . . . . . . . . . . . 92 138 11.3.6 Relative Calendar Identifier Component Property . . . 93 139 11.3.7 Calendar Store Component Properties . . . . . . . . . 94 140 11.3.7.1 Calmaster Component Property . . . . . . . . . . . . . 94 141 11.3.7.2 Calendar Store Identifier Component Property . . . . . 94 142 11.3.7.3 Default Access Rights Component Property . . . . . . . 95 143 11.3.7.4 Maximum Date Component Property . . . . . . . . . . . 96 144 11.3.7.5 Minimum Date Component Property . . . . . . . . . . . 97 145 11.3.8 Descriptive Component Properties . . . . . . . . . . . 97 146 11.3.8.1 REQUEST-STATUS property . . . . . . . . . . . . . . . 97 147 11.3.8.2 CALID Property Parameter . . . . . . . . . . . . . . . 98 148 11.3.8.3 Time Transparency . . . . . . . . . . . . . . . . . . 99 149 11.3.8.4 Name Component Property . . . . . . . . . . . . . . . 100 150 11.3.9 Calendar Access Right Component Properties . . . . . . 101 151 11.3.9.1 VCAR Identifier Component Property . . . . . . . . . . 101 152 11.3.9.2 VCAR Decreed Component Property . . . . . . . . . . . 102 153 11.3.10 Right Component Properties . . . . . . . . . . . . . . 102 154 11.3.10.1 Grant Component Property . . . . . . . . . . . . . . . 103 155 11.3.10.2 Deny Component Property . . . . . . . . . . . . . . . 103 156 11.3.10.3 Permission Component Property . . . . . . . . . . . . 104 157 11.3.10.4 Scope Component Property . . . . . . . . . . . . . . . 105 158 11.3.10.5 Restriction Component Property . . . . . . . . . . . . 106 159 12. CAP Item Registration . . . . . . . . . . . . . . . . 107 160 12.1 Registration of New and Modified CAP Entities . . . . 107 161 12.2 Registration of New Entities . . . . . . . . . . . . . 107 162 12.2.1 Define the Item . . . . . . . . . . . . . . . . . . . 107 163 12.2.2 Post the item definition . . . . . . . . . . . . . . . 108 164 12.2.3 Allow a comment period . . . . . . . . . . . . . . . . 108 165 12.2.4 Submit the proposal for approval . . . . . . . . . . . 108 166 12.3 Property Change Control . . . . . . . . . . . . . . . 109 167 13. IANA Considerations . . . . . . . . . . . . . . . . . 110 168 Authors' Addresses . . . . . . . . . . . . . . . . . . 111 169 A. Acknowledgments . . . . . . . . . . . . . . . . . . . 112 170 B. Bibliography . . . . . . . . . . . . . . . . . . . . . 113 171 Full Copyright Statement . . . . . . . . . . . . . . . 115 173 1. Introduction 175 This document specifies how a Calendar User Agent (CUA) interacts 176 with a Calendar Store (CS) to manage calendar information. In 177 particular, it specifies how to query, create, modify, and delete 178 iCalendar components (e.g., events, to-dos, or daily journal 179 entries). It further specifies how to search for available busy time 180 information. 182 CAP is specified as a BEEP "profile". As such many aspects of the 183 protocol (e.g., authentication and privacy) are provided within the 184 [BEEP]. The protocol data units leverage the standard iCalendar 185 format [RFC2445] to convey calendar related information. 187 CAP can also be used to store and fetch [iTIP] objects and when those 188 objects are used here in this memo, they mean exactly the same as 189 defined in [iTIP]. 191 1.1 Formatting Conventions 193 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 194 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this 195 document are to be interpreted as described in [RFC2119]. 197 Calendaring and scheduling roles are referred to in quoted-strings of 198 text with the first character of each word in upper case. For 199 example, "Organizer" refers to a role of a "Calendar User" (CU) 200 within the protocol defined by [iTIP]. Calendar components defined 201 by [RFC2445] are referred to with capitalized, quoted-strings of 202 text. All calendar components start with the letter "V". For 203 example, "VEVENT" refers to the event calendar component, "VTODO" 204 refers to the to-do calendar component and "VJOURNAL" refers to the 205 daily journal calendar component. 207 Scheduling methods defined by [iTIP], are referred to with 208 capitalized, quoted-strings of text. For example, "REPLY" refers to 209 the method for replying to a "REQUEST". 211 CAP commands are referred by lower-case, quotes-strings of text, 212 followed by the word "command". For example, "create" command refers 213 to the command for creating a calendar entry, "search" command refers 214 to the command for reading calendar components. 216 Properties defined by this memo are referred to with capitalized, 217 quoted-strings of text, followed by the word "property". For 218 example, "ATTENDEE" property refers to the iCalendar property used to 219 convey the calendar address of a "Calendar User". Property 220 parameters defined by this memo are referred to with capitalized, 221 quoted-strings of text, followed by the word "parameter". For 222 example, "PARTSTAT" parameter refers to the iCalendar property 223 parameter used to specify the participation status of an attendee. 224 Enumerated values defined by this memo are referred to with 225 capitalized text, either alone or followed by the word "value". 227 In tables, the quoted-string text is specified without quotes in 228 order to minimize the table length. 230 1.2 Related Documents 232 Implementers will need to be familiar with several other memos that, 233 along with this one, describe the Internet calendaring and scheduling 234 standards. These documents are: 236 [RFC2445] (RFC2445) which specifies the objects, data types, 237 properties and property parameters used in the protocols, along with 238 the methods for representing and encoding them, 240 [iTIP] (RFC2446) which specifies an interoperability protocol for 241 scheduling between different implementations. The related documents 242 are: 244 [iMIP] (RFC2447) which specifies an Internet email binding for 245 [iTIP]. 247 [GUIDE] (draft/rfc...) which is a guide to implementers and describes 248 the elements of a calendaring system, how they interact with each 249 other, how they interact with end users, and how the standards and 250 protocols are used. 252 This memo does not attempt to repeat the specification of concepts 253 and definitions from these other memos. Where possible, references 254 are made to the memo that provides for the specification of these 255 concepts and definitions. 257 1.3 Definitions 259 Booked 261 An entry in a calendar has one of three conceptual states. It 262 is scheduled, booked or marked for delete. A scheduled entry 263 has been stored in the calendar store but has not been acted on 264 by a calendar user (CU) or calendar user agent (CUA). A 265 scheduled entry contains a METHOD property set to an [iTIP] 266 method. A booked entry has its METHOD property set to CREATE. 267 A marked for delete component has its METHOD property set to 268 DELETE 270 Calendar 272 A collection of logically related objects or entities each of 273 which may be associated with a calendar date and possibly time 274 of day. These entities can include other calendar properties 275 or calendar components. In addition, a calendar might be 276 hierarchically related to other calendars with the RELATED-TO 277 property. A calendar is identified by its unique calendar 278 identifier. The [RFC2445] defines calendar properties, 279 calendar components and component properties that make up the 280 content of a calendar. 282 Calendar Access Protocol (CAP) 284 The standard Internet protocol that permits a Calendar User 285 Agent to access and manipulate calendars residing on a Calendar 286 Store. (this memo) 288 Calendar Access Rights (CAR) 290 The mechanism for specifying the CAP operations ("PERMISSION") 291 that a particular calendar user ("UPN") is granted or denied 292 permission to perform on a given calendar object ("SCOPE"). 293 The calendar access rights are specified with the "VCAR" 294 calendar components within a CS and calendar. 296 Calendar Component 298 An object within a calendar or a calendar store (CS). Some 299 types of calendar components include calendars, events, to-dos, 300 journals, alarms, time zones and freebusy data. A calendar 301 component consists of component properties and possibly other 302 sub-components. For example, an event may contain an alarm 303 component. 305 Calendar Component Properties 307 An attribute of a particular calendar component. Some calendar 308 component properties are applicable to different types of 309 calendar components. For example, DTSTART is applicable to 310 VEVENT, VTODO, VJOURNAL calendar components. Other calendar 311 components are applicable only to an individual type of 312 calendar component. For example, TZURL is only applicable to 313 VTIMEZONE calendar components. 315 Calendar Identifier (CalID) 317 A globally unique identifier associated with a calendar. 319 Calendars reside within a CS. See Qualified Calendar 320 Identifier and Relative Calendar Identifier. All CalIDs start 321 with "cap:" 323 Calendar Policy 325 A CAP operational restriction on the access or manipulation of 326 a calendar. These may be outside of the scope of the CAP 327 protocol. For example, "events MUST be scheduled in unit 328 intervals of one hour". 330 Calendar Property 332 An attribute of a calendar (VAGENDA). The attribute applies to 333 the calendar, as a whole. For example, CALSCALE specifies the 334 calendar scale (e.g., GREGORIAN) for the whole calendar. 336 Calendar Service 338 An implementation of a Calendar Store that manages one or more 339 calendars. 341 Calendar Store (CS) 343 The data and service model definition for a Calendar Service. 345 Calendar Store Identifier (CSID) 347 The globally unique identifier for an individual CS. A CSID 348 consists of the host and port portions of a "Common Internet 349 Scheme Syntax" part of a URL, as defined by [RFC1738]. 351 Calendar Store Components 353 Components maintained in a CS specify a grouping of calendar 354 store-wide information. 356 Calendar Store Properties 358 Properties maintained in a Calendar Store calendar store-wide 359 information. 361 Calendar User (CU) 363 An entity (often biological) that uses a calendaring system. 365 Calendar User Agent (CUA) 366 The CUA is the client application that a CU utilizes to access 367 and manipulate a calendar. 369 CAP Session 371 An open communication channel between a CUA and a Calendar 372 Service. 374 Contained Component / Contained Properties 376 A component or property that is contained inside a component. 377 VALARM for example may be contained inside of a VEVENT. And 378 TRIGGER is a contained property of a VALARM. 380 Delegate 382 A calendar user (sometimes called the delegatee) who has been 383 assigned participation in a scheduled calendar component (e.g., 384 VEVENT) by one of the attendees in the scheduled calendar 385 component (sometimes called the delegator). An example of a 386 delegate is a team member told to go to a particular meeting. 388 Designate 390 A calendar user who is authorized to act on behalf of another 391 calendar user. An example of a designate is an assistant. 393 Overlapped Booking 395 A policy which indicates whether or not OPAQUE events can 396 overlap one another. When the policy is applied to a calendar 397 it indicates whether or not the time span of any entry (VEVENT, 398 VTODO, ...) in the calendar can overlap the time span of any 399 other entry in the same calendar. When applied to an 400 individual entry, it indicates whether or not any other entry's 401 time span can overlap that individual entry. 403 Owner 405 One or more CUs or UGs that are listed in the "OWNER" calendar 406 property in a calendar. 408 Qualified Calendar Identifier (Qualified CalID) 410 A CalID where both the and are present. 412 Realm 413 A collection of calendar user accounts, identified by a string. 414 The name of the Realm is only used in UPNs. In order to avoid 415 namespace conflict, the Realm SHOULD be postfixed with an 416 appropriate DNS domain name. (e.g., the foobar Realm could be 417 called foobar.example.com). 419 Relative Calendar Identifier (Relative CalID) 421 An identifier for an individual calendar in a calendar store. 422 It MUST BE unique within a calendar store. A Relative CalID 423 consists of the portion of the "scheme part" of a Qualified 424 CalID following the Calendar Store Identifier. This is the 425 same as the "URL path" of the "Common Internet Scheme Syntax" 426 portion of a URL, as defined by [RFC1738]. 428 Session Identity 430 A UPN associated with a CAP session. A session gains an 431 identity after successful authentication. The identity is used 432 in combination with CAR to determine access to data in the CS. 434 User Group (UG) 436 A collection of Calendar Users and/or User Groups. These 437 groups are expanded by the CS and may reside either locally or 438 in an external database or directory. The group membership may 439 be fixed or dynamic over time. 441 Username 443 A name which denotes a Calendar User within a Realm. This is 444 part of a UPN. 446 User Principal Name (UPN) 448 A unique identifier that denotes a CU or a group of CU. A UPN 449 is a RFC 822 compliant email address, with exceptions listed 450 below, and in most cases it is deliverable to the CU. In some 451 cases it is identical to the CU's well known email address. A 452 CU's UPN MUST never be an e-mail address that is deliverable to 453 a different person as there is no requirement that a person's 454 UPN must be his e-mail address. It consists of a Realm in the 455 form of a valid, and unique, DNS domain name and a unique 456 Username. In it's simplest form it looks like 457 "user@example.com". 459 In certain cases a UPN will not be RFC 822 compliant. When 460 anonymous authentication is used, or anonymous authorization is 461 being defined, the special UPN "@" will be used. When 462 authentication must be used, but unique identity must be 463 obscured, a UPN of the form @DNS-domain-name may be used. For 464 example, "@example.com". Usage of these special cases is 465 further discussed in the authentication and authorization 466 sections of this document. 468 2. CAP Design 470 2.1 System Model 472 The system model describes the high level components of a calendar 473 system and how they interact with each other. 475 CAP is used by a "Calendar User Agent" (CUA) to send commands to and 476 receive responses from a "Calendar Service". 478 The CUA prepares a [MIME] encapsulated command, sends it to the CS, 479 and receives a [MIME] encapsulated response. The calendaring related 480 information within these messages are represented by iCalendar 481 objects. 483 There are two distinct protocols in operation to accomplish this 484 exchange. [BEEP] is the transport protocol and is used to move 485 these encapsulations between a CUA and a CS. CAP profile defines the 486 application protocol. That is, the content and semantics of the 487 messages sent between the CUA and the Calendar Service. 489 2.2 Calendar Store Object Model 491 [RFC2445] describes components such as events, todos, alarms, and 492 timezones. [CAP] requires more object infrastructure. In 493 particular, detailed definitions of the containers for events and 494 todos (calendars), access control objects, and a query language. 495 [CAP] defines the following new objects which will be discussed in 496 detail in this memo 498 Component Description 499 --------- ----------------------------------------- 500 VCAR An access control object 501 VQUERY A query object 502 VAGENDA A container that holds components and which is owned 503 by one or more CUs. 505 The conceptual model for a calendar store is shown below. The 506 calendar store contains VCARs, VQUERYs, VTIMEZONEs, VAGENDAs and 507 calendar store properties. 509 Calendars (VAGENDAs) contain VEVENTs, VTODOs, VJOURNALs, VCARs, 510 VTIMEZONEs, VQUERYs and calendar properties. 512 The special keyword VCALSTORE is used to denote the a root of the 513 calendar store. It is a point from which searches can begin. It is 514 the container for VTIMEZONEs, VQUERYs, and toplevel VAGENDAs. 516 Calendar Store 517 VCALSTORE 518 | 519 +-- VCARs 520 +-- VQUERYs 521 +-- VTIMEZONEs 522 +-- VAGENDA 523 | | 524 | +--VEVENTs 525 | | | 526 | | +--VALARMs 527 | +--VTODOs 528 | | | 529 | | +--VALARMs 530 | +--VJOURNALs 531 | +--VCARs 532 | +--VTIMEZONEs 533 | +--VQUERYs 534 | +--VAGENDAs 535 | | | 536 | | +--VEVENTs 537 | | | | 538 | | | +--VALARMs 539 | | +--VTODOs 540 | | | | 541 | | | +--VALARMs 542 | | +--VJOURNALs 543 | | +--VCARs 544 | | +--VTIMEZONEs 545 | | +--VQUERYs 546 | | +--VFREEBUSY 547 | | +--VAGENDAs 548 | | | | 549 | | | ... 551 Calendars within a Calendar Store are identified by their Relative 552 CALID. 554 2.3 Protocol Model 556 The commands listed below are used to manipulate the data on the 557 calendar store. 559 CAP Commands 560 ----------------------------------------------------------- 561 Command Description 562 ----------------------------------------------------------- 563 create Create a new calendar component. 565 delete Delete calendar components. 566 generate-uid Generate one or more unique ids. 567 get-capability Query the capabilities the CAP server 568 identify Set a new identity for calendar access. 569 modify Modify calendar components. 570 move Move calendar components to another container. 571 noop Do nothing. 572 search Search for calendar components. 573 ----------------------------------------------------------- 575 2.4 Security Model 577 2.4.1 Calendar User and UPNs 579 A Calendar User (CU) is an entity that can be authenticated. It is 580 represented in CAP as a UPN, which is a key part of access rights. 581 The UPN representation is independent of the authentication mechanism 582 used during a particular CUA/CS interaction. This is because UPNs 583 are used within VCARs. If the UPN were dependent on the 584 authentication mechanism, a VCAR could not be consistently evaluated. 585 A CU may use one mechanism while using one CUA but the same CU may 586 use a different authentication mechanism when using a different CUA, 587 or while connecting from a different location. 589 The user may also have multiple UPNs for various purposes. 591 Note that the immutability of the user's UPN may be achieved by using 592 SASL's authorization identity feature. (The transmitted 593 authorization identity may be different than the identity in the 594 client's authentication credentials.) [SASL, section 3]. This also 595 permits a CU to authenticate using their own credentials, yet request 596 the access privileges of the identity for which they are proxying 597 SASL. Also, the form of authentication identity supplied by a 598 service like TLS may not correspond to the UPNs used to express a 599 server's access rights, requiring a server specific mapping to be 600 done. The method by which a server determines a UPN, based on the 601 authentication credentials supplied by a client, is implementation 602 specific. See [BEEP] for authentication details 604 2.4.1.1 UPNs and Certificates 606 When using X.509 certificates for purposes of CAP authentication, the 607 UPN should appear in the certificate. Unfortunately there is no 608 single correct guideline for which field should contain the UPN. 610 From RFC-2459, section 4.1.2.6 (Subject): 612 If subject naming information is present only in the 613 subjectAlt-Name extension (e.g., a key bound only to an email 614 address or URI), then the subject name MUST be an empty 615 sequence and the subjectAltName extension MUST be critical. 617 Implementations of this specification MAY use these comparison 618 rules to process unfamiliar attribute types (i.e., for name 619 chaining). This allows implementations to process certificates 620 with unfamiliar attributes in the subject name. 622 In addition, legacy implementations exist where an RFC 822 name 623 is embedded in the subject distinguished name as an 624 EmailAddress attribute. The attribute value for EmailAddress 625 is of type IA5String to permit inclusion of the character '@', 626 which is not part of the PrintableString character set. 627 EmailAddress attribute values are not case sensitive (e.g., 628 "fanfeedback@redsox.com" is the same as 629 "FANFEEDBACK@REDSOX.COM"). 631 Conforming implementations generating new certificates with 632 electronic mail addresses MUST use the rfc822Name in the 633 subject alternative name field (see sec. 4.2.1.7 of [RFC 634 2459]) to describe such identities. Simultaneous inclusion of 635 the EmailAddress attribute in the subject distinguished name to 636 support legacy implementations is deprecated but permitted. 638 Since no single method of including the UPN in the certificate will 639 work in all cases, CAP implementations MUST support the ability to 640 configure what the mapping will be by the CS administrator. 641 Implementations MAY support multiple mapping definitions, for 642 example, the UPN may be found in either the subject alternative name 643 field, or the UPN may be embedded in the subject distinguished name 644 as an EmailAddress attribute. 646 Note: If a CS or CUA is validating data received via iMIP, if the 647 "ORGANIZER" or "ATTENDEE" property said (e.g.) "ATTENDEE;CN=Joe 648 Random User:MAILTO:juser@example.com" then the email address should 649 be checked against the UPN. This is so the "ATTENDEE" property 650 cannot be changed to something misleading like "ATTENDEE;CN=Joe 651 Rictus User:MAILTO:juser@example.com" and have it pass validation. 652 This validation will also defeat other attempts at confusion. 654 2.4.1.2 Anonymous Users and Authentication 656 Anonymous access is often desirable. For example an organization may 657 publish calendar information that does not require any access control 658 for viewing or login. Conversely, a user may wish to view 659 unrestricted calendar information without revealing their identity. 661 2.4.1.3 User Groups 663 A User Group is used to represent a collection of CUs or other UGs 664 that can be referenced in VCARs. A UG is represented in CAP as a 665 UPN. The CUA cannot distinguish between a UPN that represents a CU 666 or a UG. 668 UGs are expanded as necessary by the CS. The CS MAY expand a UG 669 (including nested UGs) to obtain a list of unique CUs. Duplicate 670 UPNs are filtered during expansion. 672 The CS should not preserve UG expansions across operations. A UG may 673 reference a static list of members, or it may represent a dynamic 674 list. Each operation SHOULD generate its own expansion in order to 675 recognize changes to UG membership. 677 CAP does not define commands or methods for managing UGs. 679 2.4.2 Access Rights - Summary 681 Access rights are used to grant or deny access to a calendar for a 682 CU. CAP defines a new component type called a Calendar Access Right 683 (VCAR). Specifically, a VCAR grants, or denies, UPNs the right to 684 read and write components, properties, and parameters on calendars 685 within a CS. 687 The VCAR model does not put any restriction on the sequence in which 688 the object and access rights are created. That is, an event 689 associated with a particular VCAR might be created before or after 690 the actual VCAR is defined. In addition, the VCAR and VEVENT 691 definition might be created in the same iCalendar object and passed 692 together in a single object. 694 All rights MUST be denied unless specifically granted. 696 If two rights specified in VCAR components are in conflict, the right 697 that denies access always takes precedence over the right that grant 698 access. 700 2.4.2.1 Calendar Access Right (VCAR) 702 Access rights within CAP are specified with the "VCAR" calendar 703 component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID" 704 component properties. 706 Properties within an iCalendar object are unordered. This also is 707 the case for the "VCAR" properties. 709 For details on the VCAR syntax please see section Section 2.4.2 711 2.4.2.2 Predefined VCARs 713 Predefined calendar access CARIDs that MUST be implemented are: 715 CARID:READBUSYTIMEINFO - grants all authenticated users the right to 716 read VFREEBUSY components. Suggested definition for this VCAR: 718 BEGIN:VCAR 719 CARID:READBUSYTIMEINFO 720 BEGIN:VRIGHT 721 GRANT:* 722 PERMISSION:READ 723 SCOPE:SELECT * FROM VFREEBUSY 724 END:VRIGHT 725 END:VCAR 727 CARID:REQUESTONLY - grants to users other than the owner of the 728 calendar the right to write new events with the property METHOD set 729 to REQUEST. Suggested definition for this VCAR: 731 BEGIN:VCAR 732 CARID:REQUESTONLY 733 BEGIN:VRIGHT 734 GRANT:NONOWNER 735 PERMISSION:WRITE 736 RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST' 737 END:VRIGHT 738 END:VCAR 740 CARID:UPDATEPARTSTATUS - grants all authenticated users the right to 741 modify the instances of the ATTENDEE property set to one of their 742 calendar adresses in the VEVENT and VTODO components for which the 743 ORGANIZER property is set to the address of the VAGENDA in which the 744 VEVENT or VTODO is stored, given that the submitted value of the 745 ATTENDEE property is one of their calendar adresses. Suggested 746 definition for this VCAR: 748 BEGIN:VCAR 749 CARID:UPDATEPARTSTATUS 750 BEGIN:VRIGHT 751 GRANT:* 752 PERMISSION:MODIFY 753 SCOPE:SELECT att FROM VEVENT 754 USING_PROPERTIES ATTENDEE att 755 WHERE SELF() IN CAL-OWNERS(att) AND ORGANIZER = CURRENT-CALID() 756 RESTRICTION:SELECT * FROM VEVENT 757 WHERE SELF() IN CAL-OWNERS(ATTENDEE) 758 END:VRIGHT 759 BEGIN:VRIGHT 760 GRANT:* 761 PERMISSION:MODIFY 762 SCOPE:SELECT att FROM VTODO 763 USING_PROPERTIES ATTENDEE att 764 WHERE SELF() IN CAL-OWNERS(att) AND ORGANIZER = CURRENT-CALID() 765 RESTRICTION:SELECT * FROM VTODO 766 WHERE SELF() IN CAL-OWNERS(ATTENDEE) 767 END:VRIGHT 768 END:VCAR 770 CARID:DEFAULTOWNER - grants to the owner all permissions on all the 771 objects in the calendar. Suggested definition for this VCAR: 773 BEGIN:VCAR 774 CARID:DEFAULTOWNER 775 BEGIN:VRIGHT 776 GRANT:OWNER 777 PERMISSION:* 778 SCOPE:SELECT * FROM VAGENDA 779 END:VRIGHT 780 END:VCAR 782 2.4.2.3 Decreed VCARs 784 A CS MAY choose to implement and allow persistent immutable VCARs, 785 that are configured by the CS administrator, which apply to all 786 calendars on the server. 788 When a user attempts to modify or override a decreed VCAR an error 789 will be returned, indicating that the user has insufficient 790 authorization to perform the operation. The reply to the CUA MUST BE 791 the same as if a non-decreed VCAR caused the failure. 793 The CAP protocol does not define the semantics used to initially 794 create a decreed VCAR. This administrative task is outside the scope 795 of the CAP protocol. 797 For example an implementation or a CS administrator may wish to 798 define a VCAR that will always allow the calendar owners to have full 799 access to their own calendars. The GRANT property allows the OWNERs 800 all access to their own calendar objects. The DENY property 801 disallows anyone (UPN=*) from being able to delete or modify this 802 VCAR. 804 BEGIN:VCAR 805 CARID:ctjmocfbr-01 806 NAME:Users Default Access 807 DECREED:TRUE 808 BEGIN:VRIGHT 809 GRANT:OWNER 810 PERMISSION:* 811 SCOPE:SELECT * FROM VAGENDA 812 END:VRIGHT 813 BEGIN:VRIGHT 814 DENY:* 815 PERMISSION:DELETE 816 PERMISSION:MODIFY 817 SCOPE:SELECT * FROM VCAR WHERE CARID = 'ctjmocfbr-01' 818 END:VRIGHT 819 END:VCAR 821 Decreed VCARs MUST BE readable by the calendar owner in standard VCAR 822 format. 824 2.4.3 CAP Session Identity 826 A BEEP session has an associated set of authentication credentials, 827 from which is derived a UPN. This UPN is the identity of the CAP 828 session, and is used to determine access rights for the session. 830 The CUA may change the identity of a CAP session by calling the 831 "identify" CAP command. The Calendar Service only permits the 832 operation if the session's authentication credentials are good for 833 the requested identity. The method of checking this permission is 834 implementation dependent, but may be thought of as a mapping from 835 authentication credentials to UPNs. The "identify" command allows a 836 single set of authentication credentials to choose from multiple 837 identities, and allows multiple sets of authentication credentials to 838 assume the same identity. 840 For anonymous access the identity of the session is "@", a UPN with a 841 null Username and null Realm. A UPN with a null Username, but non- 842 null Realm, such as "@foo.com" may be used to mean any identity from 843 that Realm, which is useful to grant access rights to all users in a 844 given Realm. A UPN with a non-null Username and null Realm, such as 845 "bob@" could be a security risk and MUST NOT be used. 847 Since the UPN includes Realm information it may be used to govern 848 calendar store access rights across Realms. However, governing 849 access rights across Realms is only useful if login access is 850 available. This could be done through a trusted server relationship 851 or a temporary account. Note that trusted server relationships are 852 outside the scope of [CAP]. 854 The "identify" command provides for a weak group implementation. By 855 allowing multiple sets of authentication credentials belonging to 856 different users to identify as the same UPN, that UPN essentially 857 identifies a group of people, and may be used for group calendar 858 ownership, or the granting of access rights to a group. 860 2.5 Roles 862 CAP defines methods for managing [RFC2445] objects in a Calendar 863 Store and exchanging [RFC2445] objects for the purposes of group 864 calendaring and scheduling between "Calendar Users" (CUs) or "User 865 Groups" (UGs). There are two distinct roles taken on by CUs in CAP. 866 The CU who creates an initial event or to-do and invites other CUs as 867 attendees takes on the role of "Organizer". The CUs asked to 868 participate in the event or to-do take on the role of "Attendee". 869 Note that "role" is also a descriptive parameter to the "ATTENDEE" 870 property. Its use is to convey descriptive context to an "Attendee" 871 such as "chair", "REQ-PARTICIPANT" or "NON-PARTICIPANT" and has 872 nothing to do with the scheduling workflow. 874 2.6 CAP URL 876 The CAP URL scheme is used to designate calendar stores, and 877 calendars accessible using the CAP protocol. 879 The CAP URL scheme conform to the generic URL syntax, defined in RFC 880 2396, and follows the Guidelines for URL Schemes, set forth in RFC 881 2718. 883 A CAP URL begins with the protocol prefix "cap" and is defined by the 884 following grammar. 886 capurl = scheme ":" [ "//" csid ] [ "/" relcalid ] 887 scheme = "cap" 888 csid = hostport ; As defined in Section 3.2.2 of RFC 2396 889 relcalid = *uric ; As defined in Section 2 of RFC 2396 891 'relcalid' is an identifier that uniquely identifies a calendar on a 892 particular calendar store. There is no implied structure in a 893 Relative CALID. It may refer to the calendar of a user or of a 894 resource such as a conference room. It MUST be unique within the 895 calendar store. 897 Examples: 899 cap://cal.example.com 900 cap://cal.example.com/abcd1234QWER 902 Relative CAP URLs are permitted and are resolved according to the 903 rules defined in Section 5 of RFC 2396. 905 Example of a relative CAP URL: 907 abcd1234QWER 909 2.7 Calendar Addresses 911 Calendar addresses can be described as absolute or relative CAP URLs. 913 Examples: 915 cap://cal.example.com/abcd1234QWER 916 abcd1234QWER 918 For a user currently authenticated to the CAP server on 919 cal.example.com, these two calendar addresses refer to the same 920 calendar. 922 2.8 Extensions to iCalendar 924 In mapping the calendar query feature, and access rights onto the 925 iCalendar format, several extended iCalendar properties and 926 components are defined by this memo. 928 The search operation makes use of a new component, called VQUERY. 929 The component consists of a set of new properties: QUERY, EXPAND, 930 NAME and QUERYID, that define a search filter. VQUERY is used by the 931 following CAP commands: "search", "modify", "move" and "delete". 933 Access rights are specified in the new iCalendar VCAR component. 935 Calendar are specified by the new VAGENDA component. 937 2.9 Relationship of RFC 2446 (ITIP) to CAP 939 [iTIP] describes scheduling methods which result in indirect 940 manipulation of calendar components. In CAP, the "create" command is 941 used to submit scheduling requests. Other CAP commands such as 942 "create", "delete", "modify" and "move" provide direct manipulation 943 of calendar components. In the CAP calendar store model, scheduling 944 messages are conceptually kept separate from other calendar 945 components. 947 When scheduling is used, the METHOD is saved along with components. 948 A scheduled component becomes a booked component when its METHOD 949 property is set to CREATE. For example, a component whose METHOD is 950 "REQUEST" is scheduled. The component becomes booked when the METHOD 951 is set to "CREATE". 953 Several scheduled entries can be in the CS for the same UID. They 954 are consolidated when booked, or they are removed from the CS. 956 For example, if you were on vacation, you could have a REQUEST to 957 attend a meeting and several updates to that meeting. Your CUA would 958 have to "search" them out of the CS using CAP, process them, 959 determine what the final state of the object from a possible 960 combination of user input and programmed logic. Then the CUA would 961 instruct the CS to "create" a new booked entry or "modify" an 962 existing entry. Finally, the CUA can do a "delete" of all of these 963 now old scheduling requests in the CS. See [iTIP] for details on 964 resolving multiple [iTIP] scheduling entries. 966 3. Protocol Framework 968 CAP uses the BEEP application protocol kernel mapped onto TCP (refer 969 to [BEEP] and [BEEPTCP] for more information). The default port that 970 the Calendar Service listens for connections on is port --TBD--. 972 3.1 BEEP Exchange Styles 974 [BEEP] defines three styles of message exchange: 976 MSG/ANS,ANS,...,NUL: for one-to-many exchanges. 978 MSG/RPY: for one-to-one exchanges. 980 MSG/ERR: for requests the cannot be processed due to an error. 982 A CAP request, targeted at more than one containers, MUST use a one- 983 to-many exchange, with a distinct answer associated with each target. 984 CAP request targeted at a single container MAY use a one-to-one 985 exchange or a one-to-many exchange. "MSG/ERR" MAY only be used when 986 an error condition prevents the execution of the request on all the 987 targeted calendars. 989 3.2 Use BEEP, MIME and iCalendar 991 NOTE: This topic is under debate and all CAP commands might drop the 992 XML wrapper and just send the text/calendar objects and it would 993 contain the command. 995 Each BEEP payload exchanged via CAP is a iCalendar MIME content that 996 fully conforms to [RFC2445]. 998 C: MSG 1 2 . 432 62 999 C: Content-Type: application/cap+xml 1000 C: 1001 C: 1002 C: END 1004 Otherwise, arbitrary MIME content is included in the BEEP payload 1005 using CDATA. 1007 C: MSG 1 3 . 1023 951 1008 C: Content-type: application/cap+xml 1009 C: 1010 C: 1011 C: 1030 C: 1031 C: END 1033 NOTE: From this point on many of the examples will not include the 1034 BEEP header and footer information. Only the iCalendar objects that 1035 are sent between the CUA and CS will be shown as the BEEP payload 1036 boundries are independant of CAP. 1038 3.3 Bounded Latency 1040 A CUA can associate a maximum latency time to a CAP command with the 1041 "latency" argument. If the CS is unable to complete the request in 1042 the specified amount of time, then the CS sends a "timeout" MSG on 1043 the same channel to which the CUA MUST reply with an "abort" or a 1044 "continue" reply. 1046 Upon receiving an "abort" reply, the CS MUST terminate the command in 1047 progress. 1049 When receiving a "continue" reply the server resumes its work in 1050 progress. Note that a new latency time MAY be included in a 1051 "continue" reply. 1053 The timeout argument and the "action" MUST both be added to the CAP 1054 command, or nether can be added to a command. The "latency" value 1055 MUST BE set to the maximum latency time in seconds. The "action" 1056 argument accepts the following values: "ask" and "abort". If the 1057 maximum latency time is exceeded and the "action" argument is set to 1058 "ask", then CS MUST send a "timeout" message to inform the CUA, 1059 otherwise if the argument "action" is set to "abort" the CS can 1060 directly terminate the request and return a request-status code 1061 2.0.3. 1063 Example: 1065 In this example bill@cal.example.com attempts to read a calendar but 1066 the latency time he supplies is not sufficient for the server to 1067 complete the command. 1069 C: MSG 1 4 . 2043 680 1070 C: Content-Type: application/cap+xml 1071 C: 1072 C: 1073 C: = '19990714T080000Z' AND 1083 C: DTSTART <= '19990715T080000Z' 1084 C: END:VQUERY 1085 C: END:VCALENDAR 1086 C: ]]> 1087 C: 1088 C: END 1090 # After 3 seconds 1091 S: MSG 1 2 . 102 64 1092 S: Content-Type: application/cap+xml 1093 S: 1094 S: 1095 S: END 1097 If Bill wants to continue and give the server more time he would 1098 issue a "continue" reply: 1100 C: RPY 1 2 . 166 113 1101 C: Content-Type: application/cap+xml 1102 C: 1103 C: 1104 C: END 1106 If instead, Bill wanted to abort the command and not wait any further 1107 he would issue an "abort" reply: 1109 C: RPY 1 2 . 166 62 1110 C: Content-Type: application/cap+xml 1111 C: 1112 C: 1113 C: END 1115 S: RPY 1 4 . 2723 114 1116 S: 1117 S: 1118 S: Request Aborted by the CUA. 1119 S: 1120 S: END 1122 4. New Value Types 1124 4.1 CAL-QUERY Value Type 1126 Subject: Registration of text/calendar MIME value type CAL-QUERY 1128 Value Name: CAL-QUERY 1130 Value Type Purpose: This value type is used to identify values 1131 and contains query statements targeted at locating those values. 1133 This was based on [SQL92] and [SQLCOM]. 1134 NOTE: This grammar is NOT SQL92. 1136 (1) For the purpose of a query, all components should be 1137 handled as tables, and the properties of those 1138 components, should be handled as columns. 1140 (2) All VAGENDAs and CS's look like tables for the purpose of a 1141 QUERY. And all of their properties look like columns in 1142 those tables. 1144 (3) You CAN NOT do any cross component-type joins. And that means 1145 you can ONLY have one component, OR one VAGENDA OR one CALSTORE 1146 in the the FROM clause. 1148 (4) Everything in the SELECT and WHERE clauses MUST BE from the 1149 component type, or VAGENDA OR CALSTORE in the FROM clause. 1150 This includes the values from the USING_PROPERTIES and 1151 USING_COMPONENTS clauses. 1153 (5) The '.' is used to separate the table name (component) 1154 and column name (property) when selecting a property that 1155 is contained inside of a component that is targeted in 1156 the TARGET property. 1158 In this example the '.' is used to separate the 1159 TRIGGER property from its contained component (VALARM) 1160 which is contained in any VEVENT in the selected TARGET 1161 (relcalid). All TRIGGER values in any VEVENT in relcalid 1162 would be returned. 1164 TARGET:relcalid 1165 QUERY: SELECT VALARM.TRIGGER FROM VEVENT 1167 (6) A contained component without a '.' it is the same as 1168 .* with the result being a properly formatted 1169 (s) in the data stream, and correctly formatted 1170 in the contained component(s) in iCalendar (RFC2445) format. 1172 (a) SELECT VEVENT. FROM VEVENT 1174 (b) SELECT VALARM FROM VEVENT 1176 (c) SELECT VALARM.* FROM VEVENT 1178 (d) SELECT * FROM VEVENT 1180 (e) SELECT * FROM VEVENT WHERE 1181 VALARM.TRIGGER < '20020201T000000Z' 1182 AND VALARM.TRIGGER > '20020101T000000Z' 1184 Note: (a) Selects all instances of 1185 from all VEVENT components. 1187 (b) and (c) Select all VALARM components from all 1188 VEVENT components. 1190 (d) Selects every property and every component 1191 that is in any VEVENT component. 1193 (e) Selects all properties and all contained 1194 components in all VEVENT components that have a VALARM 1195 with a TRIGGER property value between the provided 1196 dates and times. 1198 NOT VALID: 1200 (f) SELECT VEVENET.VALARM.TRIGGER FROM VEVENT 1202 (g) SELECT DTSTART,UID FROM VEVENT WHERE 1203 VTODO.SUMMERY = "Fix typo in CAP" 1205 Note: (g) Is NOT valid because it contains 1206 two '.' characters in the SELECT clause. 1208 (h) Is NOT valid because it mixes VEVENT 1209 and VTODO properties in the same VQUERY. 1211 (7) When multiple QUERY properties are supplied in a single VQUERY 1212 component, the results returned are the same as the results 1213 returned for multipled VQUERY components having each a single 1214 QUERY property. 1216 Formal Definition: The value type is defined by the following 1217 notation: 1219 comp-name = "VEVENT" / "VTODO" / "VJOURNAL" 1220 / "VTIMEZONE" / "VALARM" / "VFREEBUSY" 1221 / "VAGENDA" / "VCAR" / "CALSTORE" 1222 / "VQUERY" / iana-name / x-comp 1224 querycomp = queries / ( queryname queries) / queryname 1226 queryname = "QUERYNAME" *(";" xparam) ":" text CRLF 1228 queries = query 1229 / queries query 1231 query = "QUERY" *(";" xparam) ":" cal-query CRLF 1233 ; NOTE: There is exactly one space separating 1234 ; the various parts of cal-query 1235 ; 1236 cal-query = "SELECT" SP cap-cols SP 1237 "FROM" SP comp-name SP 1238 *(cauprops SP / capcprops SP) 1239 "WHERE" SP cap-expr 1241 / "SELECT" SP cap-cols SP 1242 "FROM" SP comp-name 1244 capuprops = "USING_PROPERTIES" SP uprop-list 1246 uprop-list = (cap-col SP cap-local) 1247 / uprop-list SP cap-col SP cap-local 1249 capcprops = "USING_COMPONENTS" SP cprop-list 1251 cprop-list = (cap-comp cap-local) 1252 / cprop-list SP cap-col SP cap-local 1254 cap-col = ; Any property name found in the component 1255 ; named in the comp-tbl used in the FROM clause. 1256 ; 1257 ; SELECT ORGANIZER FROM VEVENT ... 1258 ; 1259 ; OR 1260 ; 1261 ; A component name of an existing component contained 1262 ; inside of the cmp-tbl used in the FROM clause. 1263 ; 1264 ; SELECT VALARM FROM VEVENT ... 1266 ; NOTE: there is NO space around the "," on 1267 ; the next line 1268 cap-cols = cap-col / ( cap-cols "," cap-col) 1269 / "*" 1270 / 1271 cap-param = ; Any parameter that may be contained in the cap-col 1272 ; in the supplied PARAM() function 1274 cap-local = ; Any string that is composed of the characters 1275 ; that could be a cap-col name, but is not any 1276 ; cap-col name. It is suggested that the 1277 ; string start with "my-" to ensure it does not 1278 ; conflict with any existing or future cap-col name. 1279 ; This name MUST BE defined in the cap-using and 1280 ; can only be used in cap-expr of the same query. 1281 ; And this name is only known and valid for the 1282 ; provided query and only for the lifetime of 1283 ; the query. If multiple QUERY properties exist 1284 ; in the same component, it is only valid and usable 1285 ; in the same QUERY property where it was supplied. 1287 col-value = col-literal 1288 / "SELF()" 1289 / "CAL-OWNERS(" cal-address ")" 1290 / "CURRENT-CALID()" 1292 cal-address = ; A CALID as define by CAP 1294 col-literal = "'" literal-data "'" 1296 literal-data = ; Any data that matches the value type of the 1297 ; column that is being compared. That is you can 1298 ; not compare PRIORITY to "some string" because 1299 ; PRIORITY has a value type of integer. If it is 1300 ; not preceded by the LIKE element, any '%' and '_' 1301 ; characters in the literal data are not treated as 1302 ; wildcard characters and do not have to be backslash 1303 ; escaped. 1304 ; 1305 ; OR 1306 ; 1307 ; If the literal-data is preceded by the LIKE 1308 ; element it may also contain the '%' and '_' 1309 ; wildcard characters. And if the literal data 1310 ; that is comparing contains any '%' or '_' 1311 ; characters, they MUST BE backslash escaped as 1312 ; described in the notes below in order for them not 1313 ; to be treated as wildcard characters. 1315 cap-ucol = cap-col / cap-local 1317 cap-expr = "(" cap-expr ")" 1318 / cap-term 1320 cap-term = cap-expr SP cap-logical SP cap-expr 1321 / cap-factor 1323 cap-factor = cap-colval SP cap-oper SP col-value 1324 / cap-colval SP "NOT LIKE" SP col-value 1325 / cap-colval SP "LIKE" SP col-value 1326 / cap-colval SP "IS NULL" 1327 / cap-colval SP "IS NOT NULL" 1328 / col-value SP "NOT IN" cap-colval" 1329 / col-value SP "IN" cap-colval" 1331 cap-colval = cap-ucol 1332 / "PARAM(" cap-ucol "," cap-param ")" 1334 cap-oper = "=" 1335 / "!=" 1336 / "<" 1337 / ">" 1338 / "<=" 1339 / ">=" 1341 cap-logical = "AND" / "OR" 1343 SP = ; A single white space ascii character 1344 ; (value in HEX %x20). 1346 CRLF = ; As defined in RFC 2445. 1348 xparam = ; As defined in RFC 2445. 1350 x-prop = ; As defined in RFC 2445. 1352 x-comp = ; As defined in RFC 2445. 1354 4.1.1 CAP-QL notes 1356 (1) There is no ORDERBY. Sorting will take place in the order the 1357 columns are supplied in the command. 1359 Float and integer values MUST BE sorted by their numeric value. 1361 This means the result of a sort on an integer value type will be: 1363 1, 2, 100, 1000 1365 and not 1367 1, 100, 1000, 2 1369 This means the result of a sort on an float value type will be: 1371 1.1, 2.23, 100.332, 1000.12 1373 and not 1375 1.1, 100.332, 1000.12, 2.23 1377 Date and date time values will be sorted by their equivalent 1378 value in UTC. No matter what the returned time zone in the result 1379 set returns. This is so that if multiple components are returned 1380 each in a unique time zone, the results will be sorted in UTC. 1381 This does not mean the values must be converted to UTC in the 1382 data returned to the CUA. It means the CS must do the sort in UTC. 1384 All other values are sorted according to the locale sorting order 1385 as specified in the calendar. Or the CS locale if the calendar 1386 does not have any locale set, or the host operating system 1387 locale if the CS does not specify a locale. And the locale to 1388 use for the sort is determined in that order. 1390 (2) The CS MUST sort at least the first column. 1391 The CS MAY sort additional columns. 1393 (3) If the cap-cols is only "*" and nothing else, then: 1395 If EXPAND=FALSE sorting will be by the DTSTART value 1396 ascending. 1398 If EXPAND=TRUE sorting will be by the RECURRENCE-ID value 1399 ascending. 1401 If one or more DTSTART or RECURRENCE-ID components have 1402 exactly the same value, the order for those matching 1403 components is unspecified. 1405 If the selected component(s) do not contain a DTSTART 1406 or a RECURRENCE-ID, then the order is unspecified. 1408 (4) All literal values are surrounded by single quotes ('), not 1409 double quotes ("), and not without any quotes. If the value 1410 contains quotes or any other ESCAPED-CHAR, they must be 1411 backslash escaped as described in section "4.3.11 Text" 1412 of RFC2445. Any LIKE wildcard characters that are part 1413 of any literal data that is preceded by a LIKE clause and 1414 is not intended to mean wildcard search, MUST BE escaped as 1415 described in note (7) below. 1417 (5) When comparing DATE-TIME to DATE value types and when 1418 comparing DATE to DATE-TIME value types, the result will 1419 be true if the DATE value is on the same day as the DATE-TIME 1420 value. And they are compared in UTC no matter what time zone 1421 the data may actual have been stored in. 1423 VALUE-1 VALUE-2 Compare Results 1425 20020304 20020304T123456 TRUE 1426 (in UTC-3) (in UTC-3) 1428 20020304 20020304T003456 FALSE 1429 (in UTC-4) (in UTC-4) 1431 20020304T003456Z 20020205T003456 FALSE 1432 (in UTC-0) (in UTC-7) 1434 When comparing DATE and DATE-TIME values with the LIKE 1435 clause the comparison will be done as if the value is 1436 a RFC2445 DATE or DATE-TIME string value. 1438 LIKE '2002%' will match anything in the year 2002. 1440 LIKE '200201%' will match anything in January 2002. 1442 LIKE '%T000000' will match anything at midnight. 1444 LIKE '____01__T%' will match anything for any year or 1445 time that is in January. 1446 (Four '_', '01', two '_' 'T%'). 1448 Again all comparisons will be done in UTC. 1450 Using a LIKE value of "%00%, would return any value that 1451 contained two consecutive zeros. 1453 (6) DTEND and DURATION. 1455 When a QUERY contains a DTEND value, then the CS MUST also 1456 evaluate any existing DURATION property value and determine 1457 if it has an effective end time that matches the QUERY 1458 supplied DTEND value or any range of values supplied by 1459 the QUERY. 1461 When a QUERY contains a DURATION value, then the CS MUST 1462 also evaluate any existing DTEND property value and determine 1463 if it has an effective duration that matches the QUERY 1464 supplied DURATION value or any range of values supplied by 1465 the QUERY. 1467 As DTEND is the first time that is excluded from a components 1468 time range, any DURATION supplied by the QUERY that is 1469 exactly one second less than DTEND MUST match the QUERY. 1470 And if the DURATION ends exactly at the computed DTEND it 1471 MUST NOT match. 1473 Any DTEND supplied by the QUERY that is exactly one second 1474 more than an end time computed from a DURATION MUST match the 1475 QUERY. Any end time that is computed from a DURATION that 1476 exactly matches the supplied DTEND MUST NOT match. 1478 (6.1) Given a meeting room reserved with a component 1479 that contains: 1480 DTSTART:20020127T000000Z 1481 DTEND:20020127T010000Z 1483 The reservation is really from: 1485 January 27th, 2002 00:00:00 1486 To: 1488 January 27th, 2002,00:59:59 1490 (6.2) Given another meeting room reserved with a component 1491 that contains: 1493 DTSTART:20020127T000000Z 1494 DURATION:P59M59S 1496 The reservation is really from: 1498 January 27th, 2002 00:00:00 1499 To: 1501 January 27th, 2002,00:59:59 1503 (6.3) A QUERY that contains: 1505 ... VEVENT.DTSTART = '20020127T00000Z' 1506 AND VEVENT.DTEND = '20020127T010000Z' 1508 MUST match both (6.1) and (6.2). 1510 (6.4) A QUERY that contains: 1512 ... VEVENT.DTSTART = '20020127T00000Z' 1513 AND DURATION = 'P59M59S' 1515 MUST match both (6.1) and (6.2). 1517 (7) [NOT] LIKE notes: 1519 The pattern matching characters is the '%' that matches 1520 zero or more characters, and '_' that matches exactly one 1521 character (where character does not always mean octet). 1523 LIKE pattern matches always cover the entire string. To match 1524 a pattern anywhere within a string, the pattern must start and 1525 end with a percent sign. 1527 To match a '%' or '_' in the data and not have it interpreted 1528 as a wildcard character, they must be backslash escaped. 1529 That is to search for a '%' or '_' in the string: 1531 LIKE '%\%%' Matches any string with a '%' in it. 1532 LIKE '%\_%' Matches any string with a '_' in it. 1534 Strings compared using the LIKE clause MUST BE performed 1535 using case in-sensitive comparisons. ('a' = 'A'). 1537 If LIKE is preceded by 'NOT' then there is a match when 1538 the string compare fails. 1540 Some property values (such as the 'recur' value type), contain 1541 commas and are not multi valued. The CS must understand the 1542 objects being compared and understand how to determine how any 1543 multi valued or multi instances properties or parameter values 1544 are separated, quoted, and backslash escaped and perform the 1545 comparisons as if each value existed by itself and not quoted 1546 or backslash escaped when comparing using the CONTAINS() element. 1548 And see the examples in the next note (8). 1550 (8) 'col-value SP "NOT IN" cap-colval" 1552 This is similar to the LIKE element, except it does value 1553 matching and not string comparison matches. 1555 Some iCalendar objects can be multi instance and multi valued. 1556 The IN operator will return a match if the literal value supplied 1557 as part of the 'IN' clause is contained in the value of any 1558 instance of the named property or parameter, or is in any of 1559 the multiple values in the named property or parameter. The 1560 '%' and '_' matching characters are not used with the 'IN' 1561 clause and have no special meaning. 1563 BEGIN:A-COMPONENT 1564 a property:value1,value2 One property, two values. 1565 b property:"value1,value2" One property, one value. 1566 c FOO:parameter=1,2:x One parameter, two values. 1567 d FOO:parameter="1,2",3:y One parameter, two value. 1568 e FOO:parameter="," 1569 END:A-COMPONENT 1571 'value1' IN property would match (a) only. 1572 'value1,value2' IN property would match (b) only. 1573 'value%' IN property would NOT match any. 1574 ',' IN property would NOT match any. 1575 '%,%' IN property would NOT match any. 1577 '2' IN parameter would match (c) only. 1578 '1,2' IN parameter would match (d) only. 1579 '%,%' IN parameter would match (d) and (e). 1581 LIKE(property, "value1%" would match (a) and (b) 1582 LIKE(property, 'value%') would match (a) and (b) 1583 LIKE(parameter, '1%') would match (c) and (d) 1584 LIKE(parameter, '%2%') would match (c) and (d) 1585 LIKE(parameter, ',') would NOT match any. 1587 Some property values (such as the 'recur' value type), contain 1588 commas and are not multi valued. The CS must understand the 1589 objects being compared and understand how to determine how any 1590 multi valued or multi instances properties or parameter values 1591 are separated, quoted, and backslash escaped and perform the 1592 comparisons as if each value existed by itself and not quoted 1593 or backslash escaped when comparing using the CONTAINS() element. 1595 If IN is preceded by 'NOT' then there is a match when 1596 the value does not exist in the property or parameter value. 1598 (9) DATE-TIME and TIME values in a WHEN clause. 1600 All DATE-TIME and TIME literal values supplied as in 1601 a WHEN clause MUST BE terminated with 'Z'. That means 1602 that the CUA MUST supply the values in UTC. 1604 Valid: 1606 WHERE alarm.TRIGGER < '20020201T000000Z' 1607 AND alarm.TRIGGER > '20020101T000000Z' 1609 Not valid: 1611 WHERE alarm.TRIGGER < '20020201T000000' 1612 AND alarm.TRIGGER > '20020101T000000' 1614 It is a syntax error and the CS MUST reject the QUERY. 1616 4.2 CAP-QL notes 1618 (1) There is no ORDERBY. Sorting will take place in the order the 1619 columns are supplied in the command. 1621 Float and integer values MUST BE sorted by their numeric value. 1623 This means the result of a sort on an integer value type will be: 1625 1, 2, 100, 1000 1627 and not 1629 1, 100, 1000, 2 1631 This means the result of a sort on an float value type will be: 1633 1.1, 2.23, 100.332, 1000.12 1635 and not 1637 1.1, 100.332, 1000.12, 2.23 1639 Date and date time values will be sorted by their equivalent 1640 value in UTC. No matter what the returned time zone is in the 1641 result set. This is so that if multiple components are returned 1642 each in a unique time zone, the results will be sorted in UTC. 1643 This does not mean the values must be converted to UTC in the 1644 data returned to the CUA. It means the CS must do the sort in UTC. 1646 All other values are sorted according to the locale sorting order 1647 as specified in the calendar. Or the CS locale if the calendar 1648 does not have any locale set, or the host operating system 1649 locale if the CS does not specify a locale. And the locale to 1650 use for the sort is determined in that order. 1652 (2) The CS MUST sort at least the first column. 1653 The CS MAY sort additional columns. 1655 (3) If the cap-cols is only "*" and nothing else, then: 1657 If EXPAND=FALSE sorting will be by the DTSTART value 1658 ascending. 1660 If EXPAND=TRUE sorting will be by the RECURRENCE-ID value 1661 ascending. 1663 If one or more DTSTART or RECURRENCE-ID components have 1664 exactly the same value, the order for those matching 1665 components is unspecified. 1667 (4) All literal values are surrounded by single quotes ('), not 1668 double quotes ("), and not without any quotes. If the value 1669 contains quotes or any other ESCAPED-CHAR, they must be 1670 backslash escaped as described in section "4.3.11 Text" 1671 of RFC2445. Any LIKE wildcard characters that are part 1672 of any literal data that is preceded by a LIKE clause and 1673 is not intended to mean wildcard search, MUST BE escaped as 1674 described in note (7) below. 1676 (5) When comparing DATE-TIME to DATE value types and when 1677 comparing DATE to DATE-TIME value types, the result will 1678 be true if the DATE value is on the same day as the DATE-TIME 1679 value (both compared in UTC). And they MUST BE compared in UTC no 1680 matter what time zone the object had been tagged with when the 1681 object was stored in the CS. 1683 VALUE-1 VALUE-2 Compare Results 1685 20020304 20020304T123456 TRUE 1686 (in UTC-3) (in UTC-3) 1688 20020304 20020304T003456 FALSE 1689 (in UTC-4) (in UTC-4) 1691 20020304T003456Z 20020205T003456 FALSE 1692 (in UTC-0) (in UTC-7) 1694 When comparing DATE and DATE-TIME values with the LIKE 1695 clause the comparison will be done as if the value is 1696 a RFC2445 DATE or DATE-TIME string value (again in UTC). 1698 LIKE '2002%' will match anything in the year 2002 (UTC). 1700 LIKE '200201%' will match anything in January 2002 (UTC). 1702 LIKE '%T000000' will match anything at midnight (UTC). 1704 LIKE '____01__T%' will match anything for any year or 1705 time that is in January (UTC). 1706 (Four '_', '01', two '_' 'T%'). 1708 Again all comparisons will be done in UTC. 1710 Using a LIKE value of "%00%, would return any value that 1711 contained two consecutive zeros. 1713 (6) DTEND and DURATION. 1715 When a VQUERY contains a DTEND value, then the CS MUST also 1716 evaluate any existing DURATION property value and determine 1717 if it has an effective end time that matches the VQUERY 1718 supplied DTEND value or any range of values supplied by 1719 the VQUERY. 1721 When a VQUERY contains a DURATION value, then the CS MUST 1722 also evaluate any existing DTEND property value and determine 1723 if it has an effective duration that matches the VQUERY 1724 supplied DURATION value or any range of values supplied by 1725 the VQUERY. 1727 As DTEND is the first time that is excluded from a components 1728 time range, any DURATION supplied by the VQUERY that is 1729 exactly one second less than DTEND MUST match the VQUERY. 1730 And if the DURATION ends exactly at the computed DTEND it 1731 MUST NOT match. 1733 Any DTEND supplied by the VQUERY that is exactly one second 1734 more than an end time computed from a DURATION MUST match the 1735 VQUERY. Any end time that is computed from a DURATION that 1736 exactly matches the supplied DTEND MUST NOT match. 1738 (6.1) Given a meeting room reserved with a component 1739 that contains: 1741 DTSTART:20020127T000000Z 1742 DTEND:20020127T010000Z 1744 The reservation is really from: 1746 January 27th, 2002 00:00:00 1747 To: 1749 January 27th, 2002,00:59:59 1751 (6.2) Given another meeting room reserved with a component 1752 that contains: 1754 DTSTART:20020127T000000Z 1755 DURATION:P59M59S 1757 The reservation is really from: 1759 January 27th, 2002 00:00:00 1760 To: 1762 January 27th, 2002,00:59:59 1764 (6.3) A VQUERY that contains: 1766 ... VEVENT.DTSTART = '20020127T00000Z' 1767 AND VEVENT.DTEND = '20020127T010000Z' 1769 MUST match both (6.1) and (6.2). 1771 (6.4) A VQUERY that contains: 1773 ... VEVENT.DTSTART = '20020127T00000Z' 1774 AND DURATION = 'P59M59S' 1776 MUST match both (6.1) and (6.2). 1778 (7) [NOT] LIKE notes: 1780 The pattern matching characters is the '%' that matches 1781 zero or more characters, and '_' that matches exactly one 1782 character (where character does not always mean octet). 1784 LIKE pattern matches always cover the entire string. To match 1785 a pattern anywhere within a string, the pattern must start and 1786 end with a percent sign. 1788 To match a '%' or '_' in the data and not have it interpreted 1789 as a wildcard character, they must be backslash escaped as 1790 done in [RFC2445]. That is to search for a '%' or '_' in 1791 the string: 1793 LIKE '%\%%' Matches any string with a '%' in it. 1794 LIKE '%\_%' Matches any string with a '_' in it. 1796 Strings compared using the LIKE clause MUST BE performed 1797 using case in-sensitive comparisons. ('a' = 'A'). 1799 The CS must understand the objects being compared and 1800 understand how to determine how any multi valued property 1801 or parameter values are separated, quoted, and backslash 1802 escaped and perform the comparisons as if each value existed 1803 by itself and not quoted or backslash escaped when comparing 1804 using the LIKE element. 1806 If LIKE is preceded by 'NOT' then there is a match when 1807 the string compare fails. 1809 (8) [NOT] "CONTAINS(" cap-lhs "," col-literal ")" 1811 This is similar to the LIKE element, except it does value 1812 matching and not string comparison matches. 1814 property:value1,value2 1816 CONTAINS(property, 'value1') would match 1817 CONTAINS(property, 'value') would NOT match 1819 LIKE(property, 'value%') would match 1821 The CS must understand the objects being compared and 1822 understand how to determine how any multi valued property 1823 or parameter values are separated, quoted, and backslash 1824 escaped and perform the comparisons as if each value existed 1825 by itself and not quoted or backslash escaped when comparing 1826 using the CONTAINS() element. 1828 If CONTAINS() is preceded by 'NOT' then there is a match when 1829 the value does not exist in the property or parameter value. 1831 (9) DATE-TIME and TIME values in a WHEN clause. 1833 All DATE-TIME and TIME literal values supplied as in 1834 a WHEN clause MUST BE terminated with 'Z'. That means 1835 that the CUA MUST supply the values in UTC. 1837 Valid: 1839 WHERE alarm.TRIGGER < '20020201T000000Z' 1840 AND alarm.TRIGGER > '20020101T000000Z' 1842 Not valid: 1844 WHERE alarm.TRIGGER < '20020201T000000' 1845 AND alarm.TRIGGER > '20020101T000000' 1847 It is a syntax error and the CS MUST reject the VQUERY. 1849 4.3 Example, Query by UID 1851 The following example would match the entire content of the VEVENT 1852 or VTODO with the UID property equal to "uid123" and not expand 1853 any multiple instances of the component. If the CUA does not know 1854 if "uid123" was a VEVENT, VTODO, VJOURNAL, or any other component, 1855 then all components that the CUA supports MUST be supplied in a 1856 QUERY property. This example assumes the CUA only supports VTODO and 1857 VEVENT. 1859 If the results were empty it could also mean that "uid123" was a 1860 property in a component other than a VTODO or VEVENT. 1862 BEGIN:VQUERY 1863 QUERY:SELECT * FROM VTODO WHERE UID = 'uid123' 1864 QUERY:SELECT * FROM VEVENT WHERE UID = 'uid123' 1865 END:VQUERY 1867 4.4 Query by Date-Time range 1869 This query selects the entire content of every booked VEVENT that has 1870 an instance greater than or equal to July 1st, 2000 00:00:00 UTC and 1871 less than or equal to July 31st, 2000 23:59:59 UTC 1873 BEGIN:VQUERY 1874 EXPAND:TRUE 1875 QUERY:SELECT * FROM VEVENT 1876 WHERE RECURRENCE-ID >= '20000801T000000Z' 1877 AND RECURRENCE-ID <= '20000831T235959Z' 1878 AND METHOD = 'CREATE' 1879 END:VQUERY 1881 4.5 Query for all Non-Booked Entries 1883 The following example selects the entire contents of all [ITIP] 1884 non-booked VTODOs and VEVENTs with their METHOD set to one of 1885 the [ITIP] METHODs. The default for EXPAND is FALSE, so the 1886 recurrence rules will not be expanded. 1888 BEGIN:VQUERY 1889 QUERYID:Fetch VEVENT and VTODO iTIP components 1890 NAME;LANG=fr_ca: ...todo... 1891 QUERY:SELECT * FROM VEVENT WHERE 1892 METHOD = 'REQUEST' OR METHOD = 'ADD' OR METHOD = 'PUBLISH' OR 1893 METHOD = 'CANCEL' OR METHOD = 'REPLY' OR METHOD = 'COUNTER' OR 1894 METHOD = 'REFRESH' OR METHOD = 'DECLINECOUNTER' 1895 QUERY:SELECT * FROM VTODO WHERE 1896 METHOD = 'REQUEST' OR METHOD = 'ADD' OR METHOD = 'PUBLISH' OR 1897 METHOD = 'CANCEL' OR METHOD = 'REPLY' OR METHOD = 'COUNTER' OR 1898 METHOD = 'REFRESH' OR METHOD = 'DECLINECOUNTER' 1899 END:VQUERY 1901 In the above exampe, the QUERY property could have been written as: 1903 QUERY:SELECT * FROM VEVENT WHERE METHOD != 'CREATE' 1904 AND METHOD != 'DELETE' 1906 The following example fetches all VEVENT and VTODO booked entries 1907 from the CS. 1909 BEGIN:VQUERY 1910 QUERYID:Fetch All Booked VEVENT and VTODO components 1911 QUERY:SELECT * FROM VEVENT WHERE METHOD = 'CREATE' 1912 QUERY:SELECT * FROM VTODO WHERE METHOD = 'CREATE' 1913 END:VQUERY 1915 The following fetches the UID for all VEVENT and VTODO components 1916 that have been marked for delete (METHOD:DELETE). 1918 BEGIN:VQUERY 1919 QUERYID:Fetch UIDs of marked for delete VEVENTs and VTODOs 1920 QUERY:SELECT UID FROM VEVENT WHERE METHOD = 'DELETE' 1921 QUERY:SELECT UID FROM VTODO WHERE METHOD = 'DELETE' 1922 END:VQUERY 1924 In the examples above they were bunched into groups of similar 1925 queries. They could be performed all at once by having all of 1926 the QUERY property in one BEGIN/END VQUERY component. 1928 4.6 Query with Subset of Properties by Date/Time 1930 In this example only the named properties will be selected and all 1931 booked and non-booked components will be selected that have a DTSTART 1932 from February 1st to February 10th 2000. 1934 BEGIN:VQUERY 1935 QUERY:SELECT UID,DTSTART,DESCRIPTION,SUMMARY FROM VEVENT 1936 WHERE DTSTART >= '20000201T000000Z' 1937 AND DTSTART <= '20000210T235959Z' 1938 END:VQUERY 1940 4.7 Components With Alarms In A Range 1942 This example fetches all VEVENTs with an alarm that triggers 1943 within the specified time range. In this case only the UID, SUMMARY, 1944 and DESCRIPTION will be selected for all booked VEVENTS that have an 1945 alarm between the two date-times. 1947 BEGIN:VQUERY 1948 EXPAND:TRUE 1949 QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT 1950 USING_COMPONENT VALARM my-alarm 1951 WHERE my-alarm.TRIGGER >= '20000101T030405Z' 1952 AND my-alarm.TRIGGER <= '20001231T235959Z' 1953 AND METHOD = 'CREATE' 1954 END:VQUERY 1956 5. Access Rights 1958 Access rights within CAP are specified with the "VCAR" calendar 1959 component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID" 1960 component properties. 1962 5.1 Access Control and NOCONFLICT 1964 The TRANSP property can take on values (TRANSPARENT-NOCONFLICT, 1965 OPAQUE-NOCONFLICT) that prohibit other events from overlapping it. 1966 This setting overrides access. The ALLOW-CONFLICT Calendar or 1967 component setting may also prevent overlap, returning an error code 1968 "6.3" 1970 6. Commands and Responses 1972 CAP commands and responses are described in this section. 1974 As mentioned in Section 3.2, CAP commands are defined by MIME 1975 objects. 1977 The attributes of a command are described in the "Attributes:" 1978 section in the command descriptions below. Similarly the "Elements:" 1979 section describes the elements that compose the command. The 1980 "Response:" section, identifies the responses that may be returned by 1981 the server. 1983 In the examples below, lines preceded with "S:" refer to the server 1984 and lines preceded with "C:" refer to the client. Lines in which the 1985 first non-whitespace character is a "#" are editorial comments and 1986 are not part of the protocol. 1988 6.1 Session Commands 1990 6.1.1 "generate-uid" Command 1992 Attributes: 1994 num: Number of UIDs to generate (1 if omitted). 1996 cmdid: A unique id that identifies this command to 1997 the CUA and CS. 1999 latency: How long before CS asks you to continue. (optional) 2001 action: How to handle latencty - MUST BE suppled but 2002 only when the 'latency' command is supplied. 2004 Response: 2006 "uid-list" 2008 The "generate-uid" command returns one or more unique identifiers 2009 which MUST BE globaly unique. 2011 Example: 2013 C: MSG 1 5 . 2837 60 2014 C: Content-Type: application/cap+xml 2015 C: 2016 C: 2017 C: END 2018 S: RPY 1 5 . 2897 328 2019 S: Content-Type: application/cap+xml 2020 S: 2021 S: 2022 S: 20011121T120000Z-12340@cal.example.com 2023 S: 20011121T120000Z-12341@cal.example.com 2024 S: 20011121T120000Z-12342@cal.example.com 2025 S: 20011121T120000Z-12343@cal.example.com 2026 S: 20011121T120000Z-12344@cal.example.com 2027 S: 2028 S: END 2030 6.1.2 "get-capability" Command 2032 Attributes: 2034 None 2036 Elements: 2038 None 2040 Response: 2042 "capability" 2044 The "get-capability" command returns information about the Calendar 2045 Server given the current state of the connection with the client. 2046 The values returned may differ depending on current user identify and 2047 the security level of the connection. 2049 Client implementations SHOULD NOT require any capability element 2050 beyond those defined in this specification, and MAY ignore any non- 2051 standard, experimental capability elements. Non-standard 2052 experimental capability elements MUST be prefixed with the text "x-". 2053 The prefix SHOULD also include a vendor identifier. For example, "x- 2054 foo-barcapability", for the non-standard "barcapability" capability 2055 of the vendor "foo". It may return different results depending on 2056 the UPN. 2058 Capability Occurs Description 2059 ------------------------------------------------------- 2060 cap 1 Container for CAP related elements. 2062 cap-version 1+ Version of CAP. MUST include at 2063 least "1.0" for this version of 2064 CAP. 2066 prodid 0 or 1 The product id of the CS. 2068 query-level 1+ Indicates level of SQL support. 2069 CAP-QL or NONE. (NONE is for 2070 CS's that allow ITIP methods 2071 only to be deposited and nothing 2072 else). If set to NONE, then the 2073 'car' capability MUST BE set to NONE. 2075 car 1+ Indicates level of CAR support. 2076 CAR-NONE, CAR-MIN or CAR-FULL-1. 2077 If CAR-FUL-1 is supplied then 2078 CAR-MIN MUST BE supplied. CAR = NONE 2079 MUST BE used when query-level of 2080 NONE is supplied. If 2082 date-max 0 or 1 The datetime value in UTC beyond 2083 which the server cannot accept. If 2084 not specified the default is 2085 99991231T235959Z. 2087 date-min 0 or 1 The datetime value prior to which 2088 the server cannot accept. If not 2089 specified the default is 2090 00000101T000000Z. 2092 max-component-size 2093 0 or 1 A positive integer value that specifies 2094 the size of the largest iCalendar 2095 object that the server will accept in 2096 octets. Objects larger than this will be 2097 rejected. The absence of this attribute 2098 indicates no limit. This is also the 2099 maximum value of any BEEP payload 2100 the CS will accept or send. 2102 components 1 A comma seperated list of the names of 2103 components that this CS supports. This 2104 includes any components inside of 2105 other components (VALARM and VEVENT 2106 for example). MUST include at least 2107 VCALSTORE, VCALENDAR, and VAGENDA 2108 and at least one of VEVENT, VTODO, 2109 or VJORNAL. 2111 version 1+ Version of iCalendar support. 2112 MUST BE at least "2.0". 2113 supported. 2115 itip-version 1+ Version(s) of ITIP, MUST include at 2116 least "1.0". 2118 recur-accepted 0 or 1 whether the CS accepts recurrence rules 2119 recur-expand 0 or 1 whether or not the CS supports the 2120 expansion of recurrence rules. 2121 recur-limit 0 or 1 the maximum number of occurrences or a recurrence 2122 rule that are expanded by the CS 2124 Example: 2126 C: MSG 1 6 . 3225 57 2127 C: Content-Type: application/beep+xml 2128 C: 2129 C: 2130 C: END 2131 S: RPY 1 6 . 3282 423 2132 S: Content-Type: application/beep+xml 2133 S: 2134 S: 2135 S: 2136 S: 2.0 2137 S: 65536 2138 S: 1.0 2139 S: 1.0 2140 S: CAR-FULL-1CAR-MINCAP-QL 2142 S: 00000101T000000Z 2143 S: 99991231T235959Z 2144 S: 2145 S: VCALSTORE,VAGENDA,VCALENDAR,VEVENT,X-my-vcomp,VALARM 2146 S: 2147 S: 2148 S: END 2150 6.1.3 "identify" Command 2152 Attribute: 2154 upn: The UPN of the new identify to assume. 2156 Element: 2158 None 2160 Response: 2162 "result" with one of the following request-status codes: 2164 2.0 Successful. 2166 6.4 Identity not permitted. 2168 The "identify" command allows the CUA to set a new identity to be 2169 used for calendar access. 2171 The CS determines through an internal mechanism if the credentials 2172 supplied at authentication permit the assumption of the selected 2173 identity. If they do, the session assumes the new identity, 2174 otherwise a security error is returned. 2176 If 2177 Example: 2179 C: MSG 1 7 . 3705 47 2180 C: Content-Type: application/cap+xml 2181 C: 2182 C: 2183 C: END 2185 S: RPY 1 7 . 3752 91 2186 S: Content-Type: application/cap+xml 2187 S: 2188 S: 2189 S: END 2191 6.1.4 "noop" Command 2193 Arguments: 2195 None 2197 Element: 2199 None 2201 Response: 2203 2.0 successful 2205 This command does nothing. It can be sent to the server periodically 2206 to request that the CS does not time out the session. 2208 Example: 2210 C: MSG 1 7 . 3705 47 2211 C: Content-Type: application/cap+xml 2212 C: 2213 C: 2214 C: END 2215 S: RPY 1 7 . 3752 91 2216 S: Content-Type: application/cap+xml 2217 S: 2218 S: 2219 S: END 2221 6.2 Calendaring and Scheduling Commands 2223 6.2.1 Restriction Tables 2225 Calendaring data is sent encapsulated in iCalendar objects The 2226 restriction tables listed in the commands below describe the 2227 composition of the iCalendar data for these commands and replies. 2229 The presence column uses the following values to assert whether a 2230 property is required, is optional and the number of times it may 2231 appear in the iCalendar object. A comment may be provided to further 2232 clarify the presence criteria. 2234 The table below defines the values for the presence column. 2236 Presence 2237 Value Description 2238 -------------------------------------------------------------- 2239 1 One instance MUST be present 2240 1+ At least one instance MUST be present 2241 0 Instances of this property MUST NOT be present 2242 0+ Multiple instances MAY be present 2243 0 or 1 Up to 1 instance of this property MAY be present 2244 -------------------------------------------------------------- 2246 While the tables list every component and property, their purpose is 2247 not to define the meaning of the component or property. 2249 6.2.2 Calendaring Commands 2251 Calendaring commands allow a CUA to directly manipulate a calendar. 2253 Calendar access rights can be granted for the more generalized access 2254 provided by the calendar commands. 2256 There are two kinds of replies. Those that contain an iCalendar 2257 object, and those that do not contain an iCalendar object. 2259 Any reply from the CS that contains an iCalendar object is wrappend 2260 in a and tags. 2262 Any reply from the CS that does not contain an iCalendar object is 2263 returned in a 2409 C: ]]> 2432 C: END 2434 When there are multiple TARGET'values in the original command object 2435 then the replies MUST BE in the exact same order as they were provided 2436 to the CS. The same is true for the objects created, their responses 2437 MUST BE in the exact same order as they were supplied to the CS. 2438 (With the BEEP header and footer removed) 2439 S: Content-Type: text/calendar 2440 S: 2441 S: BEGIN:VCALENDAR 2442 S: VERSION:2.0 2443 S: CMDID:creation01 2444 S: TARGET:cal.example.com 2445 S: TARGET:cal.example.com 2446 S: BEGIN:VAGENDA <- Reply for 1st calendar create 2447 S: RELCALID:relcalz1 2448 S: REQUEST-STATUS:2.0 2449 S: END:VAGENDA 2450 S: BEGIN:VAGENDA <- Reply for 2nd calendar create 2451 S: RELCALID:relcalz2 2452 S: REQUEST-STATUS:2.0 2453 S: END:VAGENDA 2454 S: END:VCALENDAR 2456 To create a new component in multiple containers simply name 2457 all of the containers in the TARGET in the create command. Here 2458 a new VEVENT is created in two TARGETs. In this example, the 2459 VEVENT is one new iTIP REQUEST object in two calendars. The 2460 results would be iCalendar object that conform to the iTIP 2461 replys as defined in iTIP. 2463 C: Content-Type: text/calendar 2464 C: 2465 C: BEGIN:VCALENDAR 2466 C: VERSION:2.0 2467 C: CMDID:creation02 2468 C: METHOD:REQUEST 2469 C: TARGET:relcalz1 2470 C: TARGET:relcalz2 2471 C: BEGIN:VEVENT 2472 C: DTSTART:99990307T180000Z 2473 C: UID:abcd12345 2474 C: DTEND:99990307T190000Z 2475 C: SUMMARY:Important Meeting 2476 C: END:VEVENT 2477 C: END:VCALENDAR 2479 The CS reply can be combined when there is exactly one target. 2480 If a command deposited two METHOD:REQUEST objects into 2481 the same target, this could be the reply. 2483 S: 2484 S: ]]> 2500 S: 2502 6.2.2.2 "move" Command 2504 Attributes: 2506 "cmdid" 2508 Elements: 2510 "max-time": See Section 3.3. 2512 "target": The "target" element points to the container where 2513 the components are to be relocated. 2515 "select": identifies the component(s) to move. 2517 Response: 2519 One "result" message for each "source" in the "select" element 2520 is returned (see Section 3.1). 2522 One of the following "request-status" codes MUST be returned: 2524 2.0 - successfully moved the component or calendar 2526 6.1 - Container not found 2528 6.3 - Bad args 2530 The "data" element of each "result" message is subject to the 2531 result restriction table defined below. 2533 The "move" command is used to move components within the CS's 2534 hierarchy of calendars. The access control on the VAGENDA after it 2535 has been moved to its new location in the calstore hierarchy MUST be 2536 at least as secure as it was prior to the move. One way to 2537 accomplish this is to build a list of VCARs that apply to the VAGENDA 2538 in its old hierarchy and and write them into the VAGENDA before 2539 moving it to its new location. 2541 Restriction Table for "data" element of the "result" response: 2543 Component/Property Presence Comment 2544 ------------------- -------- ------------------------------- 2546 VCALENDAR 1+ 2547 . VERSION 1 MUST be 2.0 2549 . VAGENDA 0+ 2550 . . RELCALID 1 2551 . . REQUEST-STATUS 1+ 2553 . VCAR 0+ 2554 . . CARID 1 2555 . . REQUEST-STATUS 1+ 2557 . VEVENT 0+ 2558 . . UID 1 2559 . . REQUEST-STATUS 1+ 2561 . . VALARM 0 if VEVENT was successfully 2562 saved 2563 1+ if there were errors saving 2564 alarms 2565 . . . ALARMID 1 2566 . . . REQUEST-STATUS 1+ 2568 . VFREEBUSY 0 2570 . VJOURNAL 0+ 2571 . . UID 1 2572 . . REQUEST-STATUS 1+ 2574 . VQUERY 0+ 2575 . . REQUEST-STATUS 1+ 2577 . VTODO 0+ 2578 . . UID 1 2579 . . REQUEST-STATUS 1+ 2580 . . VALARM 0 if VTODO was successfully 2581 saved 2583 1+ if there were errors saving 2584 alarms 2585 . . . ALARMID 1 2586 . . . REQUEST-STATUS 1+ 2588 --------------------------------------------------------- 2590 Example: moving the VAGENDA Nellis to Area-51 2592 C: MSG 1 12 . 11323 613 2593 C: Content-Type: multipart/related; boundary="boundary-kljr"; 2594 C: start="1@cal.example.com"; 2595 C: type="application/beep+xml" 2596 C: 2597 C: --boundary-kljr 2598 C: Content-Type: application/beep+xml 2599 C: Content-ID: 1@cal.example.com 2600 C: 2601 C: 2602 C: 2606 C: 2607 C: 2608 C: --boundary-kljr 2609 C: Content-Type: text/calendar 2610 C: Content-ID: query@cal.example.com 2611 C: 2612 C: BEGIN:VCALENDAR 2613 C: BEGIN:VQUERY 2614 C: QUERY: SELECT * FROM VAGENDA WHERE RELCALID='Nellis' 2615 C: END:VQUERY 2616 C: END:VCALENDAR 2617 C: --boundary-kljr-- 2618 C: END 2619 S: RPY 1 2 . 11936 571 2620 S: Content-Type: multipart/related; boundary="boundary-mnbvd"; 2621 S: start="reply@cal.example.com"; 2622 S: type="application/beep+xml" 2623 S: 2624 S: --boundary-mnbvd 2625 S: Content-Type: application/beep+xml 2626 S: Content-ID: reply@cal.example.com 2627 S: 2628 S: 2629 S: 2630 S: 2631 S: 2632 S: 2633 S: --boundary-mnbvd 2634 S: Content-Type: text/calendar 2635 S: Content-ID: 2@cal.example.com 2636 S: 2637 S: BEGIN:VCALENDAR 2638 S: BEGIN:VAGENDA 2639 S: RELCALID:Nellis 2640 S: REQUEST-STATUS: 2.0 2641 S: END:VAGENDA 2642 S: END:VCALENDAR 2643 S: --boundary-mnbvd-- 2644 S: END 2646 6.2.2.3 "delete" Command 2648 Attributes: 2650 "latency" and "action" (optional see Section xxxx) 2652 Response: 2654 One of the following "request-status" codes MUST be returned 2655 for each target supplied and for each object deleted 2656 as in that target that is effected. 2658 2.0 - successfully deleted the component or calendar 2660 6.1 - Container not found 2662 6.3 - Bad args 2664 The "delete" command is used to delete calendars or components. 2665 The "select" element specifies the container(s) to delete. 2667 Restriction Table for the "delete" command of the "reply" 2668 response. 2670 Component/Property Presence Comment 2671 ------------------- -------- ----------------------------- 2673 VCALENDAR 1+ 2675 . VERSION 1 MUST be at least 2.0 2676 . VAGENDA Only if VAGENDAS were 2677 deleted 2679 . CMDID 0+ MUST BE supplied if it was 2680 supplied in the delete command. 2682 . METHOD 1 MUST BE DELETE 2684 . TARGET 1+ 2686 . REQUEST-STATUS 1 2688 . VCAR 0+ Only if VCAR components were 2689 deleted 2690 . . CARID 1 2691 . . REQUEST-STATUS 1 2693 . VEVENT 0+ Only if VEVENT components 2694 were targets of deletion. 2695 . . UID 1 2696 . . REQUEST-STATUS 0 or 1 Omitted if an embedded VALARM was 2697 the target of the deletion. 2698 . . VALARM 0+ Only if VALARM components 2699 were targets of deletion. 2700 . . . SEQUENCE 1 2701 . . . REQUEST-STATUS 1 2703 . VFREEBUSY 0+ Only if VFREEBUSY was the target 2704 of deletion. 2705 . . UID 1 2706 . . DTSTAMP 1 2707 . . REQUEST-STATUS 1 2709 . VJOURNAL 0+ Only if VJOURNAL components 2710 were targets of deletion. 2711 . . UID 1 2712 . . REQUEST-STATUS 1 2714 . VQUERY 0+ Only if VQUERY components 2715 were targets of deletion. 2716 . UID 1 2717 . REQUEST-STATUS 1 2719 . VTIMEZONE 0+ Only if VTIMEZONE components 2720 . . TZID were targets of deletion. 2721 . . REQUEST-STATUS 1 2723 . VTODO 0+ Only if VTODO components were 2724 targets of deletion. 2725 . . UID 1 2726 . . REQUEST-STATUS 0 or 1 Omitted if an embedded VALARM was 2727 the target of the deletion. 2729 . . VALARM 0+ Only if VALARM components 2730 were targets of deletion. 2731 . . . ALARMID 1 2732 . . . REQUEST-STATUS 1 2734 ---------------------------------------------------------- 2736 Note: If a VAGENDA is deleted then NONE of its contained 2737 components will return any REQUEST-STATUS responses. 2739 Example to delete a VEVENT with VEVENT UID 'abcd12345' from 2740 the calendar "relcald-22" from the current CS: 2742 C: Content-Type: text/calendar 2743 C: 2744 C: BEGIN:VCALENDAR 2745 C: TARGET:relcalid-22 2746 C: METHOD:DELETE 2747 C: CMDID:random but unique per CAU 2748 C: BEGIN:VQUERY 2749 C: QUERY:SELECT * FROM VEVENT WHERE UID = 'abcd12345' 2750 C: END:VQUERY 2751 C: END:VCALENDAR 2753 One or more iCalendar object will be returned that contain 2754 a REQUEST-STATUS for the deleted components. There could have been 2755 more than one component deleted, Any booked and any 2756 number of unprocessed iTIP scheduling components that 2757 matched the QUERY value in the above example. Each 2758 unique METHOD that was deleted from the store MUST BE in a 2759 seperate iCalendar object. This is because only one METHOD is allowed 2760 in an iCalendar object. 2762 6.2.2.4 "modify" Command 2764 Attributes: 2766 "latency" and "action" (Optional - see xxx) 2768 Response: 2770 One of the following "request-status" codes MUST be returned: 2772 2.0 - successfully modified the component or calendar 2774 6.1 - Container not found 2776 6.3 - Bad args 2778 The "modify" command is used to modify existing components. The 2779 TARGET property specifies the calendars were the components 2780 exist that are going to be modified. 2782 The format of the request is three containers inside of VCALENDAR 2783 container object: 2785 BEGIN:VCALEDNAR 2786 2787 2788 2789 END:CALENDAR 2791 The VQUERY selects the components that are to be modified. 2793 The OLD-VALUES is a component and the contents of that component 2794 are going to change and may contain information that helps uniquely 2795 identify the original component (SEQUENCE in the example below). 2796 If the CS can not find a component that matches the QUERY and does 2797 not have at least all of the OLD-VALUES, then a 6.1 error is returned. 2799 The NEW-VALUES is a component of the same type as OLD-VALUES and 2800 NEW-VALUES contains the new data for each selected component. Any 2801 data that is in OLD-VALUES and not in NEW-VALUES is deleted from 2802 the selected component. Any values in NEW-VALUES that was not in 2803 OLD-VALULES is added to the component. 2805 In this example the VEVENT with UID:unique-58 has; the LOCATION and 2806 LAST-MODIFIED changed, the VALARM with SEQUENCE:3 has its 2807 TRIGGER disabled, the X-LOCAL property is removed from the VEVENT, 2808 and a COMMENT is added. 2810 Because SEQUENCE is used to locate the VALARM in this example, 2811 both the OLD-VALUES and the NEW-VALUES contains SEQUENCE:3 and 2812 if SEQUENCE was left out of NEW-VALUES - it would have been deleted. 2814 Example: 2816 C: Content-Type: text/calendar 2817 C: BEGIN:VCALENDAR 2818 C: VERSION:2.0 2819 C: TARGET:my-cal 2820 C: METHOD:MODIFY 2821 C: BEGIN:VQUERY 2822 C: QUERY:SELECT * FROM VEVENT WHERE UID = 'unique-58' 2823 C: END:VQUERY 2824 C: BEGIN:VEVENT 2825 C: LOCATION:building 3 2826 C: LAST-MODIFIED:20020101T123456Z 2827 C: X-LOCAL:some private stuff 2828 C: BEGIN:VALARM 2829 C: SEQUENCE:3 2830 C: TRIGGER;RELATED=END:PT5M 2831 C: END:VALARM 2832 C: END:VEVENT 2833 C: BEGIN:VEVENT 2834 C: LOCATION:building 4 2835 C: LAST-MODIFIED:20020202T010203Z 2836 C: COMMENT:Ignore global trigger. 2837 C: BEGIN:VALARM 2838 C: SEQUENCE:3 2839 C: TRIGGER;ENABLE=FALSE:RELATED=END:PT5M 2840 C: END:VALARM 2841 C: END:VEVENT 2842 C: />]]> 2843 C: 2844 C: END 2846 X-LOCAL was not supplied in the NEW-VALUES, so it was deleted. 2847 LOCATION was altered, as was LAST-MODIFIED. The VALARM with 2848 SEQUENCE:3 had its TRIGGER disabled, and SEQUENCE did not 2849 change so it was not effected. COMMENT was added. 2851 When it comes to inline ATTACHMENTs, the CUA only needs to uniquely 2852 identify the contents of the ATTACHE value in the OLD-VALUES in order 2853 to delete them. When the CS compares the attachment data it is compared 2854 in it binary form. The ATTACHMENT value supplied by the CUA MUST BE 2855 valid encoded information. 2857 For example, to delete a huge inline attachment from every 2858 VEVENT in 'my-cal' that has an ATTACH with the OLD-VALUES: 2860 BEGIN:VCALENDAR 2861 VERSION:2.0 2862 TARGET:my-cal 2863 METHOD:MODIFY 2864 BEGIN:VQUERY 2865 QUERY:SELECT ATTACH FROM VEVENT 2866 END:VQUERY 2867 BEGIN:VEVENT 2868 ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY: 2869 MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U 2870 EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE 2871 ... .... 2872 END:VEVENT 2873 BEGIN:VEVENT 2874 END:VEVENT 2875 END:VCALENDAR 2877 Above the NEW-VALUES is empty, so everything in the OLD-VALUES 2878 is deleted. 2880 Furthermore, the following additional restrictions apply: 2882 One can not change the "UID" property of a component. 2884 If a contained component is changed inside of a selected 2885 component, and that contained component has multiple 2886 instances, then OLD-VALUES MUST contain information that 2887 uniquely identifies the instance or instances that are 2888 changing. 2890 As all contained components that matching OLD-VALUES will be 2891 modified. In the first modify example above, if SEQUENCE were 2892 to be deleted from both the OLD-VALUES and NEW-VALUES, then all 2893 TRIGGERs that matched the OLD-VALUES in all VALARM in the 2894 selected VEVENTs would be disabled. 2896 The result of the modify MUST BE a valid iCalendar object. 2898 If the REQUEST-STATUS is 2.0, then the entire modification was 2899 successful. 2901 If any error occurred: 2903 No component will be changed at all. That is, it will 2904 appear just as it was prior to the modify and the CAP server 2905 SHOULD return a REQUEST-STATUS for each error that occurred. 2907 There MUST BE at least one error reported. 2909 If multiple components are selected, then the UID for each selected 2910 component MUST BE returned if the component contains a UID: 2912 S: Content-Type: text/calendar 2913 S: 2915 S: BEGIN:VCALENDAR 2916 S: TARGET:relcalid 2917 S: BEGIN:VEVENT 2918 S: UID:123 2919 S: REQUEST-STATUS:2.0 2920 S: END:VEVENT 2921 S: END:VCALENDAR 2923 6.2.2.5 "search" Command 2925 Attributes: 2927 "latency" and "action" (Optional - see xxx) 2929 Response: 2931 One iCalendar message per "target" in the "select" element is 2932 returned (see Section xxx). 2934 One of the following "request-status" codes MUST be returned: 2936 2.0 - successfully executed the query 2938 2.0.9 - success, but some data could not be returned 2940 6.1 - Container not found 2942 6.3 - Bad args 2944 The data in each result contains an iCalendar object composed 2945 of all the selected components. Only "REQUEST-STATUS" 2946 and the properties mentioned in the "SELECT" clause of the 2947 QUERY are included in the components. Each iCalendar object is 2948 tagged with the TARGET property and optional CMDID property. 2950 Searching for Events 2952 In the example below events on March 10,1999 between 080000Z and 2953 190000Z are read. In this case only 4 properties for each event are 2954 returned. Two calendars are specified. Only booked (vs scheduled) 2955 entries are to be returned. 2957 NOTE: BEEP headers and footers not included in the examples below. 2959 C: Content-Type: text/calendar 2960 C: 2961 C: BEGIN:VCALENDAR 2962 C: VERSION:2.0 2963 C: METHOD:SEARCH 2964 C: CMDID:search01 2965 C: TARGET:relcal2 2966 C: TARGET:relcal3 2967 C: BEGIN:VQUERY 2968 C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID 2969 C: FROM VEVENT 2970 C: WHERE DTEND >= '19990310T080000Z' 2971 C: AND DTSTART <= '19990310T190000Z' 2972 C: AND METHOD IS 'CREATE' 2973 C: END:VQUERY 2974 C: END:VCALENDAR 2976 S: Content-Type: text/calendar 2977 S: 2978 S: BEGIN:VCALENDAR 2979 S: VERSION:2.0 2980 S: METHOD:REPLY 2981 S: TARGET:relacal2 2982 S: CMDID:search01 2983 S: REQUEST-STATUS:2.0 2984 S: BEGIN:VEVENT 2985 S: DTSTART:19990310T090000Z 2986 S: DTEND:19990310T100000Z 2987 S: UID:abcxyz12345 2988 S: SUMMARY:Meet with Sir Elton 2989 S: REQUEST-STATUS:2.0 2990 S: END:VEVENT 2991 S: BEGIN:VEVENT 2992 S: DTSTART:19990310T130000Z 2993 S: DTEND:19990310T133000Z 2994 S: UID:abcxyz8999 2995 S: SUMMARY:Meet with brave Sir Robin 2996 S: REQUEST-STATUS:2.0 2997 S: END:VEVENT 2998 S: END:VCALENDAR 3000 S: Content-Type: text/calendar 3001 S: 3002 S: BEGIN:VCALENDAR 3003 S: VERSION:2.0 3004 S: METHOD:REPLY 3005 S: CMDID:search01 3006 S: TARGET:relcal3 3007 S: REQUEST-STATUS:2.0 3008 S: BEGIN:VEVENT 3009 S: REQUEST-STATUS:2.0 3010 S: DTSTART:19990310T140000Z 3011 S: DTEND:19990310T150000Z 3012 S: UID:123456asdf 3013 S: SUMMARY:Summer Budget 3014 S: REQUEST-STATUS:2.0 3015 S: END:VEVENT 3016 S: END:VCALENDAR 3018 The return values are subject to VCAR filtering. That is, if the 3019 request contains properties to which the UPN does not have access, 3020 those properties will not appear in the return values. If the UPN 3021 has access to at least one property of the component, but has been 3022 denied access to all properties called out in the request, the 3023 response will contain a single REQUEST-STATUS property indicating the 3024 error. That is, the VEVENT components will be the following: 3026 Here the request was successful, but the VEVENT contents 3027 were not accessable (4.1). 3029 S: Content-Type: text/calendar 3030 S: 3031 S: BEGIN:VCALENDAR 3032 S: METHOD:REPLY 3033 S: TARGET:relcalid 3034 S: CMIDID=any-id 3035 S: VERSION:2.0 3036 S: BEGIN:VEVENT 3037 S: REQUEST-STATUS:4.1 3038 S: END:VEVENT 3039 S: END:VCALENDAR 3041 If the UPN has no access to any components at all, the response will 3042 simply be an empty data set. The response looks the same if there 3043 the particular components did not exist. 3045 S: Content-Type: text/calendar 3046 S: 3047 S: BEGIN:VCALENDAR 3048 S: VERSION:2.0 3049 S: METHOD:REPLY 3050 S: CMDID:some-id 3051 S: TARGET:ralcalid 3052 S: REQUEST-STATUS:2.0 3053 S: END:VCALENDAR 3055 Find alarms within a range of time for booked VEVENTs. 3057 C: Content-Type: text/calendar 3058 C: 3059 C: BEGIN:VCALENDAR 3060 C: VERSION:2.0 3061 C: METHOD:SEARCH 3062 C: TARGET:"Doug:Baseball" 3063 C: TARGET:"Steve:Baseball" 3064 C: CMDID:search02 3065 C: BEGIN:VQUERY 3066 C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID,VALARM 3067 C: FROM VEVENT,VTODO 3068 C: USING_COMPONENT VALARM my-alarm 3069 C: WHERE my-alarm.TRIGGER >= '19990310T080000Z' 3070 C: AND my-alarm.TRIGGER <= '19990310T190000Z' 3071 C: AND METHOD = 'CREATE' 3072 C: END:VQUERY 3073 C: END:VCALENDAR 3075 Here no data was returned for relcal2: 3077 S: Content-Type: text/calendar 3078 S: 3079 S: BEGIN:VCALENDAR 3080 S: VERSION:2.0 3081 S: TARGET:relcal2 3082 S: CMDID:search02 3083 S: METHOD:REPLY 3084 S: REQUEST-STATUS:X.Y <- todo 3085 S: END:VCALENDAR 3087 And here relcal3 did return some resuls: 3089 S: Content-Type: text/calendar 3090 S: 3091 S: BEGIN:VCALENDAR 3092 S: VERSION:2.0 3093 S: METHOD:REPLY 3094 S: TARGET:relcal3 3095 S: CMDID:search02 3096 S: REQUEST-STATUS:2.0 3097 S: BEGIN:VEVENT 3098 S: DTSTART:19990310T130000Z 3099 S: DTEND:19990310T133000Z 3100 S: UID:abcxyz8999 3101 S: SUMMARY:Meet with brave Sir Robin 3102 S: BEGIN:VALARM 3103 S: TRIGGER:19990310T132500Z 3104 S: SUMMARY:Almost time... 3106 S: ACTION:DISPLAY 3107 S: END:VALARM 3108 S: END:VEVENT 3109 S: END:VCALENDAR 3111 In this example bill@example.com reads a day's worth of events from 3112 cap://cal.example.com/opaqueid99. And the optional cmdid is not 3113 supplied as the CUA will not issue another command until this 3114 one completes. 3116 C: BEGIN:VCALENDAR 3117 C: VERSION:2.0 3118 C: METHOD:SEARCH 3119 C: TARGET:opaqueid99 3120 C: BEGIN:VQUERY 3121 C: QUERY:SELECT DTSTART,DTEND,SUMMARY, UID FROM VEVENT 3122 C: WHERE DTEND >= '19990714T080000Z' 3123 C: AND DTSTART <= '19990715T080000Z' 3124 C: END:VQUERY 3125 C: END:VCALENDAR 3127 If there are multiple targets, each iCalendar reply is contained 3128 within its own . 3130 Stored VQUERY can be used by specifying the property QUERYID 3131 instead of QUERY. 3133 This matches all calendar store properties. This MUST NOT return any 3134 VAGENDAs. IT would return all RELATED-TO properties. 3136 BEGIN:VCALENDAR 3137 VERSION:2.0 3138 METHOD:SEARCH 3139 TARGET:cap://bobo.ex.com 3140 BEGIN:VQUERY 3141 QUERY:SELECT * FROM VCALSTORE 3142 END:VQUERY 3143 END:VCALENDAR 3145 This will match all properties of the VAGENDA relcal4. This MUST NOT 3146 return any components. 3148 BEGIN:VCALENDAR 3149 VERSION:2.0 3150 METHOD:SEARCH 3151 TARGET:cap://bobo.ex.com/relcal4 3152 BEGIN:VQUERY 3153 QUERY:SELECT * FROM VAGENDA 3154 END:VQUERY 3155 END:VCALENDAR 3157 This will fetch all stored VQUERYs. All stored queries MUST BE 3158 saved with a QUERYID. 3160 BEGIN:VCALENDAR 3161 VERSION:2.0 3162 METHOD:SEARCH 3163 TARGET:relcal4 3164 BEGIN:VQUERY 3165 QUERY:SELECT VQUERY.* FROM VQUERY. 3166 END:VQUERY 3167 END:VCALENDAR 3169 6.2.2.6 Response Codes 3171 Numeric response codes are returned at both the transfer and 3172 application layer. The same set of codes is used in both cases. 3174 The format of these codes is described in [RFC2445], and extend in 3175 [iTIP] and [iMIP]. The following describes new codes added to this 3176 set. 3178 At the application layer response codes are returned as the value of 3179 a "REQUEST-STATUS" property. The value type of this property is 3180 modified from that defined in [RFC2445], to make the accompanying 3181 text optional. 3183 Code Description 3184 -------------------------------------------------------------- 3185 2.0 Success. The parameters vary with the 3186 operation and are specified. 3188 2.0.3 In response to the client issuing an 3189 "abort" reply, this reply code indicates 3190 that any command currently underway was 3191 successfully aborted. 3193 2.0.9 Success of the read operation, but some 3194 requested information could not be returned 3195 due to access control. 3197 3.1.4 Capability not supported. 3199 4.1 Calendar store access denied. 3201 6.3 Attempt to create or modify an event 3202 such that it would overlap another event 3203 in either of the following two circum- 3204 stances: 3206 (a) One of the events has a TRANSP 3207 property set to OPAQUE-NOCONFLICT or 3208 TRANSPARENT-NOCONFLICT. 3210 (b) The calendar's ALLOW-CONFLICT 3211 property is set to NO. 3213 6.XXX [EDITORS NOTE: More are in this memo - 3214 add here TODO] 3216 7.0 A timeout has occurred. The server was 3217 unable to complete the operation in the 3218 requested time. 3220 8.0 A failure has occurred in the Calendar Service 3221 that prevents the operation from 3222 succeeding. 3224 8.2 Used to signal that an iCalendar object has 3225 exceeded the server's size limit 3227 8.3 A DATETIME value was too far in the future 3228 represented on this Calendar. 3230 8.4 A DATETIME value was too far in the past 3231 to be represented on this Calendar. 3233 8.5 An attempt was made to create a new 3234 object but the unique id specified is 3235 already in use. 3237 9.0 An unrecognized command was received. 3239 10.4 The operation has not been performed 3240 because it would cause the resources 3241 (memory, disk, CPU, etc) to exceed the 3242 allocated quota. 3243 -------------------------------------------------------------- 3245 7. Initial Registrations 3247 7.1 BEEP Profile Registration 3249 Profile Identification: http://iana.org/beep/transient/calsch/ 3250 cap/1.0 3252 Messages exchanged during Channel Creation: none 3254 Messages starting one-to-one exchanges: 3256 "timeout", "generate-uid", "identify", "get-capability" 3258 Messages in positive replies: 3260 "uid-list", "abort", "continue", "result", "capability" 3262 Messages in negative replies: 3264 "error" 3266 Messages in one-to-many exchanges: "create", "search", 3267 "delete", "modify" or "schedule" 3269 Message Syntax: c.f., Section 8 3271 Message Semantics: c.f., Section 6 3273 Contact Information: c.f., the "Author's Address" section of 3274 this memo 3276 7.2 Registration: The System (Well-Known) TCP port number for CAP 3278 A single well-known port (xxxx) is allocated to CAP. 3280 Protocol Number: 3282 TCP 3284 Message Formats, Types, Opcodes, and Sequences: 3286 Section 8 3288 Functions: 3290 Section 6 3292 Use of Broadcast/Multicast: 3294 none 3296 Proposed Name: 3298 Calendar Access Protocol 3300 Short name: 3302 cap 3304 Contact Information: 3306 cf., the "Authors' Addresses" section of this draft 3308 8. CAP DTD 3310 To Be Done. 3312 9. Properties 3314 [Once definitions are in iCalendar format and are agreed on, should 3315 be moved into section "Extension to iCalendar"] 3317 9.1 Calendar Store Properties 3319 The following are properties of the calendar store. 3321 Name Read Value Description 3322 Only Type 3323 -------------------------------------------------------------- 3324 CALMASTER N URI URL of contact address for person 3325 responsible. SHOULD BE 3326 mailto URL. 3328 CSID Y URI The CSID of this calendar 3329 store. If not specified, it is 3330 the same as the hostname. 3332 DEFAULT_VCARS N TEXT A multivalued property 3333 containing the default VCARs 3334 for newly created top level 3335 calendars. Each entry is a 3336 CARID. It MUST include at a 3337 minimum 3338 READBUSYTIMEINFO,REQUESTONLY, 3339 UPDATEPARTSTATUS, and 3340 DEFAULTOWNER. 3342 MAXDATE Y DATE-TIME The date/time in the future 3343 beyond which the server cannot 3344 represent. If not specified, 3345 then 99991231T235959 will be 3346 assumed. 3348 MINDATE Y DATE-TIME The date/time in the past prior 3349 to which the server cannot 3350 represent. If not specified, 3351 then 00000101T000000 will be 3352 assumed. 3354 CURRENT_DATETIME Y DATE-TIME Current server time. This is 3355 returned as a local time and 3356 TZID. 3358 RECUR_ACCEPTED Y BOOLEAN Boolean value will be set to 3359 TRUE if the server will accept 3360 recurrence rules. It will be 3361 set to FALSE if the server will 3362 not accept recurrence rules. If 3363 not specified a CUA MUST assume 3364 TRUE. 3366 RECUR_EXPAND Y BOOLEAN If set to TRUE, the CS supports 3367 the expansion of recurrence 3368 rules in the returned set. If set 3369 to FALSE, the CS is incapable 3370 of expanding recurrence rules. 3371 If not specified a CUA MUST assume 3372 TRUE. 3374 RECUR_LIMIT Y INTEGER This numeric value describes 3375 how the server handles 3376 unbounded recurrences. The 3377 value is only valid if 3378 RECURRENCE is TRUE. If the 3379 value is 0 it means that the 3380 server supports unbounded 3381 recurrence rules. If it is non- 3382 zero, it is a positive integer 3383 indicating the number of 3384 instances that will be returned 3385 when the server expands an 3386 unbounded recurrence rule when 3387 fetched from the CS. A CUA MUST 3388 query for date ranges when this 3389 value is zero. 3391 VERSION Y TEXT The version of the CS. The 3392 default and the only currently 3393 Supported version is "2.0" to 3394 match the [RFC2445] VERSION. 3396 9.2 Calendar Properties 3398 Name Read Value Description 3399 Only Type 3400 -------------------------------------------------------------- 3401 ALLOW-CONFLICT N BOOLEAN This boolean value indicates 3402 Whether or not the calendar 3403 supports event conflicts. That 3404 is, whether or not any of the 3405 events in the calendar can 3406 overlap. If not specified the 3407 default value is TRUE meaning 3408 that conflicts are allowed. 3410 CALSCALE N TEXT The CALSCALE for this calendar. 3411 If not specified the default is 3412 GREGORIAN. 3414 CHARSET N TEXT The default charset for 3415 Localized strings in this 3416 calendar. If not specified, the 3417 default is UTF-8. 3419 CHILD Y TEXT A sub-calendars belonging to this 3420 calendar. A calendar may have 3421 multiple sub-calendars, each one 3422 corresponding to a CHILD property. 3424 CREATED Y DATE-TIME The timestamp of the calendar's 3425 create date. 3427 DEFAULT_VCARS N TEXT The default VCARs for newly 3428 Created top level calendars. 3429 This is a CARID. The default 3430 value is the value of 3431 DEFAULT_VCARS in the VCALSTORE 3432 table. 3434 LANGUAGE N TEXT The default language for 3435 localizable strings in this 3436 calendar. There is no default. 3437 This value MUST NOT be empty. 3438 The possible values of this 3439 property are those specified in 3440 RFC-3066. 3442 LAST-MODIFIED N DATE-TIME The timestamp when the 3443 Properties of the calendar were 3444 last updated. Default is the 3445 same as CREATED. 3447 NAME N TEXT The display name for this 3448 calendar. It is a localizable 3449 string. If not provided, an 3450 empty value will be returned. 3452 OWNER N URI A multi-instanced property 3453 indicating the calendar owner. 3454 Each entry returned will be a 3455 UPN. There must be at least one 3456 owner. 3458 PARENT N URI The CALID of this calendar's 3459 Parent maintained by a CAP 3460 server. An empty value means 3461 the calendar is the top level 3462 parent. The default value is no 3463 parent. 3465 RELCALID N URI A unique identifier within this 3466 cal-store for the calendar. 3467 There is no default value. 3468 This value MUST NOT be empty. 3470 TOMBSTONE N BOOLEAN TRUE indicator that this 3471 Calendar has been marked as 3472 deleted. The default value is 3473 FALSE. 3475 TZID N TEXT The id of the timezone 3476 Associated with this calendar. 3477 See TZID in [RFC2445]. The default 3478 value is UTC. 3480 10. Security Considerations 3482 Access rights should be granted cautiously, consult Section 2.4.2 for 3483 a discussion of the subject. 3485 The "identify" command should be carefully implemented as discussed 3486 in Section 6.1.3. 3488 In addition, since CAP is a profile of the BEEP, consult [BEEP]'s 3489 Section 9 for a discussion of BEEP-specific security issues. 3491 Although service provisioning is a policy matter, at a minimum, all 3492 implementations must provide the following tuning profiles: 3494 for authentication: http://iana.org/beep/SASL/DIGEST-MD5 3496 for confidentiality: http://iana.org/beep/TLS (using the 3497 TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher) 3499 for both: http://iana.org/beep/TLS (using the 3500 TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher supporting client-side 3501 certificates) 3503 11. Extensions To iCalendar 3505 The following section contains new components, properties, 3506 parameters, and values. 3508 11.1 Property Value Data Types 3510 11.1.1 UPN 3512 To: ietf-calendar@imc.org 3514 Subject: Registration of text/calendar MIME value type UPN 3516 Value Name: UPN 3518 Purpose: This value type is used to identify values that contain user 3519 principal name of CU or group of CU. 3521 Formal Definition: The value type is defined by the following 3522 notation: 3524 upn = "@" / 3525 [ dot-atom-text ] "@" dot-atom-text 3527 ; dot-atom-text is defined in RFC 2822 3529 Description: This data type is an identifier that denotes a CU or a 3530 group of CU. A UPN is a RFC 2822 compliant e-mail address, with 3531 exceptions listed below, and in most cases it is deliverable to the 3532 CU. In some cases it is identical to the CU's well known email 3533 address. A CU's UPN MUST never be an e-mail address that is 3534 deliverable to a different person as there is no requirement that a 3535 person's UPN must be his e-mail address. 3537 In certain cases a UPN will not be RFC 2822 compliant. When 3538 anonymous authentication is used, or anonymous authorization is being 3539 defined, the special UPN "@" will be used. When authentication must 3540 be used, but unique identity must be obscured, a UPN of the form 3541 @DNS-domain-name may be used. 3543 Example: 3545 The following is a UPN for a CU: 3547 jdoe@acme.com 3549 The following is a UPN for a group of CU: 3551 staff@acme.com 3553 The following is a UPN for an anonymous CU belonging to 3555 @acme.com 3557 The following is a UPN for an anonymous CU: 3559 @ 3561 11.1.2 UPN Filter 3563 To: ietf-calendar@imc.org 3565 Subject: Registration of text/calendar MIME value type UPN-FILTER 3567 Value Name: UPN-FILTER 3569 Purpose: This value type is used to identify values that contain a 3570 user principal name filter. 3572 Formal Definition: The value type is defined by the following 3573 notation: 3575 upn-filter = "OWNER" / 3576 "NONOWNER" / 3577 "*" / 3578 [ "*" / dot-atom-text ] "@" ( "*" / dot-atom-text ) 3580 ; dot-atom-text is defined in RFC 2822 3582 Description: The value is used to match user principal names (UPNs). 3584 Example: The following are examples of this value type: 3586 OWNER Matches the UPNs equal to any instance 3587 of the OWNER property of the VAGENDA in 3588 which the encapsulating VCAR is stored. 3590 NONOWNER Matches all UPNs different from all 3591 instances of the OWNER property of the 3592 VAGENDA in which the encapsulating VCAR 3593 is stored. 3595 * Matches all UPNs. 3597 @ Matches the UPN of anonymous CUs 3598 belonging to the null realm 3600 @* Matches the UPN of anonymous CUs 3601 belonging to any non-null realm 3603 @realm Matches the UPN of anonymous CUs 3604 belonging to the specified realm 3606 *@* Matches the UPN of non-anonymous CUs 3607 belonging to any non-null realm 3609 *@realm Matches the UPN of non-anonymous CUs 3610 belonging to the specified realm 3612 user@realm Matches the UPN of the specified CU 3613 belonging to the specified realm 3615 user@* Matches the UPN of the specified CU 3616 belonging to any non-null realm 3618 11.2 Calendar Components 3620 11.2.1 Agenda Component 3622 To: ietf-calendar@imc.org 3624 Subject: Registration of text/calendar MIME component VAGENDA 3626 Component Name: VAGENDA 3628 Purpose: Provide a grouping of component properties that defines an 3629 agenda. 3631 Formal Definition: A "VAGENDA" calendar component is defined by the 3632 following notation: 3634 agendac = "BEGIN" ":" "VAGENDA" CRLF 3635 agendaprop 3636 "END" ":" "VAGENDA" CRLF 3638 agendaprop = *( 3639 ; the following MUST occur exactly once 3641 created / recalid / last-mod / 3643 ; the following MUST occur at least once 3644 owner / 3646 ; the following are optional, 3647 ; but MUST NOT occur more than once 3649 allow-conflict / calscale / default-charset / default-locale / 3650 method / default-tzid / 3652 ; the following are optional, 3653 ; and MAY occur more than once 3655 name / related / iana-token / x-prop / x-comp 3656 ) 3658 Example: The following is an example of this component: 3660 BEGIN:VAGENDA 3661 CREATED:20020121T123149Z 3662 NAME:Work Calendar 3663 OWNER:john@example.calendar.com 3664 RECALID:lhdi98dey6 3665 LAST-MODIFIED:20020210T152301Z 3666 ALLOW-CONFLICT:FALSE 3667 METHOD:DELETE 3668 END:VAGENDA 3670 11.2.2 Calendar Store Component 3672 To: ietf-calendar@imc.org 3674 Subject: Registration of text/calendar MIME component VCALSTORE 3676 Component Name: VCALSTORE 3678 Purpose: Provide a grouping of component properties that defines a 3679 calendar store. 3681 Formal Definition: A "VCALSTORE" calendar component is defined by the 3682 following notation: 3684 calstorec = "BEGIN" ":" "VCALSTORE" CRLF 3685 calstoreprop 3686 "END" ":" "VCALSTORE" CRLF 3688 calstoreprop = *( 3689 ; the following MUST occur exactly once 3690 calmaster / current-datetime / 3692 ; the following must occur at least once 3694 default-vcar / 3696 ; the following are optional, 3697 ; but MUST NOT occur more than once 3699 maxdate / mindate / recur-accepted / recur-expand / 3700 recur-limit / csid / 3702 ; the following are optional, 3703 ; and MAY occur more than once 3705 iana-token / x-prop / x-comp / vcard 3706 ) 3708 Example: The following is an example of this component: 3710 BEGIN:VCALSTORE 3711 CALMASTER:mailto:admin@example.calendar.com 3712 DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY 3713 DEFAULT-VCARS:UPDATEPARTSTATUS,DEFAULTOWNER 3714 CSID:example.calendar.com 3715 END:VCALSTORE 3717 11.2.3 Calendar Access Right Component 3719 To: ietf-calendar@imc.org 3721 Subject: Registration of text/calendar MIME component VCAR 3723 Component Name: "VCAR" 3725 Purpose: Provide a grouping of calendar access rights. 3727 Format Definition: A "VCAR" calendar component is defined by the 3728 following notation: 3730 carc = "BEGIN" ":" "VCAR" CRLF 3731 carprop 1*rightc 3732 "END" ":" "VCAR" CRLF 3734 carprop = 1*( 3735 ; 'carid' is REQUIRED, 3736 ; but MUST NOT occur more than once 3738 carid / 3740 ; the following are OPTIONAL, 3741 ; and MAY occur more than once 3743 name / x-prop / iana-prop 3744 ) 3746 Description: A "VCAR" calendar component is a grouping of component 3747 properties, and "VRIGHT" calendar components, that represents access 3748 rights granted or denied to calendar users. 3750 The "CARID" property specifies the local identifier for the "VCAR" 3751 calendar component. The "NAME" property specifies a localizable 3752 display name. 3754 Example: In the following example, the UPN "foo@host.com" is given 3755 read access to the "DTSTART" and "DTEND" VEVENT properties. No other 3756 access is specified: 3758 BEGIN:VCAR 3759 CARID:xyzzy-001 3760 NAME:View Start and End Times 3761 BEGIN:VRIGHT 3762 GRANT:foo@host.com 3763 PERMISSION:READ 3764 SCOPE:SELECT DTSTART,DTEND FROM VEVENT 3765 END:VRIGHT 3766 END:VCAR 3768 In this example, all UPNs are given read access to "DTSTART" and 3769 "DTEND" properties of VEVENT components. "All CUs and UGs" are 3770 specified by the UPN value "*". Note that this enumerated UPN value 3771 is not in quotes: 3773 BEGIN:VCAR 3774 CARID:xyzzy-002 3775 NAME:View Start and End Times 2 3776 BEGIN:VRIGHT 3777 GRANT:* 3778 PERMISSION:READ 3779 SCOPE:SELECT DTSTART,DTEND FROM VEVENT 3780 END:VRIGHT 3781 END:VCAR 3783 In this example, rights are specified for all UPNs to read VEVENT 3784 components classified as PUBLIC: 3786 BEGIN:VCAR 3787 CARID:xyzzy-003 3788 NAME:View PUBLIC Start and End Times 3789 BEGIN:VRIGHT 3790 GRANT:* 3791 PERMISSION:READ 3792 SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC' 3793 END:VRIGHT 3794 END:VCAR 3796 In this example, rights are specified for all UPNs to read or modify 3797 existing VEVENT components classified as PUBLIC: 3799 BEGIN:VCAR 3800 CARID:xyzzy-004 3801 NAME:Read and Modify PUBLIC Calendar Entries 3802 BEGIN:VRIGHT 3803 GRANT:* 3804 PERMISSION:READ 3805 PERMISSION:MODIFY 3806 SCOPE:SELECT * FROM VEVENT WHERE CLASS = 'PUBLIC' 3807 END:VRIGHT 3808 END:VCAR 3810 In these examples, full calendar access rights are given to the 3811 OWNER, and a hypothetical administrator is given access rights to 3812 specify calendar access rights. If no other rights are specified, 3813 only these two UPNs can specify calendar access rights: 3815 BEGIN:VCAR 3816 CARID:xyzzy-005 3817 NAME:Only OWNER or ADMIN Settable CARs 3818 BEGIN:VRIGHT 3819 GRANT:OWNER 3820 PERMISSION:* 3821 SCOPE:SELECT * FROM VAGENDA 3822 END:VRIGHT 3823 BEGIN:VRIGHT 3824 GRANT:cal-admin@host.com 3825 PERMISSION:* 3826 SCOPE:SELECT * FROM VCAR 3827 RESTRICTION:SELECT * FROM VCAR 3828 END:VRIGHT 3829 END:VCAR 3831 In this example, rights to write, read, modify or delete calendar 3832 access rights are denied to all UPNs. This example would disable 3833 providing different access rights to the calendar store or calendar. 3834 This calendar access right should be specified with great care, as it 3835 remove the ability to change calendar access; even for the owner or 3836 administrator: 3838 BEGIN:VCAR 3839 CARID:xyzzy-006 3840 NAME:No CAR At All 3841 BEGIN:VRIGHT 3842 DENY:* 3843 PERMISSION:* 3844 SCOPE:SELECT * FROM VCAR 3845 END:VRIGHT 3846 END:VCAR 3848 11.2.4 VRIGHT Calendar Component 3850 To: ietf-calendar@imc.org 3852 Subject: Registration of text/calendar MIME component VRIGHT 3854 Component Name: "VRIGHT" 3856 Purpose: Provide a grouping of component properties that describe an 3857 access right. 3859 Format Definition: A "VRIGHT" calendar component is defined by the 3860 following notation: 3862 rightc = "BEGIN" ":" "VRIGHT" CRLF 3863 rightprop 3864 "END" ":" "VRIGHT" CRLF 3866 rightprop = 2*( 3868 ; either 'grant' or 'deny' MUST 3869 ; occur at least once 3870 ; and MAY occur more than once 3872 grant / deny / 3874 ; 'permission' MUST occur at least once 3875 ; and MAY occur more than once 3877 permission / 3878 ; the following are optional, 3879 ; and MAY occur more than once 3881 scope / restriction / x-prop / iana-prop 3883 ) 3885 Description: A "VRIGHT" calendar component is a grouping of calendar 3886 access right component properties. 3888 The "GRANT" property specifies the CU or UG to whom a calendar access 3889 right is granted. The "DENY" property specifies the CU or UG to whom 3890 a calendar access right is denied. The "PERMISSION" property 3891 specifies the actual permission being set. The "SCOPE" property 3892 identifies the calendar store properties, calendar properties, 3893 calendar components, component properties to which the access right 3894 applies. The "RESTRICTION" property specifies restriction on the 3895 value that may take calendar store properties, calendar properties, 3896 calendar components, and component properties after a WRITE or MODIFY 3897 operation. Values MUST match all the instances of the RESTRICTION 3898 property to be valid. 3900 11.3 Component Properties 3902 The following properties can appear within calendar components, as 3903 specified by each component property definition. 3905 11.3.1 Allow-Conflict Component Property 3907 To: ietf-calendar@imc.org 3909 Subject: Registration of text/calendar MIME property ALLOW-CONFLICT 3911 Property Name: ALLOW-CONFLICT 3913 Purpose: This property indicates whether or not the calendar supports 3914 component conflicts. That is, whether or not any of the components 3915 in the calendar can overlap. 3917 Value Type: BOOLEAN 3919 Property Parameters: Non-standard property parameters can be 3920 specified on this property. 3922 Conformance: This property can be specified in "VAGENDA" calendar 3923 component. 3925 Description: In a "VAGENDA", this property is used to indicate 3926 whether components may conflict. That is, if their expanded 3927 instances may share the same time or overlap the same time periods. 3928 If it has a value of TRUE, then conflicts are allowed. If FALSE, the 3929 no two components may conflict. 3931 Format Definition: The property is defined by the following notation: 3933 allow-conflict = "ALLOW-CONFLICT" allowconflictparam ":" boolean 3934 CRLF 3936 allowconflictvalue = *(";" xparam) 3938 Example: The following is an example of this property for a "VAGENDA" 3939 calendar component: 3941 ALLOW-CONFLICT:FALSE 3943 11.3.2 Charset Component Property 3945 To: ietf-calendar@imc.org 3947 Subject: Registration of text/calendar MIME property DEFAULT-CHARSET 3949 Property Name: DEFAULT-CHARSET 3951 Purpose: This property indicates the default charset for localized 3952 strings. 3954 Value Type: TEXT 3956 Property Parameters: Non-standard property parameters can be 3957 specified on this property. 3959 Conformance: This property can be specified in "VAGENDA" calendar 3960 component. 3962 Description: In a "VAGENDA", this property is used to indicate the 3963 charset of the localized strings of all its components. If not 3964 specified, the default is UTF-8. The value MUST be an IANA 3965 registered character set as defined in [RFC 2278]. 3967 Format Definition: The property is defined by the following notation: 3969 default-charset = "DEFAULT-CHARSET" default-charsetparam ":" text CRLF 3971 default-charsetparam = *(";" xparam) 3973 Example: The following is an example of this property for a "VAGENDA" 3974 calendar component: 3976 DEFAULT-CHARSET:Shift_JIS 3978 11.3.3 Default Locale Component Property 3980 To: ietf-calendar@imc.org 3982 Subject: Registration of text/calendar MIME property DEFAULT-LOCALE 3984 Property Name: DEFAULT-LOCALE 3986 Purpose: This property specifies the default language for text 3987 values. 3989 Value Type: TEXT 3991 Property Parameters: Non-standard property parameters can be 3992 specified on this property. 3994 Conformance: This property can be specified in "VAGENDA" calendar 3995 component. 3997 Description: In a "VAGENDA", this property is used to indicate the 3998 default locale for values in the components, e.g., "VEVENT", of the 3999 "VAGENDA." The full locale SHOULD be used. The default and minimum 4000 locale is POSIX, if not supplied in the UTF-8 charset as defined in 4001 RFC 2277. 4003 Format Definition: The property is defined by the following notation: 4005 default-locale = "DEFAULT-LOCALE" default-localeparam ":" language CRLF 4007 default-localeparam = *(";" xparam) 4009 default-locale = Text identifying a locale, as defined in [RFC 2277] 4011 Example: The following is an example of this property: 4013 DEFAULT-LOCALE:en-US.iso-8859-1 4015 11.3.4 Default Time Zone Property 4017 Property Name: DEFAULT-TZID 4018 Purpose: This property specifies the text value that specifies the 4019 default time zone for a calendar. 4021 Value Type: TEXT 4023 Property Parameters: Non-standard property parameters can be 4024 specified on this property. 4026 Conformance: This property may be specified once in a "VAGENDA" 4027 calendar component. 4029 Description: This is the label by which the default time zone for a 4030 calendar is specified. The default is used for all TIME and DATE- 4031 TIME properties, in the calendar, that do not have a timezone nor are 4032 in UTC. The presence of the SOLIDUS character (US-ASCII decimal 47) 4033 as a prefix, indicates that this TZID represents an unique ID in a 4034 globally defined time zone registry (when such registry is defined). 4036 Format Definition: This property is defined by the following 4037 notation: 4039 default-tzid = "DEFAULT-TZID" default-tzidpropparam ":" [tzidprefix] text CRLF 4041 default-tzidpropparam = *(";" xparam) 4043 Example: The following is an example of this property: 4045 DEFAULT-TZID:US-Eastern 4047 11.3.5 Owner Component Property 4049 To: ietf-calendar@imc.org 4051 Subject: Registration of text/calendar MIME property OWNER 4053 Property Name: OWNER 4055 Purpose: The property specifies an owner of a calendar. 4057 Value Type: UPN 4059 Property Parameters: Non-standard, alternate text representation and 4060 language property parameters can be specified on this property. 4062 Conformance: The property MUST be specified at in a "VAGENDA" 4063 component. 4065 Description: A multi-instanced property indicating the calendar 4066 owner. 4068 Format Definition: The property is defined by the following notation: 4070 owner = "OWNER" ownerparam ":" upn CRLF 4072 ownerparam = *(";" xparam) 4074 Example: The following is an example of this property: 4076 OWNER:jsmith@acme.com 4077 OWNER:jdoe@acme.com 4079 11.3.6 Relative Calendar Identifier Component Property 4081 To: ietf-calendar@imc.org 4083 Subject: Registration of text/calendar MIME property RELCALID 4085 Property Name: RELCALID 4087 Purpose: The property specifies an identifier for a "VAGENDA." It 4088 must be unique within the CS. 4090 Value Type: URI 4092 Property Parameters: Non-standard, alternate text representation and 4093 language property parameters can be specified on this property. 4095 Conformance: The property MUST be specified in a "VAGENDA" component. 4097 Description: The parameter value MUST be a UTF-8 string. It MUST NOT 4098 be empty. 4100 Format Definition: The property is defined by the following notation: 4102 recalidprop = "RELCALID" recalidparam ":" relcalid CRLF 4104 [EDITORS NOTE: recalid is defined in Bernard's proposition for the definition of a CAP URL] 4106 recalidparam = *(";" xparam) 4108 Example: The following is an example of this property: 4110 RELCALID:hjik123A001 4112 11.3.7 Calendar Store Component Properties 4114 11.3.7.1 Calmaster Component Property 4116 To: ietf-calendar@imc.org 4118 Subject: Registration of text/calendar MIME property CALMASTER 4120 Property Name: CALMASTER 4122 Purpose: The property specifies an e-mail address of a person 4123 responsible for the calendar store. 4125 Value Type: URI 4127 Property Parameters: Non-standard property parameters can be 4128 specified on this property. 4130 Conformance: The property can be specified in a "VCALSTORE" 4131 component. 4133 Description: The parameter value MUST be a MAILTO URI as defined in 4134 [RFC 1738]. 4136 Format Definition: The property is defined by the following notation: 4138 calmaster = "CALMASTER" calmasterparam ":" uri CRLF 4140 calmasterparam = *(";" xparam) 4142 uri = as defined by RFC 2445 4144 Example: The following is an example of this property: 4146 CALMASTER:mailto:administrator@acme.com 4148 11.3.7.2 Calendar Store Identifier Component Property 4150 To: ietf-calendar@imc.org 4152 Subject: Registration of text/calendar MIME property CSID 4154 Property Name: CSID 4156 Purpose: The property specifies a the globally unique identifier for 4157 the calendar store. 4159 Value Type: URI 4161 Property Parameters: Non-standard property parameters can be 4162 specified on this property. 4164 Conformance: The property can be specified in a "VCALSTORE" 4165 component. 4167 Description: The identifier MUST be globally unique. If not 4168 specified, it is the same as the hostname. 4170 Format Definition: The property is defined by the following notation: 4172 csid = "CSID" csidparam ":" capurl CRLF 4174 [EDITORS NOTE: capurl is defined in Bernard's proposition for the definition of a CAP URL] 4176 csidparam = *(";" xparam) 4178 Example: The following is an example of this property: 4180 CSID:cap://calendar.acme.com 4182 11.3.7.3 Default Access Rights Component Property 4184 To: ietf-calendar@imc.org 4186 Subject: Registration of text/calendar MIME property DEFAULT-VCARS 4188 Property Name: DEFAULT-VCARS 4190 Purpose: This property is used to specify the CARID of the default 4191 VCAR components for newly created VAGENDA components. 4193 Value Type: TEXT 4195 Property Parameters: Only non-standard property parameters can be 4196 specified on this property. 4198 Conformance: This property MUST be specified in "VCALSTORE" calendar 4199 component and MUST at least specify the following values: 4200 READBUSYTIMEINFO, REQUESTONLY, UPDATEPARTSTATUS, and DEFAULTOWNER. 4202 Description: This property is used in the "VCALSTORE" calendar 4203 component to specify the CARID of the VCAR components that must be 4204 copied in VAGENDA at creation time. 4206 Format Definition: The property is defined by the following notation: 4208 def-vcars = "DEFAULT-VCARS" def-vcarsparam ":" text 4209 *( "," text ) CRLF 4211 def-vcarsparam = *( ";" xparam ) 4213 Example: The following is an example of this property: 4215 DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY 4216 DEFAULT-VCARS:UPDATEPARTSTATUS,DEFAULTOWNER 4218 11.3.7.4 Maximum Date Component Property 4220 To: ietf-calendar@imc.org 4222 Subject: Registration of text/calendar MIME property MAXDATE 4224 Property Name: MAXDATE 4226 Purpose: This property specifies the date/time in the future beyond 4227 which the server cannot represent. 4229 Value Type: DATE-TIME 4231 Property Parameters: Non-standard property parameters can be 4232 specified on this property. 4234 Conformance: The property can be specified once in "VCALSTORE". 4236 Description: The date and time MUST be a UTC value. If not 4237 specified, then 99991231T235959Z will be assumed. 4239 Format Definition: The property is defined by the following notation: 4241 maxdate = "MAXDATE" maxdateparam ":" date-time CRLF 4243 maxdateparam = *(";" xparam) 4245 Example: The following is an example of this property: 4247 MAXDATE:20990101T000000Z 4249 11.3.7.5 Minimum Date Component Property 4251 To: ietf-calendar@imc.org 4253 Subject: Registration of text/calendar MIME property MINDATE 4255 Property Name: MINDATE 4257 Purpose: This property specifies the date/time in the past prior to 4258 which the server cannot represent. 4260 Value Type: DATE-TIME 4262 Property Parameters: Non-standard property parameters can be 4263 specified on this property. 4265 Conformance: The property can be specified once in "VCALSTORE". 4267 Description: The date and time MUST be a UTC value. If not 4268 specified, then 00000101T000000Z will be assumed. 4270 Format Definition: The property is defined by the following notation: 4272 mindate = "MINDATE" mindateparam ":" date-time CRLF 4274 mindateparam = *(";" xparam) 4276 Example: The following is an example of this property: 4278 MINDATE:19710101T000000Z 4280 11.3.8 Descriptive Component Properties 4282 The following properties specify descriptive information about 4283 calendar components. 4285 11.3.8.1 REQUEST-STATUS property 4287 This description is a revision of the REQUEST-STATUS property for 4288 VCALENDAR version 2.1. 4290 rstatus = "REQUEST-STATUS" rstatparam ":" 4291 statcode [";" statdesc [";" extdata]] 4293 rstatparam = *( 4294 ; the following is optional, 4295 ; but MUST NOT occur more than once 4296 (";" languageparm) / 4298 ; the following is optional, 4299 ; and MAY occur more than once 4301 (";" xparam) 4303 ) 4305 statcode = 1*DIGIT *("." 1*DIGIT) 4306 ;Hierarchical, numeric return status code 4308 statdesc = text 4309 ;An optional textual status description, content is 4310 ;decided by the implementor. May be empty. 4312 extdata = text 4313 ;Textual exception data. For example, the offending property 4314 ;name and value or complete property line. 4316 Example: The following are some possible examples of this property. 4317 The COMMA and SEMICOLON separator characters in the property value 4318 are BACKSLASH character escaped because they appear in a text value. 4320 REQUEST-STATUS:2.0;Success 4322 REQUEST-STATUS:2.0;Success despite braindead LDAP implementation 4324 REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01 4326 REQUEST-STATUS:2.8; Success, repeating event ignored. Scheduled 4327 as a single event.;RRULE:FREQ=WEEKLY;INTERVAL=2 4329 REQUEST-STATUS:4.1;Event conflict. Date/time is busy. 4331 REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE: 4332 MAILTO:jsmith@host.com 4334 REQUEST-STATUS:3.7;;ATTENDEE:MAILTO:jsmith@host.com 4336 REQUEST-STATUS:10.4;Help! That really shouldnt have happened. 4338 11.3.8.2 CALID Property Parameter 4340 Property Name: CALID 4341 Property Parameters: none 4343 Conformance: This property can be specified in the "VCAP" 4345 Description: This property is used to specify a fully qualified 4346 calid. 4348 Format Definition: The property is defined by the following notation: 4350 CALID = "DENY" ":" calid CRLF 4352 Example: 4354 CALID:cap://cal.example.com/sdfifgty4321 4356 11.3.8.3 Time Transparency 4358 Property Name: TRANSP 4360 Purpose: This property defines whether an event is transparent or not 4361 to busy time searches. 4363 Value Type: TEXT 4365 Property Parameters: Non-standard property parameters can be 4366 specified on this property. 4368 Conformance: This property can be specified once in a "VEVENT" 4369 calendar component. 4371 Description: Time Transparency is the characteristic of an event that 4372 determines whether it appears to consume time on a calendar. Events 4373 that consume actual time for the individual or resource associated 4374 with the calendar SHOULD be recorded as OPAQUE, allowing them to be 4375 detected by free-busy time searches. Other events, which do not take 4376 up the individual's (or resource's) time SHOULD be recorded as 4377 TRANSPARENT, making them invisible to free-busy time searches. 4379 Format Definition: The property is specified by the following 4380 notation: 4382 transp = "TRANSP" tranparam ":" transvalue CRLF 4384 tranparam = *(";" xparam) 4386 transvalue = "OPAQUE" ;Blocks or opaque on busy time searches. 4387 / "TRANSPARENT" ;Transparent on busy time searches. 4389 / "TRANSPARENT-NOCONFLICT" ; Transparent on busy time 4390 ; searches and no other OPAQUE 4391 ; or OPAQUE-NOCONFLICT event 4392 ; can overlap it. 4394 / "OPAQUE-NOCONFLICT" ; Opaque on busy time 4395 ; searches and no other OPAQUE 4396 ; or OPAQUE-NOCONFLICT event 4397 ; can overlap it. 4398 ; 4399 ;Default value is OPAQUE 4401 Example: The following is an example of this property for an event 4402 that is transparent or does not block on free/busy time searches: 4404 TRANSP:TRANSPARENT 4406 The following is an example of this property for an event that is 4407 opaque or blocks on free/busy time searches: 4409 TRANSP:OPAQUE 4411 The following is an example of this property for an event that is 4412 opaque or blocks on free/busy time searches plus no other event can 4413 overlap it: 4415 TRANSP:OPAQUE-NOCONFLICT 4417 11.3.8.4 Name Component Property 4419 To: ietf-calendar@imc.org 4421 Subject: Registration of text/calendar MIME property NAME 4423 Property Name: NAME 4425 Purpose: This property provides a localizable display name for a 4426 calendar component. 4428 Value Type: TEXT 4430 Property Parameters: Non-standard property parameters can be 4431 specified on this property. 4433 Conformance: This property can be specified in "VAGENDA" and "VCAR" 4434 calendar components. 4436 Description: This property is used in the "VAGENDA" and in the "VCAR" 4437 calendar components to specify a localizable display name. 4439 Format Definition: The property is defined by the following notation: 4441 name = "NAME" nameparam ":" text CRLF 4443 nameparam = *( 4444 ; the following is optional, 4445 ; but MUST NOT occur more than once 4447 ( ";" languageparam ) / 4449 ; the following is optional, 4450 ; and MAY occur more than once 4452 ( ";" xparam ) 4453 ) 4455 Example: The following is an example of this property: 4457 NAME:Restrict Guests From Creating ALARMs On Events 4459 11.3.9 Calendar Access Right Component Properties 4461 11.3.9.1 VCAR Identifier Component Property 4463 To: ietf-calendar@imc.org 4465 Subject: Registration of text/calendar MIME property CARID 4467 Property Name: CARID 4469 Purpose: This property specifies the identifier for an access right 4470 calendar component. 4472 Value Type: TEXT 4474 Property Parameters: Non-standard property parameters can be 4475 specified on this property. 4477 Conformance: This property MUST be specified once in a "VCAR" 4478 calendar component. 4480 Description: This property is used in the "VCAR" calendar component 4481 to specify an identifier. 4483 Format Definition: The property is defined by the following notation: 4485 carid = "CARID" caridparam ":" text CRLF 4487 caridparam = *( ";" xparam ) 4489 Example: The following is an example of this property: 4491 CARID:xyzzy-007 4493 11.3.9.2 VCAR Decreed Component Property 4495 To: ietf-calendar@imc.org 4497 Subject: Registration of text/calendar MIME property DECREED 4499 Property Name: DECREED 4501 Purpose: This property specifies if an access right calendar 4502 component is decreed or not. 4504 Value Type: BOOLEAN 4506 Property Parameters: Non-standard property parameters can be 4507 specified on this property. 4509 Conformance: This property MAY be specified once in a "VCAR" calendar 4510 component. 4512 Description: This property is used in the "VCAR" calendar component 4513 to specify whether the component is decreed or not. 4515 Format Definition: The property is defined by the following notation: 4517 decreed = "DECREED" decreedparam ":" boolean CRLF 4519 decreedparam = *( ";" xparam ) 4521 Example: The following is an example of this property: 4523 DECREED:TRUE 4525 11.3.10 Right Component Properties 4526 11.3.10.1 Grant Component Property 4528 To: ietf-calendar@imc.org 4530 Subject: Registration of text/calendar MIME property GRANT 4532 Property Name: GRANT 4534 Purpose: This property identifies the UPN(s) being granted access in 4535 the VRIGHT component. 4537 Value Type: UPN-FILTER 4539 Property Parameters: Only non-standard property parameters can be 4540 specified on this property. 4542 Conformance: This property can be specified in "VRIGHT" calendar 4543 components. 4545 Description: This property is used in the "VRIGHT" calendar component 4546 to specify the CU or UG being granted access. 4548 Format Definition: The property is defined by the following notation: 4550 grant = "GRANT" grantparam ":" upn-filter CRLF 4552 grantparam = *( ";" xparam ) 4554 Example: The following are examples of this property: 4556 GRANT:* 4558 GRANT:bob@example.com 4560 11.3.10.2 Deny Component Property 4562 To: ietf-calendar@imc.org 4564 Subject: Registration of text/calendar MIME property DENY 4566 Property Name: DENY 4568 Purpose: This property identifies the UPN(s) being denied access in 4569 the VRIGHT component. 4571 Value Type: UPN-FILTER 4572 Property Parameters: Only non-standard property parameters can be 4573 specified on this property. 4575 Conformance: This property can be specified in "VRIGHT" calendar 4576 components. 4578 Description: This property is used in the "VRIGHT" calendar component 4579 to define the CU or UG being denied access. 4581 Format Definition: The property is defined by the following notation: 4583 deny = "DENY" denyparam ":" upn-filter CRLF 4585 denyparam = *( ";" xparam ) 4587 Example: The following are examples of this property: 4589 DENY:* 4591 DENY:bob@example.com 4593 11.3.10.3 Permission Component Property 4595 To: ietf-calendar@imc.org 4597 Subject: Registration of text/calendar MIME property PERMISSION 4599 Property Name: PERMISSION 4601 Purpose: This property defines a permission that is granted or denied 4602 in a VRIGHT component. 4604 Value Type: TEXT 4606 Property Parameters: Only non-standard property parameters can be 4607 specified on this property. 4609 Conformance: This property can be specified in "VRIGHT" calendar 4610 components. 4612 Description: This property is used in the "VRIGHT" calendar component 4613 to define a permission that is granted or denied. 4615 Format Definition: The property is defined by the following notation: 4617 perm = "PERMISSION" permparam ":" permvalue CRLF 4618 permparam = *( ";" xparam ) 4620 permvalue = ( "READ" / "WRITE" / "DELETE" / "MODIFY" / all ) 4622 all = "*" 4624 Example: The following is an example of this property: 4626 PERMISSION:READ 4628 11.3.10.4 Scope Component Property 4630 To: ietf-calendar@imc.org 4632 Subject: Registration of text/calendar MIME property SCOPE 4634 Property Name: SCOPE 4636 Purpose: This property identifies the objects in the CS to which the 4637 access rights applies. 4639 Value Type: CAL-QUERY 4641 Property Parameters: Only non-standard property parameters can be 4642 specified on this property. 4644 Conformance: This property can be specified in "VRIGHT" calendar 4645 components. 4647 Description: This property is used in the "VRIGHT" calendar component 4648 to define the set of objects subject to the access right being 4649 defined. 4651 Format Definition: The property is defined by the following notation: 4653 scope = "SCOPE" scopeparam ":" cal-query CRLF 4655 scopeparam = *( ";" xparam ) 4657 Example: The following is an example of this property: 4659 SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC' 4661 11.3.10.5 Restriction Component Property 4663 To: ietf-calendar@imc.org 4665 Subject: Registration of text/calendar MIME property RESTRICTION 4667 Property Name: RESTRICTION 4669 Purpose: This property defines restrictions on the value that may 4670 take new or existent calendar components. 4672 Value Type: CAL-QUERY 4674 Property Parameters: Only non-standard property parameters can be 4675 specified on this property. 4677 Conformance: This property can be specified in "VRIGHT" calendar 4678 components, but only when the PERMISSION property is set to "WRITE", 4679 "MODIFY", or "*". 4681 Description: This property is used in the "VRIGHT" calendar component 4682 to define restrictions on the calendar components that can be written 4683 (i.e., by using the "create" or "move" commands) as well as on the 4684 values that may take existent calendar store properties, calendar 4685 properties, calendar components, and component properties (i.e., by 4686 using the "modify" command). Accepted values MUST match the 4687 specified RESTRICTION. 4689 Format Definition: The property is defined by the following notation: 4691 restrict = "RESTRICTION" restrictparam ":" cal-query CRLF 4693 restrictparam = *( ";" xparam ) 4695 Example: The following are examples of this property: 4697 RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST' 4699 RESTRICTION:SELECT * FROM VEVENT WHERE 4700 SELF() IN CAL-OWNERS(ORGANIZER) 4702 RESTRICTION:SELECT * FROM VEVENT WHERE 'BUSINESS' IN 4703 CATEGORIES 4705 12. CAP Item Registration 4707 This section provides the process for registration of new or modified 4708 CAP entities. 4710 12.1 Registration of New and Modified CAP Entities 4712 New CAP entities are registered by the publication of an IETF Request 4713 for Comment (RFC). Changes to a CAP item are registered by the 4714 publication of a revision of the RFC defining the method. 4716 12.2 Registration of New Entities 4718 This section defines procedures by which new entities (i.e., 4719 components, properties, parameters, enumerated values or restriction 4720 tables) for a CAP item can be registered with the IANA. 4722 Non-standard, experimental entities can be used by bilateral 4723 agreement, provided the associated properties names follow the "X-" 4724 convention. Such non-standard and experimental entities are non-IANA 4725 entities and need not be registered using this process. 4727 The procedures defined here are designed to allow public comment and 4728 review of new CAP entities, while posing only a small impediment to 4729 the definition of new properties. 4731 Registration of a new CAP item is accomplished by the following 4732 steps. 4734 12.2.1 Define the Item 4736 A CAP item is defined by completing the following template. 4738 To: ietf-calendar@imc.org 4739 Subject: Registration of CAP item XXX 4740 Item name: 4741 Item purpose: 4742 Description: 4743 CAP terminology changes: 4744 CAP data model changes: 4745 CAP system model changes: 4746 Conformance considerations: 4747 Format definition: 4748 Examples: 4750 The meaning of each field in the template is as follows. 4752 Item name: The name of the item. 4754 Item purpose: The purpose of the item (e.g., Extends the CAP 4755 command set to poll for notifications, etc.). Give a short but 4756 clear description. 4758 Description: Any special notes about the item, how it is to be 4759 used, etc. 4761 CAP terminology changes: Any change or additions to the 4762 existing CAP terminology needs to be specified. 4764 CAP data model changes: Any of the valid property parameters 4765 for the property needs to be specified. 4767 CAP system model changes: 4769 Conformance: A clear summary of how and where this CAP item 4770 extension MUST, MAY, SHOULD or can be used. Any changes or 4771 impact to the existing conformance definition for CAP should be 4772 explained. The impact to implementations conforming to the 4773 existing CAP specification should be clearly described. 4775 Format definition: The ABNF for each element of the CAP item 4776 needs to be specified. 4778 Examples: One or more examples of instances of the CAP item and 4779 each of its usage scenarios needs to be specified. 4781 12.2.2 Post the item definition 4783 The item description MUST be posted to the new item discussion list, 4784 ietf-calendar@imc.org. 4786 12.2.3 Allow a comment period 4788 Discussion on the new item MUST be allowed to take place on the list 4789 for a minimum of two weeks. Consensus MUST be reached on the 4790 property before proceeding to the next step. 4792 12.2.4 Submit the proposal for approval 4794 Once the two-week comment period has elapsed, and the proposer is 4795 convinced consensus has been reached on the proposal, the 4796 registration application should be submitted to the Method Reviewer 4797 for approval. The Method Reviewer is appointed by the Application 4798 Area Directors and can either accept or reject the proposal 4799 registration. An accepted registration should be passed on by the 4800 Method Reviewer to the IANA for inclusion in the official IANA method 4801 registry. The registration can be rejected for any of the following 4802 reasons. 1) Insufficient comment period; 2) Consensus not reached; 4803 3) Technical deficiencies raised on the list or elsewhere have not 4804 been addressed. The Method Reviewers decisions may be appealed to 4805 the IESG. 4807 12.3 Property Change Control 4809 Existing CAP entities can be changed using the same process by which 4810 they were registered. 4812 1. Define the change 4814 2. Post the change 4816 3. Allow a comment period 4818 4. Submit the proposal for approval 4820 Note that the original author or any other interested party can 4821 propose a change to an existing CAP object, but that such changes 4822 should only be proposed when there are serious omissions or errors in 4823 the published memo. The Method Reviewer can object to a change if it 4824 is not backward compatible, but is not required to do so. 4826 CAP objects definitions can never be deleted from the IANA registry, 4827 but objects which are no longer believed to be useful can be declared 4828 OBSOLETE by adding this text to their "Item purpose" field. 4830 13. IANA Considerations 4832 This memo defines IANA registered extensions to the attributes 4833 defined by iCalendar, as defined in [RFC2445], and [iTIP]. 4835 IANA registration proposals for iCalendar and iTIP are to be mailed 4836 to the registration agent for the "text/calendar" [MIME] content- 4837 type, using the format defined in 4838 section 7 of [RFC2445]. 4840 If the IESG approves this memo for publication, then the IANA 4841 registers the profile specified in Section 7.1, and selects an IANA- 4842 specific URI, e.g., http://iana.org/beep/cap/1.0. 4844 URIs 4846 [1] 4848 Authors' Addresses 4850 Steve Mansour 4851 AOL/Netscape 4852 466 Ellis Road 4853 Mountain View, CA 94043 4854 US 4856 Phone: +1-650-937-3351 4857 EMail: sman@netscape.com 4859 Doug Royer 4860 INET-Consulting LLC 4861 1795 W. Broadway #266 4862 Idaho Falls, ID 83402 4864 Phone: 208-520-4044 4865 EMail: Doug@Royer.com 4867 George Babics 4868 Steltor 4869 2000 Peel Street 4870 Montreal, Quebec H3A 2W5 4871 CA 4873 Phone: +1-514-733-8500 x4201 4874 Fax: +1-514-733-8878 4875 EMail: georgeb@steltor.com 4877 Paul Hill 4878 Massachusetts Institute of Technology 4879 W92-172 4880 77 Massachusetts Avenue 4881 Cambridge, MA 02139 4882 US 4884 Phone: +1-617-253-0124 4885 Fax: +1-617-258-8736 4886 EMail: phb@mit.edu 4888 Appendix A. Acknowledgments 4890 The following have individuals were major contributors in the 4891 drafting and discussion of this memo: 4893 Harald Alvestrand, Mario Bonin, Andre Courtemanche, Dave 4894 Crocker, Bernard Desruisseaux, Pat Egen, Gilles Fortin, Jeff 4895 Hodges, Alex Hoppman, Bruce Kahn, Lisa Lippert, David Madeo, 4896 Bob Mahoney, Bob Morgan, Patrice Lapierre, Pete O'Leary, 4897 Richard Shusterman, Tony Small, John Stracke, Alexander Taler, 4898 Mark Wahl. Special thanks to Patrice Lapierre for transforming 4899 CAP into a BEEP profile. 4901 Appendix B. Bibliography 4903 [RFC1521] Borenstein, N., Freed, N., "Specifying and Describing the Format of Internet Message 4904 Bodies", RFC 1521, September 1993 4905 ftp://ftp.isi.edu/in-notes/rfc1521.txt 4907 [RFC1738] Berners-Lee, T, Masinter, L. and McCahil, M., "Uniform Resource Locators (URL)", RFC 4908 1738, December 1994 4909 ftp://ftp.isi.edu/in-notes/rfc1738.txt 4911 [RFC2045] Borenstein, N. and Freed, N., "Multipurpose Internet Mail Extensions (MIME) Part 4912 One: Format of Internet Message Bodies", RFC 2045, November 1996 4913 ftp://ftp.isi.edu/in-notes/rfc2045.txt 4915 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, 4916 BCP 14, March 1997 4917 ftp://ftp.isi.edu/in-notes/rfc2119.txt 4919 [RFC2222] Myers, J., "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997 4920 ftp://ftp.isi.edu/in-notes/rfc2222.txt 4922 [RFC2246] Dierks, T. and Allen, C., "The TLS Protocol Version 1.0", RFC 2246, January 1999 4923 ftp://ftp.isi.edu/in-notes/rfc2246.txt 4925 [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource Locators", RFC 2392, 4926 August 1998 4927 ftp://ftp.isi.edu/in-notes/rfc2392.txt 4929 [RFC2396] Berners-Lee, T, Fielding, R. and Masinter, L., "Uniform Resource Identifiers (URI): 4930 Generic Syntax", RFC 2396, August 1998 4931 ftp://ftp.isi.edu/in-notes/rfc2396.txt 4933 [RFC2445] Dawson, F. and Stenerson, D., "Internet Calendaring and Scheduling Core Object 4934 Specification (iCalendar)", RFC 2445, November 1998 4935 ftp://ftp.isi.edu/in-notes/rfc2245.txt 4937 [RFC2446] Silverberg, S., Mansour, S., Dawson, F. and Hopson, R., "iCalendar Transport-Independent 4938 Interoperability Protocol (iTIP) Events, BusyTime, To-dos and Journal Entries", RFC 4939 2446, November 1998 4940 ftp://ftp.isi.edu/in-notes/rfc2446.txt 4942 [RFC2447] Dawson, F., Mansour, S. and Silverberg, "iCalendar Message-Based Interoperability 4943 Protocol (iMIP)", RFC 2447, November 1998 4944 ftp://ftp.isi.edu/in-notes/rfc2447.txt 4946 [RFC3080] Rose, M., "The Block Extensible Exchange Protocol Core", RFC 3080, March 2001 4947 ftp://ftp.isi.edu/in-notes/rfc3080.txt 4949 [RFC3081] Rose, M., "Mapping the BEEP Core onto TCP", RFC 3081, March 2001 4950 ftp://ftp.isi.edu/in-notes/rfc3081.txt 4952 [RFC3087] Campbell, B. and Sparks, R., "Control of Service Context using SIP Request-URI", 4953 RFC 3087, April 2001 4954 ftp://ftp.isi.edu/in-notes/rfc3087.txt 4956 [SQL] "Database Language SQL", ANSI/ISO/IEC 9075: 1992, aka ANSI X3.135-1992, aka FiPS PUB 127-2 4958 [SQLCOM] ANSI/ISO/IEC 9075:1992/TC-1-1995, Technical corrigendum 1 to ISO/IEC 9075: 1992, also 4959 adopted as Amendment 1 to ANSI X3.135.1992 4961 [UNICODE] The Unicode Consortium, "The Unicode Standard, Version 3.1" 4962 http://www.unicode.org/unicode/standard/standard.html 4964 [US-ASCII] Coded Character Set -- 7-bit American Standard Code for Information Interchange, 4965 ANSI X3.4-1986. 4967 [????] "Worldwide Character Encoding -- Version 1.0", Addison-Wesley, Volume 1, 1991, 4968 Volume 2, 1992. UTF-8 is described in Unicode Technical Report #4. 4970 Full Copyright Statement 4972 Copyright (C) The Internet Society (2002). All Rights Reserved. 4974 This document and translations of it may be copied and furnished to 4975 others, and derivative works that comment on or otherwise explain it 4976 or assist in its implementation may be prepared, copied, published 4977 and distributed, in whole or in part, without restriction of any 4978 kind, provided that the above copyright notice and this paragraph are 4979 included on all such copies and derivative works. However, this 4980 document itself may not be modified in any way, such as by removing 4981 the copyright notice or references to the Internet Society or other 4982 Internet organizations, except as needed for the purpose of 4983 developing Internet standards in which case the procedures for 4984 copyrights defined in the Internet Standards process must be 4985 followed, or as required to translate it into languages other than 4986 English. 4988 The limited permissions granted above are perpetual and will not be 4989 revoked by the Internet Society or its successors or assigns. 4991 This document and the information contained herein is provided on an 4992 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 4993 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 4994 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 4995 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 4996 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4998 Acknowledgement 5000 Funding for the RFC Editor function is currently provided by the 5001 Internet Society.