draft-ietf-calsch-cap-06.txt   draft-ietf-calsch-cap-07.txt 
Network Working Group S. Mansour Network Working Group S. Mansour
Internet-Draft AOL/Netscape Internet-Draft AOL/Netscape
Expires: May 21, 2002 D. Royer Expires: August 30, 2002 D. Royer
INET-Consulting LLC INET-Consulting LLC
G. Babics G. Babics
Steltor Steltor
P. Hill P. Hill
Massachusetts Institute of Massachusetts Institute of
Technology Technology
November 20, 2001 March 01, 2002
Calendar Access Protocol (CAP) Calendar Access Protocol (CAP)
draft-ietf-calsch-cap-06 draft-ietf-calsch-cap-07
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.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
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://
http://www.ietf.org/ietf/1id-abstracts.txt. 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 May 21, 2002. This Internet-Draft will expire on August 30, 2002.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved. Copyright (C) The Internet Society (2002). 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 [RFC2445] based Calendar Store (CS). This memo defines
CAP specification. the CAP specification.
The CAP definition is based on requirements identified by the The CAP definition is based on requirements identified by the
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://
http://www.imc.org/ietf-calendar and at the IETF web site at www.imc.org/ietf-calendar and at the IETF web site at http://
http://www.ietf.org/html.charters/calsch-charter.html[1]. Refer to www.ietf.org/html.charters/calsch-charter.html [1]. Refer to the
the references within this memo for further information on how to references within this memo for further information on how to access
access these various documents. 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 . . . . . . . . . . . . . . . . . . . . . . . 12 2. CAP Design . . . . . . . . . . . . . . . . . . . . . . 12
2.1 System Model . . . . . . . . . . . . . . . . . . . . . . 12 2.1 System Model . . . . . . . . . . . . . . . . . . . . . 12
2.2 Calendar Store Object Model . . . . . . . . . . . . . . 12 2.2 Calendar Store Object Model . . . . . . . . . . . . . 12
2.3 Protocol Model . . . . . . . . . . . . . . . . . . . . . 13 2.3 Protocol Model . . . . . . . . . . . . . . . . . . . . 13
2.4 Security Model . . . . . . . . . . . . . . . . . . . . . 14 2.4 Security Model . . . . . . . . . . . . . . . . . . . . 14
2.4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . . 14 2.4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . 14
2.4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . . 14 2.4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . 14
2.4.1.2 Anonymous Users and Authentication . . . . . . . . . . . 16 2.4.1.2 Anonymous Users and Authentication . . . . . . . . . . 15
2.4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . . 16 2.4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . 16
2.4.2 Access Rights - Summary . . . . . . . . . . . . . . . . 16 2.4.2 Access Rights - Summary . . . . . . . . . . . . . . . 16
2.4.2.1 Calendar Access Right (VCAR) . . . . . . . . . . . . . . 17 2.4.2.1 Calendar Access Right (VCAR) . . . . . . . . . . . . . 16
2.4.2.2 Decreed VCARs . . . . . . . . . . . . . . . . . . . . . 17 2.4.2.2 Predefined VCARs . . . . . . . . . . . . . . . . . . . 17
2.4.3 Inheritance . . . . . . . . . . . . . . . . . . . . . . 18 2.4.2.3 Decreed VCARs . . . . . . . . . . . . . . . . . . . . 18
2.4.4 CAP Session Identity . . . . . . . . . . . . . . . . . . 18 2.4.3 CAP Session Identity . . . . . . . . . . . . . . . . . 19
2.5 Roles . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.5 Roles . . . . . . . . . . . . . . . . . . . . . . . . 20
2.6 Calendar Addresses . . . . . . . . . . . . . . . . . . . 19 2.6 CAP URL . . . . . . . . . . . . . . . . . . . . . . . 20
2.7 Extensions to iCalendar . . . . . . . . . . . . . . . . 20 2.7 Calendar Addresses . . . . . . . . . . . . . . . . . . 21
2.8 Relationship of RFC 2446 (ITIP) to CAP . . . . . . . . . 20 2.8 Extensions to iCalendar . . . . . . . . . . . . . . . 21
3. Protocol Framework . . . . . . . . . . . . . . . . . . . 22 2.9 Relationship of RFC 2446 (ITIP) to CAP . . . . . . . . 21
3.1 BEEP Exchange Styles . . . . . . . . . . . . . . . . . . 22 3. Protocol Framework . . . . . . . . . . . . . . . . . . 23
3.2 Use of XML, MIME and iCalendar . . . . . . . . . . . . . 22 3.1 BEEP Exchange Styles . . . . . . . . . . . . . . . . . 23
3.3 Bounded Latency . . . . . . . . . . . . . . . . . . . . 23 3.2 Use BEEP, MIME and iCalendar . . . . . . . . . . . . . 23
4. Formal Command Syntax . . . . . . . . . . . . . . . . . 26 3.3 Bounded Latency . . . . . . . . . . . . . . . . . . . 24
4.1 Searching and Filtering . . . . . . . . . . . . . . . . 26 4. New Value Types . . . . . . . . . . . . . . . . . . . 27
4.1.1 Grammar For Search Mechanism . . . . . . . . . . . . . . 26 4.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . . 27
4.1.2 SQL-MIN notes . . . . . . . . . . . . . . . . . . . . . 27 4.1.1 CAP-QL notes . . . . . . . . . . . . . . . . . . . . . 31
4.1.3 Querying Experminental Properties . . . . . . . . . . . 28 4.2 CAP-QL notes . . . . . . . . . . . . . . . . . . . . . 37
4.1.4 Example, Query by UID . . . . . . . . . . . . . . . . . 28 4.3 Example, Query by UID . . . . . . . . . . . . . . . . 42
4.1.5 Query by Date-Time range . . . . . . . . . . . . . . . . 29 4.4 Query by Date-Time range . . . . . . . . . . . . . . . 42
4.1.6 Query for all Non-Booked Entries . . . . . . . . . . . . 29 4.5 Query for all Non-Booked Entries . . . . . . . . . . . 43
4.1.7 Query with Subset of Properties by Date/Time . . . . . . 29 4.6 Query with Subset of Properties by Date/Time . . . . . 44
4.1.8 Components With Alarms In A Range . . . . . . . . . . . 30 4.7 Components With Alarms In A Range . . . . . . . . . . 44
5. Access Rights . . . . . . . . . . . . . . . . . . . . . 31 5. Access Rights . . . . . . . . . . . . . . . . . . . . 45
5.1 VCAR Inheritance . . . . . . . . . . . . . . . . . . . . 31 5.1 Access Control and NOCONFLICT . . . . . . . . . . . . 45
5.2 Access Control and NOCONFLICT . . . . . . . . . . . . . 31 6. Commands and Responses . . . . . . . . . . . . . . . . 46
6. Commands and Responses . . . . . . . . . . . . . . . . . 32 6.1 Session Commands . . . . . . . . . . . . . . . . . . . 46
6.1 Session Commands . . . . . . . . . . . . . . . . . . . . 32 6.1.1 "generate-uid" Command . . . . . . . . . . . . . . . . 46
6.1.1 "generate-uid" Command . . . . . . . . . . . . . . . . . 32 6.1.2 "get-capability" Command . . . . . . . . . . . . . . . 47
6.1.2 "get-capability" Command . . . . . . . . . . . . . . . . 33 6.1.3 "identify" Command . . . . . . . . . . . . . . . . . . 49
6.1.3 "identify" Command . . . . . . . . . . . . . . . . . . . 35 6.1.4 "noop" Command . . . . . . . . . . . . . . . . . . . . 50
6.1.4 "noop" Command . . . . . . . . . . . . . . . . . . . . . 35 6.2 Calendaring and Scheduling Commands . . . . . . . . . 51
6.2 Calendaring and Scheduling Commands . . . . . . . . . . 36 6.2.1 Restriction Tables . . . . . . . . . . . . . . . . . . 51
6.2.1 Restriction Tables . . . . . . . . . . . . . . . . . . . 36 6.2.2 Calendaring Commands . . . . . . . . . . . . . . . . . 52
6.2.2 Common Attributes . . . . . . . . . . . . . . . . . . . 37 6.2.2.1 "create" Command . . . . . . . . . . . . . . . . . . . 52
6.2.2.1 "id" Attribute . . . . . . . . . . . . . . . . . . . . . 37 6.2.2.2 "move" Command . . . . . . . . . . . . . . . . . . . . 57
6.2.3 Common Elements . . . . . . . . . . . . . . . . . . . . 37 6.2.2.3 "delete" Command . . . . . . . . . . . . . . . . . . . 60
6.2.3.1 "data" Element . . . . . . . . . . . . . . . . . . . . . 37 6.2.2.4 "modify" Command . . . . . . . . . . . . . . . . . . . 62
6.2.3.2 "select" Element . . . . . . . . . . . . . . . . . . . . 37 6.2.2.5 "search" Command . . . . . . . . . . . . . . . . . . . 66
6.2.3.3 "source" Element . . . . . . . . . . . . . . . . . . . . 39 6.2.2.6 Response Codes . . . . . . . . . . . . . . . . . . . . 71
6.2.3.4 "target" Element . . . . . . . . . . . . . . . . . . . . 39 7. Initial Registrations . . . . . . . . . . . . . . . . 73
6.2.4 Calendaring Commands . . . . . . . . . . . . . . . . . . 40 7.1 BEEP Profile Registration . . . . . . . . . . . . . . 73
6.2.4.1 "create" Command . . . . . . . . . . . . . . . . . . . . 40 7.2 Registration: The System (Well-Known) TCP port number
6.2.4.2 "delete" Command . . . . . . . . . . . . . . . . . . . . 50 for CAP . . . . . . . . . . . . . . . . . . . . . . . 73
6.2.4.3 "modify" Command . . . . . . . . . . . . . . . . . . . . 53 8. CAP DTD . . . . . . . . . . . . . . . . . . . . . . . 75
6.2.4.4 "move" Command . . . . . . . . . . . . . . . . . . . . . 59 9. Properties . . . . . . . . . . . . . . . . . . . . . . 76
6.2.4.5 "search" Command . . . . . . . . . . . . . . . . . . . . 62 9.1 Calendar Store Properties . . . . . . . . . . . . . . 76
6.3 Scheduling Commands . . . . . . . . . . . . . . . . . . 72 9.2 Calendar Properties . . . . . . . . . . . . . . . . . 77
6.3.1 "schedule" Command . . . . . . . . . . . . . . . . . . . 72 10. Security Considerations . . . . . . . . . . . . . . . 80
6.3.2 Processing Scheduling Components . . . . . . . . . . . . 74 11. Extensions To iCalendar . . . . . . . . . . . . . . . 81
6.3.3 iTIP Examples . . . . . . . . . . . . . . . . . . . . . 76 11.1 Property Value Data Types . . . . . . . . . . . . . . 81
6.3.3.1 Sending and Receiving an iTIP request . . . . . . . . . 76 11.1.1 UPN . . . . . . . . . . . . . . . . . . . . . . . . . 81
6.3.3.2 Handling an iTIP refresh . . . . . . . . . . . . . . . . 81 11.1.2 UPN Filter . . . . . . . . . . . . . . . . . . . . . . 82
6.3.3.3 Sending and accepting an iTIP counter . . . . . . . . . 83 11.2 Calendar Components . . . . . . . . . . . . . . . . . 83
6.3.3.4 Declining an iTIP counter . . . . . . . . . . . . . . . 86 11.2.1 Agenda Component . . . . . . . . . . . . . . . . . . . 83
7. Response Codes . . . . . . . . . . . . . . . . . . . . . 89 11.2.2 Calendar Store Component . . . . . . . . . . . . . . . 84
8. BEEP Profile Registration . . . . . . . . . . . . . . . 91 11.2.3 Calendar Access Right Component . . . . . . . . . . . 85
9. CAP DTD . . . . . . . . . . . . . . . . . . . . . . . . 92 11.2.4 VRIGHT Calendar Component . . . . . . . . . . . . . . 88
10. Implementation Issues . . . . . . . . . . . . . . . . . 95 11.3 Component Properties . . . . . . . . . . . . . . . . . 89
11. Properties . . . . . . . . . . . . . . . . . . . . . . . 96 11.3.1 Allow-Conflict Component Property . . . . . . . . . . 89
11.1 Calendar Store Properties . . . . . . . . . . . . . . . 96 11.3.2 Charset Component Property . . . . . . . . . . . . . . 90
11.2 Calendar Properties . . . . . . . . . . . . . . . . . . 97 11.3.3 Default Locale Component Property . . . . . . . . . . 91
12. CAP Item Registration . . . . . . . . . . . . . . . . . 100 11.3.4 Default Time Zone Property . . . . . . . . . . . . . . 91
12.1 Registration of New and Modified CAP Entities . . . . . 100 11.3.5 Owner Component Property . . . . . . . . . . . . . . . 92
12.2 Registration of New Entities . . . . . . . . . . . . . . 100 11.3.6 Relative Calendar Identifier Component Property . . . 93
12.2.1 Define the Item . . . . . . . . . . . . . . . . . . . . 100 11.3.7 Calendar Store Component Properties . . . . . . . . . 94
12.2.2 Post the item definition . . . . . . . . . . . . . . . . 101 11.3.7.1 Calmaster Component Property . . . . . . . . . . . . . 94
12.2.3 Allow a comment period . . . . . . . . . . . . . . . . . 101 11.3.7.2 Calendar Store Identifier Component Property . . . . . 94
12.2.4 Submit the proposal for approval . . . . . . . . . . . . 101 11.3.7.3 Default Access Rights Component Property . . . . . . . 95
12.3 Property Change Control . . . . . . . . . . . . . . . . 102 11.3.7.4 Maximum Date Component Property . . . . . . . . . . . 96
13. IANA Considerations . . . . . . . . . . . . . . . . . . 103 11.3.7.5 Minimum Date Component Property . . . . . . . . . . . 97
Authors' Addresses . . . . . . . . . . . . . . . . . . . 103 11.3.8 Descriptive Component Properties . . . . . . . . . . . 97
A. Acknowledgments . . . . . . . . . . . . . . . . . . . . 105 11.3.8.1 REQUEST-STATUS property . . . . . . . . . . . . . . . 97
B. Bibliography . . . . . . . . . . . . . . . . . . . . . . 106 11.3.8.2 CALID Property Parameter . . . . . . . . . . . . . . . 98
Full Copyright Statement . . . . . . . . . . . . . . . . 108 11.3.8.3 Time Transparency . . . . . . . . . . . . . . . . . . 99
11.3.8.4 Name Component Property . . . . . . . . . . . . . . . 100
11.3.9 Calendar Access Right Component Properties . . . . . . 101
11.3.9.1 VCAR Identifier Component Property . . . . . . . . . . 101
11.3.9.2 VCAR Decreed Component Property . . . . . . . . . . . 102
11.3.10 Right Component Properties . . . . . . . . . . . . . . 102
11.3.10.1 Grant Component Property . . . . . . . . . . . . . . . 103
11.3.10.2 Deny Component Property . . . . . . . . . . . . . . . 103
11.3.10.3 Permission Component Property . . . . . . . . . . . . 104
11.3.10.4 Scope Component Property . . . . . . . . . . . . . . . 105
11.3.10.5 Restriction Component Property . . . . . . . . . . . . 106
12. CAP Item Registration . . . . . . . . . . . . . . . . 107
12.1 Registration of New and Modified CAP Entities . . . . 107
12.2 Registration of New Entities . . . . . . . . . . . . . 107
12.2.1 Define the Item . . . . . . . . . . . . . . . . . . . 107
12.2.2 Post the item definition . . . . . . . . . . . . . . . 108
12.2.3 Allow a comment period . . . . . . . . . . . . . . . . 108
12.2.4 Submit the proposal for approval . . . . . . . . . . . 108
12.3 Property Change Control . . . . . . . . . . . . . . . 109
13. IANA Considerations . . . . . . . . . . . . . . . . . 110
Authors' Addresses . . . . . . . . . . . . . . . . . . 111
A. Acknowledgments . . . . . . . . . . . . . . . . . . . 112
B. Bibliography . . . . . . . . . . . . . . . . . . . . . 113
Full Copyright Statement . . . . . . . . . . . . . . . 115
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.
CAP is specified as a BEEP "profile". As such many aspects of the CAP is specified as a BEEP "profile". As such many aspects of the
protocol (e.g., authentication and privacy) are provided within the protocol (e.g., authentication and privacy) are provided within the
BEEP core [BEEP]. The protocol data units leverage the standard [BEEP]. The protocol data units leverage the standard iCalendar
iCalendar format [iCAL] to convey calendar related information. format [RFC2445] to convey calendar related information.
CAP can also be used to store and fetch [iTIP] objects and when those
objects are used here in this memo, they mean exactly the same as
defined in [iTIP].
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 of Calendaring and scheduling roles are referred to in quoted-strings 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 [iTIP]. Calendar components defined
defined by [iCAL] are referred to with capitalized, quoted-strings of by [RFC2445] 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. daily journal calendar component.
Scheduling methods defined by [iTIP], are referred to with Scheduling methods defined by [iTIP], are referred to with
capitalized, quoted-strings of text. For example, "REPLY" refers to capitalized, quoted-strings of text. For example, "REPLY" refers to
the method for replying to a "REQUEST". the method for replying to a "REQUEST".
Calendar commands are referred by lower-case, quotes-strings of text, CAP commands are referred by lower-case, quotes-strings of text,
followed by the word "command". For example, "create" command refers 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 creating a calendar entry, "search" command refers
to the command for reading calendar components. 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 capitalized, 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
skipping to change at page 6, line 15 skipping to change at page 6, line 19
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
standards. These documents are: standards. These documents are:
[iCAL] (RFC2445) which specifies the objects, data types, properties [RFC2445] (RFC2445) which specifies the objects, data types,
and property parameters used in the protocols, along with the methods properties and property parameters used in the protocols, along with
for representing and encoding them, the methods 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].
[GUIDE] (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
skipping to change at page 6, line 40 skipping to change at page 6, line 44
This memo does not attempt to repeat the specification of concepts This memo does not attempt to repeat the specification of concepts
and definitions from these other memos. Where possible, references and definitions from these other memos. Where possible, references
are made to the memo that provides for the specification of these are made to the memo that provides for the specification of these
concepts and definitions. concepts and definitions.
1.3 Definitions 1.3 Definitions
Booked Booked
An entry in a calendar has one of two conceptual states. It is An entry in a calendar has one of three conceptual states. It
scheduled or it is booked. A scheduled entry has been stored in is scheduled, booked or marked for delete. A scheduled entry
the calendar store but has not been acted on by a calendar user has been stored in the calendar store but has not been acted on
(CU) or calendar user agent (CUA). A scheduled entry contains a by a calendar user (CU) or calendar user agent (CUA). A
METHOD property set to an [iTIP] method. A booked entry is a scheduled entry contains a METHOD property set to an [iTIP]
component does not have a METHOD property. method. A booked entry has its METHOD property set to CREATE.
A marked for delete component has its METHOD property set to
DELETE
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
day. These entities can include other calendar properties or of day. These entities can include other calendar properties
calendar components. In addition, a calendar might be or calendar components. In addition, a calendar might be
hierarchically related to other sub-calendars. A calendar is hierarchically related to other calendars with the RELATED-TO
identified by its unique calendar identifier. The [iCAL] defines property. A calendar is identified by its unique calendar
calendar properties, calendar components and component properties identifier. The [RFC2445] defines calendar properties,
that make up the content of a calendar. calendar components and component properties 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
to access and manipulate calendars residing on a Calendar Store. Agent to access and manipulate calendars residing on a Calendar
Store. (this memo)
Calendar Access Rights (CAR) Calendar Access Rights (CAR)
The mechanism for specifying the CAP operations ("ACTION") that a The mechanism for specifying the CAP operations ("PERMISSION")
particular calendar user ("UPN") are granted or denied permission that a particular calendar user ("UPN") is granted or denied
to perform on a given calendar object ("OBJECT"). The calendar permission to perform on a given calendar object ("SCOPE").
access rights are specified with the "VCAR" calendar components The calendar access rights are specified with the "VCAR"
within a CS and calendar. calendar components within a CS and calendar.
Calendar Component Calendar Component
An object within a calendar or a calendar store (CS). Some types An object within a calendar or a calendar store (CS). Some
of calendar components include calendars, events, to-dos, types of calendar components include calendars, events, to-dos,
journals, alarms, time zones and freebusy data. A calendar journals, alarms, time zones and freebusy data. A calendar
component consists of component properties and possibly other sub- component consists of component properties and possibly other
components. For example, an event may contain an alarm component. sub-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
components. For example, DTSTART is applicable to VEVENT, VTODO, calendar components. For example, DTSTART is applicable to
VJOURNAL calendar components. Other calendar components are VEVENT, VTODO, VJOURNAL calendar components. Other calendar
applicable only to an individual type of calendar component. For components are applicable only to an individual type of
example, TZURL is only applicable to VTIMEZONE calendar calendar component. For example, TZURL is only applicable to
components. VTIMEZONE calendar components.
Calendar Identifier (CalID) Calendar Identifier (CalID)
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
and Relative Calendar Identifier. Calendars reside within a CS. See Qualified Calendar
Identifier and Relative Calendar Identifier. All CalIDs start
with "cap:"
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
calendar. For example, "events MUST be scheduled in unit a calendar. These may be outside of the scope of the CAP
protocol. For example, "events MUST be scheduled in unit
intervals of one hour". intervals of one hour".
Calendar Property Calendar Property
An attribute of a calendar (VAGENDA). The attribute applies to An attribute of a calendar (VAGENDA). The attribute applies to
the 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
skipping to change at page 8, line 24 skipping to change at page 8, line 35
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 [RFC1738].
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. store-wide information.
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. 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 utilizes to access
The CUA is the client application that a CU utilizes to access and and manipulate a calendar.
manipulate a calendar.
CAP Session CAP Session
An open communication channel between a CUA and a Calendar An open communication channel between a CUA and a Calendar
Service. Service.
Contained Component / Contained Properties
A component or property that is contained inside a component.
VALARM for example may be contained inside of a VEVENT. And
TRIGGER is a contained property of a VALARM.
Delegate Delegate
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
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.
Fan Out
The calendaring and scheduling process by which a calendar
operation on one calendar is also performed on every other
calendar specified in the operation.
Hierarchical Calendars
A CS feature where a calendar has a hierarchical relationship with
another calendar in the CS. The top-most calendars in the
hierarchical relationship have the CS as their parent. There may
be multiple top-most calendars in a given CS. Within a given
hierarchical relationship, all sub-calendars have a calendar with
a "parent" relationship. In addition, sub-calendars may have a
relationship with another calendar that has a "child"
relationship. The hierarchical calendar feature is not a storage
relationship of the calendars within the CS. Instead it is a
feature that relates access control rights to calendar content
between different calendars in the CS. The hierarchical
relationship of a calendar is specified in the "PARENT" and
"CHILDREN" calendar properties.
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
one another. When the policy is applied to a calendar it overlap one another. When the policy is applied to a calendar
indicates whether or not the time span of any entry (VEVENT, it 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
entry in the same calendar. When applied to an individual entry, other entry in the same calendar. When applied to an
it indicates whether or not any other entry's time span can individual entry, it indicates whether or not any other entry's
overlap that individual entry. time span can 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 are listed in the "OWNER" calendar
for a calendar. The owner is specified in the "OWNER" calendar property in a calendar.
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. (e.g., 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.
is unique within a calendar store. It is recommended to be It MUST BE unique within a calendar store. A Relative CalID
globally unique. A Relative CalID consists of the portion of the consists of the portion of the "scheme part" of a Qualified
"scheme part" of a Qualified CalID following the Calendar Store CalID following the Calendar Store Identifier. This is the
Identifier. This is the same as the "URL path" of the "Common same as the "URL path" of the "Common Internet Scheme Syntax"
Internet Scheme Syntax" portion of a URL, as defined by [URL]. portion of a URL, as defined by [RFC1738].
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
after successful authentication. The identity is used in identity after successful authentication. The identity is used
combination with CAR to determine access to data in the CS. in combination with CAR to determine access to data in the CS.
Sub-calendars
Calendars that have a "child" hierarchical relationship with
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
are expanded by the CS and may reside either locally or in an groups are expanded by the CS and may reside either locally or
external database or directory. The group membership may be fixed in an external database or directory. The group membership may
or dynamic over time. be fixed or dynamic over time.
Username 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
of a UPN. part of a UPN.
User Principal Name (UPN) User Principal Name (UPN)
A unique identifier that denotes a CU or a group of CU. A UPN is A unique identifier that denotes a CU or a group of CU. A UPN
a RFC 822 compliant email address, with exceptions listed below, is a RFC 822 compliant email address, with exceptions listed
and in most cases it is deliverable to the CU. In some cases it below, and in most cases it is deliverable to the CU. In some
is identical to the CU's well known email address. A CU's UPN cases it is identical to the CU's well known email address. A
MUST never be an e-mail address that is deliverable to a different CU's UPN MUST never be an e-mail address that is deliverable to
person as there is no requirement that a person's UPN must be his a different person as there is no requirement that a person's
e-mail address. It consists of a Realm in the form of a valid, UPN must be his e-mail address. It consists of a Realm in the
and unique, DNS domain name and a unique Username. In it's form of a valid, and unique, DNS domain name and a unique
simplest form it looks like "user@example.com". Username. In it's 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
a UPN of the form @DNS-domain-name may be used. For example, obscured, a UPN of the form @DNS-domain-name may be used. For
"@example.com". Usage of these special cases is further discussed example, "@example.com". Usage of these special cases is
in the authentication and authorization sections of this document. further discussed 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". receive responses from a "Calendar Service".
The CUA prepares a [MIME] encapsulated command, sends it to the CS, The CUA prepares a [MIME] encapsulated command, sends it to the CS,
and receives a [MIME] encapsulated response. The calendaring related and receives a [MIME] encapsulated response. The calendaring related
information within these messages are represented by iCalendar information within these messages are represented by iCalendar
objects. objects.
There are two distinct protocols in operation to accomplish this There are two distinct protocols in operation to accomplish this
exchange. [BEEP] is used to move these encapsulations between a CUA exchange. [BEEP] is the transport protocol and is used to move
and a CS. The CAP profile defines the content and semantics of the these encapsulations between a CUA and a CS. CAP profile defines the
application protocol. That is, the content and semantics of the
messages sent between the CUA and the Calendar Service. messages sent between the CUA and the Calendar Service.
2.2 Calendar Store Object Model 2.2 Calendar Store Object Model
[RFC2445] describes components such as events, todos, alarms, and
timezones. [CAP] requires more object infrastructure. In
particular, detailed definitions of the containers for events and
todos (calendars), access control objects, and a query language.
[CAP] defines the following new objects which will be discussed in
detail in this memo
Component Description
--------- -----------------------------------------
VCAR An access control object
VQUERY A query object
VAGENDA A container that holds components and which is owned
by one or more CUs.
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 VCARs, VQUERYs, VTIMEZONEs, VAGENDAs and calendar store contains VCARs, VQUERYs, VTIMEZONEs, VAGENDAs and
calendar store properties. calendar store properties.
Calendars (VAGENDAs) contain VEVENTs, VTODOs, VJOURNALs, VCARs, Calendars (VAGENDAs) contain VEVENTs, VTODOs, VJOURNALs, VCARs,
VTIMEZONEs, VQUERYs and calendar properties. Calendars may also VTIMEZONEs, VQUERYs and calendar properties.
contain other calendars (VAGENDAs).
The special keyword VCALSTORE is used to denote the a root of the
calendar store. It is a point from which searches can begin. It is
the container for VTIMEZONEs, VQUERYs, and toplevel VAGENDAs.
Calendar Store Calendar Store
VCALSTORE
| |
+-- VCARs +-- VCARs
+-- VQUERYs +-- VQUERYs
+-- VTIMEZONEs +-- VTIMEZONEs
+-- VAGENDA +-- VAGENDA
| | | |
| +--VEVENTs | +--VEVENTs
| | | | | |
| | +--VALARMs | | +--VALARMs
| +--VTODOs | +--VTODOs
skipping to change at page 13, line 42 skipping to change at page 13, line 43
| | +--VTIMEZONEs | | +--VTIMEZONEs
| | +--VQUERYs | | +--VQUERYs
| | +--VFREEBUSY | | +--VFREEBUSY
| | +--VAGENDAs | | +--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 set of scheduling messages that have
not yet been applied to the calendar. Components in VSCHEDULE are
discussed in more detail below.
2.3 Protocol Model 2.3 Protocol Model
The commands listed below are used to manipulate the data on the The commands listed below are used to manipulate the data on the
calendar store. Their usage and semantics are defined in Section 6. calendar store.
CAP Commands CAP Commands
----------------------------------------------------------- -----------------------------------------------------------
Command Description Command Description
----------------------------------------------------------- -----------------------------------------------------------
create Create a new calendar component. create Create a new calendar component.
delete Delete calendar components. delete Delete calendar components.
generate-uid Generate one or more unique ids. generate-uid Generate one or more unique ids.
get-capability Query the capabilities of the CS. get-capability Query the capabilities the CAP server
identify Set a new identity for calendar access. identify Set a new identity for calendar access.
modify Modify calendar components. modify Modify calendar components.
move Move calendar components to another container. move Move calendar components to another container.
noop Do nothing. noop Do nothing.
schedule Add an [iTIP] object to the VSCHEDULE set.
search Search for calendar components. search Search for calendar components.
----------------------------------------------------------- -----------------------------------------------------------
2.4 Security Model 2.4 Security Model
2.4.1 Calendar User and UPNs 2.4.1 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, which is the subject of access rights. represented in CAP as a UPN, which is a key part of access rights.
The UPN representation is independent of the authentication mechanism The UPN representation is independent of the authentication mechanism
used during a particular CUA/CS interaction. This is because UPNs used during a particular CUA/CS interaction. This is because UPNs
are used within VCARs. If the UPN were dependent on the are used within VCARs. If the UPN were dependent on the
authentication mechanism, a VCAR could not be consistently evaluated. authentication mechanism, a VCAR could not be consistently evaluated.
A CU may use one mechanism while using one CUA but the same CU may A CU may use one mechanism while using one CUA but the same CU may
use a different authentication mechanism when using a different CUA, use a different authentication mechanism when 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.
skipping to change at page 14, line 45 skipping to change at page 14, line 42
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 rights, requiring a server specific mapping to be server's access rights, requiring a server specific mapping to be
done. The method by which a server determines a UPN, based on the done. The method by which a server determines a UPN, based on the
authentication credentials supplied by a client, is implementation authentication credentials supplied by a client, is implementation
specific. specific. See [BEEP] for authentication details
2.4.1.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
Name extension (e.g., a key bound only to an email address or subjectAlt-Name extension (e.g., a key bound only to an email
URI), then the subject name MUST be an empty sequence and the address or URI), then the subject name MUST be an empty
subjectAltName extension MUST be critical. sequence and the subjectAltName extension MUST be critical.
Implementations of this specification MAY use these comparison Implementations of this specification MAY use these comparison
rules to process unfamiliar attribute types (i.e., for name rules to process unfamiliar attribute types (i.e., for name
chaining). This allows implementations to process certificates chaining). This allows implementations to process certificates
with unfamiliar attributes in the subject name. with unfamiliar attributes in the subject name.
In addition, legacy implementations exist where an RFC 822 name is In addition, legacy implementations exist where an RFC 822 name
embedded in the subject distinguished name as an EmailAddress is embedded in the subject distinguished name as an
attribute. The attribute value for EmailAddress is of type EmailAddress attribute. The attribute value for EmailAddress
IA5String to permit inclusion of the character '@', which is not is of type IA5String to permit inclusion of the character '@',
part of the PrintableString character set. EmailAddress attribute which is not part of the PrintableString character set.
values are not case sensitive (e.g., "fanfeedback@redsox.com" is EmailAddress attribute values are not case sensitive (e.g.,
the same as "FANFEEDBACK@REDSOX.COM"). "fanfeedback@redsox.com" is 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
alternative name field (see sec. 4.2.1.7 of [RFC 2459]) to subject alternative name field (see sec. 4.2.1.7 of [RFC
describe such identities. Simultaneous inclusion of the 2459]) to describe such identities. Simultaneous inclusion of
EmailAddress attribute in the subject distinguished name to the 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:MAILTO:juser@example.com" then the email address should Random User:MAILTO:juser@example.com" then the email address should
be checked against the UPN, and the CN should also be checked. This be checked against the UPN. This is so the "ATTENDEE" property
is so the "ATTENDEE" property cannot be changed to something cannot be changed to something misleading like "ATTENDEE;CN=Joe
misleading like "ATTENDEE;CN=Joe Rictus Rictus User:MAILTO:juser@example.com" and have it pass validation.
User:MAILTO:juser@example.com" and have it pass validation. This This validation will also defeat other attempts at confusion.
validation will also defeat other attempts at confusion.
2.4.1.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.
2.4.1.3 User Groups 2.4.1.3 User Groups
skipping to change at page 16, line 43 skipping to change at page 16, line 36
CU. CAP defines a new component type called a Calendar 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 object.
All rights MUST be denied unless specifically granted; individual All rights MUST be denied unless specifically granted.
VCARs MUST be specifically granted to an authenticated CU.
The access for a particular UPN is the union of all grants for that If two rights specified in VCAR components are in conflict, the right
UPN minus the union of its denies. that denies access always takes precedence over the right that grant
access.
2.4.2.1 Calendar 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 "VCAR" properties.
there is no implied ordering required for components of a "RIGHTS"
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
incorrect.]
For details on the VCAR syntax please see section <forward ref> For details on the VCAR syntax please see section Section 2.4.2
2.4.2.2 Decreed VCARs 2.4.2.2 Predefined VCARs
Predefined calendar access CARIDs that MUST be implemented are:
CARID:READBUSYTIMEINFO - grants all authenticated users the right to
read VFREEBUSY components. Suggested definition for this VCAR:
BEGIN:VCAR
CARID:READBUSYTIMEINFO
BEGIN:VRIGHT
GRANT:*
PERMISSION:READ
SCOPE:SELECT * FROM VFREEBUSY
END:VRIGHT
END:VCAR
CARID:REQUESTONLY - grants to users other than the owner of the
calendar the right to write new events with the property METHOD set
to REQUEST. Suggested definition for this VCAR:
BEGIN:VCAR
CARID:REQUESTONLY
BEGIN:VRIGHT
GRANT:NONOWNER
PERMISSION:WRITE
RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST'
END:VRIGHT
END:VCAR
CARID:UPDATEPARTSTATUS - grants all authenticated users the right to
modify the instances of the ATTENDEE property set to one of their
calendar adresses in the VEVENT and VTODO components for which the
ORGANIZER property is set to the address of the VAGENDA in which the
VEVENT or VTODO is stored, given that the submitted value of the
ATTENDEE property is one of their calendar adresses. Suggested
definition for this VCAR:
BEGIN:VCAR
CARID:UPDATEPARTSTATUS
BEGIN:VRIGHT
GRANT:*
PERMISSION:MODIFY
SCOPE:SELECT att FROM VEVENT
USING_PROPERTIES ATTENDEE att
WHERE SELF() IN CAL-OWNERS(att) AND ORGANIZER = CURRENT-CALID()
RESTRICTION:SELECT * FROM VEVENT
WHERE SELF() IN CAL-OWNERS(ATTENDEE)
END:VRIGHT
BEGIN:VRIGHT
GRANT:*
PERMISSION:MODIFY
SCOPE:SELECT att FROM VTODO
USING_PROPERTIES ATTENDEE att
WHERE SELF() IN CAL-OWNERS(att) AND ORGANIZER = CURRENT-CALID()
RESTRICTION:SELECT * FROM VTODO
WHERE SELF() IN CAL-OWNERS(ATTENDEE)
END:VRIGHT
END:VCAR
CARID:DEFAULTOWNER - grants to the owner all permissions on all the
objects in the calendar. Suggested definition for this VCAR:
BEGIN:VCAR
CARID:DEFAULTOWNER
BEGIN:VRIGHT
GRANT:OWNER
PERMISSION:*
SCOPE:SELECT * FROM VAGENDA
END:VRIGHT
END:VCAR
2.4.2.3 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 or override a decreed VCAR an error When a user attempts to modify or override a decreed VCAR an error
will be returned, indicating that the user has insufficient will be returned, indicating that the user has insufficient
authorization to perform the operation. authorization to perform the operation. The reply to the CUA MUST BE
the same as if a non-decreed VCAR caused the failure.
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 outside the scope create a decreed VCAR. This administrative task is outside the 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 access to their own calendar objects. The DENY property
property disallows anyone (UPN=*) from being able to delete or modify disallows anyone (UPN=*) from being able to delete or modify this
this VCAR. VCAR.
BEGIN:VCAR BEGIN:VCAR
CARID:Users Default Access CARID:ctjmocfbr-01
GRANT:UPN=OWNER;OBJECT=*;OBJECT=OBJECT=METHOD;VALUE=* NAME:Users Default Access
DENY:UPN=*;OBJECT=VCAR;OBJECT=CARID; DECREED:TRUE
VALUE="Users Default Access" BEGIN:VRIGHT
;OBJECT=METHOD,VALUE=DELETE,MODIFY GRANT:OWNER
PERMISSION:*
SCOPE:SELECT * FROM VAGENDA
END:VRIGHT
BEGIN:VRIGHT
DENY:*
PERMISSION:DELETE
PERMISSION:MODIFY
SCOPE:SELECT * FROM VCAR WHERE CARID = 'ctjmocfbr-01'
END:VRIGHT
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.3 Inheritance 2.4.3 CAP Session Identity
Calendars inherit VCARs from their parent calendar. Calendars whose
parent is the Calendar Store inherit VCARs from the Calendar Store.
VCARs specified in a calendar or a sub-calendar override all
inherited VCARs.
2.4.4 CAP Session Identity
A BEEP 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" CAP command. The Calendar Service only permits the
if the session's authentication credentials are good for the operation if the session's authentication credentials are good for
requested identity. The method of checking this permission is the 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. Note that trusted server relationships are
outside the scope of [CAP].
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.
2.5 Roles 2.5 Roles
CAP defines methods for managing [iCAL] objects in a Calendar Store CAP defines methods for managing [RFC2445] objects in a Calendar
and exchanging [iCAL] objects for the purposes of group calendaring Store and exchanging [RFC2445] objects for the purposes of group
and scheduling between "Calendar Users" (CUs) or "User Groups" (UGs). calendaring and scheduling between "Calendar Users" (CUs) or "User
Groups" (UGs). 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 as
attendees takes on the role of "Organizer". The CUs asked to
participate in the event or to-do take on the role of "Attendee".
Note that "role" is also a descriptive parameter to the "ATTENDEE"
property. Its use is to convey descriptive context to an "Attendee"
such as "chair", "REQ-PARTICIPANT" or "NON-PARTICIPANT" and has
nothing to do with the scheduling workflow.
There are two distinct roles taken on by CUs in CAP. The CU who 2.6 CAP URL
creates an initial event or to-do and invites other CUs as attendees
takes on the role of "Organizer". The CUs asked to participate in
the event or to-do take on the role of "Attendee". Note that "role"
is also a descriptive parameter to the "ATTENDEE" property. Its use
is to convey descriptive context to an "Attendee" such as "chair",
"REQ-PARTICIPANT" or "NON-PARTICIPANT" and has nothing to do with the
scheduling workflow.
2.6 Calendar Addresses The CAP URL scheme is used to designate calendar stores, and
calendars accessible using the CAP protocol.
Calendar addresses are URIs that are modeled after URLs [URL]. CAP The CAP URL scheme conform to the generic URL syntax, defined in RFC
uses the following forms of URI. 2396, and follows the Guidelines for URL Schemes, set forth in RFC
2718.
[[<scheme>]://<csid>[:<port>]/]<relativeCALID> A CAP URL begins with the protocol prefix "cap" and is defined by the
following grammar.
where: capurl = scheme ":" [ "//" csid ] [ "/" relcalid ]
scheme = "cap"
csid = hostport ; As defined in Section 3.2.2 of RFC 2396
relcalid = *uric ; As defined in Section 2 of RFC 2396
<scheme> is "cap", the protocol described in this memo. 'relcalid' is an identifier that uniquely identifies a calendar on a
particular calendar store. There is no implied structure in a
Relative CALID. It may refer to the calendar of a user or of a
resource such as a conference room. It MUST be unique within the
calendar store.
<csid> is the Calendar Store ID. It is the network address of the Examples:
computer on which the CAP server is running.
<port> is optional. The port must be present in the URL if the cap://cal.example.com
CAP server does not listen on the default port number. cap://cal.example.com/abcd1234QWER
<relativeCALID> is an identifier that uniquely identifies the Relative CAP URLs are permitted and are resolved according to the
calendar on a particular calendar store. There is no implied rules defined in Section 5 of RFC 2396.
structure in a Relative CALID. It is an arbitrary string 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
unique within the calendar store. It is recommended that the
Relative CALID be globally unique.
If the <scheme> and <csid> are present the calendar address is said Example of a relative CAP URL:
to be "qualified". Senders are required to supply the
<relativeCALID> portion of the address. A qualified calendar address
is required when the <csid> of the target calendar address differs
from that of the CAP server receiving the command.
Examples of CAP URIs: abcd1234QWER
cap://calendar.example.com/user1 2.7 Calendar Addresses
://calendar.example.com/user1
user1 Calendar addresses can be described as absolute or relative CAP URLs.
cap://calendar.example.com/conferenceRoomA
cap://calendar.example.com/89798-098-zytytasd Examples:
For a user currently authenticated to a CAP server on
calendar.example.com, the first three addresses refer to the same cap://cal.example.com/abcd1234QWER
abcd1234QWER
For a user currently authenticated to the CAP server on
cal.example.com, these two calendar addresses refer to the same
calendar. calendar.
2.7 Extensions to iCalendar 2.8 Extensions to iCalendar
In mapping the calendar query feature, and access rights onto the In mapping the calendar query feature, and access rights onto the
iCalendar format, several extended iCalendar properties and iCalendar format, several extended iCalendar properties and
components are defined by this memo. components are defined by this memo.
The search operation makes use of a new component, called VQUERY. The search operation makes use of a new component, called VQUERY.
The component consists of a set of new properties: QUERY, EXPAND and The component consists of a set of new properties: QUERY, EXPAND,
QUERYNAME, that define a search filter. VQUERY is used by the NAME and QUERYID, that define a search filter. VQUERY is used by the
following CAP commands: "search", "move", "modify" and "delete". following CAP commands: "search", "modify", "move" and "delete".
Access rights are specified in the new iCalendar VCAR component. Access rights are specified in the new iCalendar VCAR component.
Calendar are specified by the new VAGENDA component. Calendar are specified by the new VAGENDA component.
2.8 Relationship of RFC 2446 (ITIP) to CAP 2.9 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. In CAP, the "schedule" command manipulation of calendar components. In CAP, the "create" command is
is used to submit scheduling requests. Other CAP commands such as used to submit scheduling requests. Other CAP commands such as
"create", "delete", "modify" and "move" provide direct manipulation "create", "delete", "modify" and "move" provide direct manipulation
of calendar components. In the CAP calendar store model, scheduling of calendar components. In the CAP calendar store model, scheduling
messages are conceptually kept separate from other calendar messages are conceptually kept separate from other calendar
components. This is modeled with the VSCHEDULE set. Note that this components.
is a conceptual model, the actual storage details are left to
implementations.
When scheduling is used, the METHOD is saved along with components. When scheduling is used, the METHOD is saved along with components.
A scheduled component becomes a booked component when its METHOD A scheduled component becomes a booked component when its METHOD
property is removed. For example, a component whose METHOD is property is set to CREATE. For example, a component whose METHOD is
"REQUEST" is scheduled. The component becomes booked when the METHOD "REQUEST" is scheduled. The component becomes booked when the METHOD
is removed. is set to "CREATE".
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 "search" them out of the CS using CAP, process them, have to "search" them out of the CS using CAP, process them,
determine what the final state of the object from a possible determine what the final state of the object from a possible
combination of user input and programmed logic. Then the CUA would combination of user input and programmed logic. Then the CUA would
instruct the CS to "create" a new booked entry or "modify" an instruct the CS to "create" a new booked entry or "modify" an
existing entry. Finally, the CUA can do a "delete" of all of these existing entry. Finally, the CUA can do a "delete" of all of these
now old scheduling requests in the CS. See [iTIP] for details on now old scheduling requests in the CS. See [iTIP] for details on
resolving multiple [iTIP] scheduling entries. resolving multiple [iTIP] scheduling entries.
3. Protocol Framework 3. Protocol Framework
CAP uses the BEEP application protocol kernel mapped onto TCP (refer CAP uses the BEEP application protocol kernel mapped onto TCP (refer
to [BEEP] and [BEEPTCP] for more information). The default port that to [BEEP] and [BEEPTCP] for more information). The default port that
the Calendar Service listens for connections on is port 5229. the Calendar Service listens for connections on is port --TBD--.
3.1 BEEP Exchange Styles 3.1 BEEP Exchange Styles
[BEEP] defines three styles of message exchange: [BEEP] defines three styles of message exchange:
MSG/ANS,ANS,...,NUL: for one-to-many exchanges. MSG/ANS,ANS,...,NUL: for one-to-many exchanges.
MSG/RPY: for one-to-one exchanges. MSG/RPY: for one-to-one exchanges.
MSG/ERR: for requests the cannot be processed due to an error. MSG/ERR: for requests the cannot be processed due to an error.
A CAP request, targeted at more than one containers, MUST use a one- A CAP request, targeted at more than one containers, MUST use a one-
to-many exchange, with a distinct answer associated with each target. to-many exchange, with a distinct answer associated with each target.
CAP request targeted at a single container MAY use a one-to-one 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 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 an error condition prevents the execution of the request on all the
targeted calendars. targeted calendars.
3.2 Use of XML, MIME and iCalendar 3.2 Use BEEP, MIME and iCalendar
Each BEEP payload exchanged via CAP consists of an XML document and NOTE: This topic is under debate and all CAP commands might drop the
possibly an arbitrary MIME content. The XML document defines the XML wrapper and just send the text/calendar objects and it would
action to be performed. When needed, the calendaring related data is contain the command.
included in a related MIME part containing an iCalendar object.
If only an XML document is sent in the BEEP payload, then the mapping Each BEEP payload exchanged via CAP is a iCalendar MIME content that
to a BEEP payload is straight-forward, e.g., fully conforms to [RFC2445].
C: MSG 1 2 . 432 62 C: MSG 1 2 . 432 62
C: Content-Type: application/beep+xml C: Content-Type: application/cap+xml
C: C:
C: <generate-uid num=10/> C: <generate-uid num="10"/>
C: END C: END
Otherwise, arbitrary MIME content is included in the BEEP payload by Otherwise, arbitrary MIME content is included in the BEEP payload
using a "multipart/related" (see [RFC 3087]), identified using a using CDATA.
"cid" URL (see [RFC 2392]), and the XML control document occurs as
the starting body part, e.g.,
C: MSG 1 3 . 1023 951 C: MSG 1 3 . 1023 951
C: Content-Type: multipart/related; boundary="boundary-asdf123"; C: Content-type: application/cap+xml
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:
C: <schedule id="abcd12346"> C: <create>
C: <target relcalid="john-relcalid"/> C: <![CDATA[
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-Type: text/calendar
C: Content-ID: 2@cal.example.com
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: METHOD:REQUEST C: METHOD:REQUEST
C: CMDID:abcd12346
C: BEGIN:VEVENT C: BEGIN:VEVENT
C: UID:abcd12345 C: UID:abcd12345
C: ORGAGNIZER:cap://cal.example.com/mary-relcalid C: ORGAGNIZER:cap://cal.example.com/mary-relcalid
C: ATTENDEE;PARTSTAT=ACCEPTED: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/john-relcalid
C: ATTENDEE;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:cap://cal.example.com/bob-relcalid C: ATTENDEE;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:cap://cal.example.com/bob-relcalid
C: DTSTART:20010920T180000Z C: DTSTART:20010920T180000Z
C: DTEND:20010920T190000Z C: DTEND:20010920T190000Z
C: SUMMARY:Mary invites John and Robert C: SUMMARY:Mary invites John and Robert
C: END:VEVENT C: END:VEVENT
C: END:VCALENDAR C: END:VCALENDAR
C: --boundary-asdf123-- C: ]]>
C: </create>
C: END C: END
The MIME content-type "application/beep+xml" is defined in Section NOTE: From this point on many of the examples will not include the
6.4 of [BEEP]. BEEP header and footer information. Only the iCalendar objects that
are sent between the CUA and CS will be shown as the BEEP payload
boundries are independant of CAP.
3.3 Bounded Latency 3.3 Bounded Latency
A CUA can associate a maximum latency time to a command with the A CUA can associate a maximum latency time to a CAP command with the
"max-time" element. If the CS is unable to complete the request in "latency" argument. If the CS is unable to complete the request in
the specified amount of time, then the server sends a "timeout" the specified amount of time, then the CS sends a "timeout" MSG on
request to which the CUA MUST respond with a "abort" or "continue" the same channel to which the CUA MUST reply with an "abort" or a
reply. "continue" reply.
Upon receiving an "abort" reply, the CS MUST terminate the command in 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 progress.
"continue" reply the server resumes its work in progress. Note that
a new latency time MAY be included in a "continue" reply.
The timeout element takes two arguments "latency" and "action". The When receiving a "continue" reply the server resumes its work in
"latency" argument MUST be set to the maximum latency time in progress. Note that a new latency time MAY be included in a
seconds. The "action" argument accepts the following values: "ask" "continue" reply.
and "abort". If the maximum latency time is exceeded and the
"action" argument is set to "ask", then CS MUST send a "timeout" The timeout argument and the "action" MUST both be added to the CAP
message to inform the CUA, otherwise if the argument "action" is set command, or nether can be added to a command. The "latency" value
to "abort" the CS can directly terminate the request and return a MUST BE set to the maximum latency time in seconds. The "action"
request-status code 2.0.3. 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.
Example: Example:
In this example bill@cal.example.com attempts to read a calendar but In this example bill@cal.example.com attempts to read a calendar but
the latency time he supplies is not sufficient for the server to the latency time he supplies is not sufficient for the server to
complete the command. complete the command.
C: MSG 1 4 . 2043 680 C: MSG 1 4 . 2043 680
C: Content-Type: multipart/related; boundary="boundary-zxy123"; C: Content-Type: application/cap+xml
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:
C: <search id="xyz12346"> C: <search latency="3" action="ask">
C: <max-time latency=3 action=ask/> C: <![CDATA[
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-Type: text/calendar
C: Content-ID: 2@cal.example.com
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: METOD:SEARCH
C: TARGET:relcalid-123
C: CMDID:xyz12346
C: BEGIN:VQUERY C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID FROM VEVENT C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID FROM VEVENT
C: WHERE DTEND >= '19990714T080000Z' AND C: WHERE DTEND >= '19990714T080000Z' AND
C: DTSTART <= '19990715T080000Z' C: DTSTART <= '19990715T080000Z'
C: END:VQUERY C: END:VQUERY
C: END:VCALENDAR C: END:VCALENDAR
C: --boundary-zxy123-- C: ]]>
C: </search>
C: END C: END
# After 3 seconds # After 3 seconds
S: MSG 1 2 . 102 64 S: MSG 1 2 . 102 64
S: Content-Type: application/beep+xml S: Content-Type: application/cap+xml
S: S:
S: <timeout id="xyz12346"/> S: <timeout cmdid="xyz12346"/>
S: END S: END
If Bill wants to continue and give the server more time he would If Bill wants to continue and give the server more time he would
issue a "continue" reply: issue a "continue" reply:
C: RPY 1 2 . 166 113 C: RPY 1 2 . 166 113
C: Content-Type: application/beep+xml C: Content-Type: application/cap+xml
C: C:
C: <continue id="xyz12346"> C: <continue cmdid="xyz12346" latency="3" action="ask"/>
C: <max-time latency=3 action=ask/>
C: </continue>
C: END C: END
If Bill wants to abort the command and not wait any further he would If instead, Bill wanted to abort the command and not wait any further
issue an "abort" reply: he would issue an "abort" reply:
C: RPY 1 2 . 166 62 C: RPY 1 2 . 166 62
C: Content-Type: application/beep+xml C: Content-Type: application/cap+xml
C: C:
C: <abort id="xyz12346"/> C: <abort cmdid="xyz12346"/>
C: END C: END
S: RPY 1 4 . 2723 114 S: RPY 1 4 . 2723 114
S: S:
S: <result>
S: <request-status code="2.0.3"> S: <request-status code="2.0.3">
S: Request Aborted by the CUA. S: Request Aborted by the CUA.
S: </request-status> S: </request-status>
S: </result>
S: END S: END
4. Formal Command Syntax 4. New Value Types
4.1 Searching and Filtering 4.1 CAL-QUERY Value Type
This section describes CAP's selecting and filtering entities within Subject: Registration of text/calendar MIME value type CAL-QUERY
a calendar store. It is based on the Standard Query Language (SQL)
defined in [SQL].
4.1.1 Grammar For Search Mechanism Value Name: CAL-QUERY
search = "BEGIN:VQUERY" CRLF Value Type Purpose: This value type is used to identify values
[expand] querycomp and contains query statements targeted at locating those values.
"END:VQUERY" CRLF
expand = "EXPAND" ":" ( "TRUE" / "FALSE") CRLF This was based on [SQL92] and [SQLCOM].
# the default is EXPAND:FALSE NOTE: This grammar is NOT SQL92.
(1) For the purpose of a query, all components should be
handled as tables, and the properties of those
components, should be handled as columns.
(2) All VAGENDAs and CS's look like tables for the purpose of a
QUERY. And all of their properties look like columns in
those tables.
(3) You CAN NOT do any cross component-type joins. And that means
you can ONLY have one component, OR one VAGENDA OR one CALSTORE
in the the FROM clause.
(4) Everything in the SELECT and WHERE clauses MUST BE from the
component type, or VAGENDA OR CALSTORE in the FROM clause.
This includes the values from the USING_PROPERTIES and
USING_COMPONENTS clauses.
(5) The '.' is used to separate the table name (component)
and column name (property) when selecting a property that
is contained inside of a component that is targeted in
the TARGET property.
In this example the '.' is used to separate the
TRIGGER property from its contained component (VALARM)
which is contained in any VEVENT in the selected TARGET
(relcalid). All TRIGGER values in any VEVENT in relcalid
would be returned.
TARGET:relcalid
QUERY: SELECT VALARM.TRIGGER FROM VEVENT
(6) A contained component without a '.' it is the same as
<component>.* with the result being a properly formatted
<component>(s) in the data stream, and correctly formatted
in the contained component(s) in iCalendar (RFC2445) format.
(a) SELECT VEVENT.<a-property-name> FROM VEVENT
(b) SELECT VALARM FROM VEVENT
(c) SELECT VALARM.* FROM VEVENT
(d) SELECT * FROM VEVENT
(e) SELECT * FROM VEVENT WHERE
VALARM.TRIGGER < '20020201T000000Z'
AND VALARM.TRIGGER > '20020101T000000Z'
Note: (a) Selects all instances of <a-property-name>
from all VEVENT components.
(b) and (c) Select all VALARM components from all
VEVENT components.
(d) Selects every property and every component
that is in any VEVENT component.
(e) Selects all properties and all contained
components in all VEVENT components that have a VALARM
with a TRIGGER property value between the provided
dates and times.
NOT VALID:
(f) SELECT VEVENET.VALARM.TRIGGER FROM VEVENT
(g) SELECT DTSTART,UID FROM VEVENT WHERE
VTODO.SUMMERY = "Fix typo in CAP"
Note: (g) Is NOT valid because it contains
two '.' characters in the SELECT clause.
(h) Is NOT valid because it mixes VEVENT
and VTODO properties in the same VQUERY.
(7) When multiple QUERY properties are supplied in a single VQUERY
component, the results returned are the same as the results
returned for multipled VQUERY components having each a single
QUERY property.
Formal Definition: The value type is defined by the following
notation:
comp-name = "VEVENT" / "VTODO" / "VJOURNAL" comp-name = "VEVENT" / "VTODO" / "VJOURNAL"
/ "VTIMEZONE" / "VALARM" / "VFREEBUSY" / "VAGENDA" / "VTIMEZONE" / "VALARM" / "VFREEBUSY"
/ "VCAR" / iana-name / x-name / "VAGENDA" / "VCAR" / "CALSTORE"
/ "VQUERY" / iana-name / x-comp
querycomp = ( query ) / ( queryname query ) / queryname querycomp = queries / ( queryname queries) / queryname
queryname = "QUERYNAME:" text queryname = "QUERYNAME" *(";" xparam) ":" text CRLF
query = "QUERY:" ( query-min / query-92 ) queries = query
# / queries query
# NOTE: query-min MUST be implemented in CSs.
#
# query-92 is ONLY used if CAPABILITY returns SQL-92
# as the QUERYLEVEL value or if QUERYLEVEL is not
# specified.
#
query-min = capselect-min query = "QUERY" *(";" xparam) ":" cal-query CRLF
capselect-min = "SELECT" capmin-cols "FROM" capmin-comps ; NOTE: There is exactly one space separating
"WHERE" capmin-cmp ; the various parts of cal-query
;
cal-query = "SELECT" SP cap-cols SP
"FROM" SP comp-name SP
*(cauprops SP / capcprops SP)
"WHERE" SP cap-expr
capmin-col = # Any property name found in any of the / "SELECT" SP cap-cols SP
components. "FROM" SP comp-name
capmin-cols = ( capmin-col / capmin-col "," capuprops = "USING_PROPERTIES" SP uprop-list
capmin-cols )
capmin-comps = ( comp-name / comp-name ","
compmin-comps )
capmin-cmp = ( colname capmin-cmp-rhs uprop-list = (cap-col SP cap-local)
/ colname capmin-cmp-rhs / uprop-list SP cap-col SP cap-local
capmin-logical capmin-cmp )
capmin-cmp-rhs = ( capmin-oper colvalue capcprops = "USING_COMPONENTS" SP cprop-list
/ "IS" ["NOT"] "NULL" )
colname = ( # Any valid component property name. cprop-list = (cap-comp cap-local)
/ "*" ) / cprop-list SP cap-col SP cap-local
cmpmin-oper = ( " = " / " != " / " < " / " > " / " <= " cap-col = ; Any property name found in the component
/ " >= " ) ; named in the comp-tbl used in the FROM clause.
;
; SELECT ORGANIZER FROM VEVENT ...
;
; OR
;
; A component name of an existing component contained
; inside of the cmp-tbl used in the FROM clause.
;
; SELECT VALARM FROM VEVENT ...
capmin-logical = ( " AND " / " OR " ) ; NOTE: there is NO space around the "," on
; the next line
cap-cols = cap-col / ( cap-cols "," cap-col)
/ "*"
/
cap-param = ; Any parameter that may be contained in the cap-col
; in the supplied PARAM() function
query-92 = capselect-92 capfrom-92 capwhere-92 cap-local = ; Any string that is composed of the characters
caporderby-92 ; that could be a cap-col name, but is not any
; cap-col name. It is suggested that the
; string start with "my-" to ensure it does not
; conflict with any existing or future cap-col name.
; This name MUST BE defined in the cap-using and
; can only be used in cap-expr of the same query.
; And this name is only known and valid for the
; provided query and only for the lifetime of
; the query. If multiple QUERY properties exist
; in the same component, it is only valid and usable
; in the same QUERY property where it was supplied.
capselect-92 = # Any valid [SQL] string that goes into col-value = col-literal
a SELECT clause. / "SELF()"
/ "CAL-OWNERS(" cal-address ")"
/ "CURRENT-CALID()"
capfrom-92 = # Like capmin-comps except embedded spaces cal-address = ; A CALID as define by CAP
# are allowed between commas - per [SQL].
capwhere-92 = # Any valid [SQL] string that goes into a col-literal = "'" literal-data "'"
# WHERE clause.
caporderby-92 = # Any valid [SQL] string that goes into a literal-data = ; Any data that matches the value type of the
# ORDERBY clause. ; column that is being compared. That is you can
; not compare PRIORITY to "some string" because
; PRIORITY has a value type of integer. If it is
; not preceded by the LIKE element, any '%' and '_'
; characters in the literal data are not treated as
; wildcard characters and do not have to be backslash
; escaped.
;
; OR
;
; If the literal-data is preceded by the LIKE
; element it may also contain the '%' and '_'
; wildcard characters. And if the literal data
; that is comparing contains any '%' or '_'
; characters, they MUST BE backslash escaped as
; described in the notes below in order for them not
; to be treated as wildcard characters.
4.1.2 SQL-MIN notes cap-ucol = cap-col / cap-local
(1) No inlined spaces are allowed if not in the grammar above. cap-expr = "(" cap-expr ")"
/ cap-term
(2) Note that cmpmin-oper and capmin-logical elements are cap-term = cap-expr SP cap-logical SP cap-expr
surrounded by exactly one space. / cap-factor
Use 'VEVENT,VTODO', not 'VEVENT, VTODO' cap-factor = cap-colval SP cap-oper SP col-value
Use 'DTSTART <= 20000605T131313Z', not / cap-colval SP "NOT LIKE" SP col-value
'DTSTART <= 20000605T131313Z'. / cap-colval SP "LIKE" SP col-value
Use ' AND ' and ' OR ', not 'AND' and not 'OR'. / cap-colval SP "IS NULL"
/ cap-colval SP "IS NOT NULL"
/ col-value SP "NOT IN" cap-colval"
/ col-value SP "IN" cap-colval"
(3) There is no ORDERBY. Sorting will take place in the order the cap-colval = cap-ucol
/ "PARAM(" cap-ucol "," cap-param ")"
cap-oper = "="
/ "!="
/ "<"
/ ">"
/ "<="
/ ">="
cap-logical = "AND" / "OR"
SP = ; A single white space ascii character
; (value in HEX %x20).
CRLF = ; As defined in RFC 2445.
xparam = ; As defined in RFC 2445.
x-prop = ; As defined in RFC 2445.
x-comp = ; As defined in RFC 2445.
4.1.1 CAP-QL notes
(1) There is no ORDERBY. Sorting will take place in the order the
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 Float and integer values MUST BE sorted by their numeric value.
additional columns.
(5) If EXPAND=FALSE and if colname is "*" sorting will be by the This means the result of a sort on an integer value type will be:
DTSTART value ascending. If EXPAND=TRUE and if colname is "*"
sorting will be by the RECURRENCE-ID value ascending.
If colname is "*" and capmin-coms is VALARM only then sorting will 1, 2, 100, 1000
be by TRIGGER time in UTC ascending.
(6) SQL-MIN MUST be implemented. and not
4.1.3 Querying Experminental Properties 1, 100, 1000, 2
4.1.4 Example, Query by UID This means the result of a sort on an float value type will be:
The following example would match the entire content of the component 1.1, 2.23, 100.332, 1000.12
with the UID property equal to "uid123" and not expand any multiple
instances of the component. If the CUA does not know if "uid123" was and not
a VEVENT, VTODO, VJOURNAL, or any other component, then all
components that the CUA supports MUST be supplied on the QUERY 1.1, 100.332, 1000.12, 2.23
property. This example assumes the CUA only supports VTODO and
Date and date time values will be sorted by their equivalent
value in UTC. No matter what the returned time zone in the result
set returns. This is so that if multiple components are returned
each in a unique time zone, the results will be sorted in UTC.
This does not mean the values must be converted to UTC in the
data returned to the CUA. It means the CS must do the sort in UTC.
All other values are sorted according to the locale sorting order
as specified in the calendar. Or the CS locale if the calendar
does not have any locale set, or the host operating system
locale if the CS does not specify a locale. And the locale to
use for the sort is determined in that order.
(2) The CS MUST sort at least the first column.
The CS MAY sort additional columns.
(3) If the cap-cols is only "*" and nothing else, then:
If EXPAND=FALSE sorting will be by the DTSTART value
ascending.
If EXPAND=TRUE sorting will be by the RECURRENCE-ID value
ascending.
If one or more DTSTART or RECURRENCE-ID components have
exactly the same value, the order for those matching
components is unspecified.
If the selected component(s) do not contain a DTSTART
or a RECURRENCE-ID, then the order is unspecified.
(4) All literal values are surrounded by single quotes ('), not
double quotes ("), and not without any quotes. If the value
contains quotes or any other ESCAPED-CHAR, they must be
backslash escaped as described in section "4.3.11 Text"
of RFC2445. Any LIKE wildcard characters that are part
of any literal data that is preceded by a LIKE clause and
is not intended to mean wildcard search, MUST BE escaped as
described in note (7) below.
(5) When comparing DATE-TIME to DATE value types and when
comparing DATE to DATE-TIME value types, the result will
be true if the DATE value is on the same day as the DATE-TIME
value. And they are compared in UTC no matter what time zone
the data may actual have been stored in.
VALUE-1 VALUE-2 Compare Results
20020304 20020304T123456 TRUE
(in UTC-3) (in UTC-3)
20020304 20020304T003456 FALSE
(in UTC-4) (in UTC-4)
20020304T003456Z 20020205T003456 FALSE
(in UTC-0) (in UTC-7)
When comparing DATE and DATE-TIME values with the LIKE
clause the comparison will be done as if the value is
a RFC2445 DATE or DATE-TIME string value.
LIKE '2002%' will match anything in the year 2002.
LIKE '200201%' will match anything in January 2002.
LIKE '%T000000' will match anything at midnight.
LIKE '____01__T%' will match anything for any year or
time that is in January.
(Four '_', '01', two '_' 'T%').
Again all comparisons will be done in UTC.
Using a LIKE value of "%00%, would return any value that
contained two consecutive zeros.
(6) DTEND and DURATION.
When a QUERY contains a DTEND value, then the CS MUST also
evaluate any existing DURATION property value and determine
if it has an effective end time that matches the QUERY
supplied DTEND value or any range of values supplied by
the QUERY.
When a QUERY contains a DURATION value, then the CS MUST
also evaluate any existing DTEND property value and determine
if it has an effective duration that matches the QUERY
supplied DURATION value or any range of values supplied by
the QUERY.
As DTEND is the first time that is excluded from a components
time range, any DURATION supplied by the QUERY that is
exactly one second less than DTEND MUST match the QUERY.
And if the DURATION ends exactly at the computed DTEND it
MUST NOT match.
Any DTEND supplied by the QUERY that is exactly one second
more than an end time computed from a DURATION MUST match the
QUERY. Any end time that is computed from a DURATION that
exactly matches the supplied DTEND MUST NOT match.
(6.1) Given a meeting room reserved with a component
that contains:
DTSTART:20020127T000000Z
DTEND:20020127T010000Z
The reservation is really from:
January 27th, 2002 00:00:00
To:
January 27th, 2002,00:59:59
(6.2) Given another meeting room reserved with a component
that contains:
DTSTART:20020127T000000Z
DURATION:P59M59S
The reservation is really from:
January 27th, 2002 00:00:00
To:
January 27th, 2002,00:59:59
(6.3) A QUERY that contains:
... VEVENT.DTSTART = '20020127T00000Z'
AND VEVENT.DTEND = '20020127T010000Z'
MUST match both (6.1) and (6.2).
(6.4) A QUERY that contains:
... VEVENT.DTSTART = '20020127T00000Z'
AND DURATION = 'P59M59S'
MUST match both (6.1) and (6.2).
(7) [NOT] LIKE notes:
The pattern matching characters is the '%' that matches
zero or more characters, and '_' that matches exactly one
character (where character does not always mean octet).
LIKE pattern matches always cover the entire string. To match
a pattern anywhere within a string, the pattern must start and
end with a percent sign.
To match a '%' or '_' in the data and not have it interpreted
as a wildcard character, they must be backslash escaped.
That is to search for a '%' or '_' in the string:
LIKE '%\%%' Matches any string with a '%' in it.
LIKE '%\_%' Matches any string with a '_' in it.
Strings compared using the LIKE clause MUST BE performed
using case in-sensitive comparisons. ('a' = 'A').
If LIKE is preceded by 'NOT' then there is a match when
the string compare fails.
Some property values (such as the 'recur' value type), contain
commas and are not multi valued. The CS must understand the
objects being compared and understand how to determine how any
multi valued or multi instances properties or parameter values
are separated, quoted, and backslash escaped and perform the
comparisons as if each value existed by itself and not quoted
or backslash escaped when comparing using the CONTAINS() element.
And see the examples in the next note (8).
(8) 'col-value SP "NOT IN" cap-colval"
This is similar to the LIKE element, except it does value
matching and not string comparison matches.
Some iCalendar objects can be multi instance and multi valued.
The IN operator will return a match if the literal value supplied
as part of the 'IN' clause is contained in the value of any
instance of the named property or parameter, or is in any of
the multiple values in the named property or parameter. The
'%' and '_' matching characters are not used with the 'IN'
clause and have no special meaning.
BEGIN:A-COMPONENT
a property:value1,value2 One property, two values.
b property:"value1,value2" One property, one value.
c FOO:parameter=1,2:x One parameter, two values.
d FOO:parameter="1,2",3:y One parameter, two value.
e FOO:parameter=","
END:A-COMPONENT
'value1' IN property would match (a) only.
'value1,value2' IN property would match (b) only.
'value%' IN property would NOT match any.
',' IN property would NOT match any.
'%,%' IN property would NOT match any.
'2' IN parameter would match (c) only.
'1,2' IN parameter would match (d) only.
'%,%' IN parameter would match (d) and (e).
LIKE(property, "value1%" would match (a) and (b)
LIKE(property, 'value%') would match (a) and (b)
LIKE(parameter, '1%') would match (c) and (d)
LIKE(parameter, '%2%') would match (c) and (d)
LIKE(parameter, ',') would NOT match any.
Some property values (such as the 'recur' value type), contain
commas and are not multi valued. The CS must understand the
objects being compared and understand how to determine how any
multi valued or multi instances properties or parameter values
are separated, quoted, and backslash escaped and perform the
comparisons as if each value existed by itself and not quoted
or backslash escaped when comparing using the CONTAINS() element.
If IN is preceded by 'NOT' then there is a match when
the value does not exist in the property or parameter value.
(9) DATE-TIME and TIME values in a WHEN clause.
All DATE-TIME and TIME literal values supplied as in
a WHEN clause MUST BE terminated with 'Z'. That means
that the CUA MUST supply the values in UTC.
Valid:
WHERE alarm.TRIGGER < '20020201T000000Z'
AND alarm.TRIGGER > '20020101T000000Z'
Not valid:
WHERE alarm.TRIGGER < '20020201T000000'
AND alarm.TRIGGER > '20020101T000000'
It is a syntax error and the CS MUST reject the QUERY.
4.2 CAP-QL notes
(1) There is no ORDERBY. Sorting will take place in the order the
columns are supplied in the command.
Float and integer values MUST BE sorted by their numeric value.
This means the result of a sort on an integer value type will be:
1, 2, 100, 1000
and not
1, 100, 1000, 2
This means the result of a sort on an float value type will be:
1.1, 2.23, 100.332, 1000.12
and not
1.1, 100.332, 1000.12, 2.23
Date and date time values will be sorted by their equivalent
value in UTC. No matter what the returned time zone is in the
result set. This is so that if multiple components are returned
each in a unique time zone, the results will be sorted in UTC.
This does not mean the values must be converted to UTC in the
data returned to the CUA. It means the CS must do the sort in UTC.
All other values are sorted according to the locale sorting order
as specified in the calendar. Or the CS locale if the calendar
does not have any locale set, or the host operating system
locale if the CS does not specify a locale. And the locale to
use for the sort is determined in that order.
(2) The CS MUST sort at least the first column.
The CS MAY sort additional columns.
(3) If the cap-cols is only "*" and nothing else, then:
If EXPAND=FALSE sorting will be by the DTSTART value
ascending.
If EXPAND=TRUE sorting will be by the RECURRENCE-ID value
ascending.
If one or more DTSTART or RECURRENCE-ID components have
exactly the same value, the order for those matching
components is unspecified.
(4) All literal values are surrounded by single quotes ('), not
double quotes ("), and not without any quotes. If the value
contains quotes or any other ESCAPED-CHAR, they must be
backslash escaped as described in section "4.3.11 Text"
of RFC2445. Any LIKE wildcard characters that are part
of any literal data that is preceded by a LIKE clause and
is not intended to mean wildcard search, MUST BE escaped as
described in note (7) below.
(5) When comparing DATE-TIME to DATE value types and when
comparing DATE to DATE-TIME value types, the result will
be true if the DATE value is on the same day as the DATE-TIME
value (both compared in UTC). And they MUST BE compared in UTC no
matter what time zone the object had been tagged with when the
object was stored in the CS.
VALUE-1 VALUE-2 Compare Results
20020304 20020304T123456 TRUE
(in UTC-3) (in UTC-3)
20020304 20020304T003456 FALSE
(in UTC-4) (in UTC-4)
20020304T003456Z 20020205T003456 FALSE
(in UTC-0) (in UTC-7)
When comparing DATE and DATE-TIME values with the LIKE
clause the comparison will be done as if the value is
a RFC2445 DATE or DATE-TIME string value (again in UTC).
LIKE '2002%' will match anything in the year 2002 (UTC).
LIKE '200201%' will match anything in January 2002 (UTC).
LIKE '%T000000' will match anything at midnight (UTC).
LIKE '____01__T%' will match anything for any year or
time that is in January (UTC).
(Four '_', '01', two '_' 'T%').
Again all comparisons will be done in UTC.
Using a LIKE value of "%00%, would return any value that
contained two consecutive zeros.
(6) DTEND and DURATION.
When a VQUERY contains a DTEND value, then the CS MUST also
evaluate any existing DURATION property value and determine
if it has an effective end time that matches the VQUERY
supplied DTEND value or any range of values supplied by
the VQUERY.
When a VQUERY contains a DURATION value, then the CS MUST
also evaluate any existing DTEND property value and determine
if it has an effective duration that matches the VQUERY
supplied DURATION value or any range of values supplied by
the VQUERY.
As DTEND is the first time that is excluded from a components
time range, any DURATION supplied by the VQUERY that is
exactly one second less than DTEND MUST match the VQUERY.
And if the DURATION ends exactly at the computed DTEND it
MUST NOT match.
Any DTEND supplied by the VQUERY that is exactly one second
more than an end time computed from a DURATION MUST match the
VQUERY. Any end time that is computed from a DURATION that
exactly matches the supplied DTEND MUST NOT match.
(6.1) Given a meeting room reserved with a component
that contains:
DTSTART:20020127T000000Z
DTEND:20020127T010000Z
The reservation is really from:
January 27th, 2002 00:00:00
To:
January 27th, 2002,00:59:59
(6.2) Given another meeting room reserved with a component
that contains:
DTSTART:20020127T000000Z
DURATION:P59M59S
The reservation is really from:
January 27th, 2002 00:00:00
To:
January 27th, 2002,00:59:59
(6.3) A VQUERY that contains:
... VEVENT.DTSTART = '20020127T00000Z'
AND VEVENT.DTEND = '20020127T010000Z'
MUST match both (6.1) and (6.2).
(6.4) A VQUERY that contains:
... VEVENT.DTSTART = '20020127T00000Z'
AND DURATION = 'P59M59S'
MUST match both (6.1) and (6.2).
(7) [NOT] LIKE notes:
The pattern matching characters is the '%' that matches
zero or more characters, and '_' that matches exactly one
character (where character does not always mean octet).
LIKE pattern matches always cover the entire string. To match
a pattern anywhere within a string, the pattern must start and
end with a percent sign.
To match a '%' or '_' in the data and not have it interpreted
as a wildcard character, they must be backslash escaped as
done in [RFC2445]. That is to search for a '%' or '_' in
the string:
LIKE '%\%%' Matches any string with a '%' in it.
LIKE '%\_%' Matches any string with a '_' in it.
Strings compared using the LIKE clause MUST BE performed
using case in-sensitive comparisons. ('a' = 'A').
The CS must understand the objects being compared and
understand how to determine how any multi valued property
or parameter values are separated, quoted, and backslash
escaped and perform the comparisons as if each value existed
by itself and not quoted or backslash escaped when comparing
using the LIKE element.
If LIKE is preceded by 'NOT' then there is a match when
the string compare fails.
(8) [NOT] "CONTAINS(" cap-lhs "," col-literal ")"
This is similar to the LIKE element, except it does value
matching and not string comparison matches.
property:value1,value2
CONTAINS(property, 'value1') would match
CONTAINS(property, 'value') would NOT match
LIKE(property, 'value%') would match
The CS must understand the objects being compared and
understand how to determine how any multi valued property
or parameter values are separated, quoted, and backslash
escaped and perform the comparisons as if each value existed
by itself and not quoted or backslash escaped when comparing
using the CONTAINS() element.
If CONTAINS() is preceded by 'NOT' then there is a match when
the value does not exist in the property or parameter value.
(9) DATE-TIME and TIME values in a WHEN clause.
All DATE-TIME and TIME literal values supplied as in
a WHEN clause MUST BE terminated with 'Z'. That means
that the CUA MUST supply the values in UTC.
Valid:
WHERE alarm.TRIGGER < '20020201T000000Z'
AND alarm.TRIGGER > '20020101T000000Z'
Not valid:
WHERE alarm.TRIGGER < '20020201T000000'
AND alarm.TRIGGER > '20020101T000000'
It is a syntax error and the CS MUST reject the VQUERY.
4.3 Example, Query by UID
The following example would match the entire content of the VEVENT
or VTODO with the UID property equal to "uid123" and not expand
any multiple instances of the component. If the CUA does not know
if "uid123" was a VEVENT, VTODO, VJOURNAL, or any other component,
then all components that the CUA supports MUST be supplied in a
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 VTODO WHERE UID = 'uid123'
END:VQUERY QUERY:SELECT * FROM VEVENT WHERE UID = 'uid123'
The following example would match the entire content of the component
with the UID property equal to "uid123" and would expand any
instances of the component after applying any recurrence rules. This
query could select multiple instances of components each with the
same UID. Each instance would have a unique RECURRENCE-ID of the
expanded component.
BEGIN:VQUERY
EXPAND:TRUE
QUERY:SELECT * FROM VEVENT,VTODO WHERE UID = 'uid123'
END:VQUERY END:VQUERY
4.1.5 Query by Date-Time range 4.4 Query by Date-Time range
This query selects the entire content of every booked VEVENT that has This query selects the entire content of every booked VEVENT that has
an instance greater than or equal to July 1st, 2000 00:00:00 UTC and an instance greater than or equal to July 1st, 2000 00:00:00 UTC and
less than or equal to July 31st, 2000 23:59:59 UTC 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
4.1.6 Query for all Non-Booked Entries 4.5 Query for all Non-Booked Entries
The following example selects the entire content of all scheduling The following example selects the entire contents of all [ITIP]
VEVENTS in the CS. The default for EXPAND is FALSE, so the non-booked VTODOs and VEVENTs with their METHOD set to one of
the [ITIP] METHODs. 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 IS NOT NULL QUERYID:Fetch VEVENT and VTODO iTIP components
NAME;LANG=fr_ca: ...todo...
QUERY:SELECT * FROM VEVENT WHERE
METHOD = 'REQUEST' OR METHOD = 'ADD' OR METHOD = 'PUBLISH' OR
METHOD = 'CANCEL' OR METHOD = 'REPLY' OR METHOD = 'COUNTER' OR
METHOD = 'REFRESH' OR METHOD = 'DECLINECOUNTER'
QUERY:SELECT * FROM VTODO WHERE
METHOD = 'REQUEST' OR METHOD = 'ADD' OR METHOD = 'PUBLISH' OR
METHOD = 'CANCEL' OR METHOD = 'REPLY' OR METHOD = 'COUNTER' OR
METHOD = 'REFRESH' OR METHOD = 'DECLINECOUNTER'
END:VQUERY END:VQUERY
The following example fetches the UIDs of all non-booked VEVENTs and In the above exampe, the QUERY property could have been written as:
VTODOs.
QUERY:SELECT * FROM VEVENT WHERE METHOD != 'CREATE'
AND METHOD != 'DELETE'
The following example fetches all VEVENT and VTODO booked entries
from the CS.
BEGIN:VQUERY BEGIN:VQUERY
QUERY:SELECT UID FROM VEVENT,VTODO WHERE METHOD IS NOT NULL QUERYID:Fetch All Booked VEVENT and VTODO components
QUERY:SELECT * FROM VEVENT WHERE METHOD = 'CREATE'
QUERY:SELECT * FROM VTODO WHERE METHOD = 'CREATE'
END:VQUERY END:VQUERY
4.1.7 Query with Subset of Properties by Date/Time The following fetches the UID for all VEVENT and VTODO components
that have been marked for delete (METHOD:DELETE).
BEGIN:VQUERY
QUERYID:Fetch UIDs of marked for delete VEVENTs and VTODOs
QUERY:SELECT UID FROM VEVENT WHERE METHOD = 'DELETE'
QUERY:SELECT UID FROM VTODO WHERE METHOD = 'DELETE'
END:VQUERY
In the examples above they were bunched into groups of similar
queries. They could be performed all at once by having all of
the QUERY property in one BEGIN/END VQUERY component.
4.6 Query with Subset of Properties by Date/Time
In this example only the named properties will be selected and all In this example only the named properties will be selected and all
booked and non-booked components will be selected that have a DTSTART booked and non-booked components will be selected that have a DTSTART
from February 1st to February 10th 2000. from February 1st to February 10th 2000.
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
4.1.8 Components With Alarms In A Range 4.7 Components With Alarms In A Range
This example fetches all components with an alarm that triggers This example fetches all VEVENTs 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' USING_COMPONENT VALARM my-alarm
AND VALARM.TRIGGER <= '20001231T235959Z' WHERE my-alarm.TRIGGER >= '20000101T030405Z'
AND my-alarm.TRIGGER <= '20001231T235959Z'
AND METHOD = 'CREATE' AND METHOD = 'CREATE'
END:VQUERY END:VQUERY
5. 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.
Properties within a VCAR must be evaluated in the order provided. 5.1 Access Control and NOCONFLICT
5.1 VCAR Inheritance
Calendar access rights specified in a calendar store are inherited as
default calendar access rights for any calendar in the parent
calendar store. Likewise, any calendar access rights specified in a
root calendar are inherited as default calendar access rights for any
sub-calendar to the root calendar. Furthermore, calendar access
rights specified in a sub-calendar are inherited as default calendar
access rights for any calendars that are hierarchically below the
sub-calendar.
Calendar access rights specified in a calendar override any default
calendar access rights. Calendar access rights specified within a
sub-calendar override any default calendar access rights.
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. The ALLOW-CONFLICT Calendar or This setting overrides access. The ALLOW-CONFLICT Calendar or
component setting may also prevent overlap, returning an error code component setting may also prevent overlap, returning an error code
"6.3" "6.3"
6. 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.
As mentioned in Section 3.2, CAP commands are defined by XML As mentioned in Section 3.2, CAP commands are defined by MIME
documents. The syntax of the commands is defined in Section 9, this objects.
section describes their semantic.
The attributes of a command are described in the "Attributes:" The attributes of a command are described in the "Attributes:"
section in the command descriptions below. Similarly the "Elements:" section in the command descriptions below. Similarly the "Elements:"
section describes the elements that compose the command. The section describes the elements that compose the command. The
"Response:" section, identifies the responses that may be returned by "Response:" section, identifies the responses that may be returned by
the server. the server.
In the examples below, lines preceded with "S:" refer to the server In the examples below, lines preceded with "S:" refer to the server
and lines preceded with "C:" refer to the client. Lines in which the and lines preceded with "C:" refer to the client. Lines in which the
first non-whitespace character is a "#" are editorial comments and first non-whitespace character is a "#" are editorial comments and
are not part of the protocol. are not part of the protocol.
6.1 Session Commands 6.1 Session Commands
6.1.1 "generate-uid" Command 6.1.1 "generate-uid" Command
Attributes: Attributes:
num: Number of UIDs to generate (1 if omitted). num: Number of UIDs to generate (1 if omitted).
cmdid: A unique id that identifies this command to
the CUA and CS.
latency: How long before CS asks you to continue. (optional)
action: How to handle latencty - MUST BE suppled but
only when the 'latency' command is supplied.
Response: Response:
"uid-list" "uid-list"
The "generate-uid" command returns one or more unique identifiers The "generate-uid" command returns one or more unique identifiers
which MUST be unique on the server's calendar store. It is which MUST BE globaly unique.
recommended that the return values be globally unique ids.
Example: Example:
C: MSG 1 5 . 2837 60 C: MSG 1 5 . 2837 60
C: Content-Type: application/beep+xml C: Content-Type: application/cap+xml
C: C:
C: <generateuid num=5/> C: <generateuid num=5/>
C: END C: END
S: RPY 1 5 . 2897 328 S: RPY 1 5 . 2897 328
S: Content-Type: application/beep+xml S: Content-Type: application/cap+xml
S: S:
S: <uid-list> S: <uid-list>
S: <uid>20011121T120000Z-12340@cal.example.com</uid> S: <uid>20011121T120000Z-12340@cal.example.com</uid>
S: <uid>20011121T120000Z-12341@cal.example.com</uid> S: <uid>20011121T120000Z-12341@cal.example.com</uid>
S: <uid>20011121T120000Z-12342@cal.example.com</uid> S: <uid>20011121T120000Z-12342@cal.example.com</uid>
S: <uid>20011121T120000Z-12343@cal.example.com</uid> S: <uid>20011121T120000Z-12343@cal.example.com</uid>
S: <uid>20011121T120000Z-12344@cal.example.com</uid> S: <uid>20011121T120000Z-12344@cal.example.com</uid>
S: </uid-list> S: </uid-list>
S: END S: END
skipping to change at page 33, line 25 skipping to change at page 47, line 31
Elements: Elements:
None None
Response: Response:
"capability" "capability"
The "get-capability" command returns information about the Calendar The "get-capability" command returns information about the Calendar
Service given the current state of the connection with the client. Server given the current state of the connection with the client.
The values returned may differ depending on current user identify and The values returned may differ depending on current user identify and
the security level of the connection. the security level of the connection.
Client implementations SHOULD NOT require any capability element Client implementations SHOULD NOT require any capability element
beyond those defined in this specification, and MAY ignore any non- beyond those defined in this specification, and MAY ignore any non-
standard, experimental capability elements. Non-standard standard, experimental capability elements. Non-standard
experimental capability elements MUST be prefixed with the text "x-". experimental capability elements MUST be prefixed with the text "x-".
The prefix SHOULD also include a vendor identifier. For example, "x- The prefix SHOULD also include a vendor identifier. For example, "x-
foo-barcapability", for the non-standard "barcapability" capability foo-barcapability", for the non-standard "barcapability" capability
of the vendor "foo". It may return different results depending on of the vendor "foo". It may return different results depending on
the UPN. the UPN.
Capability Occurs Description Capability Occurs Description
------------------------------------------------------- -------------------------------------------------------
cap 1 Container for CAP related elements. cap 1 Container for CAP related elements.
version 1+ Version(s) of CAP, MUST include at
least "1.0". cap-version 1+ Version of CAP. MUST include at
least "1.0" for this version of
CAP.
prodid 0 or 1 The product id of the CS.
query-level 1+ Indicates level of SQL support. query-level 1+ Indicates level of SQL support.
SQL-MIN or SQL-92. MUST include at CAP-QL or NONE. (NONE is for
least SQL-MIN. CS's that allow ITIP methods
only to be deposited and nothing
else). If set to NONE, then the
'car' capability MUST BE set to NONE.
car 1+ Indicates level of CAR support. car 1+ Indicates level of CAR support.
CAR-MIN or CAR-FULL-1. CAR-MIN MUST CAR-NONE, CAR-MIN or CAR-FULL-1.
be present. If CAR-FUL-1 is supplied then
CAR-MIN MUST BE supplied. CAR = NONE
MUST BE used when query-level of
NONE is supplied. If
date 0 or 1 date-max 0 or 1 The datetime value in UTC beyond
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
date-min 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.
icalendar 1 Container for CAP related elements.
version 1+ Version(s) of iCalendar that is (are) supported.
max-component-size max-component-size
0 or 1 A positive integer value that specifies 0 or 1 A positive integer value that specifies
the size of the largest iCalendar object that the size of the largest iCalendar
the server will accept in bytes. Objects object that the server will accept in
larger than this will be rejected. octets. Objects larger than this will be
The absence of this attribute indicates rejected. The absence of this attribute
no limit. indicates no limit. This is also the
maximum value of any BEEP payload
the CS will accept or send.
itip 1 Container for iTIP related elements. components 1 A comma seperated list of the names of
version 1+ Version(s) of ITIP, MUST include at least components that this CS supports. This
"1.0". includes any components inside of
other components (VALARM and VEVENT
for example). MUST include at least
VCALSTORE, VCALENDAR, and VAGENDA
and at least one of VEVENT, VTODO,
or VJORNAL.
version 1+ Version of iCalendar support.
MUST BE at least "2.0".
supported.
itip-version 1+ Version(s) of ITIP, MUST include at
least "1.0".
recur-accepted 0 or 1 whether the CS accepts recurrence rules
recur-expand 0 or 1 whether or not the CS supports the
expansion of recurrence rules.
recur-limit 0 or 1 the maximum number of occurrences or a recurrence
rule that are expanded by the CS
Example: Example:
C: MSG 1 6 . 3225 57 C: MSG 1 6 . 3225 57
C: Content-Type: application/beep+xml C: Content-Type: application/beep+xml
C: C:
C: <get-capability/> C: <get-capability/>
C: END C: END
S: RPY 1 6 . 3282 423 S: RPY 1 6 . 3282 423
S: Content-Type: application/beep+xml S: Content-Type: application/beep+xml
S: S:
S: S:
S: <capability> S: <capability>
S: <icalendar> S: <version>2.0</version>
S: <version>2.1</version>
S: <max-component-size>65536</max-component-size> S: <max-component-size>65536</max-component-size>
S: </icalendar> S: <itip-version>1.0</itip-version>
S: <itip> S: <cap-version>1.0</cap-version>
S: <version>1.0</version> S: <car>CAR-FULL-1</car><car>CAR-MIN</car.
S: </itip> S: <query-level>CAP-QL</query-level>
S: <cap> S: <date-min>00000101T000000Z</date-min>
S: <version>1.0</version> S: <date-max>99991231T235959Z</date-max>
S: <car>CAR-MIN</car> S: <components>
S: <query-level>SQL-MIN</query-level> S: VCALSTORE,VAGENDA,VCALENDAR,VEVENT,X-my-vcomp,VALARM
S: <date> S: </components>
S: <min>00000101T000000Z</min>
S: <max>99991231T235959Z</max>
S: </date>
S: </cap>
S: </capability> S: </capability>
S: END S: END
6.1.3 "identify" Command 6.1.3 "identify" Command
Attribute: Attribute:
upn: The UPN of the new identify to assume. upn: The UPN of the new identify to assume.
Element: Element:
skipping to change at page 35, line 37 skipping to change at page 50, line 23
6.4 Identity not permitted. 6.4 Identity not permitted.
The "identify" command allows the CUA to set a new identity to be The "identify" command allows the CUA to set a new identity to be
used for calendar access. used for calendar access.
The CS determines through an internal mechanism if the credentials The CS determines through an internal mechanism if the credentials
supplied at authentication permit the assumption of the selected supplied at authentication permit the assumption of the selected
identity. If they do, the session assumes the new identity, identity. If they do, the session assumes the new identity,
otherwise a security error is returned. otherwise a security error is returned.
If
Example:
C: MSG 1 7 . 3705 47
C: Content-Type: application/cap+xml
C:
C: <identify upn="my-alter-ego"/>
C: END
S: RPY 1 7 . 3752 91
S: Content-Type: application/cap+xml
S:
S: <request-status code="2.0"/>
S: END
6.1.4 "noop" Command 6.1.4 "noop" Command
Arguments: Arguments:
None None
Element: Element:
None None
Response: Response:
"result" with the following request-status code:
2.0 successful 2.0 successful
This command does nothing. It can be sent to the server periodically This command does nothing. It can be sent to the server periodically
to request that the CS does not time out the session. to request that the CS does not time out the session.
[EDITORS NOTE: should an unauthenticated and unidentified client be
able to issue this command?]
[EDITORS NOTE: in view of the integration with BEEP should "noop" be
removed?]
Example: Example:
C: MSG 1 7 . 3705 47 C: MSG 1 7 . 3705 47
C: Content-Type: application/beep+xml C: Content-Type: application/cap+xml
C: C:
C: <noop/> C: <noop/>
C: END C: END
S: RPY 1 7 . 3752 91 S: RPY 1 7 . 3752 91
S: Content-Type: application/beep+xml S: Content-Type: application/cap+xml
S: S:
S: <result>
S: <request-status code="2.0"/> S: <request-status code="2.0"/>
S: </result>
S: END S: END
6.2 Calendaring and Scheduling Commands 6.2 Calendaring and Scheduling Commands
6.2.1 Restriction Tables 6.2.1 Restriction Tables
Calendaring data are sent encapsulated in iCalendar objects (see Calendaring data is sent encapsulated in iCalendar objects The
Section 6.2.3.1). The restriction tables listed in the commands restriction tables listed in the commands below describe the
below describe the composition of the iCalendar data for these composition of the iCalendar data for these commands and replies.
commands and replies.
The presence column uses the following values to assert whether a The presence column uses the following values to assert whether a
property is required, is optional and the number of times it may property is required, is optional and the number of times it may
appear in the iCalendar object. A comment may be provided to further appear in the iCalendar object. A comment may be provided to further
clarify the presence criteria. clarify the presence criteria.
The table below defines the values for the presence column. The table below defines the values for the presence column.
Presence Presence
Value Description Value Description
skipping to change at page 37, line 12 skipping to change at page 52, line 5
1 One instance MUST be present 1 One instance MUST be present
1+ At least one instance MUST be present 1+ At least one instance MUST be present
0 Instances of this property MUST NOT be present 0 Instances of this property MUST NOT be present
0+ Multiple instances MAY be present 0+ Multiple instances MAY be present
0 or 1 Up to 1 instance of this property 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 While the tables list every component and property, their purpose is
not to define the meaning of the component or property. not to define the meaning of the component or property.
6.2.2 Common Attributes 6.2.2 Calendaring Commands
6.2.2.1 "id" Attribute
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.
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.
6.2.3 Common Elements
6.2.3.1 "data" Element
The role of the "data" element is to join an iCalendar document to an
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.
Depending of the context, the content of the referred iCalendar
object is subject to restrictions. See Section 6.2.1 for more
details.
6.2.3.2 "select" Element
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.
The "select" element is composed of the following:
A "data" element that MUST refer to a VQUERY component.
One or more "source" elements that identify the containers to
consider.
Restriction Table for the "data" element:
Component/Property Presence Comment
------------------- -------- ---------------------------
VCALENDAR 1
. VERSION 1 MUST be 2.1
. [IANA-PROP] 0+ any IANA registered
property
. 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
. VTIMEZONE 0+ MUST be present if any
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
6.2.3.3 "source" Element
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).
Attributes:
csid: when specified MUST point to a CSID. When omitted the CSID
of the current server is assumed.
relcalid: when specified MUST point to a RELCALID. The value is
relative the value of the "csid" attribute.
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 "*".
owner: if present MUST be set to a UPN. When specified only the
VAGENDA owned by the given UPN are considered.
6.2.3.4 "target" Element
The "target" element is used to specify a container targeted by a CAP
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.
Attributes:
csid: when specified MUST point to a CSID. When omitted the CSID
of the current server is assumed.
relcalid: when specified MUST point to a RELCALID. The value is
relative the value of the "csid" attribute.
6.2.4 Calendaring Commands
Calendaring commands allow a CUA to directly manipulate a calendar. 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.
6.2.4.1 "create" Command There are two kinds of replies. Those that contain an iCalendar
object, and those that do not contain an iCalendar object.
Attributes:
"id" (see Section 6.2.2.1). Any reply from the CS that contains an iCalendar object is wrappend
in a <reply> and </reply> tags.
Elements: Any reply from the CS that does not contain an iCalendar object is
returned in a <request-status code="x.y"/&gt tag. And if this reply
includes any cap command replies. Then they are returned wrapped
between <request-status code="x.y"&gt and </request-status
code="x.y"&gt tags.
"max-time": See Section 3.3. 6.2.2.1 "create" Command
"target": Each "target" element points to a container where the Attributes:
new component will be created.
"data": MUST point to an iCalendar object defining the "latency" with "action" (optional)
component(s) to create. See the restriction table given below.
Response: Response:
One "result" message per "target" element MUST be returned (see One "result" iCalendar object per "target" element MUST be
Section 3.1). returned (see Section 3.1)
One of the following "request-status" codes MUST be returned: 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.1 - Container not found 6.1 - Target not found
6.3 - Bad args 6.3 - Bad args
The "data" element of each "result" message is subject to the
result restriction table defined below.
The "create" command is used to create one or more iCalendar objects. The "create" command is used to create one or more iCalendar objects.
The "target" elements specify the containers where the component(s)
The TARGET property specify the containers where the component(s)
will be created. will be created.
Restriction table for the "data" element of the "create" command: The CDATA portion of the command can be any valid [ITIP] object
or any iCalendar object using the following restriction table.
There MUST BE at least one component inside of the VCALENDAR
object.
Restriction table for the "create" command:
Component/Property Presence Comment Component/Property Presence Comment
------------------- -------- ----------------------------- ------------------- -------- -----------------------------
VCALENDAR 1 VCALENDAR 1
. VERSION 1 MUST be 2.1 . VERSION 1 MUST BE at least 2.0
. TARGET 1+
. METHOD 1 MUST BE the METHOD of the newly
created components.
. CMDID 0 or 1
. [IANA-PROP] 0+ any IANA registered . [IANA-PROP] 0+ any IANA registered
property property
. VAGENDA 0+ . VAGENDA 0+
. VAGENDA 0+
. . ALLOW-CONFLICT 0 or 1
. . CALMASTER 0 or 1 . . CALMASTER 0 or 1
. . NAME 0 or 1 . . CALSCALE 0 or 1
. . CREATED 0 or 1
. . DEFAULT-CHARSET 0 or 1
. . DEFAULT-LOCALE 0 or 1
. . DEFAULT-TZID 0 or 1
. . LAST-MODIFIED 0 or 1
. . METHOD 0 or 1 The only valid values are
"CREATE" or "DELETE."
. . NAME 0+
. . OWNER 1+ . . OWNER 1+
. . RELATED-TO 0+
. . RELCALID 1 . . RELCALID 1
. . TZID 0 or 1 . . TZID 0 or 1
. . X-PROPERTY 0+
. . [IANA-PROP] 0+ any IANA registered . . [IANA-PROP] 0+ any IANA registered
property property
. . X-COMPONENT 0+
. VCAR 0+ . VCAR 0+
. . CARID 0 or 1 . . . CARID 1
. . DENY 0+ Note, there must be at . . . NAME 0+ Note, there MUST NOT be
more than one NAME with
no LANGUAGE parameter,
and there MUST NOT be
more than one NAME with
the same LANGUAGE value.
. . . DECREED 0 This property is outside
the scope of the protocol.
. . . X-PROPERTY 0+
. . . [IANA-PROP] 0+ any IANA registered
property
. . . VRIGHT 1+
. . . . PERMISSION 1+
. . . . DENY 0+ Note, there must be at
least one GRANT or DENY least one GRANT or DENY
within the VCAR. within the VRIGHT.
. . 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 VRIGHT.
. . [IANA-PROP] 0+ any IANA registered . . . . SCOPE 0+ Note, there must be at
least one SCOPE if
PERMISSION is set to
"READ", "MODIFY",
"DELETE", or "*".
. . . . RESTRICTION 0 or 0+ Note, allowed only if
PERMISSION is set to
"WRITE", "MODIFY", or "*".
. . . . X-PROPERTY 0+
. . . . [IANA-PROP] 0+ any IANA registered
property property
. VQUERY 0+ . VQUERY 0+
. . EXPAND 0 or 1 (For VQUERY minimum values - see the VQUERY sections.
. . QUERYNAME 1 Plus each each new VQUERY must have a QUERYID property)
. . QUERY 1
. . [IANA-PROP] 0+ any IANA registered
property
. VEVENT 0+
. . 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
. . 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
. . 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+
. . . ACTION 1
. . . ALARMID 1
. . . 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+
. . 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
. . 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+
. . [IANA-PROP] 0+ any IANA registered property
. . VALARM 0+
. . . ACTION 1
. . . ALARMID 1
. . . 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+
. . ATTENDEE 0
. . DESCRIPTION 1 Can be null.
. . DTSTAMP 1
. . DTSTART 1
. . ORGANIZER 1
. . 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
. . EXDATE 0+
. . EXRULE 0+
. . LAST-MODIFIED 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+
. . RRULE 0+
. . SEQUENCE 0 or 1 MUST be present if
non-zero. MAY be
present if zero.
. . STATUS 0 or 1
. . SUMMARY 0 or 1 Can be null
. . URL 0 or 1
. . X-PROPERTY 0+
. . [IANA-PROP] 0+ any IANA registered
property
. VFREEBUSY 0
. VTIMEZONE 0+ MUST be present if any . x-component 0+
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
Restriction Table for the "data" element of the "result" response: Restriction Table for the CDATA section of a reply that contains
an iCalendar object is any valid [ITIP] response plus any from
this restriction table and the VQUERY responses can contain
any iCalendar properties that are wrapped in BEGIN/END VCALENDAR.
There MUST BE at least one component inside of the VCALENDAR
object.
Component/Property Presence Comment Component/Property Presence Comment
------------------- -------- ------------------------------- ------------------- -------- -------------------------------
VCALENDAR 1+ VCALENDAR 1+
. VERSION 1 MUST be 2.1 . VERSION 1 MUST BE at least 2.0
. TARGET 1+
. CMDID 0 or 1
. VAGENDA 0+ . VAGENDA 0+
. . RELCALID 1 . . RELCALID 1
. . REQUEST-STATUS 1+ . . REQUEST-STATUS 1+
. VCAR 0+ . VCAR 0+
. . CARID 1 . . CARID 1
. . REQUEST-STATUS 1+ . . REQUEST-STATUS 1+
. VEVENT 0+
. . UID 1 The UID for which this
REQUEST-STATUS applies
. . REQUEST-STATUS 1+
. . RECURRENCE-ID 0 or 1 MUST be specified only if instance of
a recurring component was created.
. . VALARM 0 if VEVENT was successfully
saved
1+ if there were errors saving
alarms
. . . ALARMID 1
. . . REQUEST-STATUS 1+
. VFREEBUSY 0
. VJOURNAL 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+
. VQUERY 0+ . VQUERY 0+
. . QUERYID 0+ One for each QUERYID supplied in "create"
. . REQUEST-STATUS 1+ . . REQUEST-STATUS 1+
(Plus the query results)
. VTODO 0+ . x-component 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
1+ if there were errors saving
alarms
. . . ALARMID 1
. . . REQUEST-STATUS 1+
Example:
In the following example, two new top level VAGENDAs are created. In the following example, two new top level VAGENDAs are created.
Note that the CSID of the server is cal.example.com. Note that the CSID of the server is cal.example.com.
C: MSG 1 8 . 3843 778 C: MSG 1 8 . 3843 480
C: Content-Type: multipart/related; boundary="boundary-foo321"; C: Content-Type: application/cap+xml
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:
C: <create id="creation01"> C: <create>
C: <target csid="cal.example.com"/> C: <![CDATA[
C: <data content="cid:2@cal.example.com"/>
C: </create>
C: --boundary-foo321
C: Content-Type: text/calendar C: Content-Type: text/calendar
C: Content-ID: 2@cal.example.com
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: VERSION:2.1 C: VERSION:2.0
C: BEGIN:VAGENDA C: CMDID:creation01
C: TARGET:cal.example.com
C: BEGIN:VAGENDA <- data for 1st new calendar
C: RELCALID:relcalz1 C: RELCALID:relcalz1
C: NAME;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/Pacific
C: END:VAGENDA C: END:VAGENDA
C: BEGIN:VAGENDA C: BEGIN:VAGENDA <- data for 2nd new calendar
C: RELCALID:relcalz2 C: RELCALID:relcalz2
C: NAME;LANGUAGE=EN-us:Mary's personal calendar C: NAME;LANGUAGE=EN-us:Mary's personal 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/Pacific
C: END:VAGENDA C: END:VAGENDA
C: END:VCALENDAR C: END:VCALENDAR
C: --boundary-foo321-- C: />]]>
C: END C: END
S: RPY 1 8 . 4621 647
S: Content-Type: multipart/related; boundary="boundary-bar321"; When there are multiple TARGET'values in the original command object
S: start="1@cal.example.com"; then the replies MUST BE in the exact same order as they were provided
S: type="application/beep+xml" to the CS. The same is true for the objects created, their responses
S: MUST BE in the exact same order as they were supplied to the CS.
S: --boundary-bar321 (With the BEEP header and footer removed)
S: Content-Type: application/beep+xml S: Content-Type: text/calendar
S: Content-ID: 1@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:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.1 S: VERSION:2.0
S: BEGIN:VAGENDA S: CMDID:creation01
S: TARGET:cal.example.com
S: TARGET:cal.example.com
S: BEGIN:VAGENDA <- Reply for 1st calendar create
S: RELCALID:relcalz1 S: RELCALID:relcalz1
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VAGENDA S: END:VAGENDA
S: BEGIN:VAGENDA S: BEGIN:VAGENDA <- Reply for 2nd calendar create
S: RELCALID:relcalz2 S: RELCALID:relcalz2
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VAGENDA S: END:VAGENDA
S: END:VCALENDAR S: END:VCALENDAR
S: --boundary-bar321--
S: END
Example to create a new component in multiple containers. To create a new component in multiple containers simply name
all of the containers in the TARGET in the create command. Here
a new VEVENT is created in two TARGETs. In this example, the
VEVENT is one new iTIP REQUEST object in two calendars. The
results would be iCalendar object that conform to the iTIP
replys as defined in iTIP.
C: MSG 1 9 . 5268 622
C: Content-Type: multipart/related; boundary="boundary-kshgd";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
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-Type: text/calendar
C: Content-ID: 2@cal.example.com
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: VERSION:2.1 C: VERSION:2.0
C: CMDID:creation02
C: METHOD:REQUEST
C: TARGET:relcalz1
C: TARGET:relcalz2
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:VCALENDAR C: END:VCALENDAR
C: --boundary-kshgd--
C: END The CS reply can be combined when there is exactly one target.
S: ANS 1 9 . 58901 563 0 If a <create> command deposited two METHOD:REQUEST objects into
S: Content-Type: multipart/related; boundary="boundary-eqrga"; the same target, this could be the reply.
S: start="1@cal.example.com";
S: type="application/beep+xml" S: <result>
S: S: <![CDATA[
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-Type: text/calendar
S: Content-ID: 2@cal.example.com
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.1 S: CMDID:deposit request
S: TARGET:relcalz1
S: VERSION:2.0
S: BEGIN:VEVENT S: BEGIN:VEVENT
S: UID:abcd12345 S: REQUEST-STATUS:2.0
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: UID:abcd12345 S: REQUEST-STATUS:2.0
S: REQUEST-STATUS:6.0
S: END:VEVENT S: END:VEVENT
S: END:VCALENDAR S: END:VCALENDAR
S: --boundary-982hf-- S: >]]>
S: END S: </result>
S: NUL 1 9 . 7016 0
S: END
As described in Section 3.1, the CS sends one response per "target"
element present in the "create" command.
6.2.4.2 "delete" Command 6.2.2.2 "move" Command
Attributes: Attributes:
"id" (see Section 6.2.2.1). "cmdid"
Elements: Elements:
"max-time": See Section 3.3. "max-time": See Section 3.3.
"select": specifies the compoments to delete (see Section "target": The "target" element points to the container where
6.2.3.2). the components are to be relocated.
"select": identifies the component(s) to move.
Response: Response:
One "result" message per "source" in the "select" element (see One "result" message for each "source" in the "select" element
Section 3.1). is returned (see Section 3.1).
One of the following "request-status" codes MUST be returned: One of the following "request-status" codes MUST be returned:
2.0 - successfully created the component or calendar 2.0 - successfully moved the component or calendar
6.1 - Container not found 6.1 - Container not found
6.3 - Bad args 6.3 - Bad args
The "data" element of each "result" message is subject to the The "data" element of each "result" message is subject to the
result restriction table define below. result restriction table defined below.
The "delete" command is used to delete a calendar or component. The The "move" command is used to move components within the CS's
"select" element specifies the container(s) to delete. hierarchy of calendars. The access control on the VAGENDA after it
has been moved to its new location in the calstore hierarchy MUST be
at least as secure as it was prior to the move. One way to
accomplish this is to build a list of VCARs that apply to the VAGENDA
in its old hierarchy and and write them into the VAGENDA before
moving it to its new location.
Restriction Table for the "data" element of the "result" response(s). Restriction Table for "data" element of the "result" response:
Component/Property Presence Comment Component/Property Presence Comment
------------------- -------- ----------------------------- ------------------- -------- -------------------------------
VCALENDAR 1+ VCALENDAR 1+
. VERSION 1 MUST be 2.0
. VERSION 1 MUST be 2.1 . VAGENDA 0+
. . RELCALID 1
. VAGENDA Only if VAGENDAS were . . REQUEST-STATUS 1+
deleted
. RELCALID 1
. REQUEST-STATUS 1
. VCAR 0+ Only if VCAR components were . VCAR 0+
deleted
. . CARID 1 . . CARID 1
. . REQUEST-STATUS 1 . . REQUEST-STATUS 1+
. VEVENT 0+ Only if VEVENT components . VEVENT 0+
were deleted
. . UID 1 . . UID 1
. . REQUEST-STATUS 0 or 1 Omitted if an embedded VALARM was . . REQUEST-STATUS 1+
the target of the deletion.
. . VALARM 0+ Only if VALARM components . . VALARM 0 if VEVENT was successfully
were deleted saved
1+ if there were errors saving
alarms
. . . ALARMID 1 . . . ALARMID 1
. . . REQUEST-STATUS 1 . . . REQUEST-STATUS 1+
. VFREEBUSY 0 . VFREEBUSY 0
. . UID 1
. . DTSTAMP 1
. . REQUEST-STATUS 1
. VJOURNAL 0+ Only if VJOURNAL components . VJOURNAL 0+
were deleted
. . UID 1 . . UID 1
. . REQUEST-STATUS 1 . . REQUEST-STATUS 1+
. VQUERY 0+ Only if VQUERY components . VQUERY 0+
were deleted . . REQUEST-STATUS 1+
. UID 1
. REQUEST-STATUS 1
. VTIMEZONE 0+ Only if VTIMEZONE components . VTODO 0+
. . TZID were deleted
. . REQUEST-STATUS 1
. VTODO 0+ Only if VTODO components were
deleted
. . UID 1 . . UID 1
. . REQUEST-STATUS 0 or 1 Omitted if an embedded VALARM was . . REQUEST-STATUS 1+
the target of the deletion. . . VALARM 0 if VTODO was successfully
saved
. . VALARM 0+ Only if VALARM components 1+ if there were errors saving
were deleted alarms
. . . ALARMID 1 . . . ALARMID 1
. . . REQUEST-STATUS 1 . . . REQUEST-STATUS 1+
----------------------------------------------------------
[EDITORS NOTE: Issues:
- Can one use DELETE to remove all VALARMs and VTIMEZONEs that ---------------------------------------------------------
match a certain search criteria and that belong to all components,
event though VALARMs and VTIMEZONEs never exist as independent
components? Or should one use MODIFY? If they can be deleted, do
we return the REQUEST-STATUS of their deletion in a VEVENT or
separately?
Example to delete a VEVENT with UID 'abcd12345' from any of the Example: moving the VAGENDA Nellis to Area-51
calendar owned by the CU with the UPN="user@cal.example.com":
C: MSG 1 10 . 7016 558 C: MSG 1 12 . 11323 613
C: Content-Type: multipart/related; boundary="boundary-gsdmx3"; C: Content-Type: multipart/related; boundary="boundary-kljr";
C: start="1@cal.example.com"; C: start="1@cal.example.com";
C: type="application/beep+xml" C: type="application/beep+xml"
C: C:
C: --boundary-gsdmx3 C: --boundary-kljr
C: Content-Type: application/beep+xml C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com C: Content-ID: 1@cal.example.com
C: C:
C: <delete id="delete01"> C: <move id="move01"/>
C: <select> C: <select>
C: <source depth=* owner="user@cal.example.com"/> C: <source csid="cal@example.com" depth=*>
C: <data content="cid:2@cal.example.com"/> C: <data content="cid:query@cal.example.com"/>
C: </select> C: </select>
C: </delete> C: <target relcalid="area-51"/>
C: --boundary-gsdmx3 C: </move>
C: --boundary-kljr
C: Content-Type: text/calendar C: Content-Type: text/calendar
C: Content-ID: 2@cal.example.com C: Content-ID: query@cal.example.com
C: C:
C: BEGIN:VCALENDAR
C: BEGIN:VQUERY C: BEGIN:VQUERY
C: QUERY:SELECT * FROM VEVENT WHERE UID = 'abcd12345' C: QUERY: SELECT * FROM VAGENDA WHERE RELCALID='Nellis'
C: END:VQUERY C: END:VQUERY
C: --boundary-gsdmx3-- C: END:VCALENDAR
C: --boundary-kljr--
C: END C: END
S: RPY 1 10 . 7574 587 S: RPY 1 2 . 11936 571
S: Content-Type: multipart/related; boundary="boundary-oifc3j"; S: Content-Type: multipart/related; boundary="boundary-mnbvd";
S: start="1@cal.example.com"; S: start="reply@cal.example.com";
S: type="application/beep+xml" S: type="application/beep+xml"
S: S:
S: --boundary-oifc3j S: --boundary-mnbvd
S: Content-Type: application/beep+xml S: Content-Type: application/beep+xml
S: Content-ID: 1@cal.example.com S: Content-ID: reply@cal.example.com
S: S:
S: <result id="delete01"> S: <result id="move01">
S: <source depth=* owner="user@cal.example.com"/> S: <source csid=cal@example.com depth=*>
S: <data content="cid:2@cal.example.com"/>
S: <request-status code="2.0"/> S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result> S: </result>
S: --boundary-oifc3j S: --boundary-mnbvd
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com S: Content-ID: 2@cal.example.com
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.1 S: BEGIN:VAGENDA
S: BEGIN:VEVENT S: RELCALID:Nellis
S: UID:abcd12345
S: REQUEST-STATUS: 2.0 S: REQUEST-STATUS: 2.0
S: END:VEVENT S: END:VAGENDA
S: END:VCALENDAR S: END:VCALENDAR
S: --boundary-oifc3j-- S: --boundary-mnbvd--
S: END S: END
6.2.4.3 "modify" Command 6.2.2.3 "delete" Command
Attributes: Attributes:
"id" (see Section 6.2.2.1). "latency" and "action" (optional see Section xxxx)
Elements:
"max-time": See Section 3.3.
"select": identifies the component(s) to modify.
"add": adds properties to the selected component(s).
"remove": removes properties from the selected component(s).
"update": updates the content of the selected component(s).
Response: Response:
One "result" message per "source" in the "select" is returned (see One of the following "request-status" codes MUST be returned
Section 3.1). for each target supplied and for each object deleted
as in that target that is effected.
One of the following "request-status" codes MUST be returned:
2.0 - successfully created the component or calendar 2.0 - successfully deleted the component or calendar
6.1 - Container not found 6.1 - Container not found
6.3 - Bad args 6.3 - Bad args
The "data" element of each "result" message is subject to the The "delete" command is used to delete calendars or components.
restriction table defined below. The "select" element specifies the container(s) to delete.
The "modify" command is used to modify existing components. The Restriction Table for the "delete" command of the "reply"
"select" element specifies the components to modify. The "add", response.
"remove" and "update" elements define the operations to perform.
The "add" element is used to add properties or nested components to Component/Property Presence Comment
the selected components. The "add" element is composed of a "data" ------------------- -------- -----------------------------
element that contains a component with the properties to add. For
example to add an inline attachment to a VEVENT the following
iCalendar object could be:
BEGIN:VCALENDAR VCALENDAR 1+
BEGIN:VEVENT
ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY:
MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U
EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE
<...remainder of "BASE64" encoded binary data...>
END:VEVENT
END:VCALENDAR
The "remove" element is used to remove properties from the selected . VERSION 1 MUST be at least 2.0
components. The "data" element contains an iCalendar with the . VAGENDA Only if VAGENDAS were
properties to delete. When the "ignore-value" attribute is set to deleted
true, all the properties specified in the "data" element are removed
even if the values do not match the current state of the component.
This is useful to remove potentially large properties efficiently
(e.g., "ATTACH").
The "update" element is used to update or add the properties referred . CMDID 0+ MUST BE supplied if it was
to by the "data" element. If the "remove-missing" attribute is set supplied in the delete command.
to true, then all the elements not present in the "data" element
document will be removed from the selected components.
When more than one operations is specified, the modifications MUST . METHOD 1 MUST BE DELETE
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.
Restriction Table for "data" element of the "result" response: . TARGET 1+
Component/Property Presence Comment . REQUEST-STATUS 1
------------------- -------- -------------------------------
VCALENDAR 1+ . VCAR 0+ Only if VCAR components were
. VERSION 1 MUST be 2.1 deleted
. . CARID 1
. . REQUEST-STATUS 1
. VAGENDA 0+ . VEVENT 0+ Only if VEVENT components
. . RELCALID 1 were targets of deletion.
. . REQUEST-STATUS 1+ . . UID 1
. . REQUEST-STATUS 0 or 1 Omitted if an embedded VALARM was
the target of the deletion.
. . VALARM 0+ Only if VALARM components
were targets of deletion.
. . . SEQUENCE 1
. . . REQUEST-STATUS 1
. VCAR 0+ . VFREEBUSY 0+ Only if VFREEBUSY was the target
. . CARID 1 of deletion.
. . REQUEST-STATUS 1+ . . UID 1
. . DTSTAMP 1
. . REQUEST-STATUS 1
. VEVENT 0+ . VJOURNAL 0+ Only if VJOURNAL components
were targets of deletion.
. . UID 1 . . UID 1
. . RECURRENCE-ID 0 or 1 MUST be specified only if instance of . . REQUEST-STATUS 1
a recurring component was modified.
. . REQUEST-STATUS 1+
. . VALARM 0 if VEVENT was successfully . VQUERY 0+ Only if VQUERY components
saved were targets of deletion.
1+ if there were errors saving . UID 1
alarms . REQUEST-STATUS 1
. . . REQUEST-STATUS 1+
. VFREEBUSY 0 . VTIMEZONE 0+ Only if VTIMEZONE components
. . TZID were targets of deletion.
. . REQUEST-STATUS 1
. VJOURNAL 0+ . VTODO 0+ Only if VTODO components were
targets of deletion.
. . UID 1 . . UID 1
. . RECURRENCE-ID 0 or 1 MUST be specified only if instance of . . REQUEST-STATUS 0 or 1 Omitted if an embedded VALARM was
a recurring component was modified. the target of the deletion.
. . REQUEST-STATUS 1+
. VQUERY 0+ . . VALARM 0+ Only if VALARM components
. . REQUEST-STATUS 1+ were targets of deletion.
. . . ALARMID 1
. . . REQUEST-STATUS 1
. VTODO 0+ ----------------------------------------------------------
. . UID 1
. . RECURRENCE-ID 0 or 1 MUST be specified only if instance of
a recurring component was modified.
. . REQUEST-STATUS 1+
. . VALARM 0 if VTODO was successfully
saved
1+ if there were errors saving
alarms
. . . REQUEST-STATUS 1+
In the example below, the start and end time of the event with UID Note: If a VAGENDA is deleted then NONE of its contained
abcd12345 is changed and the LOCATION property is removed. components will return any REQUEST-STATUS responses.
Example to delete a VEVENT with VEVENT UID 'abcd12345' from
the calendar "relcald-22" from the current CS:
C: MSG 1 11 . 8161 1144
C: Content-Type: multipart/related; boundary="boundary-324dav";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary-324dav
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.cal.example.com
C:
C: <modify id="modify01"/>
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-Type: text/calendar
C: Content-ID: query@cal.example.com
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: TARGET:relcalid-22
C: METHOD:DELETE
C: CMDID:random but unique per CAU
C: BEGIN:VQUERY C: BEGIN:VQUERY
C: QUERY: SELECT * FROM VEVENT WHERE UID='abcd12345' C: QUERY: SELECT * FROM VEVENT WHERE UID='abcd12345'
C: END:VQUERY C: END:VQUERY
C: END:VCALENDAR 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: LOCATION:
C: END:VEVENT One or more iCalendar object will be returned that contain
C: END:VCALENDAR a REQUEST-STATUS for the deleted components. There could have been
C: --boundary-324dav more than one component deleted, Any booked and any
C: Content-Type: text/calendar number of unprocessed iTIP scheduling components that
C: Content-ID: update@cal.example.com matched the QUERY value in the above example. Each
C: unique METHOD that was deleted from the store MUST BE in a
C: BEGIN:VCALENDAR seperate iCalendar object. This is because only one METHOD is allowed
C: BEGIN:VEVENT in an iCalendar object.
C: DTSTART:19990421T160000Z
C: DTEND:19990421T163000Z
C: END:VEVENT
C: END:VCALENDAR
C: --boundary-324dav--
C: END
S: RPY 1 11 . 9305 570
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
In this example, all instances of "Building 6" are replaced by "New 6.2.2.4 "modify" Command
office lobby" in VEVENTs:
C: MSG 1 12 . 9875 870 Attributes:
C: Content-Type: multipart/related; boundary="boundary-trew2";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary-trew2
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <modify id="modify02"/>
C: <select>
C: <source owner="user@cal.example.com" depth=*/>
C: <data content="cid:query@cal.example.com"/>
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: LOCATION:New office lobby
C: END:VEVENT
C: END:VCALENDAR
C: --boundary-trew2--
C: END
S: RPY 1 12 . 10745 578
S: Content-Type: multipart/related; boundary="boundary-poiu51";
S: start="command@cal.example.com";
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
6.2.4.4 "move" Command "latency" and "action" (Optional - see xxx)
Attributes: Response:
"id" (see Section 6.2.2.1). One of the following "request-status" codes MUST be returned:
Elements: 2.0 - successfully modified the component or calendar
"max-time": See Section 3.3. 6.1 - Container not found
"target": The "target" element points to the container where the 6.3 - Bad args
components are to be relocated.
"select": identifies the component(s) to move. The "modify" command is used to modify existing components. The
TARGET property specifies the calendars were the components
exist that are going to be modified.
Response: The format of the request is three containers inside of VCALENDAR
container object:
One "result" message for each "source" in the "select" element is BEGIN:VCALEDNAR
returned (see Section 3.1). <VQUERY>
<OLD-VALUES>
<NEW-VALUES>
END:CALENDAR
One of the following "request-status" codes MUST be returned: The VQUERY selects the components that are to be modified.
2.0 - successfully created the component or calendar The OLD-VALUES is a component and the contents of that component
are going to change and may contain information that helps uniquely
identify the original component (SEQUENCE in the example below).
If the CS can not find a component that matches the QUERY and does
not have at least all of the OLD-VALUES, then a 6.1 error is returned.
6.1 - Container not found The NEW-VALUES is a component of the same type as OLD-VALUES and
NEW-VALUES contains the new data for each selected component. Any
data that is in OLD-VALUES and not in NEW-VALUES is deleted from
the selected component. Any values in NEW-VALUES that was not in
OLD-VALULES is added to the component.
6.3 - Bad args In this example the VEVENT with UID:unique-58 has; the LOCATION and
LAST-MODIFIED changed, the VALARM with SEQUENCE:3 has its
TRIGGER disabled, the X-LOCAL property is removed from the VEVENT,
and a COMMENT is added.
The "data" element of each "result" message is subject to the Because SEQUENCE is used to locate the VALARM in this example,
result restriction table defined below. both the OLD-VALUES and the NEW-VALUES contains SEQUENCE:3 and
if SEQUENCE was left out of NEW-VALUES - it would have been deleted.
The "move" command is used to move components within the CS's Example:
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.
Restriction Table for "data" element of the "result" response: C: Content-Type: text/calendar
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: TARGET:my-cal
C: METHOD:MODIFY
C: BEGIN:VQUERY
C: QUERY:SELECT * FROM VEVENT WHERE UID = 'unique-58'
C: END:VQUERY
C: BEGIN:VEVENT
C: LOCATION:building 3
C: LAST-MODIFIED:20020101T123456Z
C: X-LOCAL:some private stuff
C: BEGIN:VALARM
C: SEQUENCE:3
C: TRIGGER;RELATED=END:PT5M
C: END:VALARM
C: END:VEVENT
C: BEGIN:VEVENT
C: LOCATION:building 4
C: LAST-MODIFIED:20020202T010203Z
C: COMMENT:Ignore global trigger.
C: BEGIN:VALARM
C: SEQUENCE:3
C: TRIGGER;ENABLE=FALSE:RELATED=END:PT5M
C: END:VALARM
C: END:VEVENT
C: />]]>
C: </modify>
C: END
Component/Property Presence Comment X-LOCAL was not supplied in the NEW-VALUES, so it was deleted.
------------------- -------- ------------------------------- LOCATION was altered, as was LAST-MODIFIED. The VALARM with
SEQUENCE:3 had its TRIGGER disabled, and SEQUENCE did not
change so it was not effected. COMMENT was added.
VCALENDAR 1+ When it comes to inline ATTACHMENTs, the CUA only needs to uniquely
. VERSION 1 MUST be 2.1 identify the contents of the ATTACHE value in the OLD-VALUES in order
to delete them. When the CS compares the attachment data it is compared
in it binary form. The ATTACHMENT value supplied by the CUA MUST BE
valid encoded information.
. VAGENDA 0+ For example, to delete a huge inline attachment from every
. . RELCALID 1 VEVENT in 'my-cal' that has an ATTACH with the OLD-VALUES:
. . REQUEST-STATUS 1+
. VCAR 0+ BEGIN:VCALENDAR
. . CARID 1 VERSION:2.0
. . REQUEST-STATUS 1+ TARGET:my-cal
METHOD:MODIFY
BEGIN:VQUERY
QUERY:SELECT ATTACH FROM VEVENT
END:VQUERY
BEGIN:VEVENT
ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY:
MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U
EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE
...<remander of attachment data NOT supplied> ....
END:VEVENT
BEGIN:VEVENT
END:VEVENT
END:VCALENDAR
. VEVENT 0+ Above the NEW-VALUES is empty, so everything in the OLD-VALUES
. . UID 1 is deleted.
. . REQUEST-STATUS 1+
. . VALARM 0 if VEVENT was successfully Furthermore, the following additional restrictions apply:
saved
1+ if there were errors saving
alarms
. . . ALARMID 1
. . . REQUEST-STATUS 1+
. VFREEBUSY 0 One can not change the "UID" property of a component.
. VJOURNAL 0+ If a contained component is changed inside of a selected
. . UID 1 component, and that contained component has multiple
. . REQUEST-STATUS 1+ instances, then OLD-VALUES MUST contain information that
uniquely identifies the instance or instances that are
changing.
. VQUERY 0+ As all contained components that matching OLD-VALUES will be
. . REQUEST-STATUS 1+ modified. In the first modify example above, if SEQUENCE were
to be deleted from both the OLD-VALUES and NEW-VALUES, then all
TRIGGERs that matched the OLD-VALUES in all VALARM in the
selected VEVENTs would be disabled.
. VTODO 0+ The result of the modify MUST BE a valid iCalendar object.
. . 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: If the REQUEST-STATUS is 2.0, then the entire modification was
successful.
1) Should one be able to move a calendar owned by person X into a If any error occurred:
calendar owned by person Y. (Can these such rights be specified
in VCARs?)
Example: moving the VAGENDA Nellis to Area-51 No component will be changed at all. That is, it will
appear just as it was prior to the modify and the CAP server
SHOULD return a REQUEST-STATUS for each error that occurred.
There MUST BE at least one error reported.
If multiple components are selected, then the UID for each selected
component MUST BE returned if the component contains a UID:
C: MSG 1 12 . 11323 613
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: BEGIN:VCALENDAR
C: BEGIN:VQUERY
C: QUERY: SELECT * FROM VAGENDA WHERE RELCALID='Nellis'
C: END:VQUERY
C: END:VCALENDAR
C: --boundary-kljr--
C: END
S: RPY 1 2 . 11936 571
S: Content-Type: multipart/related; boundary="boundary-mnbvd";
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-Type: text/calendar
S: Content-ID: 2@cal.example.com
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: BEGIN:VAGENDA S: TARGET:relcalid
S: RELCALID:Nellis S: BEGIN:VEVENT
S: UID:123
S: REQUEST-STATUS: 2.0 S: REQUEST-STATUS: 2.0
S: END:VAGENDA S: END:VEVENT
S: END:VCALENDAR S: END:VCALENDAR
S: --boundary-mnbvd--
S: END
6.2.4.5 "search" Command 6.2.2.5 "search" Command
Attributes: Attributes:
"id" (see Section 6.2.2.1). "latency" and "action" (Optional - see xxx)
Elements:
"max-time": See Section 3.3.
"select": identifies the components to return.
"max-results": maximum number of components to return per source
(if omited unlimited).
"max-size": maximum size in bytes, of the iCalendar object to
return.
Response: Response:
A "result" message per "source" in the "select" element is One iCalendar message per "target" in the "select" element is
returned (see Section 3.1). returned (see Section xxx).
One of the following "request-status" codes MUST be returned: One of the following "request-status" codes MUST be returned:
2.0 - successfully created the component or calendar 2.0 - successfully executed the query
2.0.9 - success, but some data could not be returned
6.1 - Container not found 6.1 - Container not found
6.3 - Bad args 6.3 - Bad args
The "data" element of each "result" message points to an iCalendar
object composed of all the selected components. Only "REQUEST- The data in each result contains an iCalendar object composed
STATUS" and the properties mentioned in the "SELECT" clause of the of all the selected components. Only "REQUEST-STATUS"
QUERY are included in the components. and the properties mentioned in the "SELECT" clause of the
QUERY are included in the components. Each iCalendar object is
tagged with the TARGET property and optional CMDID property.
Searching for Events Searching for Events
In the example below events on March 10,1999 between 080000Z and In the example below events on March 10,1999 between 080000Z and
190000Z are read. In this case only 4 properties for each event are 190000Z are read. In this case only 4 properties for each event are
returned. Two calendars are specified. Only booked (vs scheduled) returned. Two calendars are specified. Only booked (vs scheduled)
entries are to be returned. The first result returns two VEVENTs entries are to be returned.
that match in that "source", the second result returns only one
VEVENT for the second "source". NOTE: BEEP headers and footers not included in the examples below.
C: MSG 1 13 . 12507 704
C: Content-Type: multipart/related; boundary="boundary-5329";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary-5329
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <search id="search01"/>
C: <select>
C: <source relcalid="relcal2"/>
C: <source relcalid="relcal3"/>
C: <data content="cid:query@cal.example.com"/>
C: </select>
C: </search>
C: --boundary-5329
C: Content-Type: text/calendar C: Content-Type: text/calendar
C: Content-ID: query@cal.example.com
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: VERSION:2.0
C: METHOD:SEARCH
C: CMDID:search01
C: TARGET:relcal2
C: TARGET:relcal3
C: BEGIN:VQUERY C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID
C: FROM VEVENT C: FROM VEVENT
C: WHERE DTEND >= '19990310T080000Z' C: WHERE DTEND >= '19990310T080000Z'
C: AND DTSTART <= '19990310T190000Z' C: AND DTSTART <= '19990310T190000Z'
C: AND METHOD IS NULL C: AND METHOD IS 'CREATE'
C: END:VQUERY C: END:VQUERY
C: END:VCALENDAR C: END:VCALENDAR
C: --boundary-5329--
C: END
S: ANS 1 13 . 13211 803 0
S: Content-Type: multipart/related; boundary="boundary-f4fw2";
S: start="answer@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-f4fw2
S: Content-Type: application/beep+xml
S: Content-ID: answer@cal.example.com
S:
S: <result id="search01">
S: <source relcalid="relcal2"/>
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-f4fw2
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.1 S: VERSION:2.0
S: METHOD:REPLY
S: TARGET:relacal2
S: CMDID:search01
S: REQUEST-STATUS:2.0
S: BEGIN:VEVENT S: BEGIN:VEVENT
S: DTSTART:19990310T090000Z S: DTSTART:19990310T090000Z
S: DTEND:19990310T100000Z S: DTEND:19990310T100000Z
S: UID:abcxyz12345 S: UID:abcxyz12345
S: SUMMARY:Meet with Sir Elton S: SUMMARY:Meet with Sir Elton
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VEVENT S: END:VEVENT
S: BEGIN:VEVENT S: BEGIN:VEVENT
S: DTSTART:19990310T130000Z S: DTSTART:19990310T130000Z
S: DTEND:19990310T133000Z S: DTEND:19990310T133000Z
S: UID:abcxyz8999 S: UID:abcxyz8999
S: SUMMARY:Meet with brave Sir Robin S: SUMMARY:Meet with brave Sir Robin
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VEVENT S: END:VEVENT
S: END:VCALENDAR S: END:VCALENDAR
S: --boundary-f4fw2--
S: END
S: ANS 1 13 . 14014 664 1
S: Content-Type: multipart/related; boundary="boundary-r432";
S: start="answer@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-r432
S: Content-Type: application/beep+xml
S: Content-ID: answer@cal.example.com
S:
S: <result id="search01">
S: <source relcalid="relcal3"/>
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-r432
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.1 S: VERSION:2.0
S: METHOD:REPLY
S: CMDID:search01
S: TARGET:relcal3
S: REQUEST-STATUS:2.0
S: BEGIN:VEVENT S: BEGIN:VEVENT
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: DTSTART:19990310T140000Z S: DTSTART:19990310T140000Z
S: DTEND:19990310T150000Z S: DTEND:19990310T150000Z
S: UID:123456asdf S: UID:123456asdf
S: SUMMARY:Summer Budget S: SUMMARY:Summer Budget
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VEVENT S: END:VEVENT
S: END:VCALENDAR S: END:VCALENDAR
S: --boundary-r432--
S: END
S: NUL 1 13 . 14678 0
S: END
The return values are subject to VCAR filtering. That is, if the The return values are subject to VCAR filtering. That is, if the
request contains properties to which the UPN does not have access, request contains properties to which the UPN does not have access,
those properties will not appear in the return values. If the UPN those properties will not appear in the return values. If the UPN
has access to at least one property of the component, but has been has access to at least one property of the component, but has been
denied access to all properties called out in the request, the denied access to all properties called out in the request, the
response will contain a single REQUEST-STATUS property indicating the response will contain a single REQUEST-STATUS property indicating the
error. That is, the VEVENT components will be the following: error. That is, the VEVENT components will be the following:
[EDITORS NOTE: Should the one(s) that the UPN has access to - be Here the request was successful, but the VEVENT contents
returned?] were not accessable (4.1).
S: ANS 1 13 . 14014 548 0
S: Content-Type: multipart/related; boundary="boundary-fmei3";
S: start="command@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-fmei3
S: Content-Type: application/beep+xml
S: Content-ID: command@cal.example.com
S:
S: <result>
S: <source relcalid="relcalid"/>
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-fmei3
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.1 S: METHOD:REPLY
S: TARGET:relcalid
S: CMIDID=any-id
S: VERSION:2.0
S: BEGIN:VEVENT S: BEGIN:VEVENT
S: REQUEST-STATUS:4.1 S: REQUEST-STATUS:4.1
S: END:VEVENT S: END:VEVENT
S: END:VCALENDAR S: END:VCALENDAR
S: --boundary-fmei3--
S: END
If the UPN has no access to any events at all, the response will If the UPN has no access to any components at all, the response will
simply be an empty data set. The response looks the same if there simply be an empty data set. The response looks the same if there
are particular events to which the CU has been denied access. the particular components did not exist.
S: ANS 1 13 . 14014 502 0
S: Content-Type: multipart/related; boundary="boundary-ewrvc";
S: start="command@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-ewrvc
S: Content-Type: application/beep+xml
S: Content-ID: command@cal.example.com
S:
S: <result>
S: <source relcalid="relcalid"/>
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-ewrvc
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.1 S: VERSION:2.0
S: METHOD:REPLY
S: CMDID:some-id
S: TARGET:ralcalid
S: REQUEST-STATUS:2.0
S: END:VCALENDAR S: END:VCALENDAR
S: --boundary-ewrvc--
S: END
Find alarms within a range of time for booked VEVENTs. Find alarms within a range of time for booked VEVENTs.
C: MSG 1 15 . 14678 747
C: Content-Type: multipart/related; boundary="boundary-weoiu";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary-weoiu
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <search id="search02"/>
C: <select>
C: <source relcalid="relcal2"/>
C: <source relcalid="relcal3"/>
C: <data content="cid:query@cal.example.com"/>
C: </select>
C: </search>
C: --boundary-weoiu
C: Content-Type: text/calendar C: Content-Type: text/calendar
C: Content-ID: query@cal.example.com
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: VERSION:2.0
C: METHOD:SEARCH
C: TARGET:"Doug:Baseball"
C: TARGET:"Steve:Baseball"
C: CMDID:search02
C: BEGIN:VQUERY C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID,VALARM.* C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID,VALARM
C: FROM VEVENT,VTODO C: FROM VEVENT,VTODO
C: WHERE VALARM.TRIGGER >= '19990310T080000Z' C: USING_COMPONENT VALARM my-alarm
C: AND VALARM.TRIGGER <= '19990310T190000Z' C: WHERE my-alarm.TRIGGER >= '19990310T080000Z'
C: AND METHOD IS NULL C: AND my-alarm.TRIGGER <= '19990310T190000Z'
C: AND METHOD = 'CREATE'
C: END:VQUERY C: END:VQUERY
C: END:VCALENDAR C: END:VCALENDAR
C: --boundary-weoiu--
C: END Here no data was returned for relcal2:
S: ANS 1 15 . 15426 511 0
S: Content-Type: multipart/related; boundary="boundary-kjhs";
S: start="command@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-kjhs
S: Content-Type: application/beep+xml
S: Content-ID: command@cal.example.com
S:
S: <result id="search02">
S: <source relcalid="relcal2"/>
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-kjhs
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.1 S: VERSION:2.0
S: TARGET:relcal2
S: CMDID:search02
S: METHOD:REPLY
S: REQUEST-STATUS:X.Y <- todo
S: END:VCALENDAR S: END:VCALENDAR
S: --boundary-kjhs--
S: END And here relcal3 did return some resuls:
S: ANS 1 2 . 15937 734 1
S: Content-Type: multipart/related; boundary="boundary-435fe";
S: start="command@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-435fe
S: Content-Type: application/beep+xml
S: Content-ID: command@cal.example.com
S:
S: <result id="search02">
S: <source relcalid="relcal3"/>
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-435fe
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.1 S: VERSION:2.0
S: METHOD:REPLY
S: TARGET:relcal3
S: CMDID:search02
S: REQUEST-STATUS:2.0
S: BEGIN:VEVENT S: BEGIN:VEVENT
S: DTSTART:19990310T130000Z S: DTSTART:19990310T130000Z
S: DTEND:19990310T133000Z S: DTEND:19990310T133000Z
S: UID:abcxyz8999 S: UID:abcxyz8999
S: SUMMARY:Meet with brave Sir Robin S: SUMMARY:Meet with brave Sir Robin
S: BEGIN:VALARM S: BEGIN:VALARM
S: TRIGGER:19990310T132500Z S: TRIGGER:19990310T132500Z
S: SUMMARY:Almost time... S: SUMMARY:Almost time...
S: ACTION:DISPLAY S: ACTION:DISPLAY
S: END:VALARM S: END:VALARM
S: END:VEVENT S: END:VEVENT
S: END:VCALENDAR S: END:VCALENDAR
S: --boundary-435fe--
S: END
S: NUL 1 15 . 16671 0
S: END
In this example bill@example.com reads a day's worth of events from In this example bill@example.com reads a day's worth of events from
cap://cal.example.com/opaqueid99. cap://cal.example.com/opaqueid99. And the optional cmdid is not
supplied as the CUA will not issue another command until this
one completes.
C: MSG 1 16 . 16671 668
C: Content-Type: multipart/related; boundary="boundary-vnj43";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary-vnj43
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <search id="xyz12345"/>
C: <select>
C: <source relcalid="opaqueid99"/>
C: <data content="cid:query@cal.example.com"/>
C: </select>
C: </search>
C: --boundary-vnj43
C: Content-Type: text/calendar
C: Content-ID: query@cal.example.com
C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: VERSION:2.1 C: VERSION:2.0
C: METHOD:SEARCH
C: TARGET:opaqueid99
C: BEGIN:VQUERY C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY, UID FROM VEVENT C: QUERY:SELECT DTSTART,DTEND,SUMMARY, UID FROM VEVENT
C: WHERE DTEND >= '19990714T080000Z' C: WHERE DTEND >= '19990714T080000Z'
C: AND DTSTART <= '19990715T080000Z' C: AND DTSTART <= '19990715T080000Z'
C: END:VQUERY C: END:VQUERY
C: END:VCALENDAR C: END:VCALENDAR
C: --boundary-vnj43--
C: END
S: RPY 1 16 . 17359 751
S: Content-Type: multipart/related; boundary="boundary-rfew";
S: start="command@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-rfew
S: Content-Type: application/beep+xml
S: Content-ID: command@cal.example.com
S:
S: <result id="xyz12345">
S: <source relcalid="opaqueid99"/>
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-rfew
S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: BEGIN:VEVENT
S: DTSTART:19990714T200000Z
S: DTEND:19990714T210000Z
S: UID:000444888929922
S: SUMMARY:Blah blah
S: END:VEVENT
S: BEGIN:VEVENT
S: UID:0034848098038888989443
S: SUMMARY:meeting
S: DTEND:19990714T233000Z
S: DTSTART:19990714T223000Z
S: END:VEVENT
S: END:VCALENDAR
S: --boundary-rfew--
S: END
In this example bill@example.com reads a day's worth of events from
cap://cal.example.com/opaqueid101 and
cap://cal.example.com/opaqueid103
C: MSG 1 17 . 18110 694
C: Content-Type: multipart/related; boundary="boundary=wtu";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary=wtu
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <search id="xyz12346"/>
C: <select>
C: <source relcalid="opaqueid101"/>
C: <source relcalid="opaqueid103"/>
C: <data content="cid:query@cal.example.com"/>
C: </select>
C: </search>
C: --boundary=wtu
C: Content-Type: text/calendar
C: Content-ID: query@cal.example.com
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1
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=wtu--
C: END
S: ANS 1 17 . 18804 717 0
S: Content-Type: multipart/related; boundary="boundary-09436";
S: start="command@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-09436
S: Content-Type: application/beep+xml
S: Content-ID: command@cal.example.com
S:
S: <result id="xyz12346">
S: <source relcalid="opaqueid103"/>
S: <request-status code="2.0"/>
# this response code means that the transport successfully
# delivered the data.
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-09436
S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: BEGIN:VEVENT
S: UID:0034848098038888989443
S: SUMMARY:meeting
S: DTEND:19990714T233000Z
S: DTSTART:19990714T223000Z
S: END:VEVENT
S: END:VCALENDAR
S: --boundary-09436--
S: END
S: ANS 1 18 . 19521 216 1
S: Content-Type: application/beep+xml
S:
S: <result id="xyz12346">
S: <source relcalid="opaqueid101"/>
S: <request-status code="4.1">Access Denied<request-status/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: END
S: NUL 1 18 . 19737 0 If there are multiple targets, each iCalendar reply is contained
S: END within its own <reply>.
Stored VQUERY can be used by specifying the property QUERYNAME Stored VQUERY can be used by specifying the property QUERYID
instead of QUERY. instead of QUERY.
Example: This matches all calendar store properties. This MUST NOT return any
VAGENDAs. IT would return all RELATED-TO properties.
BEGIN:VQUERY
QUERYNAME:StoredVQuery-1
END:VQUERY
This match all calendar store properties. This MUST NOT return any
VAGENDAs.
BEGIN:VCALENDAR BEGIN:VCALENDAR
VERSION:2.1 VERSION:2.0
METHOD:SEARCH
TARGET:cap://bobo.ex.com
BEGIN:VQUERY BEGIN:VQUERY
QUERY:SELECT * FROM CALSTORE WHERE CSID='bobo.ex.com' QUERY:SELECT * FROM VCALSTORE
END:VQUERY END:VQUERY
END:VCALENDAR END:VCALENDAR
This will match all properties of the VAGENDA relcal4. This MUST NOT This will match all properties of the VAGENDA relcal4. This MUST NOT
return any components. return any components.
BEGIN:VCALENDAR BEGIN:VCALENDAR
VERSION:2.1 VERSION:2.0
METHOD:SEARCH
TARGET:cap://bobo.ex.com/relcal4
BEGIN:VQUERY BEGIN:VQUERY
QUERY:SELECT * FROM VAGENDA WHERE RELCALID='relcal4' QUERY:SELECT * FROM VAGENDA
END:VQUERY END:VQUERY
END:VCALENDAR END:VCALENDAR
This will fetch all stored VQUERYs. This will fetch all stored VQUERYs. All stored queries MUST BE
saved with a QUERYID.
BEGIN:VCALENDAR BEGIN:VCALENDAR
VERSION:2.1 VERSION:2.0
METHOD:SEARCH
TARGET:relcal4
BEGIN:VQUERY BEGIN:VQUERY
QUERY:SELECT * FROM VQUERY WHERE QUERYNAME IS NOT NULL QUERY:SELECT VQUERY.* FROM VQUERY.
END:VQUERY END:VQUERY
END:VCALENDAR END:VCALENDAR
6.3 Scheduling Commands 6.2.2.6 Response Codes
Scheduling commands allow a CU to indirectly manipulate a calendar by
asking another CU to perform an operation on their calendar. For
example, CU-A can request CU-B to add a meeting to their calendar; in
effect inviting CU-B to the meeting.
Calendar access rights can be granted for scheduling commands without
granting rights for more generalized access with the calendar
commands.
[EDITORS NOTE: This section needs to be completed by adding the
restriction tables for each of these iTIP methods. The basis for the
text is to be taken from [iTIP].]
6.3.1 "schedule" Command
Attributes:
"id" (see Section 6.2.2.1).
Elements:
"max-time": See Section 3.3.
"target": Each "target" element points to a container where the
sceduled element will be created.
"data": MUST point to a valid iTip iCalendar object. Refer to
[iTIP] for the definition of the accepted METHOD and restriction
tables.
Response:
One "result" message per "target" element MUST be returned (see
Section 3.1).
One of the following "request-status" codes MUST be returned:
2.0 - Success
6.1 - Container not found
6.3 - Bad args
Additionnal request-status code MAY be returned as described on
[iTIP].
The "data" element of each "result" message is subject to the
result restriction table defined below.
The "schedule" command insert a new scheduled component into the
VSCHEDULE set of the container(s) referred to by the "target"
element(s).
A Calendar Service MUST accept iCalendar object with the following
METHODs as described in [iTIP]:
-----------------------------------------------------------
Command Description
-----------------------------------------------------------
PUBLISH Publish a calendar entry to one or more
calendars.
REQUEST Schedule a calendar entry with one or more
calendars.
REPLY Response to a scheduling request.
ADD Add one or more instances to an existing
calendar entry.
CANCEL Cancel one or more instances to an existing
calendar entry.
REFRESH A request for the latest version of a
calendar entry.
COUNTER A request for a change (a counter-proposal)
to a calendar entry.
DECLINECOUNTER Decline a counter proposal.
-----------------------------------------------------------
6.3.2 Processing Scheduling Components
A CU might be invited to a meeting. If the CU had been invited by
CAP, the entry in the CU calendar will be scheduled, but not booked.
So a CUA will need to look for scheduled entries in the calendar and
present them to the CU or automatically decide if the invitation is
to be accepted or processed.
Example:
The little league coach places the teams entire schedule into your
calendar. Lets say that every game and practice is on a Friday night
and your calendar now has this iTIP scheduling data:
BEGIN:VCALENDAR
VERSION:2.0
METHOD:PUBLISH
BEGIN:VEVENT
DTSTAMP;TZID=US/Pacific:20000229T180000
DTSTART;TZID=US/Pacific:20000303T180000
ORGANIZER:coach@little.league.com
SUMMARY:Schedule of games and practice
UID:1-coach@little.league.com
SEQUENCE:0
DESCRIPTION:Please have your child at the field
and ready to play by 6pm.
RRULE:FREQ=WEEKLY;COUNT=10
END:VEVENT
END:VCALENDAR
At this point the above VEVENT is not booked in your calendar; it is
simply scheduled. A CUA would fetch this and all other scheduled
VEVENTs from your calendar with:
C: MSG 1 19 . 19737 582
C: Content-Type: multipart/related; boundary="boundary-rtij41";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary-rtij41
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <search id="xyz12345"/>
C: <select>
C: <source relcalid="relcal2"/>
C: <data content="cid:query@cal.example.com"/>
C: </select>
C: </search>
C: --boundary-rtij41
C: Content-Type: text/calendar
C: Content-ID: query@cal.example.com
C:
C: BEGIN:VCALENDAR
C: BEGIN:VQUERY
C: QUERY:SELECT * WHERE FROM VEVENT METHOD IS NOT NULL
C: END:VQUERY
C: END:VCALENDAR
C: --boundary-rtij41--
C: END
The CUA and CU could determine which scheduling entries were to
remain on the calendar. Each scheduling component could be deleted
or updated with the "modify" command to remove the iTip METHOD.
In some cases the CUA could automatically do the work and inform the
CU. An example of this is CANCEL. If configured to process
METHOD:CANCEL it could execute the "delete" command to delete the
component and inform the CU that the booked component had been
canceled.
The CUA MUST process the scheduled components in the order sent.
Some optimization could be done by the CUA. One example is if a
PUBLISH and later a CANCEL for the same component with the same
SEQUENCE number were scheduled, but not booked. The CUA might never
inform the CU and treat it as if the PUBLISH had never been received
by doing a "delete" command on both entries.
It is important to note that scheduled components do not show up in
busy time as BUSY. Only when they are booked does the TRANSP:OPAQUE
property take effect. A CS implementation MAY mark the time as
TENTATIVE. This is an implementation and administrative choice.
The CS MAY automatically process some iTIP request. For example a CS
MAY automatically send out REFRESH replies via iMIP or CAP, then
delete the REFRESH entry. But only if there are no other pending
scheduled entries for this calendar that may affect what REFRESH
would send back. If the CS is not able to reply to the REFRESH
request then it is left in the scheduling set until the CUA and CU
processes the set. At the point where there are no outstanding
scheduled command that would effect the reply results, the CS may
then automatically send the reply to the REFRESH request.
6.3.3 iTIP Examples
The following examples describe scenarios for the handling of
incoming iTIP data. An appropriate sort-order for the handling of
incoming iTIP is by UID, Recurrence-id, sequence, dtstamp. This
processing may be optimized, for instance, REFRESHs could be
processed last.
As an update to [iTIP], data with the "COUNTER" method should be
processed even if the Sequence number is stale.
6.3.3.1 Sending and Receiving an iTIP request
In this example A invites B and C to a meeting, B accepts the meeting
and C rejects it. The calendars for A, B and C are relcal1, relcal2
and relcal3 respectively, and are all on the same server,
"cal.example.com". A lot of these described actions are performed by
the CUAs and not the users themselves, the CUAs are called A-c, B-c
and C-c respectively.
A wishes to create a meeting with B and C, so A-c uses CAP to send
the following iTIP request to relcal2 and relcal3, while logged in to
"cal.example.com".
C: MSG 1 20 . 22254 874
C: Content-Type: multipart/related; boundary="boundary-rewf4";
C: start="1@cal.example.com;
C: type="application/beep+xml"
C:
C: --boundary-rewf4
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <schedule id="xhj-dd"/>
C: <target relcalid="relcal3"/>
C: <target relcalid="relcal2"/>
C: <select>
C: <data content="cid:request@cal.example.com"/>
C: </select>
C: </schedule>
C: --boundary-rewf4
C: Content-Type: text/calendar
C: Content-ID: request@cal.example.com
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1
C: METHOD:REQUEST
C: BEGIN:VEVENT
C: UID:abcd12345
C: DTSTART:19990307T180000Z
C: DTEND:19990307T190000Z
C: ORGANIZER:cap://cal.example.com/relcal1
C: ATTENDEE;RSVP=TRUE;
C: PARTSTAT=NEEDS-ACTION:cap://cal.example.com/relcal2
C: ATTENDEE;RSVP=TRUE;
C: PARTSTAT=NEEDS-ACTION:cap://cal.example.com/relcal3
C: SUMMARY:Important Meeting
C: END:VEVENT
C: END:VCALENDAR
C: --boundary-rewf4--
C: END
An incoming event (indicated by the value of the "METHOD" property)
then appears in relcal2 and relcal3, with the following data:
BEGIN:VEVENT
METHOD:REQUEST
UID:abcd12345
DTSTART:19990307T180000Z
DTEND:19990307T190000Z
ORGANIZER:cap://cal.example.com/relcal1
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.example.c
om/relcal2
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.example.c
om/relcal3
SUMMARY:Important Meeting
END:VEVENT
B-c and C-c must search for such incoming events, they do so using
the following CAP search:
C: MSG 1 21 . 24655 631
C: Content-Type: multipart/related; boundary="boundary-ytem";
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary-ytem
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com;
C:
C: <search id="xhr-de">