idnits 2.17.1 draft-ietf-calsch-cap-04.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: ---------------------------------------------------------------------------- ** Missing document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == There is 1 instance of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. (A line matching the expected section header was found, but with an unexpected indentation: ' 1 Introduction' ) ** The document seems to lack a Security Considerations section. (A line matching the expected section header was found, but with an unexpected indentation: ' 12 Security Considerations' ) ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) (A line matching the expected section header was found, but with an unexpected indentation: ' 14 IANA Considerations' ) ** The document seems to lack an Authors' Addresses Section. ** The abstract seems to contain references ([UNICODE], [US-ASCII], [CMDID], [RFC2119], [VCARD], [MIME], [VQUERY], [IANA-PROP], [RFC2246], [URL], [SQLCOM], [TLS], [SASL], [SQL], [IMPL]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** 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 309: '... a calendar. For example, "events MUST...' RFC 2119 keyword, line 472: '... SHOULD be postfixed w...' RFC 2119 keyword, line 529: '...ail address. A CU's UPN MUST never be...' RFC 2119 keyword, line 580: '... * CS1 MAY play the role of ...' RFC 2119 keyword, line 582: '... * CS1 MUST be able play the...' (184 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 893 has weird spacing: '...mpts at confu...' == Line 1019 has weird spacing: '...ich are made...' == Line 1254 has weird spacing: '...dicates the c...' == Line 1257 has weird spacing: '...dentify a com...' == Line 1873 has weird spacing: '...ator to get ...' == (5 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: The CS SHOULD not preserve UG expansions across operations. A UG may reference a static list of members, or it may represent a dynamic list. Each operation SHOULD generate its own CAP Expires September 2001 == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The response-args are defined in Section 8. The debug-text is human-readable information for protocol debugging and is optional and is only used to aid developers writing CSs and CUAs. The debug-text MUST not be depended on by CUAs in normal interactions with a CS. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Subsequent to the initial Anonymous Authentication with a CS, a CUA will have to provide a UPN for some CAP operations. For anonymous access the UPN that MUST be used by the CUA is "@", a UPN with a null username and null realm. The user's normal UPN MUST not be used for the subsequent CAP operations. -- 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.) -- Couldn't find a document date in the document -- date freshness check skipped. -- 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? 'RFC2119' on line 5376 looks like a reference -- Missing reference section? 'IMPL' on line 210 looks like a reference -- Missing reference section? 'URL' on line 5380 looks like a reference -- Missing reference section? 'MIME' on line 5366 looks like a reference -- Missing reference section? 'TLS' on line 5373 looks like a reference -- Missing reference section? 'SASL' on line 5378 looks like a reference -- Missing reference section? 'RFC 2246' on line 942 looks like a reference -- Missing reference section? 'SQL' on line 5396 looks like a reference -- Missing reference section? 'CMDID' on line 4756 looks like a reference -- Missing reference section? 'IANA-PROP' on line 3810 looks like a reference -- Missing reference section? 'VQUERY' on line 3198 looks like a reference -- Missing reference section? 'VCARD' on line 5417 looks like a reference -- Missing reference section? 'SQLCOM' on line 5399 looks like a reference -- Missing reference section? 'UNICODE' on line 5403 looks like a reference -- Missing reference section? 'US-ASCII' on line 5409 looks like a reference Summary: 9 errors (**), 0 flaws (~~), 12 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Steve Mansour/Netscape 3 Internet Draft Doug Royer 4 George Babics/Steltor 5 Paul Hill/MIT 6 Calendar Access Protocol (CAP) 8 Status of this Memo 10 This memo is an Internet-Draft and is in full conformance with 11 all provisions of Section 10 of RFC2026. 13 Internet-Drafts are working documents of the Internet 14 Engineering Task Force (IETF), its areas, and its working 15 groups. Note that other groups may also distribute working 16 documents as Internet-Drafts. Internet-Drafts are draft 17 documents valid for a maximum of six months and may be 18 updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet- Drafts as reference 20 material or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt . 25 The list of Internet-Draft Shadow Directories can be accessed 26 at http://www.ietf.org/shadow.html. 28 Distribution of this document is unlimited. 30 Copyright Statement 32 Copyright (C) The Internet Society 2000. All Rights Reserved. 34 Abstract 36 The Calendar Access Protocol (CAP) is an Internet protocol 37 that permits a Calendar User (CU) to utilize a Calendar User 38 Agent (CUA) to access an [iCAL] based Calendar Store (CS). 39 This memo defines the CAP specification. 41 The CAP definition is based on requirements identified by the 42 Internet Engineering Task Force (IETF) Calendaring and 43 Scheduling (CALSCH) Working Group. More information about the 44 IETF CALSCH Working Group activities can be found on the IMC 45 web site at http://www.imc.org/ietf-calendar, and at the IETF 46 web site at http://www.ietf.org/html.charters/calsch- 47 charter.html. Refer to the references within this memo for 48 further information on how to access these various documents. 50 CAP Expires September 2001 52 Table Of Contents 53 1 Introduction.............................................4 54 1.1 Formatting Conventions...............................4 55 1.2 Related Documents....................................5 56 1.3 Definitions..........................................5 57 2 CAP Design..............................................12 58 2.1 System Model........................................12 59 2.2 Calendar Store Object Model.........................13 60 2.3 Protocol Model......................................15 61 2.4 Security Model......................................16 62 2.4.1 Authentication, Credentials, and Identity........17 63 2.4.2 Calendar User and UPNs...........................18 64 2.4.3 User Groups......................................21 65 2.4.4 Access Rights - Summary..........................22 66 2.4.5 Inheritance......................................23 67 2.4.6 CAP Session Identity.............................24 68 2.5 Roles...............................................25 69 2.6 Calendar Addresses..................................25 70 2.7 Extensions to iCalendar.............................26 71 2.8 Relationship of RFC 2446 (ITIP) to CAP..............27 72 3 State Diagram...........................................29 73 4 Protocol Framework......................................30 74 4.1 CAP Application Layer...............................30 75 4.2 CAP Transfer Protocol...............................31 76 4.3 Pipelining of Commands..............................32 77 4.4 Auto-logout Timer...................................32 78 4.5 Bounded Latency.....................................32 79 4.6 Data Elements.......................................32 80 5 Formal Command Syntax...................................32 81 5.1 Searching and Filtering.............................32 82 5.1.1 Grammar For Search Mechanism.....................33 83 5.1.2 SQL-MIN notes....................................34 84 5.1.3 SQL-92 notes.....................................35 85 5.1.4 Example, Query by UID............................35 86 5.1.5 Query by Date-Time range.........................35 87 5.1.6 Query for all Non-Booked Entries.................36 88 5.1.7 Query with Subset of Properties by Date/Time.....36 89 5.1.8 Components With Alarms In A Range................36 90 6 Access Rights...........................................37 91 6.1 VCAR Inheritance....................................37 92 6.2 Access Control and NOCONFLICT.......................37 93 7 Commands and Responses..................................38 94 7.1 Transfer Protocol Commands..........................38 95 7.1.1 Initial Connection...............................38 96 7.1.2 ABORT Command....................................39 97 7.1.3 AUTHENTICATE Command.............................39 98 7.1.4 CALIDEXPAND Command..............................43 99 7.1.5 CAPABILITY Command...............................45 100 7.1.6 CONTINUE Command.................................47 101 CAP Expires September 2001 103 7.1.7 DISCONNECT Command...............................48 104 7.1.8 SENDDATA Command.................................49 105 7.2 Application Protocol Commands.......................52 106 7.2.1 Calendaring Commands.............................52 107 7.2.2 Scheduling Commands..............................84 108 7.2.3 iTIP Examples....................................89 109 8 Response Codes..........................................96 110 9 Examples................................................98 111 9.1 Authentication Examples.............................98 112 9.1.1 Login Using Kerberos V4..........................98 113 9.1.2 Error Scenarios..................................99 114 9.2 Read Examples......................................100 115 9.2.1 Read From Multiple Calendars....................101 116 9.2.2 Timeouts........................................102 117 9.2.3 Using Parent and Children Properties............103 118 9.2.4 Query VEVENT.DTSTART and VALARM.DTSTART.........103 119 10 Implementation Issues................................103 120 11 Properties...........................................104 121 11.1 Calendar Store Properties........................104 122 11.2 Calendar Properties..............................105 123 12 Security Considerations..............................107 124 13 CAP Item Registration................................107 125 13.1 Registration of New and Modified CAP Entities....107 126 13.2 Registration of New Entities.....................107 127 13.2.1 Define the Item...............................108 128 13.2.2 Post the item definition......................109 129 13.2.3 Allow a comment period........................109 130 13.2.4 Submit the proposal for approval..............109 131 13.3 Property Change Control..........................109 132 14 IANA Considerations..................................110 133 15 Acknowledgments......................................110 134 16 Bibliography.........................................111 135 17 Author's Address.....................................112 136 18 Full Copyright Statement.............................112 137 CAP Expires September 2001 139 1 Introduction 141 This document specifies how a Calendar User Agent (CUA) 142 interacts with a Calendar Store (CS) to manage calendar 143 information. In particular, it specifies how to query, create, 144 modify, and delete iCalendar components (e.g., events, to-dos, 145 or daily journal entries). It further specifies how to search 146 for available busy time information. 148 This protocol is based on request/response form of data units, 149 sent from a client CUA to a calendar server. The protocol data 150 units leverage the standard iCalendar format [iCAL] for 151 conveying CS related information. 153 1.1 Formatting Conventions 155 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 156 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and 157 "OPTIONAL" in this document are to be interpreted as described 158 in [RFC2119]. 160 Calendaring and scheduling roles are referred to in quoted- 161 strings of text with the first character of each word in upper 162 case. For example, "Organizer" refers to a role of a "Calendar 163 User" (CU) within the protocol defined by this memo. Calendar 164 components defined by [iCAL] are referred to with capitalized, 165 quoted-strings of text. All calendar components start with the 166 letter "V". For example, "VEVENT" refers to the event calendar 167 component, "VTODO" refers to the to-do calendar component and 168 "VJOURNAL" refers to the daily journal calendar component. 169 Calendar access methods defined by this memo, as well as 170 scheduling methods defined by [iTIP], are referred to with 171 capitalized, quoted-strings of text. For example, "CREATE" 172 refers to the method for creating a calendar component on a 173 calendar, "READ" refers to the method for reading calendar 174 components. 176 Properties defined by this memo are referred to with 177 capitalized, quoted-strings of text, followed by the word 178 "property". For example, "ATTENDEE" property refers to the 179 iCalendar property used to convey the calendar address of a 180 "Calendar User". Property parameters defined by this memo are 181 referred to with lower case, quoted-strings of text, followed 182 by the word "parameter". For example, "value" parameter refers 183 to the iCalendar property parameter used to override the 184 default data type for a property value. Enumerated values 185 defined by this memo are referred to with capitalized text, 186 either alone or followed by the word "value". 188 CAP Expires September 2001 190 In tables, the quoted-string text is specified without quotes 191 in order to minimize the table length. 193 1.2 Related Documents 195 Implementers will need to be familiar with several other memos 196 that, along with this one, describe the Internet calendaring 197 and scheduling standards. These documents are: 199 [iCAL] (RFC2445) which specifies the objects, data types, 200 properties and property parameters used in the protocols, 201 along with the methods for representing and encoding them, 203 [iTIP] (RFC2446) which specifies an interoperability protocol 204 for scheduling between different implementations. The related 205 documents are: 207 [iMIP] (RFC2447) which specifies an Internet email binding for 208 [iTIP]. 210 [IMPL] (draft/rfc...) which is a guide to implementers and 211 describes the elements of a calendaring system, how they 212 interact with each other, how they interact with end users, 213 and how the standards and protocols are used. 215 This memo does not attempt to repeat the specification of 216 concepts or definitions from these other memos. Where 217 possible, references are made to the memo that provides for 218 the specification of these concepts or definitions. 220 1.3 Definitions 222 Authentication ID (AuthID) 224 A tuple of username, realm, and authentication 225 method, used by the Calendar Service internally to 226 identify a successfully authenticated CAP session. 228 Booked 230 A entry in a calendar has one of two conceptual 231 states. It is scheduled or it is booked. A scheduled 232 entry has been stored in the calendar store but has 233 not been acted on by a calendar user or calendar user 234 agent. A booked appointment is an entry that has had 235 its state changed from one of the [iTIP] scheduling 236 methods to a CAP method of CREATE by a calendar user 237 CAP Expires September 2001 239 or calendar user agent which resulted in decision to 240 keep the entry in the calendar store. 242 Calendar 244 A collection of logically related objects or entities 245 each of which may be associated with a calendar date 246 and possibly time of day. These entities can include 247 other calendar properties or calendar components.In 248 addition, a calendar might be hierarchically related 249 to other sub-calendars. A calendar is identified by 250 its unique calendar identifier. The [iCAL] defines 251 calendar properties, calendar components and 252 component properties that make up the content of a 253 calendar. 255 Calendar Access Protocol (CAP) 257 The standard Internet protocol that permits a 258 Calendar User Agent to access and manipulate a 259 calendar residing on a Calendar Store. 261 Calendar Access Rights (CAR) 263 The mechanism for specifying the CAP operations 264 ("ACTIONS") that a particular calendar user ("UPN") 265 are granted or denied permission to perform on a 266 given calendar item ("OBJECT"). The calendar access 267 rights are specified with the "VCAR" calendar 268 components within a CS and calendar. 270 Calendar Collection 272 A collection of Calendars, Resource Calendars, and/or 273 other Calendar Collections. These collections are 274 expanded by the CS and may reside either locally or 275 in an external database or directory. The calendars 276 in the collection may be fixed or dynamic over time. 278 Calendar Component 280 An item within a calendar. Some types of calendar 281 components include events, to-dos, journals, alarms, 282 time zones and freebusy data. A calendar component 283 consists of component properties and possibly other 284 CAP Expires September 2001 286 sub-components. For example, an event may contain an 287 alarm component. 289 Calendar Component Properties 291 An attribute of a particular calendar component. Some 292 calendar component properties are applicable to 293 different types of calendar components. For example, 294 DTSTART is applicable to VEVENT, VTODO, VJOURNAL 295 calendar components. Other calendar components are 296 applicable only to an individual type of calendar 297 component. For example, TZURL is only applicable to 298 VTIMEZONE calendar components. 300 Calendar Identifier (CalID) 302 A globally unique identifier associated with a 303 calendar. Calendars reside within a CS. See Qualified 304 Calendar Identifier and Relative Calendar Identifier. 306 Calendar Policy 308 A CAP operational restriction on the access or 309 manipulation of a calendar. For example, "events MUST 310 be scheduled in unit intervals of one hour". 312 Calendar Properties 314 An attribute of a calendar. The attribute applies to 315 the calendar, as a whole. For example, CALSCALE 316 specifies the calendar scale (e.g., GREGORIAN) for 317 the whole calendar. 319 Calendar Service 321 An implementation of a Calendar Store that manages 322 one or more calendars. 324 Calendar Store (CS) 326 The data and service model definition for a Calendar 327 Service. 329 CAP Expires September 2001 331 Calendar Store Identifier (CSID) 333 The globally unique identifier for an individual CS. 334 A CSID consists of the host and port portions of a 335 "Common Internet Scheme Syntax" part of a URL, as 336 defined by [URL]. 338 Calendar Store Components 340 Components maintained in a CS specify a grouping of 341 calendar store-wide information. Calendar store 342 components can be accessed using CAP. 344 Calendar Store Properties 346 Properties maintained in a Calendar Store calendar 347 store-wide information. Calendar store properties can 348 be accessed using CAP. 350 Calendar User (CU) 352 An entity (often biological) that uses a calendaring 353 system. 355 Calendar User Agent (CUA) 357 The CUA is the client application that a CU or UG 358 utilizes to access and manipulate a calendar. 360 Calendaring and Scheduling System 362 The computer sub-system that provides the services 363 for accessing, manipulating calendars and scheduling 364 calendar components. 366 CAP Session 368 An open communication channel between a CAP CUA and a 369 CAP CS. 371 Connected Mode 372 CAP Expires September 2001 374 A mobile computing mode where the CUA is directly 375 connected to the CS. 377 Delegate 379 Is a calendar user (sometimes called the delegatee) 380 who has been assigned participation in a scheduled 381 calendar component (e.g., VEVENT) by one of the 382 attendees in the scheduled calendar component 383 (sometimes called the delegator). An example of a 384 delegate is a team member told to go to a particular 385 meeting. 387 Designate 389 Is a calendar user who is authorized to act on behalf 390 of another calendar user. An example of a designate 391 is an assistant. 393 Disconnected Mode 395 A mobile computing mode where a CUA can be 396 disconnected from a CS. When the CUA is disconnected, 397 it is in the disconnected mode. 399 Fan Out 401 The calendaring and scheduling process by which a 402 calendar operation on one calendar is also performed 403 on every other calendar specified in the operation. 404 This may include the calendar associated with TARGET 405 calendar property. 407 Hierarchical Calendars 409 A CS feature where a calendar have a hierarchical 410 relationship with another calendar in the CS. The 411 top-most calendar in the hierarchical relationship 412 has the CS as its parent. There may be multiple top- 413 most calendars in a given CS. Within a given 414 hierarchical relationship, all sub-calendars have a 415 calendar with a "parent" topographical relationship. 416 In addition, sub-calendars may have a relationship 417 CAP Expires September 2001 419 with another calendar that has a "child" 420 topographical relationship. In addition, a calendar 421 may have a relationship such that one or more 422 calendars have a "sibling" topographical relationship 423 with the calendar. The hierarchical calendar feature 424 is not a storage relationship of the calendars within 425 the CS. Instead it is a feature that relates access 426 control rights to calendar content between different 427 calendars in the CS. The hierarchical relationship 428 of a calendar is specified in the "PARENT" and 429 "CHILDREN" calendar properties. 431 High Bandwidth Connection 433 A communications connection supporting high transfer 434 rates; transfer rates commonly found within a LAN. 436 Local Store 438 A CS which is on the same platform as the CUA. 440 Low Bandwidth Connection 442 A communications connection supporting slow transfer 443 rates; transfer rates commonly found in remote access 444 technology. 446 Overlapped Booking 448 A policy which indicates whether or not OPAQUE events 449 can overlap one another. When the policy is applied 450 to a calendar it indicates whether or not any OPAQUE 451 events in the calendar can overlap. When applied to 452 an individual event, it indicates whether or not it 453 can be overlapped by any other OPAQUE event. 455 Owner 457 One or more CUs or UGs that have "OWNER" calendar 458 access rights for a calendar. The owner is specified 459 in the "OWNER" calendar property. 461 Qualified Calendar Identifier (Qualified CalID) 462 CAP Expires September 2001 464 A CalID where both the and are 465 present. 467 Realm 469 A collection of calendar user accounts, identified by 470 a string. The name of the realm is only used in 471 UPNs. In order to avoid namespace conflict, the realm 472 SHOULD be postfixed with an appropriate DNS domain 473 name. (eg: the foobar realm could be called 474 foobar.example.com). 476 Relative Calendar Identifier (Relative CalID) 478 An identifier for an individual calendar in a 479 calendar store. It is unique within a calendar store. 480 It is recommended to be globally unique. A Relative 481 CalID consists of the portion of the "scheme part" of 482 a Qualified CalID following the Calendar Store 483 Identifier. This is the same as the "URL path" of the 484 "Common Internet Scheme Syntax" portion of a URL, as 485 defined by [URL]. 487 Remote Store 489 A CS which is not on the same platform as the CUA. 491 Resource Calendar (RC) 493 A non-human Calendar, associated with an 494 organizational resource. There is no syntactic 495 difference between an RC and a Calendar. 497 Session Identity 499 A UPN associated with a CAP session. A session gains 500 an identity after successful authentication. The 501 identity is used in combination with CAR to determine 502 access to data in the CS. 504 Sub-calendars 505 CAP Expires September 2001 507 Calendars that have a "child" hierarchical 508 relationship with another calendar, its "parent". 510 User Group (UG) 512 A collection of Calendar Users and/or User Groups. 513 These groups are expanded by the CS and may reside 514 either locally or in an external database or 515 directory. The group membership may be fixed or 516 dynamic over time. 518 User Name 520 A name which denotes a Calendar User within a realm. 521 This is part of a UPN. 523 User Principal Name (UPN) 525 An identifier that denotes a unique CU. A UPN is an 526 RFC 822 compliant email address, with exceptions 527 listed below, and in most cases it is deliverable to 528 the CU. In some cases it is identical to the CU's 529 well known email address. A CU's UPN MUST never be 530 deliverable to a different person. It consists of a 531 realm in the form of a valid, and unique, DNS domain 532 name and a unique username. In it's simplest form it 533 looks like "user@example.com". 535 In certain cases a UPN will not be RFC 822 compliant. 536 When anonymous authentication is used, or anonymous 537 authorization is being defined, the special UPN "@" 538 will be used. When authentication must be used, but 539 unique identity must be obscured, a UPN of the form 540 @DNS-domain-name may be used. For example, 541 "@example.com". Usage of these special cases is 542 further discussed in the authentication and 543 authorization sections of this document. 545 2 CAP Design 547 2.1 System Model 549 The system model describes the high level components of a 550 calendar system and how they interact with each other. 552 CAP Expires September 2001 554 CAP is used by a "Calendar User Agent" (CUA) to send commands 555 to and receive responses from a "Calendar Service" (CS). The 556 CUA prepares a [MIME] encapsulated iCalendar object containing 557 a command, sends it to the CS, and receives a [MIME] 558 encapsulated iCalendar object as a response. There are two 559 distinct protocols in operation to accomplish this exchange. 560 The Transfer Protocol is used to move these encapsulations 561 between a CUA and a CS. The Application Protocol defines the 562 content and semantics of the iCalendar objects sent between 563 the CUA and the CS. This document defines both the Transfer 564 Protocol and the Application Protocol. 566 In the diagram below, a user uses CUA1 to communicate with CS1 567 using CAP. The CUA must authenticate the Calendar User (CU) so 568 that access to calendars on CS1 can be controlled. The CUA can 569 then view, create, edit, and delete calendars, calendar 570 properties, and calendar components subject to the access 571 rights. 573 CAP servers support fanout. Fanout allows a CUA to communicate 574 with a single CS to perform scheduling operations with 575 calendars on multiple CSs. That is, a CU can book or schedule 576 events (or to-dos) on or read events (or to-dos) from 577 calendars on other calendar stores. To accomplish this, a CAP 578 server takes on these roles: 580 * CS1 MAY play the role of a CUA and use CAP to access 581 CS2; 582 * CS1 MUST be able play the role of a CUA and use [iMIP] 583 to interoperate with other CUAs. 585 +-----+ +-----+ 586 | | CAP | | CAP 587 CUA1------| CS1 |----------| CS2 |--------- CUA2 588 | | | | A 589 | | | | | 590 | | | | | 591 +-----+ +-----+ | 592 | IMIP | 593 +--------------------------------+ 595 Note that the fanout feature in CAP is a convenience to the 596 CUA. It is perfectly valid for the CUA to assume the 597 responsibility for fanout if it wishes. That is, [iMIP] 598 messages could also be sent from CUA1 to CUA2. 600 2.2 Calendar Store Object Model 601 CAP Expires September 2001 603 The conceptual model for a calendar store is shown below. The 604 calendar store contains calendars, VTIMEZONEs, VCARs, and 605 calendar store properties. 607 Calendars contain VEVENTs, VTODOs, VJOURNALs, VALARMs, VCARs, 608 and calendar properties. Calendars may also contain other 609 calendars. 611 Calendar Store 612 | 613 +-- VCARs 614 +-- Properties 615 +-- VCARs 616 +-- VTIMEZONEs 617 +-- VCALENDARs 618 | 619 +--VEVENTs 620 +--VALARMs 621 +--VTODOs 622 +--VALARMs 623 +--VJOURNALs 624 +--VCARs 625 +--Properties 626 +--VTIMEZONEs 627 +--VSCHEDULE 628 +--Calendar 629 | 630 +--VEVENTs 631 +--VALARMs 632 +--VTODOs 633 +--VALARMs 634 +--VJOURNALs 635 +--VALARMs 636 +--VCARs 637 +--Properties 638 +--VTIMEZONEs 639 +--VSCHEDULE 640 +--Calendar 641 | 642 ... 644 Calendars within a Calendar Store are identified by their 645 Relative CALID. 647 In this model, VSCHEDULE is a queue of scheduling messages 648 that have not yet been applied to the calendar. Items in 649 VSCHEDULE are discussed in more detail below. 651 CAP Expires September 2001 653 2.3 Protocol Model 655 A generic transfer-layer, Calendar Server Transfer Protocol 656 (CSTP), is used to move data objects between a CUA and the CS. 657 CSTP commands are listed below and their usage and semantics 658 are defined in section 7.1 of this document. 660 CSTP Commands 661 ----------------------------------------------------------- 662 Command Description 663 ----------------------------------------------------------- 664 ABORT Stop a command. Perhaps because its latency 665 time has been exceeded. 666 AUTHENTICATE Authenticate a UPN. 667 CONTINUE Continue the execution of a command whose 668 Latency time has been exceeded. 669 IDENTIFY Set a new identity for calendar access. 670 DISCONNECT Terminate a connection with the server. 671 SENDDATA Send a data object [MIME] encapsulated 672 iCalendar. 673 STARTTLS Negotiate transport level security using 674 [TLS]. 675 ----------------------------------------------------------- 677 Application-level commands are used to manipulate data on the 678 calendar store. They are listed below and discussed in detail 679 in section 7.2. 681 CAP Calendaring Commands 682 ----------------------------------------------------------- 683 Command Description 684 ----------------------------------------------------------- 685 CREATE Create a new calendar or component. 686 DELETE Delete a calendar or component. 687 GENERATEUID Generate one or more unique ids. 688 MODIFY Change a calendar or component. 689 MOVE Move a calendar. 690 READ Read a calendar properties or components. 691 ----------------------------------------------------------- 693 CAP Scheduling Commands 694 (As defined in [iTIP]) 695 ----------------------------------------------------------- 696 Command Description 697 ----------------------------------------------------------- 698 CAP Expires September 2001 700 PUBLISH Publish a calendar entry to one or more 701 calendars. 702 REQUEST Schedule a calendar entry with one or more 703 calendars. 704 REPLY Response to a scheduling request. 705 ADD Add one or more instances to an existing 706 calendar entry. 707 CANCEL Cancel one or more instances to an existing 708 calendar entry. 709 REFRESH A request for the latest version of a 710 calendar entry. 711 COUNTER A request for a change(a counter-proposal)to 712 a calendar entry. 713 DECLINECOUNTER Decline a counter proposal. 714 ----------------------------------------------------------- 716 2.4 Security Model 718 Authentication to the CS will be performed using [SASL]. 720 As noted in the CAP system model section, a variety of 721 connectivity scenarios are possible. This complicates the 722 security model considerably, and a thorough familiarity with 723 the concepts is required to ensure interoperability. 725 Basic threats to a Calendaring and Scheduling System include: 727 (1) Unauthorized access to data via data-fetching operations, 729 (2) Unauthorized access to reusable client authentication 730 information by monitoring others' access, 732 (3) Unauthorized access to data by monitoring others' access, 734 (4) Unauthorized modification of data, 736 (5) Unauthorized or excessive use of resources (denial of 737 service), and 739 (6) Spoofing of CS: Tricking a client into believing that 740 information came from the CS when in fact it did 741 not, either by modifying data in transit or 742 misdirecting the client's connection. 744 Threats (1), (4), (5) and (6) are due to hostile clients. 745 Threats (2), and (3) are due to hostile agents on the path 746 between client and server, or posing as a server. 748 CAP Expires September 2001 750 CAP can be protected with the following security mechanisms: 752 (1) Client authentication by means of the SASL mechanism 753 set, possibly backed by the TLS credentials exchange 754 mechanism, 756 (2) Client authorization by means of access control based 757 on the requestor's authenticated identity, 759 (3) Data integrity protection by means of the TLS protocol 760 or data integrity SASL mechanisms, 762 (4) Protection against snooping by means of the TLS 763 protocol or data encrypting SASL mechanisms, 765 (5) Resource limitation by means of administrative limits 766 on service controls, and 768 (6) Server authentication by means of the TLS protocol or 769 SASL mechanism. 771 Imposition of access controls (authorizations) is done by 772 means of VCARs, an overview is provided in section , 773 and a detailed syntax is provided in section . 774 Authentication is explained in detail in section . 776 2.4.1 Authentication, Credentials, and Identity 778 Generically, authentication credentials are the evidence 779 supplied by one party to another, asserting the identity of 780 the supplying party (e.g. a user) who is attempting to 781 establish an association with the other party (typically a 782 server). Authentication is the process of generating, 783 transmitting, and verifying these credentials and thus the 784 identity they assert. An authentication identity is the name 785 presented in a credential. 787 There are many forms of authentication credentials. The form 788 used depends upon the particular authentication mechanism 789 negotiated by the parties. For example: X.509 certificates, 790 Kerberos tickets, simple identity and password pairs. Note 791 that an authentication mechanism may constrain the form of 792 authentication identities used with it. 794 SASL only provides a protocol to negotiate a mutually 795 acceptable authentication mechanism. SASL itself does not 796 constrain or dictate the form of the authentication identities 797 used to perform the authentication. 799 CAP Expires September 2001 801 2.4.2 Calendar User and UPNs 803 A Calendar User(CU) is an entity that can be authenticated. It 804 is represented in CAP as a UPN. A UPN is the owner of a 805 calendar and the subject of access rights. The UPN 806 representation is independent of the authentication mechanism 807 used during a particular CUA/CS interaction. This is because 808 UPNs are used within VCARs. If the UPN were dependent on the 809 authentication mechanism, a VCAR could not be consistently 810 evaluated. A CU may use one mechanism while using one CUA but 811 the same CU may use a different authentication mechanism when 812 using a different CUA, or while connecting from a different 813 location. 815 The user may also have multiple UPNs for various purposes. 817 Note that the immutability of the user's UPN may be achieved 818 by using SASL's authorization identity feature. (The 819 transmitted authorization identity may be different than the 820 identity in the client's authentication credentials.) [SASL, 821 section 3] This also permits a CU to authenticate using their 822 own credentials, yet request the access privileges of the 823 identity for which they are proxying SASL. Also, the form of 824 authentication identity supplied by a service like TLS may not 825 correspond to the UPNs used to express a server's access 826 control policy, requiring a server-specific mapping to be 827 done. The method by which a server composes and validates an 828 authorization identity from the authentication credentials 829 supplied by a client is implementation-specific. 831 For Calendaring and Scheduling Systems that are integrated 832 with a directory system, the CS MUST support the ability to 833 configure which schema attribute stores the UPN. The CS MAY 834 allow one or more attributes to be searched for the UPN. 836 2.4.2.1 UPNs and Certificates 838 When using X.509 certificates for purposes of CAP 839 authentication, the UPN should appear in the certificate. 840 Unfortunately there is no single correct guideline for which 841 field should contain the UPN. 843 From RFC-2459, section 4.1.2.6 (Subject): 845 If subject naming information is present only in the 846 subjectAlt-Name extension (e.g., a key bound only to 847 an email address or URI), then the subject name MUST 848 CAP Expires September 2001 850 be an empty sequence and the subjectAltName extension 851 MUST be critical. 853 Implementations of this specification MAY use these 854 comparison rules to process unfamiliar attribute 855 types (i.e., for name chaining). This allows 856 implementations to process certificates with 857 unfamiliar attributes in the subject name. 859 In addition, legacy implementations exist where an 860 RFC 822 name is embedded in the subject distinguished 861 name as an EmailAddress attribute. The attribute 862 value for EmailAddress is of type IA5String to permit 863 inclusion of the character '@', which is not part of 864 the PrintableString character set. EmailAddress 865 attribute values are not case sensitive (e.g., 866 "fanfeedback@redsox.com" is the same as 867 "FANFEEDBACK@REDSOX.COM"). 869 Conforming implementations generating new 870 certificates with electronic mail addresses MUST use 871 the rfc822Name in the subject alternative name field 872 (see sec. 4.2.1.7 [of RFC 2459]) to describe such 873 identities. Simultaneous inclusion of the 874 EmailAddress attribute in the subject distinguished 875 name to support legacy implementations is deprecated 876 but permitted. 878 Since no single method of including the UPN in the certificate 879 will work in all cases, CAP implementations MUST support the 880 ability to configure what the mapping will be by the CS 881 administrator. Implementations MAY support multiple mapping 882 definitions, for example, the UPN may be found in either the 883 subject alternative name field, or the UPN may be embedded in 884 the subject distinguished name as an EmailAddress attribute. 886 Note: If a CS or CUA is validating data received via iMIP, if 887 the "ORGANIZER" or "ATTENDEE" property said (e.g.) 888 "ATTENDEE;CN=Joe Random User:juser@example.com" then the email 889 address should be checked against the UPN, and the CN should 890 also be checked. This is so the "ATTENDEE" property couldn't 891 be munged to something misleading like "ATTENDEE;CN=Joe Rictus 892 User:juser@example.com" and have it pass validation. This 893 validation will also defeat other attempts at confusion. 894 2.4.2.2 Anonymous Users and Authentication 895 CAP Expires September 2001 897 Anonymous access is often desirable. For example an 898 organization may publish calendar information that does not 899 require any access control for viewing or login. Conversely, a 900 user may wish to view unrestricted calendar information 901 without revealing their identity. 903 CAP implementations MUST support anonymous authentication, as 904 defined in section . 906 CAP implementations MAY support anonymous authentication with 907 TLS, as defined in section . 908 2.4.2.3 Required Security Mechanisms 910 The following implementation conformance requirements are in 911 place: 913 (1) For a read-only, public CS, anonymous authentication, 914 described in section , can be used. 916 (2) Implementations providing password-based authenticated 917 access MUST support authentication using Digest, as described 918 in section . This provides client authentication 919 with protection against passive eavesdropping attacks, but 920 does not provide protection against active intermediary 921 attacks. 923 (3) For a CS needing session protection and authentication, 924 the Start TLS extended operation, and either the simple 925 authentication choice or the SASL EXTERNAL mechanism, are to 926 be used together. Implementations SHOULD support 927 authentication with a password as described in section , and SHOULD support authentication with a certificate as 929 described in section . Together, these can provide 930 integrity and disclosure protection of transmitted data, and 931 authentication of client and server, including protection 932 against active intermediary attacks. 933 2.4.2.4 TLS Ciphersuites 935 The following ciphersuites defined in [RFC 2246] MUST NOT be 936 used for confidentiality protection of passwords or data: 938 TLS_NULL_WITH_NULL_NULL 939 TLS_RSA_WITH_NULL_MD5 940 TLS_RSA_WITH_NULL_SHA 942 The following ciphersuites defined in [RFC 2246] can be 943 cracked easily (less than a week of CPU time on a standard CPU 944 in 1997). The client and server SHOULD carefully consider the 945 CAP Expires September 2001 947 value of the password or data being protected before using 948 these ciphersuites: 950 TLS_RSA_EXPORT_WITH_RC4_40_MD5 951 TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 952 TLS_RSA_EXPORT_WITH_DES40_CBC_SHA 953 TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA 954 TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA 955 TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA 956 TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA 957 TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 958 TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA 960 The following ciphersuites are vulnerable to man-in-the-middle 961 attacks, and SHOULD NOT be used to protect passwords or 962 sensitive data, unless the network configuration is such that 963 the danger of a man-in-the-middle attack is tolerable: 965 TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 966 TLS_DH_anon_WITH_RC4_128_MD5 967 TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA 968 TLS_DH_anon_WITH_DES_CBC_SHA 969 TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 971 A client or server that supports TLS MUST support at least: 973 TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 974 2.4.3 User Groups 976 User Group is used to represent a collection of CUs or other 977 UGs that can be referenced in VCARS. A UG is represented in 978 CAP as a UPN. The CUA cannot distinguish between a UPN that 979 represents a CU or a UG. 981 UGs are expanded as necessary by the CS. The CS MUST accept a 982 CUA request for UG expansion, although the CS may be 983 configured to restrict some responses. The CS MAY expand a UG 984 (including nested UGs) to obtain a list of unique CUs. 985 Duplicate UPNs are filtered during expansion. Incomplete 986 expansion should be treated as a failure. 988 Groups may be in a directory with its own ACL model and CAP 989 should use the directory service to expand a UPN subject to 990 the directory service access control model for the 991 authenticated entity. 993 The CS SHOULD not preserve UG expansions across operations. A 994 UG may reference a static list of members, or it may represent 995 a dynamic list. Each operation SHOULD generate its own 996 CAP Expires September 2001 998 expansion in order to recognize changes to UG membership. 999 However, during fan out to other CSs, the originating CS 1000 SHOULD expand all UGs so that the target CS receives only a 1001 list of unique CUs. This is to prevent confusion when two CSs 1002 do not share the same UG database or directory. 1004 CAP does not define commands or methods for managing UGs. 1006 Small UG: 1007 The Three Stooges. There is only and always three at any 1008 one time. 1010 Large UG: 1011 The MIT graduating class of 1999. This is a static list. 1013 Dynamic UG: 1014 The IETF membership which is a large and changing list of 1015 members. 1017 Nested UG: 1018 The National Football League, made up of the AFC and NFC, 1019 which are made up of 3 divisions each... 1021 2.4.4 Access Rights - Summary 1023 Access rights are used to grant or deny access to a calendar 1024 for a CU. CAP defines a new component type called a Vcalendar 1025 Access Right (VCAR). Specifically, a VCAR grants, or denies, 1026 UPNs the right to read and write components, properties, and 1027 parameters on calendars within a CS. 1029 The VCAR model does not put any restriction on the sequence in 1030 which the object and access rights are created. That is, an 1031 event associated with a particular VCAR might be created 1032 before or after the actual VCAR is defined. In addition, the 1033 VCAR and VEVENT definition might be created in the same 1034 iCalendar object and passed together in a single command. 1036 All rights MUST be denied unless specifically granted; 1037 individual VCARs MUST be specifically granted to an 1038 authenticated CU. 1040 The access for a particular UPN is the union of all grants for 1041 that UPN minus the union of its denies. 1043 2.4.4.1 VCalendar Access Right (VCAR) 1044 CAP Expires September 2001 1046 Access rights within CAP are specified with the "VCAR" 1047 calendar component, "RIGHTS" value type and the "GRANT", 1048 "DENY" and "CARID" component properties. 1050 Properties within an iCalendar object are unordered. This also 1051 is the case for the "GRANT", "DENY" and "CARID" properties. 1052 Likewise, there is no implied ordering required for components 1053 of a "RIGHTS" value type other than that specified by the 1054 ABNF. [EDITOR'S NOTE, this requires a lot of review. We think 1055 that this paragraph may be incorrect. ] 1057 For details on the VCAR syntax please see section 1060 2.4.4.2 Decreed VCARs 1062 A CS MAY choose to implement and allow persistent immutable 1063 VCARs, that are configured by the CS Administrator, which 1064 apply to all calendars on the server. 1066 When a user attempts to modify a decreed VCAR an error will be 1067 returned, indicating that the user has insufficient 1068 authorization to perform the operation. 1070 The CAP protocol does not define the semantics used to 1071 initially create a decreed VCAR. This administrative task is 1072 out side the scope of the CAP protocol. 1074 For example an implementation or a CS administrator may wish 1075 to define a VCAR that will always allow the calendar owners to 1076 have full access to their own calendars. The GRANT property 1077 allows the OWNERs all (OBJECT=*) access to their own calendar 1078 objects. The DENY property disallows anyone (UPN=*) from 1079 being able to delete or modify this VCAR. 1081 BEGIN:VCAR 1082 CARID:Users Default Access 1083 GRANT:UPN=OWNER;OBJECT=*;OBJECT=OBJECT=METHOD;VALUE=* 1084 DENY:UPN=*;OBJECT=VCAR;OBJECT=CARID; 1085 VALUE="Users Default Access" 1086 ;OBJECT=METHOD,VALUE=DELETE,MODIFY 1087 END:VCAR 1089 Decreed VCARs MUST be readable by the calendar owner in 1090 standard VCAR format. 1092 2.4.5 Inheritance 1093 CAP Expires September 2001 1095 Calendars inherit VCARs from their parent calendar. Calendars 1096 whose parent is the Calendar Store inherit VCARs from the 1097 Calendar Store. 1099 VCARs specified in a calendar or a sub-calendar override all 1100 inherited VCARs. 1102 2.4.6 CAP Session Identity 1104 A CAP session has an associated set of authentication 1105 credentials, from which is derived a UPN. This UPN is the 1106 identity of the CAP session, and is used to determine access 1107 rights for the session. 1109 The CUA may change the identity of a CAP session by calling 1110 the "IDENTIFY" command. The Calendar Service only permits the 1111 operation if the session's authentication credentials are good 1112 for the requested identity. The method of checking this 1113 permission is implementation dependent, but may be thought of 1114 as a mapping from authentication credentials to UPNs. The 1115 "IDENTIFY" command allows a single set of authentication 1116 credentials to choose from multiple identities, and allows 1117 multiple sets of authentication credentials to assume the same 1118 identity. 1120 For anonymous access the identity of the session is "@", a UPN 1121 with a null username and null realm. A UPN with a null 1122 username, but non-null realm, such as "@foo.com" may be used 1123 to mean any identity from that realm, which is useful to grant 1124 access rights to all users in a given realm. A UPN with a non- 1125 null username and null realm, such as "bob@" could be a 1126 security risk and MUST NOT be used. 1128 Since the UPN includes realm information it may be used to 1129 govern calendar store access rights across realms. However, 1130 governing access rights across realms is only useful if login 1131 access is available. This could be done through a trusted 1132 server relationship or a temporary account. 1134 The "IDENTIFY" command provides for a weak group 1135 implementation. By allowing multiple sets of authentication 1136 credentials belonging to different users to identify as the 1137 same UPN, that UPN essentially identifies a group of people, 1138 and may be used for group calendar ownership, or the granting 1139 of access rights to a group. 1141 Examples: 1143 Small UG: 1145 CAP Expires September 2001 1147 The Three Stooges. There will always be three, it 1148 will not change. 1150 Large UG: 1151 The MIT graduating class of 1999. This is a static 1152 list. 1154 Dynamic UG: 1155 The IETF membership, which is a large and changing 1156 list of members. 1158 Nested UG: 1159 The National Football League, made up of the AFC and 1160 NFC, which are made up of 3 divisions each. 1162 2.5 Roles 1164 CAP defines methods for managing [iCAL] objects on a Calendar 1165 Store and exchanging [iCAL] objects for the purposes of group 1166 calendaring and scheduling between "Calendar Users" (CUs) or 1167 "User Groups" (UGs). There are two distinct roles taken on by 1168 CUs in CAP. The CU who creates an initial event or to-do and 1169 invites other CUs or UGs as attendees takes on the role of 1170 "Organizer". The CUs or UGs asked to participate in the group 1171 event or to-do take on the role of "Attendee". Note that 1172 "role" is also a descriptive parameter to the "ATTENDEE" 1173 property. Its use is to convey descriptive context to an 1174 "Attendee" such as "chair", "REQ-PARTICIPANT" or "NON- 1175 PARTICIPANT" and has nothing to do with the scheduling 1176 workflow. 1178 2.6 Calendar Addresses 1180 Calendar addresses are URIs that are modeled after URLs [URL]. 1181 CAP uses the following forms of URI. 1183 [[]://[:]/] 1185 where: 1187 is "cap", the protocol described in this 1188 memo. 1190 is the Calendar Store ID. It is the network 1191 address of the computer on which the CAP server is 1192 running. 1194 CAP Expires September 2001 1196 is optional. Its default value is 5229. The 1197 port must be present in the URL if the CAP server 1198 does not listen on this default port of 5229. 1200 is an identifier that uniquely 1201 identifies the calendar on a particular calendar 1202 store. There is no implied structure in a Relative 1203 CALID. It is an arbitrary string of printable 7 bit 1204 ASCII characters. It may refer to the calendar of a 1205 user or of a resource such as a conference room. It 1206 MUST be unique within the calendar store. It is 1207 recommended that the Relative CALID be globally 1208 unique. 1210 If the and are present the calendar address is 1211 said to be "qualified". Senders are required to supply the 1212 portion of the address. A qualified calendar 1213 address is required when the of the target calendar 1214 address differs from that of the CAP server receiving the 1215 command. 1217 Examples of CAP URIs: 1219 cap://calendar.example.com/user1 1220 ://calendar.example.com/user1 1221 user1 1222 cap://calendar.example.com/conferenceRoomA 1223 cap://calendar.example.com/89798-098-zytytasd 1225 For a user currently authenticated to a CAP server on 1226 calendar.example.com, the first three addresses refer to the 1227 same calendar. 1229 2.7 Extensions to iCalendar 1231 In mapping the CAP command set, query feature, and access 1232 rights onto the iCalendar format, several extended iCalendar 1233 methods and components are defined by this memo. 1235 * The search function is specified with the new 1236 iCalendar QUERY method. The QUERY method makes use of 1237 a new component, called VQUERY, that contains the 1238 search filter. The component consists of a set of new 1239 properties: EXPAND, MAXRESULTS, MAXRESULTSSIZE, QUERY 1240 and QUERYNAME, that define the search filter. Note 1241 that QUERY simply is the filter that is used by the CS 1242 to select the data used in METHOD:READ, METHOD:CREATE, 1243 CAP Expires September 2001 1245 METHOD:MODIFY, METHOD:DELETE, any other METHOD that is 1246 defined to use a QUERY filter. 1247 * Access control is specified the the new iCalendar VCAR 1248 component. 1249 * The iCalendar METHOD property format has been updated 1250 with new values. 1251 * A new iCalendar component, VCOMMAND, has been added. 1252 VCOMMANDs are needed to specify CAP commands. 1253 * TARGET is a new property within the VCOMMAND 1254 component. It indicates the calendars to which the 1255 command applies 1256 * CMDID is a Command ID that is used in a VCOMMAND to 1257 uniquely identify a command. Responses to a VCOMMAND 1258 will contain the same CMDID. 1260 2.8 Relationship of RFC 2446 (ITIP) to CAP 1262 [iTIP] describes scheduling methods which result in indirect 1263 manipulation of calendar components. CAP methods provide 1264 direct manipulation of calendar components. In the CAP 1265 calendar store model, scheduling messages are conceptually 1266 kept separate from other calendar components. This is modeled 1267 with the VSCHEDULE queue. Note that this is a conceptual 1268 model, the actual storage details are left to implementations. 1269 The model is shown pictorially as follows: 1271 +-----------------VCALENDAR-------------------+ 1272 | | 1273 | +-----------+ +-------VSCHEDULE---------+ | 1274 | | VEVENTs | | PUBLISH messages | | 1275 | | VTODOs | | REQUEST messages | | 1276 | | VJOURNALs | | REPLY messages | | 1277 | | | | ADD messages | | 1278 | | | | CANCEL messages | | 1279 | | | | REFRESH messages | | 1280 | | | | COUNTER messages | | 1281 | | | | DECLINECOUNTER messages | | 1282 | +-----------+ +-------------------------+ | 1283 +---------------------------------------------+ 1285 The METHOD is saved along with components. Scheduled 1286 components become booked components when the METHOD changes 1287 from an ITIP method to the CAP storage method CREATE. For 1288 example, a component whose METHOD is "REQUEST" is scheduled. 1289 The component becomes booked when the METHOD is changed to 1290 "CREATED". 1292 CAP Expires September 2001 1294 Several scheduled entries can be in the CS for the same UID. 1295 They are consolidated when booked. Or they are removed from 1296 the CS. 1298 For example, if you were on vacation, you could have a REQUEST 1299 to attend a meeting and several updates to that meeting. Your 1300 CUA would have to READ them out of the CS using CAP, process 1301 them, determine what the final state of the object from a 1302 possible combination of user input and programmed logic. Then 1303 the CUA would instruct the CS to CREATE a new booked entry or 1304 MODIFY an existing entry. Followed by a DELETE of all of these 1305 now old scheduling requests in the CS. See [iTIP] for details 1306 on resolving multiple [iTIP] scheduling entries. 1308 CAP Expires September 2001 1310 3 State Diagram 1312 This section describes the states of the transport connection 1313 between a CUA and a CS. The state diagram is shown below. 1314 State names are shown with first letter capitalized. Commands 1315 used to switch between states are shown next to an arrow 1316 connecting the states. The commands are listed in all capital 1317 letters. A condition that causes a state to change is shown in 1318 lower case letters. 1320 STARTTLS / 1321 CAPABILITY 1322 +-------+ 1323 | | +---------------+ 1324 | +-----------+ AUTHENTICATE | | 1325 +-->| Connected |-------------->| Authenticated | 1326 +-----------+ | | 1327 | +---------------+ 1328 | | 1329 | | +-----+ 1330 | V | |STARTTLS / 1331 | +---------------+ |IDENTIFY 1332 | | |<-+ 1333 | | Identified |<-----+ 1334 | +--------| | | 1335 | | +---------------+ | 1336 | | | command| 1337 V |DISCONNECT | completes| 1338 +--------------+ | | | 1339 | Disconnected |<--+ | | 1340 +--------------+ |SENDDATA | ABORT 1341 A | | 1342 | V | 1343 | DISCONNECT +---------------+ | 1344 +--------------------| Receive |------+ 1345 | |<--+ 1346 +---------------+ | 1347 | | 1348 +----+ 1349 CONTINUE 1351 The connection begins the Connected state when a CUA connects 1352 to a CAP server. The capabilities of the CS are reported in 1353 the response from the CS. From this state, the CUA can issue 1354 the DISCONNECT command to terminate the connection, the 1355 CAPABILITY, STARTTLS, or AUTHENTICATE commands. One use of the 1356 CAPABILITY command at this stage is to determine the supported 1357 CAP Expires September 2001 1359 authentication mechanisms supported by the server. Once the 1360 STARTTLS command has been successfully executed from either 1361 the Connected or Authenticated state, it must not be executed 1362 again. 1364 If an AUTHENTICATE command is successful, the connection 1365 enters the Authenticated state and then immediately goes to 1366 the IDENTIFIED state. While in the Identified state, allow 1367 CALIDEXPAND and UPNEXPAND commands. From here the CUA can 1368 issue the CAPABILITY command. The capabilities the server 1369 offers in the Authenticated state may be different than those 1370 in the Connected state to allow for the users realm to be used 1371 to grant or deny features. The CUA can also use the IDENTIFY 1372 command to change the identity of the user subject to access 1373 control. The connection remains in the Authenticated state 1374 after the CAPABILITY command completes. The CUA can issue the 1375 DISCONNECT command to terminate the connection. The SENDDATA 1376 command can be used to send a request to read, write, modify, 1377 or delete data on the server. 1379 After the SENDDATA command has been issued the connection 1380 enters the Receive state while the CUA awaits and reads a 1381 server reply. Normally, the server handles the command, sends 1382 a reply which is read by the CUA and the connection returns to 1383 the Authenticated state. The CUA may have issued the SENDATA 1384 command with a maximum latency time. This informs the server 1385 that the CUA expects a response within the maximum latency 1386 time, even if the command was not completed. When the server 1387 is unable to complete the command in the maximum latency time, 1388 it issues an appropriate reply code and waits for the CUA to 1389 tell it how to proceed. If the CUA issues a CONTINUE command 1390 the server continues processing the command and the connection 1391 remains in the Receive state. If the CUA issues the ABORT 1392 command the server need not process the command any further 1393 and the connection returns to the Authenticated state. The 1394 DISCONNECT command can also be issued from the Receive state. 1396 4 Protocol Framework 1398 4.1 CAP Application Layer 1400 The CAP application layer is used for the manipulation of the 1401 calendar store. Commands and responses are transmitted between 1402 the CUA and CS inside "VCALENDAR" component wrappers. Commands 1403 are specified as the value of a "METHOD" property, and 1404 responses are specified as the value of a "REQUEST-STATUS" 1405 property. 1407 CAP Expires September 2001 1409 4.2 CAP Transfer Protocol 1411 The CAP transfer protocol defines the format of data 1412 transmitted between a CUA and the CS. 1414 CAP transfer protocol commands are transmitted using the 1415 underlying transport. The transport used is a TCP/IP socket 1416 connection between the CUA and the CS. The default port that 1417 the CS listens for connections on is port 5229. 1419 Messages sent between the CUA and CS are formatted as a 1420 command followed by any associated data: 1422 [] 1424 Response Format 1426 Server responses consist of a response code and any 1427 parameters: 1429 [response-args] [; debug-text ] 1430 . 1431 [] 1432 . 1434 The response-args are defined in Section 8. The debug-text is 1435 human-readable information for protocol debugging and is 1436 optional and is only used to aid developers writing CSs and 1437 CUAs. The debug-text MUST not be depended on by CUAs in 1438 normal interactions with a CS. 1440 The optional application-data begins on the next line. 1442 The response is terminated with the second "." 1443 sequence. Any "." sequences which appear in the 1444 transmitted data must be quoted by placing an additional "." 1445 between the and the ".". For example, the following 1446 sequences of characters in the application data: 1448 . 1449 ..2 1450 ...3 1452 are quoted as follows: 1454 .. 1455 ...2 1456 ....3 1457 CAP Expires September 2001 1459 4.3 Pipelining of Commands 1461 If the CS returns a PIPELINE number greater then one (1) as a 1462 result of a CAPABILITY command the CUA can send up to PIPELINE 1463 VCOMMANDS without waiting for the CS to reply. 1465 4.4 Auto-logout Timer 1467 If a server has an inactivity auto-logout timer, that timer 1468 MUST be of at least 15 minutes duration if there is no value 1469 of AUTOLOGOUTTIME returned in the CS CAPABILITY reply. The 1470 receipt of ANY command from the client during that interval 1471 MAY reset the auto-logout timer, subject to CS administrators 1472 policy. A CUA may be discouraged from attempts to do useless 1473 things only to keep the connection alive. 1475 A CS MAY have different AUTOLOGOUTTIME values depending on the 1476 UPN or the realm of the UPN. 1478 When a timeout occurs, the server drops the connection to the 1479 CUA. 1481 4.5 Bounded Latency 1483 CAP is designed so that the CUA can either obtain an immediate 1484 response from a request or discover within a specified amount 1485 of time that the request could not be completed in the 1486 requested amount of time. When the CUA initiates a command 1487 that the server cannot complete within the specified latency 1488 time, the server returns an appropriate response code. The CUA 1489 then issues either a CONTINUE or ABORT command. The ABORT 1490 command immediately terminates the command in progress 1491 identified by CMDID and the connection returns to the 1492 Authenticated state. The CONTINUE command instructs the 1493 server to continue processing the command identified by the 1494 CMDID. 1496 4.6 Data Elements 1498 The data elements for CAP are [MIME] encapsulated iCalendar 1499 objects. 1501 5 Formal Command Syntax 1502 5.1 Searching and Filtering 1503 CAP Expires September 2001 1505 This section describes CAPs selecting and filtering entities 1506 within a calendar store. It is based on the Standard Query 1507 Language (SQL) defined in [SQL]. 1509 5.1.1 Grammar For Search Mechanism 1511 search = "BEGIN:VQUERY" CRLF 1512 [expand] [maxresults] [maxsize] querycomp 1513 "END:VQUERY" CRLF 1515 expand = "EXPAND" ":" ( "TRUE" / "FALSE") 1516 # the default is EXPAND:FALSE 1518 comp-name = "VEVENT" / "VTODO" / "VJOURNAL" 1519 / "VTIMEZONE" / "VALARM" / "VFREEBUSY" 1520 / "VCAR" / iana-name / x-name 1522 maxresults = integer 1524 maxsize = integer 1526 querycomp = ( query ) / ( queryname query ) / queryname 1528 queryname = "QUERYNAME:" text 1530 query = "QUERY:" ( query-min / query-92 ) 1531 # 1532 # NOTE: query-min MUST be implemented in CSs. 1533 # 1534 # query-92 is ONLY used if CAPABILITY returns SQL-92 1535 # as the QUERYLEVEL value or if QUERYLEVEL is not 1536 # specified. 1537 # 1539 query-min = capselect-min capfrom-min capwhere-min 1541 capselect-min = "SELECT" capmin-cols "FROM" capmin-comps 1542 "WHERE" capmin-cmp 1544 capmin-col = # Any property name found in any of the 1545 components. 1547 capmin-cols = ( capmin-col / capmin-col "," 1548 capmin-cols ) 1550 capmin-comps = ( comp-name / comp-name "," 1551 compmin-comps ) 1552 CAP Expires September 2001 1554 capmin-cmp = ( colname cmpmin-oper colvalue 1555 / colname cmpmin-oper colvalue 1556 capmin-logical capmin-cmp ) 1558 colname = ( # Any valid component property name. 1559 / "*" ) 1561 cmpmin-oper = ( " = " / " != " / " < " / " > " / " <= " 1562 / " >= " ) 1564 capmin-logical = ( " AND " / " OR " ) 1566 query-92 = capselect-92 capfrom-92 capwhere-92 1567 caporderby-92 1569 capselect-92 = # Any valid [SQL] string that goes into 1570 a SELECT clause. 1572 capfrom-92 = # Like capmin-comps except embedded spaces 1573 # are allowed between commas - per [SQL]. 1575 capwhere-92 = # Any valid [SQL] string that goes into a 1576 # WHERE clause. 1578 caporderby-92 = # Any valid [SQL] string that goes into a 1579 # ORDERBY clause. 1581 5.1.2 SQL-MIN notes 1583 (1) No inlined spaces are allowed if not in the grammar above. 1585 (2) Note that cmpmin-oper and capmin-logical elements are 1586 surrounded by exactly one space. 1588 Use 'VEVENT,VTODO', not 'VEVENT, VTODO' 1589 Use 'DTSTART <= 20000605T131313Z', not 1590 'DTSTART<= 20000605T131313Z'. 1591 Use ' AND ' and ' OR ', not 'AND' and not 'OR'. 1593 (3) There is no ORDERBY. Sorting will take place in the order 1594 the columns are supplied in the command. 1596 (4) The CS MUST sort at least the first column.The CS MAY sort 1597 additional columns. 1599 (5) If EXPAND=FALSE and if colname is "*" sorting will be by 1600 the DTSTART value ascending. 1602 CAP Expires September 2001 1604 If EXPAND=TRUE and if colname is "*" sorting will be by 1605 the RECURRENCE-ID value ascending. 1607 If colname is "*" and capmin-coms is VALARM only then 1608 sorting will be by TRIGGER time in GMT ascending. 1610 (6) SQL-MIN MUST be implemented. 1612 5.1.3 SQL-92 notes 1614 (1) Although this memo specifies that any [SQL] query can be 1615 used, some of the [SQL] grammar is optional and therefore is 1616 considered optional in CSs advertising an SQL-92 1617 implementation with CAPABILITY. 1619 (2) A CS implementation MAY implement SQL-92. If a CS does not 1620 implement SQL-92 then it MUST advertise SQL-MIN in the 1621 capability reply. 1623 5.1.4 Example, Query by UID 1625 This example would select the entire contents of uid123 and 1626 not expand any multiple instances of the component. If the 1627 CUA does not know if 'uid123' was a VEVENT, VTODO, VJOURNAL, 1628 or other component, then all components that the CUA supports 1629 MUST be supplied on the QUERY property. This example assumes 1630 the CUA only supports VTODO and VEVENT. 1632 If the results were empty it could also mean that 'uid123' was 1633 a property in a component other than a VTODO or VEVENT. 1635 BEGIN:VQUERY 1636 QUERY:SELECT * FROM VEVENT,VTODO WHERE UID = 'uid123' 1637 END:VQUERY 1639 This example would select the entire contents of uid123 and 1640 would expand any instances of the component after applying any 1641 recurrence rules. This query could select multiple instances 1642 of components each with the same UID. Each instance would 1643 have a unique RECURRENCE-ID of the expanded component. 1645 BEGIN:VQUERY 1646 EXPAND:TRUE 1647 QUERY:SELECT * FROM VEVENT,VTODO WHERE UID = 'uid123' 1648 END:VQUERY 1650 5.1.5 Query by Date-Time range 1651 CAP Expires September 2001 1653 This query selects the entire contents of every booked VEVENT 1654 that has an instance less than or equal to July 31st, 2000 1655 23:59:59 Z and greater than or equal to July 1st, 2000 1656 00:00:00 Z 1658 BEGIN:VQUERY 1659 EXPAND:TRUE 1660 QUERY:SELECT * FROM VEVENT 1661 WHERE RECURRENCE-ID >= '20000801T000000Z' 1662 AND RECURRENCE-ID <= '20000831T235959Z' 1663 AND METHOD = 'CREATE' 1664 END:VQUERY 1666 5.1.6 Query for all Non-Booked Entries 1667 This example selects the entire contents of all scheduling 1668 (non-booked) VEVENTS in the CS. The default for EXPAND is 1669 FALSE, so the recurrence rules will not be expanded. 1671 BEGIN:VQUERY 1672 QUERY:SELECT * FROM VEVENT,VTODO WHERE METHOD != 'CREATE' 1673 END:VQUERY 1675 The following example fetches the UIDs of all non-booked 1676 VEVENTs and VTODOs. 1678 BEGIN:VQUERY 1679 QUERY:SELECT UID FROM VEVENT,VTODO WHERE METHOD != 'CREATE' 1680 END:VQUERY 1682 5.1.7 Query with Subset of Properties by Date/Time 1684 This MUST implement is similar to the one above, except only 1685 the named properties will be selected and all booked and non- 1686 booked components will be selected that have a DTSTART from 1687 Feb 1st to Feb 10th. 1689 BEGIN:VQUERY 1690 QUERY:SELECT UID,DTSTART,DESCRIPTION,SUMMARY FROM VEVENT 1691 WHERE DTSTART >= '20000201T000000Z' 1692 AND DTSTART <= '20000210T235959Z' 1693 END:VQUERY 1695 5.1.8 Components With Alarms In A Range 1696 This example fetches all components with an alarm that 1697 triggers within the specified time range. In this case only 1698 the UID, SUMMARY, and DESCRIPTION will be selected for all 1699 booked VEVENTS that have an alarm between the two date-times. 1701 CAP Expires September 2001 1703 BEGIN:VQUERY 1704 EXPAND:TRUE 1705 QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT 1706 WHERE VALARM.TRIGGER >= '20000101T030405Z' 1707 AND VALARM.TRIGGER <= '20001231T235959Z' 1708 AND METHOD = 'CREATE' 1709 END:VQUERY 1711 6 Access Rights 1713 Access rights within CAP are specified with the "VCAR" 1714 calendar component, "RIGHTS" value type and the "GRANT", 1715 "DENY" and "CARID" component properties. 1717 Individual calendar access rights MUST be specifically granted 1718 to an authenticated calendar user (i.e., UPN); all rights are 1719 denied unless specifically granted. 1721 Properties within a VCAR must be evaluated in the order 1722 provided. 1724 6.1 VCAR Inheritance 1726 Calendar access rights specified in a calendar store are 1727 inherited as default calendar access rights for any calendar 1728 in the parent calendar store. Likewise, any calendar access 1729 rights specified in a root calendar are inherited as default 1730 calendar access rights for any sub- calendar to the root 1731 calendar. By implication, calendar access rights specified in 1732 a sub-calendar are inherited as default calendar access rights 1733 for any calendars that are hierarchically below the sub- 1734 calendar. 1736 Calendar access rights specified in a calendar override any 1737 default calendar access rights. Calendar access rights 1738 specified within a sub-calendar override any default calendar 1739 access rights. 1741 6.2 Access Control and NOCONFLICT 1743 The TRANSP property can take on values (TRANSPARENT- 1744 NOCONFLICT, OPAQUE-NOCONFLICT) that prohibit other events from 1745 overlapping it. This setting overrides access While access 1746 control may allow a UPN to store an event on a particular 1747 calendar. , the CONFLICTS Calendar or component setting may 1748 prevent it, returning an error code "6.3" 1749 CAP Expires September 2001 1751 7 Commands and Responses 1753 CAP commands and responses are described in this section. 1755 Command arguments, identified by "Arguments:" in the command 1756 descriptions below, are described by function, not by syntax. 1757 The precise syntax of command arguments is described in the 1758 Formal Syntax section. 1760 Some commands cause specific server data to be returned; these 1761 are identified by "Data:" in the command descriptions below. 1762 See the response descriptions in the Responses section for 1763 information on these responses, and the Formal Syntax section 1764 for the precise syntax of these responses. 1766 The "Result:" in the command description refers to the 1767 possible status responses to a command, and any special 1768 interpretation of these status responses. 1770 Commands have the general form: 1772 [arguments...] 1774 where is a command listed in the table above. A 1775 command MAY have arguments. Arguments are defined in the 1776 detailed command definitions below. 1778 Responses to commands have the following general form: 1780 responseCode [sep transportDescr sep 1781 [applicationDescr]] 1782 CRLF "." CRLF 1784 In the examples below, lines preceded with "S:" refer to the 1785 sender and lines preceded with "R:" refer to the receiver. 1786 Lines in which the first non-whitespace character is a "#" are 1787 editorial comments and are not part of the protocol. 1789 7.1 Transfer Protocol Commands 1791 7.1.1 Initial Connection 1793 Arguments: none 1795 Data: none 1796 CAP Expires September 2001 1798 Result: 2.0 - success. 1799 8.1 - server too busy 1801 Upon session startup, the server sends a response of 2.0 to 1802 indicate that it is ready to receive commands. A response of 1803 8.1 indicates that the server is too busy to accept the 1804 connection. In addition, the general capabilities of the CS 1805 are reported in the response from the CS. These capabilities 1806 may be different than those reported in the authenticated 1807 state. 1809 7.1.2 ABORT Command 1811 Arguments: [CMDID] 1813 Data: none 1815 Result: 2.0 - success 1816 2.2 - no command is in progress 1818 The ABORT command is issued by the CUA to stop a command. A 1819 common usage could be to ABORT a command whose latency time 1820 has been exceeded. When the latency time is specified on the 1821 SENDATA command, the CS must issue a reply to the CUA within 1822 the specified time. It may be a reply code indicating that the 1823 CS has not yet processed the request. The CUA must then tell 1824 the server whether to continue or abort. 1826 The CUA can issue the ABORT command at any time after the 1827 SENDATA command has been completed but before receiving a 1828 reply. 1830 If CMDID is supplied then the command identified by CMDID is 1831 aborted. 1833 If CMDID is not supplied then the fist command that is still 1834 pending is aborted. 1836 7.1.3 AUTHENTICATE Command 1838 Arguments: [] 1840 Data: continuation data may be requested 1842 Result: 1843 2.0 - Authenticate completed, now in authenticated 1844 CAP Expires September 2001 1846 state. 1847 6.0 - Failed authentication. 1848 6.1 - Authorization identity refused. 1849 6.2 - Sender aborted authentication, authentication 1850 exchange cancelled. 1851 6.3 - Unsupported Authentication Mechanism. 1852 6.4 - Temporary failure (back end authentication 1853 server down). 1854 6.5 - Authentication exchange cancelled. 1855 6.6 - Authentication mechanism too weak. 1856 6.7 - Encryption required. 1857 6.8 - Pass phrase expired. The pass phrase was 1858 correct but expired. The user will have to 1859 contact a pass phrase change server prior to 1860 authenticating. 1861 6.9 - The user is valid but the server does not 1862 have an entry in the authentication database 1863 for the requested mechanism (e.g., DIGEST- 1864 MD5). If the user successfully authenticates 1865 using a plain text password, then the back 1866 end back end entry will be updated. Note 1867 that if the client chooses to fall back to 1868 plain text password authentication it should 1869 enable an encryption layer or get user-con- 1870 firmation that a one-time transition is ac- 1871 ceptable. 1872 6.10 - User account disabled. The user will have to 1873 contact the system administrator to get the 1874 account re-enabled. 1875 9.1 - Unexpected command. 1877 The capabilities of the CS in the authenticated state are 1878 reported in the response from the CS. These may be different 1879 than the capabilities in the Connected, but unauthenticated 1880 state. 1882 The AUTHENTICATE command is used by the CUA to identify the 1883 user to the CS. CAP supports a number of authentication 1884 methods, the SASL specification for authentication is the 1885 preferred method. 1887 If STARTTLS is negotiated prior to the AUTHENTICATE command, 1888 the client MUST discard all information about the CS 1889 capabilities fetched prior to the TLS negotiation. In 1890 particular, the value of supported SASL Mechanisms MAY be 1891 different after TLS has been negotiated. 1893 CAP Expires September 2001 1895 If a SASL security layer is negotiated, the client MUST 1896 discard all information about the CS capabilities fetched 1897 prior to SASL. In particular, if the client is configured to 1898 support multiple SASL mechanisms, it SHOULD fetch supported 1899 SASL Mechanisms both before and after the SASL security layer 1900 is negotiated and verify that the value has not changed after 1901 the SASL security layer was negotiated. This detects active 1902 attacks which remove supported SASL mechanisms from the 1903 supported SASL Mechanisms list. 1905 is an optional parameter which can be used for 1906 mechanisms which require an initial response from the CUA. 1908 The AUTHENTICATE command is followed by an authentication 1909 protocol exchange, in the form of a series of CS challenges 1910 and CUA responses, per the relevant RFC that describes the 1911 specific SASL mechanism being used. 1913 Cancelling the authentication process during its negotiation 1914 is implementation specific and not within scope of the CAP 1915 specification. 1917 If a security layer was negotiated it comes into effect for 1918 the CS starting with the first octet transmitted after the 1919 CRLF which follows the 2.0 reply code, and for the CUA 1920 starting with the first octet after the CRLF of its last 1921 response in the authentication exchange. Encrypted data is 1922 transmitted as described in SASL. 1924 The service name specified by this protocol's profile of SASL 1925 is "cap". [EDITORS NOTE: this must be registered with IANA, 1926 has anyone done this yet?] 1928 The result of the AUTHENTICATE command includes data 1929 indicating the identity which has been assigned to the 1930 session, derived from the supplied authentication credentials, 1931 and/or authorization identifier. A CAP session does not have 1932 an identity until the CUA has issued the "AUTHENTICATE" 1933 command. 1935 The CUA may not issue the "AUTHENTICATE" command multiple 1936 times, even if the first attempt was aborted. If a CUA 1937 attempts to do this the CS must terminate the session. 1939 Here is an example of a successful authentication: 1941 C: AUTHENTICATE KERBEROS_V4 1942 S: AmFYig== 1943 CAP Expires September 2001 1945 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT 1946 S: or//EoAADZI= 1947 C: DiAF5A4gA+oOIALuBkAAmw== 1948 S: 2.0 1949 S: . 1950 S: Content-Type:text/calendar; method=REQUEST; 1951 S: charset=US-ASCII 1952 S: Content-Transfer-Encoding: 7bit 1953 S: 1954 S: BEGIN:VCAP 1955 S: PRODID:-//ACME/CAPserver//EN 1956 S: VERSION:2.1 1957 S: IDENTITY=bill@example.com 1958 S: CAPVERSION=1.0 1959 S: ITIPVERSION=1.0 1960 S: AUTH=KERBEROS_V4 1961 S: AUTH=DIGEST_MD5 1962 S: CAR=CAR-FULL-1 1963 S: MINDATE=19700101T000000Z 1964 S: MAXDATE=20370201T000000Z 1965 S: END:VCAP 1966 S: . 1968 This example shows a failed authentication: 1970 C: AUTHENTICATE KERBEROS_V4 1972 S: AmFYig== 1973 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT 1974 S: . 1975 S: 6.0 1976 S: . 1977 S: . 1979 7.1.3.1 AUTHENTICATE ANONYMOUS 1981 RFC-2245 defines the Anonymous SASL mechanism. This RFC states 1982 that "the mechanism consists of a single message from the 1983 client to the server. The client sends optional trace 1984 information in the form of a human readable string. The trace 1985 information should take one of three forms: an Internet email 1986 address, an opaque string which does not contain the '@' 1987 character and can be interpreted by the system administrator 1988 of the client's domain, or nothing. For privacy reasons, an 1989 Internet email address should only be used with permission 1990 from the user." 1991 CAP Expires September 2001 1993 RFC-2245 goes on to state, "A client which uses the user's 1994 correct email address as trace information without explicit 1995 permission may violate that user's privacy." Information about 1996 who accesses an anonymous CS on a sensitive subject (e.g., AA 1997 meeting times and locations) has strong privacy needs. 1998 "Clients should not send the email address without explicit 1999 permission of the user and should offer the option of 2000 supplying no trace token -- thus only exposing the source IP 2001 address and time." 2003 Example of CUA using the Capability command followed by an 2004 anonymous authentication: 2006 C: CAPABILITY 2007 S: 2.0 2008 S:CAPVERSION=1.0 2009 S:AUTH=KERBEROS_V4 2010 S:AUTH=DIGEST_MD5 2011 S:AUTH=ANONYMOUS 2012 S:. 2013 C:AUTHENTICATE ANONYMOUS 2014 S:+ 2015 C:c21yaGM= 2016 S:2.0 2018 Subsequent to the initial Anonymous Authentication with a CS, 2019 a CUA will have to provide a UPN for some CAP operations. For 2020 anonymous access the UPN that MUST be used by the CUA is "@", 2021 a UPN with a null username and null realm. The user's normal 2022 UPN MUST not be used for the subsequent CAP operations. 2024 Note that the CS implementation may have internal audit logs 2025 that use the user's asserted UPN as trace information. 2026 However, this UPN will not appear on the wire after the 2027 initial SASL anonymous authentication. 2029 Use of the "@" UPN and wild-carding of UPNs within VCARs are 2030 covered in 2032 Section . 2034 7.1.4 CALIDEXPAND Command 2036 Arguments: CalID 2038 Data: no specific data for this command 2040 Result: 2.0 Successful, and requested data follows 2041 CAP Expires September 2001 2043 2.1 Permission Denied 2044 2.2 Requested CSID not found 2045 2.3 Result exceeds MAXEXPANDLIST 2046 2.4 Misc. EXPAND error 2048 Return the members of the argument CalID. Successful result 2049 yields one or more Calendars and/or Resource Calendars. More 2050 than one C or RC returned implies that the CalID was a CC. 2052 Example: 2054 Example #1: Request lookup of CSID which is a Calendar 2055 Collection 2057 C: CALIDEXPAND cap://cal.example.com/calid14 2058 S: 2.0 cap://cal.example.com/calid14 2059 S: cap://cal.example.com/calid2 2060 S: cap://cal.example.com/calid5 2061 S: cap://cal.example.com/calid66 2062 S: . 2064 Example #2: Request lookup a CSID which is a Resource Calendar 2066 C: CALIDEXPAND cap://cal.example.com/conf5 2067 S: 2.0 cap://cal.example.com/conf5 2068 S: cap://cal.example.com/conf5 2069 S: . 2071 Example #3: Request CSID which exceeds MAXCALIDEXPANDLIST 2073 C: CALIDEXPAND cap://cal.example.com/calid76 2074 S: 2.0 cap://cal.example.com/calid76 2075 S: cap://cal.example.com/calid3 2076 S: cap://cal.example.com/calid12 2077 S: cap://cal.example.com/calid21 2078 S: cap://cal.example.com/calid33 2079 S: 2.3 Expansion resulted in too much data 2080 S: . 2082 Example #4: CS loses contact with directory server during 2083 CALIDEXPAND 2085 C: CALIDEXPAND cap://cal.example.com/calid76 2086 S: 2.0 cap://cal.example.com/calid76 2087 S: cap://cal.example.com/calid3 2088 S: cap://cal.example.com/calid5 2089 S: 2.4 Lost contact with directory server 2090 S: . 2092 CAP Expires September 2001 2094 7.1.5 CAPABILITY Command 2096 Arguments: none 2098 Data: none 2100 Result: capabilities as described below 2102 The CAPABILITY command returns information about the CAP 2103 server given the current state of the connection with the 2104 client. The values returned may differ depending on whether 2105 the connection is in the Connected or the Authenticated state. 2106 The return values may also be different for a secure versus a 2107 non-secure connection. 2109 Client implementations SHOULD NOT require any capability name 2110 beyond those defined in this specification, and MAY ignore any 2111 non-standard, experimental capability names. Non-standard 2112 experimental capability names MUST be prefixed with the text 2113 "X-". The prefix SHOULD also include a short character vendor 2114 identifier For example, "X-FOO-BARCAPABILITY", for the non- 2115 standard "BARCAPABILITY" capability of the implementor "FOO". 2116 This command may return different results in the Connected 2117 state versus the Authenticated state. It may also return 2118 different results depending on the UPN. 2120 Capability Occurs Description 2121 ------------------------------------------------------- 2122 AUTH 1+ The authentication mechanisms 2123 supported. Implementations MUST 2124 implement at least 2126 CAPVERSION 1 Revision of CAP, MUST include at 2127 least "1.0". Comma separated 2128 values. 2130 ITIPVERSION 0 or 1 Revision of ITIP, MAY be present. 2131 If present, it MUST include at 2132 least "1.0" 2133 CAR 0 or 1 Indicates level of CAR support. 2134 CAR-MIN or CAR-FULL-1. If not 2135 specified the default is 2136 CAR-FULL-1. Implementations 2137 MUST implement CAR-MIN. 2138 Implementations MAY implement 2139 CAR-FULL-1. 2141 CAP Expires September 2001 2143 QUERYLEVEL 0 or 1 Indicates level of SQL support. 2144 SQL-MIN or SQL-92. If not 2145 specified the default is SQL-92. 2146 Implementations MUST implement 2147 SQL-MIN. Implementations MAY 2148 implement SQL-92. 2150 MAXICALOBJECTSIZE 2151 0 or 1 An integer value that specifies 2152 The largest ICAL object the server 2153 will accept in bytes. Objects 2154 larger than this will be rejected. 2155 A value of zero (0) indicates 2156 unlimited. The default is zero (0) 2157 if not specified. 2159 MAXDATE 0 or 1 The datetime value in GMT beyond 2160 which the server cannot accept. If 2161 not specified the default is 2162 99991231T235959Z. 2164 MAXCALIDEXPANDLIST 2165 0 or 1 An integer value that specifies 2166 the maximum number of CalIDs that 2167 can be returned by the CALIDEXPAND 2168 Command. A value of zero (0) 2169 indicates unlimited which is the 2170 default if not specified. 2172 MAXUPNEXPANDLIST 2173 0 or 1 An integer value that specifies 2174 the maximum number of UPNs that 2175 can be returned by the UPNEXPAND 2176 Command. A value of zero (0) 2177 indicates unlimited which is the 2178 default if not specified. 2180 MINDATE 0 or 1 The datetime value prior to which 2181 the server cannot accept. If not 2182 specified the default is 2183 00000101T000000Z. 2185 PIPELINE 0 or 1 An integer value that specifies 2186 the maximum number of commands a 2187 CUA may send without the CUA 2188 waiting for a reply from the CS. 2189 If not specified, the default 2190 value is one (1). A value of zero 2191 (0)indicates unlimited. 2193 CAP Expires September 2001 2195 AUTOLOGOUTTIME 2196 0 or 1 An integer value that specifies 2197 the default idle time in seconds 2198 the CS will wait before 2199 disconnecting an idle CUA.If the 2200 CS is busy the CS may adjust down 2201 the auto-logout timer. If not 2202 specified, the value is 15 minutes 2203 (900 seconds). A value of zero (0) 2204 indicates unlimited connect time 2205 is allowed. 2207 Example: 2209 C: CAPABILTIY 2210 S: 2.0 2211 S: . 2212 S: CAPVERSION=1.0 2213 S: ITIPVERSION=1.0 2214 S: AUTH=KERBEROS_V4 2215 S: AUTH=DIGEST_MD5 2216 S: . 2218 7.1.6 CONTINUE Command 2220 Arguments: latency time in seconds (optional) 2222 Data: none 2224 Result: results from the command in progress 2225 2.0.2 - reply pending. 2227 The CONTINUE command is issued by the client in response to a 2228 SENDATA timeout. When a timeout value is specified on the 2229 SENDDATA command, the server must issue a reply to the client 2230 within the specified time. If the latency time has elapsed 2231 prior to the server completing the command it returns a 2232 timeout response code. If the client wants the server to 2233 continue processing the command it responds with the CONTINUE 2234 command. 2236 If latencyTime is present, it must be a positive integer that 2237 specifies the maximum number of seconds the client will wait 2238 for the next response. If it is omitted, the receiver waits an 2239 indefinite period of time for the response. 2241 CAP Expires September 2001 2243 In this example, the client requests a response from the 2244 server every 10 seconds. 2246 C: SENDDATA:10 2247 C: Content-Type:text/calendar; method=READ; component=VEVENT 2248 C: 2249 C: BEGIN:VCAP 2250 # etc 2251 C: END:VCAP 2252 C: . 2253 # after 10 seconds... 2254 S: . 2255 S: 2.0.2 2256 S: . 2257 S: . 2258 C: CONTINUE:10 2259 S: 2.0 2260 S: . 2261 S: Content-type:text/calendar; 2262 S: Method=RESPONSE;Component=VDATA; 2263 S: Optinfo=VERSION:2.1 2264 S: 2265 S: BEGIN:VCAP 2267 S: VERSION:2.1 2268 S: CALID:cap://cal.example.com/relcal2 2269 # etc. 2270 S: END:VCAP 2271 S: . 2273 7.1.7 DISCONNECT Command 2275 Arguments: none 2277 Data: 2279 Result: 2.0 2281 The DISCONNECT command is used by a client to terminate a 2282 connection. It always succeeds. 2284 The CUA MUST wait for the CS 2.0 reply to ensure that TCP/IP 2285 (which knows nothing about CAP) can be sure the connection 2286 should go away. This avoids the CS connection being stuck in 2287 TCP-WAIT state. 2289 Example: 2291 CAP Expires September 2001 2293 C: DISCONNECT 2294 # [ed. Note: should the client now wait for a response from 2295 the 2296 server 2297 # before disconnecting? ] 2298 S: 2.0 2299 S: . 2300 S: . 2301 S: 2302 C: 2304 7.1.8. IDENTIFY Command 2306 Arguments: Identity to assume 2308 Data: None 2310 Result: 2.0 2311 .4 Identity not permitted 2313 The "IDENTIFY" command allows the CUA to select a new identity 2314 to be used for calendar access. This command may only be 2315 called in the Identified State. 2317 The CS determines through an internal mechanism if the 2318 credentials supplied at authentication permit the assumption 2319 of the selected the identity. If they do the session assumes 2320 the new identity, otherwise a security error is returned. 2322 7.1.8 SENDDATA Command 2324 Arguments: [latencyTime] 2326 Data: a [MIME] encapsulated iCalendar object 2328 Result: 2.0.1 - Server will now accept input until 2329 . is encountered. 2331 The SENDDATA command is used to send calendar requests and 2332 commands to the server. After a response code of 2.0.1 is 2333 issued the CUA sends a [MIME] encapsulated iCalendar object to 2334 the server. The end of this [MIME] data is signaled by the 2335 special sequence . . 2337 7.1.10. STARTTLS Command 2338 CAP Expires September 2001 2340 Arguments: None 2342 Data: None 2344 Result: 2.0 2345 5 TLS not supported 2347 The "STARTTLS" command is issued by the CUA to indicate to the 2348 CS that it wishes to negotiate transport level security using 2349 [TLS]. If the CS does not support TLS it returns status code 2350 6.5. If the CS supports TLS it issues an initial response of 2351 2.0.12 indicating that the CUA should proceed with TLS 2352 negotiation. Once the TLS negotiation is complete the server 2353 returns the response code 2.0. 2355 After issuing the "STARTTLS" command the CUA issues the 2356 "AUTHENTICATE" command. The SASL external mechanism may be 2357 used if the CUA wishes to use the authentication id which was 2358 used in the TLS negotiation. 2360 The CUA MUST NOT issue a "STARTTLS" if it has already issued 2361 an "AUTHENTICATE" or "STARTTLS" command in this session. If a 2362 CUA does this the CS must terminate the session. 2364 The following examples illustrate the use of the "STARTTLS" 2365 command: 2367 Unsupported TLS: 2369 C: STARTTLS 2370 S: 6.5 2372 Supported TLS: 2374 C: STARTTLS 2375 S: 2.0.12 2376 2377 S: 2.0 2379 S: . 2380 S: . 2382 7.1.8.1 UPNEXPAND Method 2384 Arguments: UPN 2386 Data: no specific data for this command 2387 CAP Expires September 2001 2389 Result: 2.0 - success 2390 2.1 Permission Denied 2391 2.2 Requested UPN not found 2392 2.3 Result exceeds MAXUPNEXPANDLIST 2393 2.4 Misc. UPNEXPAND error 2395 Return the members of the argument UPN. Successful result 2396 yields one or more CalIDs. More than one CalID returned 2397 implies that the UPN was a UG. 2399 Example #1: Request lookup of a UPN which is a CU 2401 C: UPNEXPAND upn@example.com 2402 S: 2.0 upn@example.com 2403 S: cap://cal.example.com/calid3 2404 S: . 2406 Example #2: Request lookup of UPN which is a UG 2408 C: UPNEXPAND group@example.com 2409 S: 2.0 group@example.com 2410 S: cap://cal.example.com/calid3 2411 S: cap://cal.example.com/calid6 2412 S: cap://cal.example.com/calid1342 2413 S: . 2415 Example #3: Request lookup exceeds MAXUPNEXPANDLIST 2417 C: UPNEXPAND group@example.com 2418 S: 2.0 group@example.com 2419 S: cap://cal.example.com/calid3 2420 S: cap://cal.example.com/calid12 2421 S: cap://cal.example.com/calid21 2422 S: cap://cal.example.com/calid33 2423 S: 2.3 Lookup resulted in too much data 2424 S: . 2426 Example #4: CS loses contact with directory server during 2427 UPNEXPAND 2429 C: UPNEXPAND group@example.com 2430 S: 2.0 group@example.com 2431 S: cap://cal.example.com/calid3 2432 S: cap://cal.example.com/calid5 2434 S: 2.4 Lost contact with directory server 2435 S: . 2437 CAP Expires September 2001 2439 7.2 Application Protocol Commands 2441 7.2.1 Calendaring Commands 2443 The following methods provide a set of calendaring commands in 2444 CAP. Calendaring commands (or methods) allow a CU to directly 2445 manipulate a calendar. 2447 Calendar access rights can be granted for the more generalized 2448 access provided by the calendar commands. 2450 7.2.1.1 Restriction Tables 2452 Commands are sent to CAP servers encapsulated in iCalendar 2453 objects. The reply to these commands are also encapsulated in 2454 iCalendar objects. The restriction tables listed in the 2455 commands below describe the composition of the iCalendar data 2456 for these commands and replies. 2458 The Presence column uses the following values to assert 2459 whether a property is required, is optional and the number of 2460 times it may appear in the iCalendar object. A Comment may be 2461 provided to further clarify the presence criteria. 2463 The table below defines the values for the Presence column. 2465 Presence Value Description 2466 -------------------------------------------------------------- 2467 1 One instance MUST be present 2468 1+ At least one instance MUST be present 2469 0 Instances of this property Must NOT be present 2470 0+ Multiple instances MAY be present 2471 0 or 1 Up to 1 instance of this property MAY be present 2472 -------------------------------------------------------------- 2474 While the tables list every component and property, their 2475 purpose is not to define the meaning of the component or 2476 property. 2478 There will be a REQUEST-STATUS for each VCALENDAR and 2479 component created, modified, deleted, or requested. The number 2480 of REQUEST-STATUS values returned MUST be equal to the number 2481 of TARGETS times the number of objects in the command. The 2482 responses MUST be ordered first by TARGET then by the order of 2483 the objects as supplied in the command. 2485 CAP Expires September 2001 2487 7.2.1.2 CREATE Method 2489 Arguments: none 2491 Data: no specific data for this command 2493 Result: 2.0 - successfully created the component or calendar 2494 6.0 - Permission denied 2495 6.1 - Container(s) not found 2496 6.2 - Calendar or component already exists 2497 6.3 - 2498 Bad args 2500 The CREATE method is used to create a new iCalendar object of 2501 type objtype. The property TARGET specifies the container(s) 2502 for the create. The type of object wrapped inside of the 2503 VCALENDAR/CREATE object is the object type(s) being created. 2504 When creating a new calendar at the top level, the CSID is 2505 specified. Otherwise the container will be a CalID. 2507 Restriction table 2509 Component/Property Presence Comment 2510 ------------------- -------- ----------------------------- 2511 VCAP 1+ The CUA can send up 2512 PIPELINE commands 2513 without processing a 2514 response 2516 . VERSION 1 MUST be 2.0 2517 . [IANA-PROP] 0+ any IANA registered 2518 property 2520 . VCOMMAND 1 MUST at least one container 2521 (VCALENDAR, VCAR, VQUERY, 2522 VEVENT, VTODO, VJOURNAL) 2523 . . CMDID 0 or 1 If CMDID is not supplied, 2524 then there must not be 2525 pending replies to previous 2526 command. 2528 . . [IANA-PROP] 0+ any IANA registered 2529 property 2530 . . METHOD 1 MUST be CREATE. 2531 . . TARGET 1+ MUST be the CSID or CALID 2533 . . VCALENDAR 0+ 2534 CAP Expires September 2001 2536 . . . CALMASTER 0 or 1 2537 . . . NAME 0 or 1 2538 . . . OWNER 1+ 2539 . . . RELCALID 1 2540 . . . TZID 0 or 1 2541 . . . [IANA-PROP] 0+ any IANA registered 2542 property 2544 . . VCAR 0+ 2545 . . . CARID 0 or 1 2546 . . . DENY 0+ Note, there must be at 2547 least one GRANT or DENY 2548 within the VCAR. 2549 . . . GRANT 0+ Note, there must be at 2550 least one GRANT or DENY 2551 within the VCAR. 2552 . . . [IANA-PROP] 0+ any IANA registered 2553 property 2555 . . VQUERY 0+ 2556 . . . EXPAND 0 or 1 2557 . . . MAXRESULTS 0 or 1 2558 . . . MAXSIZE 0 or 1 2559 . . . QUERYNAME 1 2560 . . . QUERY 1 2561 . . . [IANA-PROP] 0+ any IANA registered 2562 property 2564 . . VEVENT 0+ 2565 . . . ATTENDEE 0+ 2566 . . . SEQUENCE 0 or 1 MUST be present if value is 2567 greater than 0, 2568 MAY be present if 0 2569 . . . SUMMARY 1 Can be null 2570 . . . UID 1 2572 . . . ATTACH 0+ 2573 . . . CATEGORIES 0 or 1 2574 . . . CLASS 0 or 1 2575 . . . COMMENT 0 or 1 2576 . . . CONTACT 0+ 2577 . . . CREATED 0 or 1 2578 . . . DESCRIPTION 0 or 1 Can be null 2579 . . . DTEND 0 or 1 if present DURATION MUST 2580 NOT be present 2581 . . . DTSTAMP 1 2582 . . . DTSTART 1 2583 . . . DURATION 0 or 1 if present DTEND MUST NOT 2584 be present 2585 CAP Expires September 2001 2587 . . . EXDATE 0+ 2588 . . . EXRULE 0+ 2589 . . . GEO 0 or 1 2590 . . . LAST-MODIFIED 0 or 1 2591 . . . LOCATION 0 or 1 2592 . . . METHOD 1 <> 2594 . . . ORGANIZER 1 2595 . . . PRIORITY 0 or 1 2596 . . . RDATE 0+ 2597 . . . RECURRENCE-ID 0 or 1 only if referring to an 2598 instance of a recurring 2599 calendar component. 2600 Otherwise it MUST NOT be 2601 present. 2602 . . . RELATED-TO 0+ 2603 . . . REQUEST-STATUS 0+ 2604 . . . RESOURCES 0 or 1 This property MAY contain a 2605 list of values 2606 . . . RRULE 0+ 2607 . . . STATUS 0 or 1 2608 . . . TRANSP 0 or 1 2609 . . . URL 0 or 1 2610 . . . X-PROPERTY 0+ 2611 . . . [IANA-PROP] 0+ any IANA registered 2612 property 2614 . . . VALARM 0+ 2615 . . . . ACTION 1 2616 . . . . ALARMID 0 or 1 MUST be 1 if multiple 2617 VALARMs are present in 2618 same component. 2619 . . . . ATTACH 0+ 2620 . . . . DESCRIPTION 0 or 1 2621 . . . . DURATION 0 or 1 if present REPEAT MUST be 2622 present 2623 . . . . REPEAT 0 or 1 if present DURATION MUST be 2624 present 2625 . . . . SUMMARY 0 or 1 2626 . . . . TRIGGER 1 2627 . . . . X-PROPERTY 0+ 2628 . . . . [IANA-PROP] 0+ any IANA registered property 2630 . . VTODO 0+ 2631 . . . ATTENDEE 0+ 2632 . . . SEQUENCE 0 or 1 MUST be present if value is 2633 greater than 0, MAY be 2634 present if 0 2635 CAP Expires September 2001 2637 . . . SUMMARY 1 Can be null. 2638 . . . UID 1 2640 . . . ATTACH 0+ 2641 . . . CATEGORIES 0 or 1 This property may contain a 2642 list of values 2643 . . . CLASS 0 or 1 2644 . . . COMMENT 0 or 1 2645 . . . CONTACT 0+ 2646 . . . CREATED 0 or 1 2647 . . . DESCRIPTION 0 or 1 Can be null 2648 . . . DTSTAMP 1 2649 . . . DTSTART 1 2650 . . . DUE 0 or 1 If present DURATION MUST NOT 2651 be present 2652 . . . DURATION 0 or 1 If present DUE MUST NOT be 2653 present 2654 . . . EXDATE 0+ 2655 . . . EXRULE 0+ 2656 . . . GEO 0 or 1 2657 . . . LAST-MODIFIED 0 or 1 2658 . . . LOCATION 0 or 1 2659 . . . METHOD 1 <> 2661 . . . ORGANIZER 1 2662 . . . PRIORITY 1 2663 . . . PERCENT-COMPLETE 0 or 1 2664 . . . RDATE 0+ 2665 . . . RECURRENCE-ID 0 or 1 MUST only if referring to an 2666 instance of a recurring 2667 calendar component. 2668 Otherwise it MUST NOT be 2669 present. 2670 . . . RELATED-TO 0+ 2671 . . . REQUEST-STATUS 0 2672 . . . RESOURCES 0 or 1 This property may contain a 2673 list of values 2674 . . . RRULE 0+ 2675 . . . STATUS 0 or 1 MAY be one of COMPLETED, 2676 NEEDS-ACTION, 2677 IN-PROCESS, CANCELLED 2678 . . . URL 0 or 1 2680 . . . X-PROPERTY 0+ 2681 . . . [IANA-PROP] 0+ any IANA registered property 2683 . . . VALARM 0+ 2684 . . . . ACTION 1 2685 . . . . ALARMID 0 or 1 MUST be 1 if multiple 2686 CAP Expires September 2001 2688 VALARMs are present in 2689 same component. 2690 . . . . ATTACH 0+ 2691 . . . . DESCRIPTION 0 or 1 2692 . . . . DURATION 0 or 1 if present REPEAT MUST be 2693 present 2694 . . . . REPEAT 0 or 1 if present DURATION MUST be 2695 present 2696 . . . . SUMMARY 0 or 1 2697 . . . . TRIGGER 1 2698 . . . . X-PROPERTY 0+ 2699 . . . . [IANA-PROP] 0+ any IANA registered property 2701 . . VJOURNAL 0+ 2702 . . . ATTENDEE 0 2703 . . . DESCRIPTION 1 Can be null. 2704 . . . DTSTAMP 1 2705 . . . DTSTART 1 2706 . . . ORGANIZER 1 2707 . . . UID 1 2709 . . . ATTACH 0+ 2710 . . . CATEGORIES 0 or 1 This property MAY contain a list 2711 of values 2712 . . . CLASS 0 or 1 2713 . . . COMMENT 0 or 1 2714 . . . CONTACT 0+ 2715 . . . CREATED 0 or 1 2716 . . . EXDATE 0+ 2717 . . . EXRULE 0+ 2718 . . . LAST-MODIFIED 0 or 1 2719 . . . METHOD 1 <> 2721 . . . RDATE 0+ 2722 . . . RECURRENCE-ID 0 or 1 MUST only if referring to 2723 an instance of a recurring 2724 calendar component. 2725 Otherwise it MUST NOT be 2726 present. 2727 . . . RELATED-TO 0+ 2728 . . . RRULE 0+ 2729 . . . SEQUENCE 0 or 1 MUST be present if 2730 non-zero. MAY be 2731 present if zero. 2732 . . . STATUS 0 or 1 2733 . . . SUMMARY 0 or 1 Can be null 2734 . . . URL 0 or 1 2735 . . . X-PROPERTY 0+ 2736 CAP Expires September 2001 2738 . . . [IANA-PROP] 0+ any IANA registered 2739 property 2741 . . VFREEBUSY 0 2743 . . VTIMEZONE 0+ MUST be present if any 2744 date/time refers to a 2745 timezone 2746 . . . DAYLIGHT 0+ MUST be one or more of 2747 either STANDARD or 2748 DAYLIGHT 2749 . . . . . COMMENT 0 or 1 2750 . . . . . DTSTART 1 2751 . . . . . RDATE 0+ if present RRULE MUST NOT 2752 be present 2753 . . . . . RRULE 0+ if present RDATE MUST NOT 2754 be present 2755 . . . . . TZNAME 0 or 1 2756 . . . . . TZOFFSET 1 2757 . . . . . TZOFFSETFROM 1 2758 . . . . . TZOFFSETTO 1 2759 . . . . . X-PROPERTY 0+ 2760 . . . . . [IANA-PROP] 0+ any IANA registered 2761 property 2762 . . . LAST-MODIFIED 0 or 1 2763 . . . STANDARD 0+ 2764 . . . . . COMMENT 0 or 1 2765 . . . . . DTSTART 1 2766 . . . . . RDATE 0+ if present RRULE MUST NOT 2767 be present 2768 . . . . . RRULE 0+ if present RDATE MUST NOT 2769 be present 2770 . . . . . TZNAME 0 or 1 2771 . . . . . TZOFFSETFROM 1 2772 . . . . . TZOFFSETTO 1 2773 . . . . . X-PROPERTY 0+ 2774 . . . . . [IANA-PROP] 0+ any IANA registered property 2775 . . . TZID 1 2776 . . . TZURL 0 or 1 2777 . . . X-PROPERTY 0+ 2778 . . . [IANA-PROP] 0+ any IANA registered property 2780 Server Restriction Table for the CREATE command 2782 Component/Property Presence Comment 2783 ------------------- -------- ------------------------------- 2784 CAP Expires September 2001 2786 VCAP 1+ 2787 . VCALENDAR 1+ 2788 . . TARGET 1 2790 . . VERSION 1 MUST be 2.0 2792 . . CMDID 0 or 1 MUST be returned if the 2793 request contained 2794 a CMDID 2795 . . REQUEST-STATUS 0 if not creating a calendar 2796 1+ if creating a calendar 2798 . . . VCAR 0+ 2799 . . . . REQUEST-STATUS 1+ 2800 . . . . * 0 No other VCAR properties 2801 are present 2802 . 2803 . . . VCOMMAND 0 2805 . . . VEVENT 0+ 2806 . . . . REQUEST-STATUS 1+ 2807 . . . . * 0 No other VEVENT properties 2808 are present 2809 . . . . VALARM 0 if VEVENT was successfully 2810 saved 2811 1+ if there were errors saving 2812 alarms 2813 . . . . . REQUEST-STATUS 1+ 2815 . . . VFREEBUSY 0+ 2816 . . . . REQUEST-STATUS 1+ 2817 . . . . * 0 No other VFREEBUSY 2818 properties are present 2820 . . . VJOURNAL 0+ 2821 . . . . REQUEST-STATUS 1+ 2822 . . . . * 0 No other VJOURNAL 2823 properties are present 2825 . . . VQUERY 0+ 2826 . . . . REQUEST-STATUS 1+ 2827 . . . . * 0 No other VQUERY properties 2828 are present 2830 . . . VTODO 0+ 2831 . . . . REQUEST-STATUS 1+ 2832 . . . . * 0 No other VTODO properties 2833 are present 2834 CAP Expires September 2001 2836 . . . . VALARM 0 if VTODO was successfully 2837 saved 2838 1+ if there were errors saving 2839 alarms 2840 . . . . . REQUEST-STATUS 1+ 2842 7.2.1.2.1 Creating New Calendars 2844 Example to create two new calendars different containers. In 2845 the following example, the client is in the Authenticated 2846 state with CS cal.example.com. 2848 C: SENDDATA 2849 C: CONTENT-TYPE: text/calendar; method=CREATE; 2850 C: component=VCOMMAND 2851 C: Content-Transfer-Encoding:7bit 2852 C: 2853 C: BEGIN:VCAP 2854 C: VERSION:2.1 2855 C: BEGIN:VCOMMAND 2856 C: METHOD:CREATE 2857 C: TARGET:cap://cal.example.com/ 2858 C: TARGET:relcal4 2859 C: BEGIN:VCALENDAR 2860 C: RELCALID:relcalz1 2861 C: NAME:CHARSET=us-ascii;LANGUAGE=EN-us:Bill's Soccer Team 2862 C: OWNER:bill 2863 C: CALMASTER:mailto:bill@example.com 2864 C: TZID:US_PST 2865 C: BEGIN:VCAR 2866 C: CARID:12345 2867 C: GRANT:UPN=bill;ACTION=*;OBJECT=* 2868 C: END:VCAR 2869 C: END:VCALENDAR 2870 C: BEGIN:VCALENDAR 2871 C: RELCALID:relcalz2 2872 C: NAME:CHARSET=us-ascii;LANGUAGE=EN-us:Mary's personal 2873 C: calendar 2874 C: OWNER:mary 2875 C: CALMASTER:mailto:mary@example.com 2876 C: TZID:US_PST 2877 C: BEGIN:VCAR 2878 C: CARID:12346 2879 C: GRANT:UPN=mary;ACTION=*;OBJECT=* 2880 C: END:VCAR 2881 C: END:VCALENDAR 2882 C: END:VCOMMAND 2883 C: END:VCAP 2884 CAP Expires September 2001 2886 C: . 2887 S: 2.0 2888 S: Content-Type:text/calendar; method=RESPONSE; 2889 S: OPTINFO="CMDID:abcde" 2890 # This 2.0 is the transport reply status and ends with a 2891 # CRLF.CRLF (below) 2892 S: BEGIN:VCAP 2893 S: METHOD:RESPONSE 2894 S: TARGET:cap://cal.example.com/ 2895 S: REQUEST-STATUS:2.0 2896 S: END:VCAP 2897 S: BEGIN:VCAP 2898 S: METHOD:RESPONSE 2899 S: REQUEST-STATUS:2.0 2900 S: END:VCAP 2901 S: . 2903 Example to create a new component. 2905 C: SENDDATA 2906 C: Content-Type:text/calendar; method=CREATE; 2907 C: charset=US-ASCII 2908 C: Content-Transfer-Encoding:7bit 2909 C: 2910 C: BEGIN:VCAP 2911 C: VERSION:2.1 2912 C: CMDID:abcde 2913 C: BEGIN:VCOMMAND 2914 C: METHOD:CREATE 2915 C: TARGET:cap://cal.example.com/relcal1 2916 C: TARGET:relcal2 2917 C: BEGIN:VEVENT 2919 C: DTSTART:99990307T180000Z 2920 C: UID:abcd12345 2921 C: DTEND:99990307T190000Z 2922 C: SUMMARY:Important Meeting 2923 C: END:VEVENT 2924 C: END:VCOMMAND 2925 C: END:VCAP 2926 C: . 2927 S: 2.0 2928 S: Content-Type:text/calendar; method=RESPONSE; 2929 S: OPTINFO="CMDID:abcde" 2930 S: 2931 S: BEGIN:VCAP 2932 S: VERSION:2.1 2933 S: CMDID:abcde 2934 CAP Expires September 2001 2936 S: METHOD:RESPONSE 2937 S: BEGIN:VEVENT 2938 S: TARGET::cap://cal.example.com/relcal1 2939 S: REQUEST-STATUS:2.9 2940 S: END:VEVENT 2941 S: BEGIN:VEVENT 2942 S: REQUEST-STATUS:2.9 2943 S: REQUEST-STATUS:2.10 2944 S: END:VEVENT 2945 S: END:VCAP 2946 S: . 2948 The response contains the calendar (CALID) and UID of the 2949 component so that the CUA can match up the TARGET from 2950 multiple objects created on multiple calendards (TARGETs). 2952 7.2.1.3 DELETE Method 2954 Arguments: none 2956 Data: no specific data for this command 2958 Result: 2.0 - successfully deleted the component or calendar 2959 Permission 2960 Calendar or component not found 2961 Bad args 2962 Container(s) not found 2964 The DELETE method is used to delete a calendar or component. 2965 The TARGET properties specify the container(s) for the delete. 2966 When deleting a calendar at the top level, the CSID is 2967 specified. Otherwise the container will be a CalID. 2969 Restriction Table 2971 Component/Property Presence Comment 2972 ------------------- -------- --------------------------- 2973 VCAP 1+ The CUA can send up 2974 PIPELINE commands 2975 without processing a 2976 response 2978 VERSION 1 MUST be 2.0 2980 VCOMMAND 1 2981 CMDID 0 or 1 If CMDID is not supplied, 2982 then there must 2983 not be pending replies to 2984 CAP Expires September 2001 2986 previous command. 2987 METHOD 1 MUST be DELETE. 2988 TARGET 1+ MUST be a the CSID or CALID 2990 VQUERY 0+ 2991 EXPAND 0 ? 2992 MAXRESULTS 0 or 1 Limit the solution set to 2993 no more than this many 2994 entries. 2995 MAXSIZE 0 ? 2996 QUERYNAME 1 Name by which this query is 2997 referenced 2998 QUERY 1 The query 3000 Server Restriction Table for the DELETE command 3002 Component/Property Presence Comment 3003 ------------------- -------- ----------------------------- 3005 VCAP 1+ 3006 TARGET 1 3008 VERSION 1 MUST be 2.0 3010 CMDID 0 or 1 MUST be returned if the 3011 request contained a CMDID 3013 VCALENDAR Only if VCALENDARs were 3014 deleted 3015 REQUEST-STATUS 1 3016 * 1+ No other VALARM properties 3017 are present 3019 VALARM 0+ Only if VALARM components 3020 were deleted 3021 REQUEST-STATUS 1 3022 * 0 No other VALARM properties 3023 are present 3025 VCAR 0+ Only if VCAR components were 3026 deleted 3027 REQUEST-STATUS 1 3028 * 0 No other VCAR properties are 3029 present 3031 VEVENT 0+ Only if VEVENT components 3032 were deleted 3033 REQUEST-STATUS 1+ 3034 CAP Expires September 2001 3036 * 0 No other VEVENT properties 3037 are present 3039 VFREEBUSY 0 3040 REQUEST-STATUS 1+ 3041 * 0 No other VFREEBUSY properties 3042 are present 3044 VJOURNAL 0+ Only if VJOURNAL components 3045 were deleted 3046 REQUEST-STATUS 1+ 3047 * 0 No other VJOURNAL properties 3048 are present 3050 VQUERY 0+ Only if VQUERY components 3051 were deleted 3052 REQUEST-STATUS 1+ 3053 * 0 No other VQUERY properties 3054 are present 3056 VTIMEZONE 0+ Only if VTIMEZONE components 3057 were deleted 3058 REQUEST-STATUS 1+ 3059 * 0 No other VQUERY properties 3060 are present 3062 VTODO 0+ Only if VTODO components were 3063 deleted 3064 REQUEST-STATUS 1+ 3065 * 0 No other VTODO properties are 3066 present 3068 ---------------------------------------------------------- 3070 [Editors note: Issues: 3072 - Currently CAP requires that the server return a response 3073 status. However, if there are multiple components deleted, 3074 should the UID also be returned? 3076 - VQUERY EXPAND and MAXSIZE parameters do not seem to apply to 3077 deletion? 3079 - Can one use DELETE to remove all VALARMs and VTIMEZONEs that 3080 match a certain search criteria and that belong to all 3081 components, event though VALARMs and VTIMEZONEs never exist as 3082 independent components? Or should one use MODIFY? If they can 3083 CAP Expires September 2001 3085 be deleted, do we return the REQUEST-STATUS of their deletion 3086 in a VEVENT or separately? 3088 - In the example in CAP where a calendar is deleted all the 3089 server returns is 2.0, nothing else? 3091 - We should not be able to delete any VFREEBUSY components? 3093 - Can we delete multiple calendars? 3095 - Currently one can not delete a VCALENDAR and some other 3096 component in the same DELETE command. This seems OK. Anyone 3097 see any need to be able to do this? 3099 - Should the MAXRESULTS property of VQUERY apply to deletion? 3100 We can use it to delete only the first n components that 3101 match. 3102 ] 3104 Example to delete a VEVENT with UID 'abcd12345': 3106 C: SENDDATA 3107 C: Content-Type:text/calendar; method=DELETE; 3108 component=VCOMMAND 3109 C: Content-Transfer-Encoding:7bit 3110 C: 3112 C: BEGIN:VCAP 3113 C: BEGIN:VCOMMAND 3114 C: METHOD:DELETE 3115 C: TARGET:cap://cal.foo.com/bill 3116 C: BEGIN:VQUERY 3117 C: QUERY:SELECT UID FROM VEVENT WHERE UID = 'abcd12345' 3118 C: END:VQUERY 3119 C: END:VCOMMAND 3120 C: END:VCAP 3121 C: . 3122 S: 2.0 3123 S: Content-Type:text/calendar; method=DELETE; 3124 S: component=VCOMMAND 3125 S: 3126 S: BEGIN:VCAP 3127 S: METHOD:RESPONSE 3128 S: BEGIN:VEVENT 3129 S: REQUEST-STATUS:2.0 3130 S: END:VEVENT 3131 S: END:VCAP 3132 S: . 3134 CAP Expires September 2001 3136 And an example to delete the 'MrBill' calendar: 3138 C: SENDDATA 3139 C: Content-Type:text/calendar; method=DELETE; 3140 C: component=VCOMMAND 3141 C: Content-Transfer-Encoding:7bit 3142 C: 3143 C: BEGIN:VCAP 3144 C: BEGIN:VCOMMAND 3145 C: METHOD:DELETE 3146 C: TARGET:cap://cal.foo.com/MrBill 3147 C: END:VCOMMAND 3148 C: END:VCAP 3149 C: . 3150 S: 2.0 3151 S: . 3153 7.2.1.4 GENERATEUID Method 3155 Arguments: Number of UIDs to generate. 3157 Data: new uids 3159 Result: 2.0 3161 GENERATEUID returns one or more new unique identifier which 3162 MUST be unique on the server's calendar store. It is 3163 recommended that the return value be a globally unique id. 3165 Example: 3167 C: GENERATEUID 2 3169 S: 2.0 abcde1234567-asdf-lkhh abcde1234567-asdf-3455 3171 [EDITORS NOTE: this example needs work. It's not packaged 3172 right] 3174 7.2.1.5 MODIFY Method 3176 Arguments: none 3178 Data: no specific data for this command 3180 Result: 2.0 - successfully modified the component or 3181 calendar 3182 Permission 3183 CAP Expires September 2001 3185 Calendar or component not found 3186 Bad args 3187 Container(s) not found 3189 The MODIFY method is used to change an existing calendar or 3190 component. TARGET specify the container(s) of the 3191 modification. When modifying a calendar at the top level, the 3192 CSID is specified. Otherwise the container will be a CalID. 3194 The format of the request is two or three containers inside of 3195 a VCOMMAND container: 3197 BEGIN:VCOMMAND 3198 [VQUERY] 3199 OLD-VALUES 3200 NEW-VALUES 3201 END:VCOMMAND 3203 If a VQUERY is present, then only objects matching the query 3204 results are modified. 3206 Restriction Table 3208 Component/Property Presence Comment 3209 ------------------- -------- --------------------------- 3210 VCAP 1+ The CUA can send up 3211 PIPELINE commands 3212 without processing a 3213 response 3215 . VERSION 1 MUST be 2.0 3216 . [IANA-PROP] 0+ any IANA registered 3217 property 3219 . VCOMMAND 1 MUST have at least one 3220 container (VCALENDAR, 3221 VCAR, VQUERY, VEVENT, 3222 VTODO, VJOURNAL) 3223 . . CMDID 0 or 1 If CMDID is not supplied, 3224 then there must 3225 not be pending replies to 3226 previous command. 3227 . . [IANA-PROP] 0+ any IANA registered 3228 property 3229 . . METHOD 1 MUST be MODIFY 3230 . . TARGET 1+ MUST be the CALID 3232 . . VCALENDAR 0+ 3233 CAP Expires September 2001 3235 . . . CALMASTER 0 or 1 3236 . . . NAME 0 or 1 3237 . . . OWNER 1+ 3238 . . . RELCALID 1 3239 . . . TZID 0 or 1 3240 . . . [IANA-PROP] 0+ any IANA registered 3241 property 3243 . . VCAR 0+ 3244 . . . CARID 0 or 1 3245 . . . DENY 0+ Note, there must be at 3246 least one GRANT or DENY 3247 within the VCAR. 3248 . . . GRANT 0+ Note, there must be at 3249 least one GRANT or DENY 3250 within the VCAR. 3251 . . . [IANA-PROP] 0+ any IANA registered 3252 property 3254 . . VQUERY 0+ 3255 . . . EXPAND 0 or 1 3256 . . . MAXRESULTS 0 or 1 3257 . . . MAXSIZE 0 or 1 3258 . . . QUERYNAME 1 3259 . . . QUERY 1 3260 . . . [IANA-PROP] 0+ any IANA registered 3261 property 3263 . . VEVENT 0+ 3264 . . . ATTENDEE 0+ 3265 . . . SEQUENCE 0 or 1 MUST be present if value is 3266 greater than 0, 3267 MAY be present if 0 3268 . . . SUMMARY 1 Can be null 3269 . . . UID 1 3271 . . . ATTACH 0+ 3272 . . . CATEGORIES 0 or 1 3273 . . . CLASS 0 or 1 3274 . . . COMMENT 0 or 1 3275 . . . CONTACT 0+ 3276 . . . CREATED 0 or 1 3277 . . . DESCRIPTION 0 or 1 Can be null 3278 . . . DTEND 0 or 1 if present DURATION MUST 3279 NOT be present 3280 . . . DTSTAMP 1 3281 . . . DTSTART 1 3282 . . . DURATION 0 or 1 if present DTEND MUST NOT 3283 be present 3284 CAP Expires September 2001 3286 . . . EXDATE 0+ 3287 . . . EXRULE 0+ 3288 . . . GEO 0 or 1 3289 . . . LAST-MODIFIED 0 or 1 3290 . . . LOCATION 0 or 1 3291 . . . METHOD 1 <> 3293 . . . ORGANIZER 1 3294 . . . PRIORITY 0 or 1 3295 . . . RDATE 0+ 3296 . . . RECURRENCE-ID 0 or 1 only if referring to an 3297 instance of a recurring 3298 calendar component. 3299 Otherwise it MUST NOT be 3300 present. 3301 . . . RELATED-TO 0+ 3302 . . . REQUEST-STATUS 0+ 3303 . . . RESOURCES 0 or 1 This property MAY contain a 3304 list of values 3305 . . . RRULE 0+ 3306 . . . STATUS 0 or 1 3307 . . . TRANSP 0 or 1 3308 . . . URL 0 or 1 3309 . . . X-PROPERTY 0+ 3310 . . . [IANA-PROP] 0+ any IANA registered 3311 property 3313 . . . VALARM 0+ 3314 . . . . ACTION 1 3315 . . . . ALARMID 0 or 1 MUST be 1 if multiple 3316 VALARMs are present in same 3317 component. 3318 . . . . ATTACH 0+ 3319 . . . . DESCRIPTION 0 or 1 3320 . . . . DURATION 0 or 1 if present REPEAT MUST be 3321 present 3322 . . . . REPEAT 0 or 1 if present DURATION MUST be 3323 present 3324 . . . . SUMMARY 0 or 1 3325 . . . . TRIGGER 1 3326 . . . . X-PROPERTY 0+ 3327 . . . . [IANA-PROP] 0+ any IANA registered 3328 property 3330 . . VTODO 0+ 3331 . . . ATTENDEE 0+ 3332 . . . SEQUENCE 0 or 1 MUST be present if value is 3333 greater than 0, MAY be 3334 CAP Expires September 2001 3336 present if 0 3337 . . . SUMMARY 1 Can be null. 3338 . . . UID 1 3340 . . . ATTACH 0+ 3341 . . . CATEGORIES 0 or 1 This property may contain a 3342 list of values 3343 . . . CLASS 0 or 1 3344 . . . COMMENT 0 or 1 3345 . . . CONTACT 0+ 3346 . . . CREATED 0 or 1 3347 . . . DESCRIPTION 0 or 1 Can be null 3348 . . . DTSTAMP 1 3349 . . . DTSTART 1 3350 . . . DUE 0 or 1 If present DURATION MUST 3351 NOT be present 3352 . . . DURATION 0 or 1 If present DUE MUST NOT be 3353 present 3354 . . . EXDATE 0+ 3355 . . . EXRULE 0+ 3356 . . . GEO 0 or 1 3357 . . . LAST-MODIFIED 0 or 1 3358 . . . LOCATION 0 or 1 3359 . . . METHOD 1 <> 3361 . . . ORGANIZER 1 3362 . . . PRIORITY 1 3363 . . . PERCENT-COMPLETE 0 or 1 3364 . . . RDATE 0+ 3365 . . . RECURRENCE-ID 0 or 1 MUST only if referring to 3366 an instance of a recurring 3367 calendar component. 3368 Otherwise it MUST NOT 3369 be present. 3370 . . . RELATED-TO 0+ 3371 . . . REQUEST-STATUS 0 3372 . . . RESOURCES 0 or 1 This property may contain a 3373 list of values 3374 . . . RRULE 0+ 3375 . . . STATUS 0 or 1 MAY be one of COMPLETED, 3376 NEEDS-ACTION, 3377 IN-PROCESS, CANCELLED 3378 . . . URL 0 or 1 3380 . . . X-PROPERTY 0+ 3381 . . . [IANA-PROP] 0+ any IANA registered 3382 property 3384 . . . VALARM 0+ 3385 CAP Expires September 2001 3387 . . . . ACTION 1 3388 . . . . ALARMID 0 or 1 MUST be 1 if multiple 3389 VALARMs are present in 3390 same component. 3391 . . . . ATTACH 0+ 3392 . . . . DESCRIPTION 0 or 1 3393 . . . . DURATION 0 or 1 if present REPEAT MUST be 3394 present 3395 . . . . REPEAT 0 or 1 if present DURATION MUST be 3396 present 3397 . . . . SUMMARY 0 or 1 3398 . . . . TRIGGER 1 3399 . . . . X-PROPERTY 0+ 3400 . . . . [IANA-PROP] 0+ any IANA registered 3401 property 3403 . . VJOURNAL 0+ 3404 . . . ATTENDEE 0 3405 . . . DESCRIPTION 1 Can be null. 3406 . . . DTSTAMP 1 3407 . . . DTSTART 1 3408 . . . ORGANIZER 1 3409 . . . UID 1 3411 . . . ATTACH 0+ 3412 . . . CATEGORIES 0 or 1 This property MAY contain a 3413 list of values 3414 . . . CLASS 0 or 1 3415 . . . COMMENT 0 or 1 3416 . . . CONTACT 0+ 3417 . . . CREATED 0 or 1 3418 . . . EXDATE 0+ 3419 . . . EXRULE 0+ 3420 . . . LAST-MODIFIED 0 or 1 3421 . . . METHOD 1 <> 3423 . . . RDATE 0+ 3424 . . . RECURRENCE-ID 0 or 1 MUST only if referring to 3426 an instance of a recurring 3427 calendar component. 3428 Otherwise it MUST NOT be 3429 present. 3430 . . . RELATED-TO 0+ 3431 . . . RRULE 0+ 3432 . . . SEQUENCE 0 or 1 MUST be present if non- 3433 zero. MAY be 3434 . . . . . present if zero. 3436 CAP Expires September 2001 3438 . . . STATUS 0 or 1 3439 . . . SUMMARY 0 or 1 Can be null 3440 . . . URL 0 or 1 3441 . . . X-PROPERTY 0+ 3442 . . . [IANA-PROP] 0+ any IANA registered 3443 property 3445 . . VFREEBUSY 0 3447 . . VTIMEZONE 0+ MUST be present if any 3448 date/time refers 3449 to a timezone 3450 . . . DAYLIGHT 0+ MUST be one or more of 3451 either STANDARD 3452 or DAYLIGHT 3453 . . . . . COMMENT 0 or 1 3454 . . . . . DTSTART 1 3455 . . . . . RDATE 0+ if present RRULE MUST NOT 3456 be present 3457 . . . . . RRULE 0+ if present RDATE MUST NOT 3458 be present 3459 . . . . . TZNAME 0 or 1 3460 . . . . . TZOFFSET 1 3461 . . . . . TZOFFSETFROM 1 3462 . . . . . TZOFFSETTO 1 3463 . . . . . X-PROPERTY 0+ 3464 . . . . . [IANA-PROP] 0+ any IANA registered 3465 property 3466 . . . LAST-MODIFIED 0 or 1 3467 . . . STANDARD 0+ 3468 . . . . . COMMENT 0 or 1 3469 . . . . . DTSTART 1 3470 . . . . . RDATE 0+ if present RRULE MUST NOT 3471 be present 3472 . . . . . RRULE 0+ if present RDATE MUST NOT 3473 be present 3474 . . . . . TZNAME 0 or 1 3475 . . . . . TZOFFSETFROM 1 3476 . . . . . TZOFFSETTO 1 3477 . . . . . X-PROPERTY 0+ 3478 . . . . . [IANA-PROP] 0+ any IANA registered 3479 property 3480 . . . TZID 1 3481 . . . TZURL 0 or 1 3482 . . . X-PROPERTY 0+ 3483 . . . [IANA-PROP] 0+ any IANA registered 3484 property 3485 CAP Expires September 2001 3487 Server Restriction Table for the MODIFY command 3489 Component/Property Presence Comment 3490 --------------------- -------- -------------------------- 3492 VCAP 1+ 3493 . VCALENDAR 1+ 3494 . . TARGET 1 3496 . . VERSION 1 MUST be 2.0 3498 . . CMDID 0 or 1 MUST be returned if the 3499 request contained a CMDID 3500 . . REQUEST-STATUS 0 if not creating a calendar 3501 1+ if creating a calendar 3503 . . . VCAR 0+ 3504 . . . . REQUEST-STATUS 1+ 3505 . . . . * 0 No other VCAR properties are 3506 present 3507 . 3508 . . . VCOMMAND 0 3510 . . . VEVENT 0+ 3511 . . . . REQUEST-STATUS 1+ 3512 . . . . * 0 No other VEVENT properties 3513 are present 3514 . . . . VALARM 0 if VEVENT was successfully 3515 saved 3516 1+ if there were errors saving 3517 alarms 3518 . . . . . REQUEST-STATUS 1+ 3520 . . . VFREEBUSY 0+ 3521 . . . . REQUEST-STATUS 1+ 3522 . . . . * 0 No other VFREEBUSY 3523 properties are 3524 present 3526 . . . VJOURNAL 0+ 3527 . . . . REQUEST-STATUS 1+ 3528 . . . . * 0 No other VJOURNAL properties 3529 are present 3531 . . . VQUERY 0+ 3532 . . . . REQUEST-STATUS 1+ 3533 CAP Expires September 2001 3535 . . . . * 0 No other VQUERY properties 3536 are present 3538 . . . VTODO 0+ 3539 . . . . REQUEST-STATUS 1+ 3540 . . . . * 0 No other VTODO properties 3541 are present 3542 . . . . VALARM 0 if VTODO was successfully 3543 saved 3544 1+ if there were errors saving 3545 alarms 3546 . . . . . REQUEST-STATUS 1+ 3548 [Editor�s notes: Issues: 3549 freebusy - a cap server should dynamically calculate freebusy 3550 information we recommend that you cannot create, modify, or 3551 delete freebusy composers ] 3553 In the example below, the start and end time of the event with 3554 UID abcd12345 is changed and the LOCATION property is removed. 3556 C: SENDDATA 3557 C: Content-type:text/calendar; Method=MODIFY; 3558 C: Component=VCOMMAND 3559 C: 3560 C: BEGIN:VCAP 3561 C: VERSION:2.1 3562 C: BEGIN:VCOMMAND 3563 C: METHOD:MODIFY 3564 C: TARGET:relcal2 3565 C: BEGIN:VCOMMAND 3566 C: BEGIN:VQUERY 3567 C: QUERY:SELECT UID FROM VEVENT WHERE UID = 'abcd12345' 3568 C: END:VQUERY 3569 C: BEGIN:VEVENT 3570 C: DTSTART:19990421T160000Z 3571 C: DTEND:19990421T163000Z 3572 C: LOCATION:Joe's Diner 3573 C: END:VCOMMAND 3574 C: END:VEVENT 3576 C: BEGIN:VEVENT 3577 C: DTSTART:19990421T160000Z 3578 C: DTEND:19990421T163000Z 3579 C: END:VEVENT 3580 C: END:VCOMMAND 3581 C: END:VCAP 3582 C: . 3584 CAP Expires September 2001 3586 S: 2.0 cap://cal.example.com/relcal2 3588 And in this example, all instances of "Building 6" are 3589 replaced by "New office lobby" in VEVENTs: 3591 C: SENDDATA 3592 C: Content-type:text/calendar; Method=MODIFY; 3593 C: Component=VCOMMAND 3594 C: 3595 C: BEGIN:VCAP 3596 C: VERSION:2.1 3597 C: BEGIN:VCOMMAND 3598 C: METHOD:MODIFY 3599 C: TARGET:relcal2 3600 C: BEGIN:VCOMMAND 3601 C: BEGIN:VEVENT 3602 C: LOCATION:Building 6 3603 C: END:VEVENT 3604 C: BEGIN:VEVENT 3605 C: LOCATION:New office lobby 3606 C: END:VEVENT 3607 C: END:VCOMMAND 3608 C: END:VCOMMAND 3609 C: END:VCAP 3610 C: . 3611 S: 2.0 cap://cal.example.com/relcal2 3613 7.2.1.6 MOVE Method 3615 Arguments: ContainerId 3617 Data: data as described below 3619 Result: 2.0 - success 3620 2.2 - will attempt operation on the remote CAP 3621 server 3622 Permission 3623 Calendar already exists 3624 Bad args 3625 Parent Calendar(s) not found 3627 This method is used to move a calendar within the CS's 3628 hierarchy of calendars. 3630 Restriction Table 3631 Component/Property Presence Comment 3632 ------------------- -------- --------------------- 3633 VCAP 1+ The CUA can send up 3634 CAP Expires September 2001 3636 PIPELINE commands without 3637 processing a response 3639 . VERSION 1 MUST be 2.0 3641 . VCOMMAND 1 MUST have at least one 3642 VCALENDAR 3644 . . CMDID 0 or 1 If CMDID is not supplied, 3645 then there must not be 3646 pending replies to 3647 previous command. 3649 . . [IANA-PROP] 0+ any IANA registered 3650 property 3652 . . METHOD 1 MUST be MOVE. 3653 . . TARGET 1 MUST be a the CSID or 3654 CALID 3656 . . VCALENDAR 1+ 3657 . . . CALMASTER 0 3658 . . . NAME 0 3659 . . . OWNER 0 3660 . . . RELCALID 1 3661 . . . TZID 0 3662 . . . [IANA-PROP] 0+ any IANA registered 3663 property 3665 Server Restriction Table for the MOVE command 3667 Component/Property Presence Comment 3668 ------------------- -------- ----------------------------- 3670 VCAP 1+ 3672 . VCALENDAR 1+ 3674 . . TARGET 1 3675 . . VERSION 1 MUST be 2.0 3677 . . CMDID 0 or 1 MUST be returned if the 3678 request contained 3679 a CMDID 3680 . . REQUEST-STATUS 1+ 3682 --------------------------------------------------------- 3683 CAP Expires September 2001 3685 [Editors note: Issues: 3686 1) Should one be able to move a calendar owned by person X 3687 into a calendar owned by person Y. (Can these such rights be 3688 specified in VCARs?) 3689 2) Should we also be able to move components from one 3690 calendar to another? What if the calendars are owned by 3691 different users? (With components one can do a copy, then 3692 delete the original.) 3693 3) There was very little information about MOVE in CAP. Why 3694 was it added? Was there some major need for it? 3695 4) Can one move multiple calendars into one calendar? 3696 ] 3698 7.2.1.7 NOOP Method 3700 Arguments: none 3702 Data: none 3704 Result: 2.0 - success 3706 This method does nothing. It can be sent to the server 3707 periodically to request that the CS not time out the session. 3709 7.2.1.8 READ Method 3711 Arguments: ContainerId 3713 Data: data as described below 3715 Result: 2.0 - 3716 - successful and the requested data follows 3717 2.2 - will attempt read on the remote CAP server 3718 Permission 3719 Bad args 3721 Restriction Table 3723 Component/Property Presence Comment 3724 ------------------- -------- --------------------------- 3725 VCAP 1+ The CUA can send 3726 PIPELINE commands 3727 without processing a 3728 response 3730 . VERSION 1 MUST be 2.0 3731 . [IANA-PROP] 0+ any IANA registered 3732 property 3733 CAP Expires September 2001 3735 . VCOMMAND 1 MUST have at least one 3736 container (VCALENDAR, 3737 VCAR, VQUERY, VEVENT, 3738 VTODO, VJOURNAL) 3739 . . CMDID 0 or 1 If CMDID is not supplied, 3740 then there must not be pending 3741 replies to previous command. 3742 . . [IANA-PROP] 0+ any IANA registered 3743 property 3744 . . METHOD 1 MUST be READ 3745 . . TARGET 1+ MUST be the CALID 3747 . . VCALENDAR 0+ 3748 . . . CALMASTER 0 or 1 3749 . . . NAME 0 or 1 3750 . . . OWNER 1+ 3751 . . . RELCALID 1 3752 . . . TZID 0 or 1 3753 . . . [IANA-PROP] 0+ any IANA registered 3754 property 3756 . . VCAR 0 3758 . . VQUERY 1 3759 . . . EXPAND 0 or 1 3760 . . . MAXRESULTS 0 or 1 3761 . . . MAXSIZE 0 or 1 3762 . . . QUERYNAME 1 3763 . . . QUERY 1 3764 . . . [IANA-PROP] 0+ any IANA registered 3765 property 3767 . . VEVENT 0 3768 . . VTODO 0 3769 . . VJOURNAL 0 3770 . . VFREEBUSY 0 3772 . . VTIMEZONE 0+ MUST be present if any 3773 date/time refers 3774 to a timezone 3775 . . . DAYLIGHT 0+ MUST be one or more of 3776 either STANDARD 3777 or DAYLIGHT 3778 . . . . . COMMENT 0 or 1 3779 . . . . . DTSTART 1 3780 . . . . . RDATE 0+ if present RRULE MUST NOT 3781 be present 3782 . . . . . RRULE 0+ if present RDATE MUST NOT 3783 CAP Expires September 2001 3785 be present 3786 . . . . . TZNAME 0 or 1 3787 . . . . . TZOFFSET 1 3788 . . . . . TZOFFSETFROM 1 3789 . . . . . TZOFFSETTO 1 3790 . . . . . X-PROPERTY 0+ 3791 . . . . . [IANA-PROP] 0+ any IANA registered 3792 property 3793 . . . LAST-MODIFIED 0 or 1 3794 . . . STANDARD 0+ 3795 . . . . . COMMENT 0 or 1 3796 . . . . . DTSTART 1 3797 . . . . . RDATE 0+ if present RRULE MUST NOT 3798 be present 3799 . . . . . RRULE 0+ if present RDATE MUST NOT 3800 be present 3801 . . . . . TZNAME 0 or 1 3802 . . . . . TZOFFSETFROM 1 3803 . . . . . TZOFFSETTO 1 3804 . . . . . X-PROPERTY 0+ 3805 . . . . . [IANA-PROP] 0+ any IANA registered 3806 property 3807 . . . TZID 1 3808 . . . TZURL 0 or 1 3809 . . . X-PROPERTY 0+ 3810 . . . [IANA-PROP] 0+ any IANA registered 3811 property 3813 Server Restriction Table for the READ command 3815 Component/Property Presence Comment 3816 --------------------- -------- -------------------------- 3818 VCAP 1+ 3819 . VCALENDAR 1+ 3820 . . TARGET 1 3822 . . VERSION 1 MUST be 2.0 3824 . . CMDID 0 or 1 MUST be returned if the 3825 request contained a CMDID 3826 . . REQUEST-STATUS 0 if not creating a calendar 3827 1+ if creating a calendar 3829 . . . VCAR 0+ 3830 . . . . REQUEST-STATUS 1+ 3831 . . . . * 0 No other VCAR properties are 3832 CAP Expires September 2001 3834 present 3835 . 3836 . . . VCOMMAND 0 3838 . . . VEVENT 0+ 3839 . . . . REQUEST-STATUS 1+ 3840 . . . . * 0 No other VEVENT properties 3841 are present 3842 . . . . VALARM 0 if VEVENT was successfully 3843 saved 3844 1+ if there were errors saving 3845 alarms 3846 . . . . . REQUEST-STATUS 1+ 3848 . . . VFREEBUSY 0+ 3849 . . . . REQUEST-STATUS 1+ 3850 . . . . * 0 No other VFREEBUSY 3851 properties are 3852 present 3854 . . . VJOURNAL 0+ 3855 . . . . REQUEST-STATUS 1+ 3856 . . . . * 0 No other VJOURNAL properties 3857 are present 3859 . . . VQUERY 0+ 3860 . . . . REQUEST-STATUS 1+ 3861 . . . . * 0 No other VQUERY properties 3862 are present 3864 . . . VTODO 0+ 3865 . . . . REQUEST-STATUS 1+ 3866 . . . . * 0 No other VTODO properties 3867 are present 3868 . . . . VALARM 0 if VTODO was successfully 3869 saved 3870 1+ if there were errors saving 3871 alarms 3872 . . . . . REQUEST-STATUS 1+ 3874 Read Events 3876 In the example below events on March 10,1999 between 080000Z 3877 and 190000Z are read. In this case only 4 properties for each 3878 event are returned. Two calendars are specified. Only booked 3879 (vs scheduled) entries are to be returned. The first returns 3880 CAP Expires September 2001 3882 two VEVENTS that match in that TARGET, the second result 3883 returns only one VEVENT for the second TARGET. 3885 C: SENDDATA 3886 C: Content-type:text/calendar; Method=READ; Component=VQUERY 3887 C: 3888 C: BEGIN:VCAP 3889 C: VERSION:2.1 3890 C: BEGIN:VCOMMAND 3891 C: METHOD:READ 3892 C: CMDID:xyz12345 3893 C: TARGET:relcal2 3894 C: TARGET:cap://bobo.ex.com/relcal3 3895 C: BEGIN:VQUERY 3896 C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID 3897 FROM VEVENT 3898 WHERE DTEND >= '19990310T080000Z' 3899 AND DTSTART <= '19990310T190000Z' 3900 AND METHOD = 'CREATE' 3901 C: END:VQUERY 3902 C: END:VCOMMAND 3903 C: END:VCAP 3904 C: . 3905 S: 2.0 cap://cal.example.com/relcal2 3906 S: Content-type:text/calendar; Method=RESPONSE; 3907 Optinfo=VERSION:2.1 3908 S: Content-Transfer-Encoding: 7bit 3909 S: 3910 S: BEGIN:VCAP 3911 S: VERSION:2.1 3912 S: METHOD:RESPONSE 3913 S: BEGIN:VEVENT 3915 S: DTSTART:19990310T090000Z 3916 S: DTEND:19990310T100000Z 3917 S: UID:abcxyz12345 3918 S: SUMMARY:Meet with Sir Elton 3919 S: END:VEVENT 3920 S: BEGIN:VEVENT 3921 S: DTSTART:19990310T130000Z 3922 S: DTEND:19990310T133000Z 3923 S: UID:abcxyz8999 3924 S: SUMMARY:Meet with brave brave Sir Robin 3925 S: END:VEVENT 3926 S: END:VCAP 3927 S: . 3928 S: 2.0 cap://bobo.ex.com/relcal3 3929 S: Content-type:text/calendar; Method=RESPONSE; 3930 S: Component=VDATA; Optinfo=VERSION:2.1 3931 CAP Expires September 2001 3933 S: Content-Transfer-Encoding: 7bit 3934 S: 3935 S: BEGIN:VCAP 3936 S: VERSION:2.1 3937 S: METHOD:RESPONSE 3938 S: BEGIN:VDATA 3939 S: BEGIN:VEVENT 3940 S: DTSTART:19990310T140000Z 3941 S: DTEND:19990310T150000Z 3942 S: UID:123456asdf 3943 S: SUMMARY:Summer Budget 3944 S: END:VEVENT 3945 S: END:VDATA 3946 S: END:VCAP 3947 S: . 3949 The return values are subject to VCAR filtering. That is, if 3950 the request contains properties to which the UPN does not have 3951 access, those properties will not appear in the return values. 3952 If the UPN has access to at least one property of events, but 3953 has been denied access to all properties called out in the 3954 request, the response will contain a single REQUEST-STATUS 3955 property indicating the error. That is, the VEVENT 3956 components will be the following: 3958 [EDITORS NOTE: Should the one(s) that the UPN has access to 3959 - be 3960 returned?] 3961 S: 2.0 cap://bobo.ex.com/sally 3962 S: Content-type:text/calendar; 3963 Method=RESPONSE;Component=VDATA; 3964 S: Optinfo=VERSION:2.1 3965 S: Content-Transfer-Encoding: 7bit 3966 S: 3967 S: BEGIN:VCAP 3968 S: VERSION:2.1 3969 S: BEGIN:VDATA 3970 S: BEGIN:VEVENT 3971 S: REQUEST-STATUS:3.8 3972 S: END:VEVENT 3974 S: END:VDATA 3975 S: END:VCAP 3976 S: . 3978 If the UPN has no access to any events at all, the response 3979 will simply be an empty data set. The response looks the same 3980 CAP Expires September 2001 3982 if there are particular events to which the requester has been 3983 denied access. 3985 S: 2.0 cap://bobo.ex.com/sally 3986 S: Content-type:text/calendar; Method=RESPONSE; 3987 S: Component=VDATA; 3988 S: Optinfo=VERSION:2.1 3989 S: Content-Transfer-Encoding: 7bit 3990 S: 3991 S: BEGIN:VCAP 3992 S: VERSION:2.1 3993 S: BEGIN:VDATA 3994 S: END:VDATA 3995 S: END:VCAP 3996 S: . 3998 Find alarms within a range of time for booked (METHOD = 3999 CREATE) VEVENTs. 4001 C: SENDDATA 4002 C: Content-type:text/calendar; Method=READ; Component=VQUERY 4003 C: 4004 C: BEGIN:VCAP 4005 C: VERSION:2.1 4006 C: BEGIN:VCOMMAND 4007 C: METHOD:READ 4008 C: CMDID:xyz12345 4009 C: TARGET:relcal2 4010 C: TARGET:cap://bobo.ex.com/relcal3 4011 C: BEGIN:VQUERY 4012 C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID, VALARM.* 4013 FROM VEVENT,VTODO 4014 WHERE VALARM.TRIGGER >= '19990310T080000Z' 4015 AND VALARM.TRIGGER <= '19990310T190000Z' 4016 AND METHOD = 'CREATE' 4017 C: END:VQUERY 4018 C: END:VCOMMAND 4019 C: END:VCAP 4020 C: . 4021 S: 2.0 cap://bobo.ex.com/relcal3 4022 S: Content-type:text/calendar; Method=RESPONSE; 4023 S: Optinfo=VERSION:2.1 4024 S: Content-Transfer-Encoding: 7bit 4025 S: 4026 S: BEGIN:VCAP 4027 S: VERSION:2.1 4028 S: METHOD:RESPONSE 4029 S: CMDID:xyz12345 4030 S: TARGET:cap://bobo.ex.com/relcal3 4031 CAP Expires September 2001 4033 S: BEGIN:VEVENT 4034 S: DTSTART:19990310T130000Z 4035 S: DTEND:19990310T133000Z 4037 S: UID:abcxyz8999 4038 S: SUMMARY:Meet with brave brave Sir Robin 4039 S: BEGIN:VALARM 4040 S: TRIGGER:19990310T132500Z 4041 S: SUMMARY:Almost time.. 4042 S: ACTION:DISPLAY 4043 S: END:VALARM 4044 S: END:VEVENT 4045 S: END:VCAP 4046 S: . 4047 S: 2.0 cap://bobo.ex.com/relcal2 4048 S: Content-type:text/calendar; Method=RESPONSE; 4049 S: Optinfo=VERSION:2.1 4050 S: Content-Transfer-Encoding: 7bit 4051 S: 4052 S: BEGIN:VCAP 4053 S: VERSION:2.1 4054 S: METHOD:RESPONSE 4055 S: CMDID:xyz12345 4056 S: TARGET:cap://bobo.ex.com/relcal2 4057 S: BEGIN:VEVENT 4058 S: REQUEST-STATUS:2.0 4059 S: END:VEVENT 4060 S: END:VCAP 4061 S: . 4063 7.2.2 Scheduling Commands 4065 The following provide a set of scheduling commands (or 4066 methods) in CAP. Scheduling commands allow a CU to indirectly 4067 manipulate a calendar by asking another CU to perform an 4068 operation on their calendar. For example, CU-A can request CU- 4069 B to add a meeting to their calendar; in effect inviting CU-B 4070 to the meeting. 4072 Calendar access rights can be granted for scheduling commands 4073 without granting rights for more generalized access with the 4074 calendar commands. 4076 [EDITORS NOTE: This section needs to be completed by adding 4077 the restriction tables for each of these iTIP methods. The 4078 basis for the text is to be taken from [iTIP].] 4079 CAP Expires September 2001 4081 7.2.2.1 Reading Scheduling Components 4083 A CU might be invited to a meeting. If the CU had been invited 4084 by CAP, the entry in the CU calendar will be scheduled, but 4085 not booked. So a CUA will need to look for scheduled entries 4086 in the calendar and present them to the CU or automaticly 4087 decide if the invitation is to be accepted or processed. 4089 Example: 4091 The little league coach places the teams entire schedule into 4092 your calendar. Lets say that every game and practice is on a 4093 Friday night and your calendar now has this iTIP scheduling 4094 data: 4096 BEGIN:VCAP 4097 VERSION:2.0 4098 METHOD:PUBLISH 4099 BEGIN:VEVENT 4100 DTSTAMP;TZID=US/Pacific:20000229T180000 4101 DTSTART;TZID=US/Pacific:20000303T180000 4102 ORGANIZER:coach@little.league.com 4103 SUMMARY: Schedule of games and practice 4104 UID:1-coach@little.league.com 4105 SEQUENCE:0 4106 DESCRIPTION:Please have your child at the field 4107 and ready to play by 6pm. 4108 RRULE:FREQ=WEEKLY;COUNT=10 4109 END:VEVENT 4110 END:VCAP 4112 At this point the above VEVENT is not booked in your calendar, 4113 It is simply scheduled. A CUA would fetch this and all other 4114 scheduled VEVENTs from your calendar with: 4116 C: SENDDATA 4117 C: Content-type:text/calendar; Method=READ; Component=VQUERY 4118 C: 4119 C: BEGIN:VCAP 4120 C: VERSION:2.1 4121 C: BEGIN:VCOMMAND 4122 C: METHOD:READ 4123 C: CMDID:xyz12345 4124 C: TARGET:relcal2 4125 C: BEGIN:VQUERY 4126 C: QUERY:SELECT * WHERE FROM VEVENT METHOD != 'CREATE' 4127 C: END:VQUERY 4128 C: END:VCOMMAND 4129 C: END:VCAP 4130 CAP Expires September 2001 4132 C: . 4134 The the CUA and CU could determine which scheduling items were 4135 to remain on the calendar. Each scheduling component could be 4136 deleted or updated with METHOD:MODIFY to change the METHOD 4137 from PUBLISH, REQUEST, REPLY, ADD, CANCEL, REFRESH, COUNTER, 4138 or DECLINE-COUNTER to what the CU and CUA had decided. 4140 In some cases the CUA could automaticly do the work and inform 4141 the CU. An example of this is CANCEL. If configured to process 4142 METHOD:CANCEL it could METHOD:DELETE the component an inform 4143 the CU that the booked component had been canceled. 4145 The CUA MUST process the scheduled components in the order 4146 sent. Some optimization could be done by the CUA. One example 4147 is if a PUBLISH and later a CANCEL for the same component with 4148 the same SEQUENCE number were scheduled, but not booked. The 4149 CUA might never inform the CU and treat it as if the PUBLISH 4150 had never been received by doing a METHOD:DELETE on both 4151 entries. 4153 It is important to note that scheduled components do not show 4154 up in busy time as BUSY. Only when they are booked does the 4155 TRANSP:OPAQUE property take effect. A CS implementation MAY 4156 mark the time as TENTATIVE. This is an implementation and 4157 administrative choice. 4159 7.2.2.2 PUBLISH 4161 Arguments: 4163 Data: data as described below 4165 Result: 2.0 - success 4166 2.2 - will attempt operation on the remote CAP 4167 server 4168 Permission 4169 Calendar already exists 4170 Bad args 4171 Parent Calendar(s) not found 4173 This method is used to move a calendar within the CS's 4174 hierarchy of calendars. If the CU wishes to keep the published 4175 entry. A METHOD:MODIFY changing the entries METHOD from 4176 PUBLISH to CREATE would be done, booking the entry. Or 4177 METHOD:DELETE if the CU did not wish this scheduled item to 4178 exist in their calendar. 4180 CAP Expires September 2001 4182 7.2.2.3 REQUEST 4184 Arguments: 4186 Data: data as described below 4188 Result: 2.0 - success 4189 2.2 - will attempt operation on the remote CAP 4190 server 4191 Permission 4192 Calendar already exists 4193 Bad args 4194 Parent Calendar(s) not found 4196 This as described in [iTIP] and would be modified just like 4197 PUBLISH above. 4199 7.2.2.4 REPLY 4201 Arguments: 4203 Data: data as described below 4205 Result: 2.0 - success 4206 2.2 - will attempt operation on the remote CAP 4207 server 4208 Permission 4209 Calendar already exists 4210 Bad args 4211 Parent Calendar(s) not found 4213 7.2.2.5 ADD 4215 Arguments: 4217 Data: data as described below 4219 Result: 2.0 - success 4220 2.2 - will attempt operation on the remote CAP 4221 server 4222 Permission 4223 Calendar already exists 4224 Bad args 4225 Parent Calendar(s) not found 4226 CAP Expires September 2001 4228 7.2.2.6 CANCEL 4230 Arguments: 4232 Data: data as described below 4234 Result: 2.0 - success 4235 2.2 - will attempt operation on the remote CAP 4236 server 4237 Permission 4238 Calendar already exists 4239 Bad args 4240 Parent Calendar(s) not found 4242 7.2.2.7 REFRESH 4244 Arguments: 4246 Data: data as described below 4248 Result: 2.0 - success 4249 2.2 - will attempt operation on the remote CAP 4250 server 4251 Permission 4252 Calendar already exists 4253 Bad args 4254 Parent Calendar(s) not found 4256 7.2.2.8 COUNTER 4258 Arguments: 4260 Data: data as described below 4262 Result: 2.0 - success 4263 2.2 - will attempt operation on the remote CAP 4264 server 4265 Permission 4266 Calendar already exists 4267 Bad args 4268 Parent Calendar(s) not found 4270 7.2.2.9 DECLINECOUNTER 4272 Arguments: 4274 CAP Expires September 2001 4276 Data: data as described below 4278 Result: 2.0 - success 4279 2.2 - will attempt operation on the remote CAP 4280 server 4281 Permission 4282 Calendar already exists 4283 Bad args 4284 Parent Calendar(s) not found 4286 7.2.3 iTIP Examples 4288 The following examples describe scenarios for the handling of 4289 incoming iTIP data. An appropriate sort-order for the handling 4290 of incoming iTIP is by UID, Recurrence-id, sequence, dtstamp. 4291 This processing may be optimized, for instance, REFRESHs could 4292 be processed last. 4294 As an update to [iTIP], data with the "COUNTER" method should 4295 be processed even if the Sequence number is stale. 4297 7.2.3.1 Sending and Receiving an iTIP request 4299 In this example A invites B and C to a meeting, B accepts the 4300 meeting and C rejects it. The calendars for A, B and C are 4301 relcal1, relcal2 and relcal3 respectively, and are all on the 4302 same server, "cal.foo.com". A lot of these described actions 4303 are performed by the CUAs and not the users themselves, the 4304 CUAs are called A-c, B-c and C-c respectively. 4306 A wishes to create a meeting with B and C, so A-c uses CAP to 4307 send the following iTIP request to relcal2 and relcal3, while 4308 logged in to "cal.foo.com". 4310 BEGIN:VCAP 4311 VERSION:2.1 4313 CMDID:xhj-dd 4314 BEGIN:VCOMMAND 4315 METHOD:REQUEST 4316 TARGET:cap://cal.foo.com/relcal2 4317 TARGET:relcal3 4318 BEGIN:VEVENT 4319 UID:abcd12345 4320 DTSTART:19990307T180000Z 4321 DTEND:19990307T190000Z 4322 ORGANIZER:cap://cal.foo.com/relcal1 4323 CAP Expires September 2001 4325 ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS- 4326 ACTION:cap://cal.foo.com/relcal2 4327 ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS- 4328 ACTION:cap://cal.foo.com/relcal3 4329 SUMMARY:Important Meeting 4330 END:VEVENT 4331 END:VCOMMAND 4332 END:VCAP 4334 An incoming event (indicated by the value of the "METHOD" 4335 property) then appears in relcal2 and relcal3, with the 4336 following data: 4338 BEGIN:VEVENT 4339 METHOD:REQUEST 4340 UID:abcd12345 4341 DTSTART:19990307T180000Z 4342 DTEND:19990307T190000Z 4343 ORGANIZER:cap://cal.foo.com/relcal1 4344 ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.c 4345 om/relcal2 4346 ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.c 4347 om/relcal3 4348 SUMMARY:Important Meeting 4349 END:VEVENT 4351 B-c and C-c must search for such incoming events, they do so 4352 using the following CAP search: 4354 BEGIN:VCAP 4355 VERSION:2.1 4356 BEGIN:VCOMMAND 4357 METHOD:READ 4358 CMDID:xhr-de 4359 TARGET:relcal2 4360 # or TARGET:relcal3 4361 BEGIN:VCOMMAND 4362 BEGIN:VQUERY 4363 QUERY:SELECT * FROM VEVENT WHERE METHOD = 'REQUEST'; 4364 END:VQUERY 4365 END:VCOMMAND 4366 END:VCOMMAND 4367 END:VCAP 4369 In response to this search they get the above event. B-c and 4370 C-c must then crack open the VEVENT, find the UID and 4371 determine if there is already an event on their calendar with 4372 that UID. To do this they use the following search: 4374 CAP Expires September 2001 4376 BEGIN:VCAP 4377 VERSION:2.1 4378 BEGIN:VCOMMAND 4379 METHOD:READ 4380 CMDID:xhr-df 4381 TARGET:relcal2 4383 BEGIN:VCOMMAND 4384 BEGIN:VQUERY 4385 QUERY:SELECT * FROM VEVENT WHERE UID = 'abcd12345' AND 4386 METHOD = 'CREATE' 4387 END:VQUERY 4388 END:VCOMMAND 4389 END:VCOMMAND 4390 END:VCAP 4392 We assume that the event is not already in their relcal2 or 4393 relcal3. 4395 B-c prompts B who decides to accept the meeting request, and 4396 B-c creates a copy of the event in relcal2, with the 4397 "PARTSTAT" parameter set to ACCEPTED. B-c also sends this copy 4398 to the Organizer at relcal1 as an iTIP REPLY, preserving the 4399 CMDID: 4401 BEGIN:VCAP 4402 VERSION:2.1 4403 CMDID:xhj-dd 4404 METHOD:REPLY 4405 TARGET:cap://cal.foo.com/relcal1 4406 BEGIN:VEVENT 4407 UID:abcd12345 4408 DTSTART:19990307T180000Z 4409 DTEND:19990307T190000Z 4410 ORGANIZER:cap://cal.foo.com/relcal1 4411 ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.foo.com/relcal2 4412 SUMMARY:Important Meeting 4413 END:VEVENT 4414 END:VCAP 4416 C, on the other hand, decides to decline the meeting, and C-c 4417 sends a reply to the Organizer to that effect, as follows: 4419 BEGIN:VCALENDAR 4420 VERSION:2.1 4421 CMDID:xhj-dd 4422 METHOD:REPLY 4423 TARGET:cap://cal.foo.com/relcal1 4424 BEGIN:VEVENT 4425 CAP Expires September 2001 4427 UID:abcd12345 4428 DTSTART:19990307T180000Z 4429 DTEND:19990307T190000Z 4430 ORGANIZER:cap://cal.foo.com/relcal1 4431 ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3 4432 SUMMARY:Important Meeting 4433 END:VEVENT 4434 END:VCALENDAR 4436 It is preferable that C-c store the event in relcal3 even 4437 though it has been declined. Storing the event in relcal3 4438 allows subsequent iTIP messages to be interpreted correctly. 4439 The "PARTSTAT" parameter indicates that the event was refused. 4441 After receiving the replies from relcal2 and relcal3, A-c 4442 updates the version of the event in relcal1 to indicate the 4443 new participation status: 4445 BEGIN:VEVENT 4446 METHOD:REQUEST 4447 UID:abcd12345 4448 DTSTART:19990307T180000Z 4449 DTEND:19990307T190000Z 4450 ORGANIZER:cap://cal.foo.com/relcal1 4451 ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.foo.com/relcal2 4452 ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3 4453 SUMMARY:Important Meeting 4454 END:VEVENT 4456 A-c then sends a new iTIP request to relcal2 only, indicating 4457 the updated information. 4459 7.2.3.2 Handling an iTIP refresh 4461 A little bit later, C is thinking about accepting the event in 4462 the previous example, but first wants to check the current 4463 state of the event. To find the current state C-c uses the 4464 iTIP "REFRESH" method, sending the following to relcal1: 4466 BEGIN:VCALENDAR 4467 VERSION:2.1 4468 CMDID:xud-pn 4469 METHOD:REFRESH 4470 TARGET:cap://cal.foo.com/relcal1 4471 BEGIN:VEVENT 4472 UID:abcd12345 4473 ORGANIZER:cap://cal.foo.com/relcal1 4474 ATTENDEE:cap://cal.foo.com/relcal3 4475 CAP Expires September 2001 4477 DTSTAMP:19990306T202333Z 4478 END:VEVENT 4479 END:VCALENDAR 4481 A-c finds the refresh as an incoming iTIP, and searches for 4482 the corresponding event. Having found the event (with no 4483 changes since the last example) A-c then verifies that relcal3 4484 is in fact an Attendee of the event and is thus allowed to 4485 request a refresh. (In the case of a published event things 4486 are more complicated.) A-c packages the event up as an iTIP 4487 request and sends it to relcal3: 4489 BEGIN:VCALENDAR 4490 VERSION:2.1 4491 CMDID: xud-pn 4492 METHOD:REQUEST 4493 TARGET:cap://cal.foo.com/relcal3 4494 BEGIN:VEVENT 4495 UID:abcd12345 4496 DTSTART:19990307T180000Z 4497 DTEND:19990307T190000Z 4498 ORGANIZER:cap://cal.foo.com/relcal1 4499 ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.foo.com/relcal2 4501 ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3 4502 SUMMARY:Important Meeting 4503 SEQUENCE:0 4504 DTSTAMP:19990306T204333Z 4505 END:VEVENT 4506 END:VCALENDAR 4508 7.2.3.3 Sending and accepting an iTIP counter 4510 Having received the latest copy of the event C wishes to 4511 propose a venue for the event, using an iTIP COUNTER. To do 4512 this C-c sends the following to relcal1: 4514 BEGIN:VCAP 4515 VERSION:2.1 4516 CMDID:zzykjjk 4517 METHOD:COUNTER 4518 TARGET:cap://cal.foo.com/relcal1 4519 BEGIN:VEVENT 4520 UID:abcd12345 4521 DTSTART:19990307T180000Z 4522 DTEND:19990307T190000Z 4523 ORGANIZER:cap://cal.foo.com/relcal1 4524 CAP Expires September 2001 4526 ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3 4527 SUMMARY:Important Meeting 4528 LOCATION:La Belle Province 4529 COMMENT:My favorite restaurant, I'll definitely go if it's 4530 there. 4531 END:VEVENT 4532 END:VCAP 4534 Having sent the information to relcal1, C-c shouldn't store 4535 the new details in relcal3. If C-c updated the version in 4536 relcal3 and relcal1 did not reply to the counter, then relcal3 4537 would have incorrect information. Instead C-c preserves the 4538 correct information and waits for a response from relcal1. A 4539 CUA implementation may wish to preserve this information 4540 itself, externally to the CS. 4542 In order to receive an iTIP counter A-c follows the same 4543 search as for other iTIP data, first find the incoming 4544 message, next find any matching events in the calendar store. 4546 Having found the matching event, A reviews the proposed 4547 changes and decides to accept the COUNTER. To do this, A-c 4548 modifies the version in relcal1 (bumping the sequence number) 4549 to: 4551 BEGIN:VEVENT 4552 METHOD:CREATE 4553 UID:abcd12345 4554 DTSTART:19990307T180000Z 4555 DTEND:19990307T190000Z 4556 ORGANIZER:cap://cal.foo.com/relcal1 4557 ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.foo.com/relcal2 4559 ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3 4560 SUMMARY:Important Meeting 4561 LOCATION:La Belle Province 4562 SEQUENCE:1 4563 END:VEVENT 4565 A-c then sends the updated version as a request to both 4566 relcal2 and relcal3: 4568 BEGIN:VCAP 4569 VERSION:2.1 4570 CMDID:xup-po 4571 METHOD:REQUEST 4572 TARGET:cap://cal.foo.com/relcal2 4573 TARGET:cap://cal.foo.com/relcal3 4574 BEGIN:VEVENT 4575 CAP Expires September 2001 4577 UID:abcd12345 4578 DTSTART:19990307T180000Z 4579 DTEND:19990307T190000Z 4580 ORGANIZER:cap://cal.foo.com/relcal1 4581 ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS- 4582 ACTION:cap://cal.foo.com/relcal2 4583 ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS- 4584 ACTION:cap://cal.foo.com/relcal3 4585 SUMMARY:Important Meeting 4586 LOCATION:La Belle Province 4587 SEQUENCE:1 4588 DTSTAMP:19990307T054339Z 4589 END:VEVENT 4590 END:VCAP 4592 7.2.3.4 Declining an iTIP counter 4594 B does not like the new location and also counters the event, 4595 B-c sends the following iTIP: 4597 BEGIN:VCAP 4598 VERSION:2.1 4599 CMDID:xim-ef 4600 METHOD:COUNTER 4601 TARGET:cap://cal.foo.com/relcal1 4602 BEGIN:VEVENT 4603 UID:abcd12345 4604 DTSTART:19990307T180000Z 4605 DTEND:19990307T190000Z 4606 ORGANIZER:cap://cal.foo.com/relcal1 4607 ATTENDEE:cap://cal.foo.com/relcal2 4608 SUMMARY:Important Meeting 4609 LOCATION:Au Coin Dor=E9 4610 END:VEVENT 4611 END:VCAP 4613 However, C does not accept the counter, and C-c replies with a 4614 decline counter: 4616 BEGIN:VCAP 4617 VERSION:2.1 4618 CMDID:xim-ef 4619 METHOD:DECLINE-COUNTER 4620 TARGET:cap://cal.foo.com/relcal2 4621 BEGIN:VEVENT 4622 DTSTAMP:19990307T093245Z 4623 UID:abcd12345 4624 ORGANIZER:cap://cal.foo.com/relcal1 4625 CAP Expires September 2001 4627 SEQUENCE:1 4628 END:VEVENT 4629 END:VCAP 4631 Fortunately B-c kept the original information when sending the 4632 counter, and there is no problem when no information is 4633 returned in the DECLINE-COUNTER. 4635 8 Response Codes 4636 Numeric response codes are returned at both the transfer and 4637 application layer. The same set of codes is used in both 4638 cases. 4640 [EDITORS NOTE: Do we want to use the same set of codes?] 4642 The format of these codes is described in [iCAL], and extend 4643 in [iTIP] and [iMIP]. The following describes new codes added 4644 to this set. 4646 At the application layer response codes are returned as the 4647 value of a "REQUEST-STATUS" property. The value type of this 4648 property is modified from that defined in [iCAL], to make the 4649 accompanying text optional. 4651 Code Params Description 4652 -------------------------------------------------------------- 4653 2.0 [CMDID] varies 4654 Success, The parameters vary with the 4655 operation and are specified. 4657 2.0.1 [CMDID] Success, send data, terminate with 4658 . 4660 2.0.2 [CMDID] A reply is pending. It could not be com- 4661 pleted in the specified amount of time. 4662 The server awaits a CONTINUE or ABORT 4663 command. If can optionally be followed 4664 by a CMDID. If the SENDDATA object con- 4665 tained a CMDID, then the CS MUST append 4666 the CMDID to the 2.0.2 reply for that 4667 object. 4669 2.0.3 [CMDID] In response to the client issuing an 4670 ABORT command, this reply code indicates 4671 that any command currently underway was 4672 successfully aborted. If can optionally 4673 be followed by a CMDID. If the SENDDATA 4674 CAP Expires September 2001 4676 object contained a CMDID, then the CS 4677 MUST append the CMDID to the 2.0.2 reply 4678 for that object. 4680 2.0.6 [CMDID] An operation is being attempted on a 4681 re-mote server. This response indicates 4682 that the server has not yet been con- 4683 tacted but an attempt will be made to 4684 contact it after the command has been 4685 sent. 4687 3.1.4 [CMDID] Capability not supported. 4689 4.1 [CMDID] Calendar store access denied. 4691 6. 1 [CMDID] Authenticate failure: unsupported au- 4692 thentication mechanism, credentials re- 4693 jected. 4695 6.2 [CMDID] Sender aborted authentication, authenti- 4696 cation exchange cancelled. 4698 6.3 [CMDID] Attempt to create or modify an event 4699 such that it would overlap another event 4700 in either of the following two circum- 4701 stances: 4703 (a) One of the events has a TRANSP 4704 property set to OPAQUE-NOCONFLICT or 4705 TRANSPARENT-NOCONFLICT. 4707 (b) The calendar's ALLOW-CONFLICT 4708 property is set to NO. 4710 6.XXX [CMDID] [EDITORS NOTE: More are in this memo - 4711 add here TODO] 4713 7.0 [CMDID] A timeout has occurred. The server was 4714 unable to complete the operation in the 4715 requested time. 4717 8.0 [CMDID] A failure has occurred in the Receiver 4718 that prevents the operation from 4719 succeeding. 4721 8.1 [CMDID] Sent when a session cannot be 4722 established because the CAP Server is too 4723 busy. 4725 CAP Expires September 2001 4727 8.2 [CMDID] Used to signal that an ICAL object has 4728 exceeded the server's size limit 4730 8.3 [CMDID] A DATETIME value was too large to be 4731 represented on this Calendar. 4733 8.4 [CMDID] A DATETIME value was too far in the past 4734 to be represented on this Calendar. 4736 8.5 [CMDID] An attempt was made to create a new 4737 object but the unique id specified is 4738 already in use. 4740 9.0 [CMDID] An unrecognized command was received. 4742 10.1 [CMDID] 4743 Accompanied by an alternate address. The 4744 RECIPIENT specified should be contacted at 4745 the given alternate address. The 4746 referral address MUST follow the reply 4747 code. 4749 10.2 The server is shutting down. 4751 10.4 The operation has not be performed 4752 because it would cause the resources 4753 (memory, disk,CPU, etc) to exceed the 4754 allocated quota. 4756 10.5 [CMDID] The ITIP message has been queued too too 4757 long. Delivery has been aborted. 4758 -------------------------------------------------------------- 4760 9 Examples 4762 For all the examples in this section, the authenticated user 4763 is user@example.com. 4765 9.1 Authentication Examples 4767 9.1.1 Login Using Kerberos V4 4769 Use Kerberos V4 to authenticate as bill@example.com to the 4770 CAP server on 4771 cal.example.com. 4773 C: 4774 S: 2.0 4775 CAP Expires September 2001 4777 S: . 4778 C: CAPABILTY 4779 S: CAPVERSION=1.0 4780 S: ITIPVERSION=1.0 4781 S: AUTH=KERBEROS_V4 4782 S: AUTH=DIGEST_MD5 4783 S: . 4784 C: AUTHENTICATE KERBEROS_V4 4785 S: AmFYig== 4786 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT 4787 S: or//EoAADZI= 4788 C: DiAF5A4gA+oOIALuBkAAmw== 4789 S: 2.0 4790 S: IDENTITY=bill@example.com 4791 S: CAPVERSION=1.0 4793 S: ITIPVERSION=1.0 4794 S: AUTH=KERBEROS_V4 4795 S: AUTH=DIGEST_MD5 4796 S: CAR=CAR-FULL-1 4797 S: MINDATE=19700101T000000Z 4798 S: MAXDATE=20380118T191407Z 4799 S: . 4801 9.1.2 Error Scenarios 4803 Use of SASL Authorization Identity is not supported. Use the 4804 IDENTITY command instead. If you attempt to use the 4805 Authorization Identity, an error status will be returned. 4807 C: AUTHENTICATE KERBEROS_V4 4808 S: AmFYig== 4809 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT 4810 S: or//EoAADZI= 4811 C: DiAF5A4gA+oOIALuBkAAmw== 4812 S: 6.1 4813 S: . 4815 Sender aborted authentication: 4817 C: AUTHENTICATE KERBEROS_V4 4818 S: AmFYig== 4819 C: . 4820 S: 6.2 4821 S: . 4823 Unsupported mechanism: 4825 CAP Expires September 2001 4827 C: AUTHENTICATE Experimental_Auth 4828 S: 6.3 4829 S: . 4831 9.2 Read Examples 4833 10.2.1. Read From A Single Calendar 4835 In this example bill@example.com reads a day's worth of events 4836 from cap://cal.example.com/opaqueid99. 4838 C: SENDDATA 4839 C: Content-type:text/calendar; Method=READ; Component=VQUERY 4840 C: 4841 C: BEGIN:VCAP 4842 C: VERSION:2.1 4843 C: BEGIN:VCOMMAND 4844 C: METHOD:READ 4845 C: CMDID:xyz12345 4847 C: TARGET:cap://cal.example.com/opaqueid99 4848 C: BEGIN:VQUERY 4849 C: QUERY:SELECT DTSTART,DTEND,SUMMARY, UID FROM VEVENT 4850 WHERE DTEND >= '19990714T080000Z' 4851 AND DTSTART <= '19990715T080000Z' 4852 C: END:VQUERY 4853 C: END:VCOMMAND 4854 C: END:VCAP 4855 C: . 4856 # this response code means that the transport successfully 4857 # delivered the data. 4858 S: 2.0 ; got the request OK ; really 4859 S: . 4860 S: Content-type:text/calendar; Method=RESPONSE; 4861 S: Optinfo=VERSION:2.1 4862 S: Content-Transfer-Encoding: 7bit 4863 S: 4864 S: BEGIN:VCAP 4865 S: VERSION:2.1 4866 S: METHOD:RESPONSE 4867 S: TARGET:cap://cal.example.com/opaqueid99 4868 S: CMDID:xyz12345 4869 S: REQUEST-STATUS:2.0 4870 S: BEGIN:VEVENT 4871 S: DTSTART:19990714T200000Z 4872 S: DTEND:19990714T210000Z 4873 CAP Expires September 2001 4875 S: UID:000444888929922 4876 S: SUMMARY:Blah bla 4877 S: END:VEVENT 4878 S: BEGIN:VEVENT 4879 S: UID:0034848098038888989443 4880 S: SUMMARY:meeting 4881 S: DTEND:19990714T233000Z 4882 S: DTSTART:19990714T223000Z 4883 S: END:VEVENT 4884 S: END:VCAP 4885 S: . 4887 9.2.1 Read From Multiple Calendars 4889 In this example bill@example.com reads a day's worth of events 4890 from cap://cal.example.com/opaqueid101 and 4891 cap://cal.example.com/opaqueid103 4893 C: SENDDATA 4894 C: Content-type:text/calendar; Method=READ; Component=VQUERY 4895 C: 4896 C: BEGIN:VCAP 4897 C: VERSION:2.1 4898 C: BEGIN:VCOMMAND 4899 C: METHOD:READ 4900 C: CMDID:xyz12346 4901 C: TARGET:cap://cal.example.com/opaqueid101 4902 C: TARGET:opaqueid103 4903 C: BEGIN:VQUERY 4904 C: VSCOPE:VEVENT 4906 C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID FROM VEVENT 4907 C: WHERE DTEND >= 19990714T080000Z AND 4908 C: DTSTART <= 19990715T080000Z 4909 C: END:VQUERY 4910 C: END:VCOMMAND 4911 C: END:VCAP 4912 C: . 4913 S: 2.0 4914 S: . 4915 S: Content-Type:multipart/mixed; 4916 S: boundary="--FEE3790DC7E35189CA67" 4917 S: 4918 S: ----FEE3790DC7E35189CA67 4919 S: Content-type:text/calendar; Method=RESPONSE; 4920 S: Optinfo=VERSION:2.1 4921 S: Content-Transfer-Encoding: 7bit 4922 CAP Expires September 2001 4924 S: 4925 S: BEGIN:VCAP 4926 S: VERSION:2.1 4927 S: METHOD:RESPONSE 4928 S: TARGET:cap://cal.example.com/opaqueid103 4929 S: CMDID:xyz12346 4930 S: REQUEST-STATUS:2.0 4931 S: BEGIN:VEVENT 4932 S: UID:0034848098038888989443 4933 S: SUMMARY:meeting 4934 S: DTEND:19990714T233000Z 4935 S: DTSTART:19990714T223000Z 4936 S: END:VEVENT 4937 S: END:VCAP 4938 S: 4939 S: ----FEE3790DC7E35189CA67CE2C 4940 S: Content-type:text/calendar; Method=RESPONSE; 4941 S: Optinfo=VERSION:2.1 4942 S: Content-Transfer-Encoding: 7bit 4943 S: 4944 S: BEGIN:VCAP 4945 S: VERSION:2.1 4946 S: METHOD:RESPONSE 4947 S: TARGET:cap://cal.example.com/opaqueid101 4948 S: CMDID:xyz12346 4949 S: REQUEST-STATUS:4.1 ; access denied 4950 S: END:VCAP 4951 S: 4952 S: ----FEE3790DC7E35189CA67CE2C 4953 S: . 4955 9.2.2 Timeouts 4957 In this example bill@example.com attempts to read a calendar 4958 but the latency time he supplies is not sufficient for the 4959 server to complete the command. 4961 C: SENDDATA 3 4962 C: Content-type:text/calendar; Method=READ; Component=VQUERY 4964 C: 4965 C: BEGIN:VCAP 4966 C: VERSION:2.1 4967 C: BEGIN:VCOMMAND 4968 C: METHOD:READ 4969 C: CMDID:xyz12346 4970 C: TARGET:cap://cal.example.com/opaqueid101 4971 CAP Expires September 2001 4973 C: TARGET:opaqueid103 4974 C: BEGIN:VQUERY 4975 C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID FROM VEVENT 4976 C: WHERE DTEND >= '19990714T080000Z' AND 4977 C: DTSTART <= '19990715T080000Z' 4978 C: END:VQUERY 4979 C: END:VCOMMAND 4980 C: END:VCALENDAR 4981 C: . 4982 S: 7.0 ; xyz12346 4983 S: . 4984 S: . 4986 If Bill wants to continue and give the server more time he 4987 would issue a CONTINUE command: 4989 C: CONTINUE 10 ; xyz12346 4991 If Bill wants to abort the command and not wait any further he 4992 would issue an ABORT command: 4994 C: ABORT ; xyz12346 4995 S: 2.0 4996 S: . 4997 S: . 4999 9.2.3 Using Parent and Children Properties 5001 9.2.4 Query VEVENT.DTSTART and VALARM.DTSTART 5003 10 Implementation Issues 5005 1. What are the minimum component properties set required to 5006 create a new VEVENT, VTODO and VJOURNAL?. PROPOSAL: DTSTART, 5007 SUMMARY and UID. 5009 [EDITORS NOTE (dr): They MUST be the same as for iTIP] 5011 2. What is the state of all undefined properties? PROPOSAL: 5012 Not defined. So a query will not return them, if they are 5013 selected. 5015 [EDITORS NOTE (dr): Many have default values, a CS may return 5016 the default values?] 5017 CAP Expires September 2001 5019 11 Properties 5021 [EDITORS NOTE: These extensions/changes to iCalendar need to 5022 be reformatted to conform to the IANA registration process 5023 defined in section 7 of [iCAL].] 5025 11.1 Calendar Store Properties 5026 The following are properties of the calendar store. 5028 Name Read Value Description 5029 Only Type 5030 -------------------------------------------------------------- 5031 CALMASTER N URI The email address for a 5032 Responsible person. MUST be a 5033 mailto URL. 5035 CSID Y URI The CSID of this calendar 5036 store. If not specified, it is 5037 the same as the hostname or 5038 virtual host name. 5040 DEFAULT_VCARS N TEXT A multivalued property 5041 Containing the default VCARs 5042 for newly created top level 5043 calendars. Each entry is a 5044 CARID It MUST include at a 5045 minimum 5046 READBUSYTIMEINFO,REQUESTONLY, 5047 UPDATEPARTSTATUS, and 5048 DEFAULTOWNER. 5050 MAXDATE Y DATE-TIME The date/time in the future 5051 beyond which the server cannot 5052 represent. If not specified, 5053 then 99991231T235959 will be 5054 assumed. 5056 MINDATE Y DATE-TIME The date/time in the past prior 5057 To which the server cannot 5058 represent. If not specified, 5059 then 00000101T000000 will be 5060 assumed. 5062 CURRENT_DATETIME Y DATE-TIME Current server time. This is 5063 returned as a local time and 5064 TZID. 5066 RECUR_ACCEPTED Y BOOLEAN Boolean value will be set to 5067 CAP Expires September 2001 5069 TRUE if the server will accept 5070 recurrence rules. It will be 5071 set to FALSE if the server will 5072 not accept recurrence rules. If 5073 not specified a CUA MUST assume 5074 TRUE. 5076 RECUR_EXPAND Y BOOLEAN If set to TRUE, the CS supports 5077 The expansion of recurrence 5078 rules. If set to FALSE, the CS 5079 is incapable of expanding 5080 recurrence rules. If not 5081 specified a CUA MUST assume 5082 TRUE. 5084 RECUR_LIMIT Y INTEGER This numeric value describes 5085 How the server handles 5086 unbounded recurrences. The 5087 value is only valid if 5088 RECURRENCE is TRUE. If the 5089 value is 0 it means that the 5090 server supports unbounded 5091 recurrence rules. If it is non- 5092 zero, it is a positive integer 5093 indicating the number of 5094 instances that will be created 5095 when the server expands an 5096 unbounded recurrence rule when 5097 fetched from the CS. A CUA MUST 5098 query for date ranges when this 5099 value is zero. 5101 VERSION Y TEXT The version of the CS. The 5102 Default and the only currently 5103 Supported version is "2.0" to 5104 match the [iCAL] VERSION. 5106 11.2 Calendar Properties 5108 Name Read Value Description 5109 Only Type 5110 -------------------------------------------------------------- 5111 ALLOW-CONFLICTS N BOOLEAN This boolean value indicates 5112 Whether or not the calendar 5113 supports event conflicts. That 5114 is, whether or not any of the 5115 events in the calendar can 5116 overlap. If not specified the 5117 CAP Expires September 2001 5119 default value is TRUE meaning 5120 that conflicts are allowed. 5122 CALSCALE N TEXT The CALSCALE for this calendar. 5123 If not specified the default is 5124 GREGORIAN. 5126 CHARSET N TEXT The default charset for 5127 Localized strings in this 5128 calendar. If not specified, the 5129 default is UTF-8. 5131 CHILDREN Y TEXT The list of sub-calendars 5132 Belonging to this calendar. An 5133 empty list means no children. 5134 The results may be a comma 5135 separated list of children. 5136 Each entry returned is a CALID. 5137 The default is an empty list. 5139 CREATED Y DATE-TIME The timestamp of the calendar's 5140 create date. 5142 DEFAULT_VCAR N TEXT The default VCARs for newly 5143 Created top level calendars. 5144 This is a CARID. The default 5145 value is the value of 5146 DEFAULT_VCAR in the CALSTORE 5147 table. 5149 LANGUAGE N TEXT The default language for 5150 localizable strings in this 5151 calendar. There is no default. 5152 This value MUST NOT be empty. 5154 LAST-MODIFIED N DATE-TIME The timestamp when the 5155 Properties of the calendar were 5156 last updated. Default is the 5157 same as CREATED. 5159 NAME N TEXT The display name for this 5160 calendar. It is a localizable 5161 string. If not provided, an 5162 empty value will be returned. 5164 OWNERS N URI A multi-instanced property 5165 indicating the calendar owner. 5166 Each entry returned will be a 5167 UPN. There must be at least one 5168 CAP Expires September 2001 5170 owner. 5172 PARENT N URI The CALID of this calendars 5173 Parent maintained by a CAP 5174 server. An empty value means 5175 the calendar is the top level 5176 parent. The default value is no 5177 parent. 5179 RELCALID N URI A unique name for the calendar. 5180 There is no default value and 5181 This value MUST NOT be empty. 5183 TOMBSTONE N BOOLEAN TRUE indicator that this 5184 Calendar has been marked as 5185 deleted. The default value is 5186 FALSE. 5188 TZID N TEXT The id of the timezone 5189 Associated with this calendar. 5190 See TZID in [iCAL]. The default 5191 value is GMT. 5193 12 Security Considerations 5195 For the mandatory SASL mechanism that CAP specifies, the 5196 mechanism support is: 5198 MUST authentication 5199 MUST authorization 5200 MAY impersonation 5202 13 CAP Item Registration 5204 This section provides the process for registration of new or 5205 modified CAP entities. 5207 13.1 Registration of New and Modified CAP Entities 5208 New CAP entities are registered by the publication of an IETF 5209 Request for Comment (RFC). Changes to a CAP item are 5210 registered by the publication of a revision of the RFC 5211 defining the method. 5213 13.2 Registration of New Entities 5215 This section defines procedures by which new entities (i.e., 5216 components, properties, parameters, enumerated values or 5217 CAP Expires September 2001 5219 restriction tables) for a CAP item can be registered with the 5220 IANA. 5222 Non-standard, experimental entities can be used by bilateral 5223 agreement, provided the associated properties names follow the 5224 "X-" convention. Such non-standard and experimental entities 5225 are non-IANA entities and need not be registered using this 5226 process. 5228 The procedures defined here are designed to allow public 5229 comment and review of new CAP entities, while posing only a 5230 small impediment to the definition of new properties. 5232 Registration of a new CAP item is accomplished by the 5233 following steps. 5235 13.2.1 Define the Item 5236 A CAP item is defined by completing the following template. 5238 To: ietf-calendar@imc.org 5239 Subject: Registration of CAP item XXX 5240 Item name: 5241 Item purpose: 5242 Description: 5243 CAP terminology changes: 5244 CAP data model changes: 5245 CAP system model changes: 5246 Conformance considerations: 5247 Format definition: 5248 Examples: 5250 The meaning of each field in the template is as follows. 5252 Item name: The name of the item. 5254 Item purpose: The purpose of the item (e.g., Extends the CAP 5255 command set to poll for notifications, etc.). Give a short but 5256 clear description. 5258 Description: Any special notes about the item, how it is to be 5259 used, etc. 5261 CAP terminology changes: Any change or additions to the 5262 existing CAP terminology needs to be specified. 5264 CAP data model changes: Any of the valid property parameters 5265 for the property needs to be specified. 5267 CAP Expires September 2001 5269 CAP system model changes: 5271 Conformance: A clear summary of how and where this CAP item 5272 extension MUST, MAY, SHOULD or can be used. Any changes or 5273 impact to the existing conformance definition for CAP should 5274 be explained. The impact to implementations conforming to the 5275 existing CAP specification should be clearly described. 5277 Format definition: The ABNF for each element of the CAP item 5278 needs to be specified. 5280 Examples: One or more examples of instances of the CAP item 5281 and each of its usage scenarios needs to be specified. 5283 13.2.2 Post the item definition 5285 The item description MUST be posted to the new item discussion 5286 list, ietf-calendar@imc.org. 5288 13.2.3 Allow a comment period 5290 Discussion on the new item MUST be allowed to take place on 5291 the list for a minimum of two weeks. Consensus MUST be reached 5292 on the property before proceeding to the next step. 5294 13.2.4 Submit the proposal for approval 5296 Once the two-week comment period has elapsed, and the proposer 5297 is convinced consensus has been reached on the proposal, the 5298 registration application should be submitted to the Method 5299 Reviewer for approval. The Method Reviewer is appointed by the 5300 Application Area Directors and can either accept or reject the 5301 proposal registration. An accepted registration should be 5302 passed on by the Method Reviewer to the IANA for inclusion in 5303 the official IANA method registry. The registration can be 5304 rejected for any of the following reasons. 1) Insufficient 5305 comment period; 2) Consensus not reached; 3) Technical 5306 deficiencies raised on the list or elsewhere have not been 5307 addressed. The Method Reviewers decision to reject a proposal 5308 can be appealed by the proposer to the IESG, or the objections 5309 raised can be addressed by the proposer and the proposal 5310 resubmitted. 5312 [EDITORS NOTE: John Stracke to review any updates] 5314 13.3 Property Change Control 5315 CAP Expires September 2001 5317 Existing CAP entities can be changed using the same process by 5318 which they were registered. 5320 1. Define the change 5321 2. Post the change 5322 3. Allow a comment period 5323 4. Submit the proposal for approval 5325 Note that the original author or any other interested party 5326 can propose a change to an existing CAP object, but that such 5327 changes should only be proposed when there are serious 5328 omissions or errors in the published memo. The Method Reviewer 5329 can object to a change if it is not backward compatible, but 5330 is not required to do so. 5332 CAP objects definitions can never be deleted from the IANA 5333 registry, but objects which are no longer believed to be 5334 useful can be declared OBSOLETE by adding this text to their 5335 "Item purpose" field. 5337 14 IANA Considerations 5339 This memo defines IANA registered extensions to the attributes 5340 defined by iCalendar, as defined in [iCAL], and [iTIP], as 5341 defined in [VCARD]. 5343 [EDITORS NOTE (DR): RFC2426 - is vCard. This needs more 5344 explanation. What does vCARD have todo with this?] 5346 IANA registration proposals for iCalendar and iTIP are to be 5347 mailed to the registration agent for the "text/calendar" 5348 [MIME] content-type, using the 5349 format defined in section 7 of [iCAL]. 5351 15 Acknowledgments 5353 The following have individuals were major contributors in the 5354 drafting and discussion of this memo: 5356 Harald Alvestrand, Mario Bonin, Andre Courtemanche, Dave 5357 Crocker, Pat Egen, Gilles Fortin, Jeff Hodges, Alex Hoppman, 5358 Bruce Kahn, Lisa Lippert, David Madeo, Bob Mahoney, Bob 5359 Morgan, Pete O'Leary, Richard Shusterman, Tony Small, John 5360 Stracke, Mark Wahl, Alexander Taler. 5362 CAP Expires September 2001 5364 16 Bibliography 5366 [MIME] N. Borenstein and N. Freed, "MIME (Multipurpose 5367 Internet Mail Extensions) Part One: Mechanisms for Internet 5368 Draft UTF-825 July 1996 5370 Specifying and Describing the Format of Internet Message 5371 Bodies", RFC 1521, Bellcore, Innosoft, September 1993. 5373 [TLS] Dierks, Allen, "The TLS Protocol", RFC 2246, January 5374 1999 5376 [RFC2119] TODO... 5378 [SASL] RFC2222 TODO... 5380 [URL] Berners-Lee, Fielding, Masinter, "Uniform Resource 5381 Identifiers 5383 (URI): Generic Syntax", RFC 2396, August 1998. 5385 [iCAL] Dawson, Stenerson, "Internet Calendaring and Scheduling 5386 Core Object Specification (iCalendar)", RFC 2445, November 5387 1998 5389 [iTIP] Silverberg, Mansour, Dawson, Hopson, "iCalendar 5390 Transport-Independent Interoperability Protocol (iTIP)", RFC 5391 2446, November 1998 5393 [iMIP] Dawson, Mansour, Silverberg, "iCalendar Message-Based 5394 Interoperability Protocol (iMIP)", RFC 2445, November 1998 5396 [SQL] "Database Language SQL", ANSI/ISO/IEC 9075: 1992, aka 5397 ANSI X3.135-1992, aka FiPS PUB 127-2 5399 [SQLCOM] ANSI/ISO/IEC 9075:1992/TC-1-1995, Technical 5400 corrigendum 1 to ISO/IEC 9075: 1992, also adopted as Amendment 5401 1 to ANSI X3.135.1992 5403 [UNICODE] The Unicode Consortium, "The Unicode Standard - 5404 - 5405 Worldwide Character Encoding -- Version 1.0", Addison-Wesley, 5406 Volume 1, 1991, Volume 2, 1992. UTF-8 is described in Unicode 5407 Technical Report #4. 5409 [US-ASCII] Coded Character Set--7-bit American Standard Code 5410 for Information Interchange, ANSI X3.4-1986. 5412 [VCARD] RFC.... TODO 5413 CAP Expires September 2001 5415 17 Author's Address 5416 The following address information is provided in a vCard v3.0, 5417 the [VCARD] electronic business card format. 5419 Steve Mansour 5420 Judge, Jury, and Executioner 5421 Netscape, iPlanet 5422 501 E Middlfield Road 5423 Mountain View, CA 94043 USA 5424 Phone: +1-408-276-4268 5425 mailto:sman@netscape.com 5427 Paul Hill 5428 Senior Programmer Analyst 5429 Massachusetts Institute of Technology 5430 W92-172 5431 77 Massachusetts Avenue 5432 Cambridge, MA, USA 5433 02139 5434 Phone: +1-617-253-0124 5435 Fax: +1-617-258-8736 5436 mailto:pbh@mit.edu 5438 Doug Royer 5439 mailto:Doug@Royer.com 5441 George Babics 5442 Steltor (formerly CS&T/Lexacom) 5443 2000 Peel Street 5444 Montreal, Quebec, Canada 5445 H3A 2W5 5446 Tel: (514) 733-8500 x4201 5447 Fax: (514) 733-8878 5448 Mailto: georgeb@steltor.com 5450 18 Full Copyright Statement 5452 "Copyright (C) The Internet Society (2000). All Rights 5453 Reserved. This document and translations of it may be copied 5454 and furnished to others, and derivative works that comment on 5455 or otherwise explain it or assist in its implementation may be 5456 prepared, copied, published and distributed, in whole or in 5457 part, without restriction of any kind, provided that the above 5458 copyright notice and this paragraph are included on all such 5459 copies and derivative works. However, this document itself may 5460 not be modified in any way, such as by removing the copyright 5461 notice or references to the Internet Society or other Internet 5462 CAP Expires September 2001 5464 organizations, except as needed for the purpose of developing 5465 Internet standards in which case the procedures for copyrights 5466 defined in the Internet Standards process MUST be followed, or 5467 as required to translate it into languages other than English. 5469 The limited permissions granted above are perpetual and will 5470 not be revoked by the Internet Society or its successors or 5471 assigns. This document and the information contained herein is 5472 provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE 5473 INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, 5474 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY 5475 THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY 5476 RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS 5477 FOR A PARTICULAR PURPOSE.