draft-ietf-calsch-cap-08.txt   draft-ietf-calsch-cap-09.txt 
Network Working Group D. Royer Network Working Group D. Royer
Internet-Draft INET-Consulting Internet-Draft INET-Consulting
Expires: December 29, 2002 G. Babics Expires: May 4, 2003 G. Babics
Steltor Oracle
P. Hill P. Hill
MIT Massachusetts Institute of
Technology
S. Mansour S. Mansour
AOL/Netscape AOL/Netscape
June 30, 2002 November 3, 2002
Calendar Access Protocol (CAP) Calendar Access Protocol (CAP)
draft-ietf-calsch-cap-08 draft-ietf-calsch-cap-09.txt
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
skipping to change at page 1, line 37 skipping to change at page 1, line 38
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http:// The list of current Internet-Drafts can be accessed at 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 December 29, 2002. This Internet-Draft will expire on May 4, 2003.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2002). All Rights Reserved. Copyright (C) The Internet Society (2002). All Rights Reserved.
Abstract Abstract
The Calendar Access Protocol (CAP) is an Internet protocol described The Calendar Access Protocol (CAP) is an Internet protocol described
in this memo that permits a Calendar User (CU) to utilize a Calendar in this memo that permits a Calendar User (CU) to utilize a Calendar
User Agent (CUA) to access an [iCAL] based Calendar Store (CS). User Agent (CUA) to access an [iCAL] based Calendar Store (CS).
skipping to change at page 2, line 22 skipping to change at page 2, line 23
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 . . . . . . . . . . . . . . . . . . . . . . 7 1.3 Definitions . . . . . . . . . . . . . . . . . . . . . . 7
2. Additions to iCalendar . . . . . . . . . . . . . . . . . 12 2. Additions to iCalendar . . . . . . . . . . . . . . . . . 12
2.1 New Value Types (summary) . . . . . . . . . . . . . . . 13 2.1 New Value Types (summary) . . . . . . . . . . . . . . . 13
2.1.1 New Parameters (summary) . . . . . . . . . . . . . . . . 14 2.1.1 New Parameters (summary) . . . . . . . . . . . . . . . . 14
2.1.2 New Properties (summary) . . . . . . . . . . . . . . . . 15 2.1.2 New Properties (summary) . . . . . . . . . . . . . . . . 15
2.1.3 New Components (summary) . . . . . . . . . . . . . . . . 17 2.1.3 New Components (summary) . . . . . . . . . . . . . . . . 17
2.2 Relationship of RFC-2446 (ITIP) and CAP . . . . . . . . 17 2.2 Relationship of RFC-2446 (ITIP) and CAP . . . . . . . . 18
3. CAP Design . . . . . . . . . . . . . . . . . . . . . . . 20 3. CAP Design . . . . . . . . . . . . . . . . . . . . . . . 20
3.1 System Model . . . . . . . . . . . . . . . . . . . . . . 20 3.1 System Model . . . . . . . . . . . . . . . . . . . . . . 20
3.2 Calendar Store Object Model . . . . . . . . . . . . . . 20 3.2 Calendar Store Object Model . . . . . . . . . . . . . . 20
3.3 Protocol Model . . . . . . . . . . . . . . . . . . . . . 21 3.3 Protocol Model . . . . . . . . . . . . . . . . . . . . . 21
3.3.1 Use of BEEP, MIME and iCalendar . . . . . . . . . . . . 22 3.3.1 Use of BEEP, MIME and iCalendar . . . . . . . . . . . . 22
4. Security Model . . . . . . . . . . . . . . . . . . . . . 24 4. Security Model . . . . . . . . . . . . . . . . . . . . . 24
4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . . 24 4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . . 24
4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . . 24 4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . . 24
4.1.2 Anonymous Users and Authentication . . . . . . . . . . . 25 4.1.2 Anonymous Users and Authentication . . . . . . . . . . . 25
4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . . 25 4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . . 25
4.2 Access Rights . . . . . . . . . . . . . . . . . . . . . 26 4.2 Access Rights . . . . . . . . . . . . . . . . . . . . . 26
4.2.1 Access Control and NOCONFLICT . . . . . . . . . . . . . 26 4.2.1 Access Control and NOCONFLICT . . . . . . . . . . . . . 26
4.2.2 Calendar Access Right (VCAR) . . . . . . . . . . . . . . 26 4.2.2 Calendar Access Right (VCAR) . . . . . . . . . . . . . . 26
4.2.3 Predefined VCARs . . . . . . . . . . . . . . . . . . . . 27 4.2.3 Predefined VCARs . . . . . . . . . . . . . . . . . . . . 27
4.2.4 Decreed VCARs . . . . . . . . . . . . . . . . . . . . . 28 4.2.4 Decreed VCARs . . . . . . . . . . . . . . . . . . . . . 28
4.3 CAP Session Identity . . . . . . . . . . . . . . . . . . 29 4.3 CAP Session Identity . . . . . . . . . . . . . . . . . . 29
5. CAP URL and Calendar Address . . . . . . . . . . . . . . 31 5. CAP URL and Calendar Address . . . . . . . . . . . . . . 31
6. New Components, Properties, Parameters, and Values . . . 33 6. New Value Types . . . . . . . . . . . . . . . . . . . . 33
6.1 Property Value Data Types . . . . . . . . . . . . . . . 33 6.1 Property Value Data Types . . . . . . . . . . . . . . . 33
6.1.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . . . 33 6.1.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . . . 33
6.1.1.1 CAL-OWNERS() . . . . . . . . . . . . . . . . . . . . . . 39 6.1.1.1 [NOT] CAL-OWNERS() . . . . . . . . . . . . . . . . . . . 38
6.1.1.2 CURRENT-TARGET() . . . . . . . . . . . . . . . . . . . . 39 6.1.1.2 CURRENT-TARGET() . . . . . . . . . . . . . . . . . . . . 39
6.1.1.3 [NOT] OWNER() . . . . . . . . . . . . . . . . . . . . . 39 6.1.1.3 PARAM() . . . . . . . . . . . . . . . . . . . . . . . . 39
6.1.1.4 SELF() . . . . . . . . . . . . . . . . . . . . . . . . . 39 6.1.1.4 SELF() . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.1.1.5 STATE() . . . . . . . . . . . . . . . . . . . . . . . . 39 6.1.1.5 STATE() . . . . . . . . . . . . . . . . . . . . . . . . 40
6.1.1.6 Ordering of Results . . . . . . . . . . . . . . . . . . 39 6.1.1.6 Ordering of Results . . . . . . . . . . . . . . . . . . 40
6.1.1.7 Date sorting order . . . . . . . . . . . . . . . . . . . 40 6.1.1.7 Date sorting order . . . . . . . . . . . . . . . . . . . 40
6.1.1.8 Use of single quote . . . . . . . . . . . . . . . . . . 41 6.1.1.8 Use of single quote . . . . . . . . . . . . . . . . . . 41
6.1.1.9 Comparing DATE and DATE-TIME values . . . . . . . . . . 41 6.1.1.9 Comparing DATE and DATE-TIME values . . . . . . . . . . 41
6.1.1.10 DTEND and DURATION . . . . . . . . . . . . . . . . . . . 42 6.1.1.10 DTEND and DURATION . . . . . . . . . . . . . . . . . . . 42
6.1.1.11 [NOT] LIKE . . . . . . . . . . . . . . . . . . . . . . . 44 6.1.1.11 [NOT] LIKE . . . . . . . . . . . . . . . . . . . . . . . 44
6.1.1.12 Empty vs. NULL . . . . . . . . . . . . . . . . . . . . . 44 6.1.1.12 Empty vs. NULL . . . . . . . . . . . . . . . . . . . . . 45
6.1.1.13 [NOT] IN . . . . . . . . . . . . . . . . . . . . . . . . 45 6.1.1.13 [NOT] IN . . . . . . . . . . . . . . . . . . . . . . . . 45
6.1.1.14 DATE-TIME and TIME values in a WHEN clause . . . . . . . 46 6.1.1.14 DATE-TIME and TIME values in a WHEN clause . . . . . . . 46
6.1.1.15 Multiple contained components . . . . . . . . . . . . . 46 6.1.1.15 Multiple contained components . . . . . . . . . . . . . 47
6.1.1.16 Example, Query by UID . . . . . . . . . . . . . . . . . 47 6.1.1.16 Example, Query by UID . . . . . . . . . . . . . . . . . 47
6.1.1.17 Query by Date-Time range . . . . . . . . . . . . . . . . 47 6.1.1.17 Query by Date-Time range . . . . . . . . . . . . . . . . 48
6.1.1.18 Query for all Unprocessed Entries . . . . . . . . . . . 47 6.1.1.18 Query for all Unprocessed Entries . . . . . . . . . . . 48
6.1.1.19 Query with Subset of Properties by Date/Time . . . . . . 48 6.1.1.19 Query with Subset of Properties by Date/Time . . . . . . 49
6.1.1.20 Query with Components and Alarms In A Range . . . . . . 49 6.1.1.20 Query with Components and Alarms In A Range . . . . . . 49
6.1.2 UPN Value Type . . . . . . . . . . . . . . . . . . . . . 49 6.1.2 UPN Value Type . . . . . . . . . . . . . . . . . . . . . 50
6.1.3 UPN-FILTER Value . . . . . . . . . . . . . . . . . . . . 50 6.1.3 UPN-FILTER Value . . . . . . . . . . . . . . . . . . . . 51
6.2 New Parameter . . . . . . . . . . . . . . . . . . . . . 51 7. New Parameters . . . . . . . . . . . . . . . . . . . . . 53
6.2.1 ENABLE Parameter . . . . . . . . . . . . . . . . . . . . 51 7.1 ENABLE Parameter . . . . . . . . . . . . . . . . . . . . 53
6.2.2 LOCAL Parameter . . . . . . . . . . . . . . . . . . . . 52 7.2 LOCAL Parameter . . . . . . . . . . . . . . . . . . . . 53
7. New Properties . . . . . . . . . . . . . . . . . . . . . 54 8. New Properties . . . . . . . . . . . . . . . . . . . . . 55
7.1 ALLOW-CONFLICT Property . . . . . . . . . . . . . . . . 54 8.1 ALLOW-CONFLICT Property . . . . . . . . . . . . . . . . 55
7.2 CALID Property . . . . . . . . . . . . . . . . . . . . . 54 8.2 ATT-COUNTER Property . . . . . . . . . . . . . . . . . . 55
7.3 CALMASTER Property . . . . . . . . . . . . . . . . . . . 55 8.3 CALID Property . . . . . . . . . . . . . . . . . . . . . 56
7.4 CARID Property . . . . . . . . . . . . . . . . . . . . . 56 8.4 CALMASTER Property . . . . . . . . . . . . . . . . . . . 57
7.5 CSID Property . . . . . . . . . . . . . . . . . . . . . 56 8.5 CARID Property . . . . . . . . . . . . . . . . . . . . . 57
7.6 DECREED Property . . . . . . . . . . . . . . . . . . . . 57 8.6 CSID Property . . . . . . . . . . . . . . . . . . . . . 58
7.7 DEFAULT-CHARSET Property . . . . . . . . . . . . . . . . 58 8.7 DECREED Property . . . . . . . . . . . . . . . . . . . . 59
7.8 DEFAULT-LOCALE Property . . . . . . . . . . . . . . . . 58 8.8 DEFAULT-CHARSET Property . . . . . . . . . . . . . . . . 59
7.9 DEFAULT-TZID Property . . . . . . . . . . . . . . . . . 59 8.9 DEFAULT-LOCALE Property . . . . . . . . . . . . . . . . 60
7.10 DEFAULT-VCARS Property . . . . . . . . . . . . . . . . . 60 8.10 DEFAULT-TZID Property . . . . . . . . . . . . . . . . . 61
7.11 DENY Property . . . . . . . . . . . . . . . . . . . . . 61 8.11 DEFAULT-VCARS Property . . . . . . . . . . . . . . . . . 62
7.12 EXPAND property . . . . . . . . . . . . . . . . . . . . 62 8.12 DENY Property . . . . . . . . . . . . . . . . . . . . . 63
7.13 GRANT Property . . . . . . . . . . . . . . . . . . . . . 62 8.13 EXPAND property . . . . . . . . . . . . . . . . . . . . 63
7.14 MAXDATE Property . . . . . . . . . . . . . . . . . . . . 63 8.14 GRANT Property . . . . . . . . . . . . . . . . . . . . . 64
7.15 MINDATE Property . . . . . . . . . . . . . . . . . . . . 64 8.15 MAXDATE Property . . . . . . . . . . . . . . . . . . . . 65
7.16 NAME Property . . . . . . . . . . . . . . . . . . . . . 64 8.16 MINDATE Property . . . . . . . . . . . . . . . . . . . . 65
7.17 OWNER Property . . . . . . . . . . . . . . . . . . . . . 65 8.17 MULTIPART Property . . . . . . . . . . . . . . . . . . . 66
7.18 PERMISSION Property . . . . . . . . . . . . . . . . . . 66 8.18 NAME Property . . . . . . . . . . . . . . . . . . . . . 67
7.19 QUERY property . . . . . . . . . . . . . . . . . . . . . 67 8.19 OWNER Property . . . . . . . . . . . . . . . . . . . . . 68
7.20 QUERYID property . . . . . . . . . . . . . . . . . . . . 67 8.20 PERMISSION Property . . . . . . . . . . . . . . . . . . 69
7.21 REQUEST-STATUS property . . . . . . . . . . . . . . . . 68 8.21 QUERY property . . . . . . . . . . . . . . . . . . . . . 69
7.22 RESTRICTION Property . . . . . . . . . . . . . . . . . . 69 8.22 QUERYID property . . . . . . . . . . . . . . . . . . . . 70
7.23 SCOPE Property . . . . . . . . . . . . . . . . . . . . . 70 8.23 REQUEST-STATUS property . . . . . . . . . . . . . . . . 71
7.24 TARGET Property . . . . . . . . . . . . . . . . . . . . 71 8.24 RESTRICTION Property . . . . . . . . . . . . . . . . . . 72
7.25 TRANSP Property . . . . . . . . . . . . . . . . . . . . 71 8.25 SCOPE Property . . . . . . . . . . . . . . . . . . . . . 73
8. New Components . . . . . . . . . . . . . . . . . . . . . 73 8.26 TARGET Property . . . . . . . . . . . . . . . . . . . . 73
8.1 VAGENDA Component . . . . . . . . . . . . . . . . . . . 73 8.27 TRANSP Property . . . . . . . . . . . . . . . . . . . . 74
8.2 VCALSTORE Component . . . . . . . . . . . . . . . . . . 75 9. New Components . . . . . . . . . . . . . . . . . . . . . 76
8.3 VCAR Component . . . . . . . . . . . . . . . . . . . . . 78 9.1 VAGENDA Component . . . . . . . . . . . . . . . . . . . 76
8.4 VRIGHT Component . . . . . . . . . . . . . . . . . . . . 81 9.2 VCALSTORE Component . . . . . . . . . . . . . . . . . . 78
8.5 VREPLY Component . . . . . . . . . . . . . . . . . . . . 82 9.3 VCAR Component . . . . . . . . . . . . . . . . . . . . . 81
8.6 VQUERY Component . . . . . . . . . . . . . . . . . . . . 82 9.4 VRIGHT Component . . . . . . . . . . . . . . . . . . . . 84
9. Commands and Responses . . . . . . . . . . . . . . . . . 84 9.5 VREPLY Component . . . . . . . . . . . . . . . . . . . . 85
9.1 CAP Commands (CMD) . . . . . . . . . . . . . . . . . . . 84 9.6 VQUERY Component . . . . . . . . . . . . . . . . . . . . 85
9.1.1 Bounded Latency . . . . . . . . . . . . . . . . . . . . 85 10. Commands and Responses . . . . . . . . . . . . . . . . . 87
9.1.2 ABORT Command . . . . . . . . . . . . . . . . . . . . . 88 10.1 CAP Commands (CMD) . . . . . . . . . . . . . . . . . . . 87
9.1.3 CONTINUE Command . . . . . . . . . . . . . . . . . . . . 88 10.1.1 Bounded Latency . . . . . . . . . . . . . . . . . . . . 88
9.1.4 CREATE Command . . . . . . . . . . . . . . . . . . . . . 90 10.1.2 ABORT Command . . . . . . . . . . . . . . . . . . . . . 91
9.1.5 DELETE Command . . . . . . . . . . . . . . . . . . . . . 96 10.1.3 CONTINUE Command . . . . . . . . . . . . . . . . . . . . 92
9.2 GENERATE-UID Command . . . . . . . . . . . . . . . . . . 99 10.1.4 CREATE Command . . . . . . . . . . . . . . . . . . . . . 93
9.3 GET-CAPABILITY Command . . . . . . . . . . . . . . . . . 101 10.1.5 DELETE Command . . . . . . . . . . . . . . . . . . . . . 99
9.4 IDENTIFY Command . . . . . . . . . . . . . . . . . . . . 105 10.2 GENERATE-UID Command . . . . . . . . . . . . . . . . . . 102
9.5 MODIFY Command . . . . . . . . . . . . . . . . . . . . . 107 10.3 GET-CAPABILITY Command . . . . . . . . . . . . . . . . . 104
9.6 MOVE Command . . . . . . . . . . . . . . . . . . . . . . 112 10.4 IDENTIFY Command . . . . . . . . . . . . . . . . . . . . 108
9.7 REPLY Response to a Command . . . . . . . . . . . . . . 115 10.5 MODIFY Command . . . . . . . . . . . . . . . . . . . . . 111
9.8 SEARCH Command . . . . . . . . . . . . . . . . . . . . . 116 10.6 MOVE Command . . . . . . . . . . . . . . . . . . . . . . 115
9.9 SET-LOCALE Command . . . . . . . . . . . . . . . . . . . 119 10.7 REPLY Response to a Command . . . . . . . . . . . . . . 118
9.10 TIMEOUT Command . . . . . . . . . . . . . . . . . . . . 121 10.8 SEARCH Command . . . . . . . . . . . . . . . . . . . . . 119
9.11 Response Codes . . . . . . . . . . . . . . . . . . . . . 121 10.9 SET-LOCALE Command . . . . . . . . . . . . . . . . . . . 122
10. Object Registration . . . . . . . . . . . . . . . . . . 124 10.10 TIMEOUT Command . . . . . . . . . . . . . . . . . . . . 124
10.1 Registration of New and Modified Entities . . . . . . . 124 10.11 Response Codes . . . . . . . . . . . . . . . . . . . . . 125
10.2 Post the item definition . . . . . . . . . . . . . . . . 124 11. Object Registration . . . . . . . . . . . . . . . . . . 128
10.3 Allow a comment period . . . . . . . . . . . . . . . . . 124 11.1 Registration of New and Modified Entities . . . . . . . 128
10.4 Release a new RFC . . . . . . . . . . . . . . . . . . . 124 11.2 Post the item definition . . . . . . . . . . . . . . . . 128
11. BEEP and CAP . . . . . . . . . . . . . . . . . . . . . . 125 11.3 Allow a comment period . . . . . . . . . . . . . . . . . 128
11.1 BEEP Profile Registration . . . . . . . . . . . . . . . 125 11.4 Release a new RFC . . . . . . . . . . . . . . . . . . . 128
11.2 BEEP Exchange Styles . . . . . . . . . . . . . . . . . . 125 12. BEEP and CAP . . . . . . . . . . . . . . . . . . . . . . 129
12. IANA Considerations . . . . . . . . . . . . . . . . . . 126 12.1 BEEP Profile Registration . . . . . . . . . . . . . . . 129
13. Security Considerations . . . . . . . . . . . . . . . . 127 12.2 BEEP Exchange Styles . . . . . . . . . . . . . . . . . . 129
Authors' Addresses . . . . . . . . . . . . . . . . . . . 128 13. IANA Considerations . . . . . . . . . . . . . . . . . . 130
A. Acknowledgments . . . . . . . . . . . . . . . . . . . . 130 14. Security Considerations . . . . . . . . . . . . . . . . 131
B. Bibliography . . . . . . . . . . . . . . . . . . . . . . 131 Authors' Addresses . . . . . . . . . . . . . . . . . . . 132
Full Copyright Statement . . . . . . . . . . . . . . . . 133 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . 134
B. Bibliography . . . . . . . . . . . . . . . . . . . . . . 135
Full Copyright Statement . . . . . . . . . . . . . . . . 137
1. Introduction 1. Introduction
This document specifies how a Calendar CUA interacts with a CS to This document specifies how a Calendar CUA interacts with a CS to
manage calendar information. In particular, it specifies how to manage calendar information. In particular, it specifies how to
query, create, modify, and delete iCalendar components (e.g., events, query, create, modify, and delete iCalendar components (e.g., events,
to-dos, or daily journal entries). It further specifies how to to-dos, or daily journal entries). It further specifies how to
search for available busy time information. Synchronization with search for available busy time information. Synchronization with
CUAs is not covered. CUAs is not covered.
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 protocol (e.g., authentication and privacy) are provided within
[BEEP]. The protocol data units leverage the standard iCalendar [BEEP]. The protocol data units leverage the standard iCalendar
format [iCAL] to convey calendar related information. format [iCAL] to convey calendar related information.
CAP can also be used to store and fetch [iTIP] objects and when those CAP can also be used to store and fetch [iTIP] objects and when those
objects are used in this memo, they mean exactly the same as defined objects are used in this memo, they mean exactly the same as defined
in [iTIP]. When iCalendar objects are transfered between the in [iTIP]. When iCalendar objects are transfered between the CUA and
calendar user agent and a calendar server, some additional properties a CS, some additional properties and parameters may be added and the
and parameters may be added and the calendar user agent is CUA is responsible for correctly generating iCalendar objects to non
responsible for correctly generating iCalendar objects to non CAP CAP processes.
processes.
The definition of new components, properties, parameter's, and value The definition of new components, properties, parameter's, and value
types are broken into two parts. The first part summarizes and types are broken into two parts. The first part summarizes and
defined the new objects. The second part provides the detail and any defined the new objects. The second part provides the detail and any
ABNF for those objects. ABNF for those objects.
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 [RFCWORDS].
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 [iTIP]. Calendar components defined within the protocol defined by [iTIP]. Calendar components defined
by [iCAL] are referred to with capitalized, quoted-strings of text. by [iCAL] are referred to with capitalized, quoted-strings of text.
All iCalendar components should start with the letter "V". For All iCalendar components should 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 component and "VJOURNAL" refers to the daily refers to the to-do component and "VJOURNAL" refers to the daily
journal component. journal component.
skipping to change at page 6, line 23 skipping to change at page 6, line 22
"VTODO" component. "VTODO" component.
Property parameters defined by this memo are referred to with Property parameters defined by this memo are referred to with
capitalized, quoted-strings of text, followed by the word capitalized, quoted-strings of text, followed by the word
"parameter". For example, "PARTSTAT" parameter refers to the "parameter". For example, "PARTSTAT" parameter refers to the
iCalendar property parameter used to specify the participation status iCalendar property parameter used to specify the participation status
of an attendee. Enumerated values defined by this memo are referred of an attendee. Enumerated values defined by this memo are referred
to with capitalized text, either alone or followed by the word to with capitalized text, either alone or followed by the word
"value". "value".
Object states defined by this memo are referred to with capitalized,
quoted-strings of text, followed by the word "state". For example,
"BOOKED" state refers to an object in the booked state.
Within a query, the different parts are referred to as a "clause" and
its value as "clause value" and the clause name will be in uppercase
enclosed in quotes. Example, The "SELECT" clause or if the "SELECT"
clause value contains ...
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, [iCAL] - (RFC2445) Which specifies the objects, data types,
properties and property parameters used in the protocols, along properties and property parameters used in the protocols, along
with the methods for representing and encoding them. with 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 installations. scheduling between different installations.
[iMIP] - (RFC2447) Which specifies the Internet email binding for [iMIP] - (RFC2447) Which specifies the Internet email binding for
[iTIP]. [iTIP].
[GUIDE] - (draft/rfc...), a guide to implementers and describes the [GUIDE] - (RFC3283), a guide to implementers and describes the
elements of a calendaring system, how they interact with each elements of a calendaring system, how they interact with each
other, how they interact with end users, and how the standards and other, how they interact with end users, and how the standards and
protocols are used. protocols are used.
This memo does not attempt to repeat the specification of concepts 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 - An entry in the calendar store has one of three conceptual BOOKED - An obect in the calendar store has one of three conceptual
states. It is "UNPROCESSED", "BOOKED" or marked as "DELETED". states. It is "UNPROCESSED" state, "BOOKED" state or marked as
How the implementation stores the state of any object is not a "DELETED" state. How the implementation stores the state of any
protocol issues and is not discussed. An object can be said to be object is not a protocol issues and is not discussed. An object
booked, unprocessed, or marked for delete. can be said to be booked, unprocessed, or marked for delete.
1. A "UNPROCESSED" scheduling entry has been stored in the 1. An "UNPROCESSED" state scheduling object has been stored in
calendar store but has not been acted on by a Calendar User the calendar store but has not been acted on by a CU or CUA.
(CU) or Calendar User Agent (CUA). All scheduled entries are All scheduled entries are [iTIP] objects. All [iTIP] objects
[iTIP] objects. All [iTIP] objects in the store are not in the store are not in the "BOOKED" state. To retrieve any
booked. To retrieve any [iTIP] object, simply do a query [iTIP] object, simply do a query asking for any objects that
asking for any objects that were stored with its state set to were stored in the "UNPROCESSED" state.
"UNPROCESSED".
2. A booked entry is stored with the CREATE command. It is an 2. A "BOOKED" state entry is stored with the "CREATE" command.
entry that has been acted on by a CU or CUA and there has It is an object that has been acted on by a CU or CUA and
been a decision to store an object. To retrieve any booked there has been a decision to store an object. To retrieve any
object, simply do a query asking for any objects that were booked object, simply do a query asking for any objects that
stored with its state set to "BOOKED". were stored in the "BOOKED" state.
3. A marked for delete component has its state set to DELETE. To 3. A "DELETED" state entry is created by sending a "DELETE"
command with the "OPTION" parameter value set to "MARK". To
retrieve any deleted object, simply do a query asking for any retrieve any deleted object, simply do a query asking for any
objects that were stored with its state set to "DELETED". By objects that were stored in the "DELETED" state. By default
default objects marked for delete are not returned. The CUA objects marked for delete are not returned. The CUA must
must specifically ask for marked for delete objects. specifically ask for marked for delete objects. You can not
ask for components in the "DELETED" state and in other states
in the same "VQUERY" component, as there would be no way to
distinguish between them in the reply.
Calendar - A collection of logically related objects or entities Calendar - A collection of logically related objects or entities
each of which may be associated with a calendar date and possibly each of which may be associated with a calendar date and possibly
time of day. These entities can include calendar properties or time of day. These entities can include calendar properties or
components. In addition, a calendar might be related to other components. In addition, a calendar might be related to other
calendars with the "RELATED-TO" property. A calendar is calendars with the "RELATED-TO" property. A calendar is
identified by its unique calendar identifier. The [iCAL] defines identified by its unique calendar identifier. The [iCAL] defines
the initial calendar properties, calendar components and the initial calendar properties, calendar components and
properties that make up the contents of a calendar. properties that make up the contents of a calendar.
Calendar Access Protocol (CAP) - The standard Internet protocol that Calendar Access Protocol (CAP) - The standard Internet protocol that
permits a CUA to access and manipulate calendars residing on a permits a CUA to access and manipulate calendars residing on a
Calendar Store. (this memo) Calendar Store. (this memo)
Calendar Access Rights (VCAR) - The mechanism for specifying the CAP Calendar Access Rights (VCAR) - The mechanism for specifying the CAP
operations ("PERMISSION") that a particular calendar user ("UPN") operations ("PERMISSION") that a particular calendar user ("UPN")
is granted or denied permission to perform on a given calendar is granted or denied permission to perform on a given calendar
object ("SCOPE"). The calendar access rights are specified with object ("SCOPE"). The calendar access rights are specified with a
the "VCAR" calendar components within a CS and calendar. "VCAR" component.
Calendar Address - Also See Calendar URL - they are one in the same Calendar Address - Also See Calendar URL - they are one in the same
for CAP addresses. The calendar address can also be the value to for CAP addresses. The calendar address can also be the value to
the "ATTENDEE" and "ORGANIZER" properties as defined in [iCAL]. the "ATTENDEE" and "ORGANIZER" properties as defined in [iCAL].
Calendar URL - A calendar URL is a URL defined in this memo that Calendar URL - A calendar URL is a URL defined in this memo that
specifies the address of a CS or Calendar. specifies the address of a CS or Calendar.
Component- Any object that conforms to the iCalendar object format Component- Any object that conforms to the iCalendar object format
and that is either defined in an internet draft, registered with and that is either defined in an internet draft, registered with
IANA, or is an experimental object that is prefixed with "x-". IANA, or is an experimental object that is prefixed with "x-".
Some types of components include calendars, events, to-dos, Some types of components include calendars, events, to-dos,
journals, alarms, and time zones. A component consists of journals, alarms, and time zones. A component consists of
properties and possibly other contained components. For example, properties and possibly other contained components. For example,
an event may contain an alarm component. an event may contain an alarm component.
Container - This is a generic name for VCALSTORE or VAGENDA.
Properties - An attribute of a particular component. Some Properties - An attribute of a particular component. Some
properties are applicable to different types of components. For properties are applicable to different types of components. For
example, the "DTSTART" property is applicable to "VEVENT", example, the "DTSTART" property is applicable to the "VEVENT",
"VTODO", "VJOURNAL" components. Other components are applicable "VTODO", and "VJOURNAL" components. Other components are
only to an individual type of calendar component. For example, applicable only to an individual type of calendar component. For
the "TZURL" property may only applicable to "VTIMEZONE" example, the "TZURL" property may only be applicable to the
components. "VTIMEZONE" components.
Calendar Identifier (CalID) - A globally unique identifier Calendar Identifier (CalID) - A globally unique identifier
associated with a calendar. Calendars reside within a CS. See associated with a calendar. Calendars reside within a CS. See
Qualified Calendar Identifier and Relative Calendar Identifier. Qualified Calendar Identifier and Relative Calendar Identifier.
All CalIDs start with "cap:". All CalIDs start with "cap:".
Calendar Policy - A CAP operational restriction on the access or Calendar Policy - A CAP operational restriction on the access or
manipulation of a calendar. These may be outside of the scope of manipulation of a calendar. These may be outside of the scope of
the CAP protocol. An example of an implementation or site policy the CAP protocol. An example of an implementation or site policy
is, "events MUST BE scheduled in unit intervals of one hour". is, "events MUST BE scheduled in unit intervals of one hour".
Calendar Property - An attribute of a calendar ("VAGENDA"). The Calendar Property - An attribute of a calendar ("VAGENDA"). The
attribute applies to the calendar, as a whole. For example, the attribute applies to the calendar, as a whole. For example, the
"CALSCALE" property specifies the calendar scale (e.g., the "CALSCALE" property specifies the calendar scale (e.g., the
"GREGORIAN" value) for the whole calendar. "GREGORIAN" value) for the all entries within the calendar.
Calendar Server - An implementation of a Calendar Store that manages
one or more calendars.
Calendar Store (CS) - The data and service model definition for a Calendar Store (CS) - The data and service model definition for a
Calendar Store as defined in this memo. This memo does not Calendar Store as defined in this memo. This memo does not
specify how the CS is implemented. specify how the CS is implemented.
Calendar Server - An implementation of a Calendar Store (CS) that
manages one or more calendars.
Calendar Store Identifier (CSID) - The globally unique identifier Calendar Store Identifier (CSID) - The globally unique identifier
for an individual CS. A CSID consists of the host and port for an individual CS. A CSID consists of the host and port
portions of a "Common Internet Scheme Syntax" part of a URL, as portions of a "Common Internet Scheme Syntax" part of a URL, as
defined by [RFC1738]. The CSID excludes any reference to a defined by [URL]. The CSID excludes any reference to a specific
specific calendar. calendar.
Calendar Store Components - Components maintained in a CS specify a Calendar Store Components - Components maintained in a CS specify a
grouping of calendar store-wide information. grouping of calendar store-wide information.
Calendar Store Properties - Properties maintained in a Calendar Calendar Store Properties - Properties maintained in a Calendar
Store calendar store-wide information. Store calendar store-wide information.
Calendar User (CU) - An entity (often biological) that uses a Calendar User (CU) - An entity (often biological) that uses a
calendaring system. calendaring system.
Calendar User Agent (CUA) - The client application that a CU Calendar User Agent (CUA) - The client application that a CU
utilizes to access and manipulate a calendar. utilizes to access and manipulate a calendar.
CAP Session - An open communication channel between a CUA and a CAP Session - An open communication channel between a CUA and a
Calendar Server. If the CAP session is authenticated, the the CU Calendar Server. If the CAP session is authenticated, the CU is
is "authenticated" and it is an "authenticated CAP session". "authenticated" and it is an "authenticated CAP session".
Contained Component / Contained Properties - A component or property Contained Component / Contained Properties - A component or property
that is contained inside of another component. A "VALARM" that is contained inside of another component. A "VALARM"
component for example may be contained inside of a "VEVENT" component for example may be contained inside of a "VEVENT"
component. And a "TRIGGER" property could be a contained property component. And a "TRIGGER" property could be a contained property
of a "VALARM" component. of a "VALARM" component.
Delegate - A calendar user (sometimes called the delegatee) who has Delegate - A CU (sometimes called the delegatee) who has been
been assigned participation in a scheduled component (e.g., assigned participation in a scheduled component (e.g., VEVENT) by
VEVENT) by one of the attendees in the scheduled component one of the attendees in the scheduled component (sometimes called
(sometimes called the delegator). An example of a delegate is a the delegator). An example of a delegate is a team member told to
team member told to go to a particular meeting in place of another go to a particular meeting in place of another Attendee who is
Attendee who is unable to attend. unable to attend.
Designate - A calendar user who is authorized to act on behalf of Designate - A CU who is authorized to act on behalf of another CU.
another calendar user. An example of a designate is an assistant. An example of a designate is an assistant.
Experiential - The CUA and CS may implement experimental extensions Experiential - The CUA and CS may implement experimental extensions
to the protocol. They also might have experimental components, to the protocol. They also might have experimental components,
properties, and parameters. These extensions MUST start with "x-" properties, and parameters. These extensions MUST start with "x-"
(or "X-") and should include a vendor prefix (such as "x-myvendor- (or "X-") and should include a vendor prefix (such as "x-myvendor-
"). There is no guarantee that these experimental extensions will "). There is no guarantee that these experimental extensions will
interoperate with other implementations. There is no guarantee interoperate with other implementations. There is no guarantee
that they will not interact in unpredictable ways with other that they will not interact in unpredictable ways with other
vendor experimental extensions. Implementations should limit vendor experimental extensions. Implementations should limit
sending those extensions to other implementations. sending those extensions to other implementations.
Object - A generic name for any component, property, parameter, or Object - A generic name for any component, property, parameter, or
value type to be used in iCalendar. value type to be used in iCalendar.
Overlapped Booking - A policy which indicates whether or not Overlapped Booking - A policy which indicates whether or not
components with a "TRANSP" property not set to "TRANSPARENT- components with a "TRANSP" property not set to "TRANSPARENT-
NOCONFLICT" or "OPAQUE-NOCONFLICT" value can overlap one another. NOCONFLICT" or "OPAQUE-NOCONFLICT" value can overlap one another.
When the policy is applied to a calendar it indicates whether or When the policy is applied to a calendar it indicates whether or
not the time span of any component (VEVENT, VTODO, ...) in the not the time span of any component (VEVENT, VTODO, ...) in the
calendar can overlap the time span of any other component in the calendar can overlap the time span of any other component in the
same calendar. When applied to an individual entry, it indicates same calendar. When applied to an individual object, it indicates
whether or not any other component's time span can overlap that whether or not any other component's time span can overlap that
individual component. If the CS does not allow overlapped individual component. If the CS does not allow overlapped
booking, then the CS is unwilling to allow any overlapped bookings booking, then the CS is unwilling to allow any overlapped bookings
within any calendar in the CS. within any calendar in the CS.
Owner - One or more CUs or UGs that are listed in the "OWNER" Owner - One or more CUs or UGs that are listed in the "OWNER"
property in a calendar. There can be more than one owner. The " property in a calendar. There can be more than one owner. The "
Qualified Calendar Identifier (Qualified CalID) - A CalID in which Qualified Calendar Identifier (Qualified CalID) - A CalID in which
both the scheme and csid of the CAP URI are present. both the scheme and csid of the CAP URI are present.
skipping to change at page 10, line 33 skipping to change at page 10, line 46
Realm - A collection of calendar user accounts, identified by a Realm - A collection of calendar user accounts, identified by a
string. The name of the Realm is only used in UPNs. In order to string. The name of the Realm is only used in UPNs. In order to
avoid namespace conflict, the Realm SHOULD be postfixed with an avoid 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) - An identifier for an Relative Calendar Identifier (Relative CalID) - An identifier for an
individual calendar in a calendar store. It MUST BE unique within individual calendar in a calendar store. It MUST BE unique within
a calendar store. A Relative CalID consists of the "URL path" of a calendar store. A Relative CalID consists of the "URL path" of
the "Common Internet Scheme Syntax" portion of a URL, as defined the "Common Internet Scheme Syntax" portion of a URL, as defined
by [RFC396] and [RFC2718]. by [URI] and [URLGUIDE].
Session Identity - A UPN associated with a CAP session. A session Session Identity - A UPN associated with a CAP session. A session
gains an identity after successful authentication. The identity gains an identity after successful authentication. The identity
is used in combination with VCAR to determine access to data in is used in combination with VCAR to determine access to data in
the CS. the CS.
User Group (UG) - A collection of Calendar Users and/or User Groups. User Group (UG) - A collection of Calendar Users and/or User Groups.
These groups are expanded by the CS and may reside either locally These groups are expanded by the CS and may reside either locally
or in an external database or directory. The group membership may or in an external database or directory. The group membership may
be fixed or dynamic over time. be fixed or dynamic over time.
skipping to change at page 12, line 11 skipping to change at page 12, line 11
authentication MUST BE used, but unique identity MUST BE obscured, authentication MUST BE used, but unique identity MUST BE obscured,
a UPN of the form @DNS-domain-name may be used. For example, a UPN of the form @DNS-domain-name may be used. For example,
"@example.com". "@example.com".
2. Additions to iCalendar 2. Additions to iCalendar
Several new components, properties, parameters, and value types are Several new components, properties, parameters, and value types are
added in CAP. This section summarizes those new objects. added in CAP. This section summarizes those new objects.
This memo extends the properties that can go into 'calprops' as This memo extends the properties that can go into 'calprops' as
defined in [iCAL] section 4.6 page 51 to allow iTIP objects defined in [iCAL] section 4.6 page 51 to allow [iTIP] objects
transmitted between a CAP aware CUA and the CS to contain the transmitted between a CAP aware CUA and the CS to contain the
"TARGET" and "CMD" properties. This memo does not address how a CUA "TARGET" and "CMD" properties. This memo does not address how a CUA
transmits iTIP or iMIP objects to non CAP programs. transmits [iTIP] or [iMIP] objects to non CAP programs.
calprops = 2*( calprops = 2*(
; 'prodid' and 'version' are both REQUIRED, ; 'prodid' and 'version' are both REQUIRED,
; but MUST NOT occur more than once. ; but MUST NOT occur more than once.
; ;
prodid /version / prodid /version /
; These are optional, but MUST NOT occur ; These are optional, but MUST NOT occur
; more than once. ; more than once.
; ;
calscale / calscale /
method / method /
target /
iana-prop /
cmd / cmd /
; These are optional, and may occur more ; These are optional, and may occur more
; than once. ; than once.
; ;
target /
iana-prop /
x-prop x-prop
Another change is that the 'component' part of the 'icalbody' ABNF as
described in [iCAL] section 4.6 is optional when sending a command as
shown in the following updated ABNF:
icalbody = calprops component
; If the "VCALENDAR" component contains the "CMD"
; component then the 'component' is optional:
;
/ calprops ; Which MUST include a "CMD" property
In addition a problem exists with the control of "VALARM" components In addition a problem exists with the control of "VALARM" components
and their "TRIGGER" properties. A CU may wish to set their own alarm and their "TRIGGER" properties. A CU may wish to set their own alarm
(local alarms) on components. These local alarms are not to be (local alarms) on components. These local alarms are not to be
forwarded to other CUs, CUAs, or CSs as are the "SEQUENCE" property forwarded to other CUs, CUAs, or CSs as are the "SEQUENCE" property
and the "ENABLE" parameter. So for the protocol between a CUA and a and the "ENABLE" parameter. So for the protocol between a CUA and a
CS, the following changes apply to the CAP protocol from [iCAL] CS, the following changes apply to the CAP protocol from [iCAL]
section "4.6.6" page 67: section "4.6.6" page 67:
alarmc = "BEGIN" ":" "VALARM" CRLF alarmc = "BEGIN" ":" "VALARM" CRLF
alarm-seq alarm-seq
skipping to change at page 13, line 20 skipping to change at page 13, line 25
alarm-seq = "SEQUENCE" alarmseqparam ":" integer CRLF alarm-seq = "SEQUENCE" alarmseqparam ":" integer CRLF
alarmseqparam = *( ";" xparam) alarmseqparam = *( ";" xparam)
/ ";" local-param / ";" local-param
The CUA adds a "SEQUENCE" property to each "VALARM" component as it The CUA adds a "SEQUENCE" property to each "VALARM" component as it
books the component. This property along with the "LOCAL" and books the component. This property along with the "LOCAL" and
"ENABLE" parameters allow the CUA to uniquely identify any VALARM in "ENABLE" parameters allow the CUA to uniquely identify any VALARM in
any component. The CUA should remove those before forwarding to non any component. The CUA should remove those before forwarding to non
CAP aware CUAs (including iMIP CUAs). CAP aware CUAs (including [iMIP] CUAs).
In addition, if a CUA wished to ignore a "TRIGGER" property in a In addition, if a CUA wished to ignore a "TRIGGER" property in a
"VALARM" that was supplied to it by the ORGANIZER, the CUA needs a "VALARM" component that was supplied to it by the "Organizer", the
common way to tag that trigger as disabled. So for the protocol CUA needs a common way to tag that trigger as disabled. So for the
between a CUA and a CS, the following is a modification to [iCAL] protocol between a CUA and a CS, the following is a modification to
section "4.8.6.3" page 127: [iCAL] section "4.8.6.3" page 127:
trigger = "TRIGGER" 1*(";" enable-param) (trigrel / trigabs) trigger = "TRIGGER" 1*(";" enable-param) (trigrel / trigabs)
Section 6.2.1 and Section 6.2.2. Section 7.1 and Section 7.2.
These additions will be transmitted between a CS and a CAP aware CUA. These additions will be transmitted between a CS and a CAP aware CUA.
So the VERSION value will remain at "2.0" as no existing iTIP or iMIP So the "VERSION" value will remain at "2.0" as no existing [iTIP] or
implementation will be effected. [iMIP] implementation will be effected.
2.1 New Value Types (summary) 2.1 New Value Types (summary)
UPN The UPN value type is text value type restricted to only UPN UPN The UPN value type is text value type restricted to only UPN
values. (Section 6.1.2) values. (Section 6.1.2)
UPN-FILTER Like the UPN value type, but also includes filter rules UPN-FILTER Like the UPN value type, but also includes filter rules
that allow wildcards. (Section 6.1.3) that allow wildcards. (Section 6.1.3)
CALQUERY The "CAL-QUERY" (Section 6.1.1) value type is a query syntax CALQUERY The "CAL-QUERY" (Section 6.1.1) value type is a query syntax
that is used by the CUA to specify the rules that apply to a CAP that is used by the CUA to specify the rules that apply to a CAP
command. In the case of "SEARCH", the query language is used to command. In the case of "SEARCH" command the query language is
fetch objects from the CS. When used with "DELETE", the selected used to fetch objects from the CS. When used with the "DELETED"
objects are deleted from the CS. "CAL-QUERY" can also be used command, the selected objects are deleted from the CS. "CAL-
with "MOVE" and "MODIFY". QUERY" value type can also be used with "MOVE" and "MODIFY"
commands.
2.1.1 New Parameters (summary) 2.1.1 New Parameters (summary)
ENABLE - ENABLE -
The "ENABLE" parameter in CAP is used to tag a "TRIGGER" property The "ENABLE" parameter in CAP is used to tag a "TRIGGER" property
in a component as disabled or enabled. This is used when a in a component as disabled or enabled. This is used when a
scheduling request arrives and the CU wishes to ignore the trigger scheduling request arrives and the CU wishes to ignore the trigger
time included. (Section 6.2.1). time included. (Section 7.1).
Formal Definition: The "ENABLE" parameter is defined by the Formal Definition: The "ENABLE" parameter is defined by the
following notation: following notation:
enable-param = "ENABLE" "=" ("TRUE" / "FALSE") enable-param = "ENABLE" "=" ("TRUE" / "FALSE")
LOCAL - LOCAL -
The "LOCAL" parameter in CAP is used to tag a "SEQUENCE" property The "LOCAL" parameter in CAP is used to tag a "SEQUENCE" property
in a "VALARM" to signify that a VALARM is local or to be in a "VALARM" component to signify that a VALARM is local or to be
distributed. (Section 6.2.2). distributed. (Section 7.2).
For example, when inviting others to an event, the ORGANIZERs For example, when inviting others to an event, the "Organizer's"
booked VEVENT might contain VALARMs, and those VALARMS might be booked "VEVENT" component might contain "VALARM" components, and
'alarm be 5 minutes before the meeting'. However other ATTENDEEs, those "VALARM" component might be 'alarm be 5 minutes before the
may have to set their own VALARMs for the same event (assuming meeting'. However other "Attendees" may have to set their own
they reply that they will be attending). So, by tagging the "VALARM" components for the same event (assuming they reply that
VALARM as local the CUA MUST never forward those local VALARMs to they will be attending). So, by tagging the "VALARM" component as
other CS's or CUAs. local the CUA MUST never forward those local "VALARM" components
to other CS's or CUAs.
The CUA can not simply delete any VALARMs from components where The CUA can not simply delete any "VALARM components where the CU
the CU is not the ORGANIZER. If it did, any [iTIP] "COUNTER" is not the "Organizer". If it did, any [iTIP] "COUNTER" method
would result in the ORGANIZER thinking that the ATTENDEE wished to would result in the "Organizer" thinking that the "Attendee"
also counter with removing those VALARMs. And in addition, any wished to also counter with removing those "VALARM" components.
update to an existing component would re-create those VALARMs in And in addition, any update to an existing component would re-
the ATTENDEEs CS. create those "VALARM" components in the "Attendees" CS.
Formal Definition: The "LOCAL" parameter is defined by the Formal Definition: The "LOCAL" parameter is defined by the
following notation: following notation:
local-param = "LOCAL" "=" ("TRUE" / "FALSE") local-param = "LOCAL" "=" ("TRUE" / "FALSE")
2.1.2 New Properties (summary) 2.1.2 New Properties (summary)
ALLOW-CONFLICT - Some entries in a calendar might not be valid if ALLOW-CONFLICT - Some entries in a calendar might not be valid if
other entries were to allowed to overlap the same time span. other entries were allowed to overlap the same time span. Renting
Renting a car for example. It would not make sense to allow two a car for example. It would not make sense to allow two
reservations for the same car at the same time. The "ALLOW- reservations for the same car at the same time. The "ALLOW-
CONFLICT" property takes a boolean value. If FALSE, then CONFLICT" property takes a boolean value. If FALSE, then
conflicts are not allowed. (Section 7.1) conflicts are not allowed. (Section 8.1)
ATT-COUNTER - When storing a "METHOD" property with the "COUNTER"
method, there needs to be a way to remember who sent the COUNTER.
The ATT-COUNTER property MUST BE added to all "COUNTER" [iTIP]
components by the CUA before storing in a CS. (Section 8.2)
CSID - Each CS needs its own unique identifier. The "CSID" property CSID - Each CS needs its own unique identifier. The "CSID" property
is the official unique identifier for the CS. If the BEEP is the official unique identifier for the CS. If the BEEP
'serverName' attribute was suppled in the BEEP 'start' message, 'serverName' attribute was supplied in the BEEP 'start' message,
then the CSID will be mapped to the virtual host name supplied and then the CSID will be mapped to the virtual host name supplied and
the host name part of the CSID MUST BE the same as the the host name part of the CSID MUST BE the same as the
'serverName' value. This allows one CS implementation to service 'serverName' value. This allows one CS implementation to service
multiple virtual hosts. CS's are not required to support virtual multiple virtual hosts. CS's are not required to support virtual
hosting. If a CS does not support virtual hosting then it must hosting. If a CS does not support virtual hosting then it must
ignore the BEEP 'serverName'. (Section 7.5) ignore the BEEP 'serverName' attribute. (Section 8.6)
CALID - Each calendar within a CS needs to be uniquely identifiable. CALID - Each calendar within a CS needs to be uniquely identifiable.
The "CALID" property identifies a unique calendar within a CS. It The "CALID" property identifies a unique calendar within a CS. It
can be a full CALID or a relative CALID. (Section 7.2) can be a full CALID or a relative CALID. (Section 8.3)
CALMASTER - The "CALMASTER" property specifies the contact CALMASTER - The "CALMASTER" property specifies the contact
information for the CS. (Section 7.3) information for the CS. (Section 8.4)
CARID - Access rights can be saved and fetched by unique ID - the CARID - Access rights can be saved and fetched by unique ID - the
"CARID". (Section 7.4) "CARID" property. (Section 8.5)
CMD - The enumerated list of CAP commands and the options for those CMD - The CAP commands, as well as replies are transmitted using the
commands, as well as replies are transmitted using the "CMD" "CMD" property. (Section 10.1)
property. (Section 9.1)
DECREED - Some access rights are not changeable by the CUA. When DECREED - Some access rights are not changeable by the CUA. When
that is the case, the "DECREED" property value in the "VCAR" will that is the case, the "DECREED" property value in the "VCAR"
be TRUE. (Section 7.6) component will be TRUE. (Section 8.7)
DEFAULT-CHARSET - The list of charsets supported by the CS. The DEFAULT-CHARSET - The list of charsets supported by the CS. The
first entry MUST BE the default for the CS. (Section 7.7) first entry MUST BE the default for the CS. (Section 8.8)
DEFAULT-LOCALE - The list of locales supported by the CS. The first DEFAULT-LOCALE - The list of locales supported by the CS. The first
entry in the list is the default locale. (Section 7.8) entry in the list is the default locale. (Section 8.9)
DEFAULT-TZID - This is the list of known timezones supported. The DEFAULT-TZID - This is the list of known timezones supported. The
first entry is the default. (Section 7.9) first entry is the default. (Section 8.10)
DEFAULT-VCARS - A list of the CARIDs that will be used to create new DEFAULT-VCARS - A list of the "CARID" properties that will be used
calendars. (Section 7.10) to create new calendars. (Section 8.11)
DENY - The UPNs listed in the "DENY" property of a "VCAR" will
denied access as described in the "VRIGHT" component. (Section DENY - The UPNs listed in the "DENY" property of a "VCAR" component
7.11) will denied access as described in the "VRIGHT" component.
(Section 8.12)
EXPAND - This property tells the CS if the query reply should expand EXPAND - This property tells the CS if the query reply should expand
components into multiple instances. The default is FALSE. components into multiple instances. The default is FALSE.
(Section 7.12) (Section 8.13)
GRANT - The UPNs listed in the "GRANT" property of a "VCAR" will GRANT - The UPNs listed in the "GRANT" property of a "VCAR"
allowed access as described in the "VRIGHT" component. (Section component will allowed access as described in the "VRIGHT"
7.13) component. (Section 8.14)
MAXDATE - The maximum date supported by the CS. (Section 7.14) MAXDATE - The maximum date supported by the CS. (Section 8.15)
MINDATE - The minimum date supported by the CS. (Section 7.15) MINDATE - The minimum date supported by the CS. (Section 8.16)
MULTIPART - Passed in the capability messages to indicate which MIME
multipart types the sender supports. (Section 8.17)
NAME - Several storeable components such as "VCAR" and "VQUERY" may NAME - Several storeable components such as "VCAR" and "VQUERY" may
have the "NAME" property contained in them to describe in a have the "NAME" property contained in them to describe in various
various locals the purpose of the component. Components may have locals the purpose of the component. Components may have multiple
multiple "NAME" properties. (Section 7.16) "NAME" properties each with a unique "LANGUAGE" parameter.
(Section 8.18)
OWNER - Each calendar has at least one "OWNER". (xref OWNER - Each calendar has at least one "OWNER" property. (xref
target="OWNER"/>) Related to the "OWNER()" (Section 6.1.3) query target="OWNER"/>) Related to the "CAL-OWNERS()" (Section 6.1.1.1)
clause. query clause.
PERMISSION - This property specifies the permission being granted or PERMISSION - This property specifies the permission being granted or
denied. Examples are "READ" and "MODIFY". (Section 7.18) denied. Examples are the "SEARCH" and "MODIFY" values. (Section
8.20)
QUERY - Use to hold the CAL-QUERY (Section 7.19) for the component.
QUERYID - A unique id for a stored query. (Section 7.20) QUERY - Used to hold the CAL-QUERY (Section 8.21) for the component.
QUERYID - A unique id for a stored query. (Section 8.22)
REQUEST-STATUS - The [iCAL] "REQUEST-STATUS" property is extended to REQUEST-STATUS - The [iCAL] "REQUEST-STATUS" property is extended to
include new error numbers. (Section 7.21) include new error numbers. (Section 8.23)
RESTRICTION - In the final check when granting calendar access RESTRICTION - In the final check when granting calendar access
requests, the CS test the results to the value of the requests, the CS test the results to the value of the
"RESTRICTION" property in the corresponding "VRIGHT" component to "RESTRICTION" property in the corresponding "VRIGHT" component to
determine if the access meets that restriction. (Section 7.22) determine if the access meets that restriction. (Section 8.24)
SCOPE - The "SCOPE" property is used in "VRIGHT"s component to SCOPE - The "SCOPE" property is used in "VRIGHT"s component to
select the subset of data that may be acted upon when checking select the subset of data that may be acted upon when checking
access rights. (Section 7.23) access rights. (Section 8.25)
TARGET - The new VCALENDAR property "TARGET" (Section 7.24) used to TARGET - The new "VCALENDAR" component property "TARGET" (Section
specify which calendar(s) will be the subject of the CAP command. 8.26) is used to specify which calendar(s) will be the subject of
the CAP command.
TRANSP - This is a modification the the [iCAL] TRANSP property and TRANSP - This is a modification the [iCAL] "TRANSP" property and it
it allows more values. (Section 7.25) allows more values. The new values are related to conflict
control. (Section 8.27)
2.1.3 New Components (summary) 2.1.3 New Components (summary)
VAGENDA - CAP allows the fetching and storing of the entire contents VAGENDA - CAP allows the fetching and storing of the entire contents
of a calendar. The "VCALENDAR" object is not sufficient to of a calendar. The "VCALENDAR" component is not sufficient to
encapsulate all of the needed data that describes a calendar. The encapsulate all of the needed data that describes a calendar. The
VAGENDA object is the encapsulating object for an entire calendar. "VAGENDA" component is the encapsulating object for an entire
(Section 8.1) calendar. (Section 9.1)
VCALSTORE - Each CS contains one or more calendars (VAGENDAs), the VCALSTORE - Each CS contains one or more calendars (VAGENDAs), the
VCALSTORE object is the encapsulating object that can hold all of "VCALSTORE" component is the encapsulating object that can hold
the "VAGENDA"s along with any components and properties that are all of the "VAGENDA" components along with any components and
unique to the store level. (Section 8.2) properties that are unique to the store level. (Section 9.2)
VCAR - Calendar Access Rights are specified and encapsulated in the VCAR - Calendar Access Rights are specified and encapsulated in the
new iCalendar "VCAR" (Section 8.3) component. The "VCAR" new iCalendar "VCAR" (Section 9.3) component. The "VCAR"
component holds some new properties and at least one "VRIGHT" component holds some new properties and at least one "VRIGHT"
component. component.
VRIGHT - (Section 8.4) This component encapsulates a set of VRIGHT - (Section 9.4) This component encapsulates a set of
instructions to the CS that define the rights or restrictions instructions to the CS that define the rights or restrictions
needed. needed.
VREPLY - (Section 8.5) This component encapsulates a set of data VREPLY - (Section 9.5) This component encapsulates a set of data
that can consist of an arbitrary amounts of properties and that can consist of an arbitrary amounts of properties and
components. Its contents is dependent on the command that was components. Its contents is dependent on the command that was
issued. issued.
VQUERY - The search operation makes use of a new component, called VQUERY - The search operation makes use of a new component, called
"VQUERY" (Section 8.6) and a new value type "CAL-QUERY" (Section "VQUERY" (Section 9.6) and a new value type "CAL-QUERY" (Section
6.1.1). "VQUERY" is used to fetch objects from the CS. 6.1.1). The "VQUERY" component is used to fetch objects from the
CS.
2.2 Relationship of RFC-2446 (ITIP) and CAP 2.2 Relationship of RFC-2446 (ITIP) and CAP
[iTIP] describes scheduling methods which result in indirect [iTIP] describes scheduling methods which result in indirect
manipulation of components. In CAP, the "CREATE" command is used to manipulation of components. In CAP, the "CREATE" command is used to
deposit entities into the store. Other CAP commands such as deposit entities into the store. Other CAP commands such as
"DELETE", "MODIFY" and "MOVE" provide direct manipulation of "DELETE", "MODIFY" and "MOVE" command values provide direct
components. In the CAP calendar store model, scheduling messages are manipulation of components. In the CAP calendar store model,
conceptually kept separate from other components by their state. scheduling messages are conceptually kept separate from other
components by their state.
All scheduling operations and are as define in [iTIP]. This memo All scheduling operations and are as define in [iTIP]. This memo
makes no changes to any of the workflow described in [iTIP]. In this makes no changes to any of the workflow described in [iTIP]. In this
memo when referring to the presence of the "METHOD" property in an memo referring to the presence of the "METHOD" property in an object
object is the same as saying an [iTIP] object. is the same as saying an [iTIP] object.
A CUA may create a "BOOKED" entry by depositing a iCalendar object A CUA may create a "BOOKED" state object by depositing a iCalendar
into the store. This is done by depositing an object that does not object into the store. This is done by depositing an object that
have a "METHOD" property. The CS then knows to set the state of the does not have a "METHOD" property. The CS then knows to set the
object to "BOOKED". If the object has a "METHOD" property then the state of the object to the "BOOKED" state. If the object has a
object is stored in the "UNPROCESSED" state. "METHOD" property then the object is stored in the "UNPROCESSED"
state.
If existing "UNPROCESSED" objects exist in the CS for the same UID If existing "UNPROCESSED" state objects exist in the CS for the same
then a CUA may wish to consolidate the objects in to one "BOOKED" UID then a CUA may wish to consolidate the objects in to one "BOOKED"
object. The CUA would fetch the "UNPROCESSED" objects for that UID state object. The CUA would fetch the "UNPROCESSED" state objects
and process them in the CUA as described in [iTIP]. Then if the CUA for that UID and process them in the CUA as described in [iTIP].
wished to book the UID, then the CUA would issue a "CREATE" command Then if the CUA wished to book the UID, the CUA would issue a
to create the new "BOOKED" object in the CS, followed by a "DELETE" "CREATE" command to create the new "BOOKED" state object in the CS,
command to remove any related old [iTIP] objects from the CS. And it followed by a "DELETE" command to remove any related old [iTIP]
might also involve having the CUA send some [iMIP] objects or objects from the CS. And it might also involve having the CUA send
contacting other CS's and performing CAP operations on those CSs. some [iMIP] objects or contacting other CS's and performing CAP
operations on those CSs.
The CUA could also decide not to book the object. In which case the The CUA could also decide not to book the object. In which case the
"UNPROCESSED" objects could be deleted from the CS. Or the CUA could "UNPROCESSED" state objects could be removed from the CS or the CUA
set those object to the marked for delete. could set those object to the marked for delete state. The CUA could
also ignore objects for later processing.
The marked for delete state is used to keep the object around so that The marked for delete state is used to keep the object around so that
the CUA can process duplicate requests automatically. If a duplicate the CUA can process duplicate requests automatically. If a duplicate
[iTIP] object is deposited into the CS and there exists identical [iTIP] object is deposited into the CS and there exists identical
marked for delete objects, then a CUA acting on behalf of the "OWNER" marked for delete objects, then a CUA acting on behalf of the "OWNER"
can silently drop those duplicate entries. can silently drop those duplicate entries.
Another purpose for the marked for delete state is so that when a CU Another purpose for the marked for delete state is so that when a CU
decides they do not wish to have the object show in their calendar, decides they do not wish to have the object show in their calendar,
the CUA can book the object, changing the PARTSTAT parameter to the CUA can book the object; changing the "PARTSTAT" parameter to
"DECLINED" in the "ATTENDEE" property that corresponds to their UPN. "DECLINED" in the "ATTENDEE" property that corresponds to their UPN.
Perform an iTIP processing such as sending back a decline. Then mark Perform an [iTIP] processing such as sending back a decline. Then
that object as marked for delete. Their CUA might be configurable to mark that object as marked for delete. Their CUA might be
automatically drop any updates for that object knowing the CU has configurable to automatically drop any updates for that object
already declined. knowing the CU has already declined.
When synchronizing with multiple CUAs, the marked for delete state When synchronizing with multiple CUAs, the marked for delete state
could be used to inform the synchronization process that an object is could be used to inform the synchronization process that an object is
to be deleted. How synchronization is done is not specified in this to be deleted. How synchronization is done is not specified in this
memo. memo.
Several "UNPROCESSED" entries can be in the CS for the same UID. Several "UNPROCESSED" state entries can be in the CS for the same
However once consolidated, then only one entry exists in the CS and UID. However once consolidated, then only one object exists in the
that is the booked object. The others MUST BE removed, or have their CS and that is the booked object. The others MUST BE removed, or
state changed to "DELETED". have their state changed to "DELETED".
There MUST NOT BE more than one "BOOKED" entry in a calendar for the There MUST NOT BE more than one "BOOKED" state object in a calendar
same "UID". for the same "UID". The "ADD" method value may create multiple
objects all in the "BOOKED" state for the same UID, however for the
purpose of this memo, they are the same object that simply have
multiple "VCALENDAR" components.
For example, if you were on vacation, you could have a REQUEST to For example, if you were on vacation, you could have receive a
attend a meeting and several updates to that meeting. Your CUA would "REQUEST" method to attend a meeting and several updates to that
have to "SEARCH" them out of the CS using CAP, process them, meeting. Your CUA would have to issue "SEARCH" commands to find them
determine what the final state of the object from a possible in the CS using CAP, process them, determine what the final state of
combination of user input and programmed logic. Then the CUA would the object from a possible combination of user input and programmed
instruct the CS to create a new booked entry from the consolidated logic. Then the CUA would instruct the CS to create a new booked
results. Finally, the CUA could do a "DELETE" or change their state object from the consolidated results. Finally, the CUA could do a
to "DELETED" for all of these now old scheduling requests in the CS. "DELETE" command to remove the related "UNPROCESSED" state objects.
See [iTIP] for details on resolving multiple [iTIP] scheduling See [iTIP] for details on resolving multiple [iTIP] scheduling
entries. entries.
3. CAP Design 3. CAP Design
3.1 System Model 3.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 CUA to send commands to and receive responses from a
receive responses from a "Calendar Server" (CS). CS.
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. In addition the "GET-CAPABIBILITY" command can be sent from
the CS to the CUA.
There are two distinct protocols in operation to accomplish this There are two distinct protocols in operation to accomplish this
exchange. [BEEP] is the transport protocol is used to move these exchange. [BEEP] is the transport protocol is used to move these
encapsulations between a CUA and a CS. CAP's [BEEP] profile defines encapsulations between a CUA and a CS. CAP's [BEEP] profile defines
the application protocol where the content and semantics of the the application protocol where the content and semantics of the
messages sent between the CUA and the CS are specified. messages sent between the CUA and the CS are specified.
3.2 Calendar Store Object Model 3.2 Calendar Store Object Model
[iCAL] describes components such as events, todos, alarms, and [iCAL] describes components such as events, todos, alarms, and
timezones. [CAP] requires additional object infrastructure. In timezones. [CAP] requires additional object infrastructure. In
particular, detailed definitions of the containers for events and particular, detailed definitions of the containers for events and
todos (calendars), access control objects, and a query language. todos (calendars), access control objects, and a query language.
The conceptual model for a calendar store is shown below. The The conceptual model for a calendar store is shown below. The
calendar store (VCALSTORE - Section 8.2) contains "VCAR"s, "VQUERY"s, calendar store (VCALSTORE - Section 9.2) contains "VCAR"s, "VQUERY"s,
"VTIMEZONE"s, "VAGENDA"s and calendar store properties. "VTIMEZONE"s, "VAGENDA"s and calendar store properties.
Calendars (VAGENDAs) contain "VEVENT"s, "VTODO"s, "VJOURNAL"s, Calendars (VAGENDAs) contain "VEVENT"s, "VTODO"s, "VJOURNAL"s,
"VCAR"s, "VTIMEZONE"s, "VFREEBUSY", "VQUERY"s and calendar "VCAR"s, "VTIMEZONE"s, "VFREEBUSY", "VQUERY"s and calendar
properties. properties.
The component "VCALSTORE" is used to denote the a root of the The component "VCALSTORE" is used to denote the a root of the
calendar store and contains all of the calendars. calendar store and contains all of the calendars.
Calendar Store Calendar Store
VCALSTORE VCALSTORE
| |
+-- properties +-- properties
+-- VCARs +-- VCARs
+-- VQUERYs +-- VQUERYs
+-- VTIMEZONEs +-- VTIMEZONEs
+-- VAGENDAs +-- VAGENDA
| | | |
| +--properties | +--properties
| +--VEVENTs | +--VEVENTs
| | | | | |
| | +--VALARMs | | +--VALARMs
| +--VTODOs | +--VTODOs
| | | | | |
| | +--VALARMs | | +--VALARMs
| +--VJOURNALs | +--VJOURNALs
| +--VCARs | +--VCARs
| +--VTIMEZONEs | +--VTIMEZONEs
| +--VQUERYs | +--VQUERYs
| +--VFREEBUSY | +--VFREEBUSYs
| | | |
| | ... | | ...
. .
. .
+-- VAGENDAs +-- VAGENDA
. . . .
. . . .
. . . .
Calendars within a Calendar Store are identified by their unique Calendars within a Calendar Store are identified by their unique
Relative CALID. Relative CALID.
3.3 Protocol Model 3.3 Protocol Model
CAP uses beep as the transport and authentication protocol. CAP uses beep as the transport and authentication protocol.
skipping to change at page 22, line 8 skipping to change at page 22, line 8
'greeting' then the CUA may tell the CS to switch locales for the 'greeting' then the CUA may tell the CS to switch locales for the
session by issuing the "SET-LOCALE" CAP command and supplying one of session by issuing the "SET-LOCALE" CAP command and supplying one of
the locales supplied by the BEEP 'localize' attribute. If supplied the locales supplied by the BEEP 'localize' attribute. If supplied
the first locale supplied in the BEEP 'localize' attribute MUST BE the first locale supplied in the BEEP 'localize' attribute MUST BE
the default locale of the CS. The locale is switched only after a the default locale of the CS. The locale is switched only after a
successful reply. successful reply.
The "DEFAULT-CHARSET" property of the CS contains the list of The "DEFAULT-CHARSET" property of the CS contains the list of
charsets supported by the CS with the first value being the default charsets supported by the CS with the first value being the default
for new calendars. If the CUA wishes to switch to one of those for new calendars. If the CUA wishes to switch to one of those
charsets for the session, the CUA issues the "SET-LOCALE" CAP charsets for the session, the CUA issues the "SET-LOCALE" command.
command. The CUA would have to first perform a "GET-CAPABILITY" The CUA would have to first perform a "GET-CAPABILITY" command on the
command on the CS to get the list of charsets supported by the CS. CS to get the list of charsets supported by the CS. The charset is
The charset is switched only after a successful reply. switched only after a successful reply.
The CUA may switch locales and charsets as needed. There is no The CUA may switch locales and charsets as needed. There is no
requirement that a CS support multiple locales or charsets. requirement that a CS support multiple locales or charsets.
3.3.1 Use of BEEP, MIME and iCalendar 3.3.1 Use of BEEP, MIME and iCalendar
CAP uses the BEEP application protocol over TCP. (refer to [BEEP] CAP uses the BEEP application protocol over TCP. (refer to [BEEP]
and [BEEPTCP] for more information). The default port that the and [BEEPTCP] for more information). The default port that the
Calendar Server listens for connections is on user port 1026. Calendar Server listens for connections is on user port 1026.
skipping to change at page 22, line 39 skipping to change at page 22, line 39
initiator and responder are used as defined in [BEEP].) initiator and responder are used as defined in [BEEP].)
C: MSG 1 2 . 432 62 C: MSG 1 2 . 432 62
C: Content-Type: text/calendar C: Content-Type: text/calendar
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: VERSION:2.0 C: VERSION:2.0
C: PRODID:-//someone's prodid C: PRODID:-//someone's prodid
C: CMD;ID=unique-per-cua-123;OPTIONS=10:GENERATE-UID C: CMD;ID=unique-per-cua-123;OPTIONS=10:GENERATE-UID
C: END:VCALENDAR C: END:VCALENDAR
C: END
NOTE: The following examples will not include the BEEP header and NOTE: The following examples will not include the BEEP header and
footer information. Only the iCalendar objects that are sent between footer information. Only the iCalendar objects that are sent between
the CUA and CS will be shown as the BEEP payload boundaries are the CUA and CS will be shown as the BEEP payload boundaries are
independent of CAP. independent of CAP.
The commands listed below are used to manipulate or access the data The commands listed below are used to manipulate or access the data
on the calendar store: on the calendar store:
ABORT - Sent to halt the processing of any command except ABORT. ABORT - Sent to halt the processing of any command except ABORT.
(Section 9.1.2) (Section 10.1.2)
CONTINUE - Sent to continue processing a command that has had its CONTINUE - Sent to continue processing a command that has had its
specified timeout time reached. (Section 9.1.3) specified timeout time reached. (Section 10.1.3)
CREATE - Create a new object on the CS. This can be implied for CREATE - Create a new object on the CS. This can be implied for
iTIP objects. Initiated by the CUA only. (Section 9.1.4) [iTIP] objects. Initiated by the CUA only. (Section 10.1.4)
SET-LOCALE - Tell the CS to use any named locale and charset SET-LOCALE - Tell the CS to use any named locale and charset
supplied. Initiated by the CUA only. (Section 9.9) supplied. Initiated by the CUA only. (Section 10.9)
DELETE - Delete objects from the CS. Initiated by the CUA only. DELETE - Delete objects from the CS. Initiated by the CUA only.
Can also be used to mark a object for deletion. (Section 9.1.5) Can also be used to mark a object for deletion. (Section 10.1.5)
GENERATE-UID - Generate one or more unique ids. Initiated by the GENERATE-UID - Generate one or more unique ids. Initiated by the
CUA only. (Section 9.2) CUA only. (Section 10.2)
GET-CAPABILITY - Query the capabilities the other end point of the GET-CAPABILITY - Query the capabilities the other end point of the
session. (Section 9.3) session. (Section 10.3)
IDENTIFY - Set a new identity for the session. Initiated by the CUA IDENTIFY - Set a new identity for the session. Initiated by the CUA
only. (Section 9.4) only. (Section 10.4)
MODIFY - Modify components. Initiated by the CUA only. (Section MODIFY - Modify components. Initiated by the CUA only. (Section
9.5) 10.5)
MOVE - Move components to another container. Initiated by the CUA MOVE - Move components to another container. Initiated by the CUA
only. (Section 9.6) only. (Section 10.6)
REPLY - When replying to a command, the "CMD" value will be set to REPLY - When replying to a command, the "CMD" value will be set to
"REPLY" so that it will not be confused with a new command. "REPLY" so that it will not be confused with a new command.
(Section 9.7) (Section 10.7)
SEARCH - Search for components. Initiated by the CUA only. SEARCH - Search for components. Initiated by the CUA only.
(Section 9.8) (Section 10.8)
TIMEOUT - Sent when a specified amount of time has lapsed and a TIMEOUT - Sent when a specified amount of time has lapsed and a
command has not finished. (Section 9.10) command has not finished. (Section 10.10)
4. Security Model 4. Security Model
The BEEP transport performs all session authentication. The BEEP transport performs all session authentication.
4.1 Calendar User and UPNs 4.1 Calendar User and UPNs
A Calendar User (CU) is an entity that can be authenticated. It is A CU is an entity that can be authenticated. It is represented in
represented in CAP as a UPN, which is a key part of access rights. CAP as a UPN, which is a key part of access rights. The UPN
The UPN representation is independent of the authentication mechanism representation is independent of the authentication mechanism used
used during a particular CUA/CS interaction. This is because UPNs during a particular CUA/CS interaction. This is because UPNs are
are used within VCARs. If the UPN were dependent on the used within VCARs. If the UPN were dependent on the authentication
authentication mechanism, a VCAR could not be consistently evaluated. mechanism, a VCAR could not be consistently evaluated. A CU may use
A CU may use one mechanism while using one CUA but the same CU may one mechanism while using one CUA but the same CU may use a different
use a different authentication mechanism when using a different CUA, authentication mechanism when using a different CUA, or while
or while connecting from a different location. connecting from a different location.
The user may also have multiple UPNs for various purposes. The user may also have multiple UPNs for various purposes.
Note that the immutability of the user's UPN may be achieved by using Note that the immutability of the user's UPN may be achieved by using
SASL's authorization identity feature. (The transmitted SASL's authorization identity feature. (The transmitted
authorization identity may be different than the identity in the authorization identity may be different than the identity in the
client's authentication credentials.) [SASL, section 3]. This also client's authentication credentials.) [SASL, section 3]. This also
permits a CU to authenticate using their own credentials, yet request permits a CU to authenticate using their own credentials, yet request
the access privileges of the identity for which they are proxying the access privileges of the identity for which they are proxying
SASL. Also, the form of authentication identity supplied by a SASL. Also, the form of authentication identity supplied by a
skipping to change at page 25, line 16 skipping to change at page 25, line 16
In addition, legacy implementations exist where an RFC 822 name is In addition, legacy implementations exist where an RFC 822 name is
embedded in the subject distinguished name as an EmailAddress embedded in the subject distinguished name as an EmailAddress
attribute. The attribute value for EmailAddress is of type attribute. The attribute value for EmailAddress is of type
IA5String to permit inclusion of the character '@', which is not IA5String to permit inclusion of the character '@', which is not
part of the PrintableString character set. EmailAddress attribute part of the PrintableString character set. EmailAddress attribute
values are not case sensitive (e.g., "fanfeedback@redsox.com" is values are not case sensitive (e.g., "fanfeedback@redsox.com" is
the same as "FANFEEDBACK@REDSOX.COM"). the same as "FANFEEDBACK@REDSOX.COM").
Conforming implementations generating new certificates with Conforming implementations generating new certificates with
electronic mail addresses MUST use the rfc822Name in the subject electronic mail addresses MUST use the rfc822Name in the subject
alternative name field (see sec. 4.2.1.7 of [RFC 2459]) to alternative name field (see sec. 4.2.1.7 of [X509CRL]) to
describe such identities. Simultaneous inclusion of the describe such identities. Simultaneous inclusion of the
EmailAddress attribute in the subject distinguished name to EmailAddress attribute in the subject distinguished name to
support legacy implementations is deprecated but permitted. support legacy implementations is deprecated but permitted.
Since no single method of including the UPN in the certificate will Since no single method of including the UPN in the certificate will
work in all cases, CAP implementations MUST support the ability to work in all cases, CAP implementations MUST support the ability to
configure what the mapping will be by the CS administrator. configure what the mapping will be by the CS administrator.
Implementations MAY support multiple mapping definitions, for Implementations MAY support multiple mapping definitions, for
example, the UPN may be found in either the subject alternative name example, the UPN may be found in either the subject alternative name
field, or the UPN may be embedded in the subject distinguished name field, or the UPN may be embedded in the subject distinguished name
as an EmailAddress attribute. as an EmailAddress attribute.
Note: If a CS or CUA is validating data received via iMIP, if the Note: If a CS or CUA is validating data received via [iMIP], if the
"ORGANIZER" or "ATTENDEE" property said (e.g.) "ATTENDEE;CN=Joe "ORGANIZER" or "ATTENDEE" properties 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. This is so the "ATTENDEE" property be checked against the UPN. This is so the "ATTENDEE" property
cannot be changed to something misleading like "ATTENDEE;CN=Joe cannot be changed to something misleading like "ATTENDEE;CN=Joe
Rictus User:MAILTO:jrictus@example.com" and have it pass validation. Rictus User:MAILTO:jrictus@example.com" and have it pass validation.
Note that it is the email addresses that miscompare, the CN Note that it is the email addresses that miscompare, the CN
miscompare is irrelevant. miscompare is irrelevant.
4.1.2 Anonymous Users and Authentication 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
skipping to change at page 26, line 22 skipping to change at page 26, line 22
membership. membership.
CAP does not define commands or methods for managing UGs. CAP does not define commands or methods for managing UGs.
4.2 Access Rights 4.2 Access Rights
Access rights are used to grant or deny access to calendars, Access rights are used to grant or deny access to calendars,
components, properties, and parameters in a CS to a CU. CAP defines components, properties, and parameters in a CS to a CU. CAP defines
a new component type called a Calendar Access Right (VCAR). a new component type called a Calendar Access Right (VCAR).
Specifically, a "VCAR" component grants, or denies, UPNs the right to Specifically, a "VCAR" component grants, or denies, UPNs the right to
read and write components, properties, and parameters on calendars search 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" component model does not put any restriction on the
the object and access rights are created. That is, an object sequence in which the object and access rights are created. That is,
associated with a particular VCAR might be created before or after an object associated with a particular "VCAR" component might be
the actual VCAR is defined. In addition, the VCAR and VEVENT created before or after the actual "VCAR" component is defined. In
definition might be created in the same iCalendar object and passed addition, the "VCAR" and "VEVENT" components might be created in the
together in a single object. same iCalendar object and passed together in a single object.
All rights MUST BE denied unless specifically granted. All rights MUST BE denied unless specifically granted.
If two rights specified in VCAR components are in conflict, the right If two rights specified in "VCAR" components are in conflict, the
that denies access always takes precedence over the right that grants right that denies access always takes precedence over the right that
access. Any attempt to create a VCAR that conflicts with an grants access. Any attempt to create a "VCAR" component that
immutable VCAR must fail. conflicts with an immutable "VCAR" components must fail.
4.2.1 Access Control and NOCONFLICT 4.2.1 Access Control and NOCONFLICT
The TRANSP property can take on values "TRANSPARENT-NOCONFLICT" and The "TRANSP" property can take on values "TRANSPARENT-NOCONFLICT" and
"OPAQUE-NOCONFLICT" that prohibit other components from overlapping "OPAQUE-NOCONFLICT" that prohibit other components from overlapping
it. This setting overrides access. The "ALLOW-CONFLICT" CS, it. This setting overrides access. The "ALLOW-CONFLICT" CS,
Calendar or component setting may also prevent overlap, returning an Calendar or component setting may also prevent overlap, returning an
error code "6.3". error code "6.3".
4.2.2 Calendar Access Right (VCAR) 4.2.2 Calendar Access Right (VCAR)
Access rights within CAP are specified with the "VCAR" component, Access rights within CAP are specified with the "VCAR" component,
"RIGHTS" value type and the "GRANT", "DENY" and "CARID" properties. "RIGHTS" value type and the "GRANT", "DENY" and "CARID" 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 "VCAR" properties. the case for the "VCAR" component properties.
4.2.3 Predefined VCARs 4.2.3 Predefined VCARs
Predefined calendar access CARIDs that MUST BE implemented are: Predefined calendar access CARIDs that MUST BE implemented are:
CARID:READBUSYTIMEINFO - Specifies the "GRANT" and "DENY" rules that CARID:READBUSYTIMEINFO - Specifies the "GRANT" and "DENY" rules that
allow UPNs to read "VFREEBUSY" components. An example definition allow UPNs to search "VFREEBUSY" components. An example
for this VCAR is: definition for this VCAR is:
BEGIN:VCAR BEGIN:VCAR
CARID:READBUSYTIMEINFO CARID:READBUSYTIMEINFO
BEGIN:VRIGHT BEGIN:VRIGHT
GRANT:* GRANT:*
PERMISSION:READ PERMISSION:SEARCH
SCOPE:SELECT * FROM VFREEBUSY SCOPE:SELECT * FROM VFREEBUSY
END:VRIGHT END:VRIGHT
END:VCAR END:VCAR
CARID:REQUESTONLY - Specifies the "GRANT" and "DENY" rules to UPNs CARID:REQUESTONLY - Specifies the "GRANT" and "DENY" rules to UPNs
other than the owner of the calendar the ability to write new other than the owner of the calendar the ability to write new
objects with the property "METHOD" property set to the "REQUEST" objects with the property "METHOD" property set to the "REQUEST"
value. This CARID allows the owner to specify which UPNs are value. This CARID allows the owner to specify which UPNs are
allowed to make scheduling requests. An example definition for allowed to make scheduling requests. An example definition for
this VCAR is: this VCAR is:
BEGIN:VCAR BEGIN:VCAR
CARID:REQUESTONLY CARID:REQUESTONLY
BEGIN:VRIGHT BEGIN:VRIGHT
GRANT:NON OWNER() GRANT:NON CAL-OWNERS()
PERMISSION:CREATE PERMISSION:CREATE
RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST' RESTRICTION:SELECT VEVENT FROM VAGENDA WHERE METHOD = 'REQUEST'
RESTRICTION:SELECT VTODO FROM VAGENDA WHERE METHOD = 'REQUEST'
RESTRICTION:SELECT VJOURNAL FROM VAGENDA WHERE METHOD = 'REQUEST'
END:VRIGHT END:VRIGHT
END:VCAR END:VCAR
CARID:UPDATEPARTSTATUS - Grants to authenticated users the right to CARID:UPDATEPARTSTATUS - Grants to authenticated users the right to
modify the instances of the "ATTENDEE" property set to one of modify the instances of the "ATTENDEE" property set to one of
their calendar addresses in any components for any booked their calendar addresses in any components for any booked
component containing a "ATTENDEE" property. This allows (or component containing a "ATTENDEE" property. This allows (or
denies) a CU the ability to update their own participation status denies) a CU the ability to update their own participation status
in a calendar where they might not otherwise have MODIFY access. in a calendar where they might not otherwise have "MODIFY" command
They are not allowed to change the "ATTENDEE" property value. An access. They are not allowed to change the "ATTENDEE" property
example definition for this VCAR is (This example only effects the value. An example definition for this VCAR is (This example only
"VEVENT" components): effects the "VEVENT" components):
BEGIN:VCAR BEGIN:VCAR
CARID:UPDATEPARTSTATUS CARID:UPDATEPARTSTATUS
BEGIN:VRIGHT BEGIN:VRIGHT
GRANT:* GRANT:*
PERMISSION:MODIFY PERMISSION:MODIFY
SCOPE:SELECT ATTENDEE FROM VEVENT SCOPE:SELECT ATTENDEE FROM VEVENT
WHERE ATTENDEE = SELF() WHERE ATTENDEE = SELF()
AND ORGANIZER = CURRENT-TARGET() AND ORGANIZER = CURRENT-TARGET()
AND STATE() = 'BOOKED' AND STATE() = 'BOOKED'
skipping to change at page 28, line 29 skipping to change at page 28, line 31
WHERE ATTENDEE = SELF() WHERE ATTENDEE = SELF()
END:VRIGHT END:VRIGHT
END:VCAR END:VCAR
CARID:DEFAULTOWNER - Grants to any owner the permission they have CARID:DEFAULTOWNER - Grants to any owner the permission they have
for the target. An example definition for this VCAR is: for the target. An example definition for this VCAR is:
BEGIN:VCAR BEGIN:VCAR
CARID:DEFAULTOWNER CARID:DEFAULTOWNER
BEGIN:VRIGHT BEGIN:VRIGHT
GRANT:OWNER() GRANT:CAL-OWNERS()
PERMISSION:* PERMISSION:*
SCOPE:SELECT * FROM VAGENDA SCOPE:SELECT * FROM VAGENDA
END:VRIGHT END:VRIGHT
END:VCAR END:VCAR
4.2.4 Decreed VCARs 4.2.4 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 may be configured by the CS administrator. A reply from the CS that may be configured by the CS administrator. A reply from the CS
may dynamically create VCARs that are decreed depending on the may dynamically create "VCAR" components that are decreed depending
implementation. To the CUA any "VCAR" component with the "DECREED" on the implementation. To the CUA any "VCAR" component with the
property set to "TRUE" can not be changed by the currently "DECREED" property set to "TRUE" can not be changed by the currently
authenticated UPN, and depending on the implementation and other authenticated UPN, and depending on the implementation and other
VCARs; might not be able to be changed by any UPN using CAP, and "VCAR" components; might not be able to be changed by any UPN using
never when the CUA gets a "DECREED:TRUE" VCAR. CAP, and never when the CUA gets a "DECREED:TRUE" VCAR.
When a user attempts to modify or override a decreed VCAR an error When a user attempts to modify or override a decreed "VCAR" component
will be returned indicating that the user has insufficient rules an error will be returned indicating that the user has
authorization to perform the operation. The reply to the CUA MUST BE insufficient authorization to perform the operation. The reply to
the same as if a non-decreed VCAR caused the failure. 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. access to their own calendars.
Decreed VCARs MUST BE readable by the calendar owner in standard VCAR Decreed "VCAR" components MUST BE readable by the calendar owner in
format. standard "VCAR" component format.
4.3 CAP Session Identity 4.3 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 Server only permits the operation "IDENTIFY" command. The Calendar Server only permits the operation
if the session's authentication credentials are good for the if the session's authentication credentials are good for the
skipping to change at page 31, line 21 skipping to change at page 31, line 21
2396, and follows the Guidelines for URL Schemes, set forth in RFC 2396, and follows the Guidelines for URL Schemes, set forth in RFC
2718. 2718.
A CAP URL begins with the protocol prefix "cap" and is defined by the A CAP URL begins with the protocol prefix "cap" and is defined by the
following grammar. following grammar.
capurl = "cap://" csid [ "/" relcalid ] capurl = "cap://" csid [ "/" relcalid ]
csid = hostport ; As defined in Section 3.2.2 of RFC 2396 csid = hostport ; As defined in Section 3.2.2 of RFC 2396
relcalid = *uric ; As defined in Section 2 of RFC 2396 relcalid = *uric ; As defined in Section 2 of RFC 2396
'relcalid' is an identifier that uniquely identifies a calendar on a A 'relcalid' is an identifier that uniquely identifies a calendar on
particular calendar store. There is no implied structure in a 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 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 resource such as a conference room. It MUST BE unique within the
calendar store. calendar store.
Examples: Examples:
cap://cal.example.com cap://cal.example.com
cap://cal.example.com/Company/Holidays cap://cal.example.com/Company/Holidays
cap://cal.example.com/abcd1234Usr cap://cal.example.com/abcd1234Usr
skipping to change at page 33, line 5 skipping to change at page 33, line 5
A Calendar addresses can be described as qualified or relative CAP A Calendar addresses can be described as qualified or relative CAP
URLs. URLs.
For a user currently authenticated to the CS on cal.example.com, For a user currently authenticated to the CS on cal.example.com,
these two example calendar addresses refer to the same calendar: these two example calendar addresses refer to the same calendar:
cap://cal.example.com/abcd1234USR cap://cal.example.com/abcd1234USR
abcd1234USR abcd1234USR
6. New Components, Properties, Parameters, and Values 6. New Value Types
The following sections contains new components, properties, The following sections contains new components, properties,
parameters, and value definitions. parameters, and value definitions.
The purpose of these is to extend the iCalendar objects in a The purpose of these is to extend the iCalendar objects in a
compatible way so that existing iCalendar VERSION 2.0 parsers can compatible way so that existing iCalendar "VERSION" property "2.0"
still parse the objects without modification. value parsers can still parse the objects without modification.
6.1 Property Value Data Types 6.1 Property Value Data Types
6.1.1 CAL-QUERY Value Type 6.1.1 CAL-QUERY Value Type
Subject: Registration of text/calendar MIME value type CAL-QUERY Subject: Registration of text/calendar MIME value type CAL-QUERY
Value Name: CAL-QUERY Value Name: CAL-QUERY
Value Type Purpose: This value type is used to identify values and Value Type Purpose: This value type is used to identify values and
skipping to change at page 33, line 36 skipping to change at page 33, line 36
1. For the purpose of a query, all components should be handled as 1. For the purpose of a query, all components should be handled as
tables, and the properties of those components, should be handled tables, and the properties of those components, should be handled
as columns. as columns.
2. All VAGENDAs and CS's look like tables for the purpose of a 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 QUERY. And all of their properties look like columns in those
tables. tables.
3. You CAN NOT do any cross component-type joins. And that means 3. You CAN NOT do any cross component-type joins. And that means
you can ONLY have one component, OR one VAGENDA OR one VCALSTORE you can ONLY have one component, OR one "VAGENDA" component OR
in the the FROM clause. one "VCALSTORE" component in the "FROM" clause.
4. Everything in the SELECT and WHERE clauses MUST BE from the same 4. Everything in the "SELECT" clause and "WHERE" clauses in MUST BE
component type, or VAGENDA OR VCALSTORE in the FROM clause. from the same component type, or "VAGENDA" component OR
"VCALSTORE" component in the "FROM" clause.
5. When multiple QUERY properties are supplied in a single VQUERY 5. When multiple "QUERY" properties are supplied in a single
component, the results returned are the same as the results "VQUERY" component, the results returned are the same as the
returned for multiple VQUERY components having each a single results returned for multiple "VQUERY" components having each a
QUERY property and the results are return in the same order as single "QUERY" property and the results are return in the same
the VQUERYs were specified in the original command. order as the "VQUERY" properties were specified in the original
command.
6. The '.' is used to separate the table name (component) and column 6. The '.' is used to separate the table name (component) and column
name (property or component) when selecting a property that is name (property or component) when selecting a property that is
contained inside of a component that is targeted in the TARGET contained inside of a component that is targeted in the TARGET
property. property.
7. A contained component without a '.' is not the same as 7. A contained component without a '.' is not the same as
"component-name.*". If given as "component-name" (no dot) the "component-name.*". If given as "component-name" (no dot) the
the encapsulating BEGIN/END statement will be supplied for encapsulating BEGIN/END statement will be supplied for
"component-name".: "component-name".:
In this example the '.' is used to separate the TRIGGER property from In this example the '.' is used to separate the "TRIGGER" property
its contained component (VALARM) which is contained in any VEVENT in from its contained component (VALARM). Which is contained in any
the selected TARGET (relcalid). All TRIGGER values in any VEVENT in "VEVENT" component in the selected "TARGET" property value (a
relcalid). All "TRIGGER" properties in any "VEVENT" component in
relcalid would be returned. relcalid would be returned.
TARGET:relcalid TARGET:relcalid
QUERY:SELECT VALARM.TRIGGER FROM VEVENT QUERY:SELECT VALARM.TRIGGER FROM VEVENT
SELECT VALARM FROM VEVENT WHERE UID = "123" SELECT VALARM FROM VEVENT WHERE UID = "123"
This return one BEGIN/END VALARM for each VALARM in the VEVENT This return one BEGIN/END "VALARM" component for each
as there is no '.' (dot) in the VALARM: "VALARM" component in the matching "VEVENT" component.
As there is no '.' (dot) in the VALARM after the SELECT above:
BEGIN:VALARM BEGIN:VALARM
TRIGGER;RELATED=END:PT5M TRIGGER;RELATED=END:PT5M
REPEAT:4 REPEAT:4
... ...
END:VALARM END:VALARM
BEGIN:VALARM BEGIN:VALARM
TRIGGER;RELATED=START:PT5M TRIGGER;RELATED=START:PT5M
DURATION:PT10M DURATION:PT10M
... ...
END:VALARM END:VALARM
... ...
... ...
If provided as "component-name.*", then only the properties and any If provided as "component-name.*", then only the properties and any
contained components will be returned: contained components will be returned:
SELECT VALARM.* FROM VEVENT WHERE UID = "123" SELECT VALARM.* FROM VEVENT WHERE UID = "123"
Will return the properties in each VALARM in the VEVENT: Will return all of the properties in each "VALARM" component
in the matching "VEVENT" component:
TRIGGER;RELATED=END:PT5M TRIGGER;RELATED=END:PT5M
REPEAT:4 REPEAT:4
... ...
TRIGGER;RELATED=START:PT5M TRIGGER;RELATED=START:PT5M
DURATION:PT10M DURATION:PT10M
... ...
... ...
(a) SELECT VEVENT.<a-property-name> FROM VEVENT (a) SELECT <a-property-name> FROM VEVENT
(b) SELECT VALARM FROM VEVENT (b) SELECT VALARM FROM VEVENT
(c) SELECT VALARM.* FROM VEVENT (c) SELECT VALARM.* FROM VEVENT
(d) SELECT * FROM VEVENT (d) SELECT * FROM VEVENT
(e) SELECT * FROM VEVENT WHERE (e) SELECT * FROM VEVENT WHERE
VALARM.TRIGGER < '20020201T000000Z' VALARM.TRIGGER < '20020201T000000Z'
AND VALARM.TRIGGER > '20020101T000000Z' AND VALARM.TRIGGER > '20020101T000000Z'
Note: (a) Selects all instances of <a-property-name> Note:
from all VEVENT components. (a) Selects all instances of <a-property-name>
from all "VEVENT" components.
(b) and (c) Select all VALARM components from all (b) and (c) Select all "VALARM" components from all
VEVENT components. (b) would return then in "VEVENT" components. (b) would return then in
BEGIN/END VALARM tags. (c) would return all BEGIN/END VALARM tags. (c) would return all
of the properties without BEGIN/END VALARM tags. of the properties without BEGIN/END VALARM tags.
(d) Selects every property and every component (d) Selects every property and every component
that is in any VEVENT component. that is in any "VEVENT" component.
(e) Selects all properties and all contained (e) Selects all properties and all contained
components in all VEVENT components that have a VALARM components in all "VEVENT" components that have a "VALARM"
with a TRIGGER property value between the provided component with a "TRIGGER" property value between
dates and times. the provided dates and times.
NOT VALID: NOT VALID:
(f) SELECT VEVENET.VALARM.TRIGGER FROM VEVENT (f) SELECT VEVENT.VALARM.TRIGGER FROM VEVENT
(g) SELECT DTSTART,UID FROM VEVENT WHERE (g) SELECT DTSTART,UID FROM VEVENT WHERE
VTODO.SUMMERY = "Fix typo in CAP" VTODO.SUMMERY = "Fix typo in CAP"
Note: (f) Is NOT valid because it contains Note: (f) Is NOT valid because it contains
two '.' characters in the SELECT clause. two '.' characters in the "SELECT" clause.
(g) Is NOT valid because it mixes VEVENT (g) Is NOT valid because it mixes VEVENT
and VTODO properties in the same VQUERY. and VTODO properties in the same VQUERY.
Formal Definition: The value type is defined by the following Formal Definition: The value type is defined by the following
notation: notation:
comp-name = "VEVENT" / "VTODO" / "VJOURNAL" cal-query = "SELECT" SP cap-val SP
/ "VTIMEZONE" / "VALARM" / "VFREEBUSY"
/ "VAGENDA" / "VCAR" / "VCALSTORE"
/ "VQUERY" / iana-name / x-comp
querycomp = queries
; These next three property types
; may be in any order.
;
/ ( queryid *(name) queries)
; Only when using an existing stored query
; can query or queries be omitted.
;
/ queryid
queries = query
/ queries query
; NOTE: There is exactly one space separating
; the various parts of cal-query
;
cal-query = "SELECT" SP cap-cols SP
"FROM" SP comp-name SP "FROM" SP comp-name SP
*(cauprops SP / capcprops SP)
"WHERE" SP cap-expr "WHERE" SP cap-expr
/ "SELECT" SP cap-cols SP / "SELECT" SP cap-cols SP
"FROM" SP comp-name "FROM" SP comp-name
uprop-list = (cap-col SP cap-local) cap-val = cap-cols / param
/ uprop-list SP cap-col SP cap-local / ( cap-val "," cap-val )
cprop-list = (cap-comp cap-local)
/ cprop-list SP cap-col SP cap-local
cap-col = ; Any property name found in the component ; NOTE: there is NO space around the "," on
; named in the comp-tbl used in the FROM clause. ; the next line
cap-cols = cap-col / ( cap-cols "," cap-col)
/ "*"
; A 'cap-col' is:
;
; Any property name ('cap-prop') found in the component
; named in the 'comp-name' used in the "FROM" clause.
; ;
; SELECT ORGANIZER FROM VEVENT ... ; SELECT ORGANIZER FROM VEVENT ...
; ;
; OR ; OR
; ;
; A component name of an existing component contained ; A component name ('comp-name') of an existing component
; inside of the cmp-tbl used in the FROM clause. ; contained inside of the 'comp-name' used in the "FROM"
; clause.
; ;
; SELECT VALARM FROM VEVENT ... ; SELECT VALARM FROM VEVENT ...
;
; OR
;
; A component name ('comp-name') of an existing
; component contained inside of the 'comp-name' used
; in the "FROM" clause folowed by a property
; name ('cap-prop') to be selected from that component.
; (comp-name "." cap-prop)
;
; SELECT VALARM.TRIGGER FROM VEVENT ...
cap-col = comp-name
/ comp-name "." cap-prop
comp-name = "VEVENT" / "VTODO" / "VJOURNAL" / "VFREEBUSY"
/ "VALARM" / "DAYLIGHT" / "STANDARD" / "VAGENDA"
/ "VCAR" / "VCALSTORE" / "VQUERY" / "VTIMEZONE"
/ x-comp / iana-comp
cap-prop = ; A property that may be in the 'cap-comp' named
; in the "SELECT" clause.
cap-expr = "(" cap-expr ")"
/ cap-term
cap-term = cap-expr SP cap-logical SP cap-expr
/ cap-factor
cap-logical= "AND" / "OR"
cap-factor = cap-colval SP cap-oper SP col-value
/ cap-colval SP "NOT LIKE" SP col-value
/ cap-colval SP "LIKE" SP col-value
/ cap-colval SP "IS NULL"
/ cap-colval SP "IS NOT NULL"
/ col-value SP "NOT IN" cap-colval"
/ col-value SP "IN" cap-colval"
/ "STATE()" "=" ( "BOOKED"
/ "UNPROCESSED"
/ "DELETED" )
cap-colval = cap-col / param
param = "PARAM(" cap-col "," cap-param ")"
; 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 cap-param = ; Any parameter that may be contained in the cap-col
; in the supplied PARAM() function ; in the supplied PARAM() function
cap-local = ; Any string that is composed of the characters
; 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.
col-value = col-literal col-value = col-literal
/ "STATE()"
/ "SELF()" / "SELF()"
/ "CAL-OWNERS()" / "CAL-OWNERS()"
/ "CAL-OWNERS(" cal-address ")" / "CAL-OWNERS(" cal-address ")"
/ "CURRENT-TARGET()" / "CURRENT-TARGET()"
cal-address = ; A CALID as define by CAP cal-address = ; A CALID as define by CAP
col-literal = "'" literal-data "'" col-literal = "'" literal-data "'"
literal-data = ; Any data that matches the value type of the literal-data = ; Any data that matches the value type of the
skipping to change at page 38, line 22 skipping to change at page 38, line 29
; OR ; OR
; ;
; If the literal-data is preceded by the LIKE ; If the literal-data is preceded by the LIKE
; element it may also contain the '%' and '_' ; element it may also contain the '%' and '_'
; wildcard characters. And if the literal data ; wildcard characters. And if the literal data
; that is comparing contains any '%' or '_' ; that is comparing contains any '%' or '_'
; characters, they MUST BE backslash escaped as ; characters, they MUST BE backslash escaped as
; described in the notes below in order for them not ; described in the notes below in order for them not
; to be treated as wildcard characters. ; to be treated as wildcard characters.
cap-ucol = cap-col / cap-local
cap-expr = "(" cap-expr ")"
/ cap-term
cap-term = cap-expr SP cap-logical SP cap-expr
/ cap-factor
cap-factor = cap-colval SP cap-oper SP col-value
/ cap-colval SP "NOT LIKE" SP col-value
/ cap-colval SP "LIKE" SP col-value
/ cap-colval SP "IS NULL"
/ cap-colval SP "IS NOT NULL"
/ col-value SP "NOT IN" cap-colval"
/ col-value SP "IN" cap-colval"
cap-colval = cap-ucolq
/ "PARAM(" cap-ucol "," cap-param ")"
cap-oper = "=" cap-oper = "="
/ "!=" / "!="
/ "<" / "<"
/ ">" / ">"
/ "<=" / "<="
/ ">=" / ">="
cap-logical = "AND" / "OR"
SP = ; A single white space ascii character SP = ; A single white space ascii character
; (value in HEX %x20). ; (value in HEX %x20).
CRLF = ; As defined in RFC 2445. x-comp = ; As defined in RFC 2445 section 4.6
xparam = ; As defined in RFC 2445.
x-prop = ; As defined in RFC 2445.
x-comp = ; As defined in RFC 2445. iana-comp = ; As defined in RFC 2445 section 4.6
6.1.1.1 CAL-OWNERS() 6.1.1.1 [NOT] CAL-OWNERS()
This function returns the list of "OWNERS" for the named calendar. This function returns the list of "OWNER" properties for the named
calendar when used in the "SELECT" clause.
If called as 'CAL-OWNERS()', it is equivalent to the comma separated If called as 'CAL-OWNERS()', it is equivalent to the comma separated
list of all of the owners of the current "TARGET" calendar. If the list of all of the owners of the calendar that match the provided
target is a "VAGENDA", it returns the "CALMASTER" value. "TARGET" property value. If the target is a "VCALSTORE", it returns
the "CALMASTER" property.
If called as 'CAL-OWNERS(cal-address)', then it is the equivalent to If called as 'CAL-OWNERS(cal-address)', then it is the equivalent to
the comma separated list of owners for the named calendar id. the comma separated list of owners for the named calendar id. If
'cal-address' is a CS, it returns the "CALMASTER" property.
If used in the in the "WHERE" clause it then returns true if the
currently authenticated UPN is an owner of the currently selected
object matched in the provided "TARGET" property. Used in a CAL-
QUERY "WHERE" clause and in the UPN-FILTER.
6.1.1.2 CURRENT-TARGET() 6.1.1.2 CURRENT-TARGET()
Is equivalent to the value of the "TARGET" property in the current Is equivalent to the value of the "TARGET" property in the current
command. Used in a CAL-QUERY 'WHERE' clause. command. Used in a CAL-QUERY "WHERE" clause.
6.1.1.3 [NOT] OWNER() 6.1.1.3 PARAM()
Returns true if the current UPN is an owner of the current "TARGET". Used in a CAL-QUERY. Returns the value of the named parameter from
Used in a CAL-QUERY 'WHERE' clause and in the UPN-FILTER. the named property. If there are multiple properties in the object,
then PARAM() returns a comma separated list of parameter values. If
needed each value can be quoted or contain backslash escaped
contents.
When used in a "SELECT" clause, it returns the entire property and
all of that propertiies parameters (the result is not limited to the
supplied parameter). If the property does not contain the named
parameter, then the property is not returned (It could however be
returned as a result of another "SELECT" clause value.) If multiple
properties of the supplied name have the named parameter, all
properties with that named parameter are returned.
When used in the "WHERE" clause, a match is true when the parameter
value is "IN" or "LIKE" compare clause according to the supplied
WHERE values. If multiple named properties contain the named
parameter, then each parameter value is compared to the condition and
if any match, then the results would be true for that condition the
same as if only one had existed.
6.1.1.4 SELF() 6.1.1.4 SELF()
Used in a CAL-QUERY 'WHERE' clause. Returns the UPN of the currently Used in a CAL-QUERY "WHERE" clause. Returns the UPN of the currently
authenticated CU. authenticated UPN.
6.1.1.5 STATE() 6.1.1.5 STATE()
Returns one of three values, 'BOOKED', 'UNPROCESSED', or 'DELETED' Returns one of three values, 'BOOKED', 'UNPROCESSED', or 'DELETED'
depending on the state of the object. Used in a CAL-QUERY 'WHERE' depending on the state of the object. Used in a CAL-QUERY "WHERE"
clause. clause.
6.1.1.6 Ordering of Results 6.1.1.6 Ordering of Results
Sorting will take place in the order the columns are supplied in the Sorting will take place in the order the columns are supplied in the
QUERY command. The CS MUST sort at least the first column. The CS QUERY command. The CS MUST sort at least the first column. The CS
MAY sort additional columns. MAY sort additional columns.
Float and integer values MUST BE sorted by their numeric value. This 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: means the result of a sort on an integer value type will be:
skipping to change at page 40, line 39 skipping to change at page 41, line 6
All other values are sorted according to the locale sorting order as All other values are sorted according to the locale sorting order as
specified in the command. Or the calendar locale if known, or the CS specified in the command. Or the calendar locale if known, or the CS
locale if the calendar does not have any locale set. And the locale locale if the calendar does not have any locale set. And the locale
to use for the sort is determined in that order. to use for the sort is determined in that order.
6.1.1.7 Date sorting order 6.1.1.7 Date sorting order
If the cap-cols is only "*" and nothing else and the result set has a If the cap-cols is only "*" and nothing else and the result set has a
DTSTART, then: DTSTART, then:
If EXPAND=FALSE sorting will be by the DTSTART value ascending as if If EXPAND=FALSE sorting will be by the "DTSTART" property value
it were in UTC. ascending as if it were in UTC.
If EXPAND=TRUE sorting will be by the RECURRENCE-ID value ascending If EXPAND=TRUE sorting will be by the "RECURRENCE-ID" property value
as if it were in UTC. ascending as if it were in UTC.
If one or more DTSTART or RECURRENCE-ID components have exactly the If one or more "DTSTART" or "RECURRENCE-ID" property values in
same value, the order for those matching components is unspecified. multiple 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 If the selected component(s) do not contain a "DTSTART" property or a
RECURRENCE-ID, then the order is unspecified. "RECURRENCE-ID" property, then the order is unspecified.
If an instance does not have a RECURRENCE-ID and the query compares If an instance does not have a "RECURRENCE-ID" property and the query
RECURRENCE-IDs (comparing a RECURRENCE-ID to the date or date/time of compares "RECURRENCE-ID" properties (comparing a RECURRENCE-ID to the
a single instance object), then the CS MUST compare the DTSTART value date or date/time of a single instance object), then the CS MUST
as if it were a RECURRENCE-ID even for single instance objects that compare the "DTSTART" property value as if it were a "RECURRENCE-ID"
do not contain a RECURRENCE-ID. even for single instance objects that do not contain a "RECURRENCE-
ID" property.
A component with a DATE and no TIME value is returned before objects A component with a DATE and no TIME value is returned before objects
with both a DATE and TIME value when the dates of those two (or more) with both a DATE and TIME value when the dates of those two (or more)
objects are the same, sorted by date. objects are the same, sorted by date.
6.1.1.8 Use of single quote 6.1.1.8 Use of single quote
All literal values are surrounded by single quotes ('), not double All literal values are surrounded by single quotes ('), not double
quotes ("), and not without any quotes. If the value contains quotes quotes ("), and not without any quotes. If the value contains quotes
or any other ESCAPED-CHAR, they MUST BE backslash escaped as or any other ESCAPED-CHAR, they MUST BE backslash escaped as
described in section "4.3.11 Text" of RFC2445. Any LIKE wildcard described in section "4.3.11 Text" of RFC2445. Any "LIKE" clause
characters that are part of any literal data that is preceded by a wildcard characters that are part of any literal data that is
LIKE clause and is not intended to mean wildcard search, MUST BE preceded by a "LIKE" clause and is not intended to mean wildcard
escaped as described in note (7) below. search, MUST BE escaped as described in note (7) below.
6.1.1.9 Comparing DATE and DATE-TIME values 6.1.1.9 Comparing DATE and DATE-TIME values
When comparing DATE-TIME to DATE value types and when comparing DATE When comparing "DATE-TIME" values to "DATE" values and when comparing
to DATE-TIME value types, the result will be true if the DATE value "DATE" values to "DATE-TIME" values, the result will be true if the
is on the same day as the DATE-TIME value. And they are compared in "DATE" value is on the same day as the "DATE-TIME" value. And they
UTC no matter what time zone the data may actual have been stored in. are compared in UTC no matter what time zone the data may actual have
been stored in.
VALUE-1 VALUE-2 Compare Results VALUE-1 VALUE-2 Compare Results
20020304 20020304T123456 TRUE 20020304 20020304T123456 TRUE
(in UTC-3) (in UTC-3) (in UTC-3) (in UTC-3)
20020304 20020304T003456 FALSE 20020304 20020304T003456 FALSE
(in UTC) (in UTC-4) (in UTC) (in UTC-4)
20020304T003456Z 20020205T003456 FALSE 20020304T003456Z 20020205T003456 FALSE
(in UTC-0) (in UTC-7) (in UTC-0) (in UTC-7)
When the DATE or DATE-TIME value is not associated with a time zone, When the "DATE" value or "DATE-TIME" value is not associated with a
then the CS will compare the value assuming that the no time zone time zone, then the CS will compare the value assuming that the no
values are in the calendars default time zone. time zone values are in the calendars default time zone.
When comparing DATE and DATE-TIME values with the LIKE clause the When comparing "DATE" values and "DATE-TIME" values with the "LIKE"
comparison will be done as if the value is a RFC2445 DATE or DATE- clause the comparison will be done as if the value is a RFC2445 DATE
TIME string value. or DATE-TIME string value.
LIKE '2002%' will match anything in the year 2002. LIKE '2002%' will match anything in the year 2002.
LIKE '200201%' will match anything in January 2002. LIKE '200201%' will match anything in January 2002.
LIKE '%T000000' will match anything at midnight. LIKE '%T000000' will match anything at midnight.
LIKE '____01__T%' will match anything for any year or LIKE '____01__T%' will match anything for any year or
time that is in January. time that is in January.
(Four '_', '01', two '_' 'T%'). (Four '_', '01', two '_' 'T%').
Using a LIKE value of "%00%, would return any value that contained Using a "LIKE" clause value of "%00%, would return any value that
two consecutive zeros. contained two consecutive zeros.
Again all comparisons will be done in UTC. All comparisons will be done in UTC.
6.1.1.10 DTEND and DURATION 6.1.1.10 DTEND and DURATION
When a QUERY contains a DTEND value, then the CS MUST also evaluate When a "QUERY" property value contains a "DTEND" value, then the CS
any existing DURATION property value and determine if it has an MUST also evaluate any existing "DURATION" property value and
effective end time that matches the QUERY supplied DTEND value or any determine if it has an effective end time that matches the "QUERY"
range of values supplied by the QUERY. property supplied "DTEND" value or any range of values supplied by
the "QUERY" property.
When a QUERY contains a DURATION value, then the CS MUST also When a "QUERY" property contains a "DURATION" value, then the CS MUST
evaluate any existing DTEND property value and determine if it has an also evaluate any existing "DTEND" property values and determine if
effective duration that matches the QUERY supplied DURATION value or they have an effective duration that matches the "QUERY" property
any range of values supplied by the QUERY. value supplied "DURATION" value or any range of values supplied by
the "QUERY" property.
As DTEND is the first time that is excluded from a components time As "DTEND" value is the first time that is excluded from a components
range, any DURATION supplied by the QUERY that is exactly one second time range, any "DURATION" value supplied by the "QUERY" poperty
less than DTEND MUST match the QUERY. And if the DURATION ends value that is exactly one second less than the "DTEND" property value
MUST match the QUERY. And if the "DURATION" property value ends
exactly at the computed DTEND it MUST NOT match. exactly at the computed DTEND it MUST NOT match.
Any DTEND supplied by the QUERY that is exactly one second more than Any "DTEND" value supplied by the "QUERY" property that is exactly
an end time computed from a DURATION MUST match the QUERY. Any end one second more than an end time computed from a DURATION MUST match
time that is computed from a DURATION that exactly matches the the QUERY. Any end time that is computed from a DURATION that
supplied DTEND MUST NOT match. exactly matches the supplied DTEND MUST NOT match.
Given a meeting room reserved with a component that contains (date- Given a meeting room reserved with a component that contains (date-
time-example-1): time-example-1):
DTSTART:20020127T000000Z DTSTART:20020127T000000Z
DTEND:20020127T010000Z DTEND:20020127T010000Z
The reservation is really from: The reservation is really from:
January 27th, 2002 00:00:00 January 27th, 2002 00:00:00
skipping to change at page 44, line 11 skipping to change at page 44, line 23
AND DURATION = 'P59M59S' AND DURATION = 'P59M59S'
MUST match both (date-time-example-1) and (date-time-example-2) MUST match both (date-time-example-1) and (date-time-example-2)
6.1.1.11 [NOT] LIKE 6.1.1.11 [NOT] LIKE
The pattern matching characters are the '%' that matches zero or more The pattern matching characters are the '%' that matches zero or more
characters, and '_' that matches exactly one character (where characters, and '_' that matches exactly one character (where
character does not always mean octet). character does not always mean octet).
LIKE pattern matches always cover the entire string. To match a "LIKE" clause pattern matches always cover the entire string. To
pattern anywhere within a string, the pattern must start and end with match a pattern anywhere within a string, the pattern must start and
a percent sign. end with a percent sign.
To match a '%' or '_' in the data and not have it interpreted as a To match a '%' or '_' in the data and not have it interpreted as a
wildcard character, they MUST BE backslash escaped. That is to wildcard character, they MUST BE backslash escaped. That is to
search for a '%' or '_' in the string: search for a '%' or '_' in the string:
LIKE '%\%%' Matches any string with a '%' in it. LIKE '%\%%' Matches any string with a '%' in it.
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 Strings compared using the "LIKE" clause MUST BE performed using case
in-sensitive comparisons when the locale allows. (Example: in US- in-sensitive comparisons when the locale allows. (Example: in US-
ASCII the compare assumes 'a' = 'A'). ASCII the compare assumes 'a' = 'A').
If LIKE is preceded by 'NOT' then there is a match when the string If the "LIKE" clause is preceded by 'NOT' then there is a match when
compare fails. the string compare fails.
Some property values (such as the 'recur' value type), contain commas Some property values (such as the 'recur' value type), contain commas
and are not multi valued. The CS must understand the objects being and are not multi valued. The CS must understand the objects being
compared and understand how to determine how any multi valued or compared and understand how to determine how any multi valued or
multi instances properties or parameter values are separated, quoted, multi instances properties or parameter values are separated, quoted,
and backslash escaped and perform the comparisons as if each value and backslash escaped and perform the comparisons as if each value
existed by itself and not quoted or backslash escaped when comparing existed by itself and not quoted or backslash escaped when comparing
using the IN element. using the IN element.
And see the examples in the next section (IN). See related examples in Section 6.1.1.13
6.1.1.12 Empty vs. NULL 6.1.1.12 Empty vs. NULL
When used in a CAL-QUERY value, "NULL" means that the property or When used in a CAL-QUERY value, "NULL" means that the property or
parameter is not present in the object. parameter is not present in the object.
If the property (or parameter) exists, but has no value then "NULL" If the property (or parameter) exists, but has no value then "NULL"
MUST NOT match. MUST NOT match.
If the property (or parameter) exists, but has no value then it If the property (or parameter) exists, but has no value then it
matches the empty string '' (quote quote). matches the empty string '' (quote quote).
6.1.1.13 [NOT] IN 6.1.1.13 [NOT] IN
This is similar to the LIKE element, except it does value matching This is similar to the "LIKE" clause, except it does value matching
and not string comparison matches. and not string comparison matches.
Some iCalendar objects can be multi instance and multi valued. The Some iCalendar objects can be multi instance and multi valued. The
IN operator will return a match if the literal value supplied as part "IN" clause 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 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 named property or parameter, or is in any of the multiple values in
the named property or parameter. Unlike the 'LIKE' clause, the '%' the named property or parameter. Unlike the "LIKE" clause, the '%'
and '_' matching characters are not used with the 'IN' clause and and '_' matching characters are not used with the "IN" clause and
have no special meaning. have no special meaning.
BEGIN:A-COMPONENT BEGIN:A-COMPONENT
a property:value1,value2 One property, two values. a property:value1,value2 One property, two values.
b property:"value1,value2" One property, one value. b property:"value1,value2" One property, one value.
c FOO:parameter=1,2:x One parameter, two values. c property:parameter=1,2:x One parameter, two values.
d FOO:parameter="1,2",3:y One parameter, one value. d property:parameter="1,2",3:y One parameter, one value.
e FOO:parameter=",":z One parameter, one value. e property:parameter=",":z One parameter, one value.
f property:x,y,z One property, three values f property:x,y,z One property, three values
END:A-COMPONENT END:A-COMPONENT
'value1' IN property would match (a) only. 'value1' IN property would match (a) only.
'value1,value2' IN property would match (b) only. 'value1,value2' IN property would match (b) only.
'value%' IN property would NOT match any. 'value%' IN property would NOT match any.
',' IN property would NOT match any. ',' IN property would NOT match any.
'%,%' IN property would NOT match any. '%,%' IN property would NOT match any.
'x' IN property would match (f) and (c). 'x' IN property would match (f) and (c).
'2' IN parameter would match (c) only. '2' IN parameter would match (c) only.
'1,2' IN parameter would match (d) only. '1,2' IN parameter would match (d) only.
',' IN parameter would match (e) only. ',' IN parameter would match (e) only.
'%,%' IN parameter would NOT match any. '%,%' IN parameter would NOT match any.
property LIKE 'value1%' would match (a) and (b) property LIKE 'value1%' would match (a) and (b).
property LIKE 'value%' would match (a) and (b) property LIKE 'value%' would match (a) and (b).
property LIKE 'x' would match (f) and (c). property LIKE 'x' would match (f) and (c).
parameter LIKE '1%' would match (c) and (d) parameter LIKE '1%' would match (c) and (d).
parameter LIKE '%2%' would match (c) and (d) parameter LIKE '%2%' would match (c) and (d).
parameter LIKE ',' would match (e) only. parameter LIKE ',' would match (e) only.
Some property values (such as the 'recur' value type), contain commas Some property values (such as the "RECUR" value type), contain commas
and are not multi valued. The CS must understand the objects being and are not multi valued. The CS must understand the objects being
compared and understand how to determine how any multi valued or compared and understand how to determine how any multi valued or
multi instances properties or parameter values are separated, quoted, multi instances properties or parameter values are separated, quoted,
and backslash escaped and perform the comparisons as if each value and backslash escaped and perform the comparisons as if each value
existed by itself and not quoted or backslash escaped when comparing existed by itself and not quoted or backslash escaped when comparing
using the IN element. using the IN element.
If IN is preceded by 'NOT' then there is a match when the value does If the "IN" clause is preceded by 'NOT' then there is a match when
not exist in the property or parameter value. the value does not exist in the property or parameter value.
6.1.1.14 DATE-TIME and TIME values in a WHEN clause 6.1.1.14 DATE-TIME and TIME values in a WHEN clause
All DATE-TIME and TIME literal values supplied in a WHEN clause MUST All "DATE-TIME" and "TIME" literal values supplied in a "WHEN" clause
BE terminated with 'Z'. That means that the CUA MUST supply the MUST BE terminated with 'Z'. That means that the CUA MUST supply the
values in UTC. values in UTC.
Valid: Valid:
WHERE alarm.TRIGGER < '20020201T000000Z' WHERE alarm.TRIGGER < '20020201T000000Z'
AND alarm.TRIGGER > '20020101T000000Z' AND alarm.TRIGGER > '20020101T000000Z'
Not valid and it is a syntax error and the CS MUST reject the QUERY. Not valid and it is a syntax error and the CS MUST reject the QUERY.
WHERE alarm.TRIGGER < '20020201T000000' WHERE alarm.TRIGGER < '20020201T000000'
AND alarm.TRIGGER > '20020101T000000' AND alarm.TRIGGER > '20020101T000000'
6.1.1.15 Multiple contained components 6.1.1.15 Multiple contained components
All comparisons MUST BE done from the same instance of a contained All comparisons MUST BE done from the same instance of a contained
component or property and repeated for each instance. As in the component or property and repeated for each instance. As in the
following example that uses a VALARM component contained in a VEVENT. following example that uses a "VALARM" component contained in a
If any instance of VALARM in VEVENT matches the query and the rest of "VEVENT" component . If any instance of a "VALARM" component in any
the query is satisfied, then the UID, SUMMARY, and DESCRIPTION from "VEVENT" component matches the query and the rest of the query is
the VEVENT will be returned. If there were two VALARMs in a VEVENT, satisfied, then the "UID", "SUMMARY", and "DESCRIPTION" properties
then both VALARMs are tested and in this example only when the VEVENT from all "VEVENT" components will be returned. If there were two
state is booked: "VALARM" components in a "VEVENT" component, then both "VALARM"
components are tested and in this example only when the "VEVENT"
component state is booked:
BEGIN:VQUERY BEGIN:VQUERY
EXPAND:TRUE EXPAND:TRUE
QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT
WHERE VALARM.TRIGGER >= '20000101T030405Z' WHERE VALARM.TRIGGER >= '20000101T030405Z'
AND VALARM.TRIGGER <= '20001231T235959Z' AND VALARM.TRIGGER <= '20001231T235959Z'
AND STATE() = 'BOOKED' AND STATE() = 'BOOKED'
END:VQUERY END:VQUERY
6.1.1.16 Example, Query by UID 6.1.1.16 Example, Query by UID
skipping to change at page 47, line 25 skipping to change at page 48, line 15
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 VTODO WHERE UID = 'uid123' QUERY:SELECT * FROM VTODO WHERE UID = 'uid123'
QUERY:SELECT * FROM VEVENT WHERE UID = 'uid123' QUERY:SELECT * FROM VEVENT WHERE UID = 'uid123'
END:VQUERY END:VQUERY
6.1.1.17 Query by Date-Time range 6.1.1.17 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"
an instance greater than or equal to July 1st, 2000 00:00:00 UTC and component that has an instance greater than or equal to July 1st,
less than or equal to July 31st, 2000 23:59:59 UTC. This includes 2000 00:00:00 UTC and less than or equal to July 31st, 2000 23:59:59
single instance VEVENT objects that do no explicitly contain a UTC. This includes single instance "VEVENT" components that do no
RECURRENCE-ID. explicitly contain a "RECURRENCE-ID" property.
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 STATE() = 'BOOKED' AND STATE() = 'BOOKED'
END:VQUERY END:VQUERY
6.1.1.18 Query for all Unprocessed Entries 6.1.1.18 Query for all Unprocessed Entries
The following example selects the entire contents of all non-booked The following example selects the entire contents of all non-booked
"VTODO" and "VEVENT" components with their state of 'UNPROCESSED". "VTODO" and "VEVENT" components in the "UNPROCESSED" state. The
The default for EXPAND is FALSE, so the recurrence rules will not be default for the "EXPAND" property is FALSE, so the recurrence rules
expanded. will not be expanded.
BEGIN:VQUERY BEGIN:VQUERY
QUERYID:Fetch VEVENT and VTODO iTIP components QUERYID:Fetch VEVENT and VTODO iTIP components
QUERY:SELECT * FROM VEVENT WHERE QUERY:SELECT * FROM VEVENT WHERE
STATE() = 'UNPROCESSED' STATE() = 'UNPROCESSED'
QUERY:SELECT * FROM VTODO WHERE QUERY:SELECT * FROM VTODO WHERE
STATE() = 'UNPROCESSED' STATE() = 'UNPROCESSED'
END:VQUERY END:VQUERY
The following example fetches all "VEVENT" and "VTODO" components The following example fetches all "VEVENT" and "VTODO" components in
that are booked from the CS. the "BOOKED" state.
BEGIN:VQUERY BEGIN:VQUERY
QUERYID:Fetch All Booked VEVENT and VTODO components QUERYID:Fetch All Booked VEVENT and VTODO components
QUERY:SELECT * FROM VEVENT WHERE STATE() = 'BOOKED' QUERY:SELECT * FROM VEVENT WHERE STATE() = 'BOOKED'
QUERY:SELECT * FROM VTODO WHERE STATE() = 'BOOKED' QUERY:SELECT * FROM VTODO WHERE STATE() = 'BOOKED'
END:VQUERY END:VQUERY
The following fetches the UID for all VEVENT and VTODO components The following fetches the "UID" property for all "VEVENT" and
that have been marked for delete). "fVTODO" components that have been marked for delete.
BEGIN:VQUERY BEGIN:VQUERY
QUERYID:Fetch UIDs of marked for delete VEVENTs and VTODOs QUERYID:Fetch UIDs of marked for delete VEVENTs and VTODOs
QUERY:SELECT UID FROM VEVENT WHERE STATE() = 'DELETE' QUERY:SELECT UID FROM VEVENT WHERE STATE() = 'DELETE'
QUERY:SELECT UID FROM VTODO WHERE STATE() = 'DELETE' QUERY:SELECT UID FROM VTODO WHERE STATE() = 'DELETE'
END:VQUERY END:VQUERY
In the examples above they were bunched into groups of similar In the examples above they were bunched into groups of similar
queries. They could be performed all at once by having all of the queries. They could be performed all at once by having all of the
QUERY property in one BEGIN/END VQUERY component. "QUERY" properties in one BEGIN/END "VQUERY" component. The replies
MUST BE in the same order as the supplied "QUERY" properties.
6.1.1.19 Query with Subset of Properties by Date/Time 6.1.1.19 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
from February 1st to February 10th 2000 (in UTC). "DTSTART" value from February 1st to February 10th 2000 (in UTC).
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
6.1.1.20 Query with Components and Alarms In A Range 6.1.1.20 Query with Components and Alarms In A Range
This example fetches all booked "VEVENT" components with an alarm This example fetches all booked "VEVENT" components with an alarm
skipping to change at page 50, line 27 skipping to change at page 51, line 21
6.1.3 UPN-FILTER Value 6.1.3 UPN-FILTER Value
Value Name: UPN-FILTER Value Name: UPN-FILTER
Purpose: This value type is used to identify values that contain a Purpose: This value type is used to identify values that contain a
user principal name filter. user principal name filter.
Formal Definition: The value type is defined by the following Formal Definition: The value type is defined by the following
notation: notation:
upn-filter = "OWNER()" / ; NOTE: "CAL-OWNERS(cal-address)"
"NOT OWNER()" / ; and "NOT CAL-OWNERS(cal-addres)"
; are both NOT allowed below.
;
upn-filter = "CAL-OWNERS()" /
"NOT CAL-OWNERS()" /
"*" / "*" /
[ "*" / dot-atom-text ] "@" ( "*" / dot-atom-text ) [ "*" / dot-atom-text ] "@" ( "*" / dot-atom-text )
; dot-atom-text is defined in RFC 2822 ; dot-atom-text is defined in RFC 2822
Description: The value is used to match user principal names (UPNs). Description: The value is used to match user principal names (UPNs).
For "OWNER()" and "NOT OWNER()", see Section 6.1.1.3. For "CAL-OWNERS()" and "NOT CAL-OWNERS()", see Section 8.19.
* Matches all UPNs. * Matches all UPNs.
@ Matches the UPN of anonymous CUs @ Matches the UPN of anonymous CUs
belonging to the null realm belonging to the null realm
@* Matches the UPN of anonymous CUs @* Matches the UPN of anonymous CUs
belonging to any non-null realm belonging to any non-null realm
@realm Matches the UPN of anonymous CUs @realm Matches the UPN of anonymous CUs
skipping to change at page 51, line 29 skipping to change at page 52, line 29
*@realm Matches the UPN of non-anonymous CUs *@realm Matches the UPN of non-anonymous CUs
belonging to the specified realm belonging to the specified realm
user@realm Matches the UPN of the specified CU user@realm Matches the UPN of the specified CU
belonging to the specified realm belonging to the specified realm
user@* Not allowed. user@* Not allowed.
Example: The following are examples of this value type: Example: The following are examples of this value type:
DENY:NON OWNER() DENY:NON CAL-OWNERS()
6.2 New Parameter 7. New Parameters
6.2.1 ENABLE Parameter 7.1 ENABLE Parameter
Parameter Name: ENABLE Parameter Name: ENABLE
Purpose: This parameter indicates whether or not the "TRIGGER" Purpose: This parameter indicates whether or not the "TRIGGER"
property in a "VALARM" component should be ignored. property in a "VALARM" component should be ignored.
Value Type: BOOLEAN Value Type: BOOLEAN
Conformance: This property can be specified in the "TRIGGER" Conformance: This property can be specified in the "TRIGGER"
properties. properties.
Description: When a non owner sends an iTIP "REQUEST" to a calendar Description: When a non owner sends an [iTIP] "REQUEST" to a calendar
that object might contain a "VALARM" component. The owner may wish that object might contain a "VALARM" component. The owner may wish
to have local control over their own CUA and when or how alarms are to have local control over their own CUA and when or how alarms are
triggered. triggered.
A CUA may add the "ENABLE" parameter to any "TRIGGER" property before A CUA may add the "ENABLE" parameter to any "TRIGGER" property before
booking the component. If the "ENABLE" parameter is set to "FALSE", booking the component. If the "ENABLE" parameter is set to "FALSE",
then the alarm will be ignored by the CUA. If set to "TRUE", or of then the alarm will be ignored by the CUA. If set to "TRUE", or if
the "ENABLE" property is not in the "TRIGGER" property, the alarm is the "ENABLE" property is not in the "TRIGGER" property, the alarm is
enabled. The CUA should remove the "ENABLE" parameter before enabled. The CUA should remove the "ENABLE" parameter before
forwarding the component to a non-cap CUA. forwarding the component to a non-cap CUA.
If FALSE in the "VCALSTORE", then all "VAGENDA" ALLOW-CONFLICT values Formal Definition: The property is defined by the following notation:
MUST BE false in the CS.
Format Definition: The property is defined by the following notation:
allow-conflict = "ALLOW-CONFLICT" enable-param = "ENABLE" "=" boolean
*(";" xparam) ":" boolean CRLF
Example: The following is an example of this property for a "VAGENDA" Example: The following is an example of this property for a "VAGENDA"
component: component:
ALLOW-CONFLICT:FALSE TRIGGER;ENABLE=FALSE;RELATED=END:PT5M
6.2.2 LOCAL Parameter 7.2 LOCAL Parameter
Parameter Name: LOCAL Parameter Name: LOCAL
Purpose: Indicates if the VALARM should be exported to any non- Purpose: Indicates if the "VALARM" component should be exported to
organizer calendar. any non-organizer calendar.
Value Type: BOOLEAN Value Type: BOOLEAN
Conformance: This parameter can be specified in the "SEQUENCE"
Conformance: This property can be specified in the "SEQUENCE"
properties in a "VALARM" component. properties in a "VALARM" component.
Description: When a non owner sends an iTIP "REQUEST" to a calendar Description: When a non owner sends an [iTIP] "REQUEST" to a calendar
that object might contain a "VALARM" component. The owner may wish that object might contain a "VALARM" component. The owner may wish
to have local control over their own CUA and when or how alarms are to have local control over their own CUA and when or how alarms are
triggered. triggered.
A CUA may add the "LOCAL" parameter to the "SEQUENCE" property before A CUA may add the "LOCAL" parameter to the "SEQUENCE" property before
booking the component. If the "LOCAL" parameter is set to "FALSE", booking the component. If the "LOCAL" parameter is set to "FALSE",
then the alarm MUST NOT be forwarded to any non organizer calendar. then the alarm MUST NOT be forwarded to any non organizer calendar.
If set to "TRUE", or of the "LOCAL" property is not in the "SEQUENCE" If set to "TRUE", or of the "LOCAL" property is not in the "SEQUENCE"
property, the alarm is global. The CUA should remove the "LOCAL" property, the alarm is global. The CUA should remove the "LOCAL"
parameter before forwarding the component to a non-cap CUA and to non parameter before forwarding the component to a non-cap CUA and to non
organizer calendars. organizer calendars.
If FALSE in the "VCALSTORE", then all "VAGENDA" ALLOW-CONFLICT values Formal Definition: The property is defined by the following notation:
MUST BE false in the CS.
Format Definition: The property is defined by the following notation:
allow-conflict = "ALLOW-CONFLICT" local-param = "LOCAL" "=" boolean
*(";" xparam) ":" boolean CRLF
Example: The following is an example of this property for a "VAGENDA" Example: The following is an example of this property for a "VAGENDA"
component: component:
ALLOW-CONFLICT:FALSE SEQUENCE;LOCAL=TRUE:4
7. New Properties 8. New Properties
7.1 ALLOW-CONFLICT Property 8.1 ALLOW-CONFLICT Property
Property Name: ALLOW-CONFLICT Property Name: ALLOW-CONFLICT
Purpose: This property indicates whether or not the calendar and CS Purpose: This property indicates whether or not the calendar and CS
supports component conflicts. That is, whether or not any of the supports component conflicts. That is, whether or not any of the
components in the calendar can overlap. components in the calendar can overlap.
Value Type: BOOLEAN Value Type: BOOLEAN
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
skipping to change at page 54, line 29 skipping to change at page 55, line 29
Conformance: This property can be specified in "VAGENDA" and Conformance: This property can be specified in "VAGENDA" and
"VCALSTORE" component. "VCALSTORE" component.
Description: This property is used to indicate whether components may Description: This property is used to indicate whether components may
conflict. That is, if their expanded instances may share the same conflict. That is, if their expanded instances may share the same
time or overlap the same time periods. If it has a value of TRUE, time or overlap the same time periods. If it has a value of TRUE,
then conflicts are allowed. If FALSE, the no two components may then conflicts are allowed. If FALSE, the no two components may
conflict. conflict.
If FALSE in the "VCALSTORE", then all "VAGENDA" ALLOW-CONFLICT values If FALSE in the "VCALSTORE" component, then all "VAGENDA" component
MUST BE false in the CS. "ALLOW-CONFLICT" property values MUST BE false in the CS.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
allow-conflict = "ALLOW-CONFLICT" allow-conflict = "ALLOW-CONFLICT"
*(";" xparam) ":" boolean CRLF *(";" xparam) ":" boolean CRLF
Example: The following is an example of this property for a "VAGENDA" Example: The following is an example of this property for a "VAGENDA"
component: component:
ALLOW-CONFLICT:FALSE ALLOW-CONFLICT:FALSE
7.2 CALID Property 8.2 ATT-COUNTER Property
Property Name: ATT-COUNTER
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property MUST be specified in an iCalendar object
that specifies counter proposal to a group scheduled calendar entity.
When storing a "METHOD" property with the "COUNTER" method, there
needs to be a way to remember who sent the COUNTER. The ATT-COUNTER
property MUST BE added to all "COUNTER" [iTIP] components by the CUA
before storing in a CS.
Description: This property is used to identify the CAL-ADDRESS of the
entity that sent the "COUNTER" [iTIP] object.
Formal Definition: The property is defined by the following notation:
attcounter = "ATT-COUNTER" *(";" xparam) ":" cal-address CRLF
Examples:
ATT-COUNTER:cap:example.com/Doug
ATT-COUNTER:mailto:Doug@Example.com
8.3 CALID Property
Property Name: CALID Property Name: CALID
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in the "VAGENDA". Conformance: This property can be specified in the "VAGENDA"
component.
Description: This property is used to specify a fully qualified Description: This property is used to specify a fully qualified
calid. calid.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
CALID = "CALID" *(";" xparam) ":" calid CRLF CALID = "CALID" *(";" xparam) ":" calid CRLF
Example: Example:
CALID:cap://cal.example.com/sdfifgty4321 CALID:cap://cal.example.com/sdfifgty4321
7.3 CALMASTER Property 8.4 CALMASTER Property
Property Name: CALMASTER Property Name: CALMASTER
Purpose: The property specifies an e-mail address of a person Purpose: The property specifies an e-mail address of a person
responsible for the calendar store. responsible for the calendar store.
Value Type: URI Value Type: URI
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: The property can be specified in a "VCALSTORE" Conformance: The property can be specified in a "VCALSTORE"
component. component.
Description: The parameter value SHOULD BE a MAILTO URI as defined in Description: The parameter value SHOULD BE a MAILTO URI as defined in
[RFC1738]. It MUST BE a contact URI such as a MAILTO URI and not a [URL]. It MUST BE a contact URI such as a MAILTO URI and not a home
home page or file URI that describes how to contact the calmasters. page or file URI that describes how to contact the calmasters.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
calmaster = "CALMASTER" *(";" xparam) ":" uri CRLF calmaster = "CALMASTER" *(";" xparam) ":" uri CRLF
uri = IANA registered uri and defined by RFC 2445 uri = IANA registered uri and defined by RFC 2445
Example: The following is an example of this property: Example: The following is an example of this property:
CALMASTER:mailto:administrator@example.com CALMASTER:mailto:administrator@example.com
7.4 CARID Property 8.5 CARID Property
Property Name: CARID Property Name: CARID
Purpose: This property specifies the identifier for an access right Purpose: This property specifies the identifier for an access right
component. component.
Value Type: TEXT Value Type: TEXT
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property MUST BE specified once in a "VCAR" Conformance: This property MUST BE specified once in a "VCAR"
component. component.
Description: This property is used in the "VCAR" component to specify Description: This property is used in the "VCAR" component to specify
an identifier. an identifier. A "CARID" property value is unique per container.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
carid = "CARID" *(";" xparam) ":" text CRLF carid = "CARID" *(";" xparam) ":" text CRLF
Example: The following are examples of this property: Example: The following are examples of this property:
CARID:xyzzy-007 CARID:xyzzy-007
CARID:User Rights CARID:User Rights
7.5 CSID Property 8.6 CSID Property
Property Name: CSID Property Name: CSID
Purpose: The property specifies a the globally unique identifier for Purpose: The property specifies a the globally unique identifier for
the calendar store. the calendar store.
Value Type: URI Value Type: URI
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: The property can be specified in a "VCALSTORE" Conformance: The property can be specified in a "VCALSTORE"
component. component.
Description: The identifier MUST BE globally unique. Description: The identifier MUST BE globally unique.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
csid = "CSID" *(";" xparam) ":" capurl CRLF csid = "CSID" *(";" xparam) ":" capurl CRLF
Example: The following is an example of this property: Example: The following is an example of this property:
CSID:cap://calendar.example.com CSID:cap://calendar.example.com
7.6 DECREED Property 8.7 DECREED Property
Property Name: DECREED Property Name: DECREED
Purpose: This property specifies if an access right calendar Purpose: This property specifies if an access right calendar
component is decreed or not. component is decreed or not.
Value Type: BOOLEAN Value Type: BOOLEAN
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property MAY be specified once in a "VCAR" Conformance: This property MAY be specified once in a "VCAR"
component. component.
Description: This property is used in the "VCAR" component to specify Description: This property is used in the "VCAR" component to specify
whether the component is decreed or not. whether the component is decreed or not.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
decreed = "DECREED" *(";" xparam) ":" boolean CRLF decreed = "DECREED" *(";" xparam) ":" boolean CRLF
Example: The following is an example of this property: Example: The following is an example of this property:
DECREED:TRUE DECREED:TRUE
7.7 DEFAULT-CHARSET Property 8.8 DEFAULT-CHARSET Property
Property Name: DEFAULT-CHARSET Property Name: DEFAULT-CHARSET
Purpose: This property indicates the default charset. Purpose: This property indicates the default charset.
Value Type: TEXT Value Type: TEXT
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in "VAGENDA" and Conformance: This property can be specified in "VAGENDA" and
"VCALSTORE" calendar component. "VCALSTORE" calendar component.
Description: In a "VAGENDA", this property is used to indicate the Description: In a "VAGENDA" component, this property is used to
charset of calendar. If not specified, the default the first value indicate the charset of calendar. If not specified, the default is
in the "VCALSTORE" DEFAULT-CHARSET list. The value MUST BE an IANA the first value in the "VCALSTORE" components "DEFAULT-CHARSET"
registered character set as defined in [RFC 2278]. property value list. The value MUST BE an IANA registered character
set as defined in [CHARREG].
In a "VCALSTORE" it is a comma separated list of charsets supported In a "VCALSTORE" component it is a comma separated list of charsets
by the CS. The first entry is the default entry for all newly supported by the CS. The first entry is the default entry for all
created "VAGENDA"s. "UTF-8" MUST BE in the "VCALSTORE" DEFAULT- newly created "VAGENDA" components. The "UTF-8" value MUST BE in the
CHARSET list. "VCALSTORE" component "DEFAULT-CHARSET" property list. All compliant
CAP implementations must support the "UTF-8" charset.
If a charset name contains a comma (,), then that comma must be If a charset name contains a comma (,), then that comma must be
backslashed escaped in the value. backslashed escaped in the value.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
default-charset = "DEFAULT-CHARSET" *(";" xparam) default-charset = "DEFAULT-CHARSET" *(";" xparam)
":" text CRLF ":" text CRLF
Example: The following is an example of this property for a "VAGENDA" Example: The following is an example of this property for a "VAGENDA"
component: component:
DEFAULT-CHARSET:Shift_JIS,UTF-8 DEFAULT-CHARSET:Shift_JIS,UTF-8
7.8 DEFAULT-LOCALE Property 8.9 DEFAULT-LOCALE Property
Property Name: DEFAULT-LOCALE Property Name: DEFAULT-LOCALE
Purpose: This property specifies the default language for text Purpose: This property specifies the default language for text
values. values.
Value Type: TEXT Value Type: TEXT
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in "VAGENDA" and Conformance: This property can be specified in "VAGENDA" and
"VCALSTORE" components. "VCALSTORE" components.
Description: In a "VAGENDA", this property is used to indicate the Description: In a "VAGENDA" component, the "DEFAULT-LOCALE" property
locale of the calendar. The full locale SHOULD be used. The default is used to indicate the locale of the calendar. The full locale
and minimum locale is POSIX. SHOULD be used. The default and minimum locale is POSIX (aka the 'C'
locale).
In a "VCALSTORE" it is a comma separated list of locales supported by In a "VCALSTORE" component it is a comma separated list of locales
the CS. The first value in the list is the default for all newly supported by the CS. The first value in the list is the default for
created VAGENDAs. POSIX MUST BE in the list. all newly created VAGENDAs. "POSIX" MUST BE in the list.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
default-locale = "DEFAULT-LOCALE" *(";" xparam) default-locale = "DEFAULT-LOCALE" *(";" xparam)
":" language CRLF ":" language CRLF
language = Text identifying a locale, as defined in [RFC 2277] language = Text identifying a locale, as defined in [CHARPOL]
Example: The following is an example of this property: Example: The following is an example of this property:
DEFAULT-LOCALE:en-US.iso-8859-1,POSIX DEFAULT-LOCALE:en-US.iso-8859-1,POSIX
7.9 DEFAULT-TZID Property 8.10 DEFAULT-TZID Property
Property Name: DEFAULT-TZID Property Name: DEFAULT-TZID
Purpose: This property specifies the text value that specifies the Purpose: This property specifies the text value that specifies the
default time zone for a calendar. default time zone for a calendar.
Value Type: TEXT Value Type: TEXT
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property may be specified once in a "VAGENDA" and Conformance: This property may be specified once in a "VAGENDA" and
"VCALSTORE" components. "VCALSTORE" components.
Description: In a "VAGENDA" it is the value of the time zone for the Description: In a "VAGENDA" component it is the value of the time
calendar. This time zone is used when as the localtime for object zone for the calendar. This time zone is used when as the localtime
that contain a date or date-time value without a time zone. for object that contain a date or date-time value without a time
zone.
In a "VCALSTORE" it is a comma separated list of TZIDs known to the In a "VCALSTORE" component it is a comma separated list of TZIDs
CS. Where TZID values are the same as the TZID property as defined known to the CS. Where "TZID" property values are the same as the
in [iCAL]. The first entry in the list is used as the default TZID "TZID" property as defined in [iCAL]. The first entry in the list is
for all newly created calendars. The list MUST contain at least UTC. used as the default TZID for all newly created calendars. The list
MUST contain at least "UTC".
If the TZID contains a comma (,), the comma must be backslash If a "TZID" property value contains a comma (,), the comma must be
escaped. backslash escaped.
Format Definition: This property is defined by the following Formal Definition: This property is defined by the following
notation: notation:
default-tzid = "DEFAULT-TZID" *(";" xparam) default-tzid = "DEFAULT-TZID" *(";" xparam)
":" [tzidprefix] text CRLF ":" [tzidprefix] text CRLF
Example: The following is an example of this property: Example: The following is an example of this property:
DEFAULT-TZID:US/Eastern,UTC DEFAULT-TZID:US/Eastern,UTC
7.10 DEFAULT-VCARS Property 8.11 DEFAULT-VCARS Property
Property Name: DEFAULT-VCARS Property Name: DEFAULT-VCARS
Purpose: This property is used to specify the CARIDs of the default Purpose: This property is used to specify the "CARID" property ids of
VCAR components for newly created VAGENDA components. the default "VCAR" components for newly created "VAGENDA" components.
Value Type: TEXT Value Type: TEXT
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property MUST BE specified in "VCALSTORE" calendar Conformance: This property MUST BE specified in "VCALSTORE" calendar
component and MUST at least specify the following values: component and MUST at least specify the following values:
READBUSYTIMEINFO, REQUESTONLY, UPDATEPARTSTATUS, and DEFAULTOWNER. "READBUSYTIMEINFO", "REQUESTONLY", "UPDATEPARTSTATUS", and
"DEFAULTOWNER".
Description: This property is used in the "VCALSTORE" calendar Description: This property is used in the "VCALSTORE" component to
component to specify the CARID of the VCAR components that MUST BE specify the "CARID" value of the "VCAR" components that MUST BE
copied in VAGENDA at creation time by the CS. These VCARS components copied into now "VAGENDA" components at creation time by the CS. All
MUST BE stored in the "VCALSTORE". "DEFAULT-VCAR" values must have "VCARS" components stored in the
"VCALSTORE".
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
def-vcars = "DEFAULT-VCARS" *(";" xparam) ":" text def-vcars = "DEFAULT-VCARS" *(";" xparam) ":" text
*( "," text ) CRLF *( "," text ) CRLF
Example: The following is an example of this property: Example: The following is an example of this property:
DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY, DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY,
UPDATEPARTSTATUS,DEFAULTOWNER UPDATEPARTSTATUS,DEFAULTOWNER
7.11 DENY Property 8.12 DENY Property
Property Name: DENY Property Name: DENY
Purpose: This property identifies the UPN(s) being denied access in Purpose: This property identifies the UPN(s) being denied access in
the VRIGHT component. the "VRIGHT" component.
Value Type: UPN-FILTER Value Type: UPN-FILTER
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in "VRIGHT" calendar Conformance: This property can be specified in "VRIGHT" components.
components.
Description: This property is used in the "VRIGHT" component to Description: This property is used in the "VRIGHT" component to
define the CU or UG being denied access. define the CU or UG being denied access.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
deny = "DENY" *(";" xparam) ":" upn-filter CRLF deny = "DENY" *(";" xparam) ":" upn-filter CRLF
Example: The following are examples of this property: Example: The following are examples of this property:
DENY:* DENY:*
DENY:bob@example.com DENY:bob@example.com
7.12 EXPAND property 8.13 EXPAND property
Property Name: EXPAND Property Name: EXPAND
Purpose: This property is to notify the CS if it should or should not Purpose: This property is to notify the CS if it should or should not
expand any component with recurrence rules into multiple instances in expand any component with recurrence rules into multiple instances in
a query reply. a query reply.
Value Type: BOOLEAN Value Type: BOOLEAN
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in "VQUERY" calendar Conformance: This property can be specified in "VQUERY" components.
components.
Description: If a CUA wishes to see all of the instances of a Description: If a CUA wishes to see all of the instances of a
recurring component the CUA sets EXPAND=TRUE in the VQUERY component. recurring component the CUA sets EXPAND=TRUE in the "VQUERY"
If not specified, the default is FALSE. component. If not specified, the default is FALSE.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
expand = "EXPAND" *(";" xparam) ":" ("TRUE" / "FALSE") CRLF expand = "EXPAND" *(";" xparam) ":" ("TRUE" / "FALSE") CRLF
Example: The following are examples of this property: Example: The following are examples of this property:
EXPAND:FALSE EXPAND:FALSE
EXPAND:TRUE EXPAND:TRUE
7.13 GRANT Property 8.14 GRANT Property
Property Name: GRANT Property Name: GRANT
Purpose: This property identifies the UPN(s) being granted access in Purpose: This property identifies the UPN(s) being granted access in
the VRIGHT component. the "VRIGHT" component.
Value Type: UPN-FILTER Value Type: UPN-FILTER
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in "VRIGHT" calendar Conformance: This property can be specified in "VRIGHT" calendar
components. components.
Description: This property is used in the "VRIGHT" component to Description: This property is used in the "VRIGHT" component to
specify the CU or UG being granted access. specify the CU or UG being granted access.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
grant = "GRANT" *(";" xparam) ":" upn-filter CRLF grant = "GRANT" *(";" xparam) ":" upn-filter CRLF
Example: The following are examples of this property: Example: The following are examples of this property:
GRANT:* GRANT:*
GRANT:bob@example.com GRANT:bob@example.com
7.14 MAXDATE Property 8.15 MAXDATE Property
Property Name: MAXDATE Property Name: MAXDATE
Purpose: This property specifies the date/time in the future beyond Purpose: This property specifies the date/time in the future beyond
which the CS cannot represent. which the CS cannot represent.
Value Type: DATE-TIME Value Type: DATE-TIME
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: The property can be specified in the "VCALSTORE". Conformance: The property can be specified in the "VCALSTORE"
component.
Description: The date and time MUST BE a UTC value and end with 'Z'. Description: The date and time MUST BE a UTC value and end with 'Z'.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
maxdate = "MAXDATE" *(";" xparam) ":" date-time CRLF maxdate = "MAXDATE" *(";" xparam) ":" date-time CRLF
Example: The following is an example of this property: Example: The following is an example of this property:
MAXDATE:20990101T000000Z MAXDATE:20990101T000000Z
7.15 MINDATE Property 8.16 MINDATE Property
Property Name: MINDATE Property Name: MINDATE
Purpose: This property specifies the date/time in the past prior to Purpose: This property specifies the date/time in the past prior to
which the server cannot represent. which the server cannot represent.
Value Type: DATE-TIME Value Type: DATE-TIME
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: The property can be specified in the "VCALSTORE". Conformance: The property can be specified in the "VCALSTORE"
component.
Description: The date and time MUST BE a UTC value and end with 'Z'. Description: The date and time MUST BE a UTC value and end with 'Z'.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
mindate = "MINDATE" *(";" xparam) ":" date-time CRLF mindate = "MINDATE" *(";" xparam) ":" date-time CRLF
Example: The following is an example of this property: Example: The following is an example of this property:
MINDATE:19710101T000000Z MINDATE:19710101T000000Z
7.16 NAME Property 8.17 MULTIPART Property
Property Name: MULTIPART
Purpose: This property provides a comma separated list of supported
MIME multipart types supported by the sender.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified in a component.
Description: This property is used in the in the "GET-CAPABILITY"
comamnd reply to indicated the MIME multipart types supported. A CS
and CUS SHOULD support all registered MIME multipart types.
Formal Definition: The property is defined by the following notation:
name = "MULTIPART" nameparam ":" text CRLF
nameparam = *(
; the following is optional,
; and MAY occur more than once
( ";" xparam )
)
Example: The following is an example of this property:
MULTIPART:related,alternate,mixed
8.18 NAME Property
Property Name: NAME Property Name: NAME
Purpose: This property provides a localizeable display name for a Purpose: This property provides a localizable display name for a
component. component.
Value Type: TEXT Value Type: TEXT
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in a component. Conformance: This property can be specified in a component.
Description: This property is used in the in component to specify a Description: This property is used in the in component to specify a
localizeable display name. If more than one NAME property is in a localizable display name. If more than one "NAME" properties are in
component, then they MUST have unique LANG parameters. If the LANG a component, then they MUST have unique "LANG" parameters. If the
parameter is not supplied, then it defaults to the VAGENDAs default "LANG" parameter is not supplied, then it defaults to the "VAGENDA"
if the component is in a VAGENDA, or the VCALSTORE default if the default if the component is in a "VAGENDA", or the "VCALSTORE"
component is stored at the VCALSTORE level. default if the component is stored at the "VCALSTORE" level.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
name = "NAME" nameparam ":" text CRLF name = "NAME" nameparam ":" text CRLF
nameparam = *( nameparam = *(
; the following is optional, ; the following is optional,
; but MUST NOT occur more than once ; but MUST NOT occur more than once
( ";" languageparam ) / ( ";" languageparam ) /
; the following is optional, ; the following is optional,
skipping to change at page 65, line 28 skipping to change at page 68, line 25
( ";" xparam ) ( ";" xparam )
) )
languageparam = ; As defined in [iCAL]. languageparam = ; As defined in [iCAL].
Example: The following is an example of this property: Example: The following is an example of this property:
NAME:Restrict Guests From Creating VALARMs On VEVENTs NAME:Restrict Guests From Creating VALARMs On VEVENTs
7.17 OWNER Property 8.19 OWNER Property
Property Name: OWNER Property Name: OWNER
Purpose: The property specifies an owner of the component. Purpose: The property specifies an owner of the component.
Value Type: UPN Value Type: UPN
Property Parameters: Non-standard, alternate text representation and Property Parameters: Non-standard, alternate text representation and
language property parameters can be specified on this property. language property parameters can be specified on this property.
Conformance: The property MUST BE specified at in a "VAGENDA" Conformance: The property MUST BE specified at in a "VAGENDA"
component. component.
Description: A multi-instanced property indicating the calendar Description: A multi-instanced property indicating the calendar
owner. owner.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
owner = "OWNER" *(";" xparam) ":" upn CRLF owner = "OWNER" *(";" xparam) ":" upn CRLF
Example: The following is an example of this property: Example: The following is an example of this property:
OWNER:jsmith@acme.com OWNER:jsmith@acme.com
OWNER:jdoe@acme.com OWNER:jdoe@acme.com
7.18 PERMISSION Property 8.20 PERMISSION Property
Property Name: PERMISSION Property Name: PERMISSION
Purpose: This property defines a permission that is granted or denied Purpose: This property defines a permission that is granted or denied
in a VRIGHT component. in a "VRIGHT" component.
Value Type: TEXT Value Type: TEXT
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in "VRIGHT" calendar Conformance: This property can be specified in "VRIGHT" components.
components.
Description: This property is used in the "VRIGHT" component to Description: This property is used in the "VRIGHT" component to
define a permission that is granted or denied. define a permission that is granted or denied.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
perm = "PERMISSION" *(";" xparam) ":" permvalue CRLF perm = "PERMISSION" *(";" xparam) ":" permvalue CRLF
permvalue = ( "READ" / "CREATE" / "DELETE" / "MODIFY" / all ) permvalue = ( "SEARCH" / "CREATE" / "DELETE" / "MODIFY" / all )
all = "*" all = "*"
Example: The following is an example of this property: Example: The following is an example of this property:
PERMISSION:READ PERMISSION:SEARCH
7.19 QUERY property 8.21 QUERY property
Property Name: QUERY Property Name: QUERY
Purpose: Specifies the query for the component. Purpose: Specifies the query for the component.
Value Type: CAL-QUERY Value Type: CAL-QUERY
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in "VQUERY" components. Conformance: This property can be specified in "VQUERY" components.
Description: A "QUERY" is used to specify the CAL-QUERY (Section Description: A "QUERY" is used to specify the "CAL-QUERY" (Section
6.1.1 for the query. 6.1.1 for the query.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
query = "QUERY" *(";" xparam) ":" cal-query CRLF query = "QUERY" *(";" xparam) ":" cal-query CRLF
Example: The following is an example of this property: Example: The following is an example of this property:
QUERY:SELECT * FROM VEVENT QUERY:SELECT * FROM VEVENT
7.20 QUERYID property 8.22 QUERYID property
Property Name: QUERYID Property Name: QUERYID
Purpose: Specifies a unique ID for a query in the targeted container. Purpose: Specifies a unique ID for a query in the targeted container.
Value Type: TEXT Value Type: TEXT
Property Parameters: Non-standard property parameters are specified Property Parameters: Non-standard property parameters are specified
on this property. on this property.
Conformance: This property can be specified in "VQUERY" components. Conformance: This property can be specified in "VQUERY" components.
Description: A "QUERYID" is used to specify the unique id for a Description: A "QUERYID" property is used to specify the unique id
stored query. for a stored query. A "QUERYID" property value is unique per
container.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
queryid = "QUERYID" *(";" xparam) ":" text CRLF queryid = "QUERYID" *(";" xparam) ":" text CRLF
Example: The following are examples of this property: Example: The following are examples of this property:
QUERYID:Any Text String QUERYID:Any Text String
QUERYID:fetchUnProcessed QUERYID:fetchUnProcessed
7.21 REQUEST-STATUS property 8.23 REQUEST-STATUS property
This description is a revision of the REQUEST-STATUS property for This description is a revision of the "REQUEST-STATUS" property for
VCALENDAR version 2.0. The 'statdesc' is optional and the 'extdata' VCALENDAR version 2.0. The 'statdesc' is optional and the 'extdata'
may be included when 'statdesc' is not provided. may be included when 'statdesc' is not provided.
rstatus = "REQUEST-STATUS" rstatparam ":" rstatus = "REQUEST-STATUS" rstatparam ":"
statcode ";" *(statdesc ) ";" *(extdata) statcode ";" *(statdesc ) ";" *(extdata)
rstatparam = *( rstatparam = *(
; the following is optional, ; the following is optional,
; but MUST NOT occur more than once ; but MUST NOT occur more than once
skipping to change at page 69, line 22 skipping to change at page 72, line 21
REQUEST-STATUS:4.1;Time conflict. Date/time is busy. REQUEST-STATUS:4.1;Time conflict. Date/time is busy.
REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE: REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE:
MAILTO:jsmith@example.com MAILTO:jsmith@example.com
REQUEST-STATUS:3.7;;ATTENDEE:MAILTO:jsmith@example.com REQUEST-STATUS:3.7;;ATTENDEE:MAILTO:jsmith@example.com
REQUEST-STATUS:10.4;Help! That really shouldn't have happened. REQUEST-STATUS:10.4;Help! That really shouldn't have happened.
7.22 RESTRICTION Property 8.24 RESTRICTION Property
Property Name: RESTRICTION Property Name: RESTRICTION
Purpose: This property defines restrictions on the result value of Purpose: This property defines restrictions on the result value of
new or existing components. new or existing components.
Value Type: CAL-QUERY Value Type: CAL-QUERY
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in "VRIGHT" calendar Conformance: This property can be specified in "VRIGHT" components,
components, but only when the PERMISSION property is set to "CREATE", but only when the "PERMISSION" property is set to "CREATE", "MODIFY",
"MODIFY", or "*". or "*" property value.
Description: This property is used in the "VRIGHT" component to Description: This property is used in the "VRIGHT" component to
define restrictions on the components that can be written (i.e., by define restrictions on the components that can be written (i.e., by
using the "CREATE" or "MOVE" commands) as well as on the values that using the "CREATE" or "MOVE" commands) as well as on the values that
may take existent calendar store properties, calendar properties, may take existent calendar store properties, calendar properties,
components, and properties (i.e., by using the "MODIFY" command). components, and properties (i.e., by using the "MODIFY" command).
Accepted values MUST match the specified RESTRICTION. Accepted values MUST match any specified "RESTRICTION" property
values.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
restrict = "RESTRICTION" *(";" xparam) ":" cal-query CRLF restrict = "RESTRICTION" *(";" xparam) ":" cal-query CRLF
Example: The following are examples of this property: Example: The following are examples of this property:
RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST' RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST'
RESTRICTION:SELECT * FROM VEVENT WHERE RESTRICTION:SELECT * FROM VEVENT WHERE
SELF() IN CAL-OWNERS(ORGANIZER) SELF() IN ORGANIZER
RESTRICTION:SELECT * FROM VEVENT WHERE 'BUSINESS' IN RESTRICTION:SELECT * FROM VEVENT WHERE 'BUSINESS' IN
CATEGORIES CATEGORIES
7.23 SCOPE Property 8.25 SCOPE Property
Property Name: SCOPE Property Name: SCOPE
Purpose: This property identifies the objects in the CS to which the Purpose: This property identifies the objects in the CS to which the
access rights applies. access rights applies.
Value Type: CAL-QUERY Value Type: CAL-QUERY
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in "VRIGHT" calendar Conformance: This property can be specified in "VRIGHT" components.
components.
Description: This property is used in the "VRIGHT" component to Description: This property is used in the "VRIGHT" component to
define the set of objects subject to the access right being defined. define the set of objects subject to the access right being defined.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
scope = "SCOPE" *(";" xparam) ":" cal-query CRLF scope = "SCOPE" *(";" xparam) ":" cal-query CRLF
Example: The following is an example of this property: Example: The following is an example of this property:
SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC' SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC'
7.24 TARGET Property 8.26 TARGET Property
Property Name: TARGET Property Name: TARGET
Purpose: This property defines the container that the command that is Purpose: This property defines the container that the command that is
issued will act upon. It its value is a capurl as defended in issued will act upon. Its value is a capurl as defined in Section 5.
Section 5. The "TARGET" property MUST BE supplied when the CUA sends a command
to the CS.
Value Type: URI Value Type: URI
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in a command component. Conformance: This property can be specified in a command component.
Description: This properties value is used to specify the container Description: This property value is used to specify the container
that the command will effect. When used in a command, the command that the command will effect. When used in a command, the command
will be performed on the container which has a capurl matching the will be performed on the container which has a capurl matching the
value. value.
Format Definition: The property is specified by the following Formal Definition: The property is specified by the following
notation: notation:
target = "TARGET" *(";" xparam) ":" capurl CRLF target = "TARGET" *(";" xparam) ":" capurl CRLF
The following is an example of this property: The following is an example of this property:
TARGET:cap://mycal.example.com TARGET:cap://mycal.example.com
TARGET:SomeRelCalid TARGET:SomeRelCalid
7.25 TRANSP Property 8.27 TRANSP Property
Property Name: TRANSP Property Name: TRANSP
Purpose: This property defines whether an component is transparent or Purpose: This property defines whether an component is transparent or
not to busy time searches. This is a modification to [iCAL] TRANSP not to busy time searches. This is a modification to [iCAL] "TRANSP"
in that it adds some values. property in that it adds some values.
Value Type: TEXT Value Type: TEXT
Property Parameters: Non-standard property parameters can be Property Parameters: Non-standard property parameters can be
specified on this property. specified on this property.
Conformance: This property can be specified in a component. Conformance: This property can be specified in a component.
Description: Time Transparency is the characteristic of an object Description: Time Transparency is the characteristic of an object
that determines whether it appears to consume time on a calendar. that determines whether it appears to consume time on a calendar.
Objects that consume actual time for the individual or resource Objects that consume actual time for the individual or resource
associated with the calendar SHOULD be recorded as OPAQUE, allowing associated with the calendar SHOULD be recorded as "OPAQUE", allowing
them to be detected by free-busy time searches. Other objects, which them to be detected by free-busy time searches. Other objects, which
do not take up the individual's (or resource's) time SHOULD be do not take up the individual's (or resource's) time SHOULD be
recorded as TRANSPARENT, making them invisible to free-busy time recorded as "TRANSPARENT", making them invisible to free-busy time
searches. searches.
Format Definition: The property is specified by the following Formal Definition: The property is specified by the following
notation: notation:
transp = "TRANSP" *(";" xparam) ":" transvalue CRLF transp = "TRANSP" *(";" xparam) ":" transvalue CRLF
transvalue = "OPAQUE" ;Blocks or opaque on busy time searches. transvalue
= "OPAQUE" ;Blocks or opaque on busy time searches.
/ "TRANSPARENT" ;Transparent on busy time searches. / "TRANSPARENT" ;Transparent on busy time searches.
/ "TRANSPARENT-NOCONFLICT" ; Transparent on busy time / "TRANSPARENT-NOCONFLICT" ; Transparent on busy time
; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects ; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects
; can overlap it. ; can overlap it.
/ "OPAQUE-NOCONFLICT" ; Opaque on busy time / "OPAQUE-NOCONFLICT" ; Opaque on busy time
; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects ; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects
; can overlap it. ; can overlap it.
; ;
;Default value is OPAQUE ;Default value is OPAQUE
The following is an example of this property for an object that is The following is an example of this property for an object that is
opaque or blocks on free/busy time searches plus no other object can opaque or blocks on free/busy time searches plus no other object can
overlap it: overlap it:
TRANSP:OPAQUE-NOCONFLICT TRANSP:OPAQUE-NOCONFLICT
8. New Components 9. New Components
8.1 VAGENDA Component 9.1 VAGENDA Component
Component Name: VAGENDA Component Name: VAGENDA
Purpose: Provide a grouping of properties that defines an agenda. Purpose: Provide a grouping of properties that defines an agenda.
Formal Definition: There are two formats of a VAGENDA. (1) When it Formal Definition: There are two formats of the "VAGENDA" component.
is being created, and (2) how it exists in the VCALSTORE. A (1) When it is being created, and (2) how it exists in the
"VAGENDA" component in the VCALSTORE is defined by the following "VCALSTORE" component. A "VAGENDA" component in a "VCALSTORE"
notation table and ABNF notation. component is defined by the following notation table and ABNF
notation.
The following is a summary of the properties of a calendar. The following is a summary of the properties of a calendar.
Name Read Description Name Read Description
Only Only
------------------------------------------------------------------ ------------------------------------------------------------------
ALLOW-CONFLICT N This boolean value indicates whether or not ALLOW-CONFLICT N This boolean value indicates whether or not
the calendar supports object conflicts. That the calendar supports object conflicts. That
is, whether or not any of the components in is, whether or not any of the components in
the calendar can have a time overlap. MUST BE the calendar can have a time overlap. MUST BE
FALSE if VCALSTORE ALLOW-CONFLICT is FALSE. FALSE if VCALSTORE ALLOW-CONFLICT is FALSE.
CALID N A unique identifier within the VCALSTORE for CALID N A unique identifier within the VCALSTORE for
the calendar. MUST NOT BE empty. MUST BE a the calendar. MUST NOT BE empty. MUST BE a
relative calid in a VAGENDA. relative calid in a VAGENDA.
CALSCALE N The CALSCALE for this calendar. MUST BE from CALSCALE N The CALSCALE for this calendar. MUST BE from
the VCALSTORE CALSCALE list. The default is the VCALSTORE CALSCALE list. The default is
the first entry in the VCALSTORE CALSCALE the first entry in the VCALSTORE CALSCALE list.
list.
CREATED Y timestamp of the calendar's create date. CREATED Y timestamp of the calendar's create date.
DEFAULT-CHARSET N The charset for this calendar. MUST BE from DEFAULT-CHARSET N The charset for this calendar. MUST BE from
the VCALSTORE DEFAULT-CHARSET list. If empty the VCALSTORE DEFAULT-CHARSET list. If empty
then it is the first entry in the VCALSTORE then it is the first entry in the VCALSTORE
DEFAULT-CHARSET list. DEFAULT-CHARSET list.
DEFAULT-LOCALE DEFAULT-LOCALE
N The locale for this calendar. MUST BE from N The locale for this calendar. MUST BE from
skipping to change at page 74, line 13 skipping to change at page 77, line 11
DEFAULT-CHARSET list. DEFAULT-CHARSET list.
DEFAULT-TZID N The id of the timezone associated with this DEFAULT-TZID N The id of the timezone associated with this
calendar. If empty it is the first entry calendar. If empty it is the first entry
in VCALSTORE DEFAULT-TZID. in VCALSTORE DEFAULT-TZID.
LAST-MODIFIED Y The timestamp when the properties of the LAST-MODIFIED Y The timestamp when the properties of the
calendar were last updated. calendar were last updated.
NAME N Optional display name for this calendar. It NAME N Optional display name for this calendar. It
is a localizeable string. May be multiple is a localizable string. May be multiple
instance and no two instances may have the instance and no two instances may have the
same LANG parameter. All instances MUST have same LANG parameter. All instances MUST have
the LANG parameter. the LANG parameter.
OWNER N A multi-instanced property indicating the OWNER N A multi-instanced property indicating the
calendar owner. Each entry returned will be a calendar owner. Each entry returned will be a
UPN. There MUST BE at least one owner. UPN. There MUST BE at least one owner.
RELATED-TO N An optional multi-instance property indicating RELATED-TO N An optional multi-instance property indicating
any relationship to other CALIDs and their CALIDs. any relationship to other CALIDs and their CALIDs.
agenda = "BEGIN" ":" "VAGENDA" CRLF agenda = "BEGIN" ":" "VAGENDA" CRLF
agendaprop agendaprop
"END" ":" "VAGENDA" CRLF "END" ":" "VAGENDA" CRLF
agendaprop = *( agendaprop = *(
; The following MUST occur exactly once. ; The following MUST occur exactly once.
;
allow-conflict / calid / calscale / created allow-conflict / calid / calscale / created
/ default-charset / default-locale / default-charset / default-locale
/ default-tzid / last-modified / / default-tzid / last-modified /
; The following MUST occur at least once. ; The following MUST occur at least once.
; and the value MUST NOT be empty. ; and the value MUST NOT be empty.
/ owner / owner
; The following are optional, ; The following are optional,
skipping to change at page 75, line 11 skipping to change at page 78, line 11
) )
When creating a VAGENDA, use the following notation: When creating a VAGENDA, use the following notation:
agendac = "BEGIN" ":" "VAGENDA" CRLF agendac = "BEGIN" ":" "VAGENDA" CRLF
agendacprop agendacprop
"END" ":" "VAGENDA" CRLF "END" ":" "VAGENDA" CRLF
agendacprop = *( agendacprop = *(
; The following MUST occur exactly once. ; The following MUST occur exactly once.
;
allow-conflict / calid / calscale allow-conflict / calid / calscale
/ default-charset / default-locale / default-charset / default-locale
/ default-tzid / / default-tzid /
; The following MUST occur at least once. ; The following MUST occur at least once.
; and the value MUST NOT be empty. ; and the value MUST NOT be empty.
;
/ owner / owner
; The following are optional, ; The following are optional,
; and MAY occur more than once. ; and MAY occur more than once.
;
/ name / related-to / iana-token / x-prop / x-comp / name / related-to / iana-token / x-prop / x-comp
) )
To fetch all of the properties from the targeted VAGENDA. This does To fetch all of the properties from the targeted "VAGENDA" component.
not fetch any components: This does not fetch any components:
SELECT * FROM VAGENDA SELECT * FROM VAGENDA
To fetch all of the properties from the targeted VAGENDA and all of To fetch all of the properties from the targeted VAGENDA and all of
the contained components, use the special '*.*' value: the contained components, use the special '*.*' value:
SELECT *.* FROM VAGENDA SELECT *.* FROM VAGENDA
8.2 VCALSTORE Component 9.2 VCALSTORE Component
Component Name: VCALSTORE Component Name: VCALSTORE
Purpose: Provide a grouping of properties that defines a calendar Purpose: Provide a grouping of properties that defines a calendar
store. store.
Formal Definition: A "VCALSTORE" component is defined by the Formal Definition: A "VCALSTORE" component is defined by the
following table and ABNF notation. The creation of a VCALSTORE is an following table and ABNF notation. The creation of a "VCALSTORE"
administrative task and not part of the CAP protocol. component is an administrative task and not part of the CAP protocol.
The following is a summary of the properties of the calendar store. The following is a summary of the properties of the calendar store.
Name Read Description Name Read Description
Only Only
------------------------------------------------------------------- -------------------------------------------------------------------
ALLOW-CONFLICT Y This boolean value indicates Whether or not ALLOW-CONFLICT Y This boolean value indicates Whether or not
the VCALSTORE supports object conflicts. That the VCALSTORE supports object conflicts. That
is, whether or not any of the objects in any is, whether or not any of the objects in any
calendar can overlap. If FALSE, then the CS calendar can overlap. If FALSE, then the CS
does not allow conflicts for any entry in any does not allow conflicts for any object in any
calendar. How this property is set in the calendar. How this property is set in the
VCALSTORE is an administrative or implementation VCALSTORE is an administrative or implementation
specific issue and is not covered in CAP. specific issue and is not covered in CAP.
CALSCALE Y A comma separated list of CALSCALEs supported CALSCALE Y A comma separated list of CALSCALEs supported
by this CS. All Calendar CALSCALE properties by this CS. All Calendar CALSCALE properties
MUST BE from this list. MUST contain at least MUST BE from this list. MUST contain at least
"GREGORIAN". The default for newly created "GREGORIAN". The default for newly created
calendars is the first entry. How this property calendars is the first entry. How this property
is set in the VCALSTORE is an administrative is set in the VCALSTORE is an administrative
skipping to change at page 77, line 21 skipping to change at page 80, line 21
DEFAULT-VCARS N A multivalued property containing the CARID's for DEFAULT-VCARS N A multivalued property containing the CARID's for
the default VCARs for newly created top level the default VCARs for newly created top level
calendars. It MUST include at a minimum calendars. It MUST include at a minimum
READBUSYTIMEINFO, REQUESTONLY, UPDATEPARTSTATUS, READBUSYTIMEINFO, REQUESTONLY, UPDATEPARTSTATUS,
and DEFAULTOWNER. and DEFAULTOWNER.
DEFAULT-TZID N A comma separated list of TZID's supported by DEFAULT-TZID N A comma separated list of TZID's supported by
the CS. These will be known across all calendars. the CS. These will be known across all calendars.
Calendar entries take precedence if they exist Calendar entries take precedence if they exist
in both the CS and calendar. MUST include at least in both the CS and calendar. It MUST include at least
UTC. First entry is default for all newly created UTC. First entry is default for all newly created
calendars. calendars.
LAST-MODIFIED Y The timestamp when the Properties of the CS LAST-MODIFIED Y The timestamp when the Properties of the CS
were last updated or calendars were created were last updated or calendars were created
or deleted. or deleted.
NAME N Optional, multi instance display names for NAME N Optional, multi instance display names for
this CS. It is a localizeable string. May this CS. It is a localizable string. May
be multiple instance and no two instances may be multiple instance and no two instances may
have the same LANG parameter. All instances have the same LANG parameter. All instances
MUST have the LANG parameter in the VCALSTORE. MUST have the LANG parameter in the VCALSTORE.
RELATED-TO N An optional multi-instance property indicating RELATED-TO N An optional multi-instance property indicating
any relationship to other CSs and those CALIDs. any relationship to other CSs and those CALIDs.
calstorec = "BEGIN" ":" "VCALSTORE" CRLF calstorec = "BEGIN" ":" "VCALSTORE" CRLF
calstoreprop calstoreprop
"END" ":" "VCALSTORE" CRLF "END" ":" "VCALSTORE" CRLF
skipping to change at page 78, line 30 skipping to change at page 81, line 30
/ children / name / related-to / children / name / related-to
) )
To fetch all of the properties from the targeted VCALSTORE and not To fetch all of the properties from the targeted VCALSTORE and not
fetch the calendars that it contains: fetch the calendars that it contains:
SELECT * FROM VCALSTORE SELECT * FROM VCALSTORE
To fetch all of the properties from the targeted VCALSTORE and all of To fetch all of the properties from the targeted "VCALSTORE"
the contained calendars and all of those calendars contained component and all of the contained calendars and all of those
properties and components, use the special '*.*' value: calendars contained properties and components, use the special '*.*'
value:
SELECT *.* FROM VCALSTORE SELECT *.* FROM VCALSTORE
8.3 VCAR Component 9.3 VCAR Component
Component Name: VCAR Component Name: VCAR
Purpose: Provide a grouping of calendar access rights. Purpose: Provide a grouping of calendar access rights.
Format Definition: A "VCAR" component is defined by the following Formal Definition: A "VCAR" component is defined by the following
notation: notation:
carc = "BEGIN" ":" "VCAR" CRLF carc = "BEGIN" ":" "VCAR" CRLF
carprop 1*rightc carprop 1*rightc
"END" ":" "VCAR" CRLF "END" ":" "VCAR" CRLF
carprop = 1*( carprop = 1*(
; 'carid' is REQUIRED, ; 'carid' is REQUIRED,
; but MUST NOT occur more than once ; but MUST NOT occur more than once
skipping to change at page 79, line 27 skipping to change at page 82, line 27
; and MAY occur more than once ; and MAY occur more than once
name / x-prop / iana-prop name / x-prop / iana-prop
) )
Description: A "VCAR" component is a grouping of properties, and Description: A "VCAR" component is a grouping of properties, and
"VRIGHT" components, that represents access rights granted or denied "VRIGHT" components, that represents access rights granted or denied
to UPNs. to UPNs.
The "CARID" property specifies the local identifier for the "VCAR" The "CARID" property specifies the local identifier for the "VCAR"
component. The "NAME" property specifies a localizeable display component. The "NAME" property specifies a localizable display name.
name.
Example: In the following example, the UPN "foo@example.com" is given Example: In the following example, the UPN "foo@example.com" is given
read access to the "DTSTART" and "DTEND" VEVENT properties. No other search access to the "DTSTART" and "DTEND" VEVENT properties. No
access is specified: other access is specified:
BEGIN:VCAR BEGIN:VCAR
CARID:Veiw Start and End Times CARID:View Start and End Times
NAME:View Start and End Times NAME:View Start and End Times
BEGIN:VRIGHT BEGIN:VRIGHT
GRANT:foo@example.com GRANT:foo@example.com
PERMISSION:READ PERMISSION:SEARCH
SCOPE:SELECT DTSTART,DTEND FROM VEVENT SCOPE:SELECT DTSTART,DTEND FROM VEVENT
END:VRIGHT END:VRIGHT
END:VCAR END:VCAR
In this example, all UPNs are given read access to "DTSTART" and In this example, all UPNs are given search access to "DTSTART" and
"DTEND" properties of VEVENT components. "All CUs and UGs" are "DTEND" properties of VEVENT components. "All CUs and UGs" are
specified by the UPN value "*". Note that this enumerated UPN value specified by the UPN value "*". Note that this enumerated UPN value
is not in quotes: is not in quotes:
BEGIN:VCAR BEGIN:VCAR
CARID:ViewStartEnd2 CARID:ViewStartEnd2
NAME:View Start and End Times 2 NAME:View Start and End Times 2
BEGIN:VRIGHT BEGIN:VRIGHT
GRANT:* GRANT:*
PERMISSION:READ PERMISSION:SEARCH
SCOPE:SELECT DTSTART,DTEND FROM VEVENT SCOPE:SELECT DTSTART,DTEND FROM VEVENT
END:VRIGHT END:VRIGHT
END:VCAR END:VCAR
In these examples, full calendar access rights are given to the In these examples, full calendar access rights are given to the CAL-
OWNER(), and a hypothetical administrator is given access rights to OWNERS(), and a hypothetical administrator is given access rights to
specify calendar access rights. If no other rights are specified, specify calendar access rights. If no other rights are specified,
only these two UPNs can specify calendar access rights: only these two UPNs can specify calendar access rights:
BEGIN:VCAR BEGIN:VCAR
CARID:some-id-3 CARID:some-id-3
NAME:Only OWNER or ADMIN Settable VCARs NAME:Only OWNER or ADMIN Settable VCARs
BEGIN:VRIGHT BEGIN:VRIGHT
GRANT:OWNER() GRANT:CAL-OWNERS()
PERMISSION:* PERMISSION:*
SCOPE:SELECT * FROM VAGENDA SCOPE:SELECT * FROM VAGENDA
END:VRIGHT END:VRIGHT
BEGIN:VRIGHT BEGIN:VRIGHT
GRANT:cal-admin@example.com GRANT:cal-admin@example.com
PERMISSION:* PERMISSION:*
SCOPE:SELECT * FROM VCAR SCOPE:SELECT * FROM VCAR
RESTRICTION:SELECT * FROM VCAR RESTRICTION:SELECT * FROM VCAR
END:VRIGHT END:VRIGHT
END:VCAR END:VCAR
In this example, rights to write, read, modify or delete calendar In this example, rights to write, search, modify or delete calendar
access rights are denied to all UPNs. This example would disable access rights are denied to all UPNs. This example would disable
providing different access rights to the calendar store or calendar. providing different access rights to the calendar store or calendar.
This calendar access right should be specified with great care, as it This calendar access right should be specified with great care, as it
removes the ability to change calendar access; even for the owner or removes the ability to change calendar access; even for the owner or
administrator. It could be used by small devices that do not support administrator. It could be used by small devices that do not support
the changing of any VCAR: the changing of any VCAR:
BEGIN:VCAR BEGIN:VCAR
CARID:VeryRestrictiveVCAR-2 CARID:VeryRestrictiveVCAR-2
NAME:No CAR At All NAME:No CAR At All
BEGIN:VRIGHT BEGIN:VRIGHT
DENY:* DENY:*
PERMISSION:* PERMISSION:*
SCOPE:SELECT * FROM VCAR SCOPE:SELECT * FROM VCAR
END:VRIGHT END:VRIGHT
END:VCAR END:VCAR
8.4 VRIGHT Component 9.4 VRIGHT Component
Component Name: "VRIGHT" Component Name: "VRIGHT"
Purpose: Provide a grouping of properties that describe an access Purpose: Provide a grouping of properties that describe an access
right (granted or denied). right (granted or denied).
Format Definition: A "VRIGHT" component is defined by the following Formal Definition: A "VRIGHT" component is defined by the following
notation: notation:
rightc = "BEGIN" ":" "VRIGHT" CRLF rightc = "BEGIN" ":" "VRIGHT" CRLF
rightprop rightprop
"END" ":" "VRIGHT" CRLF "END" ":" "VRIGHT" CRLF
rightprop = 2*( rightprop = 2*(
; either 'grant' or 'deny' MUST ; either 'grant' or 'deny' MUST
; occur at least once ; occur at least once
skipping to change at page 82, line 14 skipping to change at page 85, line 14
Description: A "VRIGHT" component is a grouping of calendar access Description: A "VRIGHT" component is a grouping of calendar access
right properties. right properties.
The "GRANT" property specifies the UPN that is being granted access. The "GRANT" property specifies the UPN that is being granted access.
The "DENY" property specifies the UPN is being denied access. The The "DENY" property specifies the UPN is being denied access. The
"PERMISSION" property specifies the actual permission being set. The "PERMISSION" property specifies the actual permission being set. The
"SCOPE" property identifies the calendar store properties, calendar "SCOPE" property identifies the calendar store properties, calendar
properties, components, or properties to which the access right properties, components, or properties to which the access right
applies. The "RESTRICTION" property specifies restriction on the applies. The "RESTRICTION" property specifies restriction on the
value that may take calendar store properties, calendar properties, value that may take calendar store properties, calendar properties,
calendar components, and properties after a CREATE or MODIFY calendar components, and properties after a "CREATE" or "MODIFY"
operation. Values MUST match all the instances of the RESTRICTION command. Values MUST match all the instances of the "RESTRICTION"
property to be valid. property to be valid.
8.5 VREPLY Component 9.5 VREPLY Component
Component Name: "VREPLY" Component Name: "VREPLY"
Purpose: Provide a grouping of arbitrary properties and components Purpose: Provide a grouping of arbitrary properties and components
that are the data set result from an issued command. that are the data set result from an issued command.
Format Definition: A "VREPLY" component is defined by the following Formal Definition: A "VREPLY" component is defined by the following
notation: notation:
replyc = "BEGIN" ":" "VREPLY" CRLF replyc = "BEGIN" ":" "VREPLY" CRLF
any-prop-or-comp any-prop-or-comp
"END" ":" "VREPLY" CRLF "END" ":" "VREPLY" CRLF
any-prop-or-comp = ; Zero or more iana or experimental any-prop-or-comp = ; Zero or more iana or experimental
; properties and components, in any order. ; properties and components, in any order.
Description: Provide a grouping of arbitrary properties and Description: Provide a grouping of arbitrary properties and
components that are the data set result from an issued command. components that are the data set result from an issued command.
A query can return a predictable set of arbitrary properties and A query can return a predictable set of arbitrary properties and
components. This container is used by query and other commands to components. This component is used by query and other commands to
return data that does not fit into any other container. It may return data that does not fit into any other component. It may
contain any valid property or component, even if they are not contain any valid property or component, even if they are not
registered. registered.
8.6 VQUERY Component 9.6 VQUERY Component
Component Name: VQUERY Component Name: VQUERY
Purpose: A container to specify what is to be fetched from a CS. Purpose: A component to specify what is to be fetched from a CS.
Format Definition: A "VQUERY" component is defined by the following Formal Definition: A "VQUERY" component is defined by the following
notation: notation:
queryc = "BEGIN" ":" "VQUERY" CRLF queryc = "BEGIN" ":" "VQUERY" CRLF
queryprop queryprop
"END" ":" "VCAR" CRLF "END" ":" "VCAR" CRLF
queryprop = 1*( queryprop = 1*(
; 'queryid' is OPTIONAL but MUST NOT occur ; 'queryid' is OPTIONAL but MUST NOT occur
; more than once ; more than once. If the "TARGET" property
; is supplied then the "QUERYID" property
; MUST BE supplied.
; ;
queryid queryid / target
; the following are OPTIONAL, and MAY occur ; the following are OPTIONAL, and MAY occur
; more than once ; more than once
; ;
/ name / x-prop / iana-prop / name / x-prop / iana-prop
; the following MUST occur at least once. ; the following MUST occur at least once.
; ;
/ query / query
) )
Description: A "VQUERY" contains properties that specify which Description: A "VQUERY" contains properties that specify which
properties and components the CS is requested to return during a properties and components the CS is requested to return during a
SEARCH command. SEARCH command.
The "QUERYID" property specifies the local identifier for a stored The "QUERYID" property specifies the local identifier for a stored
"VQUERY" component. The "NAME" property specifies a localizeable "VQUERY" component. The "NAME" property specifies a localizable
display name of a stored "VQUERY" component. Normally "NAME" and display name of a stored "VQUERY" component. Normally "NAME" and
"QUERYID" are used when looking for a correct stored "VQUERY" "QUERYID" properties are used when looking for a correct stored
component, or when storing a "VQUERY" component. "VQUERY" component, or when storing a "VQUERY" component.
For a search, if the "TARGET" property is supplied in a "VQUERY"
component, then the CS is to search for the query in the calid
supplied by the "TARGET" property value.
For a create the "TARGET" property MUST NOT be supplied as the
destination container is already supplied in the "TARGET" property of
the "VCALENDAR" component.
For examples, see Section 6.1.1. For examples, see Section 6.1.1.
9. Commands and Responses 10. Commands and Responses
CAP commands and responses are described in this section. CAP commands and responses are described in this section.
9.1 CAP Commands (CMD) 10.1 CAP Commands (CMD)
All commands are send using the CMD property. All commands are send using the CMD property.
Property Name: CMD Property Name: CMD
Purpose: The property defines the command to be sent. Purpose: The property defines the command to be sent.
Value Type: TEXT Value Type: TEXT
Property Parameters: Non-standard, id, localize, latency, action or Property Parameters: Non-standard, id, localize, latency, action or
options. options.
Conformance: This property is the method used to specify the commands Conformance: This property is the method used to specify the commands
to a CS and can exist in any object sent to the CS. to a CS and can exist in any object sent to the CS.
Description: All of the command to the CS are supplied in this Description: All of the command to the CS are supplied in this
property. The OPTIONS parameter is overloaded and its meaning is property. The "OPTIONS" parameter is overloaded and its meaning is
dependent on the CMD value supplied. dependent on the CMD value supplied.
Format Definition: The property is defined by the following notation: Formal Definition: The property is defined by the following notation:
cmd = "CMD" ( cmd = "CMD" (
/ abort-cmd / abort-cmd
/ continue-cmd / continue-cmd
/ create-cmd / create-cmd
/ delete-cmd / delete-cmd
/ generate-uid-cmd / generate-uid-cmd
/ get-capability-cmd / get-capability-cmd
/ identify-cmd / identify-cmd
/ modify-cmd / modify-cmd
skipping to change at page 85, line 40 skipping to change at page 88, line 40
; CMD value. See the specific CMDs below ; CMD value. See the specific CMDs below
; for the correct values to use for each ; for the correct values to use for each
; CMD. ; CMD.
option-value = paramtext option-value = paramtext
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 or denied for any commands. Calendar access rights can be granted or denied for any commands.
9.1.1 Bounded Latency 10.1.1 Bounded Latency
A CAP command can have an associated maximum latency time by A CAP command can have an associated maximum latency time by
specifying the "LATENCY" parameter. If the command is unable to be specifying the "LATENCY" parameter. If the command is unable to be
completed in the specified amount of time (as specified by the completed in the specified amount of time (as specified by the
"LATENCY" parameter value), then a "TIMEOUT" command MUST BE sent on "LATENCY" parameter value), then a "TIMEOUT" command MUST BE sent on
the same channel to which there MUST BE a an "ABORT" or a "CONTINUE" the same channel to which there MUST BE a an "ABORT" or a "CONTINUE"
command reply. If the CUA initiated the original command, then the command reply. If the CUA initiated the original command, then the
CS would issue the "TIMEOUT" command and the CUA would then have to CS would issue the "TIMEOUT" command and the CUA would then have to
issue an "ABORT" or "CONTINUE" command. If the CS initiated the issue an "ABORT" or "CONTINUE" command. If the CS initiated the
original command then the CUA would have to issue the "TIMEOUT" and original command then the CUA would have to issue the "TIMEOUT" and
skipping to change at page 86, line 21 skipping to change at page 89, line 21
Upon receiving a "CONTINUE" command the work continues. Note that a Upon receiving a "CONTINUE" command the work continues. Note that a
new latency time MAY BE included in a "CONTINUE" command indicating new latency time MAY BE included in a "CONTINUE" command indicating
to continue the original command until the "LATENCY" parameter value to continue the original command until the "LATENCY" parameter value
expires or the results of the original command can be returned. expires or the results of the original command can be returned.
Both the "LATENCY" parameter and the "ACTION" parameter MUST BE Both the "LATENCY" parameter and the "ACTION" parameter MUST BE
supplied to any "CMD" property, or nether can be added to the "CMD" supplied to any "CMD" property, or nether can be added to the "CMD"
property. The "LATENCY" parameter MUST BE set to the maximum latency property. The "LATENCY" parameter MUST BE set to the maximum latency
time in seconds. The "ACTION" parameter accepts the following time in seconds. The "ACTION" parameter accepts the following
values: "ASK" and "ABORT". values: "ASK" and "ABORT" parameters.
If the maximum latency time is exceeded and the "ACTION" parameter is If the maximum latency time is exceeded and the "ACTION" parameter is
set to the "ASK" value, then "TIMEOUT" command MUST BE sent. set to the "ASK" value, then "TIMEOUT" command MUST BE sent.
Otherwise if the "ACTION" parameter is set to the "ABORT" value then Otherwise if the "ACTION" parameter is set to the "ABORT" value then
the command MUST BE terminated and return a REQUEST-STATUS code of the command MUST BE terminated and return a REQUEST-STATUS code of
2.0.3 for the original command. 2.0.3 for the original command.
If a CS can both start sending the reply to a command and guarantee
that all of the results can be sent from a command (short of
something like network or power falure), prior to the "LATENCY"
timeout value, then the "LETENCY" time has not expired.
Example: Example:
In this example the initiator asks for the listeners capabilities. In this example the initiator asks for the listeners capabilities.
I: Content-Type: text/calendar I: Content-Type: text/calendar
I: I:
I: BEGIN:VCALENDAR I: BEGIN:VCALENDAR
I: VERSION:2.0 I: VERSION:2.0
I: PRODID:The CUA's PRODID I: PRODID:The CUA's PRODID
I: CMD;ID=xyz12346:GET-CAPABILITY I: CMD;ID=xyz12346;LATENCY=3;ACTION=ask:GET-CAPABILITY
I: END:VCALENDAR I: END:VCALENDAR
# After 3 seconds # After 3 seconds
L: Content-Type: text/calendar L: Content-Type: text/calendar
L: L:
L: BEGIN:VCALENDAR L: BEGIN:VCALENDAR
L: PRODID:-//someone's prodid
L: VERSION:2.0 L: VERSION:2.0
L: CMD;ID=xyz12346:TIMEOUT L: CMD;ID=xyz12346:TIMEOUT
L: END:VCALENDAR L: END:VCALENDAR
In order to continue and give the CS more time then the CUA would In order to continue and give the CS more time then the CUA would
issue a "CONTINUE" command: issue a "CONTINUE" command:
I: Content-Type: text/calendar I: Content-Type: text/calendar
I: I:
I: BEGIN:VCALENDAR I: BEGIN:VCALENDAR
I: VERSION:2.0 I: VERSION:2.0
I: PRODID:-//someone's prodid
I: CMD;ID=xyz12346;LATENCY=3;ACTION=ask:CONTINUE I: CMD;ID=xyz12346;LATENCY=3;ACTION=ask:CONTINUE
I: END:VCALENDAR I: END:VCALENDAR
L: Content-Type: text/calendar L: Content-Type: text/calendar
L: L:
L: BEGIN:VCALENDAR L: BEGIN:VCALENDAR
L: VERSION:2.0 L: VERSION:2.0
L: PRODID:-//someone's prodid
L: CMD;ID=xyz12346:REPLY L: CMD;ID=xyz12346:REPLY
L: BEGIN:VREPLY L: BEGIN:VREPLY
L: REQUEST-STATUS:2.0.3;Continued for 3 more seconds L: REQUEST-STATUS:2.0.3;Continued for 3 more seconds
L: END:VREPLY L: END:VREPLY
L: END:VCALENDAR L: END:VCALENDAR
To abort the command and not wait any further then issue an "ABORT" To abort the command and not wait any further then issue an "ABORT"
command: command:
I: Content-Type: text/calendar I: Content-Type: text/calendar
I: I:
I: BEGIN:VCALENDAR I: BEGIN:VCALENDAR
I: VERSION:2.0 I: VERSION:2.0
I: PRODID:-//someone's prodid
I: CMD;ID=xyz12346:ABORT I: CMD;ID=xyz12346:ABORT
I: END:VCALENDAR I: END:VCALENDAR
# Which would result in a 2.0.3 reply. # Which would result in a 2.0.3 reply.
L: Content-Type: text/calendar L: Content-Type: text/calendar
L: L:
L: BEGIN:VCALENDAR L: BEGIN:VCALENDAR
L: VERSION:2.0 L: VERSION:2.0
L: PRODID:-//someone's prodid
L: CMD;ID=xyz12346:REPLY L: CMD;ID=xyz12346:REPLY
L: BEGIN:VREPLY L: BEGIN:VREPLY
L: REQUEST-STATUS:2.0.3;Aborted As Requested. L: REQUEST-STATUS:2.0.3;Aborted As Requested.
L: END:VREPLY L: END:VREPLY
L: END:VCALENDAR L: END:VCALENDAR
9.1.2 ABORT Command 10.1.2 ABORT Command
CMD: ABORT CMD: ABORT
Purpose: The "ABORT" command is sent to request that the named or Purpose: The "ABORT" command is sent to request that the named or
only in process command be aborted. Latency MUST not be supplied only in process command be aborted. Latency MUST not be supplied
with the "ABORT" command. with the "ABORT" command.
Formal Definition: An "ABORT" command is defined by the following Formal Definition: An "ABORT" command is defined by the following
notation: notation:
skipping to change at page 88, line 45 skipping to change at page 92, line 34
abort-reply = "BEGIN" ":" "VCALENDAR" CRLF abort-reply = "BEGIN" ":" "VCALENDAR" CRLF
calprops calprops
abort-vreply abort-vreply
"END" ":" "VCALENDAR" CRLF "END" ":" "VCALENDAR" CRLF
abort-vreply = "BEGIN" ":" "VREPLY" CRLF abort-vreply = "BEGIN" ":" "VREPLY" CRLF
request-status request-status
*(x-prop) *(x-prop)
"END" ":" "VREPLY" CRLF "END" ":" "VREPLY" CRLF
9.1.3 CONTINUE Command 10.1.3 CONTINUE Command
CMD: CONTINUE CMD: CONTINUE
Purpose: The "CONTINUE" command is only sent after a "TIMEOUT" Purpose: The "CONTINUE" command is only sent after a "TIMEOUT"
command has been received to inform the other end of the session to command has been received to inform the other end of the session to
resume working on a command. resume working on a command.
Formal Definition: A "CONTINUE" command is defined by the following Formal Definition: A "CONTINUE" command is defined by the following
notation: notation:
continue-cmd = continueparam ":" "CONTINUE" continue-cmd = continueparam ":" "CONTINUE"
continueparam = *( continueparam = *(
skipping to change at page 90, line 5 skipping to change at page 93, line 37
continue-reply = "BEGIN" ":" "VCALENDAR" CRLF continue-reply = "BEGIN" ":" "VCALENDAR" CRLF
calprops calprops
continue-vreply continue-vreply
"END" ":" "VCALENDAR" CRLF "END" ":" "VCALENDAR" CRLF
continue-vreply = "BEGIN" ":" "VREPLY" CRLF continue-vreply = "BEGIN" ":" "VREPLY" CRLF
request-status request-status
*(x-prop) *(x-prop)
"END" ":" "VREPLY" CRLF "END" ":" "VREPLY" CRLF
9.1.4 CREATE Command 10.1.4 CREATE Command
CMD: CREATE CMD: CREATE
Purpose: The "CREATE" command is used to create one or more Purpose: The "CREATE" command is used to create one or more
iCalendar objects in the store in the "BOOKED" or "UNPROCESSED" iCalendar objects in the store in the "BOOKED" or "UNPROCESSED"
state. state.
A CUA MAY send a CREATE command to a CS. The CREATE command MUST BE A CUA MAY send a "CREATE" command to a CS. The "CREATE" command MUST
implemented by all CSs. BE implemented by all CSs.
The CS MUST NOT send a CREATE command to any CUA. The CS MUST NOT send a "CREATE" command to any CUA.
Formal Definition: A "CREATE" command is defined by the following Formal Definition: A "CREATE" command is defined by the following
notation: notation:
create-cmd = createparam ":" "CREATE" create-cmd = createparam ":" "CREATE"
createparam = *( createparam = *(
; the following are optional, ; the following are optional,
; but MUST NOT occur more than once ; but MUST NOT occur more than once
id-param id-param
/ localize-param / localize-param
/ latency-param / latency-param
; the following MUST occur exactly once and only ; the following MUST occur exactly once and only
; when the latency-param has been supplied and ; when the latency-param has been supplied and
; MUST NOT be supplied if the latency-param is ; MUST NOT be supplied if the latency-param is
; not supplied. ; not supplied.
n
/ action-param / action-param
; the following is optional, ; the following is optional,
; and MAY occur more than once ; and MAY occur more than once
/ (";" xparam) / (";" xparam)
) )
Response: Response:
One iCalendar object per TARGET property MUST BE One iCalendar object per TARGET property MUST BE returned.
returned.
The REPLY of any "CREATE" command is: The REPLY of any "CREATE" command is:
Restriction Table for the iCalendar section of a reply that contains
an iCalendar object is any valid [iTIP] response plus any from this
restriction table:
create-reply = "BEGIN" ":" "VCALENDAR" CRLF create-reply = "BEGIN" ":" "VCALENDAR" CRLF
calprops calprops
1*(create-vreply) 1*(create-vreply)
"END" ":" "VCALENDAR" CRLF "END" ":" "VCALENDAR" CRLF
create-vreply = "BEGIN" ":" "VREPLY" CRLF create-vreply = "BEGIN" ":" "VREPLY" CRLF
created-id created-id
request-status request-status
*(x-prop) *(x-prop)
"END" ":" "VREPLY" CRLF "END" ":" "VREPLY" CRLF
; Where the id is appropriate for the ; Where the id is appropriate for the
; type of object created: ; type of object created:
; ;
; VAGENDA = calid ; VAGENDA = calid
; VCAR = carid ; VCAR = carid
; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid
; VQUERY = queryid ; VQUERY = queryid
; ALARM = sequence
; x-component = x-id ; x-component = x-id
; ;
created-id = ( calid / carid / uid / uid dtstamp created-id = ( calid / carid / uid / queryid /
/ queryid / tzid / sequence / x-id) tzid / sequence / x-id)
The TARGET property specify the containers where the component(s)
will be created. This can be a CSID, or a CALID.
The iCalendar portion of the command can be any valid [iTIP] object The "TARGET" property specifies the containers where the component(s)
or any valid CAP object using the following restriction table. There will be created. This can be a "CSID", or a "CALID" value type.
MUST BE at least one component inside of the VCALENDAR object.
If the iCalendar object being created does not have a "METHOD" If the iCalendar object being created does not have a "METHOD"
property, then is not an iTIP object, then its state will be property, then is not an [iTIP] object, then its state will be
"BOOKED". Use the "DELETE" command to set the state of an object to "BOOKED". Use the "DELETE" command to set the state of an object to
the "DELETED" state. A CUA can not use the "CREATE" command to the "DELETED" state. A CUA can not use the "CREATE" command to
create an object in the "DELETED" state. create an object in the "DELETED" state.
If an iTIP object is being booked, then the "METHOD" property MUST If an [iTIP] object is being booked, then the "METHOD" property MUST
NOT BE supplied". Otherwise any iTIP object MUST BE have valid iTIP NOT BE supplied". Otherwise any [iTIP] object MUST have a valid
METHOD value and it is a scheduling request being deposited into the [iTIP] "METHOD" property value and it is a scheduling request being
CS and will have its state set to "UNPROCESSED". deposited into the CS and will have its state set to "UNPROCESSED"
state.
Restriction table for the CREATE command: Restriction table for the "CREATE" command:
create-minumum = "BEGIN" ":" "VCALENDAR" CRLF create-minimum = "BEGIN" ":" "VCALENDAR" CRLF
calprops calprops
*(iana-prop) *(iana-prop)
*(x-prop) *(x-prop)
1*(create-comp) 1*(create-comp)
"END" ":" "VCALENDAR" CRLF "END" ":" "VCALENDAR" CRLF
; If The following contain the "METHOD" ; If The following contain the "METHOD"
; property they MUST conform to [iTIP]. ; property they MUST conform to [iTIP].
; ;
create-comp = agendac / carc / queryc create-comp = agendac / carc / queryc
/ timezonec / freebusyc / timezonec / freebusyc
/ eventc / todoc / journalc / eventc / todoc / journalc
/ iana-component / x-component / iana-comp / x-component
Restriction Table for the iCalendar section of a reply that contains
an iCalendar object is any valid [iTIP] response plus any from this
restriction table:
create-reply = "BEGIN" ":" "VCALENDAR" CRLF
calprops
*(iana-prop)
*(x-prop)
1*(create-comp-vreply)
"END" ":" "VCALENDAR" CRLF
create-vreply = "BEGIN" ":" "VREPLY" CRLF
created-id
request-status
"END" ":" "VREPLY" CRLF
; Where the id is appropriate for the
; type of object created:
;
; VAGENDA = calid
; VCAR = carid
; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid
; VQUERY = queryid
; ALARM = sequence
; x-component = x-id
;
created-id = ( calid / carid / uid / uid dtstamp
/ queryid / tzid / sequence / x-id)
In the following example, two new top level VAGENDAs are created.
Note that the CSID of the server is cal.example.com which is where In the following example, two new top level "VAGENDA" components are
the new VAGENDAs are going to be created. created. Note that the "CSID" value of the server is
cal.example.com which is where the new "VAGENDA" components are
going to be created.
C: Content-Type: text/calendar C: Content-Type: text/calendar
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: PRODID:-//someone's prodid
C: VERSION:2.0 C: VERSION:2.0
C: CMD;ID=creation01:CREATE C: CMD;ID=creation01:CREATE
C: TARGET:cal.example.com C: TARGET:cal.example.com
C: BEGIN:VAGENDA <- data for 1st new calendar C: BEGIN:VAGENDA <- data for 1st new calendar
C: CALID:relcalz1 C: CALID: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/Pacific C: TZID:US/Pacific
C: END:VAGENDA C: END:VAGENDA
C: BEGIN:VAGENDA <- data for 2nd new calendar C: BEGIN:VAGENDA <- data for 2nd new calendar
C: CALID:relcalz2 C: CALID: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/Pacific C: TZID:US/Pacific
C: END:VAGENDA C: END:VAGENDA
C: END:VCALENDAR C: END:VCALENDAR
When there are multiple TARGET values in the original command object When there are multiple "TARGET" properties in the original command
then the replies MUST BE in the exact same order as they were object then the replies MUST BE in the exact same order as they were
provided to the CS. The same is true for the objects created, their provided to the CS. The same is true for the objects created, their
responses MUST BE in the exact same order as they were supplied to responses MUST BE in the exact same order as they were supplied to
the CS. the CS.
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.0 S: VERSION:2.0
S: PRODID:-//someone's prodid
S: CMD;ID=creation01:REPLY S: CMD;ID=creation01:REPLY
S: TARGET:cal.example.com S: TARGET:cal.example.com
S: BEGIN:REPLY <- Reply for 1st calendar create S: BEGIN:VREPLY <- Reply for 1st calendar create
S: CALID:relcalz1 S: CALID:relcalz1
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:REPLY S: END:REPLY
S: BEGIN:VREPLY <- Reply for 2nd calendar create S: BEGIN:VREPLY <- Reply for 2nd calendar create
S: CALID:relcalz2 S: CALID:relcalz2
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VREPLY S: END:VREPLY
S: END:VCALENDAR S: END:VCALENDAR
To create a new component in multiple containers simply name all of To create a new component in multiple containers simply name all of
the containers in the TARGET in the create command. Here a new 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 "VEVENT" component is created in two TARGET components. In this
new iTIP REQUEST object in two calendars. The results would be example, the "VEVENT" component is one new [iTIP] "REQUEST" to be
iCalendar object that conform to the iTIP replies as defined in iTIP. stored in two calendars. The results would be iCalendar objects that
conform to the [iTIP] replies as defined in [iTIP].
The "VREPLY" components MUST always be returned in the same order The "VREPLY" components MUST always be returned in the same order
that the objects were listed in the original "CREATE" command. If that the objects were listed in the original "CREATE" command. If
there are multiple "TARGET" and components in the same create command there are multiple "TARGET" properties and components in the same
then the reply is first listed by the "TARGET" order of the original create command then the reply is first listed by the "TARGET" order
create command, then component replies within that "TARGET" are of the original create command, then component replies within that
ordered the same as in the original create command. "TARGET" are ordered the same as in the original create command.
This example shows two VEVENTs being created in each of two TARGETs: This example shows two "VEVENT" components being created in each of
the two supplied "TARGET" properties:
C: Content-Type: text/calendar C: Content-Type: text/calendar
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: VERSION:2.0 C: VERSION:2.0
C: PRODID:-//someone's prodid
C: CMD;ID=creation02:CREATE C: CMD;ID=creation02:CREATE
C: METHOD:REQUEST C: METHOD:REQUEST
C: TARGET:relcalz1 C: TARGET:relcalz1
C: TARGET:relcalz2 C: TARGET:relcalz2
C: BEGIN:VEVENT C: BEGIN:VEVENT
C: DTSTART:20030307T180000Z C: DTSTART:20030307T180000Z
C: UID:FirstInThisExample-1 C: UID:FirstInThisExample-1
C: DTEND:20030307T190000Z C: DTEND:20030307T190000Z
C: SUMMARY:Important Meeting C: SUMMARY:Important Meeting
C: END:VEVENT C: END:VEVENT
C: BEGIN:VEVENT C: BEGIN:VEVENT
C: DTSTART:20040307T180000Z C: DTSTART:20040307T180000Z
C: UID:SecondInThisExample-2 C: UID:SecondInThisExample-2
C: DTEND:20040307T190000Z C: DTEND:20040307T190000Z
C: SUMMARY:Important Meeting C: SUMMARY:Important Meeting
C: END:VEVENT C: END:VEVENT
C: END:VCALENDAR C: END:VCALENDAR
The CS would sends the REPLY in separate MIME objects, one per The CS could send the "VREPLY" commands in separate MIME objects, one
TARGET. per supplied "TARGET" property value.
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.0 S: VERSION:2.0
S: PRODID:-//someone's prodid
S: CMD;ID=creation02:REPLY S: CMD;ID=creation02:REPLY
S: TARGET:relcalz1 <- 1st TARGET listed S: TARGET:relcalz1 <- 1st TARGET listed
S: BEGIN:REPLY <- Reply for 1st VEVENT create in 1st TARGET. S: BEGIN:REPLY <- Reply for 1st VEVENT create in 1st TARGET.
S: UID:FirstInThisExample-1 S: UID:FirstInThisExample-1
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VREPLY S: END:VREPLY
S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 1st TARGET. S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 1st TARGET.
S: UID:SecondInThisExample-2 S: UID:SecondInThisExample-2
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VREPLY S: END:VREPLY
S: END:VCALENDAR S: END:VCALENDAR
And would send the second part of the reply later: And could send the second part of the reply later:
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.0 S: VERSION:2.0
S: PRODID:-//someone's prodid
S: CMD;ID=creation02:REPLY S: CMD;ID=creation02:REPLY
S: TARGET:relcalz2 <- 2nd TARGET listed S: TARGET:relcalz2 <- 2nd TARGET listed
S: BEGIN:REPLY <- Reply for 1st VEVENT create in 2nd TARGET. S: BEGIN:REPLY <- Reply for 1st VEVENT create in 2nd TARGET.
S: UID:FirstInThisExample-1 S: UID:FirstInThisExample-1
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VREPLY S: END:VREPLY
S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 2nd TARGET. S: BEGIN:REPLY <- Reply for 2nd VEVENT crate in 2nd TARGET.
S: UID:SecondInThisExample-2 S: UID:SecondInThisExample-2
S: REQUEST-STATUS:2.0 S: REQUEST-STATUS:2.0
S: END:VREPLY S: END:VREPLY
S: END:VCALENDAR S: END:VCALENDAR
9.1.5 DELETE Command 10.1.5 DELETE Command
CMD: DELETE CMD: DELETE
Purpose: The DELETE command physically removes the QUERY result from Purpose: The "DELETE" command physically removes the QUERY result
the store or marks it for deletion. from the store or marks it for deletion.
A CUA MAY send a DELETE command to a CS. The DELETE command MUST BE A CUA MAY send a "DELETE" command to a CS. The "DELETE" command MUST
implemented by all CSs. BE implemented by all CSs.
The CS MUST NOT send a DELETE command to any CUA. The CS MUST NOT send a "DELETE" command to any CUA.
Formal Definition: A "DELETE" command is defined by the following Formal Definition: A "DELETE" command is defined by the following
notation: notation:
delete-cmd = deleteparam ":" "DELETE" delete-cmd = deleteparam ":" "DELETE"
deleteparam = *( deleteparam = *(
; the following are optional, ; the following are optional,
; but MUST NOT occur more than once ; but MUST NOT occur more than once
skipping to change at page 97, line 31 skipping to change at page 100, line 31
/ action-param / action-param
; the following is optional, ; the following is optional,
; and MAY occur more than once ; and MAY occur more than once
/ (";" xparam) / (";" xparam)
) )
The DELETE command is used to delete calendars or components. The The "DELETE" command is used to delete calendars or components. The
included "VQUERY" component(s) specifies the container(s) to delete. included "VQUERY" component(s) specifies the container(s) to delete.
If a component is to be marked for delete and not physically removed, If a component is to be marked for delete and not physically removed,
then include the "OPTIONS" parameter with its value set to "MARK" to then include the "OPTIONS" parameter with its value set to the "MARK"
alter its state to "DELETED". value in order to alter its state to "DELETED".
When components are deleted, only the top most component REQUEST- When components are deleted, only the top most component "REQUEST-
STATUS is returned. No REQUEST-STATUS is returned for components STATUS" properties are returned. No "REQUEST-STATUS" properties are
inside of the selected components. There MUST BE one "VREPLY" returned for components inside of the selected components. There
component returned for each object that is deleted or marked for MUST BE one "VREPLY" component returned for each object that is
delete. deleted or marked for delete.
Restriction Table for the REPLY of any DELETE command. Restriction Table for the "REPLY" command for any "DELETE" command.
delete-reply = "BEGIN" ":" "VCALENDAR" CRLF delete-reply = "BEGIN" ":" "VCALENDAR" CRLF
calprops calprops
1*(delete-vreply) 1*(delete-vreply)
"END" ":" "VCALENDAR" CRLF "END" ":" "VCALENDAR" CRLF
delete-vreply = "BEGIN" ":" "VREPLY" CRLF delete-vreply = "BEGIN" ":" "VREPLY" CRLF
deleted-id deleted-id
request-status request-status
"END" ":" "VREPLY" CRLF "END" ":" "VREPLY" CRLF
skipping to change at page 98, line 30 skipping to change at page 101, line 30
; VAGENDA = calid ; VAGENDA = calid
; VCAR = carid ; VCAR = carid
; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid ; VEVENT, VFREEBUSY, VJOURNAL, VTODO = uid
; VQUERY = queryid ; VQUERY = queryid
; ALARM = sequence ; ALARM = sequence
; x-component = x-id ; x-component = x-id
; ;
deleted-id = ( calid / carid / uid / uid dtstamp deleted-id = ( calid / carid / uid / uid dtstamp
/ queryid / tzid / sequence / x-id) / queryid / tzid / sequence / x-id)
Example to delete a VEVENT with VEVENT UID 'abcd12345' from the Example to delete a "VEVENT" component with "UID" value of
calendar "relcald-22" from the current CS: 'abcd12345' from the calendar "relcald-22" from the current CS:
C: Content-Type: text/calendar C: Content-Type: text/calendar
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: TARGET:relcalid-22 C: TARGET:relcalid-22
C: CMD;ID:"random but unique per CUA":DELETE C: CMD;ID:"random but unique per CUA":DELETE
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
skipping to change at page 99, line 25 skipping to change at page 102, line 25
S: BEGIN:VCALENAR S: BEGIN:VCALENAR
S: TARGET:relcalid-22 S: TARGET:relcalid-22
S: CMD;ID:"random but unique per CUA":REPLY S: CMD;ID:"random but unique per CUA":REPLY
S: BEGIN:VREPLY S: BEGIN:VREPLY
S: UID:abcd12345 S: UID:abcd12345
S: REQUEST-STATUS:3.0 S: REQUEST-STATUS:3.0
S: END:VREPLY S: END:VREPLY
S: END:VCALENDAR S: END:VCALENDAR
One or more iCalendar objects will be returned that contain a One or more iCalendar objects will be returned that contain a
REQUEST-STATUS for the deleted components. There could have been "REQUEST-STATUS" properties for the deleted components. There could
more than one component deleted, Any booked and any number of have been more than one component deleted, Any booked and any number
unprocessed iTIP scheduling components that matched the QUERY value of unprocessed [iTIP] scheduling components that matched the QUERY
in the above example. Each unique "METHOD" property value that was value in the above example. Each unique "METHOD" property value that
deleted from the store MUST BE in a separate iCalendar object. This was deleted from the store MUST BE in a separate iCalendar object.
is because only one "METHOD" property is allowed in a single This is because only one "METHOD" property is allowed in a single
"VCALENDAR" BEGIN/END block. "VCALENDAR" BEGIN/END block.
9.2 GENERATE-UID Command 10.2 GENERATE-UID Command
CMD: GENERATE-UID CMD: GENERATE-UID
Purpose: The GENERATE-UID command returns one or more unique Purpose: The "GENERATE-UID" command returns one or more unique
identifiers which MUST BE globally unique. identifiers which MUST BE globally unique.
The GENERATE-UID command MAY BE sent to any CS. The GENERATE-UID The "GENERATE-UID" command MAY BE sent to any CS. The "GENERATE-UID"
command MUST BE implemented by all CSs. command MUST BE implemented by all CSs.
The GENERATE-UID command MUST NOT be sent to a CUA. The "GENERATE-UID" command MUST NOT be sent to a CUA.
Formal Definition: A "GENERATE-UID" command is defined by the Formal Definition: A "GENERATE-UID" command is defined by the
following notation: following notation:
generate-uid-cmd = genuidparam ":" "GENERATE-UID" generate-uid-cmd = genuidparam ":" "GENERATE-UID"
genuidparam = *( genuidparam = *(
; The following are optional, ; The following are optional,
; but MUST NOT occur more than once. ; but MUST NOT occur more than once.
skipping to change at page 100, line 35 skipping to change at page 103, line 35
; be returned. ; be returned.
/ option-param integer / option-param integer
) )
Response: Response:
gen-reply = "BEGIN" ":" "VCALENDAR" CRLF gen-reply = "BEGIN" ":" "VCALENDAR" CRLF
calprops calprops
1*(delete-vreply) 1*(gen-vreply)
"END" ":" "VCALENDAR" CRLF "END" ":" "VCALENDAR" CRLF
gen-vreply = "BEGIN" ":" "VREPLY" CRLF gen-vreply = "BEGIN" ":" "VREPLY" CRLF
*(uid) *(uid)
request-status request-status
"END" ":" "VREPLY" CRLF "END" ":" "VREPLY" CRLF
Example: Example:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: VERSION:2.0 C: VERSION:2.0
C: PRODID:-//someone's prodid C: PRODID:-//someone's prodid
C: CMD;ID=unique-per-cua-124;OPTIONS=5:GENERATE-UID C: CMD;ID=unique-per-cua-124;OPTIONS=5:GENERATE-UID
C: END:VCALENDAR C: END:VCALENDAR
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.0 S: VERSION:2.0
S: PRODID:-//someone's prodid
S: CMD;ID=unique-per-cua-124:REPLY S: CMD;ID=unique-per-cua-124:REPLY
S: BEGIN:VREPLY S: BEGIN:VREPLY
S: UID:20011121T120000Z-12340@cal.example.com S: UID:20011121T120000Z-12340@cal.example.com
S: UID:20011121T120000Z-12341@cal.example.com S: UID:20011121T120000Z-12341@cal.example.com
S: UID:20011121T120000Z-12342@cal.example.com S: UID:20011121T120000Z-12342@cal.example.com
S: UID:20011121T120000Z-12343@cal.example.com S: UID:20011121T120000Z-12343@cal.example.com
S: UID:20011121T120000Z-12344@cal.example.com S: UID:20011121T120000Z-12344@cal.example.com
S: REQUEST-STATUS:2.0
S: END:VREPLY S: END:VREPLY
S: END:VCALENDAR S: END:VCALENDAR
9.3 GET-CAPABILITY Command 10.3 GET-CAPABILITY Command
CMD: GET-CAPABILITY CMD: GET-CAPABILITY
Purpose: The GET-CAPABILITY command returns the capabilities of the Purpose: The "GET-CAPABILITY" command returns the capabilities of the
other end of the session. other end of the session.
A CUA MAY send a GET-CAPABILITY command to a CS. The GET-CAPABILITY A CUA MUST send a "GET-CAPABILITY" command to a CS after the initial
command MUST BE implemented by all CSs. connection. The "GET-CAPABILITY" command MUST BE implemented by all
CSs.
The CS MAY send a GET-CAPABILITY command to any CUA. The GET- The CS MUST send a "GET-CAPABILITY" command to a CUA after the
CAPABILITY command MAY be implemented by a CUA. initial connection. The CUA MUST recogonize the "GET-CAPABILITY"
command and MAY return a not implemented reply meaning that the CUA
supports only the default capababilities.
Formal Definition: A "GET-CAPABILITY" command is defined by the Formal Definition: A "GET-CAPABILITY" command is defined by the
following notation: following notation:
get-capability-cmd = capibiltyparam ":" "GET-CAPABILITY" get-capability-cmd = capibiltyparam ":" "GET-CAPABILITY"
genuidparam = *( capibiltyparam = *(
; the following are optional, ; the following are optional,
; but MUST NOT occur more than once ; but MUST NOT occur more than once
;
id-param id-param / localize-param / latency-param
/ localize-param
/ latency-param
; the following MUST occur exactly once and only ; the following MUST occur exactly once and only
; when the latency-param has been supplied and ; when the latency-param has been supplied and
; MUST NOT be supplied if the latency-param is ; MUST NOT be supplied if the latency-param is
; not supplied. ; not supplied.
;
/ action-param / action-param
; the following is optional, ; the following is optional,
; and MAY occur more than once ; and MAY occur more than once
;
/ (";" xparam) / (";" xparam)
) )
Response: Response:
The GET-CAPABILITY command returns information about the Calendar The "GET-CAPABILITY" command returns information about the Calendar
other end of the session given the current state of the connection. other end of the session given the current state of the connection.
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 beyond those defined in this specification, and MAY ignore any
nonstandard, experimental capability elements. The GET-CAPABILITY nonstandard, experimental capability elements. The "GET-CAPABILITY"
reply may return different results depending on the UPN and if the reply may return different results depending on the UPN and if the
UPN is authenticated. UPN is authenticated.
The following CS properties are returned in response to a GET- When sending a reply to a "GET-CAPABILITY" command, all of these MUST
CAPABILITY command: BE supplied. If the CUA does not support sending a full reply and
sends not-implemented error, then the CS MUST assume the CUA supports
the default values as defined below. A CS MUST always send the full
reply when queried.
When the CUA does not support sending a "GET-CAPABILITY" reply, then
the CS MUST assume the defaults listed below. The following
properties are returned in response to a "GET-CAPABILITY" command:
Name Occurs Description Name Occurs Description
------------------------------------------------------------------ ------------------------------------------------------------------
CAP-VERSION 1 Version of CAP. MUST include at least "1.0" for CAP-VERSION 1 Version of CAP. It MUST include at least "1.0"
this version of CAP. Like the "VERSION" property, for this version of CAP. Like the "VERSION"
it may have a range. Uses the exact same property, it may have a range. Uses the exact
syntax as the "VERSION" property value. same syntax as the "VERSION" property value.
The default is "1.0".
PRODID 1 The product id of the CS. If supplied
in the "VCALENDAR" component, the values
MUST BE identical when originated from the CS.
QUERY-LEVEL 1 Indicates level of SQL support. CAL-QL-1 or NONE.
(NONE is for 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-LEVEL 1 Indicates level of CAR support. CAR-NONE, CAR-LEVEL 1 Indicates level of CAR support. CAR-NONE,
CAR-MIN or CAR-FULL-1. If CAR-FULL-1 is CAR-MIN or CAR-FULL-1. If CAR-FULL-1 is
supplied then CAR-MIN MUST BE assumed. supplied then CAR-MIN MUST BE assumed.
CAR = NONE MUST BE used when query-level A CAR-MIN implementation only supports
of NONE is supplied. A CAR-MIN implementation the DEFAULT-VCARS listed in the VCALSTORE
only supports the DEFAULT-VCARS listed in and does not support the creation or
the VCALSTORE and does not support the modification of VCARS.
creation or modification of VCARS. The default is CAR-NONE.
COMPONENTS 1 A comma separated list of the names of
components that are supported. This
includes any components inside of
other components (VALARM for example).
It MUST include at least VCALSTORE, VCALENDAR,
VREPLY, and VAGENDA and at least one of VEVENT,
VTODO, VTIMEZONE, or VJOURNAL. The defalt
is "VCALSTORE,VCALENDAR,VREPLY,VAGENDA,
VEVENT,VALARM,VTIMEZONE,VJOURNAL,VTODO,
DAYLIGHT,STANDARD"
STORES-EXPANDED
1 If TRUE then it expands multiple instances
separately when they are stored (RRULEs
converted to RDATEs) and when sent. If
FALSE then it expands instances dynamically
during sending. Default is FALSE.
DATE-MAX 1 The datetime value in UTC beyond which the DATE-MAX 1 The datetime value in UTC beyond which the
server cannot accept. The maximum value server cannot accept. The default and and
allowed is 99991231T235959Z. maximum value allowed is 99991231T235959Z.
DATE-MIN 1 The datetime value in UTC prior to which DATE-MIN 1 The datetime value in UTC prior to which
the server cannot accept. The minimum value the server cannot accept. The default and
allowed is 00000101T000000Z. minimum value allowed is 00000101T000000Z.
ITIP-VERSION 1 Version(s) of ITIP, it MUST include at least
the default value of "2446" to specify
RFC-2446 support. Comma separated list.
MAX-COMPONENT-SIZE MAX-COMPONENT-SIZE
1 A positive integer value that specifies 1 A positive integer value that specifies
the size of the largest iCalendar the size of the largest iCalendar object
object that the server will accept in that can be accepted in octets. Objects
octets. Objects larger than this will be larger than this will be rejected. A
rejected. The absence of this attribute default value of zero (0) means no limit.
indicates no limit. This is also the This is also the maximum value of any BEEP
maximum value of any BEEP payload payload that will be accepted or sent.
the CS will accept or send.
COMPONENTS 1 A comma separated list of the names of MULTIPART 1 A comma separated list of MIME multipart
components that this CS supports. This the sender supports in lower case. The
includes any components inside of default is no multipart support (empty
other components (VALARM for example). list). Example: MULTIPART:related,alternate
MUST include at least VCALSTORE, VCALENDAR,
VREPLY, and VAGENDA and at least one of VEVENT,
VTODO, VTIMEZONE, or VJOURNAL.
VERSION 1 Versions of iCalendar support. MUST BE at PRODID 1 The product id. If supplied in the "VCALENDAR"
least "2.0". This is the same property as components, the values MUST BE identical to
defined in [iCAL]. what is sent in the "GET-CAPABILITY" reply
from the CUA or CS. The CUA and CS PRODID
values may differ from each other.
RECUR-ACCEPTED 1 Whether the CS accepts recurrence rules. QUERY-LEVEL 1 Indicates level of SQL support. The default
TRUE or FALSE. is CAL-QL-1 and CAL-QL-NONE can be supplied.
(CAL-QL-NONE is for CS's that allow ITIP
methods only to be deposited and nothing else).
The default value is CAL-QL-1.
RECUR-EXPAND 1 Whether or not the CS supports the expansion RECUR-ACCEPTED 1 Whether recurrence rules are acceptable.
of recurrence rules. TRUE or FALSE TRUE (default) or FALSE.
RECUR-LIMIT 1 The maximum number of occurrences or a RECUR-EXPAND 1 Whether or not it supports the expansion
recurrence rule that are expanded by the CS. of recurrence rules. TRUE (default) or FALSE.
Zero means unlimited.
CS-STORES-EXPANDED RECUR-LIMIT 1 The maximum number of occurrences of a
1 If TRUE then the CS expands and stores multiple recurrence rule that are expanded.
instances separately when they are booked. The default of Zero (0) means unlimited.
If FALSE then the CS expands instances dynamically
during query.
ITIP-VERSION 1 Version(s) of ITIP, MUST include at least "2447" VERSION 1 Versions of iCalendar support. MUST BE at
to specify RFC-2447 support. Comma separated list. least "2.0" (the default). This is the same
property as defined in [iCAL].
X-... 0+ May include zero or more experimental properties. RECUR-ACCEPTED 1 Whether recurrence rules are acceptable.
The default is TRUE.
X-... 0+ May include zero or more experimental
properties. These have no default and
if need to be sent by an implementation,
then all of the above MUST BE sent.
------------------------------------------------------- -------------------------------------------------------
Example: Example:
I: Content-Type: text/calendar I: Content-Type: text/calendar
I: I:
I: BEGIN:VCALENDAR I: BEGIN:VCALENDAR
I: VERSION:2.0 I: VERSION:2.0
I: PRODID:The CUA's PRODID I: PRODID:-//someone's prodid
I: CMD;ID=unique-per-cua-125:GET-CAPABILITY I: CMD;ID=unique-per-cua-125:GET-CAPABILITY
I: END:VCALENDAR I: END:VCALENDAR
L: Content-Type: text/calendar L: Content-Type: text/calendar
L: L:
L: BEGIN:VCALENDAR L: BEGIN:VCALENDAR
L: VERSION:2.0 L: VERSION:2.0
L: PRODID:-//someone's prodid
L: CMD;ID=unique-per-cua-125:REPLY L: CMD;ID=unique-per-cua-125:REPLY
L: BEGIN:VREPLY L: BEGIN:VREPLY
L: CAP-VERSION:1.0 L: CAP-VERSION:1.0
L: PRODID:The CS prodid L: PRODID:The CS prodid
L: QUERY-LEVEL:CAL-QL-1 L: QUERY-LEVEL:CAL-QL-1
L: CAR-LEVEL:CAR-FULL-1 L: CAR-LEVEL:CAR-FULL-1
L: DATE-MAX:99991231T235959Z L: DATE-MAX:99991231T235959Z
L: DATE-MIN:00000101T000000Z L: DATE-MIN:00000101T000000Z
L: MAX-COMPONENT-SIZE:0 L: MAX-COMPONENT-SIZE:0
L: COMPONENTS:VCALENDAR,VTODO,VJOURNAL,VEVENT,VCAR, L: COMPONENTS:VCALENDAR,VTODO,VJOURNAL,VEVENT,VCAR,
L: VALARM,VFREEBUSY,VTIMEZONE,STANDARD,DAYLIGHT,VREPLY L: VALARM,VFREEBUSY,VTIMEZONE,STANDARD,DAYLIGHT,VREPLY
L: ITIP-VERSION:2447 L: ITIP-VERSION:2447
L: RECUR-ACCEPTED:TRUE L: RECUR-ACCEPTED:TRUE
L: RECUR-EXPAND:TRUE L: RECUR-EXPAND:TRUE
L: RECUR-LIMIT:0 L: RECUR-LIMIT:0
L: CS-STORES-EXPANDED:FALSE L: STORES-EXPANDED:FALSE
L: X-INET-PRIVATE-COMMANDS:1.0 L: X-INET-PRIVATE-COMMANDS:1.0
L: END:VREPLY L: END:VREPLY
L: END:VCALENDAR L: END:VCALENDAR
9.4 IDENTIFY Command 10.4 IDENTIFY Command
CMD: IDENTIFY CMD: IDENTIFY
Purpose: The IDENTIFY command allows the CUA to set a new identity to Purpose: The "IDENTIFY" command allows the CUA to set a new identity
be used for calendar access. to be used for calendar access.
A CUA MAY send an IDENTIFY command to a CS. The IDENTIFY command A CUA MAY send an "IDENTIFY" command to a CS. The "IDENTIFY" command
MUST BE implemented by all CSs. A CS implementation MAY reject all MUST BE implemented by all CSs. A CS implementation MAY reject all
IDENTIFY commands. "IDENTIFY" commands.
The CS MUST NOT send a IDENTIFY command to any CUA. The CS MUST NOT send a "IDENTIFY" command to any CUA.
Formal Definition: A "IDENTIFY" command is defined by the following Formal Definition: A "IDENTIFY" command is defined by the following
notation: notation:
identify-cmd = identifyparam ":" "IDENTIFY" identify-cmd = identifyparam ":" "IDENTIFY"
identifyparam = *( identifyparam = *(
; the following are optional, ; the following are optional,
; but MUST NOT occur more than once ; but MUST NOT occur more than once
skipping to change at page 107, line 17 skipping to change at page 110, line 24
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: VERSION:2.0 C: VERSION:2.0
C: PRODID:-//someone's prodid C: PRODID:-//someone's prodid
C: CMD;ID=unique-per-cua-999;OPTIONS=newUserId:IDENTIFY C: CMD;ID=unique-per-cua-999;OPTIONS=newUserId:IDENTIFY
C: END:VCALENDAR C: END:VCALENDAR
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: VERSION:2.0 S: VERSION:2.0
S: PRODID:-//someone's prodid
S: REQUEST-STATUS:2.0;Request Approved S: REQUEST-STATUS:2.0;Request Approved
S: END:VCALENDAR S: END:VCALENDAR
Or if denied: Or if denied:
S: Content-Type: text/calendar S: Content-Type: text/calendar
S: S:
S: BEGIN:VCALENDAR S: BEGIN:VCALENDAR
S: PRODID:-//someone's prodid
S: VERSION:2.0 S: VERSION:2.0
S: REQUEST-STATUS:6.4;Request Denied S: REQUEST-STATUS:6.4;Request Denied
S: END:VCALENDAR S: END:VCALENDAR
And for the CUA to return to its original authenticated identity And for the CUA to return to its original authenticated identity
the OPTIONS parameter is omitted: the OPTIONS parameter is omitted:
C: Content-Type: text/calendar C: Content-Type: text/calendar
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: VERSION:2.0 C: VERSION:2.0
C: PRODID:-//someone's prodid C: PRODID:-//someone's prodid
C: CMD;ID=unique-per-cua-995:IDENTIFY C: CMD;ID=unique-per-cua-995:IDENTIFY
C: END:VCALENDAR C: END:VCALENDAR
The CS may accept (2.0) or deny (6.4) the request to return to the The CS may accept (2.0) or deny (6.4) the request to return to the
original identity. original identity.
If a CS considers the IDENTIFY command an attempt to violate If a CS considers the "IDENTIFY" command an attempt to violate
security, the CS MAY terminate the BEEP session without any further security, the CS MAY terminate the BEEP session without any further
notice to the CUA after sending the REQUEST-STATUS 6.4 reply. notice to the CUA after sending the "REQUEST-STATUS" 6.4 reply.
9.5 MODIFY Command 10.5 MODIFY Command
CMD: MODIFY CMD: MODIFY
Purpose: The "MODIFY" command is used to modify existing components. Purpose: The "MODIFY" command is used to modify existing components.
A CUA MAY send a MODIFY command to a CS. The MODIFY command MUST BE A CUA MAY send a "MODIFY" command to a CS. The "MODIFY" command MUST
implemented by all CSs. BE implemented by all CSs.
The CS MUST NOT send a MODIFY command to any CUA. The CS MUST NOT send a "MODIFY" command to any CUA.
Formal Definition: A "MODIFY" command is defined by the following Formal Definition: A "MODIFY" command is defined by the following
notation: notation:
modify-cmd = modifyparam ":" "MODIFY" modify-cmd = modifyparam ":" "MODIFY"
modifyparam = *( modifyparam = *(
; the following are optional, ; the following are optional,
; but MUST NOT occur more than once ; but MUST NOT occur more than once
skipping to change at page 108, line 38 skipping to change at page 111, line 48
/ action-param / action-param
; the following is optional, ; the following is optional,
; and MAY occur more than once ; and MAY occur more than once
/ (";" xparam) / (";" xparam)
) )
Response:
The "MODIFY" command is used to modify existing components. The The "MODIFY" command is used to modify existing components. The
TARGET property specifies the calendars were the components exist TARGET property specifies the calendars where the components exist
that are going to be modified. that are going to be modified.
The format of the request is two containers inside of VCALENDAR The format of the request is two components inside of "VCALENDAR"
container object: component:
BEGIN:VCALENDAR BEGIN:VCALENDAR
... ...
BEGIN:VQUERY BEGIN:VQUERY
... ...
END:VQUERY END:VQUERY
BEGIN:XXX BEGIN:XXX
...old-values... ...old-values...
END:XXX END:XXX
BEGIN:XXX BEGIN:XXX
...new-values... ...new-values...
END:XXX END:XXX
END:CALENDAR END:CALENDAR
The VQUERY selects the components that are to be modified. The "VQUERY" component selects the components that are to be
modified.
Where "XXX" above is a named component type (VEVENT, VTODO, ...). Where "XXX" above is a named component type (VEVENT, VTODO, ...).
Both the old and new components MUST BE of the same type. Both the old and new components MUST BE of the same type.
The old-values is a component and the contents of that component are The old-values is a component and the contents of that component are
going to change and may contain information that helps uniquely going to change and may contain information that helps uniquely
identify the original component (SEQUENCE in the example below). If identify the original component (SEQUENCE in the example below). If
the CS can not find a component that matches the QUERY and does not 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. have at least all of the OLD-VALUES, then a 6.1 error is returned.
The new-values is a component of the same type as old-values and new- 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 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 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- selected component. Any values in new-values that was not in old-
values is added to the component. values is added to the component.
In this example the VEVENT with UID:unique-58 has; the LOCATION and In this example the "VEVENT" component with a "UID" property value of
LAST-MODIFIED changed, the VALARM with SEQUENCE:3 has its TRIGGER 'unique-58' has; the "LOCATION" property and "LAST-MODIFIED" property
disabled, the X-LOCAL property is removed from the VEVENT, and a changed, the "VALARM" component with the "SEQUENCE" property with a
COMMENT is added. value of "3" has its "TRIGGER" property disabled, the "X-LOCAL"
property is removed from the "VEVENT" component, and a "COMMENT"
property is added.
Because SEQUENCE is used to locate the VALARM in this example, both Because "SEQUENCE" property is used to locate the "VALARM" component
the old-values and the new-values contains SEQUENCE:3 and if SEQUENCE in this example, both the old-values and the new-values contain the
was left out of new-values - it would have been deleted. "SEQUENCE" property with a value of "3" and if the "SEQUENCE"
property were to be left out of new-values, it would have been
deleted.
Example: Example:
C: Content-Type: text/calendar C: Content-Type: text/calendar
C: C:
C: BEGIN:VCALENDAR C: BEGIN:VCALENDAR
C: VERSION:2.0 C: VERSION:2.0
C: PRODID:-//someone's prodid
C: TARGET:my-cal C: TARGET:my-cal
C: CMD:ID=unique-mod:MODIFY C: CMD:ID=unique-mod:MODIFY
C: BEGIN:VQUERY <- Query to select data set. C: BEGIN:VQUERY <- Query to select data set.
C: QUERY:SELECT * FROM VEVENT WHERE UID = 'unique-58' C: QUERY:SELECT * FROM VEVENT WHERE UID = 'unique-58'
C: END:VQUERY C: END:VQUERY
C: BEGIN:VEVENT <- Start of old data. C: BEGIN:VEVENT <- Start of old data.
C: LOCATION:building 3 C: LOCATION:building 3
C: LAST-MODIFIED:20020101T123456Z C: LAST-MODIFIED:20020101T123456Z
C: X-LOCAL:some private stuff C: X-LOCAL:some private stuff
C: BEGIN:VALARM C: BEGIN:VALARM
skipping to change at page 110, line 35 skipping to change at page 113, line 36
C: BEGIN:VEVENT <- End of new data. C: BEGIN:VEVENT <- End of new data.
C: LOCATION:building 4 C: LOCATION:building 4
C: LAST-MODIFIED:20020202T010203Z C: LAST-MODIFIED:20020202T010203Z
C: COMMENT:Ignore global trigger. C: COMMENT:Ignore global trigger.
C: BEGIN:VALARM C: BEGIN:VALARM
C: SEQUENCE:3 C: SEQUENCE:3
C: TRIGGER;ENABLE=FALSE:RELATED=END:PT5M C: TRIGGER;ENABLE=FALSE:RELATED=END:PT5M
C: END:VALARM C: END:VALARM
C: END:VEVENT C: END:VEVENT
X-LOCAL was not supplied in the new-values, so it was deleted. The "X-LOCAL" property was not supplied in the new-values, so it was
LOCATION was altered, as was LAST-MODIFIED. The VALARM with deleted. The "LOCATION" property value was altered, as was the
SEQUENCE:3 had its TRIGGER disabled, and SEQUENCE did not change so "LAST-MODIFIED" value. The "VALARM" component with a "SEQUENCE"
it was not effected. COMMENT was added. property value of "3" had its "TRIGGER" property disabled, and the
"SEQUENCE" property value did not change so it was not effected. The
"COMMENT" property was added.
When it comes to inline ATTACHMENTs, the CUA only needs to uniquely When it comes to inline ATTACHMENTs, the CUA only needs to uniquely
identify the contents of the ATTACHMENT value in the old-values in identify the contents of the ATTACHMENT value in the old-values in
order to delete them. When the CS compares the attachment data it is order to delete them. When the CS compares the attachment data it is
compared in its binary form. The ATTACHMENT value supplied by the compared in its binary form. The ATTACHMENT value supplied by the
CUA MUST BE valid encoded information. CUA MUST BE valid encoded information.
For example, to delete the same huge inline attachment from every For example, to delete the same huge inline attachment from every
VEVENT in 'my-cal' that has an ATTACH with the old-values: VEVENT in 'my-cal' that has an "ATTACH" property value with the old-
values:
BEGIN:VCALENDAR BEGIN:VCALENDAR
VERSION:2.0 VERSION:2.0
PRODID:-//someone's prodid
TARGET:my-cal TARGET:my-cal
CMD:MODIFY CMD:MODIFY
BEGIN:VQUERY BEGIN:VQUERY
QUERY:SELECT ATTACH FROM VEVENT QUERY:SELECT ATTACH FROM VEVENT
END:VQUERY END:VQUERY
BEGIN:VEVENT BEGIN:VEVENT
ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY: ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY:
MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U
EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE
...< remainder of attachment data NOT supplied >.... ...< remainder of attachment data NOT supplied >....
skipping to change at page 111, line 35 skipping to change at page 114, line 36
Furthermore, the following additional restrictions apply: Furthermore, the following additional restrictions apply:
1. One can not change the "UID" property of a component. 1. One can not change the "UID" property of a component.
2. If a contained component is changed inside of a selected 2. If a contained component is changed inside of a selected
component, and that contained component has multiple instances, component, and that contained component has multiple instances,
then old-values MUST contain information that uniquely identifies then old-values MUST contain information that uniquely identifies
the instance or instances that are changing. It is valid to the instance or instances that are changing. It is valid to
change more than one. As all contained components that match change more than one. As all contained components that match
old-values will be modified. In the first modify example above, old-values will be modified. In the first modify example above,
if SEQUENCE were to be deleted from both the old-values and new- if "SEQUENCE" properties were to be deleted from both the old-
values, then all TRIGGERs that matched the old-values in all values and new-values, then all "TRIGGER" properties that matched
VALARM in the selected VEVENTs would be disabled. the old-values in all "VALARM" components in the selected
"VEVENT" components would be disabled.
3. The result of the modify MUST BE a valid iCalendar object. 3. The result of the modify MUST BE a valid iCalendar object.
If the REQUEST-STATUS is 2.0, then the entire modification was Response: A "VCALENDAR" component is returns with one ore more
successful. "REQUEST-STATUS" property values.
If any error occurred: If any error occurred:
No component will be changed at all. That is, it will appear just 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 as it was prior to the modify and the CAP server SHOULD return a
REQUEST-STATUS for each error that occurred. "REQUEST-STATUS" property for each error that occurred.
There MUST BE at least one error reported.