idnits 2.17.1 draft-oleary-icap-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-19) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 3193 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** 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.) ** There are 3 instances of too long lines in the document, the longest one being 8 characters in excess of 72. ** There are 311 instances of lines with control characters in the document. ** The abstract seems to contain references ([ICAL]), 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. RFC 2119 keyword, line 171: '...1) MUST, or the adjective REQUIRED, me...' RFC 2119 keyword, line 174: '...2) MUST NOT that the definition is an ...' RFC 2119 keyword, line 177: '...3) SHOULD means that there may exist v...' RFC 2119 keyword, line 182: '...4) SHOULD NOT means that there may exi...' RFC 2119 keyword, line 184: '...ull implications SHOULD be understood ...' (75 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 457 has weird spacing: '... can be using...' == Line 459 has weird spacing: '...of time ident...' == Line 1216 has weird spacing: '...The sequence ...' == Line 2039 has weird spacing: '...ponding compo...' == Line 2556 has weird spacing: '...esponse code ...' == 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 \NoConflict should be given when the Object being appended to the Calendar Stores specified cannot have a time conflict with any Object on any of the Calendar Stores. If a time conflict exists, the server MUST return a NO response and MUST not modify any of the specified Calendar stores. == 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: New Calendar Objects added to a Calendar store with the APPEND command MUST contain all required iCalendar properties. If a required property is missing the server MUST return a NO response and MUST not modify any of the specified Calendar stores. == 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 ICAL.REQUIRED item returns only the iCalendar properties defined as required in [ICAL] for the corresponding component type. Optional and non-standard properties MUST not be returned. == 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 \NoConflict should be given when the Object being appended to the Calendar Stores selected cannot have a time conflict with any Object on any of the Calendar Stores. If a time conflict exists, the server MUST return a NO response and MUST not modify any of the selected Calendar stores. -- 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? 'ICAL' on line 3039 looks like a reference -- Missing reference section? 'ISO-TIME' on line 3054 looks like a reference -- Missing reference section? 'ISO 8601' on line 466 looks like a reference -- Missing reference section? 'RFC 1521' on line 3043 looks like a reference -- Missing reference section? 'RFC 821' on line 3048 looks like a reference -- Missing reference section? 'ITIP' on line 3058 looks like a reference -- Missing reference section? 'RFC 1730' on line 3083 looks like a reference -- Missing reference section? 'RFC 1731' on line 3067 looks like a reference Summary: 11 errors (**), 0 flaws (~~), 11 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet-Draft 6/16/98 2 draft-oleary-icap-04.doc Expires 6 months from above date 4 Internet Calendar Access Protocol (ICAP) 6 Status of this Memo 8 This document is an Internet-Draft. Internet-Drafts are 9 working documents of the Internet Engineering Task Force 10 (IETF), its areas, and its working groups. Note that other 11 groups may also distribute working documents as Internet- 12 Drafts. 14 Internet-Drafts are draft documents valid for a maximum of six 15 months and may be updated, replaced, or obsoleted by other 16 documents at any time. It is inappropriate to use Internet-Drafts as 17 reference material or to cite them other than as "work in progress." 19 To view the entire list of current Internet-Drafts, please check 20 the "1id-abstracts.txt" listing contained in the Internet-Drafts 21 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 22 (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au 23 (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu 24 (US West Coast). 26 Abstract 28 This Internet Calendar Access Protocol (ICAP) allows a client to 29 access, manipulate and store Calendar information on a server. ICAP 30 employs the iCalendar format [ICAL] for interchange of calendaring 31 information. 33 ICAP includes operations for creating Calendar stores on a server, 34 opening them and retrieving information about them. When a 35 Calendar Store has been opened, it can be bounded by start and end 36 times so that the client can act on a smaller subset of Calendar 37 information for more efficient operation. ICAP allows users to store 38 new Calendar Objects into their own Calendar store and Calendar 39 stores owned by other users with a single operation. 41 ICAP supports searching iCalendar objects within a Calendar Store. 42 Searches can be based on any iCalendar property and filtered by 43 iCalendar Component type. 45 O'Leary, Pete 1 47 Internet-Draft 6/16/98 48 draft-oleary-icap-04.doc Expires 6 months from above date 50 Table of Contents 52 STATUS OF THIS MEMO..................................................1 53 ABSTRACT.............................................................1 54 TABLE OF CONTENTS....................................................2 55 1. PROTOCOL OVERVIEW.................................................4 56 1.1. CONVENTIONS USED IN THIS DOCUMENT...............................4 57 1.2. LINK LEVEL......................................................4 58 1.3. COMMANDS AND RESPONSES..........................................5 59 1.3.1. Client Protocol Sender and Server Protocol Receiver..........5 60 1.3.2. Server Protocol Sender and Client Protocol Receiver..........6 61 1.4. DATA FORMATS....................................................7 62 1.4.1. Atom.........................................................7 63 1.4.2. Number.......................................................7 64 1.4.3. String.......................................................7 65 1.4.4. Parenthesized Lists...........................................8 66 1.4.5. NIL...........................................................8 67 1.4.6. Dates.........................................................8 68 1.4.7. Periods of Time...............................................8 69 1.5. RESPONSE WHEN NO COMMAND IN PROGRESS...........................9 70 1.6. AUTOLOGOUT TIMER..............................................10 71 1.7. MULTIPLE COMMANDS IN PROGRESS.................................10 72 1.8. CALENDAR STORE................................................10 73 1.9. CALENDAR OBJECTS AND COMPONENTS...............................10 74 1.10. UNIQUE IDENTIFIERS............................................11 75 1.11. CALENDAR STORE NAMING.........................................11 76 1.12. DEFAULT CALENDAR..............................................12 77 1.13. ACCESS CONTROL................................................13 78 1.14. SERVER STATES.................................................13 79 1.13.1. Non-Authenticated State....................................14 80 1.13.2. Authenticated State........................................14 81 1.13.3. Selected State.............................................14 82 1.13.4. Logout State...............................................14 83 2. SCHEDULING OPERATIONS............................................14 84 2.1 OPERATIONS SUPPORTED BY ICAP....................................14 85 2.1.1. Calendar Browsing............................................14 86 2.1.2. Freetime Search..............................................15 87 2.1.3. Creating, Deleting and Modifying Calendar Objects...........15 88 2.1.4. Group Scheduling............................................15 89 2.2. OPERATIONS NOT SUPPORTED BY ICAP...............................15 90 2.2.1. Meeting Invitations..........................................15 91 2.2.2. Directory Services...........................................16 92 3. ICAP COMMANDS - ANY STATE........................................16 93 3.1. CAPABILITY COMMAND.............................................16 94 3.2. NOOP COMMAND...................................................17 95 3.4. LOGOUT COMMAND.................................................17 96 3.5. X-(ATOM) EXPERIMENTAL COMMANDS.................................18 97 4. ICAP COMMANDS - NON-AUTHENTICATED STATE..........................18 98 4.1. AUTHENTICATE COMMAND...........................................19 99 4.2. LOGIN COMMAND..................................................20 100 5. ICAP COMMANDS - AUTHENTICATED STATE..............................20 102 O'Leary, Pete 2 104 Internet-Draft 6/16/98 105 draft-oleary-icap-04.doc Expires 6 months from above date 107 5.1. SELECT COMMAND.................................................20 108 5.2. EXAMINE COMMAND...............................................23 109 5.3. CREATE COMMAND................................................24 110 5.4. DELETE COMMAND................................................25 111 5.5. RENAME COMMAND................................................25 112 5.6. LIST COMMAND..................................................25 113 5.7. LSUB COMMAND..................................................27 114 5.8. SUBSCRIBE COMMAND.............................................27 115 5.9. UNSUBSCRIBE COMMAND...........................................27 116 5.10. APPEND COMMAND................................................28 117 5.11. ATTRIBUTES COMMAND............................................30 118 5.12. FREEBUSY COMMAND..............................................32 119 6. ICAP COMMANDS - SELECTED STATE...................................33 120 6.1. CLOSE COMMAND..................................................33 121 6.2. RANGE COMMAND..................................................34 122 6.3. CHECK COMMAND..................................................35 123 6.4. EXPUNGE COMMAND................................................35 124 6.5. FETCH COMMAND..................................................36 125 6.6. STORE COMMAND..................................................38 126 6.7. COPY COMMAND...................................................41 127 6.8. MOVE COMMAND...................................................41 128 6.9. UID COMMAND....................................................42 129 6.10. SEARCH COMMAND................................................42 130 7. SERVER RESPONSES.................................................45 131 7.1. SERVER RESPONSES - STATUS RESPONSES...........................46 132 7.1.1. OK Response..................................................47 133 7.1.2. NO Response..................................................47 134 7.1.3. BAD Response.................................................47 135 7.1.4. PREAUTH Response.............................................47 136 7.1.5. BYE Response................................................48 137 7.2. SERVER RESPONSES - DATA RESPONSES..............................48 138 7.2.1. CAPABILITY Response..........................................49 139 7.2.2. LIST Response................................................49 140 7.2.3. LSUB Response................................................50 141 7.2.4. EXISTS Response..............................................50 142 7.2.5. RECENT Response..............................................51 143 7.2.6. EXPUNGE Response.............................................51 144 7.2.7. FETCH Response...............................................52 145 7.2.8. FLAGS Response...............................................52 146 7.2.9. SEARCH Response.............................................52 147 7.3. SERVER RESPONSES - COMMAND CONTINUATION REQUEST.............53 148 8. FORMAL SYNTAX....................................................53 149 9. EXAMPLE SESSIONS.................................................53 150 10. OPEN ISSUES/WORK IN PROGRESS....................................54 151 11. CHANGES FROM PREVIOUS DRAFT VERSION.............................54 152 12. REFERENCES......................................................55 153 13. SECURITY CONSIDERATIONS.........................................55 154 14. AUTHOR'S NOTES..................................................56 156 O'Leary, Pete 3 158 Internet-Draft 6/16/98 159 draft-oleary-icap-04.doc Expires 6 months from above date 161 1. PROTOCOL OVERVIEW 163 1.1. Conventions Used in this Document 165 In examples, "C:" and "S:" indicate lines sent by the client and server 166 respectively. 168 The following terms are used in this document to signify the 169 requirements of this specification. 171 1) MUST, or the adjective REQUIRED, means that the definition is 172 an absolute requirement of the specification. 174 2) MUST NOT that the definition is an absolute prohibition of the 175 specification. 177 3) SHOULD means that there may exist valid reasons in particular 178 circumstances to ignore a particular item, but the full implications 179 MUST be understood and carefully weighed before choosing a 180 different course. 182 4) SHOULD NOT means that there may exist valid reasons in 183 particular circumstances when the particular behavior is acceptable 184 or even useful, but the full implications SHOULD be understood and 185 the case carefully weighed before implementing any behavior 186 described with this label. 188 5) MAY, or the adjective OPTIONAL, means that an item is truly 189 optional. One vendor may choose to include the item because a 190 particular marketplace requires it or because the vendor feels 191 that it enhances the product while another vendor may omit the same 192 item. An implementation which does not include a particular option 193 MUST be prepared to interoperate with another implementation 194 which does include the option. 196 "Can" is used instead of "may" when referring to a possible 197 circumstance or situation, as opposed to an optional facility of the 198 protocol. 200 "User" is used to refer to a human user, whereas "client" refers to the 201 software being run by the user. 203 1.2. Link Level 205 The ICAP server assumes a reliable, stream oriented transport such 206 as that provided by TCP/IP. When ICAP is used with TCP the server 207 listens on TCP port 7668 (subject to change). 209 O'Leary, Pete 4 211 Internet-Draft 6/16/98 212 draft-oleary-icap-04.doc Expires 6 months from above date 214 1.3. Commands and Responses 215 An ICAP session consists of the establishment of a client/server 216 connection, an initial greeting from the server, and client/server 217 interactions. These client/server interactions consist of a client 218 command, server data, and a server completion result response. 220 All interactions transmitted by client and server are in the form of 221 lines; that is, strings that end with a CRLF. The protocol receiver 222 of an ICAP client or server is either reading a line, or is reading a 223 sequence of octets with a known count followed by a line. 224 The ICAP server states a greeting similar to the following: 226 S: * OK ICAP Server ready. 228 The greeting is an untagged response from the server which includes 229 a list of the server's capabilities followed by an optional human- 230 readable message. See below for the description of untagged 231 responses. If the ICAP server supports multiple capabilities (see 232 below) they must be presented using a parenthesized list. It is 233 mandatory that the capability ICAP be presented and that it be first in 234 the list of capabilities. If the capability ICAP is not presented, the 235 client cannot proceed and must close the connection immediately. 237 The server must present an OK response if it is ready to accept a 238 client connection. If the server is not ready to accept such a connect, 239 it must present a BYE response. 241 More examples of valid connection responses: 243 S: * OK (ICAP X-PigLatin) Server ready. 244 S: * OK ICAP It's a wonderful day today! 245 S: * BYE Connection refused. Please try again later. 247 1.3.1. Client Protocol Sender and Server Protocol Receiver 249 The client command begins an operation. Each client command is 250 prefixed with a identifier (typically a short alphanumeric string, e.g. 251 A0001, A0002, etc.) called a "tag". A different tag is generated by 252 the client for each command. 254 There are two cases in which a line from the client does not represent 255 a complete command. In one case, a command argument is quoted 256 with an octet count (see the description of literal in String under Data 257 Formats); in the other case, the command arguments require server 258 feedback (see the AUTHENTICATE command). In some of these 259 cases, the server sends a command continuation request response if it 260 is ready for the octets (if appropriate) and the remainder of the 261 command. This response is prefixed with the token "+". 263 Note: If, instead, the server detected an error in the command, it 264 sends a BAD completion response with tag matching the command 266 O'Leary, Pete 5 268 Internet-Draft 6/16/98 269 draft-oleary-icap-04.doc Expires 6 months from above date 271 (as described below) to reject the command and prevent the client 272 from sending any more of the command. 274 It is also possible for the server to send a completion or intermediate 275 response for some other command (if multiple commands are in 276 progress), or untagged data. In either case, the command 277 continuation request is still pending; the client takes the appropriate 278 action for the response, and reads another response from the server. 280 The protocol receiver of an ICAP server reads a command line from 281 the client, parses the command and its arguments, and transmits 282 server data and a server command completion result response. 284 1.3.2. Server Protocol Sender and Client Protocol Receiver 286 Data transmitted by the server to the client come in four forms: 287 command continuation requests, command completion results, 288 intermediate responses, and untagged responses. 290 A command completion request is prefixed with the token "+". 292 A command completion result response indicates the success or 293 failure of the operation. It is tagged with the same tag as the client 294 command which began the operation. Thus, if more than one 295 command is in progress, the tag in a server completion response 296 identifies the command to which the response applies. There are 297 three possible server completion responses: OK (indicating success), 298 NO (indicating failure), or BAD (indicating protocol error such as 299 unrecognized command or command syntax error). 301 An intermediate response returns data which can only be interpreted 302 within the context of a command in progress. It is tagged with the 303 same tag as the client command which began the operation. Thus, if 304 more than one command is in progress, the tag in an intermediate 305 response identifies the command to which the response applies. A 306 tagged response other than "OK", "NO", or "BAD" is an intermediate 307 response. 309 An untagged response returns data or status messages which may be 310 interpreted outside the context of a command in progress. It is 311 prefixed with the token "*". Untagged data may be sent as a result of 312 a client command, or may be sent unilaterally by the server. There is 313 no syntactic difference between untagged data that resulted from a 314 specific command and untagged data that were sent unilaterally. 316 The protocol receiver of an ICAP client reads a response line from 317 the server. It then takes action on the response based upon the first 318 token of the response, which may be a tag, a "*", or a "+" as 319 described above. 321 A client MUST be prepared to accept any server response at all 323 O'Leary, Pete 6 325 Internet-Draft 6/16/98 326 draft-oleary-icap-04.doc Expires 6 months from above date 328 times. This includes untagged data that it may not have requested. 329 Due to the obviously time-critical nature of applications which may use ICAP, an 330 ICAP server implementation should attempt to keep 331 connected clients "current" by sending updates to the client when a 332 selected Calendar Store is updated. 334 This topic is discussed in greater detail in the Server Responses 335 section. 337 1.4. Data Formats 339 ICAP uses textual commands and responses. Data in ICAP can be in 340 one of several forms: atom, number, string, parenthesized list, dates 341 or NIL. 343 1.4.1. Atom 345 An atom consists of one or more non-special characters. 347 1.4.2. Number 349 A number consists of one or more digit characters, and represents a 350 numeric value. 352 1.4.3. String 354 A string is in one of two forms: literal and quoted string. The literal 355 form is the general form of string. The quoted string form is an 356 alternative that avoids the overhead of processing a literal at the cost 357 of restrictions of what may be in a quoted string. 359 A literal is a sequence of zero or more octets (including CR and LF), 360 prefix-quoted with an octet count in the form of an open brace ("{"), 361 the number of octets, close brace ("}"), and CRLF. In the case of 362 literals transmitted from server to client, the CRLF is immediately 363 followed by the octet data. In the case of literals transmitted from 364 client to server, the client must wait to receive a command 365 continuation request (described later in this document) before 366 sending the octet data (and the remainder of the command). 368 A quoted string is a sequence of zero to 1024 7-bit characters, 369 excluding CR and LF, with double quote (<">) characters at each 370 end. 372 The empty string is respresented as either "" (a quoted string with 373 zero characters between double quotes), as {0} followed by CRLF (a 374 synchronizing literal with an octet count of 0), or as {0+} followed 375 by a CRLF (a non-synchronizing literal with an octet count of 0). 377 Note: Even if the octet count is 0, a client transmitting a literal must 378 wait to receive a command continuation request. 380 O'Leary, Pete 7 382 Internet-Draft 6/16/98 383 draft-oleary-icap-04.doc Expires 6 months from above date 385 1.4.4. Parenthesized Lists 387 Data structures are represented as a "parenthesized list"; a sequence 388 of data items, delimited by space, and bounded at each end by 389 parentheses. A parenthesized list can contain other parenthesized 390 lists, using multiple levels of parentheses to indicate nesting. 392 The empty list is represented as () -- a parenthesized list with no 393 members. 395 1.4.5. NIL 397 The special atom "NIL" represents the non-existence of a particular 398 data item that is represented as a string or parenthesized list, as 399 distinct from the empty string "" or the empty parenthesized list (). 401 1.4.6. Dates 403 All dates given in this document are in a compact form of the ISO 404 8601 date and time format [ISO-TIME]: YYYYMMDD 'T' 405 HHMMSS. Hours are always given using the 24 hour clock. A "Z" 406 may be appended to indicate UTC or "Zulu" time (that's GMT to 407 most people). The TZID property parameter MUST NOT be applied 408 to dates whose time values are specified in UTC. The use of local 409 time in a DATE-TIME or TIME value without the TZID property 410 parameter is to be interpreted as a local time value, in the time zone 411 of the selected calendar. Clients can check the time zone of the 412 selected calendar by using the ATTRIBUTES command (see below.) 414 Note: ICAP servers do not support ISO 8601's week of the year 415 notation. Before storing in an ICAP server, these dates must be 416 converted to the above format. 418 Examples of valid dates: 420 DTSTART:19980927T0700 'Sept. 27, 1998 421 in the local time zone 422 DTSTART:19980927T1300Z 'Sept. 27, 1998 423 in UTC time 424 DTSTART;TZID=America-NYC:20000101T0000 'New Year's Eve in New York City 426 The form of date and time with UTC offset MUST NOT be used. For 427 example, the following is not valid for a date-time value: 429 DTSTART:19980119T230000-08 'Invalid time 430 format 432 1.4.7. Periods of Time 434 A PERIOD value type is used to identify values that contain a 435 precise period of time. The description of this data type has been 437 O'Leary, Pete 8 439 Internet-Draft 6/16/98 440 draft-oleary-icap-04.doc Expires 6 months from above date 442 borrowed from the iCalendar [ICAL] document. A PERIOD is 443 defined by the following notation: 445 period = period-explicit / period-start 447 period-explicit = date-time "/" date-time 448 ; [ISO 8601] complete representation basic format for a period of 449 time consisting of a start and end. 450 ; The start MUST be before the end. 452 period-start = date-time "/" duration 453 ; [ISO 8601] complete representation basic format for a period of 454 time consisting of a start and 455 ; positive duration of time. 457 If the property permits, multiple "period" values can be using a 458 COMMA character (US-ASCII decimal 44) separator character. 459 There are two forms of a period of time. A period of time identified 460 by its start and its end. This format is expressed as the [ISO 8601] 461 complete representation, basic format for "DATE-TIME" start of the 462 period, followed by a SOLIDUS character (US-ASCII decimal 47), 463 followed by the "DATE-TIME" of the end of the period. The start of 464 the period MUST be before the end of the period. A period of time 465 can also be defined by a start time and a positive duration. The 466 format is expressed as the [ISO 8601] complete representation, basic 467 format for the "DATE-TIME" start of the period, followed by a 468 SOLIDUS character (US-ASCII decimal 47), followed by the [ISO 469 8601] basic format for "DURATION" of the period. 471 Examples of valid periods of time: 473 The period starting at 18:00:00 UTC, on January 1, 1999 and ending 474 at 07:00:00 UTC on January 2, 1999 would be: 476 19990101T180000Z/19970102T070000Z 478 The period start at 18:00:00 on January 1, 1999 and lasting 5 hours 479 and 30 minutes would be: 481 19990101T180000Z/PT5H30M 483 No additional content value encoding (i.e., BACKSLASH character 484 encoding) is defined for this value type. 486 1.5. Response when no Command in Progress 488 Server implementations are permitted to send an untagged response 489 while there is no command in progress. Server implementations that 490 send such responses MUST deal with flow control considerations. 491 Specifically, they must either (1) verify that the size of the data does 493 O'Leary, Pete 9 495 Internet-Draft 6/16/98 496 draft-oleary-icap-04.doc Expires 6 months from above date 498 not exceed the underlying transport's available window size, or (2) 499 use non-blocking writes. 501 1.6. Autologout Timer 503 If a server has an inactivity autologout timer, that timer MUST be of 504 at least 10 minutes' duration. The receipt of ANY command from 505 the client during that interval should suffice to reset the autologout 506 timer. 507 1.7. Multiple Commands in Progress 509 The client is not required to wait for the completion result response 510 of a command before sending another command, subject to flow 511 control constraints on the underlying data stream. Similarly, a server 512 is not required to process a command to completion before beginning 513 processing of the next command, unless an ambiguity would result 514 because of a command that would affect the results of other 515 commands. If there is such an ambiguity, the server executes 516 commands to completion in the order given by the client. 518 1.8. Calendar Store 520 The primary purpose of the ICAP protocol is to allow access to, and 521 the modification of, Calendar Stores. A Calendar Store is defined as 522 one set of Calendar Objects that are organized chronologically and 523 given a name. A Calendar Object is one discrete item that may be 524 posted to a calendar. In ICAP, Calendar Objects are represented in 525 iCalendar [ICAL] format and can consist of one or more Calendar 526 Components as described in the iCalendar specification. 528 Objects within a Calendar Store MUST meet one of the two 529 following requirements: 531 ? Every Date-Time property of every Object within the Calendar 532 Store MUST contain a UTC value or a UTC relative value. All 533 Objects within the Calendar Store MUST be sorted by UTC 534 using the per-Component rules specified in section 1.9 below. 535 If all Objects within a Calendar Store are contained within the same 536 time zone and their time values can all be converted to UTC 537 using the same TIMEZONE component, then TIMEZONE 538 components and UTC relative information can be omitted from 539 individual Objects within the Calendar Store. All Objects within 540 the Calendar Store MUST be sorted by using the per- 541 Component rules specified in section 1.9 below. 543 1.9. Calendar Objects and Components 545 iCalendar Objects as specified in [ICAL] consist of a sequence of 546 calendar properties and one or more calendar Components. An ICAP 547 implementation MUST support all valid iCalendar Objects and their 548 Components, with the following qualifiers: 550 O'Leary, Pete 10 552 Internet-Draft 6/16/98 553 draft-oleary-icap-04.doc Expires 6 months from above date 555 ? Calendar Properties, as identified in section 5.4.7 of [ICAL] can 556 be omitted from any Object in a Calendar Store if those 557 Properties are common to all Objects in that Calendar Store. In 558 this case, those Calendar Properties common to every Object in 559 the Calendar Store MUST be returned via the ATTRIBUTES 560 command. If the Calendar Properties for Objects in a Calendar 561 Store can vary from Object to Object, every Object contained 562 within a Calendar Store MUST contain Calendar Properties 563 appropriate to that Object. 564 ? FREEBUSY Components MUST be returned only via the 565 FREEBUSY command. 566 ? Event, To-Do and Journal Components can be intermixed within 567 the same Calendar Store. Event components are sorted according 568 to their DTSTART value. To-Do components are sorted 569 according to their DTSTART value. Journal Components are 570 sorted according to their DTSTART value. 571 ? An Object within a Calendar Store can contain at most ONE 572 Event, To-Do or Journal Component. 574 1.10. Unique Identifiers 576 Each ICAP server, Calendar store and Calendar Object must have a 577 unique identifier ("unique ID" or "UID") associated with it. This 578 unique ID must persist across sessions. Unique ID's in ICAP consist 579 of alphanumeric characters only, are exactly 16 characters in length 580 and are case sensitive. Nothing about the structure of the unique ID 581 must be assumed: they are not guaranteed to represent numeric 582 values, ascending in value, etc. 584 A Calendar store UID need only be unique within the current server 585 and is referred to hereafter as the Calendar Store ID (CSID). A 586 Calendar Object UID need only be unique within its Calendar store 587 and is referred to as the Calendar Object ID (COID). 589 The exact method for ensuring that UID's are unique is 590 implementation dependent. 592 Note that the iCalendar specification [ICAL] defines an attribute 593 called "UID" for calendar Objects which must be globally unique. 594 This value can be created by concatenating the server's host name 595 then the CSID and COID. 597 1.11. Calendar Store Naming 599 Calendar names can be any string of alphanumeric characters and the 600 characters "_" (underscore), "." (period), "-" (hyphen) and "'" 601 (apostrophe). Calendar names can contain spaces, in which case the 602 whole name must be delimited by double quote characters (see 603 below). Calendar names are case sensitive and must be distinct from 604 all other Calendar stores. 606 O'Leary, Pete 11 608 Internet-Draft 6/16/98 609 draft-oleary-icap-04.doc Expires 6 months from above date 611 Calendar names can be hierarchical: the hierarchy is read from left 612 (highest level in the hierarchy) to right and delimited by the "/" 613 (forward slash) character. If a hierarchical name is quoted, the entire 614 name must be quoted. An ICAP implementation is NOT required to 616 support hierarchical naming. 618 Examples of valid names: 620 "Pete's Calendar" 621 Product_Calendar 622 Project1 623 SpinalTapPerformanceSchedule 624 Projects/Pete/ICAP 625 "Projects/Pete O'Leary/ICAP Specification Schedule" 627 Calendar names can contain a user's name delimited by angle braces 628 "<" and ">". Empty angle braces "<>" are meant to refer to the 629 currently authenticated user. This specification refers to "users" and 630 "user names", although these concepts can apply to things other than 631 human beings. For instance, a "user" with their own Calendar store 632 may actually be a resource such as a conference room which exists 633 outside of the Calendar server itself. 635 The important distinction between user names and store names is that 636 user names very often have meaning outside the implementation of 637 the current server. For instance, a user name may be an SMTP mail 638 address or a Distinguished Name that may be looked up using a 639 directory service like LDAP. An ICAP implementation must not 640 assume anything about the structure of a user name. 642 A user's name by itself, used as a Calendar Store name, must 643 represent the default Calendar Store (see below) for that user. The 644 user's name must also be the root by which other Calendar Stores the 645 user has created can be found (see the LIST command below). A 646 user name must always be at the leftmost position in the hierarchy of 647 a Calendar Store name. It is invalid to have a Calendar name with 648 more than one user name in it. 650 See the description of the SELECT and LIST commands below for 651 more discussion about user names and their use. 653 Valid names with user/resource names: 655 656 /Project_Schedule 657 658 "" 660 O'Leary, Pete 12 662 Internet-Draft 6/16/98 663 draft-oleary-icap-04.doc Expires 6 months from above date 665 Invalid names: 667 Users/ 668 / 669 "Palo Alto/Research Building/" 671 1.12. Default Calendar 673 Every user local to a calendar server should have a "default 674 calendar". This is the Calendar store that is most likely to contain up- 675 to-the-minute information about a person's calendar. The exact 676 definition of this concept is implementation-dependent. The default 677 calendar, which can be selected using only the user's name, can be 678 used by clients to look up free and busy time information for that 679 user. 681 1.13. Access Control 683 ICAP servers should allow for different levels of access control on 684 user's Calendar stores. The exact definition of this access control is 685 implementation dependent. A good default choice would be to allow 686 read-only access to a user's default calendar store via the EXAMINE 687 command to allow for free and busy time searches. 689 The server should give a NO response any time a client requests an 690 operation which is not permitted by access control. 692 For example, a server that allows anonymous read-only browsing of 693 Calendar stores may enforce the following rules: 695 1. The client is only shown user's default Calendars when 696 performing a LIST command. 697 2. The client is only allowed to select Calendar stores via the 698 EXAMINE command. 699 3. The STORE command always returns a NO response and allows 700 no updates of the Calendar store. In this case, the server could 701 return a response to the client indicating where to send a meeting 702 invitation via e-mail to request a meeting with the desired user. 703 4. The FETCH command will return a NO response if the user 704 requests anything more than the flags and summary information 705 of a Calendar Object. This would allow the anonymous user to 706 browse the Calendar of another user in a company which had an 707 "open calendar" policy for all users. 708 5. Optionally, for a higher level of security, the server may return a 709 NO response for an attempted FETCH and allow only the use of 710 the FREEBUSY command. The FREEBUSY command does not 711 return any specific information about the Objects of a user's 712 calendar. 714 1.14. Server States 716 O'Leary, Pete 13 718 Internet-Draft 6/16/98 719 draft-oleary-icap-04.doc Expires 6 months from above date 721 An ICAP server is in one of four states. Most commands are valid in 722 only certain states. It is a protocol error for the client to attempt a 723 command while the command is in an inappropriate state. In this 724 case, a server will respond with a BAD or NO (depending upon 725 server implementation) command completion result. 727 When a command is valid in more than one server state, the 728 description below will list the "Valid States" for that command. 730 1.13.1. Non-Authenticated State 732 In non-authenticated state, the user must supply authentication 733 credentials before most commands will be permitted. This state is 734 entered when a connection starts. 736 1.13.2. Authenticated State 738 In authenticated state, the user is authenticated and most commands 739 will be permitted. This state is entered when acceptable 740 authentication credentials have been provided. 742 1.13.3. Selected State 744 In selected state, the user has chosen a particular calendar store (or 745 calendar stores) and can perform operations on them. 747 1.13.4. Logout State 749 In logout state, the session is being terminated, and the server will 750 close the connection. This state can be entered as a result of a client 751 request or by unilateral server decision. 753 2. Scheduling Operations 755 This section discusses different scheduling operations and how ICAP 756 enables those operations. This section also presents scheduling 757 operations which ICAP does not enable and gives a short discussion 758 of why. 760 2.1 Operations Supported by ICAP 762 For illustration purposes, the following is an incomplete list of the 763 scheduling operations that ICAP is intended to support: 765 2.1.1. Calendar Browsing 767 ICAP supports the ability to open and browse Calendar Stores via the 768 SELECT and FETCH commands. A client may obtain a list of 769 Calendar Stores available using the LIST command. A user can 770 browse a Calendar that belongs the them or to another user, subject 771 to access control restrictions. The SELECT command actually allows 773 O'Leary, Pete 14 775 Internet-Draft 6/16/98 776 draft-oleary-icap-04.doc Expires 6 months from above date 778 multiple users' Calendars to be viewed simultaneously. 780 2.1.2. Freetime Search 782 ICAP supports the ability to obtain free and busy information about a 783 user in two ways: 785 1. The user's default Calendar Store can be browsed as described above. 786 2. The FREEBUSY command can be used to obtain a "snapshot" 787 of users' scehdule during a given period of time. 789 2.1.3. Creating, Deleting and Modifying Calendar Objects 791 A user can create, delete and modify Objects either in their own 792 Calendar Stores or, subject to access control restrictions, in another 793 user's Calendar store. 795 The APPEND command is used to create new Calendar Objects in 796 any accessible Calendar Store. The STORE command is used to 797 modify or mark for deletion Calendar Objects in the currently 798 selected Calendar store. 800 2.1.4. Group Scheduling 802 ICAP supports the so-called "direct-book" mechanism of creating 803 group meetings by allowing a user to actually place a shared 804 Calendar Object into the Calendar Stores of multiple users. This is 805 not the only way that group scheduling can be performed (see below 806 under "Meeting Invitations"). 808 An ICAP implementation may choose not to support direct-book 809 group scheduling by enforcing access control on users' Calendar 810 Stores. 812 2.2. Operations Not Supported By ICAP 814 The following is partially complete list of the scheduling operations 815 that ICAP is NOT intended to support: 817 2.2.1. Meeting Invitations 819 ICAP contains no mechanisms for sending so-called "meeting 820 invitations" to Calendar users. Meeting invitations are one means by 821 which group scheduling can be accomplished. This operations may 822 be accomplished by sending iCalendar objects encapsulated as 823 MIME [RFC 1521] content in an SMTP [RFC 821] mail message, as 824 described in the iTIP documents [ITIP]. 826 ICAP contains no mechanisms for allowing access to meeting 827 invitations that have been received by a user. This should be 828 accomplished via message access protocols like IMAP4 [RFC 1730]. 830 O'Leary, Pete 15 832 Internet-Draft 6/16/98 833 draft-oleary-icap-04.doc Expires 6 months from above date 835 2.2.2. Directory Services 837 ICAP contains no mechanisms for locating a user or obtaining 838 personal information about a user. This operation should be 839 accomplished via LDAP [RFC 1731]. 841 3. ICAP Commands - Any State 843 3.1. CAPABILITY Command 845 Arguments: None. 847 Data: Mandatory untagged response: CAPABILITY 849 Result: OK - Command completed 850 NO - Command failed 851 BAD - Improperly formed command, invalid arguments 853 The CAPABILITY command requests a listing of capabilities that 854 the server supports. The server MUST send a single untagged 855 CAPABILITY response with "ICAP" as one of the listed capabilities 856 before the (tagged) OK response. This listing of capabilities is not 857 dependent upon connection state or user. It 858 is therefore not necessary to issue a CAPABILITY command more 859 than once in a session. 861 A capability name which begins with "AUTH=" indicates that the 862 server supports that particular authentication mechanism. See [RFC 863 1731] for a discussion of authentication mechanisms that can be used 864 with ICAP. All authentication names are, by definition, part of this 865 specification. For example, the authorization capability for an 866 experimental "blurdybloop" authenticator would be "AUTH=X- 867 BLURDYBLOOP" and not "X-AUTH=BLURDYBLOOP" or "X- 868 AUTH=X-BLURDYBLOOP". Other capability names refer to 869 extensions, revisions, or amendments to this specification. See the 870 documentation of the CAPABILITY response additional 871 information. No capabilities are enabled without explicit client 872 action to invoke the capability. See the section entitled "X-(Atom) 873 Experimental Commands" for information about the form of site or 874 implementation-specific capabilities. 876 Examples: 878 C: a001 CAPABILITY 879 S: * CAPABILITY ICAP 880 S: a001 OK CAPABILITY completed 882 C: a001 CAPABILITY 883 S: * CAPABILITY ICAP X-Vegomatic AUTH=X-Secret-Decoder-Rings 884 S: a001 OK CAPABILITY completed 886 O'Leary, Pete 16 888 Internet-Draft 6/16/98 889 draft-oleary-icap-04.doc Expires 6 months from above date 891 C: a001 CAPABILITY 892 S: * CAPABILITY ICAP AUTH=KERBEROS_V4 893 S: a001 OK CAPABILITY completed 895 3.2. NOOP Command 897 Arguments: None 899 Data: Optional untagged responses. 901 Result: OK - Command completed 902 BAD - Improperly formed command, arguments 903 supplied which are not allowed 905 An ICAP server must support this command. The NOOP command 906 always succeeds. It does nothing. 908 Since any command can return a status update as untagged data, the 909 NOOP command can be used as a periodic poll during a period of 910 inactivity. The NOOP command can also be used to reset any 911 inactivity autologout timer on the server. The ICAP server 912 implementation should attempt to ensure that the NOOP commands 913 completes in as little time as possible. 915 Examples: 917 C: A001 NOOP 918 S: A001 OK NOOP Completed. 920 C: A002 NOOP 921 S: * 42 EXISTS 922 S: * 1 RECENT 923 S: A002 OK NOOP Completed. 925 3.4. LOGOUT Command 927 Arguments: None 929 Data: None 931 Result: OK - Command completed. 932 NO - Command failed, this would indicate that 933 something is seriously wrong. 934 BAD - Improperly formed command, arguments 935 supplied which are not allowed 937 An ICAP server must support this command, closing all open 938 selected Calendars and disconnecting. If a NO response is returned 939 by this command, the server should return some human-readable 940 information describing why the Logout cannot occur and what the 941 user can do to correct the situation. The server must send an 943 O'Leary, Pete 17 945 Internet-Draft 6/16/98 946 draft-oleary-icap-04.doc Expires 6 months from above date 948 untagged BYE response before the connection is closed and the 949 command completes. 951 Example: 953 C: A001 LOGOUT 954 S: * BYE ICAP Server logging out. 955 S: A001 OK LOGOUT Completed. 957 3.5. X-(Atom) Experimental Commands 959 Arguments: implementation defined 961 Data: implementation defined 963 Result: OK - command completed 964 NO - failure 965 BAD - command unknown or arguments invalid 967 Any command prefixed with an "X-" is an experimental command. 968 Commands which are not part of this specification MUST use the 969 "X-" prefix. 971 Any added untagged responses issued by an experimental command 972 MUST also be prefixed with an X. Server implementations MUST 973 NOT send any such untagged responses, unless the client requested it 974 by issuing the associated experimental command. 976 Example: 978 C: a441 CAPABILITY 979 S: * CAPABILITY ICAP AUTH=KERBEROS_V4 X-PIG-LATIN 980 S: a441 OK CAPABILITY completed 981 C: A442 X-PIG-LATIN 982 S: * XPIG-LATIN ow-nay eaking-spay ig-pay atin-lay 983 S: A442 OK X-PIG-LATIN ompleted-cay 985 4. ICAP Commands - Non-Authenticated State 987 4.1. AUTHENTICATE Command 989 Arguments: Authentication mechanism name 991 Data: None. 993 Result: OK - Command completed, in Authenticated state 994 NO - Command failed, still in Non-Authenticated state 995 BAD - Improperly formed command, invalid arguments, 996 still Non-Authenticated. 998 The AUTHENTICATE command indicates an authentication 1000 O'Leary, Pete 18 1002 Internet-Draft 6/16/98 1003 draft-oleary-icap-04.doc Expires 6 months from above date 1005 mechanism, such as described in [RFC 1731], to the server. If the 1006 server supports the requested authentication mechanism, it performs 1007 an authentication protocol exchange to authenticate and identify the 1009 client. It MAY also negotiate an OPTIONAL protection mechanism 1010 for subsequent protocol interactions. If the requested authentication 1011 mechanism is not supported, the server SHOULD reject the 1012 AUTHENTICATE command by sending a tagged NO response. 1014 The authentication protocol exchange consists of a series of server 1015 challenges and client answers that are specific to the authentication 1016 mechanism. A server challenge consists of a command continuation 1017 request response with the "+" token followed by a BASE64 encoded 1018 string. The client answer consists of a line consisting of a BASE64 1019 encoded string. If the client wishes to cancel an authentication 1020 exchange, it issues a line with a single "*". If the server receives 1021 such an answer, it MUST reject the AUTHENTICATE command by 1022 sending a tagged BAD response. 1024 A protection mechanism provides integrity and privacy protection to 1025 the protocol session. If a protection mechanism is negotiated, it is 1026 applied to all subsequent data sent over the connection. The 1027 protection mechanism takes effect immediately following the CRLF 1028 that concludes the authentication exchange for the client, and the 1029 CRLF of the tagged OK response for the server. Once the protection 1030 mechanism is in effect, the stream of command and response octets 1031 is processed into buffers of ciphertext. Each buffer is transferred 1032 over the connection as a stream of octets prepended with a four octet 1033 field in network byte order that represents the length of the following 1034 data. The maximum ciphertext buffer length is defined by the 1035 protection mechanism. 1037 Authentication mechanisms are OPTIONAL. Protection 1038 mechanisms are also OPTIONAL; an authentication mechanism 1039 MAY be implemented without any protection mechanism. If an 1040 AUTHENTICATE command fails with a NO response, the client 1041 MAY try another authentication mechanism by issuing another 1042 AUTHENTICATE command, or MAY attempt to authenticate by 1043 using the LOGIN command. In other words, the client MAY request 1044 authentication types in decreasing order of preference, with the 1045 LOGIN command as a last resort. 1047 Example: 1049 S: * OK ICAP KerberosV4 Server 1050 C: A001 AUTHENTICATE KERBEROS_V4 1051 S: + AmFYig== 1052 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25 1053 C: a4DT+nZImJjn TNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd 1054 C: WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh 1055 S: + or//EoAADZI= 1057 O'Leary, Pete 19 1059 Internet-Draft 6/16/98 1060 draft-oleary-icap-04.doc Expires 6 months from above date 1062 C: DiAF5A4gA+oOIALuBkAAmw== 1063 S: A001 OK Kerberos V4 authentication successful 1065 Note: the line breaks in the first client answer are for editorial clarity 1066 and are not in real authenticators. 1068 4.2. LOGIN Command 1070 Arguments: User name for login. 1071 Optional password. 1073 Data: None. 1075 Result: OK - Command completed, in Authenticated state 1076 NO - Command failed, still in Non-Authenticated state 1077 BAD - Improperly formed command, invalid arguments, 1078 still in Non-Authenticated state. 1080 The LOGIN command identifies the client to the server and carries 1081 the plaintext password authenticating this user. 1083 This is accomplished by allowing a LOGIN command specifying a 1084 user name of "Anonymous" and any password. The anonymous user 1085 should be allowed to enter the Authenticated state, with access 1086 control restrictions. It is recommended that anonymous users be 1087 given read-only permission to users' default Calendar stores to allow 1088 free busy time searches. 1090 Example: 1092 C: a001 LOGIN Pete Mumblefrtoz 1093 S: a001 OK LOGIN completed 1095 5. ICAP Commands - Authenticated State 1096 5.1. SELECT Command 1098 Arguments: Name of the Calendar store to select. 1099 Optional date range 1101 Data: Mandatory untagged response: FLAGS, EXISTS 1102 Optional untagged responses: RECENT 1104 Result: OK - now in Selected state 1105 NO - no such Calendar store, can't access Calendar store 1106 BAD - Invalid arguments 1108 Valid states: Authenticated, Selected 1110 The SELECT command selects the Calendar store for the current 1111 user so that Calendar Objects can be queried and retrieved. Multiple 1113 O'Leary, Pete 20 1115 Internet-Draft 6/16/98 1116 draft-oleary-icap-04.doc Expires 6 months from above date 1118 Calendar stores can be selected by reissuing the SELECT command. 1119 In this way, a composite view of the Calendar stores can be created. 1121 This composite calendar can then be used to allow browsing of group 1122 calendars and creating of group meetings (see below). It is invalid to 1123 select the same Calendar store more than once. 1125 The name parameter can be the name of a Calendar and optionally a 1126 user name. If a user name is given, then it is bracketed with angle 1127 braces "<" and ">" and added before the Calendar store name. The 1128 default Calendar store of a user can be selected by using only the 1129 user's name bracketed by angles. The default calendar store of the 1130 current user can be selected by using angles"<>". All commands 1131 which take a Calendar store name as a parameter can accept a user 1132 name in this manner. Which Calendar store is selected as a default is 1133 implementation dependent. It is recommended that the default store 1134 be whichever Calendar store most accurately represents the user's 1135 actual schedule, so that it can be queried to find freetime (see the 1136 FREEBUSY command below). Any Calendar store name given that 1137 does not include an explicit username must be assumed to belong to 1138 the current user. In other words, a prefix of "<>/" can be implicitly 1139 added before any Calendar store name that does not give an explicit 1140 user name. 1142 The user name may be specified as <"username"@"hostname">. If 1143 "hostname" is the name of the current host machine, then 1144 "hostname" may be omitted and the form is: <"username">. If 1145 "hostname" is included, and it is different from the current host 1146 machine name, the server can either reject the name with a NO 1147 response or attempt to connect to the specified host machine on 1148 behalf of the user and issue an OK response if successful. If a NO 1149 response is given by the server because the given user's calendar 1150 information is not located on the host but the server knows where, a 1151 reference name in angle brackets may be included as part of the 1152 response. 1153 The EXISTS response should return the total number of Objects 1154 currently selected. When multiple Calendar stores are selected, this is 1155 the combined total of all Objects selected in all the Calendar stores. 1157 Optionally, a date range may be specified as part of the SELECT 1158 command. When a date range is provided, the SELECT command 1159 MUST limit the selection to entries that fall between the given range. 1160 If a date range is specified the server MUST resolve any recurring 1161 rules in the calendar's entries and present a distinct entry for each 1162 instance of the recurring set. For example, suppose a calendar 1163 contained only one entry which was a recurring event that repeated 1164 every week on Wednesdays. If a SELECT command were given 1165 which specified a date range of 4 weeks, the server MUST return 4 1166 entries as part of the selection. 1168 O'Leary, Pete 21 1170 Internet-Draft 6/16/98 1171 draft-oleary-icap-04.doc Expires 6 months from above date 1173 All Objects in the selected Calendar stores must be presented by the 1174 server in chronological order from 1 to the number of Objects 1175 selected by reissuing the SELECT command and the server cannot 1176 support presenting multiple Calendars in chronological order the 1177 server must issue a NO response for additional Calendars as they are 1178 selected. 1180 Note for readers familiar with IMAP4: The ICAP protocol does not 1181 require any correlation between Object numbers and unique ID's as 1182 IMAP4 does. UID's are not required to be strictly ascending. 1183 Furthermore, UID's in ICAP cannot change between sessions as in 1184 IMAP4 (per the UIDVALIDITY response). 1186 The RECENT response should be given if new Calendar Objects 1187 have appear in the selected Calendar since it was last selected. This 1188 may occur when someone else's Calendar store is selected or 1189 possibly when someone else - an assistant perhaps - modifies the 1190 user's Calendar 1192 The FLAGS response should list the flags supported by this Calendar 1193 store. Note that when multiple Calendar stores are selected, the 1194 FLAGS supported should be the intersection of those supported by 1195 all the Calendars. 1197 Flags current supported are: 1199 \Deleted - Object is marked for deletion. 1200 \Recent - Object has been added since the last time that this Calendar 1201 store was selected. 1202 \Repeating - Object is one of a repeating set of Objects. 1203 \Tentative - The Object is marked as being "tentative" - not yet 1204 confirmed - by the Calendar's owner. 1205 \Seen - The user has already seen this Object. Set by default when 1206 the user creates an Object in their own store. 1208 Example interactions: 1210 C: A001 SELECT 1211 S: * 123 EXISTS 1212 S: * FLAGS (\Deleted \Recent \Repeating) 1213 S: A001 OK SELECT Completed 1214 C: A002 RANGE 19970101T000000 19970130T235959 1216 The sequence above selects the current user's default Calendar store. 1217 It then sends a Selected state command called RANGE (see below). 1219 C: A001 SELECT <>/Section1 1220 S: * 45 EXISTS 1221 S: * FLAGS (\Deleted \Recent \Repeating) 1222 S: A001 OK SELECT completed 1223 C: A002 RANGE 19970101T000000 19970130T235959 1225 O'Leary, Pete 22 1227 Internet-Draft 6/16/98 1228 draft-oleary-icap-04.doc Expires 6 months from above date 1230 The sequence above selects the current user's Calendar store called 1231 "Section1". It then sends a Selected state command called RANGE. 1233 C: A001 SELECT <> 1234 S: * 23 EXISTS 1235 S: * FLAGS (\Deleted \Recent \Repeating) 1236 S: A001 OK SELECT completed 1237 C: A002 SELECT 1238 S: * 56 EXISTSS: * FLAGS (\Deleted \Recent \Repeating) 1239 S: A002 OK SELECT completed 1240 C: A003 SELECT 1241 S: * 123 EXISTS 1242 S: * FLAGS (\Deleted \Recent \Repeating) 1243 S: A003 OK SELECT completed 1245 This sequence uses multiple SELECT commands to open the current 1246 user's default Calendar store plus the default Calendar stores of Bob 1247 and Sally. Note that the EXISTS response from the command 1248 contains the number of Calendar Objects in all of the Calendars 1249 currently selected. 1251 C: A001 SELECT 1252 S: A001 NO SELECT No such user. 1254 C: A001 SELECT 1255 S: * 27 EXISTS 1256 S: * FLAGS (\Deleted \Recent \Repeating) 1257 S: A001 OK SELECT completed. 1259 C: A001 SELECT 1260 S: A001 NO SELECT Try 1262 These sequences demonstrate how a server might handle a SELECT 1263 command where the given user's Calendar store is not on the current 1264 host. In the second example, the server knows the location of the 1265 user's Calendar host and supplies that information to the client. 1267 5.2. EXAMINE Command 1269 Data: None. 1270 Result: OK - Command completed 1271 NO - Command failed 1272 BAD - Improperly formed command, invalid 1273 arguments 1275 Valid states: Authenticated, Selected 1277 This command is identical to SELECT except that the selected 1278 Calendar store is returned read only. EXAMINE and SELECT 1280 O'Leary, Pete 23 1282 Internet-Draft 6/16/98 1283 draft-oleary-icap-04.doc Expires 6 months from above date 1285 command can be given in combination to select multiple calendars 1286 for browsing. The operation is identical in all respects, regardless of 1287 which command is used, except that a Calendar store selected via 1288 EXAMINE cannot be modified or updated in any way. 1290 5.3. CREATE Command 1292 Arguments: Name of Calendar store to create. 1294 Data: None. 1296 Result: OK - Calendar store created. 1297 NO - Calendar store not created. 1298 BAD - Invalid arguments. 1300 Valid states: Authenticated, Selected 1302 Creates a new Calendar store with the given name. Calendar store 1303 names must begin with an alphabetic character and consist of 1304 alphanumeric characters. Calendar names are not case sensitive. It is 1305 illegal to create more than one Calendar store with the same name. 1306 CREATE does not automatically select the Calendar store created. 1308 ICAP servers are NOT required to support hierarchical names. If a 1309 client attempts to create a Calendar Store with a hierarchical name on 1310 a server which does not support hierarchical names, the server 1311 MUST return a response of NO to the CREATE command. 1313 If the Calendar name is suffixed with the hierarchy separator "/", this 1314 is a declaration that the client intends to create Calendar names under 1315 this name in the hierarchy. Server implementations that do not 1316 require this declaration MUST ignore it. 1318 If the hierarchy separator character appears elsewhere in the name, 1319 the server SHOULD create any superior hierarchical names that are 1320 needed for the CREATE command to complete successfully. In other 1321 words, an attempt to create "foo/bar/zap" on a server SHOULD 1322 create foo/ and foo/bar/ if they do not already exist. 1324 Example: 1326 C: A001 CREATE Projects/ 1327 S: A001 OK CREATE Completed 1328 C: A001 CREATE Projects/Purple 1329 S: A001 OK CREATE Completed 1330 C: A001 CREATE Projects/Green 1331 S: A001 OK CREATE Completed 1333 The above example creates two Calendar stores for the default user 1334 below the hierarchical name "Projects". 1336 O'Leary, Pete 24 1338 Internet-Draft 6/16/98 1339 draft-oleary-icap-04.doc Expires 6 months from above date 1341 5.4. DELETE Command 1343 Arguments: Name of Calendar store to delete. 1345 Data: None. 1347 Result: OK - Calendar store deleted. 1348 NO - Calendar store not deleted. 1349 BAD - Invalid arguments. 1351 Valid states: Authenticated, Selected 1353 Deletes the Calendar store with the given name. If this command is 1354 given from the Selected state, a currently selected Calendar cannot 1355 be deleted. 1357 Example: 1359 C: A001 DELETE Projects/Purple 1360 S: A001 OK DELETE Completed. 1362 5.5. RENAME Command 1364 Arguments: Name of Calendar store to rename. 1365 New Calendar store name. 1367 Data: None. 1368 Result: OK - Calendar store renamed 1369 NO - Calendar store not renamed. 1370 BAD - Invalid arguments 1372 Valid states: Authenticated, Selected 1374 The RENAME command changes the name of a Calendar store. A 1375 tagged OK response is returned only if the Calendar has been 1376 renamed. It is an error to attempt to rename from a Calendar name 1377 that does not exist or to a Calendar name that already exists. Any 1378 error in renaming will return a tagged NO response. 1380 If the hierarchy separator character appears in the new Calendar store 1381 name, the server SHOULD create any superior hierarchical names 1382 that are needed for the RENAME command to complete 1383 successfully. In other words, an attempt to rename a Calendar to 1384 "foo/bar/zap" on a server SHOULD create foo/ and foo/bar/ if they 1385 do not already exist. 1387 Example: 1389 C: A001 RENAME Projects/Purple Projects/Orange 1390 S: A001 OK RENAME Completed. 1391 C: A001 RENAME Projects/Green Completed/Green 1392 S: A001 OK RENAME Completed. 1394 O'Leary, Pete 25 1396 Internet-Draft 6/16/98 1397 draft-oleary-icap-04.doc Expires 6 months from above date 1399 5.6. LIST Command 1401 Arguments: Store name with optional wildcard 1403 Data: Untagged responses: LIST 1405 Result: OK - List complete. 1406 NO - List failed, no stores found that match the given 1407 pattern. 1408 BAD - What did that pattern mean anyway? 1410 Valid states: Authenticated, Selected 1412 The LIST command returns an untagged LIST response for each 1413 Calendar store that matches the given reference and store name. The 1414 "*" character is a wildcard and can be used only in the right-most 1415 position in the given store name. The "*" character matches any 1416 length string of valid Calendar Store name characters. 1418 ICAP uses the "/" character to delimit levels of hierarchy: if the 1419 Calendar store name returned by the LIST command ends with a "/" 1420 character, then a level of hierarchy exists below that store name. If 1421 that store name cannot be selected, the LIST response must include 1422 the \Noselect flag, as described below in the LIST response. 1424 The server must hide all Calendar stores that the current user does 1425 not have access to. 1427 These reference names should be interpreted in the following 1428 manner: 1430 * - all top-level Calendar stores accessible to the current user 1431 <*> - all users accessible by the server 1432 <> - the currently authenticated user 1434 Examples: 1436 C: A001 LIST <*> 1437 S: * LIST () 1438 S: * LIST () 1439 S: * LIST () 1440 S: * LIST () 1441 C: A002 LIST /* 1442 S: * LIST () /Project_1 1443 S: * LIST () /Project_2 1444 S: A001 OK LIST Completed. 1446 C: A001 LIST * 1447 S: * LIST () Business 1448 S: * LIST () Private 1450 O'Leary, Pete 26 1452 Internet-Draft 6/16/98 1453 draft-oleary-icap-04.doc Expires 6 months from above date 1455 S: * LIST () CorporateEvents 1456 S: * LIST (\Noselect) Projects/ 1457 S: A001 OK LIST Completed. 1458 C: A002 LIST Projects/* 1459 S: * LIST () Projects/ICAP_Spec 1460 S: * LIST () "Projects/Vacation Plans" 1461 S: A002 OK LIST Completed. 1463 5.7. LSUB Command 1465 Arguments: Store name with optional wildcard 1467 Data: Untagged responses: LIST 1469 Result: OK - List complete. 1470 NO - List failed, no stores found that match the 1471 given pattern. 1472 BAD - What did that pattern mean anyway? 1474 Valid states: Authenticated, Selected 1476 The LSUB command is identical to the LIST command except that it 1477 returns Calendar names from those that the current user has 1478 subscribed to. 1480 5.8. SUBSCRIBE Command 1482 Arguments: Calendar name 1484 Data: None 1486 Result: OK - Subscribe complete. 1487 NO - Subscribe failed, no stores found that match 1488 name. 1489 BAD - Invalid arguments 1491 Valid states: Authenticated, Selected 1493 The SUBSCRIBE command adds the given Calendar store name to 1494 the list of subscribed stores that will be returned by the LSUB 1495 command. 1497 Example: 1499 C: A001 SUBSCRIBE Corporate_Calendar/Barbecues 1500 S: A001 OK SUBSCRIBE Completed. 1502 5.9. UNSUBSCRIBE Command 1504 Arguments: Calendar name 1506 O'Leary, Pete 27 1508 Internet-Draft 6/16/98 1509 draft-oleary-icap-04.doc Expires 6 months from above date 1511 Data: None 1513 Result: OK - Unsubscribe complete. 1514 NO - Unsubscribe failed, no stores found that 1515 match name. 1516 BAD - Invalid arguments 1518 Valid states: Authenticated, Selected 1520 The UNSUBSCRIBE command removes the given Calendar store 1521 name from the list of subscribed stores that will be returned by the 1522 LSUB command. 1524 Example: 1526 C: A001 UNSUBSCRIBE /Barbecues 1527 S: A001 OK UNSUBSCRIBE Completed. 1529 5.10. APPEND Command 1531 Arguments: Calendar store name list or NIL for currently 1532 selected stores 1533 Flags list 1534 Calendar Object literal 1536 Data: None. 1538 Result: OK - Command completed 1539 NO - Command failed, no Objects were added to 1540 any calendar store 1541 BAD - Improperly formed command, invalid 1542 arguments, no Objects added 1544 Valid states: Authenticated, Selected 1546 The APPEND command creates a new Calendar Object in the given 1547 Calendar Stores. If the destination Calendar Store does not exist, the 1548 server must return a NO response. 1550 In the Selected state, a NIL atom may be given for the list of 1551 Calendar store names to operate on. 1553 The server can send an optional untagged response for each user or 1554 calendar that is specified. The NO response can be used to indicate 1555 that the store failed in a certain user's calendar with a response code 1556 of "REFUSED" followed by the name of the calendar refusing. The 1557 server can optionally return a response code of "MAILTO" followed 1558 by the calendar name and a mail address that can accept an invitation 1559 request for the given calendar. The server may return OK responses 1560 for selected Calendars to indicate that the STORE completed 1561 successfully in that Calendar but that some special condition exists. 1563 O'Leary, Pete 28 1565 Internet-Draft 6/16/98 1566 draft-oleary-icap-04.doc Expires 6 months from above date 1568 The server may send a response code of "TENTATIVE" to indicate 1569 that a new Calendar Object was created marked as \Tentative. The 1570 server may send a response code of "SENT" to indicate that a 1571 meeting invitation was sent to the owner of the Calendar store. 1573 The \StoreAll flag should be given when the client is creating a new 1574 Calendar Object and wants to guarantee that the Object will be 1575 created in all of the selected Calendar stores simultaneously. If the 1576 server cannot store to at least one of the selected Calendars, it must 1577 not store to any of them and must return a NO response indicating 1578 that the command failed. The server may still return untagged 1579 responses indicating which Calendar stores failed. 1581 The \NoConflict should be given when the Object being appended to 1582 the Calendar Stores specified cannot have a time conflict with any 1583 Object on any of the Calendar Stores. If a time conflict exists, the 1584 server MUST return a NO response and MUST not modify any of 1585 the specified Calendar stores. 1587 New Calendar Objects added to a Calendar store with the APPEND 1588 command MUST contain all required iCalendar properties. If a 1589 required property is missing the server MUST return a NO response 1590 and MUST not modify any of the specified Calendar stores. 1592 Examples: 1594 C: A001 APPEND Personal_Calendar () {88} 1595 C: BEGIN: VCALENDAR 1596 C: PRODID:-//Amplitude Software//NONSGML EventCenter v1.5//EN 1597 C: VERSION: 2.0 1598 C: BEGIN:VTIMEZONE 1600 C: TZID:America-New_York 1601 C: LAST-MODIFIED:19870101T000000Z 1602 C: TZURL:http://zones.stds_r_us.net/tz/America-New_York 1603 C: BEGIN:STANDARD 1604 C: DTSTART:19671029T020000 1605 C: RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 1606 C: TZOFFSETFROM:-0400 1607 C: TZOFFSETTO:-0500 1608 C: TZNAME:EST 1609 C: END:STANDARD 1610 C: BEGIN:DAYLIGHT 1611 C: DTSTART:19870405T020000 1612 C: RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 1613 C: TZOFFSETFROM:-0500 1614 C: TZOFFSETTO:-0400 1615 C: TZNAME:EDT 1616 C: END:DAYLIGHT 1617 C: END:VTIMEZONE 1618 C: BEGIN: VEVENT 1620 O'Leary, Pete 29 1622 Internet-Draft 6/16/98 1623 draft-oleary-icap-04.doc Expires 6 months from above date 1625 C: DTSTART;TZID=America-New_York: 19980606T140000 1626 C: DTEND;TZID=America-New_York: 19980606T150000 1627 C: SUMMARY: Meeting with Pete 1628 C: END: VEVENT 1629 C: END: VCALENDAR 1630 C: 1631 S: A001 OK APPEND completed 1633 C: A001 APPEND ( ) (\Tentative) {88} 1634 C: BEGIN: VCALENDAR 1635 C: PRODID:-//Amplitude Software//NONSGML Reserve 1.5//EN 1636 C: VERSION: 2.0 1637 C: BEGIN: VEVENT 1638 C: DTSTART: 19980927T163000Z 1639 C: DTEND:19980927T190000Z 1640 C: SUMMARY: Liz's Birthday Party 1641 C: END: VEVENT 1642 C: END: VCALENDAR 1643 C: 1644 S: A001 OK APPEND completed 1646 5.11. ATTRIBUTES Command 1648 Arguments: Calendar store name 1649 Name of attributes to fetch 1651 Data: Untagged FETCH response. 1653 Result: OK - ATTRIBUTES completed 1654 NO - ATTRIBUTES failed, no attributes were 1655 returned 1656 BAD - Improperly formed command, invalid 1657 arguments 1659 Valid states: Authenticated, Selected 1661 The ATTRIBUTES command returns information about the 1662 specified Calendar store. This command is similar in operation to the 1663 FETCH command (see below) except that it acts on Calendar stores 1664 instead of the Objects in them. 1666 The ATTRIBUTES command currently supports fetching the 1667 following attributes: 1669 FLAGS Returns the flags supported by this 1670 Calendar store, as when the store is selected 1671 TYPE Flags which represents this Calendar 1672 store's type. See below. 1673 CSID The unique identifier of this Calendar. 1674 COMPONENTS An iCalendar object, see below 1676 O'Leary, Pete 30 1678 Internet-Draft 6/16/98 1679 draft-oleary-icap-04.doc Expires 6 months from above date 1681 TIMEZONE An iCalendar object containing a 1682 TIMEZONE Component, see below. 1684 The TYPE flags currently supported are: 1686 \Default This container is a user's default Calendar store 1687 \Resource This container is actually owned by a resource. 1689 The COMPONENTS attribute can be used by a client to determine 1690 which Calendar Components that can be stored within a Calendar 1692 Store, along with the names and types of the properties of those 1693 Calendar Components. The server MUST return an iCalendar object 1694 which contains a "model" of all the Components the Calendar Store 1695 supports. The "model" Components MUST contain all of the 1696 properties that the Component can store. The Properties should 1697 specify a VALUE property parameter that identifies the data-type of 1698 the property. The property value MUST be an null string. 1700 The server does not have to return a TIMEZONE Component to 1701 indicate that this Component is supported. The server MUST return 1702 an ALARM Component if this Component is supported. 1703 The TIMEZONE attribute can be used by the client to determine 1704 time zone information about a specific Calendar Store. The server 1705 can return an Object containing zero or more TIMEZONE 1706 Components. If no TIMEZONE Components are returned, then 1707 every object fetched from the Calendar Store MUST contain at least 1708 one TIMEZONE Component. If one or more TIMEZONE 1709 Components are returned, then those Components apply to every 1710 Object fetched from the Calendar Store. The client MUST NOT 1711 expect to be able to store an Object that contains a TIMEZONE 1712 Component other than those returned by this attribute. 1714 Examples: 1716 C: A001 ATTRIBUTES (FLAGS TYPE CSID) 1717 S: * FETCH (FLAGS (\Deleted \Seen \Recent) TYPE \Default CSID 1718 1234123412341234) 1719 S: A001 OK ATTRIBUTES Completed. 1721 In the above example, the client queries the server for the flags 1722 supported by the specified Calendar Store, the Calendar Store type 1723 and its UID. 1725 C: A001 ATTRIBUTES COMPONENTS 1726 S: * FETCH COMPONENTS {200} 1727 S: BEGIN: VCALENDAR 1728 S: PRODID:-//Amplitude Software//NONSGML EventCenter v1.5//EN 1729 S: VERSION: 2.0 1730 S: BEGIN: VEVENT 1731 S: ATTACH; VALUE=URL: 1732 S: DESCRIPTION; VALUE=TEXT: 1734 O'Leary, Pete 31 1736 Internet-Draft 6/16/98 1737 draft-oleary-icap-04.doc Expires 6 months from above date 1739 S: DTSTART; VALUE=DATE-TIME: 1740 S: DTEND; VALUE=DATE-TIME: 1741 S: STATUS: 1742 S: SUMMARY; VALUE=TEXT: 1743 S: UID: 1744 S: X-BILLING_CODE, VALUE=INTEGER: 1745 S: X-CLIENT_NAME; VALUE=TEXT: 1746 S: END: VEVENT 1747 S: END: VCALENDAR 1748 S: A001 OK ATTRIBUTES Completed. 1750 In the above example, the client queries the server for the type of 1751 Components supported by the Calendar Store. The server returns an 1752 Object which specifies that only Event Components can be stored in 1753 the Calendar Store. The Event Components can store the required 1754 Event Component properties, plus the standard properties ATTACH, 1755 SUMMARY, STATUS and UID. Also, the non-standard properties 1756 X-BILLING_CODE and X-CLIENT_NAME can be stored. This 1757 appears to be a lawyer's calendar... 1759 5.12. FREEBUSY Command 1761 Arguments: Calendar store name list or NIL for currently 1762 selected stores 1763 Start of search range in ISO8601 format 1764 End of search range in ISO8601 format 1766 Data: Mandatory untagged response: FETCH 1768 Result: OK - Command completed 1769 NO - Command failed, no freetime found 1770 BAD - Improperly formed command, invalid 1771 Arguments 1773 Valid states: Authenticated, Selected 1775 The FREEBUSY command searches the currently selected Calendars, bounded by a 1776 start and end time, and returns a list of 1777 intervals during which an event of the given length of time can be 1778 scheduled. See below under "Example Sessions" for and example of 1779 the use of the FREEBUSY command. 1781 As is the case in the RANGE command, the start time given is 1782 included in the search range of the FREEBUSY command and the 1783 end time is excluded. 1785 In the Selected state, a NIL atom may be given for the list of 1786 Calendar store names to operate on. 1788 The freetime data is returned in an untagged FETCH response in 1789 iCalendar FREEBUSY format. The FETCH attribute CSNAME must 1791 O'Leary, Pete 32 1793 Internet-Draft 6/16/98 1794 draft-oleary-icap-04.doc Expires 6 months from above date 1796 be returned along with the FETCH response if more than one 1797 Calendar Store name was specified. An ATTENDEE property within 1798 the FREEBUSY object return may also contain the name of the 1799 person corresponding to the FREEBUSY FETCH result. If every 1800 FREEBUSY component within the FETCH responses returned by 1801 the command contains an ATTENDEE property, then CSNAME is 1802 not required. The DTSTART and DTEND properties of the 1803 FREEBUSY object MUST match the start and end dates specified. 1805 Example: 1807 C: A001 FREEBUSY ( ) 1998930T0900Z 1998930T1700Z 1808 S: * 1 FETCH (CSNAME ICAL {88} 1809 S: BEGIN: VCALENDAR 1810 S: PRODID:-//Amplitude Software//NONSGML EventCenter v1.5//EN 1811 S: VERSION: 2.0 1812 S: BEGIN: VFREEBUSY 1813 S: ATTENDEE: Ann 1814 S: DTSTART: 1998930T0900 1815 S: DTEND: 1998930T1700 1816 S: FREEBUSY; VALUE=PERIOD-START: 1998930T1000/PT1H, 1998930T1200/PT1H 1817 S: END: VFREEBUSY 1818 S: END: VCALENDAR 1819 S: ) 1820 S: A001 OK FREEBUSY 1822 In the example above, only two busy periods were found for the 1823 given time range: Ann is busy from 10 to 11 on 19970903 and also 1824 busy from 12 to 1 o'clock on the same day. 1826 6. ICAP Commands - Selected State 1828 6.1. CLOSE Command 1830 Arguments: Optional name of user and or Calendar store. 1832 Data: Optional untagged EXISTS response. 1834 Result: OK - Command completed successfully 1835 NO - Calendar name or user is not selected. 1836 BAD - Invalid argument, calendar name is invalid 1838 The CLOSE closes the currently selected Calendar store or one of 1839 the Calendar stores currently selected. When no parameter is 1840 supplied, all currently selected Calendars are closed. When a 1841 parameter is supplied, it should be of the same form for Calendar 1842 names given in the SELECT command. If the user has not previously 1843 issued a SELECT command with the exact name given in the 1844 CLOSE command, a NO response is returned. 1846 O'Leary, Pete 33 1848 Internet-Draft 6/16/98 1849 draft-oleary-icap-04.doc Expires 6 months from above date 1851 Examples: 1853 C: A001 CLOSE 1854 S: A001 OK CLOSE Completed. 1856 C: A001 CLOSE 1857 S: * 11 EXISTS 1858 S: A001 CLOSE Completed. 1860 6.2. RANGE Command 1862 Arguments: Start date/time in ISO8601 format. 1863 End date/time in ISO8601 format. 1865 Data: Mandatory untagged responses: EXISTS 1867 Result: OK - Command completed successfully, date range 1868 has been set 1869 NO - An error occurred while setting the date 1870 range 1871 BAD - Bad date format 1873 The RANGE command sets a date/time range for the currently 1874 selected Calendars and returns a EXISTS response with the number 1875 of items in the range. 1877 Either the start time or end time can be replaced with the wildcard 1878 character "*" in which case lower or upper bound, respectively, is 1879 placed on the current date range. 1881 The start time given must be included in the range. The end time 1882 given must be excluded from the range. 1884 If any Object in the selected Calendar store contains a set of 1885 recurrence rules that resolve to dates within the specified date range, 1886 then that Object MUST appear once for each date resolved within the 1887 specified range. In other words, an Object may count for more than 1888 one Object in the EXISTS response returned by the RANGE 1889 command if it is a recurring Object. 1891 Example: 1893 C: A001 RANGE 19971230T0900 19971230T1700 1894 S: * 9 EXISTS 1895 S: A001 OK RANGE 1897 The above example selects all Calendar Objects from 0900 to 1700 1898 on 1997 December 30 in the slected calendar's local time zone. 1900 C: A001 RANGE 19970730Z 19970731Z 1901 S: * 12 EXISTS 1902 S: A001 OK RANGE 1904 O'Leary, Pete 34 1906 Internet-Draft 6/16/98 1907 draft-oleary-icap-04.doc Expires 6 months from above date 1909 The above example selects all Calendar Objects on 1997 July 30, GMT. 1911 C: A001 RANGE 19970101 19980101 1912 S: * 56 EXISTS 1913 S: A001 OK RANGE 1915 The above example selects all Calendar Objects in 1997 in the 1916 selected calendar's local time. 1918 6.3. CHECK Command 1920 Arguments: None 1922 Data: None. 1924 Result: OK - Command completed 1925 NO - Command failed 1926 BAD - Improperly formed command, invalid 1927 arguments 1929 An ICAP server given the CHECK command should perform any 1930 housekeeping operations that ensure the integrity of the currently 1931 selected Calendar stores. It is expected that the CHECK command 1932 may take some time to complete. 1934 Example: 1936 C: A001 CHECK 1937 S: A001 OK CHECK 1939 6.4. EXPUNGE Command 1941 Arguments: None 1943 Data: Mandatory untagged response: EXPUNGE 1945 Result: OK - Command completed 1946 NO - Command failed, no items were removed 1947 BAD - Improperly formed command, no items 1948 were removed 1950 The EXPUNGE command permanently removes from the currently 1951 selected Calendar stores all Objects that have the \Deleted flag set. 1952 Before returning an OK to the client, an untagged EXPUNGE 1953 response is sent for each Object that is removed. 1955 Example: 1957 C: A001 EXPUNGE 1958 S: * 3 EXPUNGE 1959 S: * 3 EXPUNGE 1961 O'Leary, Pete 35 1963 Internet-Draft 6/16/98 1964 draft-oleary-icap-04.doc Expires 6 months from above date 1966 S: * 5 EXPUNGE 1967 S: * 8 EXPUNGE 1968 S: A001 OK EXPUNGE completed 1970 Note: in this example, Objects 3, 4, 7, and 11 had the \Deleted flag 1971 set. See the description of the EXPUNGE response for further 1972 explanation. 1974 6.5. FETCH Command 1976 Arguments: Set of calendar Objects to fetch. 1977 Item names. 1979 Data: Untagged responses: FETCH 1981 Result: OK - fetch completed 1982 NO - fetch error, no items were fetched 1983 BAD - command unknown or invalid arguments 1985 The FETCH command retrieves information about the specified 1986 Objects. Objects can addressed for retrieval in 3 different ways: 1988 Index number - A number from 1 to the number of Objects in the current 1989 selection as returned in the last EXISTS response from the server. 1991 Multiple index - numbers MAY be specified enclosed in parenthesis. 1993 Unique ID - The unique ID of the Object may be specified as described 1994 in the UID command below. 1996 Search criteria - A set of search criteria, as defined in the SEARCH 1997 command below. The search criteria MUST be enclosed in curly 1998 braces: "{" and "}". 2000 The information to be fetched is specified using the following item 2001 names: 2003 FLAGS The flags associated with this calendar 2004 Object 2005 ICAL iCalendar object format. All properties 2006 MUST be returned. 2007 ICAL.SIZE The size of the iCalendar iCalendar, in 2008 octets. 2009 ICAL.REQUIRED Only required iCalendar attribute 2010 information in iCalendar format. 2011 ICAL.BRIEF Only DTSTART, DTEND and 2012 SUMMARY attributes in iCalendar format. 2013 ICAL.propertyName A specific iCalendar property. 2014 UID The unique ID of the calendar Object (the 2015 COID). 2017 O'Leary, Pete 36 2019 Internet-Draft 6/16/98 2020 draft-oleary-icap-04.doc Expires 6 months from above date 2022 CSID The unique ID of the Calendar Store that 2023 contains the fetched Object. 2024 CSNAME The name of the Calendar Store that 2025 contains the fetched Object. 2027 The FLAGS item returns any flags that are currently set for the given 2028 calendar Object. 2030 The ICAL item returns the full iCalendar Object specified, including 2031 any time zone and access control information. Additionally, if any 2032 non-standard properties are associated with the Object (preceded 2033 with X-) these properties MUST be returned as well. 2035 The ICAL.SIZE item returns the size of the iCalendar object in 2036 octets. 2038 The ICAL.REQUIRED item returns only the iCalendar properties 2039 defined as required in [ICAL] for the corresponding component 2040 type. Optional and non-standard properties MUST not be returned. 2042 The ICAL.BRIEF item returns only the DTSTART, DTEND and 2043 SUMMARY properties for the specified Objects. 2045 The ICAL.propertyName item returns only the specified property for 2046 each Object requested. For example, "ICAL.DTSTART" will return 2047 only the DTSTART property. 2049 If more than one ICAL item is specified, the server should return 2050 only ONE Object per FETCH response. The server MUST return the 2051 union of the ICAL items specified. 2053 The UID item returns the unique identifier of the calendar Object. 2055 The CSID item returns the unique calendar store identifier of the 2056 Calendar which contains the specified Object. The client can use this 2057 value to distinguish Objects when multiple Calendar Stores are 2058 selected. 2060 The CSNAME item returns the name of the Calendar which contains 2061 the specified Object. The client can use this value to distinguish 2062 Objects when multiple Calendar Stores are selected. 2064 Multiple items MAY be specified by surrounding them in 2065 parenthesis. All information requested by the client is returned via a 2066 FETCH response from the server. See the description of the FETCH 2067 response below. 2069 Note that items returned by FETCH should always be returned in 2070 ascending chronological order, even when multiple Calendar stores 2071 are selected. 2073 O'Leary, Pete 37 2075 Internet-Draft 6/16/98 2076 draft-oleary-icap-04.doc Expires 6 months from above date 2078 Example: 2080 C: A001 FETCH 1 FLAGS 2081 S: * 1 FETCH FLAGS (\Deleted \Seen) 2082 S: A001 OK FETCH 2084 C: A001 FETCH 1 (FLAGS ICAL.REQUIRED) 2085 S: * 1 FETCH (FLAGS (\Deleted \Seen) ICAL.REQUIRED {96} 2086 S: BEGIN: VCALENDAR 2087 S: PRODID:-//Amplitude Software//NONSGML EventCenter v1.5//EN 2088 S: VERSION: 2.0 2089 S: BEGIN: VEVENT 2090 S: DTBEGIN: 1998701T0300Z 2091 S: DTEND: 1998701T0400Z 2092 S: SUMMARY: Test meeting 2093 S: END: VEVENT 2094 S: END: VCALENDAR 2095 S: ) 2096 S: A001 OK FETCH 2098 C: A001 FETCH 1:4 UID 2099 S: * 1 FETCH UID 1234123412341234 2100 S: * 2 FETCH UID 5678567856785678 2101 S: * 3 FETCH UID 2345234523452345 2102 S: * 4 FETCH UID abcdabcdabcdabcd 2103 S: A001 OK FETCH 2105 6.6. STORE Command 2107 Arguments: Calendar Object set 2108 Calendar Object data item name 2109 Calendar Object data item value 2111 Data: None. 2113 Result: OK - Command completed 2114 NO - Command failed, no Objects were added to 2115 any calendar store 2116 BAD - Improperly formed command, invalid 2117 arguments, no Objects added 2119 Calendar data items: 2121 +FLAGS 2123 Set the flag list of the given Calendar Objects. In the STORE 2124 command, one additional flag can be given: \StoreAll. See below for 2125 the use of this flag. 2127 O'Leary, Pete 38 2129 Internet-Draft 6/16/98 2130 draft-oleary-icap-04.doc Expires 6 months from above date 2132 -FLAGS 2134 Remove the flag argument from the flags of the given Calendar 2135 Objects. 2137 ICAL 2139 Updates the iCalendar data associated with this Calendar Object. 2140 When this form of the STORE command is used, the Calendar data 2141 item must be supplied as a literal. The data must be a iCalendar 2142 object. 2144 If a value of "0" is given for the Calendar Object set, then a new 2145 Object is created. This functionality is similar to performing an 2146 APPEND command except that it allows the client to check the 2147 availability of the Calendar stores before attempting to create new 2148 Objects. If there is more than one Calendar store selected in the 2149 given Selected object, then the STORE command will add the new 2150 Object to all of the Calendar stores. This will cause the EXISTS 2151 count for the current selection to increase by 1 for each currently 2152 selected Calendar store. 2154 The server can send an optional untagged response for each user or 2155 calendar that is currently selected. The NO response can be used to 2156 indicate that the store failed in a certain user's calendar with a 2157 response code of "REFUSED" followed by the name of the calendar 2158 refusing. The server can optionally return a response code of 2159 "MAILTO" followed by the calendar name and a mail address that 2160 can accept an invitation request for the given calendar. See the 2161 example below. The server may return OK responses for selected 2162 Calendars to indicate that the STORE completed successfully in that 2163 Calendar but that some special condition exists. The server may send 2164 a response code of "TENTATIVE" to indicate that a new Calendar 2165 Object was created marked as \Tentative. The server may send a 2166 response code of "SENT" to indicate that a meeting invitation was 2167 sent to the owner of the Calendar store. In the case of a 2168 "TENTATIVE" response from the server, the EXISTS count for the 2169 selected Calendars MUST be increased. When a SENT response is 2170 given, the EXISTS count MUST NOT be increased. 2172 The \NoConflict should be given when the Object being appended to 2173 the Calendar Stores selected cannot have a time conflict with any 2174 Object on any of the Calendar Stores. If a time conflict exists, the 2175 server MUST return a NO response and MUST not modify any of 2176 the selected Calendar stores. 2178 The \StoreAll flag should be given when the client is creating a new 2179 Calendar Object and wants to guarantee that the Object will be 2180 created in all of the selected Calendar stores simultaneously. If the 2181 server cannot store to at least one of the selected Calendars, it must 2182 not store to any of them and must return a NO response indicating 2184 O'Leary, Pete 39 2186 Internet-Draft 6/16/98 2187 draft-oleary-icap-04.doc Expires 6 months from above date 2189 that the command failed. The server may still return untagged 2190 responses indicating which Calendar stores failed. 2192 New Calendar Objects added to a Calendar store must contain all 2193 required iCalendar properties. Updates to existing Calendar Objects 2194 need only contain the actual data to be updated. Duplicate attributes 2195 names are not allowed, whenever a value is given for a attribute 2196 name that already exists, the new value replaces the old value. If the 2197 new value is a null string (""), {0} or a CRLF immediately following 2198 the ":") then the old attribute is deleted. 2200 In this first example, the users is creating a new Object in their own 2201 calendar. The operation succeeds: 2203 C: A001 STORE 0 (+FLAGS \Repeating ICAL {102} 2204 C: BEGIN: VCALENDAR 2205 C: PRODID:-//Amplitude Software//NONSGML EventCenter v1.5//EN 2206 C: VERSION: 2.0 2207 C: BEGIN:VTIMEZONE 2208 C: TZID:America-California 2209 C: LAST-MODIFIED:19870101T000000Z 2210 C: TZURL:http://zones.stds_r_us.net/tz/America-New_York 2211 C: BEGIN:STANDARD 2212 C: DTSTART:19671029T020000 2213 C: RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 2214 C: TZOFFSETFROM:-0700 2215 C: TZOFFSETTO:-0800 2216 C: TZNAME:EST 2217 C: END:STANDARD 2218 C: BEGIN:DAYLIGHT 2219 C: DTSTART:19870405T020000 2220 C: RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 2221 C: TZOFFSETFROM:-0800 2222 C: TZOFFSETTO:-0700 2223 C: TZNAME:EDT 2224 C: END:DAYLIGHT 2225 C: END:VTIMEZONE 2226 C: BEGIN: VEVENT 2227 C: DTSTART;TZID=US-California: 19980606T140000 2228 C: DTEND;TZID=US-California: 19980606T150000 2229 C: SUMMARY: Meeting with Pete 2230 C: END: VEVENT 2231 C: END: VCALENDAR 2232 C: ) 2233 S: A001 OK STORE completed 2235 In the following example, the user has two default Calendar stores 2236 selected, one for , one for and one for . 2237 The client attempts to schedule a meeting in all Calendars by using 2238 the STORE command. refuses, requests a meeting 2239 invitation be sent and accepts. Note that the terms "accept" 2241 O'Leary, Pete 40 2243 Internet-Draft 6/16/98 2244 draft-oleary-icap-04.doc Expires 6 months from above date 2246 and "refuse" to not imply an intervention on the part of a real person: 2247 whether the server accepts or refuses a STORE request should be 2248 based on access control. 2250 C: A001 STORE 0 ICAL {102} 2251 C: BEGIN: VCALENDAR 2252 C: PRODID:-//Amplitude Software//NONSGML EventCenter v1.5//EN 2253 C: VERSION: 2.0 2254 C: BEGIN: VEVENT 2255 C: DTSTART: 19980606T140000 2256 C: DTEND: 19980606T150000 2257 C: SUMMARY: Meeting with Pete. 2258 C: END: VEVENT 2259 C: END: VCALENDAR 2260 C: 2261 S: * NO [REFUSED ] Alice doesn't like you. 2262 S: * NO [MAILTO ] Please send me a meeting 2263 S: invitation. 2264 S: A001 OK STORE completed 2266 The following sequence modifies Calendar Object number 23 with a 2267 new start and end date/time. 2269 C: A001 STORE 23 ICAL {102} 2270 C: BEGIN: VCALENDAR 2271 C: PRODID:-//Amplitude Software//NONSGML EventCenter v1.5//EN 2272 C: VERSION: 2.0 2273 C: BEGIN: VEVENT 2274 C: DTSTART: 19980806T140000Z 2275 C: DTEND: 19980806T150000Z 2276 C: END: VEVENT 2277 C: END: VCALENDAR 2278 C: 2279 S: A001 OK STORE completed 2280 6.7. COPY Command 2282 6.8. MOVE Command 2284 Arguments: Calendar Object set 2285 Name of Calendar to move or copy to 2287 Data: None. 2289 Result: OK - Calendar Objects moved. 2290 NO - Calendar Objects not moved. 2291 BAD - Bad date format given. 2293 COPY and MOVE transfer a given set of Objects to a different 2294 Calendar store. In the case of the MOVE command, the Objects are 2295 removed from the current Calendar. MOVE must fail if the user does 2296 not have permission to remove an Object from the selected Calendar. 2298 O'Leary, Pete 41 2300 Internet-Draft 6/16/98 2301 draft-oleary-icap-04.doc Expires 6 months from above date 2303 The Calendar store to move or copy to MUST exist before the 2304 operation is initiated. 2306 Example: 2308 C: A001 COPY 1 Section1 2309 S: A001 OK COPY Completed. 2311 6.9. UID Command 2313 Arguments: Command 2315 Data: Untagged responses: FETCH, SEARCH. 2317 Result: OK - UID command completed. 2318 NO - UID command failed. 2319 BAD - Invalid command or UID given. 2321 In its first form the UID command takes a COPY, MOVE, FETCH 2322 or STORE command as its arguments. These commands are 2323 processed as usual, except that unique ID's must be given instead of 2324 Object numbers. 2326 In the second form, the UID command takes a SEARCH command 2327 with SEARCH command arguments. The interpretation of the 2328 arguments is the same as with SEARCH; however, the numbers 2329 returned in a SEARCH response for a UID SEARCH command are 2330 unique identifiers instead of sequence numbers. 2332 The number after the "*" in an untagged FETCH response is always 2333 a sequence number, not a unique identifier, even for a UID command 2334 response. However, server implementations MUST implicitly 2335 include the UID data item as part of any FETCH response caused by 2336 a UID command, regardless of whether UID was specified as a data 2337 item to the FETCH. 2339 Example: 2341 C: A001 UID FETCH 1234123412341234 (FLAGS ICAL.REQUIRED) 2342 S: * 12 FETCH (UID 1234123412341234 FLAGS (\Deleted \Seen) 2343 S: ICAL.REQUIRED {96} 2344 S: BEGIN: VCALENDAR 2345 S: PRODID:-//Amplitude Software//NONSGML EventCenter v1.5//EN 2346 S: VERSION: 2.0 2347 S: BEGIN: VEVENT 2348 S: DTBEGIN: 19980701T0300Z 2349 S: DTEND: 19980701T0400Z 2350 S: SUMMARY: Test meeting 2351 S: END: VEVENT 2352 S: END: VCALENDAR 2353 S: ) 2355 O'Leary, Pete 42 2357 Internet-Draft 6/16/98 2358 draft-oleary-icap-04.doc Expires 6 months from above date 2360 S: A001 OK UID FETCH 2362 6.10. SEARCH Command 2364 Arguments: One or more search criteria 2366 Data: Untagged responses: SEARCH. 2368 Result: OK - search completed. 2369 NO - search error: can't search that criteria. 2370 BAD - command unknown or invalid arguments. 2372 The SEARCH command searches the Calendar store for Objects that 2373 match the given searching criteria. Searching criteria consist of one 2374 or more search keys. The untagged SEARCH response from the 2375 server contains a listing of Object numbers corresponding to those 2376 Objects that match the searching criteria. 2378 When multiple keys are specified, the result is the intersection (AND 2379 function) of all the messages that match those keys. A search key can 2380 also be a parenthesized list of one or more search keys (e.g. for use 2381 with the OR and NO keys). 2383 Objects with sequence numbers corresponding to the 2384 specified message sequence number set 2386 ALL 2387 All Objects in the mailbox; the default initial key for ANDing. 2389 COMPONENT 2390 Objects which contain at least one of the specified Components. 2391 Valid Components are: VEVENT, VTODO, VJOURNAL, 2392 VALARM. Note that Objects which have a VALARM Component 2393 embedded anywhere within them MUST match this key. 2395 DELETED 2396 Objects with the \Deleted flag set. 2398 NEW 2399 Objects that have the \Recent flag set but not the \Seen flag. This is 2400 functionally equivalent to "(RECENT UNSEEN)". 2402 NOT 2403 Objects that do not match the specified search key. 2405 OR 2406 Objects that match either search key. 2408 RECENT 2409 Objects that have the \Recent flag set. 2411 O'Leary, Pete 43 2413 Internet-Draft 6/16/98 2414 draft-oleary-icap-04.doc Expires 6 months from above date 2416 SEEN 2417 Objects that have the \Seen flag set. 2419 TENTATIVE 2420 Objects that have the \Tentative flag set. 2422 UID 2423 Objects with unique identifiers corresponding to the specified unique 2424 identifier set. 2426 UNDELETED 2427 Objects that do not have the \Deleted flag set. 2429 UNSEEN 2430 Objects that do not have the \Seen flag set. 2432 ICAL < property value> 2433 Objects where the specified comparison operation is true. 2435 The valid comparison operators are: 2437 "=" Equals. True if the given property matches the 2438 given property value. String values are assumed to be case 2439 insensitive. Valid for all property types. 2441 "contains" Valid only for type TEXT, RFC822-ADDRESS 2442 and URL. True if the given value is a substring of the given property. 2443 String values are assumed to be case insensitive. 2445 ">" Greater than. True if the given property is greater 2446 than the given property value. Valid only for the property types 2447 DATE, TIME, DATE-TIME, PERIOD, DURATION, INTEGER, 2448 FLOAT and UTC-OFFSET. 2450 "<" Less than. True if the given property is less than 2451 the given property value. Valid only for the property types DATE, 2452 TIME, DATE-TIME, PERIOD, DURATION, INTEGER, FLOAT 2453 and UTC-OFFSET. 2455 The comparison value is assumed to have the same type as the 2456 specified Object property. The Object property type can be queried 2457 using the ATTRIBUTES command. If the property value specified in 2458 the comparison operation cannot be readily converted to the Object 2459 property type, the comparison operation is false. 2461 Comparisons of DATE and DATE-TIME values are valid only under 2462 the following conditions. If the currently selected Calendar Store 2463 contains Object having different Time Zone information, as 2464 described in the section titled "Calendar Stores" above, then all 2465 comparison values for DATE and DATE-TIME types MUST be 2466 either UTC values or be convertible to UTC. Only Calendar Stores 2468 O'Leary, Pete 44 2470 Internet-Draft 6/16/98 2471 draft-oleary-icap-04.doc Expires 6 months from above date 2473 whose objects fall within the same Time Zone information may 2474 perform comparisons based on local time values. 2476 DATE-TIME values which contain only a date component (e.g. 2477 19970106Z) MUST match any DATE-TIME which falls on the 2478 given date when used with the "=" operator. 2480 If multiple properties with the same property name exist within the 2481 same Object, the comparison operator is true if ANY of the 2482 properties meet the specified criteria. If multiple properties with 2483 different property types exist within an object, the result of the 2484 SEARCH operation is undefined. 2486 If a COMPONENT key is specified, a property name given in an 2487 ICAL search request is assumed to refer to a field within any 2488 specified COMPONENT. 2490 Examples: 2492 C: A001 SEARCH 1:20 ICAL DUE = 19981001 2493 S: * SEARCH 4 9 12 19 2494 S: A001 OK SEARCH Completed. 2496 C: A001 SEARCH UNSEEN ICAL PRIORITY > 3 2497 S: * SEARCH 3 12 45 2498 S: A001 OK SEARCH Competed. 2500 C: A001 SEARCH ICAL PRIORITY > 3 ICAL DUE < 19981112Z 2501 S: * SEARCH 3 45 2502 S: A001 OK SEARCH Competed. 2504 C: A001 SEARCH COMPONENT VALARM ICAL DTSTART = 2505 19980808Z 2506 S: * SEARCH 14 18 19 2507 S: A001 OK SEARCH Competed. 2509 The above SEARCH operation finds all of the Objects which contain 2510 an alarm set to go off on August 8th of 1998 in the Pacific Time 2511 Zone. 2513 7. Server Responses 2515 Server responses are in three forms: status responses, server data, and 2516 command continuation request. 2518 The client MUST be prepared to accept any response at all times. 2520 Status responses that are tagged indicate the completion result of a 2521 client command, and have a tag matching the command. 2523 Some status responses, and all server data, are untagged. An 2525 O'Leary, Pete 46 2527 Internet-Draft 6/16/98 2528 draft-oleary-icap-04.doc Expires 6 months from above date 2530 untagged response is indicated by the token "*" instead of a tag. 2531 Untagged status responses indicate server greeting, or server status 2532 that does not indicate the completion of a command. For historical 2533 reasons, untagged server data responses are also called "unsolicited 2534 data", although strictly speaking only unilateral server data is truly 2535 "unsolicited". 2537 Certain server data MUST be recorded by the client when it is 2538 received; this is noted in the description of that data. Such data 2539 conveys critical information which affects the interpretation of all 2540 subsequent commands and responses (e.g. updates reflecting the 2541 creation or destruction of Calendar Objects). 2543 Other server data SHOULD be recorded for later reference; if the 2544 client does not need to record the data, or if recording the data has no 2545 obvious purpose (e.g. a SEARCH response when no SEARCH 2546 command is in progress), the data SHOULD be ignored. 2548 Command continuation request responses use the token "+" instead 2549 of a tag. These responses are sent by the server to indicate 2550 acceptance of an incomplete client command and readiness for the 2551 remainder of the command. 2553 7.1. Server Responses - Status Responses 2555 Status responses MAY include an OPTIONAL response code. A 2556 response code consists of data inside square brackets in the form of 2557 an atom, possibly followed by a space and arguments. The response 2558 code contains additional information or status codes for client 2559 software beyond the OK/NO/BAD condition, and are defined when 2560 there is a specific action that a client can take based upon the 2561 additional information. 2563 The currently defined response codes are: 2565 ALERT - The human-readable text contains a special alert that 2566 MUST be presented to the user in a fashion that calls the user's 2567 attention to the message. 2569 PERMANENTFLAGS - Followed by a parenthesized list of flags, 2570 indicates which of the known flags that the client can change 2571 permanently. Any flags that are in the FLAGS untagged response, 2572 but not the PERMANENTFLAGS list, can not be set permanently. 2573 If the client attempts to STORE a flag that is not in the 2574 PERMANENTFLAGS list, the server will either reject it with a NO 2575 reply or store the state for the remainder of the current session only. 2577 MAILTO - Returned from a STORE or APPEND command to 2578 indicate that an specific user requests Meeting Invitations to be sent 2579 to them via SMTP mail. Returned with NO response only. 2581 O'Leary, Pete 47 2583 Internet-Draft 6/16/98 2584 draft-oleary-icap-04.doc Expires 6 months from above date 2586 READ-ONLY - The Calendar is selected read-only, or its access 2587 while selected has changed from read-write to read-only. 2589 READ-WRITE - The Calendar is selected read-write, or its access 2590 while selected has changed from read-only to read-write. 2592 REFUSED - Returned from a STORE or APPEND command to 2593 indicate that an specific user does not allow scheduling requests from 2594 other users. Returned with NO response only. 2596 SENT - Returned from a STORE or APPEND command to indicate 2597 that a meeting invitation was sent by the server via e-mail rather than 2598 creating an Object in a user's Calendar. 2600 TENTATIVE - Returned from a STORE or APPEND command to 2601 indicate that a Calendar Object marked as \Tentative was created in 2602 the specified users Calendar. 2604 Additional response codes defined by particular client or server 2605 implementations SHOULD be prefixed with an "X-" until they are 2606 added to a revision of this protocol. Client implementations 2607 SHOULD ignore response codes that they do not recognize. 2609 7.1.1. OK Response 2610 7.1.2. NO Response 2611 7.1.3. BAD Response 2613 Data: Optional response code 2614 Optional human-readable text. 2616 The OK, NO and BAD responses are intended to give the client 2617 information about a command's completion status or information 2618 about the operation of the server. When given in a tagged response, 2619 these responses indicates completion of the command with the 2620 associated tag. Untagged responses of this kind are always 2621 informational messages. In both cases, a message based on the 2622 response code and text MAY be presented to the user. 2624 The untagged form is also used as one of three possible greetings 2625 (along with PREAUTH and BYE) at session startup. It indicates that 2626 the session is not yet authenticated and that a LOGIN command is 2627 needed. 2629 Examples of the OK, NO and BAD response can be found within 2630 many of the examples given above. 2632 7.1.4. PREAUTH Response 2634 Data: Optional response code 2635 Human-readable text. 2637 O'Leary, Pete 47 2639 Internet-Draft 6/16/98 2640 draft-oleary-icap-04.doc Expires 6 months from above date 2642 The PREAUTH response is always untagged, and is one of three 2643 possible greetings (along with OK and BYE) at session startup. It 2644 indicates that the session has already been authenticated by external 2645 means and thus no LOGIN command is needed. 2647 Example: 2649 S: * PREAUTH ICAP server logged in as Smith 2651 7.1.5. BYE Response 2653 Data: Optional response code 2655 Human-readable text. 2657 The BYE response is always untagged, and indicates that the server 2658 is about to close the connection. The human-readable text MAY be 2659 displayed to the user in a status report by the client. The BYE 2660 response is sent under one of four conditions: 2662 1) as part of a normal logout sequence. The server will close the 2663 connection after sending the tagged OK response to the LOGOUT 2664 command. 2666 2) as a panic shutdown announcement. The server closes the 2667 connection immediately. 2669 3) as an announcement of an inactivity autologout. The server closes 2670 the connection immediately. 2672 4) as one of three possible greetings at session startup (along with 2673 OK and PREAUTH), indicating that the server is not willing to 2674 accept a session from this client. The server closes the connection 2675 immediately. 2677 The difference between a BYE that occurs as part of a normal 2678 LOGOUT sequence (the first case) and a BYE that occurs because of 2679 a failure (the other three cases) is that the connection closes 2680 immediately in the failure case. 2682 Example: 2684 S: * BYE Autologout; idle for too long 2686 7.2. Server Responses - Data Responses 2688 These responses are always untagged. This is how server data are 2689 transmitted from the server to the client, often as a result of a 2690 command with the same name. 2692 O'Leary, Pete 48 2694 Internet-Draft 6/16/98 2695 draft-oleary-icap-04.doc Expires 6 months from above date 2697 7.2.1. CAPABILITY Response 2699 Data: capability listing 2701 The CAPABILITY response occurs as a result of a CAPABILITY 2702 command. The capability listing contains a space-separated listing 2703 of capability names that the server supports. The capability listing 2704 MUST include the atom "ICAP". 2706 A capability name which begins with "AUTH=" indicates that the 2707 server supports that particular authentication mechanism. 2709 Other capability names indicate that the server supports an extension, 2710 revision, or amendment to the ICAP protocol. Server responses 2711 MUST conform to this document until the client issues a command 2712 that uses the associated capability. 2714 Capabilities not defined in this document MUST be prefixed with 2715 "X-". 2717 Client implementations SHOULD NOT require any capability name 2718 other than "ICAP", and MUST ignore any unknown capability 2719 names. 2721 Example: 2723 S: * CAPABILITY ICAP AUTH=KERBEROS_V4 X-PocketToaster 2725 7.2.2. LIST Response 2727 Data: Name attributes list 2728 Calendar name or hierarchical name, possible prefixed by 2729 an owner name 2731 The LIST response is given in response to a LIST command. 2733 Four name attributes are defined: 2735 \Noinferiors It is not possible for any child levels of hierarchy to 2736 exist under this name; no child levels 2737 exist now and none can be created in the future. 2739 \Noselect It is not possible to use this name as a selectable 2740 Calendar. 2742 \Marked The Calendar has been marked "interesting" by the 2743 server; the Calendar probably contains Objects that have been added 2744 since the last time the Calendar was selected. 2746 \Unmarked The Calendar does not contain any additional Objects 2747 since the last time the Calendar was selected. 2749 O'Leary, Pete 49 2751 Internet-Draft 6/16/98 2752 draft-oleary-icap-04.doc Expires 6 months from above date 2754 If it is not feasible for the server to determine whether the Calendar 2755 is "interesting" or not, or if the name is a \Noselect name, the server 2756 SHOULD NOT send either \Marked or \Unmarked. 2758 The hierarchy delimiter "/" is used to delimit levels of hierarchy in a 2759 Calendar name. A client can use it to create child Calendars, and to 2760 search higher or lower levels of naming hierarchy. 2762 The name represents an unambiguous left-to-right hierarchy, and 2763 MUST be valid for use as a reference in LIST and LSUB commands. 2764 Unless \Noselect is indicated, the name MUST also be valid as an 2765 argument for commands, such as SELECT, that accept Calendar names. 2767 Example: 2769 S: * LIST () Section1 2770 S: * LIST () 2771 S: * LIST () 2772 S: * LIST (\Noselect) Projects/ 2773 S: * LIST () Projects/Project_Purple 2774 S: * LIST () "Project 1/From Bill" 2776 7.2.3. LSUB Response 2778 The LSUB command is identical to the LIST command except that it 2779 is given in response to the LSUB command. 2781 Example: 2783 S: * LSUB () Section1 2784 S: * LSUB() Projects/Project_Purple 2785 S: * LSUB() "Project 1/From Bill" 2787 7.2.4. EXISTS Response 2789 Data: None. 2791 The EXISTS response reports the number of Objects in the Calendar. 2792 This response occurs as a result of a SELECT, EXAMINE or 2793 RANGE command, and if the size of the Calendar changes (e.g. new 2794 Calendar Objects). 2796 The update from the EXISTS response MUST be recorded by the 2797 client. 2799 Example: 2801 S: * 23 EXISTS 2803 O'Leary, Pete 50 2805 Internet-Draft 6/16/98 2806 draft-oleary-icap-04.doc Expires 6 months from above date 2808 7.2.5. RECENT Response 2810 Data: None. 2812 The RECENT response reports the number of Calendar Objects that 2813 have been posted since the previous time a SELECT command was 2814 done on this Calendar. This response occurs as a result of a SELECT 2815 or EXAMINE command, and if the size of the Calendar changes 2816 (e.g. new Calendar Objects). 2818 The update from the RECENT response MUST be recorded by the 2819 client. 2821 Example: 2823 S: * 1 RECENT 2825 7.2.6. EXPUNGE Response 2827 Data: None. 2829 The EXPUNGE response reports that the specified Calendar Object 2830 sequence number has been permanently removed from the Calendar. 2831 The sequence number for each successive Object in the Calendar is 2832 immediately decremented by 1, and this decrement is reflected in 2833 sequence numbers in subsequent responses (including other untagged 2834 EXPUNGE responses). 2836 As a result of the immediate decrement rule, sequence numbers that 2837 appear in a set of successive EXPUNGE responses depend upon 2838 whether the Objects are removed starting from lower numbers to 2839 higher numbers, or from higher numbers to lower numbers. For 2840 example, if the last 5 Objects in a 9-Object Calendar are expunged; a 2841 "lower to higher" server will send five untagged EXPUNGE 2842 responses for sequence number 5, whereas a "higher to lower server" 2843 will send successive untagged EXPUNGE responses for sequence 2844 numbers 9, 8, 7, 6, and 5. 2846 An EXPUNGE response MUST NOT be sent when no command is 2847 in progress; nor while responding to a FETCH, STORE, or SEARCH 2848 command. This rule is necessary to prevent a loss of synchronization 2849 of sequence numbers between client and server. 2851 The update from the EXPUNGE response MUST be recorded by the 2852 client. 2854 Example: 2856 S: * 1 EXPUNGE 2858 O'Leary, Pete 51 2860 Internet-Draft 6/16/98 2861 draft-oleary-icap-04.doc Expires 6 months from above date 2863 7.2.7. FETCH Response 2865 Data: Calendar Object data. 2867 The FETCH response returns data about a Calendar Object to the 2868 client. The data are pairs of data item names and their values in 2869 parentheses. This response occurs as the result of a FETCH, 2870 STORE, ATTRIBUTES and FREEBUSY commands, as well as by 2871 unilateral server decision (e.g. flag updates). See the description of 2872 the commands for a list of data items. 2874 S: * 1 FETCH ICAL.REQUIRED {96} 2875 S: BEGIN: VCALENDAR 2876 S: PRODID:-//Amplitude Software//NONSGML EventCenter v1.5//EN 2877 S: VERSION: 2.0 2878 S: BEGIN: VEVENT 2879 S: DTBEGIN: 19980701T0300Z 2880 S: DTEND: 19980701T0400Z 2881 S: SUMMARY: Test meeting 2882 S: END: VEVENT 2883 S: END: VCALENDAR 2884 S: ) 2886 7.2.8. FLAGS Response 2888 Data: Calendar Object flags. 2890 The FLAGS response occurs as a result of a SELECT or EXAMINE 2891 command. The flag parenthesized list identifies the flags (at a 2892 minimum, the system-defined flags) that are applicable for this 2893 Calendar. Flags other than the system flags can also exist, depending 2894 on server implementation. 2896 The update from the FLAGS response MUST be recorded by the 2897 client. 2899 Example: 2901 S: * 1 FLAGS (\Deleted) 2902 7.2.9. SEARCH Response 2904 Data: zero or more numbers 2906 The SEARCH response occurs as a result of a SEARCH or UID 2907 SEARCH command. The number(s) refer to those Objects that 2908 match the search criteria. For SEARCH, these are sequence 2909 numbers; for UID SEARCH, these are unique identifiers. Each 2910 number is delimited by a space. 2912 O'Leary, Pete 52 2914 Internet-Draft 6/16/98 2915 draft-oleary-icap-04.doc Expires 6 months from above date 2917 Example: 2919 S: * SEARCH 2 3 6 2921 7.3. Server Responses - Command Continuation Request 2923 The command completion request response is indicated by a "+" 2924 token instead of a tag. This form of response indicates that the server 2925 is ready to accept the continuation of a command from the client. 2926 The remainder of this response is a line of text. 2928 This response is used in the AUTHORIZATION command to 2929 transmit server data to the client, and request additional client data. 2930 This response is also used if an argument to any command is a literal. 2932 The client is not permitted to send the octets of the literal unless the 2933 server indicates that it expects it. This permits the server to process 2934 commands and reject errors on a line-by-line basis. The remainder 2935 of the command, including the CRLF that terminates a command, 2936 follows the octets of the literal. If there are any additional command 2937 arguments the literal octets are followed by a space and those 2938 arguments. 2940 Example: 2942 C: A001 LOGIN {11} 2943 S: + Ready for additional command text 2944 C: FRED FOOBAR {7} 2945 S: + Ready for additional command text 2946 C: fat man 2947 S: A001 OK LOGIN completed 2949 8. Formal Syntax 2951 This will be included in a later draft of this specification. 2953 9. Example Sessions 2955 Here is an example of a client using guest access to query the 2956 freetime of three individuals: 2958 S: * OK ICAP Server ready. 2959 C: A001 LOGIN anonymous pete@amplitude.com 2960 S: A001 OK LOGIN Anonymous access granted. 2961 C: A002 EXAMINE 2962 S: * 12 EXISTS 2963 S: A002 OK EXAMINE 2964 C: A003 EXAMINE 2965 S: * 22 EXISTS 2966 S: A003 OK EXAMINE 2967 C: A004 EXAMINE 2969 O'Leary, Pete 53 2971 Internet-Draft 6/16/98 2972 draft-oleary-icap-04.doc Expires 6 months from above date 2974 S: * 36 EXISTS 2975 S: A004 OK EXAMINE 2976 C: A005 FREEBUSY "" 19980701T0300Z 19980701T1900Z 2977 S: * 1 FETCH ICAL {200} 2978 S: BEGIN: VCALENDAR 2979 S: PRODID:-//hacksw/handcal//NONSGML v1.6//EN 2980 S: VERSION: 2.0 2981 S: BEGIN: VFREEBUSY 2982 S: ATTENDEE: Liz 2983 S: DTBEGIN: 19980701T0300Z 2984 S: DTEND: 19980701T1900Z 2985 C: FREEBUSY; VALUE=PERIOD-START: 19980701T0800Z/PT3H, 2986 C: 19980701T1500Z/PT2H 2987 S: END: VFREEBUSY 2988 S: BEGIN: VFREEBUSY 2989 S: ATTENDEE: Bob 2990 S: DTBEGIN: 19980701T0300Z 2991 S: DTEND: 19980701T1900Z 2992 C: FREEBUSY; VALUE=PERIOD-START: 19980701T1000Z/PT1H, 2993 C: 19980701T1500Z/PT1H 2994 S: END: VFREEBUSY 2995 S: BEGIN: VFREEBUSY 2996 S: ATTENDEE: Purna 2997 S: DTBEGIN: 19980701T0300Z 2998 S: DTEND: 19980701T1900Z 2999 C: FREEBUSY; VALUE=PERIOD-START: 19980701T0900/PT2H 3000 S: END: VFREEBUSY 3001 S: END: VCALENDAR 3002 S: A005 OK FREEBUSY 3003 C: A006 LOGOUT 3004 S: * BYE ICAP Server terminating connection. 3005 S: A006 OK LOGOUT 3007 10. Open Issues/Work in Progress 3009 How should a user's Calendar server be located? For example, given 3010 a mail address like how should a client 3011 locate the Calendar server. This is still not clearly defined. 3013 11. Changes From Previous Draft Version 3015 1. The section on the Dates data type has been updated to reflect 3016 changes to the iCalendar definition [ICAL] to better support 3017 timezone information. 3018 2. A section to explain the use of periods of time has been added. 3019 3. An optional date range has been added to the SELECT comand. 3021 O'Leary, Pete 54 3023 Internet-Draft 6/16/98 3024 draft-oleary-icap-04.doc Expires 6 months from above date 3026 4. Examples that included iCalendar objects have been updated to 3027 reflect changes to the iCalendar definition [ICAL] with reguard 3028 to timeszones, dates, the summary field (previously the 3029 description field) and the now mandatory product id field. 3030 5. The RANGE command no longer supports wildcard characters. 3031 6. The FETCH command has been modified and additional 3032 description has been added. 3034 12. References 3036 [RFC 1730] Crispin, M. "INTERNET MESSAGE ACCESS 3037 PROTOCOL - VERSION 4", Dec 1994, 3039 [ICAL] Dawson, F., Stenerson, D.,"Internet Calendaring and 3040 Scheduling Core Object Specification (iCalendar)", 05/11/1998, 3041 http://www.imc.org/draft-ietf-calsch-ical-main 3043 [RFC 1521] Borenstein, N., and Freed, N., "MIME (Multipurpose 3044 Internet Mail Extensions) Part One: Mechanisms for Specifying 3045 and Describing the Format of Internet Message Bodies," 3046 Bellcore, Innosoft, September 1993. 3048 [RFC 821] Postel, Jonathan B. "Simple Mail Transfer Protocol," 3049 STD 10, USC/Information Sciences Institute, August 1982. 3051 [RFC 1731] Myers, J., "IMAP4 Authentication Mechanism," 3052 Carnegie-Mellon University, December 1994. 3054 [ISO-TIME] Kuhn, M., "A Summary of the International Standard 3055 Date and Time Notation", 3056 http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html 3058 [ITIP] Silverberg, S., Mansour, S., Dawson, F., Hopson, R.," 3059 iCalendar Transport-Independent Interoperability Protocol", 3060 http://www.imc.org/draft-ietf-calsch-itip-part1, 3061 http://www.imc.org/draft-ietf-calsch-itip-part2, 3062 http://www.imc.org/draft-ietf-calsch-itip-part3 3064 13. Security Considerations 3066 The user name and password arguments of the LOGIN command are 3067 sent in clear text over most transport protocols. Consult [RFC 1731] 3068 for a discussion of authentication mechanisms used by IMAP4 and 3069 by ICAP. 3071 Servers should implement and enforce access control mechanisms 3072 for Calendar stores. This specification contains no provisions for 3073 defining and maintaining access control. 3075 O'Leary, Pete 55 3077 Internet-Draft 6/16/98 3078 draft-oleary-icap-04.doc Expires 6 months from above date 3080 14. Author's Notes 3082 This spec is based in very large part on the operation, commands and 3083 concepts of IMAP4 [RFC 1730]. In the spirit of "not reinventing the 3084 wheel" I have incorporated parts of the IMAP4 specification into this 3085 work. My thanks to the authors of the IMAP4 specification for their 3086 excellent work. 3088 Author's Address: 3090 Peter O'Leary 3091 Amplitude Software Corp 3092 185 Berry Street 3093 San Francisco, CA 94107 3094 http://www.amplitude.com/ 3095 (415) 659-3500 3096 E-mail: mailto:pete@amplitude.com 3098 O'Leary, Pete 56