draft-ietf-calsch-cap-05.txt   draft-ietf-calsch-cap-06.txt 
Network Working Group S. Mansour Network Working Group S. Mansour
Internet-Draft Netscape, iPlanet Internet-Draft AOL/Netscape
Expires: January 18, 2002 D. Royer Expires: May 21, 2002 D. Royer
INET-Consulting LLC
G. Babics G. Babics
Steltor Steltor
P. Hill P. Hill
Massachusetts Institute of Massachusetts Institute of
Technology Technology
July 20, 2001 November 20, 2001
Calendar Access Protocol (CAP) Calendar Access Protocol (CAP)
draft-ietf-calsch-cap-05 draft-ietf-calsch-cap-06
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
skipping to change at page 1, line 38 skipping to change at page 1, line 38
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on January 18, 2002. This Internet-Draft will expire on May 21, 2002.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved. Copyright (C) The Internet Society (2001). All Rights Reserved.
Abstract Abstract
The Calendar Access Protocol (CAP) is an Internet protocol that The Calendar Access Protocol (CAP) is an Internet protocol that
permits a Calendar User (CU) to utilize a Calendar User Agent (CUA) permits a Calendar User (CU) to utilize a Calendar User Agent (CUA)
to access an [iCAL] based Calendar Store (CS). This memo defines the to access an [iCAL] based Calendar Store (CS). This memo defines the
skipping to change at page 2, line 16 skipping to change at page 2, line 16
Internet Engineering Task Force (IETF) Calendaring and Scheduling Internet Engineering Task Force (IETF) Calendaring and Scheduling
(CALSCH) Working Group. More information about the IETF CALSCH (CALSCH) Working Group. More information about the IETF CALSCH
Working Group activities can be found on the IMC web site at Working Group activities can be found on the IMC web site at
http://www.imc.org/ietf-calendarand at the IETF web site at http://www.imc.org/ietf-calendarand at the IETF web site at
http://www.ietf.org/html.charters/calsch-charter.html[1]. Refer to http://www.ietf.org/html.charters/calsch-charter.html[1]. Refer to
the references within this memo for further information on how to the references within this memo for further information on how to
access these various documents. access these various documents.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . 5
1.1 Formatting Conventions . . . . . . . . . . . . . . . . 5 1.1 Formatting Conventions . . . . . . . . . . . . . . . . . 5
1.2 Related Documents . . . . . . . . . . . . . . . . . . 6 1.2 Related Documents . . . . . . . . . . . . . . . . . . . 6
1.3 Definitions . . . . . . . . . . . . . . . . . . . . . 6 1.3 Definitions . . . . . . . . . . . . . . . . . . . . . . 6
2. CAP Design . . . . . . . . . . . . . . . . . . . . . . 13 2. CAP Design . . . . . . . . . . . . . . . . . . . . . . . 12
2.1 System Model . . . . . . . . . . . . . . . . . . . . . 13 2.1 System Model . . . . . . . . . . . . . . . . . . . . . . 12
2.1.1 Firewalls and Fanout . . . . . . . . . . . . . . . . . 14 2.2 Calendar Store Object Model . . . . . . . . . . . . . . 12
2.2 Calendar Store Object Model . . . . . . . . . . . . . 15 2.3 Protocol Model . . . . . . . . . . . . . . . . . . . . . 13
2.3 Protocol Model . . . . . . . . . . . . . . . . . . . . 16 2.4 Security Model . . . . . . . . . . . . . . . . . . . . . 14
2.4 Security Model . . . . . . . . . . . . . . . . . . . . 17 2.4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . . 14
2.4.1 Authentication, Credentials, and Identity . . . . . . 18 2.4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . . 14
2.4.2 Calendar User and UPNs . . . . . . . . . . . . . . . . 19 2.4.1.2 Anonymous Users and Authentication . . . . . . . . . . . 16
2.4.2.1 UPNs and Certificates . . . . . . . . . . . . . . . . 19 2.4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . . 16
2.4.2.2 Anonymous Users and Authentication . . . . . . . . . . 20 2.4.2 Access Rights - Summary . . . . . . . . . . . . . . . . 16
2.4.2.3 Required Security Mechanisms . . . . . . . . . . . . . 21 2.4.2.1 Calendar Access Right (VCAR) . . . . . . . . . . . . . . 17
2.4.2.4 TLS Ciphersuites . . . . . . . . . . . . . . . . . . . 21 2.4.2.2 Decreed VCARs . . . . . . . . . . . . . . . . . . . . . 17
2.4.3 User Groups . . . . . . . . . . . . . . . . . . . . . 22 2.4.3 Inheritance . . . . . . . . . . . . . . . . . . . . . . 18
2.4.4 Access Rights - Summary . . . . . . . . . . . . . . . 23 2.4.4 CAP Session Identity . . . . . . . . . . . . . . . . . . 18
2.4.4.1 VCalendar Access Right (VCAR) . . . . . . . . . . . . 24 2.5 Roles . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.4.4.2 Decreed VCARs . . . . . . . . . . . . . . . . . . . . 24 2.6 Calendar Addresses . . . . . . . . . . . . . . . . . . . 19
2.4.5 Inheritance . . . . . . . . . . . . . . . . . . . . . 25 2.7 Extensions to iCalendar . . . . . . . . . . . . . . . . 20
2.4.6 CAP Session Identity . . . . . . . . . . . . . . . . . 25 2.8 Relationship of RFC 2446 (ITIP) to CAP . . . . . . . . . 20
2.5 Roles . . . . . . . . . . . . . . . . . . . . . . . . 26 3. Protocol Framework . . . . . . . . . . . . . . . . . . . 22
2.6 Calendar Addresses . . . . . . . . . . . . . . . . . . 26 3.1 BEEP Exchange Styles . . . . . . . . . . . . . . . . . . 22
2.7 Extensions to iCalendar . . . . . . . . . . . . . . . 27 3.2 Use of XML, MIME and iCalendar . . . . . . . . . . . . . 22
2.8 Relationship of RFC 2446 (ITIP) to CAP . . . . . . . . 28 3.3 Bounded Latency . . . . . . . . . . . . . . . . . . . . 23
3. State Diagram . . . . . . . . . . . . . . . . . . . . 30 4. Formal Command Syntax . . . . . . . . . . . . . . . . . 26
4. Protocol Framework . . . . . . . . . . . . . . . . . . 32 4.1 Searching and Filtering . . . . . . . . . . . . . . . . 26
4.1 CAP Application Layer . . . . . . . . . . . . . . . . 32 4.1.1 Grammar For Search Mechanism . . . . . . . . . . . . . . 26
4.2 CAP Transfer Protocol . . . . . . . . . . . . . . . . 32 4.1.2 SQL-MIN notes . . . . . . . . . . . . . . . . . . . . . 27
4.3 Pipelining Commands . . . . . . . . . . . . . . . . . 33 4.1.3 Querying Experminental Properties . . . . . . . . . . . 28
4.4 Auto-logout Timer . . . . . . . . . . . . . . . . . . 33 4.1.4 Example, Query by UID . . . . . . . . . . . . . . . . . 28
4.5 Bounded Latency . . . . . . . . . . . . . . . . . . . 33 4.1.5 Query by Date-Time range . . . . . . . . . . . . . . . . 29
4.6 Data Elements . . . . . . . . . . . . . . . . . . . . 34 4.1.6 Query for all Non-Booked Entries . . . . . . . . . . . . 29
5. Formal Command Syntax . . . . . . . . . . . . . . . . 35 4.1.7 Query with Subset of Properties by Date/Time . . . . . . 29
5.1 Searching and Filtering . . . . . . . . . . . . . . . 35 4.1.8 Components With Alarms In A Range . . . . . . . . . . . 30
5.1.1 Grammar For Search Mechanism . . . . . . . . . . . . . 35 5. Access Rights . . . . . . . . . . . . . . . . . . . . . 31
5.1.2 SQL-MIN notes . . . . . . . . . . . . . . . . . . . . 36 5.1 VCAR Inheritance . . . . . . . . . . . . . . . . . . . . 31
5.1.3 SQL-92 notes . . . . . . . . . . . . . . . . . . . . . 37 5.2 Access Control and NOCONFLICT . . . . . . . . . . . . . 31
5.1.4 Example, Query by UID . . . . . . . . . . . . . . . . 37 6. Commands and Responses . . . . . . . . . . . . . . . . . 32
5.1.5 Query by Date-Time range . . . . . . . . . . . . . . . 38 6.1 Session Commands . . . . . . . . . . . . . . . . . . . . 32
5.1.6 Query for all Non-Booked Entries . . . . . . . . . . . 38 6.1.1 "generate-uid" Command . . . . . . . . . . . . . . . . . 32
5.1.7 Query with Subset of Properties by Date/Time . . . . . 38 6.1.2 "get-capability" Command . . . . . . . . . . . . . . . . 33
5.1.8 Components With Alarms In A Range . . . . . . . . . . 39 6.1.3 "identify" Command . . . . . . . . . . . . . . . . . . . 35
6. Access Rights . . . . . . . . . . . . . . . . . . . . 40 6.1.4 "noop" Command . . . . . . . . . . . . . . . . . . . . . 35
6.1 VCAR Inheritance . . . . . . . . . . . . . . . . . . . 40 6.2 Calendaring and Scheduling Commands . . . . . . . . . . 36
6.2 Access Control and NOCONFLICT . . . . . . . . . . . . 40 6.2.1 Restriction Tables . . . . . . . . . . . . . . . . . . . 36
7. Commands and Responses . . . . . . . . . . . . . . . . 41 6.2.2 Common Attributes . . . . . . . . . . . . . . . . . . . 37
7.1 Transfer Protocol Commands . . . . . . . . . . . . . . 41 6.2.2.1 "id" Attribute . . . . . . . . . . . . . . . . . . . . . 37
7.1.1 Initial Connection . . . . . . . . . . . . . . . . . . 41 6.2.3 Common Elements . . . . . . . . . . . . . . . . . . . . 37
7.1.2 ABORT Command . . . . . . . . . . . . . . . . . . . . 42 6.2.3.1 "data" Element . . . . . . . . . . . . . . . . . . . . . 37
7.1.3 AUTHENTICATE Command . . . . . . . . . . . . . . . . . 42 6.2.3.2 "select" Element . . . . . . . . . . . . . . . . . . . . 37
7.1.3.1 AUTHENTICATE ANONYMOUS . . . . . . . . . . . . . . . . 45 6.2.3.3 "source" Element . . . . . . . . . . . . . . . . . . . . 39
7.1.4 CALIDEXPAND Command . . . . . . . . . . . . . . . . . 46 6.2.3.4 "target" Element . . . . . . . . . . . . . . . . . . . . 39
7.1.5 CAPABILITY Command . . . . . . . . . . . . . . . . . . 48 6.2.4 Calendaring Commands . . . . . . . . . . . . . . . . . . 40
7.1.6 CONTINUE Command . . . . . . . . . . . . . . . . . . . 50 6.2.4.1 "create" Command . . . . . . . . . . . . . . . . . . . . 40
7.1.7 DISCONNECT Command . . . . . . . . . . . . . . . . . . 51 6.2.4.2 "delete" Command . . . . . . . . . . . . . . . . . . . . 50
7.1.8 IDENTIFY Command . . . . . . . . . . . . . . . . . . . 52 6.2.4.3 "modify" Command . . . . . . . . . . . . . . . . . . . . 53
7.1.9 SENDDATA Command . . . . . . . . . . . . . . . . . . . 52 6.2.4.4 "move" Command . . . . . . . . . . . . . . . . . . . . . 59
7.1.10 STARTTLS Command . . . . . . . . . . . . . . . . . . . 53 6.2.4.5 "search" Command . . . . . . . . . . . . . . . . . . . . 62
7.1.11 UPNEXPAND Method . . . . . . . . . . . . . . . . . . . 53 6.3 Scheduling Commands . . . . . . . . . . . . . . . . . . 72
7.1.12 NOOP Command . . . . . . . . . . . . . . . . . . . . . 55 6.3.1 "schedule" Command . . . . . . . . . . . . . . . . . . . 72
7.2 Application Protocol Commands . . . . . . . . . . . . 55 6.3.2 Processing Scheduling Components . . . . . . . . . . . . 74
7.2.1 Calendaring Commands . . . . . . . . . . . . . . . . . 55 6.3.3 iTIP Examples . . . . . . . . . . . . . . . . . . . . . 76
7.2.1.1 Restriction Tables . . . . . . . . . . . . . . . . . . 56 6.3.3.1 Sending and Receiving an iTIP request . . . . . . . . . 76
7.2.1.2 CREATE Method . . . . . . . . . . . . . . . . . . . . 56 6.3.3.2 Handling an iTIP refresh . . . . . . . . . . . . . . . . 81
7.2.1.2.1 Creating New Calendars . . . . . . . . . . . . . . . . 64 6.3.3.3 Sending and accepting an iTIP counter . . . . . . . . . 83
7.2.1.2.2 Creating a new VQUERY . . . . . . . . . . . . . . . . 66 6.3.3.4 Declining an iTIP counter . . . . . . . . . . . . . . . 86
7.2.1.3 DELETE Method . . . . . . . . . . . . . . . . . . . . 67 7. Response Codes . . . . . . . . . . . . . . . . . . . . . 89
7.2.1.4 GENERATEUID Method . . . . . . . . . . . . . . . . . . 71 8. BEEP Profile Registration . . . . . . . . . . . . . . . 91
7.2.1.5 MODIFY Method . . . . . . . . . . . . . . . . . . . . 71 9. CAP DTD . . . . . . . . . . . . . . . . . . . . . . . . 92
7.2.1.6 MOVE Method . . . . . . . . . . . . . . . . . . . . . 80 10. Implementation Issues . . . . . . . . . . . . . . . . . 95
7.2.1.7 READ Method . . . . . . . . . . . . . . . . . . . . . 83 11. Properties . . . . . . . . . . . . . . . . . . . . . . . 96
7.2.1.7.1 Query With A Stored Query . . . . . . . . . . . . . . 90 11.1 Calendar Store Properties . . . . . . . . . . . . . . . 96
7.2.2 Scheduling Commands . . . . . . . . . . . . . . . . . 91 11.2 Calendar Properties . . . . . . . . . . . . . . . . . . 97
7.2.2.1 Reading Scheduling Components . . . . . . . . . . . . 92 12. CAP Item Registration . . . . . . . . . . . . . . . . . 100
7.2.2.2 PUBLISH . . . . . . . . . . . . . . . . . . . . . . . 93 12.1 Registration of New and Modified CAP Entities . . . . . 100
7.2.2.3 REQUEST . . . . . . . . . . . . . . . . . . . . . . . 94 12.2 Registration of New Entities . . . . . . . . . . . . . . 100
7.2.2.4 REPLY . . . . . . . . . . . . . . . . . . . . . . . . 94 12.2.1 Define the Item . . . . . . . . . . . . . . . . . . . . 100
7.2.2.5 ADD . . . . . . . . . . . . . . . . . . . . . . . . . 95 12.2.2 Post the item definition . . . . . . . . . . . . . . . . 101
7.2.2.6 CANCEL . . . . . . . . . . . . . . . . . . . . . . . . 95 12.2.3 Allow a comment period . . . . . . . . . . . . . . . . . 101
7.2.2.7 REFRESH . . . . . . . . . . . . . . . . . . . . . . . 95 12.2.4 Submit the proposal for approval . . . . . . . . . . . . 101
7.2.2.8 COUNTER . . . . . . . . . . . . . . . . . . . . . . . 96 12.3 Property Change Control . . . . . . . . . . . . . . . . 102
7.2.2.9 DECLINECOUNTER . . . . . . . . . . . . . . . . . . . . 96 13. IANA Considerations . . . . . . . . . . . . . . . . . . 103
7.2.3 iTIP Examples . . . . . . . . . . . . . . . . . . . . 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . 103
7.2.3.1 Sending and Receiving an iTIP request . . . . . . . . 96 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . 105
7.2.3.2 Handling an iTIP refresh . . . . . . . . . . . . . . . 99 B. Bibliography . . . . . . . . . . . . . . . . . . . . . . 106
7.2.3.3 Sending and accepting an iTIP counter . . . . . . . . 100 Full Copyright Statement . . . . . . . . . . . . . . . . 108
7.2.3.4 Declining an iTIP counter . . . . . . . . . . . . . . 102
8. Response Codes . . . . . . . . . . . . . . . . . . . . 104
8.1 Examples . . . . . . . . . . . . . . . . . . . . . . . 106
8.1.1 Authentication Examples . . . . . . . . . . . . . . . 106
8.1.1.1 Login Using Kerberos V4 . . . . . . . . . . . . . . . 106
8.1.1.2 Error Scenarios . . . . . . . . . . . . . . . . . . . 106
8.2 Read Examples . . . . . . . . . . . . . . . . . . . . 106
8.2.1 Read From A Single Calendar . . . . . . . . . . . . . 106
8.2.2 Read From Multiple Calendars . . . . . . . . . . . . . 107
8.2.3 Timeouts . . . . . . . . . . . . . . . . . . . . . . . 109
8.2.4 Using Parent and Children Properties . . . . . . . . . 110
8.2.5 Query VEVENT.DTSTART and VALARM.DTSTART . . . . . . . 110
9. Implementation Issues . . . . . . . . . . . . . . . . 111
10. Properties . . . . . . . . . . . . . . . . . . . . . . 112
10.1 Calendar Store Properties . . . . . . . . . . . . . . 112
10.2 Calendar Properties . . . . . . . . . . . . . . . . . 113
11. Security Considerations . . . . . . . . . . . . . . . 116
12. CAP Item Registration . . . . . . . . . . . . . . . . 117
12.1 Registration of New and Modified CAP Entities . . . . 117
12.2 Registration of New Entities . . . . . . . . . . . . . 117
12.2.1 Define the Item . . . . . . . . . . . . . . . . . . . 117
12.2.2 Post the item definition . . . . . . . . . . . . . . . 118
12.2.3 Allow a comment period . . . . . . . . . . . . . . . . 118
12.2.4 Submit the proposal for approval . . . . . . . . . . . 118
12.3 Property Change Control . . . . . . . . . . . . . . . 119
13. IANA Considerations . . . . . . . . . . . . . . . . . 120
Authors' Addresses . . . . . . . . . . . . . . . . . . 120
A. Acknowledegements . . . . . . . . . . . . . . . . . . 122
B. Bibliography . . . . . . . . . . . . . . . . . . . . . 123
Full Copyright Statement . . . . . . . . . . . . . . . 124
1. Introduction 1. Introduction
This document specifies how a Calendar User Agent (CUA) interacts This document specifies how a Calendar User Agent (CUA) interacts
with a Calendar Store (CS) to manage calendar information. In with a Calendar Store (CS) to manage calendar information. In
particular, it specifies how to query, create, modify, and delete particular, it specifies how to query, create, modify, and delete
iCalendar components (e.g., events, to-dos, or daily journal iCalendar components (e.g., events, to-dos, or daily journal
entries). It further specifies how to search for available busy time entries). It further specifies how to search for available busy time
information. information.
This protocol is based on request/response form of data units, sent CAP is specified as a BEEP "profile". As such many aspects of the
from a client CUA to a calendar server. The protocol data units protocol (e.g., authentication and privacy) are provided within the
leverage the standard iCalendar format [iCAL] for conveying CS BEEP core [BEEP]. The protocol data units leverage the standard
related information. iCalendar format [iCAL] to convey calendar related information.
1.1 Formatting Conventions 1.1 Formatting Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
Calendaring and scheduling roles are referred to in quoted- strings Calendaring and scheduling roles are referred to in quoted-strings of
of text with the first character of each word in upper case. For text with the first character of each word in upper case. For
example, "Organizer" refers to a role of a "Calendar User" (CU) example, "Organizer" refers to a role of a "Calendar User" (CU)
within the protocol defined by this memo. Calendar components within the protocol defined by this memo. Calendar components
defined by [iCAL] are referred to with capitalized, quoted-strings of defined by [iCAL] are referred to with capitalized, quoted-strings of
text. All calendar components start with the letter "V". For text. All calendar components start with the letter "V". For
example, "VEVENT" refers to the event calendar component, "VTODO" example, "VEVENT" refers to the event calendar component, "VTODO"
refers to the to-do calendar component and "VJOURNAL" refers to the refers to the to-do calendar component and "VJOURNAL" refers to the
daily journal calendar component. Calendar access methods defined by daily journal calendar component.
this memo, as well as scheduling methods defined by [iTIP], are
referred to with capitalized, quoted-strings of text. For example, Scheduling methods defined by [iTIP], are referred to with
"CREATE" refers to the method for creating a calendar component on a capitalized, quoted-strings of text. For example, "REPLY" refers to
calendar, "READ" refers to the method for reading calendar the method for replying to a "REQUEST".
components.
Calendar commands are referred by lower-case, quotes-strings of text,
followed by the word "command". For example, "create" command refers
to the command for creating a calendar entry, "search" command refers
to the command for reading calendar components.
Properties defined by this memo are referred to with capitalized, Properties defined by this memo are referred to with capitalized,
quoted-strings of text, followed by the word "property". For quoted-strings of text, followed by the word "property". For
example, "ATTENDEE" property refers to the iCalendar property used to example, "ATTENDEE" property refers to the iCalendar property used to
convey the calendar address of a "Calendar User". Property convey the calendar address of a "Calendar User". Property
parameters defined by this memo are referred to with lower case, parameters defined by this memo are referred to with capitalized,
quoted-strings of text, followed by the word "parameter". For quoted-strings of text, followed by the word "parameter". For
example, "value" parameter refers to the iCalendar property parameter example, "PARTSTAT" parameter refers to the iCalendar property
used to override the default data type for a property value. parameter used to specify the participation status of an attendee.
Enumerated values defined by this memo are referred to with Enumerated values defined by this memo are referred to with
capitalized text, either alone or followed by the word "value". capitalized text, either alone or followed by the word "value".
In tables, the quoted-string text is specified without quotes in In tables, the quoted-string text is specified without quotes in
order to minimize the table length. order to minimize the table length.
1.2 Related Documents 1.2 Related Documents
Implementers will need to be familiar with several other memos that, Implementers will need to be familiar with several other memos that,
along with this one, describe the Internet calendaring and scheduling along with this one, describe the Internet calendaring and scheduling
skipping to change at page 6, line 22 skipping to change at page 6, line 26
and property parameters used in the protocols, along with the methods and property parameters used in the protocols, along with the methods
for representing and encoding them, for representing and encoding them,
[iTIP] (RFC2446) which specifies an interoperability protocol for [iTIP] (RFC2446) which specifies an interoperability protocol for
scheduling between different implementations. The related documents scheduling between different implementations. The related documents
are: are:
[iMIP] (RFC2447) which specifies an Internet email binding for [iMIP] (RFC2447) which specifies an Internet email binding for
[iTIP]. [iTIP].
[IMPL] (draft/rfc...) which is a guide to implementers and describes [GUIDE] (draft/rfc...) which is a guide to implementers and describes
the elements of a calendaring system, how they interact with each the elements of a calendaring system, how they interact with each
other, how they interact with end users, and how the standards and other, how they interact with end users, and how the standards and
protocols are used. protocols are used.
This memo does not attempt to repeat the specification of concepts or This memo does not attempt to repeat the specification of concepts
definitions from these other memos. Where possible, references are and definitions from these other memos. Where possible, references
made to the memo that provides for the specification of these are made to the memo that provides for the specification of these
concepts or definitions. concepts and definitions.
1.3 Definitions 1.3 Definitions
Authentication ID (AuthID)
A tuple of username, realm, and authentication method, used by the
Calendar Service internally to identify a successfully
authenticated CAP session.
Booked Booked
A entry in a calendar has one of two conceptual states. It is An entry in a calendar has one of two conceptual states. It is
scheduled or it is booked. A scheduled entry has been stored in scheduled or it is booked. A scheduled entry has been stored in
the calendar store but has not been acted on by a calendar user or the calendar store but has not been acted on by a calendar user
calendar user agent. A booked appointment is an entry that has (CU) or calendar user agent (CUA). A scheduled entry contains a
had its state changed from one of the [iTIP] scheduling methods to METHOD property set to an [iTIP] method. A booked entry is a
a CAP method of CREATE by a calendar user or calendar user agent component does not have a METHOD property.
which resulted in decision to keep the entry in the calendar
store.
Calendar Calendar
A collection of logically related objects or entities each of A collection of logically related objects or entities each of
which may be associated with a calendar date and possibly time of which may be associated with a calendar date and possibly time of
day. These entities can include other calendar properties or day. These entities can include other calendar properties or
calendar components.In addition, a calendar might be calendar components.In addition, a calendar might be
hierarchically related to other sub-calendars. A calendar is hierarchically related to other sub-calendars. A calendar is
identified by its unique calendar identifier. The [iCAL] defines identified by its unique calendar identifier. The [iCAL] defines
calendar properties, calendar components and component properties calendar properties, calendar components and component properties
that make up the content of a calendar. that make up the content of a calendar.
Calendar Access Protocol (CAP) Calendar Access Protocol (CAP)
skipping to change at page 7, line 16 skipping to change at page 7, line 13
day. These entities can include other calendar properties or day. These entities can include other calendar properties or
calendar components.In addition, a calendar might be calendar components.In addition, a calendar might be
hierarchically related to other sub-calendars. A calendar is hierarchically related to other sub-calendars. A calendar is
identified by its unique calendar identifier. The [iCAL] defines identified by its unique calendar identifier. The [iCAL] defines
calendar properties, calendar components and component properties calendar properties, calendar components and component properties
that make up the content of a calendar. that make up the content of a calendar.
Calendar Access Protocol (CAP) Calendar Access Protocol (CAP)
The standard Internet protocol that permits a Calendar User Agent The standard Internet protocol that permits a Calendar User Agent
to access and manipulate a calendar residing on a Calendar Store. to access and manipulate calendars residing on a Calendar Store.
Calendar Access Rights (CAR) Calendar Access Rights (CAR)
The mechanism for specifying the CAP operations ("ACTIONS") that a The mechanism for specifying the CAP operations ("ACTION") that a
particular calendar user ("UPN") are granted or denied permission particular calendar user ("UPN") are granted or denied permission
to perform on a given calendar item ("OBJECT"). The calendar to perform on a given calendar object ("OBJECT"). The calendar
access rights are specified with the "VCAR" calendar components access rights are specified with the "VCAR" calendar components
within a CS and calendar. within a CS and calendar.
Calendar Collection
A collection of Calendars, Resource Calendars, and/or other
Calendar Collections. These collections are expanded by the CS
and may reside either locally or in an external database or
directory. The calendars in the collection may be fixed or
dynamic over time.
Calendar Component Calendar Component
An item within a calendar. Some types of calendar components An object within a calendar or a calendar store (CS). Some types
include events, to-dos, journals, alarms, time zones and freebusy of calendar components include calendars, events, to-dos,
data. A calendar component consists of component properties and journals, alarms, time zones and freebusy data. A calendar
possibly other sub-components. For example, an event may contain component consists of component properties and possibly other sub-
an alarm component. components. For example, an event may contain an alarm component.
Calendar Component Properties Calendar Component Properties
An attribute of a particular calendar component. Some calendar An attribute of a particular calendar component. Some calendar
component properties are applicable to different types of calendar component properties are applicable to different types of calendar
components. For example, DTSTART is applicable to VEVENT, VTODO, components. For example, DTSTART is applicable to VEVENT, VTODO,
VJOURNAL calendar components. Other calendar components are VJOURNAL calendar components. Other calendar components are
applicable only to an individual type of calendar component. For applicable only to an individual type of calendar component. For
example, TZURL is only applicable to VTIMEZONE calendar example, TZURL is only applicable to VTIMEZONE calendar
components. components.
skipping to change at page 8, line 17 skipping to change at page 8, line 5
A globally unique identifier associated with a calendar. A globally unique identifier associated with a calendar.
Calendars reside within a CS. See Qualified Calendar Identifier Calendars reside within a CS. See Qualified Calendar Identifier
and Relative Calendar Identifier. and Relative Calendar Identifier.
Calendar Policy Calendar Policy
A CAP operational restriction on the access or manipulation of a A CAP operational restriction on the access or manipulation of a
calendar. For example, "events MUST be scheduled in unit calendar. For example, "events MUST be scheduled in unit
intervals of one hour". intervals of one hour".
Calendar Properties Calendar Property
An attribute of a calendar. The attribute applies to the An attribute of a calendar (VAGENDA). The attribute applies to
calendar, as a whole. For example, CALSCALE specifies the the calendar, as a whole. For example, CALSCALE specifies the
calendar scale (e.g., GREGORIAN) for the whole calendar. calendar scale (e.g., GREGORIAN) for the whole calendar.
Calendar Service Calendar Service
An implementation of a Calendar Store that manages one or more An implementation of a Calendar Store that manages one or more
calendars. calendars.
Calendar Store (CS) Calendar Store (CS)
The data and service model definition for a Calendar Service. The data and service model definition for a Calendar Service.
Calendar Store Identifier (CSID) Calendar Store Identifier (CSID)
The globally unique identifier for an individual CS. A CSID The globally unique identifier for an individual CS. A CSID
consists of the host and port portions of a "Common Internet consists of the host and port portions of a "Common Internet
Scheme Syntax" part of a URL, as defined by [URL]. Scheme Syntax" part of a URL, as defined by [URL].
Calendar Store Components Calendar Store Components
Components maintained in a CS specify a grouping of calendar Components maintained in a CS specify a grouping of calendar
store-wide information. Calendar store components can be accessed store-wide information.
using CAP.
Calendar Store Properties Calendar Store Properties
Properties maintained in a Calendar Store calendar store-wide Properties maintained in a Calendar Store calendar store-wide
information. Calendar store properties can be accessed using CAP. information.
Calendar User (CU) Calendar User (CU)
An entity (often biological) that uses a calendaring system. An entity (often biological) that uses a calendaring system.
Calendar User Agent (CUA) Calendar User Agent (CUA)
The CUA is the client application that a CU or UG utilizes to The CUA is the client application that a CU utilizes to access and
access and manipulate a calendar. manipulate a calendar.
Calendaring and Scheduling System
The computer sub-system that provides the services for accessing,
manipulating calendars and scheduling calendar components.
CAP Session CAP Session
An open communication channel between a CAP CUA and a CAP CS. An open communication channel between a CUA and a Calendar
Service.
Connected Mode
A mobile computing mode where the CUA is directly connected to the
CS.
Delegate Delegate
Is a calendar user (sometimes called the delegatee) who has been A calendar user (sometimes called the delegatee) who has been
assigned participation in a scheduled calendar component (e.g., assigned participation in a scheduled calendar component (e.g.,
VEVENT) by one of the attendees in the scheduled calendar VEVENT) by one of the attendees in the scheduled calendar
component (sometimes called the delegator). An example of a component (sometimes called the delegator). An example of a
delegate is a team member told to go to a particular meeting. delegate is a team member told to go to a particular meeting.
Designate Designate
Is a calendar user who is authorized to act on behalf of another A calendar user who is authorized to act on behalf of another
calendar user. An example of a designate is an assistant. calendar user. An example of a designate is an assistant.
Disconnected Mode
A mobile computing mode where a CUA can be disconnected from a CS.
When the CUA is disconnected, it is in the disconnected mode.
Fan Out Fan Out
The calendaring and scheduling process by which a calendar The calendaring and scheduling process by which a calendar
operation on one calendar is also performed on every other operation on one calendar is also performed on every other
calendar specified in the operation. This may include the calendar specified in the operation.
calendar associated with TARGET calendar property.
Hierarchical Calendars Hierarchical Calendars
A CS feature where a calendar have a hierarchical relationship A CS feature where a calendar has a hierarchical relationship with
with another calendar in the CS. The top-most calendar in the another calendar in the CS. The top-most calendars in the
hierarchical relationship has the CS as its parent. There may be hierarchical relationship have the CS as their parent. There may
multiple top- most calendars in a given CS. Within a given be multiple top-most calendars in a given CS. Within a given
hierarchical relationship, all sub-calendars have a calendar with hierarchical relationship, all sub-calendars have a calendar with
a "parent" topographical relationship. In addition, sub-calendars a "parent" relationship. In addition, sub-calendars may have a
may have a relationship with another calendar that has a "child" relationship with another calendar that has a "child"
topographical relationship. In addition, a calendar may have a relationship. The hierarchical calendar feature is not a storage
relationship such that one or more calendars have a "sibling" relationship of the calendars within the CS. Instead it is a
topographical relationship with the calendar. The hierarchical feature that relates access control rights to calendar content
calendar feature is not a storage relationship of the calendars between different calendars in the CS. The hierarchical
within the CS. Instead it is a feature that relates access relationship of a calendar is specified in the "PARENT" and
control rights to calendar content between different calendars in "CHILDREN" calendar properties.
the CS. The hierarchical relationship of a calendar is specified
in the "PARENT" and "CHILDREN" calendar properties.
High Bandwidth Connection
A communications connection supporting high transfer rates;
transfer rates commonly found within a LAN.
Local Store
A CS which is on the same platform as the CUA.
Low Bandwidth Connection
A communications connection supporting slow transfer rates;
transfer rates commonly found in remote access technology.
Overlapped Booking Overlapped Booking
A policy which indicates whether or not OPAQUE events can overlap A policy which indicates whether or not OPAQUE events can overlap
one another. When the policy is applied to a calendar it one another. When the policy is applied to a calendar it
indicates whether or not the time span of any entry (VEVENT, indicates whether or not the time span of any entry (VEVENT,
VTODO, ...) in the calendar can overlap the time span of any other VTODO, ...) in the calendar can overlap the time span of any other
entry in the same calendar. When applied to an individual entry, entry in the same calendar. When applied to an individual entry,
it indicates whether or not any other entry's time span can it indicates whether or not any other entry's time span can
overlap that individual entry. overlap that individual entry.
Owner Owner
One or more CUs or UGs that have "OWNER" calendar access rights One or more CUs or UGs that have "OWNER" calendar access rights
for a calendar. The owner is specified in the "OWNER" calendar for a calendar. The owner is specified in the "OWNER" calendar
property and in the "OWNER" calendar store property. property.
Qualified Calendar Identifier (Qualified CalID) Qualified Calendar Identifier (Qualified CalID)
A CalID where both the <scheme> and <csid> are present. A CalID where both the <scheme> and <csid> are present.
Realm Realm
A collection of calendar user accounts, identified by a string. A collection of calendar user accounts, identified by a string.
The name of the realm is only used in UPNs. In order to avoid The name of the Realm is only used in UPNs. In order to avoid
namespace conflict, the realm SHOULD be postfixed with an namespace conflict, the Realm SHOULD be postfixed with an
appropriate DNS domain name. (eg: the foobar realm could be appropriate DNS domain name. (e.g., the foobar Realm could be
called foobar.example.com). called foobar.example.com).
Relative Calendar Identifier (Relative CalID) Relative Calendar Identifier (Relative CalID)
An identifier for an individual calendar in a calendar store. It An identifier for an individual calendar in a calendar store. It
is unique within a calendar store. It is recommended to be is unique within a calendar store. It is recommended to be
globally unique. A Relative CalID consists of the portion of the globally unique. A Relative CalID consists of the portion of the
"scheme part" of a Qualified CalID following the Calendar Store "scheme part" of a Qualified CalID following the Calendar Store
Identifier. This is the same as the "URL path" of the "Common Identifier. This is the same as the "URL path" of the "Common
Internet Scheme Syntax" portion of a URL, as defined by [URL]. Internet Scheme Syntax" portion of a URL, as defined by [URL].
Remote Store
A CS which is not on the same platform as the CUA.
Resource Calendar (RC)
A non-human Calendar, associated with an organizational resource.
There is no syntactic difference between an RC and a Calendar.
Session Identity Session Identity
A UPN associated with a CAP session. A session gains an identity A UPN associated with a CAP session. A session gains an identity
after successful authentication. The identity is used in after successful authentication. The identity is used in
combination with CAR to determine access to data in the CS. combination with CAR to determine access to data in the CS.
Sub-calendars Sub-calendars
Calendars that have a "child" hierarchical relationship with Calendars that have a "child" hierarchical relationship with
another calendar, its "parent". another calendar, its "parent".
User Group (UG) User Group (UG)
A collection of Calendar Users and/or User Groups. These groups A collection of Calendar Users and/or User Groups. These groups
are expanded by the CS and may reside either locally or in an are expanded by the CS and may reside either locally or in an
external database or directory. The group membership may be fixed external database or directory. The group membership may be fixed
or dynamic over time. or dynamic over time.
User Name Username
A name which denotes a Calendar User within a realm. This is part A name which denotes a Calendar User within a Realm. This is part
of a UPN. of a UPN.
User Principal Name (UPN) User Principal Name (UPN)
An identifier that denotes a unique CU. A UPN is an RFC 822 A unique identifier that denotes a CU or a group of CU. A UPN is
compliant email address, with exceptions listed below, and in most a RFC 822 compliant email address, with exceptions listed below,
cases it is deliverable to the CU. In some cases it is identical and in most cases it is deliverable to the CU. In some cases it
to the CU's well known email address. A CU's UPN to email address is identical to the CU's well known email address. A CU's UPN
mapping MUST never be deliverable to a different person as there MUST never be an e-mail address that is deliverable to a different
is not requirement that they are the same. It consists of a person as there is no requirement that a person's UPN must be his
realm in the form of a valid, and unique, DNS domain name and a e-mail address. It consists of a Realm in the form of a valid,
unique username. In it's simplest form it looks like and unique, DNS domain name and a unique Username. In it's
"user@example.com". simplest form it looks like "user@example.com".
In certain cases a UPN will not be RFC 822 compliant. When In certain cases a UPN will not be RFC 822 compliant. When
anonymous authentication is used, or anonymous authorization is anonymous authentication is used, or anonymous authorization is
being defined, the special UPN "@" will be used. When being defined, the special UPN "@" will be used. When
authentication must be used, but unique identity must be obscured, authentication must be used, but unique identity must be obscured,
a UPN of the form @DNS-domain-name may be used. For example, a UPN of the form @DNS-domain-name may be used. For example,
"@example.com". Usage of these special cases is further discussed "@example.com". Usage of these special cases is further discussed
in the authentication and authorization sections of this document. in the authentication and authorization sections of this document.
2. CAP Design 2. CAP Design
2.1 System Model 2.1 System Model
The system model describes the high level components of a calendar The system model describes the high level components of a calendar
system and how they interact with each other. system and how they interact with each other.
CAP is used by a "Calendar User Agent" (CUA) to send commands to and CAP is used by a "Calendar User Agent" (CUA) to send commands to and
receive responses from a "Calendar Service" (CS). The CUA prepares a receive responses from a "Calendar Service".
[MIME] encapsulated iCalendar object containing a command, sends it
to the CS, and receives a [MIME] encapsulated iCalendar object as a
response. There are two distinct protocols in operation to
accomplish this exchange. The Transfer Protocol is used to move
these encapsulations between a CUA and a CS. The Application
Protocol defines the content and semantics of the iCalendar objects
sent between the CUA and the CS. This document defines both the
Transfer Protocol and the Application Protocol.
In the diagram below, a user uses CUA1 to communicate with CS1 using
CAP. The CUA must authenticate the Calendar User (CU) so that access
to calendars on CS1 can be controlled. The CUA can then view,
create, edit, and delete calendars, calendar properties, and calendar
components subject to the access rights.
CAP servers support fanout. Fanout allows a CUA to communicate with
a single CS to perform scheduling operations with calendars on
multiple CSs. That is, a CU can book or schedule events (or to-dos)
on or read events (or to-dos) from calendars on other calendar
stores. To accomplish this, a CAP server takes on these roles:
* CS1 MAY play the role of a CUA and use CAP to access CS2;
* CS1 MUST be able play the role of a CUA and use [iMIP] to
interoperate with other CUAs.
+-----+ +-----+
| | CAP | | CAP
CUA1------| CS1 |----------| CS2 |--------- CUA2
| | | | A
| | | | |
| | | | |
+-----+ +-----+ |
| IMIP |
+--------------------------------+
Note that the fanout feature in CAP is a convenience to the CUA. It
is perfectly valid for the CUA to assume the responsibility for
fanout if it wishes. That is, [iMIP] messages could also be sent
from CUA1 to CUA2.
CAP does not specify any trust model between CS1 and CS2.
Implementations may require a trust model to exist in order to
accomplish scheduling between CS1 and CS2.
2.1.1 Firewalls and Fanout
- - - ------INTERNET---------------------- - - -
| |
+----------------+ +----------------------+
| Site Public CS |<---->| Other Site Public CS |
| (CS-P) | | (CS-P2) |
+----------------+ +----------------------+
^ ^
| .
v .
+----------------+ .
| Site Firewall | - - - ---Other LAN---- -
+----------------+
|
- - ---------------LAN---------------------------- - - -
| | |
+--------------+ +--------------+ +- - - - - - - - +
| Department-1 | | Department-2 | | . . . |
| CS-1 | | CS-2 | | CS-n |
+--------------+ +--------------+ +- - - - - - - - +
One example of a site site policy could be that all entries in
department calendars that were marked PUBLIC, were visible on the
internet to any users that was granted access to CS-P.
With fanout in place, CS-P would authenticate the internet user and The CUA prepares a [MIME] encapsulated command, sends it to the CS,
decide in an implementation specific way, which user CS (CS-1, CS- and receives a [MIME] encapsulated response. The calendaring related
2, CS-n) the TARGET calendar physically existed. Then using information within these messages are represented by iCalendar
fanout, CS- P sends the request subject to VCARs or immutable objects.
VCARS from CS-P to the users CS and back to the CUA through CS-P.
CS-P could be a smart proxy.
And there is no reason that the target calendar need to exist under There are two distinct protocols in operation to accomplish this
the firewall (CS-P2), only that the CSs can authenticate with each exchange. [BEEP] is used to move these encapsulations between a CUA
other. In this way all users in a domain could appear to be at and a CS. The CAP profile defines the content and semantics of the
calendar.site.com, hiding all CS-1 through CS-n from the internet. messages sent between the CUA and the Calendar Service.
And also hiding that fact that CS-P2 may be a separate domain
controlled by the same site administrators as CS-P (which in turn
could do fanout to its LAN).
2.2 Calendar Store Object Model 2.2 Calendar Store Object Model
The conceptual model for a calendar store is shown below. The The conceptual model for a calendar store is shown below. The
calendar store contains calendars, VTIMEZONEs, VCARs, and calendar calendar store contains VCARs, VQUERYs, VTIMEZONEs, VAGENDAs and
store properties. calendar store properties.
Calendars contain VEVENTs, VTODOs, VJOURNALs, VALARMs, VCARs, and Calendars (VAGENDAs) contain VEVENTs, VTODOs, VJOURNALs, VCARs,
calendar properties. Calendars may also contain other calendars. VTIMEZONEs, VQUERYs and calendar properties. Calendars may also
contain other calendars (VAGENDAs).
Calendar Store Calendar Store
| |
+-- VCARs +-- VCARs
+-- Properties +-- VQUERYs
+-- VTIMEZONEs
+-- VCALENDARs
|
+--VEVENTs
+--VALARMs
+--VTODOs
+--VALARMs
+--VJOURNALs
+--VCARs
+--Properties
+--VTIMEZONEs
+--VSCHEDULE
+--VQUERY
+--Calendar
|
+--VEVENTs
+--VALARMs
+--VTODOs
+--VALARMs
+--VJOURNALs
+--VCARs
+--Properties
+--VTIMEZONEs +--VTIMEZONEs
+--VSCHEDULE +-- VAGENDA
+--VQUERY | |
+--Calendar | +--VEVENTs
| | | |
... | | +--VALARMs
| +--VTODOs
| | |
| | +--VALARMs
| +--VJOURNALs
| +--VCARs
| +--VTIMEZONEs
| +--VQUERYs
| +--VAGENDAs
| | |
| | +--VEVENTs
| | | |
| | | +--VALARMs
| | +--VTODOs
| | | |
| | | +--VALARMs
| | +--VJOURNALs
| | +--VCARs
| | +--VTIMEZONEs
| | +--VQUERYs
| | +--VFREEBUSY
| | +--VAGENDAs
| | | |
| | | ...
Calendars within a Calendar Store are identified by their Relative Calendars within a Calendar Store are identified by their Relative
CALID. CALID.
In this model, VSCHEDULE is a queue of scheduling messages that have In this model, VSCHEDULE is a set of scheduling messages that have
not yet been applied to the calendar. Items in VSCHEDULE are not yet been applied to the calendar. Components in VSCHEDULE are
discussed in more detail below. discussed in more detail below.
2.3 Protocol Model 2.3 Protocol Model
A generic transfer-layer, Calendar Server Transfer Protocol (CSTP), The commands listed below are used to manipulate the data on the
is used to move data objects between a CUA and the CS. CSTP commands calendar store. Their usage and semantics are defined in Section 6.
are listed below and their usage and semantics are defined in section
7.1 of this document.
CSTP Commands
-----------------------------------------------------------
Command Description
-----------------------------------------------------------
ABORT Stop a command. Perhaps because its latency
time has been exceeded.
AUTHENTICATE Authenticate a UPN.
CONTINUE Continue the execution of a command whose
Latency time has been exceeded.
IDENTIFY Set a new identity for calendar access.
DISCONNECT Terminate a connection with the server.
SENDDATA Send a data object [MIME] encapsulated
iCalendar.
STARTTLS Negotiate transport level security using
[TLS].
NOOP Do nothing operation.
-----------------------------------------------------------
Application-level commands are used to manipulate data on the
calendar store. They are listed below and discussed in detail in
section 7.2.
CAP Calendaring Commands
----------------------------------------------------------
Command Description
----------------------------------------------------------
CREATE Create a new calendar or component.
DELETE Delete a calendar or component.
GENERATEUID Generate one or more unique ids.
MODIFY Change a calendar or component.
MOVE Move a calendar.
READ Read a calendar properties or components.
----------------------------------------------------------
CAP Scheduling Commands CAP Commands
(As defined in [iTIP])
----------------------------------------------------------- -----------------------------------------------------------
Command Description Command Description
----------------------------------------------------------- -----------------------------------------------------------
PUBLISH Publish a calendar entry to one or more create Create a new calendar component.
calendars. delete Delete calendar components.
REQUEST Schedule a calendar entry with one or more generate-uid Generate one or more unique ids.
calendars. get-capability Query the capabilities of the CS.
REPLY Response to a scheduling request. identify Set a new identity for calendar access.
ADD Add one or more instances to an existing modify Modify calendar components.
calendar entry. move Move calendar components to another container.
CANCEL Cancel one or more instances to an existing noop Do nothing.
calendar entry. schedule Add an [iTIP] object to the VSCHEDULE set.
REFRESH A request for the latest version of a search Search for calendar components.
calendar entry.
COUNTER A request for a change (a counter-proposal)
to a calendar entry.
DECLINECOUNTER Decline a counter proposal.
----------------------------------------------------------- -----------------------------------------------------------
2.4 Security Model 2.4 Security Model
Authentication to the CS will be performed using [SASL]. 2.4.1 Calendar User and UPNs
As noted in the CAP system model section, a variety of connectivity
scenarios are possible. This complicates the security model
considerably, and a thorough familiarity with the concepts is
required to ensure interoperability.
Basic threats to a Calendaring and Scheduling System include:
(1) Unauthorized access to data via data-fetching operations,
(2) Unauthorized access to reusable client authentication
information by monitoring others' access,
(3) Unauthorized access to data by monitoring others' access,
(4) Unauthorized modification of data,
(5) Unauthorized or excessive use of resources (denial of
service), and
(6) Spoofing of CS: Tricking a client into believing that
information came from the CS when in fact it did not, either
by modifying data in transit or misdirecting the client's
connection.
Threats (1), (4), (5) and (6) are due to hostile clients. Threats
(2), and (3) are due to hostile agents on the path between client and
server, or posing as a server.
CAP can be protected with the following security mechanisms:
(1) Client authentication by means of the SASL mechanism set,
possibly backed by the TLS credentials exchange mechanism,
(2) Client authorization by means of access control based on the
requestor's authenticated identity,
(3) Data integrity protection by means of the TLS protocol or data
integrity SASL mechanisms,
(4) Protection against snooping by means of the TLS protocol or
data encrypting SASL mechanisms,
(5) Resource limitation by means of administrative limits on
service controls, and
(6) Server authentication by means of the TLS protocol or SASL
mechanism.
Imposition of access controls (authorizations) is done by means of
VCARs, an overview is provided in the section 2.4.4 <fwd ref> and a
detailed syntax is provided in section 6 <fwd ref> Authentication is
explained in detail in section 2.4.1 <fwd ref>
2.4.1 Authentication, Credentials, and Identity
Generically, authentication credentials are the evidence supplied by
one party to another, asserting the identity of the supplying party
(e.g. a user) who is attempting to establish an association with the
other party (typically a server). Authentication is the process of
generating, transmitting, and verifying these credentials and thus
the identity they assert. An authentication identity is the name
presented in a credential.
There are many forms of authentication credentials. The form used
depends upon the particular authentication mechanism negotiated by
the parties. For example: X.509 certificates, Kerberos tickets,
simple identity and password pairs. Note that an authentication
mechanism may constrain the form of authentication identities used
with it.
SASL only provides a protocol to negotiate a mutually acceptable
authentication mechanism. SASL itself does not constrain or dictate
the form of the authentication identities used to perform the
authentication.
2.4.2 Calendar User and UPNs
A Calendar User(CU) is an entity that can be authenticated. It is A Calendar User(CU) is an entity that can be authenticated. It is
represented in CAP as a UPN. A UPN is the owner of a calendar and represented in CAP as a UPN, which is the subject of access rights.
the subject of access rights. The UPN representation is independent The UPN representation is independent of the authentication mechanism
of the authentication mechanism used during a particular CUA/CS used during a particular CUA/CS interaction. This is because UPNs
interaction. This is because UPNs are used within VCARs. If the UPN are used within VCARs. If the UPN were dependent on the
were dependent on the authentication mechanism, a VCAR could not be authentication mechanism, a VCAR could not be consistently evaluated.
consistently evaluated. A CU may use one mechanism while using one A CU may use one mechanism while using one CUA but the same CU may
CUA but the same CU may use a different authentication mechanism when use a different authentication mechanism when using a different CUA,
using a different CUA, or while connecting from a different location. or while connecting from a different location.
The user may also have multiple UPNs for various purposes. The user may also have multiple UPNs for various purposes.
Note that the immutability of the user's UPN may be achieved by using Note that the immutability of the user's UPN may be achieved by using
SASL's authorization identity feature. (The transmitted SASL's authorization identity feature. (The transmitted
authorization identity may be different than the identity in the authorization identity may be different than the identity in the
client's authentication credentials.) [SASL, section 3] This also client's authentication credentials.) [SASL, section 3]. This also
permits a CU to authenticate using their own credentials, yet request permits a CU to authenticate using their own credentials, yet request
the access privileges of the identity for which they are proxying the access privileges of the identity for which they are proxying
SASL. Also, the form of authentication identity supplied by a SASL. Also, the form of authentication identity supplied by a
service like TLS may not correspond to the UPNs used to express a service like TLS may not correspond to the UPNs used to express a
server's access control policy, requiring a server-specific mapping server's access rights, requiring a server specific mapping to be
to be done. The method by which a server composes and validates an done. The method by which a server determines a UPN, based on the
authorization identity from the authentication credentials supplied authentication credentials supplied by a client, is implementation
by a client is implementation-specific. specific.
For Calendaring and Scheduling Systems that are integrated with a
directory system, the CS MUST support the ability to configure which
schema attribute stores the UPN. The CS MAY allow one or more
attributes to be searched for the UPN.
2.4.2.1 UPNs and Certificates 2.4.1.1 UPNs and Certificates
When using X.509 certificates for purposes of CAP authentication, the When using X.509 certificates for purposes of CAP authentication, the
UPN should appear in the certificate. Unfortunately there is no UPN should appear in the certificate. Unfortunately there is no
single correct guideline for which field should contain the UPN. single correct guideline for which field should contain the UPN.
From RFC-2459, section 4.1.2.6 (Subject): From RFC-2459, section 4.1.2.6 (Subject):
If subject naming information is present only in the subjectAlt- If subject naming information is present only in the subjectAlt-
Name extension (e.g., a key bound only to an email address or Name extension (e.g., a key bound only to an email address or
URI), then the subject name MUST be an empty sequence and the URI), then the subject name MUST be an empty sequence and the
skipping to change at page 20, line 16 skipping to change at page 15, line 28
In addition, legacy implementations exist where an RFC 822 name is In addition, legacy implementations exist where an RFC 822 name is
embedded in the subject distinguished name as an EmailAddress embedded in the subject distinguished name as an EmailAddress
attribute. The attribute value for EmailAddress is of type attribute. The attribute value for EmailAddress is of type
IA5String to permit inclusion of the character '@', which is not IA5String to permit inclusion of the character '@', which is not
part of the PrintableString character set. EmailAddress attribute part of the PrintableString character set. EmailAddress attribute
values are not case sensitive (e.g., "fanfeedback@redsox.com" is values are not case sensitive (e.g., "fanfeedback@redsox.com" is
the same as "FANFEEDBACK@REDSOX.COM"). the same as "FANFEEDBACK@REDSOX.COM").
Conforming implementations generating new certificates with Conforming implementations generating new certificates with
electronic mail addresses MUST use the rfc822Name in the subject electronic mail addresses MUST use the rfc822Name in the subject
alternative name field (see sec. 4.2.1.7 [of RFC 2459]) to alternative name field (see sec. 4.2.1.7 of [RFC 2459]) to
describe such identities. Simultaneous inclusion of the describe such identities. Simultaneous inclusion of the
EmailAddress attribute in the subject distinguished name to EmailAddress attribute in the subject distinguished name to
support legacy implementations is deprecated but permitted. support legacy implementations is deprecated but permitted.
Since no single method of including the UPN in the certificate will Since no single method of including the UPN in the certificate will
work in all cases, CAP implementations MUST support the ability to work in all cases, CAP implementations MUST support the ability to
configure what the mapping will be by the CS administrator. configure what the mapping will be by the CS administrator.
Implementations MAY support multiple mapping definitions, for Implementations MAY support multiple mapping definitions, for
example, the UPN may be found in either the subject alternative name example, the UPN may be found in either the subject alternative name
field, or the UPN may be embedded in the subject distinguished name field, or the UPN may be embedded in the subject distinguished name
as an EmailAddress attribute. as an EmailAddress attribute.
Note: If a CS or CUA is validating data received via iMIP, if the Note: If a CS or CUA is validating data received via iMIP, if the
"ORGANIZER" or "ATTENDEE" property said (e.g.) "ATTENDEE;CN=Joe "ORGANIZER" or "ATTENDEE" property said (e.g.) "ATTENDEE;CN=Joe
Random User:juser@example.com" then the email address should be Random User:MAILTO:juser@example.com" then the email address should
checked against the UPN, and the CN should also be checked. This is be checked against the UPN, and the CN should also be checked. This
so the "ATTENDEE" property couldn't be munged to something misleading is so the "ATTENDEE" property cannot be changed to something
like "ATTENDEE;CN=Joe Rictus User:juser@example.com" and have it pass misleading like "ATTENDEE;CN=Joe Rictus
validation. This validation will also defeat other attempts at User:MAILTO:juser@example.com" and have it pass validation. This
confusion. validation will also defeat other attempts at confusion.
2.4.2.2 Anonymous Users and Authentication 2.4.1.2 Anonymous Users and Authentication
Anonymous access is often desirable. For example an organization may Anonymous access is often desirable. For example an organization may
publish calendar information that does not require any access control publish calendar information that does not require any access control
for viewing or login. Conversely, a user may wish to view for viewing or login. Conversely, a user may wish to view
unrestricted calendar information without revealing their identity. unrestricted calendar information without revealing their identity.
CAP implementations MUST support anonymous authentication, as defined 2.4.1.3 User Groups
in section <fwd ref 7.1.3>
CAP implementations MAY support anonymous authentication with TLS, as
defined in section <fwd ref 7.1.3.2>
2.4.2.3 Required Security Mechanisms
The following implementation conformance requirements are in place:
(1) For a read-only, public CS, anonymous authentication,
described in section <fwd ref 7.1.3.1> can be used.
(2) Implementations providing password-based authenticated access
MUST support authentication using Digest, as described in section
<fwd ref&gt [ed note: this section has not yet been defined.
Paul can you please look into it?]; This provides client
authentication with protection against passive eavesdropping
attacks, but does not provide protection against active
intermediary attacks.
(3) For a CS needing session protection and authentication, the
Start TLS extended operation, and either the simple authentication
choice or the SASL EXTERNAL mechanism, are to be used together.
Implementations SHOULD support authentication with a password as
described in section <fwd ref> and SHOULD support authentication
with a certificate as described in section <fwd ref> Together,
these can provide integrity and disclosure protection of
transmitted data, and authentication of client and server,
including protection against active intermediary attacks.
2.4.2.4 TLS Ciphersuites
The following ciphersuites defined in [RFC 2246] MUST NOT be used for
confidentiality protection of passwords or data:
TLS_NULL_WITH_NULL_NULL
TLS_RSA_WITH_NULL_MD5
TLS_RSA_WITH_NULL_SHA
The following ciphersuites defined in [RFC 2246] can be cracked
easily (less than a week of CPU time on a standard CPU in 1997). The
client and server SHOULD carefully consider the value of the password
or data being protected before using these ciphersuites:
TLS_RSA_EXPORT_WITH_RC4_40_MD5
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5
TLS_RSA_EXPORT_WITH_DES40_CBC_SHA
TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA
TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA
TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
TLS_DH_anon_EXPORT_WITH_RC4_40_MD5
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA
The following ciphersuites are vulnerable to man-in-the-middle
attacks, and SHOULD NOT be used to protect passwords or sensitive
data, unless the network configuration is such that the danger of a
man-in-the-middle attack is tolerable:
TLS_DH_anon_EXPORT_WITH_RC4_40_MD5
TLS_DH_anon_WITH_RC4_128_MD5
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA
TLS_DH_anon_WITH_DES_CBC_SHA
TLS_DH_anon_WITH_3DES_EDE_CBC_SHA
A client or server that supports TLS MUST support at least:
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
2.4.3 User Groups
A User Group is used to represent a collection of CUs or other UGs A User Group is used to represent a collection of CUs or other UGs
that can be referenced in VCARS. A UG is represented in CAP as a that can be referenced in VCARs. A UG is represented in CAP as a
UPN. The CUA cannot distinguish between a UPN that represents a CU UPN. The CUA cannot distinguish between a UPN that represents a CU
or a UG. or a UG.
UGs are expanded as necessary by the CS. The CS MUST accept a CUA UGs are expanded as necessary by the CS. The CS MAY expand a UG
request for UG expansion, although the CS may be configured to (including nested UGs) to obtain a list of unique CUs. Duplicate
restrict some responses. The CS MAY expand a UG (including nested UPNs are filtered during expansion.
UGs) to obtain a list of unique CUs. Duplicate UPNs are filtered
during expansion. Incomplete expansion should be treated as a
failure.
Groups may be in a directory service with its own ACL model and CAP
should use the directory service to expand a UPN subject to the
directory service access control model for the authenticated entity.
The CS should not preserve UG expansions across operations. A UG may The CS should not preserve UG expansions across operations. A UG may
reference a static list of members, or it may represent a dynamic reference a static list of members, or it may represent a dynamic
list. Each operation SHOULD generate its own expansion in order to list. Each operation SHOULD generate its own expansion in order to
recognize changes to UG membership. However, during fan out to other recognize changes to UG membership.
CSs, the originating CS SHOULD expand all UGs so that the target CS
receives only a list of unique CUs. This is to prevent confusion
when two CSs do not share the same UG database or directory.
CAP does not define commands or methods for managing UGs. CAP does not define commands or methods for managing UGs.
Small UG: 2.4.2 Access Rights - Summary
The Three Stooges. There is only and always three at any one
time.
Large UG:
The MIT graduating class of 1999. This is a static list.
Dynamic UG:
The IETF membership which is a large and changing list of members.
Nested UG:
The National Football League, made up of the AFC and NFC, which
are made up of 3 divisions each...
2.4.4 Access Rights - Summary
Access rights are used to grant or deny access to a calendar for a Access rights are used to grant or deny access to a calendar for a
CU. CAP defines a new component type called a Vcalendar Access Right CU. CAP defines a new component type called a Calendar Access Right
(VCAR). Specifically, a VCAR grants, or denies, UPNs the right to (VCAR). Specifically, a VCAR grants, or denies, UPNs the right to
read and write components, properties, and parameters on calendars read and write components, properties, and parameters on calendars
within a CS. within a CS.
The VCAR model does not put any restriction on the sequence in which The VCAR model does not put any restriction on the sequence in which
the object and access rights are created. That is, an event the object and access rights are created. That is, an event
associated with a particular VCAR might be created before or after associated with a particular VCAR might be created before or after
the actual VCAR is defined. In addition, the VCAR and VEVENT the actual VCAR is defined. In addition, the VCAR and VEVENT
definition might be created in the same iCalendar object and passed definition might be created in the same iCalendar object and passed
together in a single command. together in a single command.
All rights MUST be denied unless specifically granted; individual All rights MUST be denied unless specifically granted; individual
VCARs MUST be specifically granted to an authenticated CU. VCARs MUST be specifically granted to an authenticated CU.
The access for a particular UPN is the union of all grants for that The access for a particular UPN is the union of all grants for that
UPN minus the union of its denies. UPN minus the union of its denies.
2.4.4.1 VCalendar Access Right (VCAR) 2.4.2.1 Calendar Access Right (VCAR)
Access rights within CAP are specified with the "VCAR" calendar Access rights within CAP are specified with the "VCAR" calendar
component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID" component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID"
component properties. component properties.
Properties within an iCalendar object are unordered. This also is Properties within an iCalendar object are unordered. This also is
the case for the "GRANT", "DENY" and "CARID" properties. Likewise, the case for the "GRANT", "DENY" and "CARID" properties. Likewise,
there is no implied ordering required for components of a "RIGHTS" there is no implied ordering required for components of a "RIGHTS"
value type other than that specified by the ABNF. [EDITOR'S NOTE, value type other than that specified by the ABNF. [EDITOR'S NOTE,
this requires a lot of review. We think that this paragraph may be this requires a lot of review. We think that this paragraph may be
incorrect. ] incorrect. ]
For details on the VCAR syntax please see section <forward ref> For details on the VCAR syntax please see section <forward ref>
2.4.4.2 Decreed VCARs 2.4.2.2 Decreed VCARs
A CS MAY choose to implement and allow persistent immutable VCARs, A CS MAY choose to implement and allow persistent immutable VCARs,
that are configured by the CS Administrator, which apply to all that are configured by the CS administrator, which apply to all
calendars on the server. calendars on the server.
When a user attempts to modify a decreed VCAR an error will be When a user attempts to modify or override a decreed VCAR an error
returned, indicating that the user has insufficient authorization to will be returned, indicating that the user has insufficient
perform the operation. authorization to perform the operation.
The CAP protocol does not define the semantics used to initially The CAP protocol does not define the semantics used to initially
create a decreed VCAR. This administrative task is out side the create a decreed VCAR. This administrative task is outside the scope
scope of the CAP protocol. of the CAP protocol.
For example an implementation or a CS administrator may wish to For example an implementation or a CS administrator may wish to
define a VCAR that will always allow the calendar owners to have full define a VCAR that will always allow the calendar owners to have full
access to their own calendars. The GRANT property allows the OWNERs access to their own calendars. The GRANT property allows the OWNERs
all (OBJECT=*) access to their own calendar objects. The DENY all (OBJECT=*) access to their own calendar objects. The DENY
property disallows anyone (UPN=*) from being able to delete or modify property disallows anyone (UPN=*) from being able to delete or modify
this VCAR. this VCAR.
BEGIN:VCAR BEGIN:VCAR
CARID:Users Default Access CARID:Users Default Access
GRANT:UPN=OWNER;OBJECT=*;OBJECT=OBJECT=METHOD;VALUE=* GRANT:UPN=OWNER;OBJECT=*;OBJECT=OBJECT=METHOD;VALUE=*
DENY:UPN=*;OBJECT=VCAR;OBJECT=CARID; DENY:UPN=*;OBJECT=VCAR;OBJECT=CARID;
VALUE="Users Default Access" VALUE="Users Default Access"
;OBJECT=METHOD,VALUE=DELETE,MODIFY ;OBJECT=METHOD,VALUE=DELETE,MODIFY
END:VCAR END:VCAR
Decreed VCARs MUST be readable by the calendar owner in standard VCAR Decreed VCARs MUST be readable by the calendar owner in standard VCAR
format. format.
2.4.5 Inheritance 2.4.3 Inheritance
Calendars inherit VCARs from their parent calendar. Calendars whose Calendars inherit VCARs from their parent calendar. Calendars whose
parent is the Calendar Store inherit VCARs from the Calendar Store. parent is the Calendar Store inherit VCARs from the Calendar Store.
VCARs specified in a calendar or a sub-calendar override all VCARs specified in a calendar or a sub-calendar override all
inherited VCARs. inherited VCARs.
2.4.6 CAP Session Identity 2.4.4 CAP Session Identity
A CAP session has an associated set of authentication credentials, A BEEP session has an associated set of authentication credentials,
from which is derived a UPN. This UPN is the identity of the CAP from which is derived a UPN. This UPN is the identity of the CAP
session, and is used to determine access rights for the session. session, and is used to determine access rights for the session.
The CUA may change the identity of a CAP session by calling the The CUA may change the identity of a CAP session by calling the
"IDENTIFY" command. The Calendar Service only permits the operation "identify" command. The Calendar Service only permits the operation
if the session's authentication credentials are good for the if the session's authentication credentials are good for the
requested identity. The method of checking this permission is requested identity. The method of checking this permission is
implementation dependent, but may be thought of as a mapping from implementation dependent, but may be thought of as a mapping from
authentication credentials to UPNs. The "IDENTIFY" command allows a authentication credentials to UPNs. The "identify" command allows a
single set of authentication credentials to choose from multiple single set of authentication credentials to choose from multiple
identities, and allows multiple sets of authentication credentials to identities, and allows multiple sets of authentication credentials to
assume the same identity. assume the same identity.
For anonymous access the identity of the session is "@", a UPN with a For anonymous access the identity of the session is "@", a UPN with a
null username and null realm. A UPN with a null username, but non- null Username and null Realm. A UPN with a null Username, but non-
null realm, such as "@foo.com" may be used to mean any identity from null Realm, such as "@foo.com" may be used to mean any identity from
that realm, which is useful to grant access rights to all users in a that Realm, which is useful to grant access rights to all users in a
given realm. A UPN with a non-null username and null realm, such as given Realm. A UPN with a non-null Username and null Realm, such as
"bob@" could be a security risk and MUST NOT be used. "bob@" could be a security risk and MUST NOT be used.
Since the UPN includes realm information it may be used to govern Since the UPN includes Realm information it may be used to govern
calendar store access rights across realms. However, governing calendar store access rights across Realms. However, governing
access rights across realms is only useful if login access is access rights across Realms is only useful if login access is
available. This could be done through a trusted server relationship available. This could be done through a trusted server relationship
or a temporary account. or a temporary account.
The "IDENTIFY" command provides for a weak group implementation. By The "identify" command provides for a weak group implementation. By
allowing multiple sets of authentication credentials belonging to allowing multiple sets of authentication credentials belonging to
different users to identify as the same UPN, that UPN essentially different users to identify as the same UPN, that UPN essentially
identifies a group of people, and may be used for group calendar identifies a group of people, and may be used for group calendar
ownership, or the granting of access rights to a group. ownership, or the granting of access rights to a group.
Examples:
Small UG:
The Three Stooges. There will always be three, it will not
change.
Large UG:
The MIT graduating class of 1999. This is a static list.
Dynamic UG:
The IETF membership, which is a large and changing list of
members.
Nested UG:
The National Football League, made up of the AFC and NFC, which
are made up of 3 divisions each.
2.5 Roles 2.5 Roles
CAP defines methods for managing [iCAL] objects on a Calendar Store CAP defines methods for managing [iCAL] objects in a Calendar Store
and exchanging [iCAL] objects for the purposes of group calendaring and exchanging [iCAL] objects for the purposes of group calendaring
and scheduling between "Calendar Users" (CUs) or "User Groups" (UGs). and scheduling between "Calendar Users" (CUs) or "User Groups" (UGs).
There are two distinct roles taken on by CUs in CAP. The CU who There are two distinct roles taken on by CUs in CAP. The CU who
creates an initial event or to-do and invites other CUs or UGs as creates an initial event or to-do and invites other CUs as attendees
attendees takes on the role of "Organizer". The CUs or UGs asked to takes on the role of "Organizer". The CUs asked to participate in
participate in the group event or to-do take on the role of the event or to-do take on the role of "Attendee". Note that "role"
"Attendee". Note that "role" is also a descriptive parameter to the is also a descriptive parameter to the "ATTENDEE" property. Its use
"ATTENDEE" property. Its use is to convey descriptive context to an is to convey descriptive context to an "Attendee" such as "chair",
"Attendee" such as "chair", "REQ-PARTICIPANT" or "NON- PARTICIPANT" "REQ-PARTICIPANT" or "NON-PARTICIPANT" and has nothing to do with the
and has nothing to do with the scheduling workflow. scheduling workflow.
2.6 Calendar Addresses 2.6 Calendar Addresses
Calendar addresses are URIs that are modeled after URLs [URL]. CAP Calendar addresses are URIs that are modeled after URLs [URL]. CAP
uses the following forms of URI. uses the following forms of URI.
[[<scheme>]://<csid>[:<port>]/]<relativeCALID> [[<scheme>]://<csid>[:<port>]/]<relativeCALID>
where: where:
<scheme> is "cap", the protocol described in this memo. <scheme> is "cap", the protocol described in this memo.
<csid> is the Calendar Store ID. It is the network address of the <csid> is the Calendar Store ID. It is the network address of the
computer on which the CAP server is running. computer on which the CAP server is running.
<port> is optional. Its default value is 5229. The port must be <port> is optional. The port must be present in the URL if the
present in the URL if the CAP server does not listen on this CAP server does not listen on the default port number.
default port of 5229.
<relativeCALID> is an identifier that uniquely identifies the <relativeCALID> is an identifier that uniquely identifies the
calendar on a particular calendar store. There is no implied calendar on a particular calendar store. There is no implied
structure in a Relative CALID. It is an arbitrary string of structure in a Relative CALID. It is an arbitrary string of
printable 7 bit ASCII characters. It may refer to the calendar of printable 7 bit ASCII characters. It may refer to the calendar of
a user or of a resource such as a conference room. It MUST be a user or of a resource such as a conference room. It MUST be
unique within the calendar store. It is recommended that the unique within the calendar store. It is recommended that the
Relative CALID be globally unique. Relative CALID be globally unique.
If the <scheme> and <csid> are present the calendar address is said If the <scheme> and <csid> are present the calendar address is said
skipping to change at page 27, line 27 skipping to change at page 20, line 4
is required when the <csid> of the target calendar address differs is required when the <csid> of the target calendar address differs
from that of the CAP server receiving the command. from that of the CAP server receiving the command.
Examples of CAP URIs: Examples of CAP URIs:
cap://calendar.example.com/user1 cap://calendar.example.com/user1
://calendar.example.com/user1 ://calendar.example.com/user1
user1 user1
cap://calendar.example.com/conferenceRoomA cap://calendar.example.com/conferenceRoomA
cap://calendar.example.com/89798-098-zytytasd cap://calendar.example.com/89798-098-zytytasd
For a user currently authenticated to a CAP server on For a user currently authenticated to a CAP server on
calendar.example.com, the first three addresses refer to the same calendar.example.com, the first three addresses refer to the same
calendar. calendar.
2.7 Extensions to iCalendar 2.7 Extensions to iCalendar
In mapping the CAP command set, query feature, and access rights onto In mapping the calendar query feature, and access rights onto the
the iCalendar format, several extended iCalendar methods and iCalendar format, several extended iCalendar properties and
components are defined by this memo. components are defined by this memo.
The search function is specified with the new iCalendar QUERY The search operation makes use of a new component, called VQUERY.
method. The QUERY method makes use of a new component, called The component consists of a set of new properties: QUERY, EXPAND and
VQUERY, that contains the search filter. The component consists QUERYNAME, that define a search filter. VQUERY is used by the
of a set of new properties: EXPAND, MAXSIZE, MAXRESULTS, QUERY and following CAP commands: "search", "move", "modify" and "delete".
QUERYNAME, that define the search filter. Note that QUERY simply
is the filter that is used by the CS to select the data used in
METHOD:READ, METHOD:CREATE, METHOD:MODIFY, METHOD:DELETE, any
other METHOD that is defined to use a QUERY filter.
Access control is specified the the new iCalendar VCAR component.
The iCalendar METHOD property format has been updated with new
values.
A new iCalendar component, VCOMMAND, has been added. VCOMMANDs
are needed to specify CAP commands.
VCAP is a new container for data that is transmitted as part of a
VCOMMAND
TARGET is a new property within the VCOMMAND component. It Access rights are specified in the new iCalendar VCAR component.
indicates the calendars to which the command applies
CMDID is a Command ID that is used in a VCOMMAND to uniquely Calendar are specified by the new VAGENDA component.
identify a command. Responses to a VCOMMAND will contain the
same CMDID.
2.8 Relationship of RFC 2446 (ITIP) to CAP 2.8 Relationship of RFC 2446 (ITIP) to CAP
[iTIP] describes scheduling methods which result in indirect [iTIP] describes scheduling methods which result in indirect
manipulation of calendar components. CAP methods provide direct manipulation of calendar components. In CAP, the "schedule" command
manipulation of calendar components. In the CAP calendar store is used to submit scheduling requests. Other CAP commands such as
model, scheduling messages are conceptually kept separate from other "create", "delete", "modify" and "move" provide direct manipulation
calendar components. This is modeled with the VSCHEDULE queue. Note of calendar components. In the CAP calendar store model, scheduling
that this is a conceptual model, the actual storage details are left messages are conceptually kept separate from other calendar
to implementations. The model is shown pictorially as follows: components. This is modeled with the VSCHEDULE set. Note that this
is a conceptual model, the actual storage details are left to
+-----------------VCALENDAR-------------------+ implementations.
| |
| +-----------+ +-------VSCHEDULE---------+ |
| | VEVENTs | | PUBLISH messages | |
| | VTODOs | | REQUEST messages | |
| | VJOURNALs | | REPLY messages | |
| | | | ADD messages | |
| | | | CANCEL messages | |
| | | | REFRESH messages | |
| | | | COUNTER messages | |
| | | | DECLINECOUNTER messages | |
| +-----------+ +-------------------------+ |
+---------------------------------------------+
The METHOD is saved along with components. Scheduled components When scheduling is used, the METHOD is saved along with components.
become booked components when the METHOD changes from an ITIP method A scheduled component becomes a booked component when its METHOD
to the CAP storage method CREATE. For example, a component whose property is removed. For example, a component whose METHOD is
METHOD is "REQUEST" is scheduled. The component becomes booked when "REQUEST" is scheduled. The component becomes booked when the METHOD
the METHOD is changed to "CREATED". is removed.
Several scheduled entries can be in the CS for the same UID. They Several scheduled entries can be in the CS for the same UID. They
are consolidated when booked. Or they are removed from the CS. are consolidated when booked, or they are removed from the CS.
For example, if you were on vacation, you could have a REQUEST to For example, if you were on vacation, you could have a REQUEST to
attend a meeting and several updates to that meeting. Your CUA would attend a meeting and several updates to that meeting. Your CUA would
have to READ them out of the CS using CAP, process them, determine have to "search" them out of the CS using CAP, process them,
what the final state of the object from a possible combination of determine what the final state of the object from a possible
user input and programmed logic. Then the CUA would instruct the CS combination of user input and programmed logic. Then the CUA would
to CREATE a new booked entry or MODIFY an existing entry. Followed instruct the CS to "create" a new booked entry or "modify" an
by a DELETE of all of these now old scheduling requests in the CS. existing entry. Finally, the CUA can do a "delete" of all of these
See [iTIP] for details on resolving multiple [iTIP] scheduling now old scheduling requests in the CS. See [iTIP] for details on
entries. resolving multiple [iTIP] scheduling entries.
3. State Diagram
This section describes the states of the transport connection between
a CUA and a CS. The state diagram is shown below. State names are
shown with first letter capitalized. Commands used to switch between
states are shown next to an arrow connecting the states. The
commands are listed in all capital letters. A condition that causes
a state to change is shown in lower case letters.
STARTTLS /
CAPABILITY
+-------+
| | +---------------+
| +-----------+ AUTHENTICATE | |
+-->| Connected |-------------->| Authenticated |
+-----------+ | |
| +---------------+
| |
| | +-----+
| V | |STARTTLS /
| +---------------+ |IDENTIFY
| | |<-+
| | Identified |<-----+
| +--------| | |
| | +---------------+ |
| | | command|
V |DISCONNECT | completes|
+--------------+ | | |
| Disconnected |<--+ | |
+--------------+ |SENDDATA | ABORT
A | |
| V |
| DISCONNECT +---------------+ |
+--------------------| Receive |------+
| |<--+
+---------------+ |
| |
+----+
CONTINUE
The connection begins the Connected state when a CUA connects to a
CAP server. The capabilities of the CS are reported in the response
from the CS. From this state, the CUA can issue the DISCONNECT
command to terminate the connection, the CAPABILITY, STARTTLS, or
AUTHENTICATE commands. One use of the CAPABILITY command at this
stage is to determine the supported authentication mechanisms
supported by the server. Once the STARTTLS command has been
successfully executed from either the Connected or Authenticated
state, it must not be executed again.
If an AUTHENTICATE command is successful, the connection enters the
Authenticated state and then immediately goes to the IDENTIFIED
state. While in the Identified state, the CALIDEXPAND and UPNEXPAND
commands can be executed. From here the CUA can issue the CAPABILITY
command. The capabilities offered by the server in the Authenticated
state may be different than those in the Connected state to allow for
the user's realm to be used to grant or deny features. The CUA can
also use the IDENTIFY command to change the identity of the user
subject to access control. The connection remains in the Identified
state after the CAPABILITY command completes. The CUA can issue the
DISCONNECT command to terminate the connection. The SENDDATA command
can be used to send a request to read, write, modify, or delete data
on the server.
After the SENDDATA command has been issued the connection enters the
Receive state while the CUA awaits and reads a server reply.
Normally, the server handles the command, sends a reply which is read
by the CUA and the connection returns to the Authenticated state.
The CUA may have issued the SENDATA command with a maximum latency
time. This informs the server that the CUA expects a response within
the maximum latency time, even if the command was not completed.
When the server is unable to complete the command in the maximum
latency time, it issues an appropriate reply code and waits for the
CUA to tell it how to proceed. If the CUA issues a CONTINUE command
the server continues processing the command and the connection
remains in the Receive state. If the CUA issues the ABORT command
the server need not process the command any further and the
connection returns to the Identified state. The DISCONNECT command
can also be issued from the Receive state.
4. Protocol Framework
4.1 CAP Application Layer 3. Protocol Framework
The CAP application layer is used for the manipulation of the CAP uses the BEEP application protocol kernel mapped onto TCP (refer
calendar store. Commands and responses are transmitted between the to [BEEP] and [BEEPTCP] for more information). The default port that
CUA and CS inside "VCAP" wrappers. Commands are specified as the the Calendar Service listens for connections on is port 5229.
value of a "METHOD" property, and responses are specified as the
value of a "REQUEST-STATUS" property. An optional "CMDID" may be
used to uniquely identify commands.
4.2 CAP Transfer Protocol 3.1 BEEP Exchange Styles
The CAP transfer protocol defines the format of data transmitted [BEEP] defines three styles of message exchange:
between a CUA and the CS.
CAP transfer protocol commands are transmitted using the underlying MSG/ANS,ANS,...,NUL: for one-to-many exchanges.
transport. The transport used is a TCP/IP socket connection between
the CUA and the CS. The default port that the CS listens for
connections on is port 5229.
Messages sent between the CUA and CS are formatted as a command MSG/RPY: for one-to-one exchanges.
followed by any associated data:
<command> [<command data>] MSG/ERR: for requests the cannot be processed due to an error.
Server responses consist of a response code and any parameters: A CAP request, targeted at more than one containers, MUST use a one-
to-many exchange, with a distinct answer associated with each target.
CAP request targeted at a single container MAY use a one-to-one
exchange or a one-to-many exchange. "MSG/ERR" MAY only be used when
an error condition prevents the execution of the request on all the
targeted calendars.
<transfer-level response-code> [response-args] [; debug-text ] 3.2 Use of XML, MIME and iCalendar
<CRLF>.<CRLF>
[<application-data>]
<CRLF>.<CRLF>
The response-args are defined in Section 8. The debug-text is human- Each BEEP payload exchanged via CAP consists of an XML document and
readable information for protocol debugging and is optional and is possibly an arbitrary MIME content. The XML document defines the
only used to aid developers writing CSs and CUAs. The debug-text action to be performed. When needed, the calendaring related data is
MUST not be depended on by CUAs in normal interactions with a CS. included in a related MIME part containing an iCalendar object.
The optional application-data begins on the next line. If only an XML document is sent in the BEEP payload, then the mapping
to a BEEP payload is straight-forward, e.g.,
The response is terminated with the second <CRLF> "." <CRLF> C: MSG 1 2 . 432 62
sequence. Any <CRLF> "." sequences which appear in the transmitted C: Content-Type: application/beep+xml
data must be quoted by placing an additional "." between the <CRLF> C:
and the ".". For example, the following sequences of characters in C: <generate-uid num=10/>
the application data: C: END
. Otherwise, arbitrary MIME content is included in the BEEP payload by
..2 using a "multipart/related" (see [RFC 3087]), identified using a
...3 "cid" URL (see [RFC 2392]), and the XML control document occurs as
the starting body part, e.g.,
are quoted as follows: C: MSG 1 3 . 1023 951
C: Content-Type: multipart/related; boundary="boundary-asdf123";
C: start="<1@cal.example.com>";
C: type="application/beep+xml"
C:
C: --boundary-asdf123
C: Content-Type: application/beep+xml
C: Content-ID: <1@cal.example.com>
C:
C:
C: <schedule id="abcd12346">
C: <target relcalid="john-relcalid"/>
C: <target relcalid="bob-relcalid"/>
C: <data content="cid:2@cal.example.com"/>
C: </schedule>
C: --boundary-asdf123
C: Content-Type: text/calendar
C: Content-ID: 2@cal.example.com
C:
C: BEGIN:VCALENDAR
C: METHOD:REQUEST
C: BEGIN:VEVENT
C: UID:abcd12345
C: ORGAGNIZER:cap://cal.example.com/mary-relcalid
C: ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.example.com/mary-relcalid
C: ATTENDEE;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:cap://cal.example.com/john-relcalid
C: ATTENDEE;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:cap://cal.example.com/bob-relcalid
C: DTSTART:20010920T180000Z
C: DTEND:20010920T190000Z
C: SUMMARY:Mary invites John and Robert
C: END:VEVENT
C: END:VCALENDAR
C: --boundary-asdf123--
C: END
.. The MIME content-type "application/beep+xml" is defined in Section
...2 6.4 of [BEEP].
....3
4.3 Pipelining Commands 3.3 Bounded Latency
If the CS returns a PIPELINE number greater then one (1) as a A CUA can associate a maximum latency time to a command with the
result of a CAPABILITY command then the CUA can send up to PIPELINE "max-time" element. If the CS is unable to complete the request in
VCAP (each with a unique CMDID/VCOMMAND) without waiting for the CS the specified amount of time, then the server sends a "timeout"
to reply. request to which the CUA MUST respond with a "abort" or "continue"
reply.
It is unspecified what happens of the CUA exceedes the CS limit. Upon receiving an "abort" reply, the CS MUST terminate the command in
progress and return a request-status code 2.0.3. When receiving a
"continue" reply the server resumes its work in progress. Note that
a new latency time MAY be included in a "continue" reply.
4.4 Auto-logout Timer The timeout element takes two arguments "latency" and "action". The
"latency" argument MUST be set to the maximum latency time in
seconds. The "action" argument accepts the following values: "ask"
and "abort". If the maximum latency time is exceeded and the
"action" argument is set to "ask", then CS MUST send a "timeout"
message to inform the CUA, otherwise if the argument "action" is set
to "abort" the CS can directly terminate the request and return a
request-status code 2.0.3.
If a server has an inactivity auto-logout timer, that timer MUST be Example:
of at least 15 minutes duration if there is no value of
AUTOLOGOUTTIME returned in the CS CAPABILITY reply. The receipt of
ANY command from the client during that interval MAY reset the auto-
logout timer, subject to CS administrators policy. A CUA may be
discouraged from attempts to do useless things only to keep the
connection alive.
A CS MAY have different AUTOLOGOUTTIME values depending on the UPN or In this example bill@cal.example.com attempts to read a calendar but
the realm of the UPN. the latency time he supplies is not sufficient for the server to
complete the command.
When a timeout occurs, the server drops the connection to the CUA. C: MSG 1 4 . 2043 680
C: Content-Type: multipart/related; boundary="boundary-zxy123";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary-zxy123
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <search id="xyz12346">
C: <max-time latency=3 action=ask/>
C: <select>
C: <source relcalid='opaqueid101'/>
C: <data content="cid:2@cal.example.com"/>
C: </select>
C: </search>
C: --boundary-zxy123
C: Content-Type: text/calendar
C: Content-ID: 2@cal.example.com
C:
C: BEGIN:VCALENDAR
C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID FROM VEVENT
C: WHERE DTEND >= '19990714T080000Z' AND
C: DTSTART <= '19990715T080000Z'
C: END:VQUERY
C: END:VCALENDAR
C: --boundary-zxy123--
C: END
# After 3 seconds
S: MSG 1 2 . 102 64
S: Content-Type: application/beep+xml
S:
S: <timeout id="xyz12346"/>
S: END
4.5 Bounded Latency If Bill wants to continue and give the server more time he would
issue a "continue" reply:
CAP is designed so that the CUA can either obtain an immediate C: RPY 1 2 . 166 113
response from a request or discover within a specified amount of time C: Content-Type: application/beep+xml
that the request could not be completed in the requested amount of C:
time. When the CUA initiates a command that the server cannot C: <continue id="xyz12346">
complete within the specified latency time, the server returns an C: <max-time latency=3 action=ask/>
appropriate response code. The CUA then issues either a CONTINUE or C: </continue>
ABORT command. The ABORT command immediately terminates the command C: END
in progress identified by CMDID and the connection returns to the
Authenticated state. The CONTINUE command instructs the server to
continue processing the command identified by the CMDID.
4.6 Data Elements If Bill wants to abort the command and not wait any further he would
issue an "abort" reply:
The data elements for CAP are [MIME] encapsulated iCalendar objects. C: RPY 1 2 . 166 62
C: Content-Type: application/beep+xml
C:
C: <abort id="xyz12346"/>
C: END
S: RPY 1 4 . 2723 114
S:
S: <result>
S: <request-status code="2.0.3">
S: Request Aborted by the CUA.
S: </request-status>
S: </result>
S: END
5. Formal Command Syntax 4. Formal Command Syntax
5.1 Searching and Filtering 4.1 Searching and Filtering
This section describes CAP's selecting and filtering entities within This section describes CAP's selecting and filtering entities within
a calendar store. It is based on the Standard Query Language (SQL) a calendar store. It is based on the Standard Query Language (SQL)
defined in [SQL]. defined in [SQL].
5.1.1 Grammar For Search Mechanism 4.1.1 Grammar For Search Mechanism
search = "BEGIN:VQUERY" CRLF search = "BEGIN:VQUERY" CRLF
[expand] [maxresults] [maxsize] querycomp [expand] querycomp
"END:VQUERY" CRLF "END:VQUERY" CRLF
expand = "EXPAND" ":" ( "TRUE" / "FALSE") expand = "EXPAND" ":" ( "TRUE" / "FALSE") CRLF
# the default is EXPAND:FALSE # the default is EXPAND:FALSE
comp-name = "VEVENT" / "VTODO" / "VJOURNAL" comp-name = "VEVENT" / "VTODO" / "VJOURNAL"
/ "VTIMEZONE" / "VALARM" / "VFREEBUSY" / "VTIMEZONE" / "VALARM" / "VFREEBUSY" / "VAGENDA"
/ "VCAR" / iana-name / x-name / "VCAR" / iana-name / x-name
maxresults = "MAXRESULTS" ":" integer
maxsize = "MAXSIZE" ":" integer
querycomp = ( query ) / ( queryname query ) / queryname querycomp = ( query ) / ( queryname query ) / queryname
queryname = "QUERYNAME:" text queryname = "QUERYNAME:" text
query = "QUERY:" ( query-min / query-92 ) query = "QUERY:" ( query-min / query-92 )
# #
# NOTE: query-min MUST be implemented in CSs. # NOTE: query-min MUST be implemented in CSs.
# #
# query-92 is ONLY used if CAPABILITY returns SQL-92 # query-92 is ONLY used if CAPABILITY returns SQL-92
# as the QUERYLEVEL value or if QUERYLEVEL is not # as the QUERYLEVEL value or if QUERYLEVEL is not
# specified. # specified.
# #
query-min = capselect-min capfrom-min capwhere-min query-min = capselect-min
capselect-min = "SELECT" capmin-cols "FROM" capmin-comps capselect-min = "SELECT" capmin-cols "FROM" capmin-comps
"WHERE" capmin-cmp "WHERE" capmin-cmp
capmin-col = # Any property name found in any of the capmin-col = # Any property name found in any of the
components. components.
capmin-cols = ( capmin-col / capmin-col "," capmin-cols = ( capmin-col / capmin-col ","
capmin-cols ) capmin-cols )
capmin-comps = ( comp-name / comp-name "," capmin-comps = ( comp-name / comp-name ","
compmin-comps ) compmin-comps )
capmin-cmp = ( colname cmpmin-oper colvalue capmin-cmp = ( colname capmin-cmp-rhs
/ colname cmpmin-oper colvalue / colname capmin-cmp-rhs
capmin-logical capmin-cmp ) capmin-logical capmin-cmp )
capmin-cmp-rhs = ( capmin-oper colvalue
/ "IS" ["NOT"] "NULL" )
colname = ( # Any valid component property name. colname = ( # Any valid component property name.
/ "*" ) / "*" )
cmpmin-oper = ( " = " / " != " / " < " / " > " / " <= " cmpmin-oper = ( " = " / " != " / " < " / " > " / " <= "
/ " >= " ) / " >= " )
capmin-logical = ( " AND " / " OR " ) capmin-logical = ( " AND " / " OR " )
query-92 = capselect-92 capfrom-92 capwhere-92 query-92 = capselect-92 capfrom-92 capwhere-92
caporderby-92 caporderby-92
skipping to change at page 36, line 34 skipping to change at page 27, line 37
capfrom-92 = # Like capmin-comps except embedded spaces capfrom-92 = # Like capmin-comps except embedded spaces
# are allowed between commas - per [SQL]. # are allowed between commas - per [SQL].
capwhere-92 = # Any valid [SQL] string that goes into a capwhere-92 = # Any valid [SQL] string that goes into a
# WHERE clause. # WHERE clause.
caporderby-92 = # Any valid [SQL] string that goes into a caporderby-92 = # Any valid [SQL] string that goes into a
# ORDERBY clause. # ORDERBY clause.
5.1.2 SQL-MIN notes 4.1.2 SQL-MIN notes
(1) No inlined spaces are allowed if not in the grammar above. (1) No inlined spaces are allowed if not in the grammar above.
(2) Note that cmpmin-oper and capmin-logical elements are (2) Note that cmpmin-oper and capmin-logical elements are
surrounded by exactly one space. surrounded by exactly one space.
Use 'VEVENT,VTODO', not 'VEVENT, VTODO' Use 'VEVENT,VTODO', not 'VEVENT, VTODO'
Use 'DTSTART <= 20000605T131313Z', not Use 'DTSTART <= 20000605T131313Z', not
'DTSTART<= 20000605T131313Z'. 'DTSTART<= 20000605T131313Z'.
Use ' AND ' and ' OR ', not 'AND' and not 'OR'. Use ' AND ' and ' OR ', not 'AND' and not 'OR'.
skipping to change at page 37, line 10 skipping to change at page 28, line 21
columns are supplied in the command. columns are supplied in the command.
(4) The CS MUST sort at least the first column.The CS MAY sort (4) The CS MUST sort at least the first column.The CS MAY sort
additional columns. additional columns.
(5) If EXPAND=FALSE and if colname is "*" sorting will be by the (5) If EXPAND=FALSE and if colname is "*" sorting will be by the
DTSTART value ascending. If EXPAND=TRUE and if colname is "*" DTSTART value ascending. If EXPAND=TRUE and if colname is "*"
sorting will be by the RECURRENCE-ID value ascending. sorting will be by the RECURRENCE-ID value ascending.
If colname is "*" and capmin-coms is VALARM only then sorting will If colname is "*" and capmin-coms is VALARM only then sorting will
be by TRIGGER time in GMT ascending. be by TRIGGER time in UTC ascending.
(6) SQL-MIN MUST be implemented. (6) SQL-MIN MUST be implemented.
5.1.3 SQL-92 notes 4.1.3 Querying Experminental Properties
(1) Although this memo specifies that any [SQL] query can be used,
some of the [SQL] grammar is optional and therefore is considered
optional in CSs advertising an SQL-92 implementation with CAPABILITY.
(2) A CS implementation MAY implement SQL-92. If a CS does not
implement SQL-92 then it MUST advertise SQL-MIN in the capability
reply.
5.1.4 Example, Query by UID 4.1.4 Example, Query by UID
This example would select the entire contents of uid123 and not The following example would match the entire content of the component
expand any multiple instances of the component. If the CUA does not with the UID property equal to "uid123" and not expand any multiple
know if 'uid123' was a VEVENT, VTODO, VJOURNAL, or other component, instances of the component. If the CUA does not know if "uid123" was
then all components that the CUA supports MUST be supplied on the a VEVENT, VTODO, VJOURNAL, or any other component, then all
QUERY property. This example assumes the CUA only supports VTODO and components that the CUA supports MUST be supplied on the QUERY
property. This example assumes the CUA only supports VTODO and
VEVENT. VEVENT.
If the results were empty it could also mean that 'uid123' was a If the results were empty it could also mean that "uid123" was a
property in a component other than a VTODO or VEVENT. property in a component other than a VTODO or VEVENT.
BEGIN:VQUERY BEGIN:VQUERY
QUERY:SELECT * FROM VEVENT,VTODO WHERE UID = 'uid123' QUERY:SELECT * FROM VEVENT,VTODO WHERE UID = 'uid123'
END:VQUERY END:VQUERY
This example would select the entire contents of uid123 and would The following example would match the entire content of the component
expand any instances of the component after applying any recurrence with the UID property equal to "uid123" and would expand any
rules. This query could select multiple instances of components each instances of the component after applying any recurrence rules. This
with the same UID. Each instance would have a unique RECURRENCE-ID query could select multiple instances of components each with the
of the expanded component. same UID. Each instance would have a unique RECURRENCE-ID of the
expanded component.
BEGIN:VQUERY BEGIN:VQUERY
EXPAND:TRUE EXPAND:TRUE
QUERY:SELECT * FROM VEVENT,VTODO WHERE UID = 'uid123' QUERY:SELECT * FROM VEVENT,VTODO WHERE UID = 'uid123'
END:VQUERY END:VQUERY
5.1.5 Query by Date-Time range 4.1.5 Query by Date-Time range
This query selects the entire contents of every booked VEVENT that This query selects the entire content of every booked VEVENT that has
has an instance less than or equal to July 31st, 2000 23:59:59 Z and an instance greater than or equal to July 1st, 2000 00:00:00 UTC and
greater than or equal to July 1st, 2000 00:00:00 Z less than or equal to July 31st, 2000 23:59:59 UTC
BEGIN:VQUERY BEGIN:VQUERY
EXPAND:TRUE EXPAND:TRUE
QUERY:SELECT * FROM VEVENT QUERY:SELECT * FROM VEVENT
WHERE RECURRENCE-ID >= '20000801T000000Z' WHERE RECURRENCE-ID >= '20000801T000000Z'
AND RECURRENCE-ID <= '20000831T235959Z' AND RECURRENCE-ID <= '20000831T235959Z'
AND METHOD = 'CREATE' AND METHOD = 'CREATE'
END:VQUERY END:VQUERY
5.1.6 Query for all Non-Booked Entries 4.1.6 Query for all Non-Booked Entries
This example selects the entire contents of all scheduling (non- The following example selects the entire content of all scheduling
booked) VEVENTS in the CS. The default for EXPAND is FALSE, so the VEVENTS in the CS. The default for EXPAND is FALSE, so the
recurrence rules will not be expanded. recurrence rules will not be expanded.
BEGIN:VQUERY BEGIN:VQUERY
QUERY:SELECT * FROM VEVENT,VTODO WHERE METHOD != 'CREATE' QUERY:SELECT * FROM VEVENT,VTODO WHERE METHOD IS NOT NULL
END:VQUERY END:VQUERY
The following example fetches the UIDs of all non-booked VEVENTs and The following example fetches the UIDs of all non-booked VEVENTs and
VTODOs. VTODOs.
BEGIN:VQUERY BEGIN:VQUERY
QUERY:SELECT UID FROM VEVENT,VTODO WHERE METHOD != 'CREATE' QUERY:SELECT UID FROM VEVENT,VTODO WHERE METHOD IS NOT NULL
END:VQUERY END:VQUERY
5.1.7 Query with Subset of Properties by Date/Time 4.1.7 Query with Subset of Properties by Date/Time
This MUST implement is similar to the one above, except only the In this example only the named properties will be selected and all
named properties will be selected and all booked and non- booked booked and non-booked components will be selected that have a DTSTART
components will be selected that have a DTSTART from Feb 1st to Feb from February 1st to February 10th 2000.
10th.
BEGIN:VQUERY BEGIN:VQUERY
QUERY:SELECT UID,DTSTART,DESCRIPTION,SUMMARY FROM VEVENT QUERY:SELECT UID,DTSTART,DESCRIPTION,SUMMARY FROM VEVENT
WHERE DTSTART >= '20000201T000000Z' WHERE DTSTART >= '20000201T000000Z'
AND DTSTART <= '20000210T235959Z' AND DTSTART <= '20000210T235959Z'
END:VQUERY END:VQUERY
5.1.8 Components With Alarms In A Range 4.1.8 Components With Alarms In A Range
This example fetches all components with an alarm that triggers This example fetches all components with an alarm that triggers
within the specified time range. In this case only the UID, SUMMARY, within the specified time range. In this case only the UID, SUMMARY,
and DESCRIPTION will be selected for all booked VEVENTS that have an and DESCRIPTION will be selected for all booked VEVENTS that have an
alarm between the two date-times. alarm between the two date-times.
BEGIN:VQUERY BEGIN:VQUERY
EXPAND:TRUE EXPAND:TRUE
QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT
WHERE VALARM.TRIGGER >= '20000101T030405Z' WHERE VALARM.TRIGGER >= '20000101T030405Z'
AND VALARM.TRIGGER <= '20001231T235959Z' AND VALARM.TRIGGER <= '20001231T235959Z'
AND METHOD = 'CREATE' AND METHOD = 'CREATE'
END:VQUERY END:VQUERY
6. Access Rights 5. Access Rights
Access rights within CAP are specified with the "VCAR" calendar Access rights within CAP are specified with the "VCAR" calendar
component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID" component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID"
component properties. component properties.
Individual calendar access rights MUST be specifically granted to an
authenticated calendar user (i.e., UPN); all rights are denied unless
specifically granted.
Properties within a VCAR must be evaluated in the order provided. Properties within a VCAR must be evaluated in the order provided.
6.1 VCAR Inheritance 5.1 VCAR Inheritance
Calendar access rights specified in a calendar store are inherited as Calendar access rights specified in a calendar store are inherited as
default calendar access rights for any calendar in the parent default calendar access rights for any calendar in the parent
calendar store. Likewise, any calendar access rights specified in a calendar store. Likewise, any calendar access rights specified in a
root calendar are inherited as default calendar access rights for any root calendar are inherited as default calendar access rights for any
sub- calendar to the root calendar. By implication, calendar access sub-calendar to the root calendar. Furthermore, calendar access
rights specified in a sub-calendar are inherited as default calendar rights specified in a sub-calendar are inherited as default calendar
access rights for any calendars that are hierarchically below the access rights for any calendars that are hierarchically below the
sub- calendar. sub- calendar.
Calendar access rights specified in a calendar override any default Calendar access rights specified in a calendar override any default
calendar access rights. Calendar access rights specified within a calendar access rights. Calendar access rights specified within a
sub-calendar override any default calendar access rights. sub-calendar override any default calendar access rights.
6.2 Access Control and NOCONFLICT 5.2 Access Control and NOCONFLICT
The TRANSP property can take on values (TRANSPARENT- NOCONFLICT, The TRANSP property can take on values (TRANSPARENT- NOCONFLICT,
OPAQUE-NOCONFLICT) that prohibit other events from overlapping it. OPAQUE-NOCONFLICT) that prohibit other events from overlapping it.
This setting overrides access While access control may allow a UPN to This setting overrides access. The ALLOW-CONFLICT Calendar or
store an event on a particular calendar. , the CONFLICTS Calendar or component setting may also prevent overlap, returning an error code
component setting may prevent it, returning an error code "6.3" "6.3"
7. Commands and Responses 6. Commands and Responses
CAP commands and responses are described in this section. CAP commands and responses are described in this section.
Command arguments, identified by "Arguments:" in the command As mentioned in Section 3.2, CAP commands are defined by XML
descriptions below, are described by function, not by syntax. The documents. The syntax of the commands is defined in Section 9, this
precise syntax of command arguments is described in the Formal Syntax section describes their semantic.
section.
Some commands cause specific server data to be returned; these are
identified by "Data:" in the command descriptions below. See the
response descriptions in the Responses section for information on
these responses, and the Formal Syntax section for the precise syntax
of these responses.
The "Result:" in the command description refers to the possible
status responses to a command, and any special interpretation of
these status responses.
Commands have the general form:
<command> [arguments...]
where <command> is a command listed in the table above. A command
MAY have arguments. Arguments are defined in the detailed command
definitions below.
Responses to commands have the following general form:
responseCode [sep transportDescr sep
[applicationDescr]]
CRLF "." CRLF
In the examples below, lines preceded with "S:" refer to the sender
and lines preceded with "R:" refer to the receiver. Lines in which
the first non-whitespace character is a "#" are editorial comments
and are not part of the protocol.
7.1 Transfer Protocol Commands
7.1.1 Initial Connection
Arguments: none
Data: none
Result: 2.0 - success. 8.1 - server too busy
Upon session startup, the server sends a response of 2.0 to indicate
that it is ready to receive commands. A response of 8.1 indicates
that the server is too busy to accept the connection. In addition,
the general capabilities of the CS are reported in the response from
the CS. These capabilities may be different than those reported in
the authenticated state.
7.1.2 ABORT Command
Arguments: [CMDID]
Data: none
Result: 2.0 - success 2.2 - no command is in progress
The ABORT command is issued by the CUA to stop a command. A common
usage could be to ABORT a command whose latency time has been
exceeded. When the latency time is specified on the SENDATA command,
the CS must issue a reply to the CUA within the specified time. It
may be a reply code indicating that the CS has not yet processed the
request. The CUA must then tell the server whether to continue or
abort.
The CUA can issue the ABORT command at any time after the SENDATA
command has been completed but before receiving a reply.
If CMDID is supplied then the command identified by CMDID is aborted.
If CMDID is not supplied then the fist command that is still pending
is aborted.
7.1.3 AUTHENTICATE Command
Arguments: <SASL mechanism name> [<initial data>]
Data: continuation data may be requested
Result:
2.0 - Authenticate completed, now in authenticated state.
6.0 - Failed authentication. 6.1 - Authorization identity
refused.
6.2 - Sender aborted authentication, authentication exchange
cancelled.
6.3 - Unsupported Authentication Mechanism.
6.4 - Temporary failure (back end authentication server down).
6.5 - Authentication exchange cancelled.
6.6 - Authentication mechanism too weak.
6.7 - Encryption required.
6.8 - Pass phrase expired. The pass phrase was correct but
expired. The user will have to contact a pass phrase change
server prior to authenticating.
6.9 - The user is valid but the server does not have an entry in
the authentication database for the requested mechanism (e.g.,
DIGEST- MD5). If the user successfully authenticates using a
plain text password, then the back end back end entry will be
updated. Note that if the client chooses to fall back to plain
text password authentication it should enable an encryption layer
or get user-con- firmation that a one-time transition is ac-
ceptable.
6.10 - User account disabled. The user will have to contact the
system administrator to get the account re-enabled.
9.1 - Unexpected command.
The capabilities of the CS in the authenticated state are reported in
the response from the CS. These may be different than the
capabilities in the Connected, but unauthenticated state.
The AUTHENTICATE command is used by the CUA to identify the user to
the CS. CAP supports a number of authentication methods, the SASL
specification for authentication is the preferred method.
If STARTTLS is negotiated prior to the AUTHENTICATE command, the The attributes of a command are described in the "Attributes:"
client MUST discard all information about the CS capabilities fetched section in the command descriptions below. Similarly the "Elements:"
prior to the TLS negotiation. In particular, the value of supported section describes the elements that compose the command. The
SASL Mechanisms MAY be different after TLS has been negotiated. "Response:" section, identifies the responses that may be returned by
the server.
If a SASL security layer is negotiated, the client MUST discard all In the examples below, lines preceded with "S:" refer to the server
information about the CS capabilities fetched prior to SASL. In and lines preceded with "C:" refer to the client. Lines in which the
particular, if the client is configured to support multiple SASL first non-whitespace character is a "#" are editorial comments and
mechanisms, it SHOULD fetch supported SASL Mechanisms both before and are not part of the protocol.
after the SASL security layer is negotiated and verify that the value
has not changed after the SASL security layer was negotiated. This
detects active attacks which remove supported SASL mechanisms from
the supported SASL Mechanisms list.
<initial data> is an optional parameter which can be used for 6.1 Session Commands
mechanisms which require an initial response from the CUA.
The AUTHENTICATE command is followed by an authentication protocol 6.1.1 "generate-uid" Command
exchange, in the form of a series of CS challenges and CUA responses,
per the relevant RFC that describes the specific SASL mechanism being
used.
Cancelling the authentication process during its negotiation is Attributes:
implementation specific and not within scope of the CAP
specification.
If a security layer was negotiated it comes into effect for the CS num: Number of UIDs to generate (1 if omitted).
starting with the first octet transmitted after the CRLF which
follows the 2.0 reply code, and for the CUA starting with the first
octet after the CRLF of its last response in the authentication
exchange. Encrypted data is transmitted as described in SASL.
The service name specified by this protocol's profile of SASL is Response:
"cap". [EDITORS NOTE: this must be registered with IANA, has anyone
done this yet?]
The result of the AUTHENTICATE command includes data indicating the "uid-list"
identity which has been assigned to the session, derived from the
supplied authentication credentials, and/or authorization identifier.
A CAP session does not have an identity until the CUA has issued the
"AUTHENTICATE" command.
The CUA may not issue the "AUTHENTICATE" command multiple times, even The "generate-uid" command returns one or more unique identifiers
if the first attempt was aborted. If a CUA attempts to do this the which MUST be unique on the server's calendar store. It is
CS must terminate the session. recommended that the return values be globally unique ids.
Here is an example of a successful authentication: Example:
C: AUTHENTICATE KERBEROS_V4 C: MSG 1 5 . 2837 60
S: AmFYig== C: Content-Type: application/beep+xml
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT C:
S: or//EoAADZI= C: <generateuid num=5/>
C: DiAF5A4gA+oOIALuBkAAmw== C: END
S: 2.0 S: RPY 1 5 . 2897 328
S: . S: Content-Type: application/beep+xml
S: Content-Type:text/calendar; method=REQUEST;
S: charset=US-ASCII
S: Content-Transfer-Encoding: 7bit
S: S:
S: BEGIN:VCAP S: <uid-list>
S: PRODID:-//ACME/CAPserver//EN S: <uid>20011121T120000Z-12340@cal.example.com</uid>
S: VERSION:2.1 S: <uid>20011121T120000Z-12341@cal.example.com</uid>
S: IDENTITY=bill@example.com S: <uid>20011121T120000Z-12342@cal.example.com</uid>
S: CAPVERSION=1.0 S: <uid>20011121T120000Z-12343@cal.example.com</uid>
S: ITIPVERSION=1.0 S: <uid>20011121T120000Z-12344@cal.example.com</uid>
S: AUTH=KERBEROS_V4 S: </uid-list>
S: AUTH=DIGEST_MD5 S: END
S: CAR=CAR-FULL-1
S: MINDATE=19700101T000000Z
S: MAXDATE=20370201T000000Z
S: END:VCAP
S: .
This example shows a failed authentication:
C: AUTHENTICATE KERBEROS_V4
S: AmFYig==
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
S: .
S: 6.0
S: .
S: .
7.1.3.1 AUTHENTICATE ANONYMOUS
RFC-2245 defines the Anonymous SASL mechanism. This RFC states that
"the mechanism consists of a single message from the client to the
server. The client sends optional trace information in the form of a
human readable string. The trace information should take one of
three forms: an Internet email address, an opaque string which does
not contain the '@' character and can be interpreted by the system
administrator of the client's domain, or nothing. For privacy
reasons, an Internet email address should only be used with
permission from the user."
RFC-2245 goes on to state, "A client which uses the user's correct
email address as trace information without explicit permission may
violate that user's privacy." Information about who accesses an
anonymous CS on a sensitive subject (e.g., AA meeting times and
locations) has strong privacy needs. "Clients should not send the
email address without explicit permission of the user and should
offer the option of supplying no trace token -- thus only exposing
the source IP address and time."
Example of CUA using the Capability command followed by an anonymous
authentication:
C: CAPABILITY
S: 2.0
S:CAPVERSION=1.0
S:AUTH=KERBEROS_V4
S:AUTH=DIGEST_MD5
S:AUTH=ANONYMOUS
S:.
C:AUTHENTICATE ANONYMOUS
S:+
C:c21yaGM=
S:2.0
Subsequent to the initial Anonymous Authentication with a CS, a CUA
will have to provide a UPN for some CAP operations. For anonymous
access the UPN that MUST be used by the CUA is "@", a UPN with a null
username and null realm. The user's normal UPN MUST not be used for
the subsequent CAP operations.
Note that the CS implementation may have internal audit logs that use
the user's asserted UPN as trace information. However, this UPN will
not appear on the wire after the initial SASL anonymous
authentication.
Use of the "@" UPN and wild-carding of UPNs within VCARs are covered
in
Section <forward ref>.
7.1.4 CALIDEXPAND Command
Arguments: CalID
Data: no specific data for this command
Result: 2.0 Successful, and requested data follows
2.1 Permission Denied
2.2 Requested CSID not found
2.3 Result exceeds MAXEXPANDLIST
2.4 Misc. EXPAND error
Return the members of the argument CalID. Successful result yields
one or more Calendars and/or Resource Calendars. More than one C or
RC returned implies that the CalID was a CC.
If the number of items exceeds MAXCALIDEXPAND, then up to
MAXCALIDEXPAND items are returned along with result 2.3.
If the result is 2.4, then as many of the items as possible will be
returned. It is possible that no items will be returned. The 2.4
response may have optional text describing the problem. Any such
text MUST be in the language and charset that is defined by the
calendar store properties LANGUAGE and CHARSET. If calendar store
CHARSET is not set, but the LANGUAGE property is set, then the
error message will be in LANGUAGE in the UTF-8 charset. If calendar
store LANGUAGE property is not set, then the CS MUST NOT return any
text with the results.
Examples:
Example #1: Request lookup of CSID which is a Calendar Collection
C: CALIDEXPAND cap://cal.example.com/calid14
S: 2.0
S: cap://cal.example.com/calid14
S: cap://cal.example.com/calid2
S: cap://cal.example.com/calid5
S: cap://cal.example.com/calid66
S: .
Example #2: Request lookup a CSID which is a Resource Calendar
C: CALIDEXPAND cap://cal.example.com/conf5
S: 2.0
S: cap://cal.example.com/conf5
S: cap://cal.example.com/conf5
S: .
Example #3: Request CSID which exceeds MAXCALIDEXPANDLIST
C: CALIDEXPAND cap://cal.example.com/calid76 6.1.2 "get-capability" Command
S: 2.3 Expansion resulted in too much data
S: cap://cal.example.com/calid76
S: cap://cal.example.com/calid3
S: cap://cal.example.com/calid12
S: cap://cal.example.com/calid21
S: cap://cal.example.com/calid33
S: .
Example #4: CS loses contact with directory server during CALIDEXPAND Attributes:
C: CALIDEXPAND cap://cal.example.com/calid76 None
S: 2.4 Lost contact with directory server
S: cap://cal.example.com/calid76
S: cap://cal.example.com/calid3
S: cap://cal.example.com/calid5
S: .
7.1.5 CAPABILITY Command Elements:
Arguments: none None
Data: none Response:
Result: capabilities as described below "capability"
The CAPABILITY command returns information about the CAP server given The "get-capability" command returns information about the Calendar
the current state of the connection with the client. The values Service given the current state of the connection with the client.
returned may differ depending on whether the connection is in the The values returned may differ depending on current user identify and
Connected or the Authenticated state. The return values may also be the security level of the connection.
different for a secure versus a non-secure connection.
Client implementations SHOULD NOT require any capability name beyond Client implementations SHOULD NOT require any capability element
those defined in this specification, and MAY ignore any non-standard, beyond those defined in this specification, and MAY ignore any non-
experimental capability names. Non-standard experimental capability standard, experimental capability elements. Non-standard
names MUST be prefixed with the text "X-". The prefix SHOULD also experimental capability elements MUST be prefixed with the text "x-".
include a short character vendor identifier For example, "X-FOO- The prefix SHOULD also include a vendor identifier. For example, "x-
BARCAPABILITY", for the non- standard "BARCAPABILITY" capability of foo-barcapability", for the non-standard "barcapability" capability
the implementor "FOO". This command may return different results in of the vendor "foo". It may return different results depending on
the Connected state versus the Authenticated state. It may also the UPN.
return different results depending on the UPN.
Capability Occurs Description Capability Occurs Description
------------------------------------------------------- -------------------------------------------------------
AUTH 1+ The authentication mechanisms cap 1 Container for CAP related elements.
supported. Implementations MUST version 1+ Version(s) of CAP, MUST include at
implement at least least "1.0".
AUTOLOGOUTTIME
0 or 1 An integer value that specifies
the default idle time in seconds
the CS will wait before
disconnecting an idle CUA.If the
CS is busy the CS may adjust down
the auto-logout timer. If not
specified, the value is 15 minutes
(900 seconds). A value of zero (0)
indicates unlimited connect time
is allowed.
CAPVERSION 1 Revision of CAP, MUST include at
least "1.0". Comma separated
values.
ITIPVERSION 0 or 1 Revision of ITIP, MAY be present.
If present, it MUST include at
least "1.0"
CAR 0 or 1 Indicates level of CAR support.
CAR-MIN or CAR-FULL-1. If not
specified the default is
CAR-FULL-1. Implementations
MUST implement CAR-MIN.
Implementations MAY implement
CAR-FULL-1.
QUERYLEVEL 0 or 1 Indicates level of SQL support.
SQL-MIN or SQL-92. If not
specified the default is SQL-92.
Implementations MUST implement
SQL-MIN. Implementations MAY
implement SQL-92.
MAXICALOBJECTSIZE query-level 1+ Indicates level of SQL support.
0 or 1 An integer value that specifies SQL-MIN or SQL-92. MUST include at
The largest ICAL object the server least SQL-MIN.
will accept in bytes. Objects car 1+ Indicates level of CAR support.
larger than this will be rejected. CAR-MIN or CAR-FULL-1. CAR-MIN MUST
A value of zero (0) indicates be present.
unlimited. The default is zero (0)
if not specified.
MAXDATE 0 or 1 The datetime value in GMT beyond date 0 or 1
max 0 or 1 The datetime value in UTC beyond
which the server cannot accept. If which the server cannot accept. If
not specified the default is not specified the default is
99991231T235959Z. 99991231T235959Z.
min 0 or 1 The datetime value prior to which
MAXCALIDEXPANDLIST
0 or 1 An integer value that specifies
the maximum number of CalIDs that
can be returned by the CALIDEXPAND
Command. A value of zero (0)
indicates unlimited which is the
default if not specified.
MAXUPNEXPANDLIST
0 or 1 An integer value that specifies
the maximum number of UPNs that
can be returned by the UPNEXPAND
Command. A value of zero (0)
indicates unlimited which is the
default if not specified.
MINDATE 0 or 1 The datetime value prior to which
the server cannot accept. If not the server cannot accept. If not
specified the default is specified the default is
00000101T000000Z. 00000101T000000Z.
PIPELINE 0 or 1 An integer value that specifies icalendar 1 Container for CAP related elements.
the maximum number of commands a version 1+ Version(s) of iCalendar that is (are) supported.
CUA may send without the CUA max-component-size
waiting for a reply from the CS. 0 or 1 A positive integer value that specifies
If not specified, the default the size of the largest iCalendar object that
value is one (1). A value of zero the server will accept in bytes. Objects
(0)indicates unlimited. larger than this will be rejected.
The absence of this attribute indicates
Example: no limit.
C: CAPABILTIY
S: 2.0
S: .
S: CAPVERSION=1.0
S: ITIPVERSION=1.0
S: AUTH=KERBEROS_V4
S: AUTH=DIGEST_MD5
S: .
7.1.6 CONTINUE Command
Arguments: latency time in seconds (optional)
Data: none
Result: results from the command in progress 2.0.2 - reply pending.
The CONTINUE command is issued by the client in response to a SENDATA
timeout. When a timeout value is specified on the SENDDATA command,
the server must issue a reply to the client within the specified
time. If the latency time has elapsed prior to the server completing
the command it returns a timeout response code. If the client wants
the server to continue processing the command it responds with the
CONTINUE command.
If latencyTime is present, it must be a positive integer that itip 1 Container for iTIP related elements.
specifies the maximum number of seconds the client will wait for the version 1+ Version(s) of ITIP, MUST include at least
next response. If it is omitted, the receiver waits an indefinite "1.0".
period of time for the response.
In this example, the client requests a response from the server every Example:
10 seconds.
C: SENDDATA:10 C: MSG 1 6 . 3225 57
C: Content-Type:text/calendar; method=READ; component=VEVENT C: Content-Type: application/beep+xml
C: C:
C: BEGIN:VCAP C: <get-capability/>
# etc C: END
C: END:VCAP S: RPY 1 6 . 3282 423
C: . S: Content-Type: application/beep+xml
# after 10 seconds...
S: .
S: 2.0.2
S: .
S: .
C: CONTINUE:10
S: 2.0
S: .
S: Content-type:text/calendar;
S: Method=RESPONSE;Component=VCAP;
S: Optinfo=VERSION:2.1
S: S:
S: BEGIN:VCAP S:
S: <capability>
S: <icalendar>
S: <version>2.1</version>
S: <max-component-size>65536</max-component-size>
S: </icalendar>
S: <itip>
S: <version>1.0</version>
S: </itip>
S: <cap>
S: <version>1.0</version>
S: <car>CAR-MIN</car>
S: <query-level>SQL-MIN</query-level>
S: <date>
S: <min>00000101T000000Z</min>
S: <max>99991231T235959Z</max>
S: </date>
S: </cap>
S: </capability>
S: END
S: VERSION:2.1 6.1.3 "identify" Command
S: CALID:cap://cal.example.com/relcal2
# etc.
S: END:VCAP
S: .
7.1.7 DISCONNECT Command Attribute:
Arguments: none upn: The UPN of the new identify to assume.
Data: Element:
Result: 2.0 None
The DISCONNECT command is used by a client to terminate a connection. Response:
It always succeeds.
The CUA MUST wait for the CS 2.0 reply to ensure that TCP/IP (which "result" with one of the following request-status codes:
knows nothing about CAP) can be sure the connection should go away.
This avoids the CS connection being stuck in TCP-WAIT state.
Example: 2.0 Successful.
C: DISCONNECT 6.4 Identity not permitted.
# [EDITORS NOTE: Note: should the client now wait for a response from
the
server
# before disconnecting? ]
S: 2.0
S: .
S: .
S: <drops connection>
C: <drops connection>
7.1.8 IDENTIFY Command The "identify" command allows the CUA to set a new identity to be
used for calendar access.
Arguments: Identity to assume The CS determines through an internal mechanism if the credentials
supplied at authentication permit the assumption of the selected
identity. If they do, the session assumes the new identity,
otherwise a security error is returned.
Data: None 6.1.4 "noop" Command
Result: 2.0 .4 Identity not permitted Arguments:
The "IDENTIFY" command allows the CUA to select a new identity to be None
used for calendar access. This command may only be called in the
Identified State.
The CS determines through an internal mechanism if the credentials Element:
supplied at authentication permit the assumption of the selected the
identity. If they do the session assumes the new identity, otherwise
a security error is returned.
7.1.9 SENDDATA Command None
Arguments: [latencyTime] Response:
Data: a [MIME] encapsulated iCalendar object "result" with the following request-status code:
Result: 2.0.1 - Server will now accept input until <CRLF>.<CRLF> 2.0 successful
is encountered.
The SENDDATA command is used to send calendar requests and commands This command does nothing. It can be sent to the server periodically
to the server. After a response code of 2.0.1 is issued the CUA to request that the CS does not time out the session.
sends a [MIME] encapsulated iCalendar object to the server. The end
of this [MIME] data is signaled by the special sequence <CRLF>.<CRLF>
.
7.1.10 STARTTLS Command [EDITORS NOTE: should an unauthenticated and unidentified client be
able to issue this command?]
Arguments: None [EDITORS NOTE: in view of the integration with BEEP should "noop" be
removed?]
Data: None Example:
Result: 2.0 5 TLS not supported C: MSG 1 7 . 3705 47
C: Content-Type: application/beep+xml
C:
C: <noop/>
C: END
S: RPY 1 7 . 3752 91
S: Content-Type: application/beep+xml
S:
S: <result>
S: <request-status code="2.0"/>
S: </result>
S: END
The "STARTTLS" command is issued by the CUA to indicate to the CS 6.2 Calendaring and Scheduling Commands
that it wishes to negotiate transport level security using [TLS]. If
the CS does not support TLS it returns status code 6.5. If the CS
supports TLS it issues an initial response of 2.0.12 indicating that
the CUA should proceed with TLS negotiation. Once the TLS
negotiation is complete the server returns the response code 2.0.
After issuing the "STARTTLS" command the CUA issues the 6.2.1 Restriction Tables
"AUTHENTICATE" command. The SASL external mechanism may be used if
the CUA wishes to use the authentication id which was used in the TLS
negotiation.
The CUA MUST NOT issue a "STARTTLS" if it has already issued an Calendaring data are sent encapsulated in iCalendar objects (see
"AUTHENTICATE" or "STARTTLS" command in this session. If a CUA does Section 6.2.3.1). The restriction tables listed in the commands
this the CS must terminate the session. below describe the composition of the iCalendar data for these
commands and replies.
The following examples illustrate the use of the "STARTTLS" command: The presence column uses the following values to assert whether a
property is required, is optional and the number of times it may
appear in the iCalendar object. A comment may be provided to further
clarify the presence criteria.
Unsupported TLS: The table below defines the values for the presence column.
C: STARTTLS Presence
S: 6.5 Value Description
--------------------------------------------------------------
1 One instance MUST be present
1+ At least one instance MUST be present
0 Instances of this property MUST NOT be present
0+ Multiple instances MAY be present
0 or 1 Up to 1 instance of this property MAY be present
--------------------------------------------------------------
Supported TLS: While the tables list every component and property, their purpose is
not to define the meaning of the component or property.
C: STARTTLS 6.2.2 Common Attributes
S: 2.0.12
<tls negotiation>
S: 2.0
S: . 6.2.2.1 "id" Attribute
S: .
7.1.11 UPNEXPAND Method The "id" attribute is an optional identifier for the command. When
specified, the CS will include this attribute in all the related
messages it returns to the client.
Arguments: UPN The "id" attribute is mainly useful for the "timeout" message (see
Section 3.3). The CAP server imposes no restriction on the value.
If uniqueness is required, then it is the responsibility of the CUA
to generate unique values.
Data: no specific data for this command 6.2.3 Common Elements
Result: 2.0 - success 2.1 Permission Denied 2.2 Requested UPN not
found 2.3 Result exceeds MAXUPNEXPANDLIST 2.4 Misc. UPNEXPAND error
Return the members of the argument UPN. Successful result yields one 6.2.3.1 "data" Element
or more CalIDs. More than one CalID returned implies that the UPN
was a UG.
If the number of items exceeds MAXUPNEXPANDLIST, then up to The role of the "data" element is to join an iCalendar document to an
MAXUPNEXPANDLIST items are returned along with result 2.3. XML document forming a CAP command or response. The "data" element
is composed of a single attribute ("content") that MUST be set to a
"cid" URL that refers to an iCalendar document. See Section 3.2 for
more information.
If the result is 2.4, then as many of the items as possible will be Depending of the context, the content of the referred iCalendar
returned. It is possible that no items will be returned. The 2.4 object is subject to restrictions. See Section 6.2.1 for more
response may have optional text describing the problem. Any such details.
text MUST be in the language and charset that is defined by the
calendar store properties LANGUAGE and CHARSET.
If calendar store CHARSET is not set, but the LANGUAGE property is 6.2.3.2 "select" Element
set, then the error message will be in LANGUAGE in the UTF-8
charset. If calendar store LANGUAGE property is not set, then the
CS MUST NOT return any text with the results.
Example #1: Request lookup of a UPN which is a CU Many calendaring commands can target several components stored on the
CS (e.g., "search", "delete", "modify" and "move"). The "select"
element is used to identify the targeted components.
C: UPNEXPAND upn@example.com The "select" element is composed of the following:
S: 2.0
S: upn@example.com
S: cap://cal.example.com/calid3
S: .
Example #2: Request lookup of UPN which is a UG A "data" element that MUST refer to a VQUERY component.
C: UPNEXPAND group@example.com One or more "source" elements that identify the containers to
S: 2.0 consider.
S: group@example.com
S: cap://cal.example.com/calid3
S: cap://cal.example.com/calid6
S: cap://cal.example.com/calid1342
S: .
Example #3: Request lookup exceeds MAXUPNEXPANDLIST Restriction Table for the "data" element:
C: UPNEXPAND group@example.com Component/Property Presence Comment
S: 2.3 Lookup resulted in too much data ------------------- -------- ---------------------------
S: group@example.com VCALENDAR 1
S: cap://cal.example.com/calid3 . VERSION 1 MUST be 2.1
S: cap://cal.example.com/calid12 . [IANA-PROP] 0+ any IANA registered
S: cap://cal.example.com/calid21 property
S: cap://cal.example.com/calid33
S: .
Example #4: CS loses contact with directory server during UPNEXPAND . VQUERY 1
. . EXPAND 0 or 1
. . QUERYNAME 0 or 1 MUST be present if QUERY is absent.
. . QUERY 0 or 1 MUST be present if QUERYNAME is absent.
. . [IANA-PROP] 0+ any IANA registered
property
C: UPNEXPAND group@example.com . VTIMEZONE 0+ MUST be present if any
S: group@example.com date/time refers
S: 2.4 Lost contact with directory server to a timezone
S: cap://cal.example.com/calid3 . . DAYLIGHT 0+ MUST be one or more of
S: cap://cal.example.com/calid5 either STANDARD
S: . or DAYLIGHT
. . . . COMMENT 0 or 1
. . . . DTSTART 1
. . . . RDATE 0+ if present RRULE MUST NOT
be present
. . . . RRULE 0+ if present RDATE MUST NOT
7.1.12 NOOP Command be present
. . . . TZNAME 0 or 1
. . . . TZOFFSET 1
. . . . TZOFFSETFROM 1
. . . . TZOFFSETTO 1
. . . . X-PROPERTY 0+
. . . . [IANA-PROP] 0+ any IANA registered
property
. . LAST-MODIFIED 0 or 1
. . STANDARD 0+
. . . . COMMENT 0 or 1
. . . . DTSTART 1
. . . . RDATE 0+ if present RRULE MUST NOT
be present
. . . . RRULE 0+ if present RDATE MUST NOT
be present
. . . . TZNAME 0 or 1
. . . . TZOFFSETFROM 1
. . . . TZOFFSETTO 1
. . . . X-PROPERTY 0+
. . . . [IANA-PROP] 0+ any IANA registered
property
. . TZID 1
. . TZURL 0 or 1
. . X-PROPERTY 0+
. . [IANA-PROP] 0+ any IANA registered
Arguments: none 6.2.3.3 "source" Element
Data: none The "source" element is used to specify container(s) that will be
examined during the execution of a CAP command. The "source" element
is similar to the "target" element (see Section 6.2.3.4, but can
refer to several containers (e.g., a calendar hierarchy or all the
calendar owned by a given CU).
Result: 2.0 - success Attributes:
This method does nothing. It can be sent to the server periodically csid: when specified MUST point to a CSID. When omitted the CSID
to request that the CS not time out the session. of the current server is assumed.
[EDITORS NOTE: should an unauthenticated and unidentified client be relcalid: when specified MUST point to a RELCALID. The value is
able to issue this command?] relative the value of the "csid" attribute.
[EDITORS NOTE: need to add NOOP in the state diagram?] depth: specifies the maximal depth of the calendar hierarchy to
explore. When omitted the value "0" is assumed. The accepted
values are positives integers and "*".
Example: owner: if present MUST be set to a UPN. When specified only the
VAGENDA owned by the given UPN are considered.
C: NOOP 6.2.3.4 "target" Element
S: 2.0 The "target" element is used to specify a container targeted by a CAP
S: . command (e.g., the destination of a "create" command). A "target"
element MAY refer to a VAGENGA or the top level container of a
Calendar Store.
7.2 Application Protocol Commands Attributes:
7.2.1 Calendaring Commands csid: when specified MUST point to a CSID. When omitted the CSID
of the current server is assumed.
The following methods provide a set of calendaring commands in CAP. relcalid: when specified MUST point to a RELCALID. The value is
Calendaring commands (or methods) allow a CU to directly manipulate a relative the value of the "csid" attribute.
calendar.
6.2.4 Calendaring Commands
Calendaring commands allow a CUA to directly manipulate a calendar.
Calendar access rights can be granted for the more generalized access Calendar access rights can be granted for the more generalized access
provided by the calendar commands. provided by the calendar commands.
7.2.1.1 Restriction Tables 6.2.4.1 "create" Command
Commands are sent to CAP servers encapsulated in iCalendar objects.
The reply to these commands are also encapsulated in iCalendar
objects. The restriction tables listed in the commands below
describe the composition of the iCalendar data for these commands and
replies.
The Presence column uses the following values to assert whether a Attributes:
property is required, is optional and the number of times it may
appear in the iCalendar object. A Comment may be provided to further
clarify the presence criteria.
The table below defines the values for the Presence column. "id" (see Section 6.2.2.1).
Presence Value Description Elements:
--------------------------------------------------------------
1 One instance MUST be present
1+ At least one instance MUST be present
0 Instances of this property Must NOT be present
0+ Multiple instances MAY be present
0 or 1 Up to 1 instance of this property MAY be present
--------------------------------------------------------------
While the tables list every component and property, their purpose is "max-time": See Section 3.3.
not to define the meaning of the component or property.
There will be a REQUEST-STATUS for each VCALENDAR and component "target": Each "target" element points to a container where the
created, modified, deleted, or requested. The number of REQUEST- new component will be created.
STATUS values returned MUST be equal to the number of TARGETS times
the number of objects in the command. The responses MUST be ordered
first by TARGET then by the order of the objects as supplied in the
command.
7.2.1.2 CREATE Method "data": MUST point to an iCalendar object defining the
component(s) to create. See the restriction table given below.
Arguments: none Response:
Data: no specific data for this command One "result" message per "target" element MUST be returned (see
Section 3.1).
Result: One of the following "request-status" codes MUST be returned:
2.0 - successfully created the component or calendar 2.0 - successfully created the component or calendar
6.0 - Permission denied 6.1 - Container not found
6.1 - Container(s) not found
6.2 - Calendar or component already exists
6.3 - Bad args 6.3 - Bad args
The CREATE method is used to create a new iCalendar object of type The "data" element of each "result" message is subject to the
objtype. The property TARGET specifies the container(s) for the result restriction table defined below.
create. The type of object wrapped inside of the VCALENDAR/CREATE
object is the object type(s) being created. When creating a new
calendar at the top level, the CSID is specified. Otherwise the
container will be a CalID.
Restriction table The "create" command is used to create one or more iCalendar objects.
The "target" elements specify the containers where the component(s)
will be created.
Restriction table for the "data" element of the "create" command:
Component/Property Presence Comment Component/Property Presence Comment
------------------- -------- ----------------------------- ------------------- -------- -----------------------------
VCAP 1+ The CUA can send up VCALENDAR 1
PIPELINE commands . VERSION 1 MUST be 2.1
without processing a
response
. VERSION 1 MUST be 2.0
. [IANA-PROP] 0+ any IANA registered . [IANA-PROP] 0+ any IANA registered
property property
. VCOMMAND 1 MUST at least one container . VAGENDA 0+
(VCALENDAR, VCAR, VQUERY, . . CALMASTER 0 or 1
VEVENT, VTODO, VJOURNAL) . . NAME 0 or 1
. . CMDID 0 or 1 If CMDID is not supplied, . . OWNER 1+
then there must not be . . RELCALID 1
pending replies to previous . . TZID 0 or 1
command.
. . [IANA-PROP] 0+ any IANA registered . . [IANA-PROP] 0+ any IANA registered
property property
. . METHOD 1 MUST be CREATE.
. . TARGET 1+ MUST be the CSID or CALID
. . VCALENDAR 0+
. . . CALMASTER 0 or 1
. . . NAME 0 or 1
. . . OWNER 1+
. . . RELCALID 1
. . . TZID 0 or 1
. . . [IANA-PROP] 0+ any IANA registered
property
. . VCAR 0+ . VCAR 0+
. . . CARID 0 or 1 . . CARID 0 or 1
. . . DENY 0+ Note, there must be at . . DENY 0+ Note, there must be at
least one GRANT or DENY least one GRANT or DENY
within the VCAR. within the VCAR.
. . . GRANT 0+ Note, there must be at . . GRANT 0+ Note, there must be at
least one GRANT or DENY least one GRANT or DENY
within the VCAR. within the VCAR.
. . . [IANA-PROP] 0+ any IANA registered . . [IANA-PROP] 0+ any IANA registered
property property
. . VQUERY 0+ . VQUERY 0+
. . . EXPAND 0 or 1 . . EXPAND 0 or 1
. . . MAXRESULTS 0 or 1 . . QUERYNAME 1
. . . MAXSIZE 0 or 1 . . QUERY 1
. . . QUERYNAME 1 . . [IANA-PROP] 0+ any IANA registered
. . . QUERY 1
. . . [IANA-PROP] 0+ any IANA registered
property property
. . VEVENT 0+ . VEVENT 0+
. . . ATTENDEE 0+ . . ATTENDEE 0+
. . . SEQUENCE 0 or 1 MUST be present if value is . . SEQUENCE 0 or 1 MUST be present if value is
greater than 0, greater than 0,
MAY be present if 0 MAY be present if 0
. . . SUMMARY 1 Can be null . . SUMMARY 1 Can be null
. . . UID 1 . . UID 1
. . . ATTACH 0+ . . ATTACH 0+
. . . CATEGORIES 0 or 1 . . CATEGORIES 0 or 1
. . . CLASS 0 or 1 . . CLASS 0 or 1
. . . COMMENT 0 or 1 . . COMMENT 0 or 1
. . . CONTACT 0+ . . CONTACT 0+
. . . CREATED 0 or 1 . . CREATED 0 or 1
. . . DESCRIPTION 0 or 1 Can be null . . DESCRIPTION 0 or 1 Can be null
. . . DTEND 0 or 1 if present DURATION MUST . . DTEND 0 or 1 if present DURATION MUST
NOT be present NOT be present
. . . DTSTAMP 1 . . DTSTAMP 1
. . . DTSTART 1 . . DTSTART 1
. . . DURATION 0 or 1 if present DTEND MUST NOT . . DURATION 0 or 1 if present DTEND MUST NOT
be present be present
. . . EXDATE 0+ . . EXDATE 0+
. . . EXRULE 0+ . . EXRULE 0+
. . . GEO 0 or 1 . . GEO 0 or 1
. . . LAST-MODIFIED 0 or 1 . . LAST-MODIFIED 0 or 1
. . . LOCATION 0 or 1 . . LOCATION 0 or 1
. . . METHOD 1 <<placeholder. it may move . . ORGANIZER 1
to meta-info>> . . PRIORITY 0 or 1
. . . ORGANIZER 1 . . RDATE 0+
. . . PRIORITY 0 or 1 . . RECURRENCE-ID 0 or 1 only if referring to an
. . . RDATE 0+
. . . RECURRENCE-ID 0 or 1 only if referring to an
instance of a recurring instance of a recurring
calendar component. calendar component.
Otherwise it MUST NOT be Otherwise it MUST NOT be
present. present.
. . . RELATED-TO 0+ . . RELATED-TO 0+
. . . REQUEST-STATUS 0+ . . REQUEST-STATUS 0+
. . . RESOURCES 0 or 1 This property MAY contain a . . RESOURCES 0 or 1 This property MAY contain a
list of values list of values
. . . RRULE 0+ . . RRULE 0+
. . . STATUS 0 or 1 . . STATUS 0 or 1
. . . TRANSP 0 or 1 . . TRANSP 0 or 1
. . . URL 0 or 1 . . URL 0 or 1
. . . X-PROPERTY 0+ . . X-PROPERTY 0+
. . . [IANA-PROP] 0+ any IANA registered . . [IANA-PROP] 0+ any IANA registered
property property
. . . VALARM 0+ . . VALARM 0+
. . . . ACTION 1 . . . ACTION 1
. . . . ALARMID 0 or 1 MUST be 1 if multiple . . . ALARMID 1
VALARMs are present in . . . ATTACH 0+
same component. . . . DESCRIPTION 0 or 1
. . . . ATTACH 0+ . . . DURATION 0 or 1 if present REPEAT MUST be
. . . . DESCRIPTION 0 or 1
. . . . DURATION 0 or 1 if present REPEAT MUST be
present present
. . . . REPEAT 0 or 1 if present DURATION MUST be . . . REPEAT 0 or 1 if present DURATION MUST be
present present
. . . . SUMMARY 0 or 1 . . . SUMMARY 0 or 1
. . . . TRIGGER 1 . . . TRIGGER 1
. . . . X-PROPERTY 0+ . . . X-PROPERTY 0+
. . . . [IANA-PROP] 0+ any IANA registered property . . . [IANA-PROP] 0+ any IANA registered property
. . VTODO 0+ . VTODO 0+
. . . ATTENDEE 0+ . . ATTENDEE 0+
. . . SEQUENCE 0 or 1 MUST be present if value is . . SEQUENCE 0 or 1 MUST be present if value is
greater than 0, MAY be greater than 0, MAY be
present if 0 present if 0
. . . SUMMARY 1 Can be null. . . SUMMARY 1 Can be null.
. . . UID 1 . . UID 1
. . . ATTACH 0+ . . ATTACH 0+
. . . CATEGORIES 0 or 1 This property may contain a . . CATEGORIES 0 or 1 This property may contain a
list of values list of values
. . . CLASS 0 or 1 . . CLASS 0 or 1
. . . COMMENT 0 or 1 . . COMMENT 0 or 1
. . . CONTACT 0+ . . CONTACT 0+
. . . CREATED 0 or 1 . . CREATED 0 or 1
. . . DESCRIPTION 0 or 1 Can be null . . DESCRIPTION 0 or 1 Can be null
. . . DTSTAMP 1 . . DTSTAMP 1
. . . DTSTART 1 . . DTSTART 1
. . . DUE 0 or 1 If present DURATION MUST NOT . . DUE 0 or 1 If present DURATION MUST NOT
be present be present
. . . DURATION 0 or 1 If present DUE MUST NOT be . . DURATION 0 or 1 If present DUE MUST NOT be
present present
. . . EXDATE 0+ . . EXDATE 0+
. . . EXRULE 0+ . . EXRULE 0+
. . . GEO 0 or 1 . . GEO 0 or 1
. . . LAST-MODIFIED 0 or 1 . . LAST-MODIFIED 0 or 1
. . . LOCATION 0 or 1 . . LOCATION 0 or 1
. . . METHOD 1 <<placeholder. it may move . . ORGANIZER 1
to meta-info>> . . PRIORITY 1
. . . ORGANIZER 1 . . PERCENT-COMPLETE 0 or 1
. . . PRIORITY 1 . . RDATE 0+
. . . PERCENT-COMPLETE 0 or 1 . . RECURRENCE-ID 0 or 1 MUST only if referring to an
. . . RDATE 0+
. . . RECURRENCE-ID 0 or 1 MUST only if referring to an
instance of a recurring instance of a recurring
calendar component. calendar component.
Otherwise it MUST NOT be Otherwise it MUST NOT be
present. present.
. . . RELATED-TO 0+ . . RELATED-TO 0+
. . . REQUEST-STATUS 0 . . REQUEST-STATUS 0
. . . RESOURCES 0 or 1 This property may contain a . . RESOURCES 0 or 1 This property may contain a
list of values list of values
. . . RRULE 0+ . . RRULE 0+
. . . STATUS 0 or 1 MAY be one of COMPLETED, . . STATUS 0 or 1 MAY be one of COMPLETED,
NEEDS-ACTION, NEEDS-ACTION,
IN-PROCESS, CANCELLED IN-PROCESS, CANCELLED
. . . URL 0 or 1 . . URL 0 or 1
. . . X-PROPERTY 0+ . . X-PROPERTY 0+
. . . [IANA-PROP] 0+ any IANA registered property . . [IANA-PROP] 0+ any IANA registered property
. . . VALARM 0+ . . VALARM 0+
. . . . ACTION 1 . . . ACTION 1
. . . . ALARMID 0 or 1 MUST be 1 if multiple . . . ALARMID 1
VALARMs are present in . . . ATTACH 0+
same component. . . . DESCRIPTION 0 or 1
. . . . ATTACH 0+ . . . DURATION 0 or 1 if present REPEAT MUST be
. . . . DESCRIPTION 0 or 1
. . . . DURATION 0 or 1 if present REPEAT MUST be
present present
. . . . REPEAT 0 or 1 if present DURATION MUST be . . . REPEAT 0 or 1 if present DURATION MUST be
present present
. . . . SUMMARY 0 or 1 . . . SUMMARY 0 or 1
. . . . TRIGGER 1 . . . TRIGGER 1
. . . . X-PROPERTY 0+ . . . X-PROPERTY 0+
. . . . [IANA-PROP] 0+ any IANA registered property . . . [IANA-PROP] 0+ any IANA registered property
. . VJOURNAL 0+ . VJOURNAL 0+
. . . ATTENDEE 0 . . ATTENDEE 0
. . . DESCRIPTION 1 Can be null. . . DESCRIPTION 1 Can be null.
. . . DTSTAMP 1 . . DTSTAMP 1
. . . DTSTART 1 . . DTSTART 1
. . . ORGANIZER 1 . . ORGANIZER 1
. . . UID 1 . . UID 1
. . . ATTACH 0+ . . ATTACH 0+
. . . CATEGORIES 0 or 1 This property MAY contain a list . . CATEGORIES 0 or 1 This property MAY contain a list
of values of values
. . . CLASS 0 or 1 . . CLASS 0 or 1
. . . COMMENT 0 or 1 . . COMMENT 0 or 1
. . . CONTACT 0+ . . CONTACT 0+
. . . CREATED 0 or 1 . . CREATED 0 or 1
. . . EXDATE 0+ . . EXDATE 0+
. . . EXRULE 0+ . . EXRULE 0+
. . . LAST-MODIFIED 0 or 1 . . LAST-MODIFIED 0 or 1
. . . METHOD 1 <<placeholder. it may move . . RDATE 0+
to meta-info>> . . RECURRENCE-ID 0 or 1 MUST only if referring to
. . . RDATE 0+
. . . RECURRENCE-ID 0 or 1 MUST only if referring to
an instance of a recurring an instance of a recurring
calendar component. calendar component.
Otherwise it MUST NOT be Otherwise it MUST NOT be
present. present.
. . . RELATED-TO 0+ . . RELATED-TO 0+
. . . RRULE 0+ . . REQUEST-STATUS 0+
. . . SEQUENCE 0 or 1 MUST be present if . . RRULE 0+
. . SEQUENCE 0 or 1 MUST be present if
non-zero. MAY be non-zero. MAY be
present if zero. present if zero.
. . . STATUS 0 or 1 . . STATUS 0 or 1
. . . SUMMARY 0 or 1 Can be null . . SUMMARY 0 or 1 Can be null
. . . URL 0 or 1 . . URL 0 or 1
. . . X-PROPERTY 0+ . . X-PROPERTY 0+
. . . [IANA-PROP] 0+ any IANA registered . . [IANA-PROP] 0+ any IANA registered
property property
. VFREEBUSY 0
. . VFREEBUSY 0 . VTIMEZONE 0+ MUST be present if any
. . VTIMEZONE 0+ MUST be present if any
date/time refers to a date/time refers to a
timezone timezone
. . . DAYLIGHT 0+ MUST be one or more of . . DAYLIGHT 0+ MUST be one or more of
either STANDARD or either STANDARD or
DAYLIGHT DAYLIGHT
. . . . . COMMENT 0 or 1 . . . . COMMENT 0 or 1
. . . . . DTSTART 1 . . . . DTSTART 1
. . . . . RDATE 0+ if present RRULE MUST NOT . . . . RDATE 0+ if present RRULE MUST NOT
be present be present
. . . . . RRULE 0+ if present RDATE MUST NOT . . . . RRULE 0+ if present RDATE MUST NOT
be present be present
. . . . . TZNAME 0 or 1 . . . . TZNAME 0 or 1
. . . . . TZOFFSET 1 . . . . TZOFFSET 1
. . . . . TZOFFSETFROM 1 . . . . TZOFFSETFROM 1
. . . . . TZOFFSETTO 1 . . . . TZOFFSETTO 1
. . . . . X-PROPERTY 0+ . . . . X-PROPERTY 0+
. . . . . [IANA-PROP] 0+ any IANA registered . . . . [IANA-PROP] 0+ any IANA registered
property property
. . . LAST-MODIFIED 0 or 1 . . LAST-MODIFIED 0 or 1
. . . STANDARD 0+ . . STANDARD 0+
. . . . . COMMENT 0 or 1 . . . . COMMENT 0 or 1
. . . . . DTSTART 1 . . . . DTSTART 1
. . . . . RDATE 0+ if present RRULE MUST NOT . . . . RDATE 0+ if present RRULE MUST NOT
be present be present
. . . . . RRULE 0+ if present RDATE MUST NOT . . . . RRULE 0+ if present RDATE MUST NOT
be present be present
. . . . . TZNAME 0 or 1 . . . . TZNAME 0 or 1
. . . . . TZOFFSETFROM 1 . . . . TZOFFSETFROM 1
. . . . . TZOFFSETTO 1 . . . . TZOFFSETTO 1
. . . . . X-PROPERTY 0+ . . . . X-PROPERTY 0+
. . . . . [IANA-PROP] 0+ any IANA registered property . . . . [IANA-PROP] 0+ any IANA registered property
. . . TZID 1 . . TZID 1
. . . TZURL 0 or 1 . . TZURL 0 or 1
. . . X-PROPERTY 0+ . . X-PROPERTY 0+
. . . [IANA-PROP] 0+ any IANA registered property . . [IANA-PROP] 0+ any IANA registered property
Server Restriction Table for the CREATE command Restriction Table for the "data" element of the "result" response:
Component/Property Presence Comment Component/Property Presence Comment
------------------- -------- ------------------------------- ------------------- -------- -------------------------------
VCAP 1+ VCALENDAR 1+
. VCALENDAR 1+ . VERSION 1 MUST be 2.1
. . TARGET 1
. . VERSION 1 MUST be 2.0 . VAGENDA 0+
. . CMDID 0 or 1 MUST be returned if the . . RELCALID 1
request contained . . REQUEST-STATUS 1+
a CMDID
. . REQUEST-STATUS 0 if not creating a calendar
1+ if creating a calendar
. . . VCAR 0+ . VCAR 0+
. . . . REQUEST-STATUS 1+ . . CARID 1
. . . . * 0 No other VCAR properties . . REQUEST-STATUS 1+
are present
.
. . . VCOMMAND 0
. . . VEVENT 0+ . VEVENT 0+
. . . . REQUEST-STATUS 1+ . . UID 1 The UID for which this
. . . . * 0 No other VEVENT properties REQUEST-STATUS applies
are present . . REQUEST-STATUS 1+
. . . . VALARM 0 if VEVENT was successfully . . RECURRENCE-ID 0 or 1 MUST be specified only if instance of
a recurring component was created.
. . VALARM 0 if VEVENT was successfully
saved saved
1+ if there were errors saving 1+ if there were errors saving
alarms alarms
. . . . . REQUEST-STATUS 1+ . . . ALARMID 1
. . . REQUEST-STATUS 1+
. . . VFREEBUSY 0+
. . . . REQUEST-STATUS 1+
. . . . * 0 No other VFREEBUSY
properties are present
. . . VJOURNAL 0+ . VFREEBUSY 0
. . . . REQUEST-STATUS 1+
. . . . * 0 No other VJOURNAL
properties are present
. . . VQUERY 0+ . VJOURNAL 0+
. . . . REQUEST-STATUS 1+ . . UID 1 The UID for which this
. . . . * 0 No other VQUERY properties REQUEST-STATUS applies
are present . . RECURRENCE-ID 0 or 1 MUST be specified only if instance of
a recurring component was created.
. . REQUEST-STATUS 1+
. . . VTODO 0+ . VQUERY 0+
. . . . REQUEST-STATUS 1+ . . REQUEST-STATUS 1+
. . . . * 0 No other VTODO properties
are present
. . . . VALARM 0 if VTODO was successfully . VTODO 0+
. . UID 1 The UID for which this
REQUEST-STATUS applies
. . RECURRENCE-ID 0 or 1 MUST be specified only if instance of
a recurring component was created.
. . REQUEST-STATUS 1+
. . VALARM 0 if VTODO was successfully
saved saved
1+ if there were errors saving 1+ if there were errors saving
alarms alarms
. . . . . REQUEST-STATUS 1+ . . . ALARMID 1
. . . REQUEST-STATUS 1+
7.2.1.2.1 Creating New Calendars Example:
Example to create two new calendars different containers. In the In the following example, two new top level VAGENDAs are created.
following example, the client is in the Authenticated state with CS
cal.example.com.
C: SENDDATA Note that the CSID of the server is cal.example.com.
C: CONTENT-TYPE: text/calendar; method=CREATE;
C: component=VCOMMAND C: MSG 1 8 . 3843 778
C: Content-Transfer-Encoding:7bit C: Content-Type: multipart/related; boundary="boundary-foo321";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary-foo321
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <create id="creation01">
C: <target csid="cal.example.com"/>
C: <data content="cid:2@cal.example.com"/>
C: </create>
C: --boundary-foo321
C: Content-Type: text/calendar
C: Content-ID: 2@cal.example.com
C: C:
C: BEGIN:VCAP
C: VERSION:2.1
C: BEGIN:VCOMMAND
C: METHOD:CREATE
C: TARGET:cap://cal.example.com/
C: TARGET:relcal4
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: VERSION:2.1
C: BEGIN:VAGENDA
C: RELCALID:relcalz1 C: RELCALID:relcalz1
C: NAME:CHARSET=us-ascii;LANGUAGE=EN-us:Bill's Soccer Team C: NAME;LANGUAGE=EN-us:Bill's Soccer Team
C: OWNER:bill C: OWNER:bill
C: CALMASTER:mailto:bill@example.com C: CALMASTER:mailto:bill@example.com
C: TZID:US_PST C: TZID:US_PST
C: BEGIN:VCAR C: END:VAGENDA
C: CARID:12345 C: BEGIN:VAGENDA
C: GRANT:UPN=bill;ACTION=*;OBJECT=*
C: END:VCAR
C: END:VCALENDAR
C: BEGIN:VCALENDAR
C: RELCALID:relcalz2 C: RELCALID:relcalz2
C: NAME:CHARSET=us-ascii;LANGUAGE=EN-us:Mary's personal C: NAME;LANGUAGE=EN-us:Mary's personal calendar
C: calendar
C: OWNER:mary C: OWNER:mary
C: CALMASTER:mailto:mary@example.com C: CALMASTER:mailto:mary@example.com
C: TZID:US_PST C: TZID:US_PST
C: BEGIN:VCAR C: END:VAGENDA
C: CARID:12346
C: GRANT:UPN=mary;ACTION=*;OBJECT=*
C: END:VCAR
C: END:VCALENDAR C: END:VCALENDAR
C: END:VCOMMAND C: --boundary-foo321--
C: END:VCAP C: END
C: . S: RPY 1 8 . 4621 647
S: 2.0 S: Content-Type: multipart/related; boundary="boundary-bar321";
S: Content-Type:text/calendar; method=RESPONSE; S: start="1@cal.example.com";
S: OPTINFO="CMDID:abcde" S: type="application/beep+xml"
# This 2.0 is the transport reply status and ends with a S:
# CRLF.CRLF (below) S: --boundary-bar321
S: BEGIN:VCAP S: Content-Type: application/beep+xml
S: METHOD:RESPONSE S: Content-ID: 1@cal.example.com
S: TARGET:cap://cal.example.com/ S:
S: <result id="creation01">
S: <target csid="cal-example.com"/>
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-bar321
S: Content-Type:text/calendar;
S: Content-ID: 2@cal.example.com
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: BEGIN:VAGENDA
S: RELCALID:relcalz1
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VCAP S: END:VAGENDA
S: BEGIN:VCAP S: BEGIN:VAGENDA
S: METHOD:RESPONSE S: RELCALID:relcalz2
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VCAP S: END:VAGENDA
S: . S: END:VCALENDAR
S: --boundary-bar321--
S: END
Example to create a new component. Example to create a new component in multiple containers.
C: SENDDATA C: MSG 1 9 . 5268 622
C: Content-Type:text/calendar; method=CREATE; C: Content-Type: multipart/related; boundary="boundary-kshgd";
C: charset=US-ASCII C: start="1@cal.example.com";
C: Content-Transfer-Encoding:7bit C: type="application/beep+xml"
C: C:
C: BEGIN:VCAP C: --boundary-kshgd
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <create id="creation02">
C: <target relcalid="relcalz1"/>
C: <target relcalid="relcalz2"/>
C: <data content="cid:2@cal.example.com"/>
C: </create>
C: --boundary-kshgd
C: Content-Type: text/calendar
C: Content-ID: 2@cal.example.com
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1 C: VERSION:2.1
C: CMDID:abcde
C: BEGIN:VCOMMAND
C: METHOD:CREATE
C: TARGET:cap://cal.example.com/relcal1
C: TARGET:relcal2
C: BEGIN:VEVENT C: BEGIN:VEVENT
C: DTSTART:99990307T180000Z C: DTSTART:99990307T180000Z
C: UID:abcd12345 C: UID:abcd12345
C: DTEND:99990307T190000Z C: DTEND:99990307T190000Z
C: SUMMARY:Important Meeting C: SUMMARY:Important Meeting
C: END:VEVENT C: END:VEVENT
C: END:VCOMMAND C: END:VCALENDAR
C: END:VCAP C: --boundary-kshgd--
C: . C: END
S: 2.0 S: ANS 1 9 . 58901 563 0
S: Content-Type:text/calendar; method=RESPONSE; S: Content-Type: multipart/related; boundary="boundary-eqrga";
S: OPTINFO="CMDID:abcde" S: start="1@cal.example.com";
S: type="application/beep+xml"
S: S:
S: BEGIN:VCAP S: --boundary-eqrga
S: Content-Type: application/beep+xml
S: Content-ID: 1@cal.example.com
S:
S: <result id="creation02">
S: <target relcalid="relcalz1"/>
S: <request-status code="2.0"/>
S: <data content="2@cal.example.com"/>
S: </result>
S: --boundary-eqrga
S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1 S: VERSION:2.1
S: CMDID:abcde
S: METHOD:RESPONSE
S: BEGIN:VEVENT S: BEGIN:VEVENT
S: TARGET::cap://cal.example.com/relcal1 S: UID:abcd12345
S: REQUEST-STATUS:2.9 S: REQUEST-STATUS:2.9
S: END:VEVENT S: END:VEVENT
S: END:VCALENDAR
S: --boundary-eqrga--
S: END
S: ANS 1 9 . 6453 563 1
S: Content-Type: multipart/related; boundary="boundary-982hf";
S: start="1@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-982hf
S: Content-Type: application/beep+xml
S: Content-ID: 1@cal.example.com
S:
S: <result id="creation02">
S: <target relcalid="relcalz2"/>
S: <request-status code="2.0"/>
S: <data content="2@cal.example.com"/>
S: </result>
S: --boundary-982hf
S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: BEGIN:VEVENT S: BEGIN:VEVENT
S: REQUEST-STATUS:2.9 S: UID:abcd12345
S: REQUEST-STATUS:2.10 S: REQUEST-STATUS:6.0
S: END:VEVENT S: END:VEVENT
S: END:VCAP S: END:VCALENDAR
S: . S: --boundary-982hf--
S: END
The response contains the calendar (CALID) and UID of the component S: NUL 1 9 . 7016 0
so that the CUA can match up the TARGET from multiple objects created S: END
on multiple calendards (TARGETs).
7.2.1.2.2 Creating a new VQUERY
This example creates a stored VQUERY that selects all unprocessed
scheduling entries. QUERYNAME must not exist in the TARGET
calendar.
C: SENDDATA
C: Content-Type:text/calendar; method=CREATE; charset=US-ASCII
C: Content-Transfer-Encoding:7bit
C:
C: BEGIN:VCAP
C: VERSION:2.1
C: CMDID:abcde-2
C: METHOD:CREATE
C: TARGET:cap://cal.example.com/relcal1
C: BEGIN:VQUERY
C: BEGIN:VQUERY
C: QUERYNAME:GetAlliTIPinQueue
C: QUERY:SELECT UID FROM VEVENT,VTODO WHERE METHOD != 'CREATE'
C: END:VQUERY
C: END:VEVENT
C: END:VCAP
C: .
S: 2.0
S: Content-Type:text/calendar; method=RESPONSE; OPTINFO="CMDID:abcde"
S:
S: BEGIN:VCAP
S: CMDID:abcde-2
S: METHOD:RESPONSE
S: TARGET::cap://cal.example.com/relcal1
S: BEGIN:VQUERY
S: REQUEST-STATUS:2.0;
S: END:VQUERY
S: END:VCAP
S: .
[EDITORS NOTE - can return QUERYNAME already exists error]
7.2.1.3 DELETE Method
Arguments: none As described in Section 3.1, the CS sends one response per "target"
element present in the "create" command.
Data: no specific data for this command 6.2.4.2 "delete" Command
Result: Attributes:
2.0 - successfully deleted the component or calendar "id" (see Section 6.2.2.1).
Permission Elements:
Calendar or component not found "max-time": See Section 3.3.
Bad args "select": specifies the compoments to delete (see Section
6.2.3.2).
Container(s) not found Response:
The DELETE method is used to delete a calendar or component. The One "result" message per "source" in the "select" element (see
TARGET properties specify the container(s) for the delete. When Section 3.1).
deleting a calendar at the top level, the CSID is specified.
Otherwise the container will be a CalID.
Restriction Table One of the following "request-status" codes MUST be returned:
Component/Property Presence Comment 2.0 - successfully created the component or calendar
------------------- -------- ---------------------------
VCAP 1+ The CUA can send up
PIPELINE commands
without processing a
response
VERSION 1 MUST be 2.0 6.1 - Container not found
VCOMMAND 1 6.3 - Bad args
CMDID 0 or 1 If CMDID is not supplied,
then there must
not be pending replies to
previous command.
METHOD 1 MUST be DELETE.
TARGET 1+ MUST be a the CSID or CALID
VQUERY 0+ The "data" element of each "result" message is subject to the
EXPAND 0 ? result restriction table define below.
MAXRESULTS 0 or 1 Limit the solution set to
no more than this many
entries.
MAXSIZE 0 ? The "delete" command is used to delete a calendar or component. The
QUERYNAME 1 Name by which this query is "select" element specifies the container(s) to delete.
referenced
QUERY 1 The query
Server Restriction Table for the DELETE command Restriction Table for the "data" element of the "result" response(s).
Component/Property Presence Comment Component/Property Presence Comment
------------------- -------- ----------------------------- ------------------- -------- -----------------------------
VCAP 1+ VCALENDAR 1+
TARGET 1
VERSION 1 MUST be 2.0
CMDID 0 or 1 MUST be returned if the . VERSION 1 MUST be 2.1
request contained a CMDID
VCALENDAR Only if VCALENDARs were . VAGENDA Only if VAGENDAS were
deleted deleted
REQUEST-STATUS 1 . RELCALID 1
* 1+ No other VALARM properties . REQUEST-STATUS 1
are present
VALARM 0+ Only if VALARM components
were deleted
REQUEST-STATUS 1
* 0 No other VALARM properties
are present
VCAR 0+ Only if VCAR components were . VCAR 0+ Only if VCAR components were
deleted deleted
REQUEST-STATUS 1 . . CARID 1
* 0 No other VCAR properties are . . REQUEST-STATUS 1
present
VEVENT 0+ Only if VEVENT components . VEVENT 0+ Only if VEVENT components
were deleted were deleted
REQUEST-STATUS 1+ . . UID 1
. . REQUEST-STATUS 0 or 1 Omitted if an embedded VALARM was
* 0 No other VEVENT properties the target of the deletion.
are present . . VALARM 0+ Only if VALARM components
VFREEBUSY 0
REQUEST-STATUS 1+
* 0 No other VFREEBUSY properties
are present
VJOURNAL 0+ Only if VJOURNAL components
were deleted were deleted
REQUEST-STATUS 1+ . . . ALARMID 1
* 0 No other VJOURNAL properties . . . REQUEST-STATUS 1
are present
VQUERY 0+ Only if VQUERY components . VFREEBUSY 0
. . UID 1
. . DTSTAMP 1
. . REQUEST-STATUS 1
. VJOURNAL 0+ Only if VJOURNAL components
were deleted were deleted
REQUEST-STATUS 1+ . . UID 1
* 0 No other VQUERY properties . . REQUEST-STATUS 1
are present
VTIMEZONE 0+ Only if VTIMEZONE components . VQUERY 0+ Only if VQUERY components
were deleted were deleted
REQUEST-STATUS 1+ . UID 1
* 0 No other VQUERY properties . REQUEST-STATUS 1
are present
VTODO 0+ Only if VTODO components were . VTIMEZONE 0+ Only if VTIMEZONE components
. . TZID were deleted
. . REQUEST-STATUS 1
. VTODO 0+ Only if VTODO components were
deleted deleted
REQUEST-STATUS 1+ . . UID 1
* 0 No other VTODO properties are . . REQUEST-STATUS 0 or 1 Omitted if an embedded VALARM was
present the target of the deletion.
. . VALARM 0+ Only if VALARM components
were deleted
. . . ALARMID 1
. . . REQUEST-STATUS 1
---------------------------------------------------------- ----------------------------------------------------------
[EDITORS NOTE: Issues: [EDITORS NOTE: Issues:
- Currently CAP requires that the server return a response status.
However, if there are multiple components deleted, should the UID
also be returned?
- VQUERY EXPAND and MAXSIZE parameters do not seem to apply to
deletion?
- Can one use DELETE to remove all VALARMs and VTIMEZONEs that - Can one use DELETE to remove all VALARMs and VTIMEZONEs that
match a certain search criteria and that belong to all components, match a certain search criteria and that belong to all components,
event though VALARMs and VTIMEZONEs never exist as independent event though VALARMs and VTIMEZONEs never exist as independent
components? Or should one use MODIFY? If they can be deleted, do components? Or should one use MODIFY? If they can be deleted, do
we return the REQUEST-STATUS of their deletion in a VEVENT or we return the REQUEST-STATUS of their deletion in a VEVENT or
separately? separately?
- In the example in CAP where a calendar is deleted all the server Example to delete a VEVENT with UID 'abcd12345' from any of the
returns is 2.0, nothing else? calendar owned by the CU with the UPN="user@cal.example.com":
- We should not be able to delete any VFREEBUSY components?
- Can we delete multiple calendars?
- Currently one can not delete a VCALENDAR and some other
component in the same DELETE command. This seems OK. Anyone see
any need to be able to do this?
- Should the MAXRESULTS property of VQUERY apply to deletion? We
can use it to delete only the first n components that match. ]
Example to delete a VEVENT with UID 'abcd12345':
C: SENDDATA C: MSG 1 10 . 7016 558
C: Content-Type:text/calendar; method=DELETE; C: Content-Type: multipart/related; boundary="boundary-gsdmx3";
component=VCOMMAND C: start="1@cal.example.com";
C: Content-Transfer-Encoding:7bit C: type="application/beep+xml"
C:
C: --boundary-gsdmx3
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <delete id="delete01">
C: <select>
C: <source depth=* owner="user@cal.example.com"/>
C: <data content="cid:2@cal.example.com"/>
C: </select>
C: </delete>
C: --boundary-gsdmx3
C: Content-Type: text/calendar
C: Content-ID: 2@cal.example.com
C: C:
C: BEGIN:VCAP
C: BEGIN:VCOMMAND
C: METHOD:DELETE
C: TARGET:cap://cal.foo.com/bill
C: BEGIN:VQUERY C: BEGIN:VQUERY
C: QUERY:SELECT UID FROM VEVENT WHERE UID = 'abcd12345' C: QUERY:SELECT * FROM VEVENT WHERE UID = 'abcd12345'
C: END:VQUERY C: END:VQUERY
C: END:VCOMMAND C: --boundary-gsdmx3--
C: END:VCAP C: END
C: . S: RPY 1 10 . 7574 587
S: 2.0 S: Content-Type: multipart/related; boundary="boundary-oifc3j";
S: Content-Type:text/calendar; method=DELETE; S: start="1@cal.example.com";
S: component=VCOMMAND S: type="application/beep+xml"
S: S:
S: BEGIN:VCAP S: --boundary-oifc3j
S: METHOD:RESPONSE S: Content-Type: application/beep+xml
S: Content-ID: 1@cal.example.com
S:
S: <result id="delete01">
S: <source depth=* owner="user@cal.example.com"/>
S: <data content="cid:2@cal.example.com"/>
S: <request-status code="2.0"/>
S: </result>
S: --boundary-oifc3j
S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: BEGIN:VEVENT S: BEGIN:VEVENT
S: UID:abcd12345
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VEVENT S: END:VEVENT
S: END:VCAP S: END:VCALENDAR
S: . S: --boundary-oifc3j--
C: SENDDATA S: END
C: Content-Type:text/calendar; method=DELETE;
C: component=VCOMMAND
C: Content-Transfer-Encoding:7bit
C:
C: BEGIN:VCAP
C: BEGIN:VCOMMAND
C: METHOD:DELETE
C: TARGET:cap://cal.foo.com/MrBill
C: END:VCOMMAND
C: END:VCAP
C: .
S: 2.0
S: .
7.2.1.4 GENERATEUID Method
Arguments: Number of UIDs to generate.
Data: new uids
Result: 2.0
GENERATEUID returns one or more new unique identifier which MUST be
unique on the server's calendar store. It is recommended that the
return value be a globally unique id.
Example:
C: GENERATEUID 2
S: 2.0
S: abcde1234567-asdf-lkhh
S: abcde1234567-asdf-3455
S: .
[EDITORS NOTE: this example needs work. It's not packaged right]
7.2.1.5 MODIFY Method
Arguments: none
Data: no specific data for this command
Result:
2.0 - successfully modified the component or calendar
Permission
Calendar or component not found
Bad args
Container(s) not found
The MODIFY method is used to change an existing calendar or
component. TARGET specify the container(s) of the modification.
When modifying a calendar at the top level, the CSID is specified. 6.2.4.3 "modify" Command
Otherwise the container will be a CalID.
The format of the request is two or three containers inside of a Attributes:
VCOMMAND container:
BEGIN:VCOMMAND "id" (see Section 6.2.2.1).
[VQUERY]
OLD-VALUES
NEW-VALUES
END:VCOMMAND
If a VQUERY is present, then only objects matching the query results Elements:
are modified.
Restriction Table "max-time": See Section 3.3.
Component/Property Presence Comment "select": identifies the component(s) to modify.
------------------- -------- ---------------------------
VCAP 1+ The CUA can send up
PIPELINE commands
without processing a
response
. VERSION 1 MUST be 2.0 "add": adds properties to the selected component(s).
. [IANA-PROP] 0+ any IANA registered
property
. VCOMMAND 1 MUST have at least one "remove": removes properties from the selected component(s).
container (VCALENDAR,
VCAR, VQUERY, VEVENT,
VTODO, VJOURNAL)
. . CMDID 0 or 1 If CMDID is not supplied,
then there must
not be pending replies to
previous command.
. . [IANA-PROP] 0+ any IANA registered
property
. . METHOD 1 MUST be MODIFY
. . TARGET 1+ MUST be the CALID
. . VCALENDAR 0+ "update": updates the content of the selected component(s).
. . . CALMASTER 0 or 1
. . . NAME 0 or 1
. . . OWNER 1+
. . . RELCALID 1
. . . TZID 0 or 1
. . . [IANA-PROP] 0+ any IANA registered
property
. . VCAR 0+ Response:
. . . CARID 0 or 1
. . . DENY 0+ Note, there must be at
least one GRANT or DENY
within the VCAR.
. . . GRANT 0+ Note, there must be at
least one GRANT or DENY
within the VCAR.
. . . [IANA-PROP] 0+ any IANA registered
property
. . VQUERY 0+ One "result" message per "source" in the "select" is returned (see
. . . EXPAND 0 or 1 Section 3.1).
. . . MAXRESULTS 0 or 1
. . . MAXSIZE 0 or 1
. . . QUERYNAME 1
. . . QUERY 1
. . . [IANA-PROP] 0+ any IANA registered
property
. . VEVENT 0+ One of the following "request-status" codes MUST be returned:
. . . ATTENDEE 0+
. . . SEQUENCE 0 or 1 MUST be present if value is
greater than 0,
MAY be present if 0
. . . SUMMARY 1 Can be null
. . . UID 1
. . . ATTACH 0+ 2.0 - successfully created the component or calendar
. . . CATEGORIES 0 or 1
. . . CLASS 0 or 1
. . . COMMENT 0 or 1
. . . CONTACT 0+
. . . CREATED 0 or 1
. . . DESCRIPTION 0 or 1 Can be null
. . . DTEND 0 or 1 if present DURATION MUST
NOT be present
. . . DTSTAMP 1
. . . DTSTART 1
. . . DURATION 0 or 1 if present DTEND MUST NOT
be present
. . . EXDATE 0+
. . . EXRULE 0+
. . . GEO 0 or 1
. . . LAST-MODIFIED 0 or 1
. . . LOCATION 0 or 1
. . . METHOD 1 <<placeholder. it may move
to meta-info>>
. . . ORGANIZER 1
. . . PRIORITY 0 or 1
. . . RDATE 0+
. . . RECURRENCE-ID 0 or 1 only if referring to an
instance of a recurring
calendar component.
Otherwise it MUST NOT be
present.
. . . RELATED-TO 0+
. . . REQUEST-STATUS 0+
. . . RESOURCES 0 or 1 This property MAY contain a
list of values
. . . RRULE 0+
. . . STATUS 0 or 1
. . . TRANSP 0 or 1
. . . URL 0 or 1
. . . X-PROPERTY 0+
. . . [IANA-PROP] 0+ any IANA registered
property
. . . VALARM 0+ 6.1 - Container not found
. . . . ACTION 1
. . . . ALARMID 0 or 1 MUST be 1 if multiple
VALARMs are present in same
component.
. . . . ATTACH 0+
. . . . DESCRIPTION 0 or 1
. . . . DURATION 0 or 1 if present REPEAT MUST be
present
. . . . REPEAT 0 or 1 if present DURATION MUST be
present
. . . . SUMMARY 0 or 1
. . . . TRIGGER 1
. . . . X-PROPERTY 0+
. . . . [IANA-PROP] 0+ any IANA registered
property
. . VTODO 0+ 6.3 - Bad args
. . . ATTENDEE 0+
. . . SEQUENCE 0 or 1 MUST be present if value is
greater than 0, MAY be
present if 0
. . . SUMMARY 1 Can be null.
. . . UID 1
. . . ATTACH 0+
. . . CATEGORIES 0 or 1 This property may contain a
list of values
. . . CLASS 0 or 1
. . . COMMENT 0 or 1
. . . CONTACT 0+
. . . CREATED 0 or 1
. . . DESCRIPTION 0 or 1 Can be null
. . . DTSTAMP 1
. . . DTSTART 1
. . . DUE 0 or 1 If present DURATION MUST
NOT be present
. . . DURATION 0 or 1 If present DUE MUST NOT be
present
. . . EXDATE 0+
. . . EXRULE 0+
. . . GEO 0 or 1
. . . LAST-MODIFIED 0 or 1
. . . LOCATION 0 or 1
. . . METHOD 1 <<placeholder. it may move
to meta-info>>
. . . ORGANIZER 1
. . . PRIORITY 1
. . . PERCENT-COMPLETE 0 or 1
. . . RDATE 0+
. . . RECURRENCE-ID 0 or 1 MUST only if referring to
an instance of a recurring
calendar component.
Otherwise it MUST NOT
be present.
. . . RELATED-TO 0+
. . . REQUEST-STATUS 0
. . . RESOURCES 0 or 1 This property may contain a
list of values
. . . RRULE 0+
. . . STATUS 0 or 1 MAY be one of COMPLETED,
NEEDS-ACTION,
IN-PROCESS, CANCELLED
. . . URL 0 or 1
. . . X-PROPERTY 0+ The "data" element of each "result" message is subject to the
. . . [IANA-PROP] 0+ any IANA registered restriction table defined below.
property
. . . VALARM 0+ The "modify" command is used to modify existing components. The
. . . . ACTION 1 "select" element specifies the components to modify. The "add",
. . . . ALARMID 0 or 1 MUST be 1 if multiple "remove" and "update" elements define the operations to perform.
VALARMs are present in
same component.
. . . . ATTACH 0+
. . . . DESCRIPTION 0 or 1
. . . . DURATION 0 or 1 if present REPEAT MUST be
present
. . . . REPEAT 0 or 1 if present DURATION MUST be
present
. . . . SUMMARY 0 or 1
. . . . TRIGGER 1
. . . . X-PROPERTY 0+
. . . . [IANA-PROP] 0+ any IANA registered
property
. . VJOURNAL 0+ The "add" element is used to add properties or nested components to
. . . ATTENDEE 0 the selected components. The "add" element is composed of a "data"
. . . DESCRIPTION 1 Can be null. element that contains a component with the properties to add. For
. . . DTSTAMP 1 example to add an inline attachment to a VEVENT the following
. . . DTSTART 1 iCalendar object could be:
. . . ORGANIZER 1
. . . UID 1
. . . ATTACH 0+ BEGIN:VCALENDAR
. . . CATEGORIES 0 or 1 This property MAY contain a BEGIN:VEVENT
list of values ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY:
. . . CLASS 0 or 1 MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U
. . . COMMENT 0 or 1 EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE
. . . CONTACT 0+ <...remainder of "BASE64" encoded binary data...>
. . . CREATED 0 or 1 END:VEVENT
. . . EXDATE 0+ END:VCALENDAR
. . . EXRULE 0+
. . . LAST-MODIFIED 0 or 1
. . . METHOD 1 <<placeholder. it may move
to meta-info>>
. . . RDATE 0+
. . . RECURRENCE-ID 0 or 1 MUST only if referring to
an instance of a recurring The "remove" element is used to remove properties from the selected
calendar component. components. The "data" element contains an iCalendar with the
Otherwise it MUST NOT be properties to delete. When the "ignore-value" attribute is set to
present. true, all the properties specified in the "data" element are removed
. . . RELATED-TO 0+ even if the values do not match the current state of the component.
. . . RRULE 0+ This is useful to remove potentially large properties efficiently
. . . SEQUENCE 0 or 1 MUST be present if non- (e.g., "ATTACH").
zero. MAY be
. . . . . present if zero.
. . . STATUS 0 or 1 The "update" element is used to update or add the properties referred
. . . SUMMARY 0 or 1 Can be null to by the "data" element. If the "remove-missing" attribute is set
. . . URL 0 or 1 to true, then all the elements not present in the "data" element
. . . X-PROPERTY 0+ document will be removed from the selected components.
. . . [IANA-PROP] 0+ any IANA registered
property
. . VFREEBUSY 0 When more than one operations is specified, the modifications MUST
must respect the following order: "remove" followed by "update"
followed by "add". The modifications MUST only be applied if the
resulting component respects the restriction table of the "create"
command.
. . VTIMEZONE 0+ MUST be present if any Restriction Table for "data" element of the "result" response:
date/time refers
to a timezone
. . . DAYLIGHT 0+ MUST be one or more of
either STANDARD
or DAYLIGHT
. . . . . COMMENT 0 or 1
. . . . . DTSTART 1
. . . . . RDATE 0+ if present RRULE MUST NOT
be present
. . . . . RRULE 0+ if present RDATE MUST NOT
be present
. . . . . TZNAME 0 or 1
. . . . . TZOFFSET 1
. . . . . TZOFFSETFROM 1
. . . . . TZOFFSETTO 1
. . . . . X-PROPERTY 0+
. . . . . [IANA-PROP] 0+ any IANA registered
property
. . . LAST-MODIFIED 0 or 1
. . . STANDARD 0+
. . . . . COMMENT 0 or 1
. . . . . DTSTART 1
. . . . . RDATE 0+ if present RRULE MUST NOT
be present
. . . . . RRULE 0+ if present RDATE MUST NOT
be present
. . . . . TZNAME 0 or 1
. . . . . TZOFFSETFROM 1
. . . . . TZOFFSETTO 1
. . . . . X-PROPERTY 0+
. . . . . [IANA-PROP] 0+ any IANA registered
property
. . . TZID 1
. . . TZURL 0 or 1
. . . X-PROPERTY 0+
. . . [IANA-PROP] 0+ any IANA registered
property
Server Restriction Table for the MODIFY command
Component/Property Presence Comment Component/Property Presence Comment
--------------------- -------- -------------------------- ------------------- -------- -------------------------------
VCAP 1+ VCALENDAR 1+
. VCALENDAR 1+ . VERSION 1 MUST be 2.1
. . TARGET 1
. . VERSION 1 MUST be 2.0 . VAGENDA 0+
. . RELCALID 1
. . REQUEST-STATUS 1+
. . CMDID 0 or 1 MUST be returned if the . VCAR 0+
request contained a CMDID . . CARID 1
. . REQUEST-STATUS 0 if not creating a calendar . . REQUEST-STATUS 1+
1+ if creating a calendar
. . . VCAR 0+ . VEVENT 0+
. . . . REQUEST-STATUS 1+ . . UID 1
. . . . * 0 No other VCAR properties are . . RECURRENCE-ID 0 or 1 MUST be specified only if instance of
present a recurring component was modified.
. . . REQUEST-STATUS 1+
. . . VCOMMAND 0
. . . VEVENT 0+ . . VALARM 0 if VEVENT was successfully
. . . . REQUEST-STATUS 1+
. . . . * 0 No other VEVENT properties
are present
. . . . VALARM 0 if VEVENT was successfully
saved saved
1+ if there were errors saving 1+ if there were errors saving
alarms alarms
. . . . . REQUEST-STATUS 1+ . . . REQUEST-STATUS 1+
. . . VFREEBUSY 0+ . VFREEBUSY 0
. . . . REQUEST-STATUS 1+
. . . . * 0 No other VFREEBUSY
properties are
present
. . . VJOURNAL 0+ . VJOURNAL 0+
. . . . REQUEST-STATUS 1+ . . UID 1
. . . . * 0 No other VJOURNAL properties . . RECURRENCE-ID 0 or 1 MUST be specified only if instance of
are present a recurring component was modified.
. . REQUEST-STATUS 1+
. . . VQUERY 0+ . VQUERY 0+
. . . . REQUEST-STATUS 1+ . . REQUEST-STATUS 1+
. . . . * 0 No other VQUERY properties
are present
. . . VTODO 0+ . VTODO 0+
. . . . REQUEST-STATUS 1+ . . UID 1
. . . . * 0 No other VTODO properties . . RECURRENCE-ID 0 or 1 MUST be specified only if instance of
are present a recurring component was modified.
. . . . VALARM 0 if VTODO was successfully . . REQUEST-STATUS 1+
. . VALARM 0 if VTODO was successfully
saved saved
1+ if there were errors saving 1+ if there were errors saving
alarms alarms
. . . . . REQUEST-STATUS 1+ . . . REQUEST-STATUS 1+
[EDITORS NOTES: Issues: freebusy - a cap server should dynamically
calculate freebusy information we recommend that you cannot create,
modify, or delete freebusy composers ]
In the example below, the start and end time of the event with UID In the example below, the start and end time of the event with UID
abcd12345 is changed and the LOCATION property is removed. abcd12345 is changed and the LOCATION property is removed.
C: SENDDATA C: MSG 1 11 . 8161 1144
C: Content-type:text/calendar; Method=MODIFY; C: Content-Type: multipart/related; boundary="boundary-324dav";
C: Component=VCOMMAND C: start="1@cal.example.com";
C: type="application/beep+xml"
C: C:
C: BEGIN:VCAP C: --boundary-324dav
C: VERSION:2.1 C: Content-Type: application/beep+xml
C: BEGIN:VCOMMAND C: Content-ID: 1@cal.cal.example.com
C: METHOD:MODIFY C:
C: TARGET:relcal2 C: <modify id="modify01"/>
C: BEGIN:VCOMMAND C: <select>
C: <source owner="user@cal.example.com" depth=*/>
C: <data content="cid:query@cal.example.com"/>
C: </select>
C: <remove ignore-value=true>
C: <data content="remove@cal.example.com"/>
C: </remove>
C: <update remove-missing=false>
C: <data content="cid:update@cal.example.com"/>
C: </update>
C: </modify>
C: --boundary-324dav
C: Content-Type: text/calendar
C: Content-ID: query@cal.example.com
C:
C: BEGIN:VCALENDAR
C: BEGIN:VQUERY C: BEGIN:VQUERY
C: QUERY:SELECT UID FROM VEVENT WHERE UID = 'abcd12345' C: QUERY: SELECT * FROM VEVENT WHERE UID='abcd12345'
C: END:VQUERY C: END:VQUERY
C: END:VCALENDAR
C: --boundary-324dav
C: Content-Type: text/calendar
C: Content-ID: remove@cal.example.com
C:
C: BEGIN:VCALENDAR
C: BEGIN:VEVENT C: BEGIN:VEVENT
C: DTSTART:19990421T160000Z C: LOCATION:
C: DTEND:19990421T163000Z
C: LOCATION:Joe's Diner
C: END:VCOMMAND
C: END:VEVENT
C: END:VEVENT
C: END:VCALENDAR
C: --boundary-324dav
C: Content-Type: text/calendar
C: Content-ID: update@cal.example.com
C:
C: BEGIN:VCALENDAR
C: BEGIN:VEVENT C: BEGIN:VEVENT
C: DTSTART:19990421T160000Z C: DTSTART:19990421T160000Z
C: DTEND:19990421T163000Z C: DTEND:19990421T163000Z
C: END:VEVENT C: END:VEVENT
C: END:VCOMMAND C: END:VCALENDAR
C: END:VCAP C: --boundary-324dav--
C: . C: END
S: RPY 1 11 . 9305 570
S: 2.0 cap://cal.example.com/relcal2 S: Content-Type: multipart/related; boundary="boundary-tvx2";
S: start="command@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-tvx2
S: Content-Type: application/beep+xml
S: Content-ID: command@cal.example.com
S:
S: <result id="modify01">
S: <source owner="user@cal.example.com"/>
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-tvx2
S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S:
S: BEGIN:VCALENDAR
S: BEGIN:VEVENT
S: UID:abcd12345
S: REQUEST-STATUS: 2.0
S: END:VEVENT
S: END:VCALENDAR
S: --boundary-tvx2--
S: END
And in this example, all instances of "Building 6" are replaced by In this example, all instances of "Building 6" are replaced by "New
"New office lobby" in VEVENTs: office lobby" in VEVENTs:
C: SENDDATA C: MSG 1 12 . 9875 870
C: Content-type:text/calendar; Method=MODIFY; C: Content-Type: multipart/related; boundary="boundary-trew2";
C: Component=VCOMMAND C: start="1@cal.example.com";
C: type="application/beep+xml"
C: C:
C: BEGIN:VCAP C: --boundary-trew2
C: VERSION:2.1 C: Content-Type: application/beep+xml
C: BEGIN:VCOMMAND C: Content-ID: 1@cal.example.com
C: METHOD:MODIFY C:
C: TARGET:relcal2 C: <modify id="modify02"/>
C: BEGIN:VCOMMAND C: <select>
C: BEGIN:VEVENT C: <source owner="user@cal.example.com" depth=*/>
C: LOCATION:Building 6 C: <data content="cid:query@cal.example.com"/>
C: END:VEVENT C: </select>
C: <update remove-missing=false>
C: <data content="cid:update@cal.example.com"/>
C: </update>
C: </modify>
C: --boundary-trew2
C: Content-Type: text/calendar
C: Content-ID: query@cal.example.com
C:
C: BEGIN:VCALENDAR
C: BEGIN:VQUERY
C: QUERY: SELECT * FROM VEVENT WHERE LOCATION='Building 6'
C: END:VQUERY
C: END:VCALENDAR
C: --boundary-trew2
C: Content-Type: text/calendar
C: Content-ID: update@cal.example.com
C:
C: BEGIN:VCALENDAR
C: BEGIN:VEVENT C: BEGIN:VEVENT
C: LOCATION:New office lobby C: LOCATION:New office lobby
C: END:VEVENT C: END:VEVENT
C: END:VCOMMAND C: END:VCALENDAR
C: END:VCOMMAND C: --boundary-trew2--
C: END:VCAP C: END
C: . S: RPY 1 12 . 10745 578
S: 2.0 cap://cal.example.com/relcal2 S: Content-Type: multipart/related; boundary="boundary-poiu51";
S: start="command@cal.example.com";
7.2.1.6 MOVE Method S: type="application/beep+xml"
S:
S: --boundary-poiu51
S: Content-Type: application/beep+xml
S: Content-ID: command@cal.example.com
S:
S: <result id="modify02">
S: <source owner="user@cal.example.com"/>
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-poiu51
S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S:
S: BEGIN:VCALENDAR
S: BEGIN:VEVENT
S: UID:abcd12345
S: REQUEST-STATUS: 2.0
S: END:VEVENT
S: END:VCALENDAR
S: --boundary-poiu51--
S: END
Arguments: ContainerId 6.2.4.4 "move" Command
Data: data as described below Attributes:
Result: "id" (see Section 6.2.2.1).
2.0 - success Elements:
2.2 - will attempt operation on the remote CAP server "max-time": See Section 3.3.
Permission "target": The "target" element points to the container where the
components are to be relocated.
Calendar already exists "select": identifies the component(s) to move.
Bad args Response:
Parent Calendar(s) not found One "result" message for each "source" in the "select" element is
The format of the command is: returned (see Section 3.1).
BEGIN:VCALENDAR One of the following "request-status" codes MUST be returned:
METHOD:MOVE
...
TARGET:target-name
BEGIN:VCOMMAND
BEGIN:VCALENDAR
PARENT:<old-parent>
END:VCALENDAR
BEGIN:VCALENDAR
PARENT:<new-parent>
END:VCALENDAR
END:VCOMMAND
END:VCALENDAR
This looks similar to a MODIFY command. Except the CS MUST ensure 2.0 - successfully created the component or calendar
that VCARs are still valid after the move. And the CS MUST update
the CHILDREN list in the new and old parent containers.
This method is used to move a calendar within the CS's hierarchy of 6.1 - Container not found
calendars.
Restriction Table 6.3 - Bad args
Component/Property Presence Comment The "data" element of each "result" message is subject to the
------------------- -------- --------------------- result restriction table defined below.
VCAP 1+ The CUA can send up
PIPELINE commands without
processing a response
. VERSION 1 MUST be 2.0 The "move" command is used to move components within the CS's
hierarchy of calendars. When moving VAGENDA, the CS MUST ensure that
VCARs are still valid after the move, and the CS MUST update the
PARENT and CHILDREN properties of the new and old parent containers.
. VCOMMAND 1 MUST have at least one Restriction Table for "data" element of the "result" response:
VCALENDAR
. . CMDID 0 or 1 If CMDID is not supplied, Component/Property Presence Comment
then there must not be ------------------- -------- -------------------------------
pending replies to
previous command.
. . [IANA-PROP] 0+ any IANA registered VCALENDAR 1+
property . VERSION 1 MUST be 2.1
. . METHOD 1 MUST be MOVE. . VAGENDA 0+
. . TARGET 1 MUST be a the CSID or . . RELCALID 1
CALID . . REQUEST-STATUS 1+
. . VCALENDAR 1+
. . . CALMASTER 0
. . . NAME 0
. . . OWNER 0
. . . RELCALID 1
. . . TZID 0
. . . [IANA-PROP] 0+ any IANA registered
property
Server Restriction Table for the MOVE command . VCAR 0+
. . CARID 1
. . REQUEST-STATUS 1+
Component/Property Presence Comment . VEVENT 0+
------------------- -------- ----------------------------- . . UID 1
. . REQUEST-STATUS 1+
VCAP 1+ . . VALARM 0 if VEVENT was successfully
saved
1+ if there were errors saving
alarms
. . . ALARMID 1
. . . REQUEST-STATUS 1+
. VCALENDAR 1+ . VFREEBUSY 0
. . TARGET 1 . VJOURNAL 0+
. . VERSION 1 MUST be 2.0 . . UID 1
. . REQUEST-STATUS 1+
. . CMDID 0 or 1 MUST be returned if the . VQUERY 0+
request contained
a CMDID
. . REQUEST-STATUS 1+ . . REQUEST-STATUS 1+
. VTODO 0+
. . UID 1
. . REQUEST-STATUS 1+
. . VALARM 0 if VTODO was successfully
saved
1+ if there were errors saving
alarms
. . . ALARMID 1
. . . REQUEST-STATUS 1+
--------------------------------------------------------- ---------------------------------------------------------
[EDITORS NOTE: Issues: [EDITORS NOTE: Issues:
1) Should one be able to move a calendar owned by person X into a 1) Should one be able to move a calendar owned by person X into a
calendar owned by person Y. (Can these such rights be specified calendar owned by person Y. (Can these such rights be specified
in VCARs?) in VCARs?)
2) Should we also be able to move components from one calendar to Example: moving the VAGENDA Nellis to Area-51
another? What if the calendars are owned by different users? (With
components one can do a copy, then delete the original.)
3) There was very little information about MOVE in CAP. Why was
it added? Was there some major need for it?
4) Can one move multiple calendars into one calendar?]
An example of moving a calendar from Nellis to Area-51
C: SENDDATA C: MSG 1 12 . 11323 613
C: Content-type:text/calendar; Method=MODIFY; Component=VCOMMAND C: Content-Type: multipart/related; boundary="boundary-kljr";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary-kljr
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <move id="move01"/>
C: <select>
C: <source csid="cal@example.com" depth=*>
C: <data content="cid:query@cal.example.com"/>
C: </select>
C: <target relcalid="area-51"/>
C: </move>
C: --boundary-kljr
C: Content-Type: text/calendar
C: Content-ID: query@cal.example.com
C: C:
C: BEGIN:VCAP
C: VERSION:2.1
C: METHOD:MOVE
C: TARGET:Nellis
C: BEGIN:VCOMMAND
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: PARENT:Department-33 C: BEGIN:VQUERY
C: END:VCALENDAR C: QUERY: SELECT * FROM VAGENDA WHERE RELCALID='Nellis'
C: BEGIN:CALENDAR C: END:VQUERY
C: PARENT:Area-51
C: END:VCALENDAR C: END:VCALENDAR
C: END:VCOMMAND C: --boundary-kljr--
C: END:VCAP C: END
C: . S: RPY 1 2 . 11936 571
S: 2.0 S: Content-Type: multipart/related; boundary="boundary-mnbvd";
S: Content-Type:text/calendar; method=RESPONSE S: start="reply@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-mnbvd
S: Content-Type: application/beep+xml
S: Content-ID: reply@cal.example.com
S:
S: <result id="move01">
S: <source csid=cal@example.com depth=*>
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-mnbvd
S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S: S:
S: BEGIN:VCAP
S: METHOD:RESPONSE
S: TARGET:relcal2
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: REQUEST-STATUS:2.0; S: BEGIN:VAGENDA
S: RELCALID:Nellis
S: REQUEST-STATUS: 2.0
S: END:VAGENDA
S: END:VCALENDAR S: END:VCALENDAR
S: END:VCAP S: --boundary-mnbvd--
S: . S: END
7.2.1.7 READ Method
Arguments: ContainerId
Data: data as described below
Result:
2.0 - - successful and the requested data follows
2.2 - will attempt read on the remote CAP server
Permission
Bad args
Restriction Table
Component/Property Presence Comment
------------------- -------- ---------------------------
VCAP 1+ The CUA can send
PIPELINE commands
without processing a
response
. VERSION 1 MUST be 2.0
. [IANA-PROP] 0+ any IANA registered
property
. VCOMMAND 1 MUST have at least one
container (VCALENDAR,
VCAR, VQUERY, VEVENT,
VTODO, VJOURNAL)
. . CMDID 0 or 1 If CMDID is not supplied,
then there must not be pending
replies to previous command.
. . [IANA-PROP] 0+ any IANA registered
property
. . METHOD 1 MUST be READ
. . TARGET 1+ MUST be the CALID
. . VCALENDAR 0+
. . . CALMASTER 0 or 1
. . . NAME 0 or 1
. . . OWNER 1+
. . . RELCALID 1
. . . TZID 0 or 1
. . . [IANA-PROP] 0+ any IANA registered
property
. . VCAR 0
. . VQUERY 1
. . . EXPAND 0 or 1
. . . MAXRESULTS 0 or 1
. . . MAXSIZE 0 or 1
. . . QUERYNAME 1
. . . QUERY 1
. . . [IANA-PROP] 0+ any IANA registered
property
. . VEVENT 0 6.2.4.5 "search" Command
. . VTODO 0
. . VJOURNAL 0
. . VFREEBUSY 0
. . VTIMEZONE 0+ MUST be present if any Attributes:
date/time refers
to a timezone
. . . DAYLIGHT 0+ MUST be one or more of
either STANDARD
or DAYLIGHT
. . . . . COMMENT 0 or 1
. . . . . DTSTART 1
. . . . . RDATE 0+ if present RRULE MUST NOT
be present
. . . . . RRULE 0+ if present RDATE MUST NOT
be present "id" (see Section 6.2.2.1).
. . . . . TZNAME 0 or 1
. . . . . TZOFFSET 1
. . . . . TZOFFSETFROM 1
. . . . . TZOFFSETTO 1
. . . . . X-PROPERTY 0+
. . . . . [IANA-PROP] 0+ any IANA registered
property
. . . LAST-MODIFIED 0 or 1
. . . STANDARD 0+
. . . . . COMMENT 0 or 1
. . . . . DTSTART 1
. . . . . RDATE 0+ if present RRULE MUST NOT
be present
. . . . . RRULE 0+