draft-ietf-calsch-cap-07.txt   draft-ietf-calsch-cap-08.txt 
Network Working Group S. Mansour Network Working Group D. Royer
Internet-Draft AOL/Netscape Internet-Draft INET-Consulting
Expires: August 30, 2002 D. Royer Expires: December 29, 2002 G. Babics
INET-Consulting LLC
G. Babics
Steltor Steltor
P. Hill P. Hill
Massachusetts Institute of MIT
Technology S. Mansour
March 01, 2002 AOL/Netscape
June 30, 2002
Calendar Access Protocol (CAP) Calendar Access Protocol (CAP)
draft-ietf-calsch-cap-07 draft-ietf-calsch-cap-08
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
skipping to change at page 1, line 38 skipping to change at page 1, line 37
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 August 30, 2002. This Internet-Draft will expire on December 29, 2002.
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 that The Calendar Access Protocol (CAP) is an Internet protocol described
permits a Calendar User (CU) to utilize a Calendar User Agent (CUA) in this memo that permits a Calendar User (CU) to utilize a Calendar
to access an [RFC2445] based Calendar Store (CS). This memo defines User Agent (CUA) to access an [iCAL] based Calendar Store (CS).
the CAP specification.
The CAP definition is based on requirements identified by the The CAP definition is based on requirements identified by the
Internet Engineering Task Force (IETF) Calendaring and Scheduling Internet Engineering Task Force (IETF) Calendaring and Scheduling
(CALSCH) Working Group. More information about the IETF CALSCH (CALSCH) Working Group. More information about the IETF CALSCH
Working Group activities can be found on the IMC web site at http:// Working Group activities can be found on the IMC web site at http://
www.imc.org/ietf-calendar and at the IETF web site at http:// www.imc.org/ietf-calendar and at the IETF web site at http://
www.ietf.org/html.charters/calsch-charter.html [1]. Refer to the www.ietf.org/html.charters/calsch-charter.html [1]. Refer to the
references within this memo for further information on how to access references within this memo for further information on how to access
these various documents. these various documents.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . 5
1.1 Formatting Conventions . . . . . . . . . . . . . . . . 5 1.1 Formatting Conventions . . . . . . . . . . . . . . . . . 5
1.2 Related Documents . . . . . . . . . . . . . . . . . . 6 1.2 Related Documents . . . . . . . . . . . . . . . . . . . 6
1.3 Definitions . . . . . . . . . . . . . . . . . . . . . 6 1.3 Definitions . . . . . . . . . . . . . . . . . . . . . . 7
2. CAP Design . . . . . . . . . . . . . . . . . . . . . . 12 2. Additions to iCalendar . . . . . . . . . . . . . . . . . 12
2.1 System Model . . . . . . . . . . . . . . . . . . . . . 12 2.1 New Value Types (summary) . . . . . . . . . . . . . . . 13
2.2 Calendar Store Object Model . . . . . . . . . . . . . 12 2.1.1 New Parameters (summary) . . . . . . . . . . . . . . . . 14
2.3 Protocol Model . . . . . . . . . . . . . . . . . . . . 13 2.1.2 New Properties (summary) . . . . . . . . . . . . . . . . 15
2.4 Security Model . . . . . . . . . . . . . . . . . . . . 14 2.1.3 New Components (summary) . . . . . . . . . . . . . . . . 17
2.4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . 14 2.2 Relationship of RFC-2446 (ITIP) and CAP . . . . . . . . 17
2.4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . 14 3. CAP Design . . . . . . . . . . . . . . . . . . . . . . . 20
2.4.1.2 Anonymous Users and Authentication . . . . . . . . . . 15 3.1 System Model . . . . . . . . . . . . . . . . . . . . . . 20
2.4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . 16 3.2 Calendar Store Object Model . . . . . . . . . . . . . . 20
2.4.2 Access Rights - Summary . . . . . . . . . . . . . . . 16 3.3 Protocol Model . . . . . . . . . . . . . . . . . . . . . 21
2.4.2.1 Calendar Access Right (VCAR) . . . . . . . . . . . . . 16 3.3.1 Use of BEEP, MIME and iCalendar . . . . . . . . . . . . 22
2.4.2.2 Predefined VCARs . . . . . . . . . . . . . . . . . . . 17 4. Security Model . . . . . . . . . . . . . . . . . . . . . 24
2.4.2.3 Decreed VCARs . . . . . . . . . . . . . . . . . . . . 18 4.1 Calendar User and UPNs . . . . . . . . . . . . . . . . . 24
2.4.3 CAP Session Identity . . . . . . . . . . . . . . . . . 19 4.1.1 UPNs and Certificates . . . . . . . . . . . . . . . . . 24
2.5 Roles . . . . . . . . . . . . . . . . . . . . . . . . 20 4.1.2 Anonymous Users and Authentication . . . . . . . . . . . 25
2.6 CAP URL . . . . . . . . . . . . . . . . . . . . . . . 20 4.1.3 User Groups . . . . . . . . . . . . . . . . . . . . . . 25
2.7 Calendar Addresses . . . . . . . . . . . . . . . . . . 21 4.2 Access Rights . . . . . . . . . . . . . . . . . . . . . 26
2.8 Extensions to iCalendar . . . . . . . . . . . . . . . 21 4.2.1 Access Control and NOCONFLICT . . . . . . . . . . . . . 26
2.9 Relationship of RFC 2446 (ITIP) to CAP . . . . . . . . 21 4.2.2 Calendar Access Right (VCAR) . . . . . . . . . . . . . . 26
3. Protocol Framework . . . . . . . . . . . . . . . . . . 23 4.2.3 Predefined VCARs . . . . . . . . . . . . . . . . . . . . 27
3.1 BEEP Exchange Styles . . . . . . . . . . . . . . . . . 23 4.2.4 Decreed VCARs . . . . . . . . . . . . . . . . . . . . . 28
3.2 Use BEEP, MIME and iCalendar . . . . . . . . . . . . . 23 4.3 CAP Session Identity . . . . . . . . . . . . . . . . . . 29
3.3 Bounded Latency . . . . . . . . . . . . . . . . . . . 24 5. CAP URL and Calendar Address . . . . . . . . . . . . . . 31
4. New Value Types . . . . . . . . . . . . . . . . . . . 27 6. New Components, Properties, Parameters, and Values . . . 33
4.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . . 27 6.1 Property Value Data Types . . . . . . . . . . . . . . . 33
4.1.1 CAP-QL notes . . . . . . . . . . . . . . . . . . . . . 31 6.1.1 CAL-QUERY Value Type . . . . . . . . . . . . . . . . . . 33
4.2 CAP-QL notes . . . . . . . . . . . . . . . . . . . . . 37 6.1.1.1 CAL-OWNERS() . . . . . . . . . . . . . . . . . . . . . . 39
4.3 Example, Query by UID . . . . . . . . . . . . . . . . 42 6.1.1.2 CURRENT-TARGET() . . . . . . . . . . . . . . . . . . . . 39
4.4 Query by Date-Time range . . . . . . . . . . . . . . . 42 6.1.1.3 [NOT] OWNER() . . . . . . . . . . . . . . . . . . . . . 39
4.5 Query for all Non-Booked Entries . . . . . . . . . . . 43 6.1.1.4 SELF() . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.6 Query with Subset of Properties by Date/Time . . . . . 44 6.1.1.5 STATE() . . . . . . . . . . . . . . . . . . . . . . . . 39
4.7 Components With Alarms In A Range . . . . . . . . . . 44 6.1.1.6 Ordering of Results . . . . . . . . . . . . . . . . . . 39
5. Access Rights . . . . . . . . . . . . . . . . . . . . 45 6.1.1.7 Date sorting order . . . . . . . . . . . . . . . . . . . 40
5.1 Access Control and NOCONFLICT . . . . . . . . . . . . 45 6.1.1.8 Use of single quote . . . . . . . . . . . . . . . . . . 41
6. Commands and Responses . . . . . . . . . . . . . . . . 46 6.1.1.9 Comparing DATE and DATE-TIME values . . . . . . . . . . 41
6.1 Session Commands . . . . . . . . . . . . . . . . . . . 46 6.1.1.10 DTEND and DURATION . . . . . . . . . . . . . . . . . . . 42
6.1.1 "generate-uid" Command . . . . . . . . . . . . . . . . 46 6.1.1.11 [NOT] LIKE . . . . . . . . . . . . . . . . . . . . . . . 44
6.1.2 "get-capability" Command . . . . . . . . . . . . . . . 47 6.1.1.12 Empty vs. NULL . . . . . . . . . . . . . . . . . . . . . 44
6.1.3 "identify" Command . . . . . . . . . . . . . . . . . . 49 6.1.1.13 [NOT] IN . . . . . . . . . . . . . . . . . . . . . . . . 45
6.1.4 "noop" Command . . . . . . . . . . . . . . . . . . . . 50 6.1.1.14 DATE-TIME and TIME values in a WHEN clause . . . . . . . 46
6.2 Calendaring and Scheduling Commands . . . . . . . . . 51 6.1.1.15 Multiple contained components . . . . . . . . . . . . . 46
6.2.1 Restriction Tables . . . . . . . . . . . . . . . . . . 51 6.1.1.16 Example, Query by UID . . . . . . . . . . . . . . . . . 47
6.2.2 Calendaring Commands . . . . . . . . . . . . . . . . . 52 6.1.1.17 Query by Date-Time range . . . . . . . . . . . . . . . . 47
6.2.2.1 "create" Command . . . . . . . . . . . . . . . . . . . 52 6.1.1.18 Query for all Unprocessed Entries . . . . . . . . . . . 47
6.2.2.2 "move" Command . . . . . . . . . . . . . . . . . . . . 57 6.1.1.19 Query with Subset of Properties by Date/Time . . . . . . 48
6.2.2.3 "delete" Command . . . . . . . . . . . . . . . . . . . 60 6.1.1.20 Query with Components and Alarms In A Range . . . . . . 49
6.2.2.4 "modify" Command . . . . . . . . . . . . . . . . . . . 62 6.1.2 UPN Value Type . . . . . . . . . . . . . . . . . . . . . 49
6.2.2.5 "search" Command . . . . . . . . . . . . . . . . . . . 66 6.1.3 UPN-FILTER Value . . . . . . . . . . . . . . . . . . . . 50
6.2.2.6 Response Codes . . . . . . . . . . . . . . . . . . . . 71 6.2 New Parameter . . . . . . . . . . . . . . . . . . . . . 51
7. Initial Registrations . . . . . . . . . . . . . . . . 73 6.2.1 ENABLE Parameter . . . . . . . . . . . . . . . . . . . . 51
7.1 BEEP Profile Registration . . . . . . . . . . . . . . 73 6.2.2 LOCAL Parameter . . . . . . . . . . . . . . . . . . . . 52
7.2 Registration: The System (Well-Known) TCP port number 7. New Properties . . . . . . . . . . . . . . . . . . . . . 54
for CAP . . . . . . . . . . . . . . . . . . . . . . . 73 7.1 ALLOW-CONFLICT Property . . . . . . . . . . . . . . . . 54
8. CAP DTD . . . . . . . . . . . . . . . . . . . . . . . 75 7.2 CALID Property . . . . . . . . . . . . . . . . . . . . . 54
9. Properties . . . . . . . . . . . . . . . . . . . . . . 76 7.3 CALMASTER Property . . . . . . . . . . . . . . . . . . . 55
9.1 Calendar Store Properties . . . . . . . . . . . . . . 76 7.4 CARID Property . . . . . . . . . . . . . . . . . . . . . 56
9.2 Calendar Properties . . . . . . . . . . . . . . . . . 77 7.5 CSID Property . . . . . . . . . . . . . . . . . . . . . 56
10. Security Considerations . . . . . . . . . . . . . . . 80 7.6 DECREED Property . . . . . . . . . . . . . . . . . . . . 57
11. Extensions To iCalendar . . . . . . . . . . . . . . . 81 7.7 DEFAULT-CHARSET Property . . . . . . . . . . . . . . . . 58
11.1 Property Value Data Types . . . . . . . . . . . . . . 81 7.8 DEFAULT-LOCALE Property . . . . . . . . . . . . . . . . 58
11.1.1 UPN . . . . . . . . . . . . . . . . . . . . . . . . . 81 7.9 DEFAULT-TZID Property . . . . . . . . . . . . . . . . . 59
11.1.2 UPN Filter . . . . . . . . . . . . . . . . . . . . . . 82 7.10 DEFAULT-VCARS Property . . . . . . . . . . . . . . . . . 60
11.2 Calendar Components . . . . . . . . . . . . . . . . . 83 7.11 DENY Property . . . . . . . . . . . . . . . . . . . . . 61
11.2.1 Agenda Component . . . . . . . . . . . . . . . . . . . 83 7.12 EXPAND property . . . . . . . . . . . . . . . . . . . . 62
11.2.2 Calendar Store Component . . . . . . . . . . . . . . . 84 7.13 GRANT Property . . . . . . . . . . . . . . . . . . . . . 62
11.2.3 Calendar Access Right Component . . . . . . . . . . . 85 7.14 MAXDATE Property . . . . . . . . . . . . . . . . . . . . 63
11.2.4 VRIGHT Calendar Component . . . . . . . . . . . . . . 88 7.15 MINDATE Property . . . . . . . . . . . . . . . . . . . . 64
11.3 Component Properties . . . . . . . . . . . . . . . . . 89 7.16 NAME Property . . . . . . . . . . . . . . . . . . . . . 64
11.3.1 Allow-Conflict Component Property . . . . . . . . . . 89 7.17 OWNER Property . . . . . . . . . . . . . . . . . . . . . 65
11.3.2 Charset Component Property . . . . . . . . . . . . . . 90 7.18 PERMISSION Property . . . . . . . . . . . . . . . . . . 66
11.3.3 Default Locale Component Property . . . . . . . . . . 91 7.19 QUERY property . . . . . . . . . . . . . . . . . . . . . 67
11.3.4 Default Time Zone Property . . . . . . . . . . . . . . 91 7.20 QUERYID property . . . . . . . . . . . . . . . . . . . . 67
11.3.5 Owner Component Property . . . . . . . . . . . . . . . 92 7.21 REQUEST-STATUS property . . . . . . . . . . . . . . . . 68
11.3.6 Relative Calendar Identifier Component Property . . . 93 7.22 RESTRICTION Property . . . . . . . . . . . . . . . . . . 69
11.3.7 Calendar Store Component Properties . . . . . . . . . 94 7.23 SCOPE Property . . . . . . . . . . . . . . . . . . . . . 70
11.3.7.1 Calmaster Component Property . . . . . . . . . . . . . 94 7.24 TARGET Property . . . . . . . . . . . . . . . . . . . . 71
11.3.7.2 Calendar Store Identifier Component Property . . . . . 94 7.25 TRANSP Property . . . . . . . . . . . . . . . . . . . . 71
11.3.7.3 Default Access Rights Component Property . . . . . . . 95 8. New Components . . . . . . . . . . . . . . . . . . . . . 73
11.3.7.4 Maximum Date Component Property . . . . . . . . . . . 96 8.1 VAGENDA Component . . . . . . . . . . . . . . . . . . . 73
11.3.7.5 Minimum Date Component Property . . . . . . . . . . . 97 8.2 VCALSTORE Component . . . . . . . . . . . . . . . . . . 75
11.3.8 Descriptive Component Properties . . . . . . . . . . . 97 8.3 VCAR Component . . . . . . . . . . . . . . . . . . . . . 78
11.3.8.1 REQUEST-STATUS property . . . . . . . . . . . . . . . 97 8.4 VRIGHT Component . . . . . . . . . . . . . . . . . . . . 81
11.3.8.2 CALID Property Parameter . . . . . . . . . . . . . . . 98 8.5 VREPLY Component . . . . . . . . . . . . . . . . . . . . 82
11.3.8.3 Time Transparency . . . . . . . . . . . . . . . . . . 99 8.6 VQUERY Component . . . . . . . . . . . . . . . . . . . . 82
11.3.8.4 Name Component Property . . . . . . . . . . . . . . . 100 9. Commands and Responses . . . . . . . . . . . . . . . . . 84
11.3.9 Calendar Access Right Component Properties . . . . . . 101 9.1 CAP Commands (CMD) . . . . . . . . . . . . . . . . . . . 84
11.3.9.1 VCAR Identifier Component Property . . . . . . . . . . 101 9.1.1 Bounded Latency . . . . . . . . . . . . . . . . . . . . 85
11.3.9.2 VCAR Decreed Component Property . . . . . . . . . . . 102 9.1.2 ABORT Command . . . . . . . . . . . . . . . . . . . . . 88
11.3.10 Right Component Properties . . . . . . . . . . . . . . 102 9.1.3 CONTINUE Command . . . . . . . . . . . . . . . . . . . . 88
11.3.10.1 Grant Component Property . . . . . . . . . . . . . . . 103 9.1.4 CREATE Command . . . . . . . . . . . . . . . . . . . . . 90
11.3.10.2 Deny Component Property . . . . . . . . . . . . . . . 103 9.1.5 DELETE Command . . . . . . . . . . . . . . . . . . . . . 96
11.3.10.3 Permission Component Property . . . . . . . . . . . . 104 9.2 GENERATE-UID Command . . . . . . . . . . . . . . . . . . 99
11.3.10.4 Scope Component Property . . . . . . . . . . . . . . . 105 9.3 GET-CAPABILITY Command . . . . . . . . . . . . . . . . . 101
11.3.10.5 Restriction Component Property . . . . . . . . . . . . 106 9.4 IDENTIFY Command . . . . . . . . . . . . . . . . . . . . 105
12. CAP Item Registration . . . . . . . . . . . . . . . . 107 9.5 MODIFY Command . . . . . . . . . . . . . . . . . . . . . 107
12.1 Registration of New and Modified CAP Entities . . . . 107 9.6 MOVE Command . . . . . . . . . . . . . . . . . . . . . . 112
12.2 Registration of New Entities . . . . . . . . . . . . . 107 9.7 REPLY Response to a Command . . . . . . . . . . . . . . 115
12.2.1 Define the Item . . . . . . . . . . . . . . . . . . . 107 9.8 SEARCH Command . . . . . . . . . . . . . . . . . . . . . 116
12.2.2 Post the item definition . . . . . . . . . . . . . . . 108 9.9 SET-LOCALE Command . . . . . . . . . . . . . . . . . . . 119
12.2.3 Allow a comment period . . . . . . . . . . . . . . . . 108 9.10 TIMEOUT Command . . . . . . . . . . . . . . . . . . . . 121
12.2.4 Submit the proposal for approval . . . . . . . . . . . 108 9.11 Response Codes . . . . . . . . . . . . . . . . . . . . . 121
12.3 Property Change Control . . . . . . . . . . . . . . . 109 10. Object Registration . . . . . . . . . . . . . . . . . . 124
13. IANA Considerations . . . . . . . . . . . . . . . . . 110 10.1 Registration of New and Modified Entities . . . . . . . 124
Authors' Addresses . . . . . . . . . . . . . . . . . . 111 10.2 Post the item definition . . . . . . . . . . . . . . . . 124
A. Acknowledgments . . . . . . . . . . . . . . . . . . . 112 10.3 Allow a comment period . . . . . . . . . . . . . . . . . 124
B. Bibliography . . . . . . . . . . . . . . . . . . . . . 113 10.4 Release a new RFC . . . . . . . . . . . . . . . . . . . 124
Full Copyright Statement . . . . . . . . . . . . . . . 115 11. BEEP and CAP . . . . . . . . . . . . . . . . . . . . . . 125
11.1 BEEP Profile Registration . . . . . . . . . . . . . . . 125
11.2 BEEP Exchange Styles . . . . . . . . . . . . . . . . . . 125
12. IANA Considerations . . . . . . . . . . . . . . . . . . 126
13. Security Considerations . . . . . . . . . . . . . . . . 127
Authors' Addresses . . . . . . . . . . . . . . . . . . . 128
A. Acknowledgments . . . . . . . . . . . . . . . . . . . . 130
B. Bibliography . . . . . . . . . . . . . . . . . . . . . . 131
Full Copyright Statement . . . . . . . . . . . . . . . . 133
1. Introduction 1. Introduction
This document specifies how a Calendar User Agent (CUA) interacts This document specifies how a Calendar CUA interacts with a CS to
with a Calendar Store (CS) to manage calendar information. In manage calendar information. In particular, it specifies how to
particular, it specifies how to query, create, modify, and delete query, create, modify, and delete iCalendar components (e.g., events,
iCalendar components (e.g., events, to-dos, or daily journal to-dos, or daily journal entries). It further specifies how to
entries). It further specifies how to search for available busy time search for available busy time information. Synchronization with
information. 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 the 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 [RFC2445] 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 here in this memo, they mean exactly the same as objects are used in this memo, they mean exactly the same as defined
defined in [iTIP]. in [iTIP]. When iCalendar objects are transfered between the
calendar user agent and a calendar server, some additional properties
and parameters may be added and the calendar user agent is
responsible for correctly generating iCalendar objects to non CAP
processes.
The definition of new components, properties, parameter's, and value
types are broken into two parts. The first part summarizes and
defined the new objects. The second part provides the detail and any
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 [RFC2119].
Calendaring and scheduling roles are referred to in quoted-strings of Calendaring and scheduling roles are referred to in quoted-strings of
text with the first character of each word in upper case. For text with the first character of each word in upper case. For
example, "Organizer" refers to a role of a "Calendar User" (CU) example, "Organizer" refers to a role of a "Calendar User" (CU)
within the protocol defined by [iTIP]. Calendar components defined within the protocol defined by [iTIP]. Calendar components defined
by [RFC2445] are referred to with capitalized, quoted-strings of by [iCAL] are referred to with capitalized, quoted-strings of text.
text. All calendar components 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 calendar component and "VJOURNAL" refers to the refers to the to-do component and "VJOURNAL" refers to the daily
daily journal calendar component. journal component.
Scheduling methods defined by [iTIP], are referred to with Scheduling methods defined by [iTIP], are referred to with
capitalized, quoted-strings of text. For example, "REPLY" refers to capitalized, quoted-strings of text. For example, "REPLY" refers to
the method for replying to a "REQUEST". the method for replying to a "REQUEST".
CAP commands are referred by lower-case, quotes-strings of text, CAP commands are referred to by upper-case, quoted-strings of text,
followed by the word "command". For example, "create" command refers followed by the word "command". For example, "CREATE" command refers
to the command for creating a calendar entry, "search" command refers to the command for creating a calendar entry, "SEARCH" command refers
to the command for reading calendar components. to the command for reading calendar components. CAP Commands are
named using the "CMD" property.
Properties defined by this memo are referred to with capitalized, Properties defined by this memo are referred to with capitalized,
quoted-strings of text, followed by the word "property". For quoted-strings of text, followed by the word "property". For
example, "ATTENDEE" property refers to the iCalendar property used to example, "ATTENDEE" property refers to the iCalendar property used to
convey the calendar address of a "Calendar User". Property convey the calendar address that has been invited to a "VEVENT" or
parameters defined by this memo are referred to with capitalized, "VTODO" component.
quoted-strings of text, followed by the word "parameter". For
example, "PARTSTAT" parameter refers to the iCalendar property Property parameters defined by this memo are referred to with
parameter used to specify the participation status of an attendee. capitalized, quoted-strings of text, followed by the word
Enumerated values defined by this memo are referred to with "parameter". For example, "PARTSTAT" parameter refers to the
capitalized text, either alone or followed by the word "value". iCalendar property parameter used to specify the participation status
of an attendee. Enumerated values defined by this memo are referred
to with capitalized text, either alone or followed by the word
"value".
In tables, the quoted-string text is specified without quotes in In tables, the quoted-string text is specified without quotes in
order to minimize the table length. order to minimize the table length.
1.2 Related Documents 1.2 Related Documents
Implementers will need to be familiar with several other memos that, Implementers will need to be familiar with several other memos that,
along with this one, describe the Internet calendaring and scheduling along with this one, describe the Internet calendaring and scheduling
standards. These documents are: standards. These documents are:
[RFC2445] (RFC2445) which specifies the objects, data types, [iCAL] - (RFC2445) Which specifies the objects, data types,
properties and property parameters used in the protocols, along with properties and property parameters used in the protocols, along
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 implementations. The related documents scheduling between different installations.
are:
[iMIP] (RFC2447) which specifies an Internet email binding for [iMIP] - (RFC2447) Which specifies the Internet email binding for
[iTIP]. [iTIP].
[GUIDE] (draft/rfc...) which is a guide to implementers and describes [GUIDE] - (draft/rfc...), a guide to implementers and describes the
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 BOOKED - An entry in the calendar store has one of three conceptual
states. It is "UNPROCESSED", "BOOKED" or marked as "DELETED".
How the implementation stores the state of any object is not a
protocol issues and is not discussed. An object can be said to be
booked, unprocessed, or marked for delete.
An entry in a calendar has one of three conceptual states. It 1. A "UNPROCESSED" scheduling entry has been stored in the
is scheduled, booked or marked for delete. A scheduled entry calendar store but has not been acted on by a Calendar User
has been stored in the calendar store but has not been acted on (CU) or Calendar User Agent (CUA). All scheduled entries are
by a calendar user (CU) or calendar user agent (CUA). A [iTIP] objects. All [iTIP] objects in the store are not
scheduled entry contains a METHOD property set to an [iTIP] booked. To retrieve any [iTIP] object, simply do a query
method. A booked entry has its METHOD property set to CREATE. asking for any objects that were stored with its state set to
A marked for delete component has its METHOD property set to "UNPROCESSED".
DELETE
Calendar
A collection of logically related objects or entities each of 2. A booked entry is stored with the CREATE command. It is an
which may be associated with a calendar date and possibly time entry that has been acted on by a CU or CUA and there has
of day. These entities can include other calendar properties been a decision to store an object. To retrieve any booked
or calendar components. In addition, a calendar might be object, simply do a query asking for any objects that were
hierarchically related to other calendars with the RELATED-TO stored with its state set to "BOOKED".
property. A calendar is identified by its unique calendar
identifier. The [RFC2445] defines calendar properties,
calendar components and component properties that make up the
content of a calendar.
Calendar Access Protocol (CAP) 3. A marked for delete component has its state set to DELETE. To
retrieve any deleted object, simply do a query asking for any
objects that were stored with its state set to "DELETED". By
default objects marked for delete are not returned. The CUA
must specifically ask for marked for delete objects.
The standard Internet protocol that permits a Calendar User Calendar - A collection of logically related objects or entities
Agent to access and manipulate calendars residing on a Calendar each of which may be associated with a calendar date and possibly
Store. (this memo) time of day. These entities can include calendar properties or
components. In addition, a calendar might be related to other
calendars with the "RELATED-TO" property. A calendar is
identified by its unique calendar identifier. The [iCAL] defines
the initial calendar properties, calendar components and
properties that make up the contents of a calendar.
Calendar Access Rights (CAR) Calendar Access Protocol (CAP) - The standard Internet protocol that
permits a CUA to access and manipulate calendars residing on a
Calendar Store. (this memo)
The mechanism for specifying the CAP operations ("PERMISSION") Calendar Access Rights (VCAR) - The mechanism for specifying the CAP
that a particular calendar user ("UPN") is granted or denied operations ("PERMISSION") that a particular calendar user ("UPN")
permission to perform on a given calendar object ("SCOPE"). is granted or denied permission to perform on a given calendar
The calendar access rights are specified with the "VCAR" object ("SCOPE"). The calendar access rights are specified with
calendar components within a CS and calendar. the "VCAR" calendar components within a CS and calendar.
Calendar Component Calendar Address - Also See Calendar URL - they are one in the same
for CAP addresses. The calendar address can also be the value to
the "ATTENDEE" and "ORGANIZER" properties as defined in [iCAL].
An object within a calendar or a calendar store (CS). Some Calendar URL - A calendar URL is a URL defined in this memo that
types of calendar components include calendars, events, to-dos, specifies the address of a CS or Calendar.
journals, alarms, time zones and freebusy data. A calendar
component consists of component properties and possibly other
sub-components. For example, an event may contain an alarm
component.
Calendar Component Properties Component- Any object that conforms to the iCalendar object format
and that is either defined in an internet draft, registered with
IANA, or is an experimental object that is prefixed with "x-".
Some types of components include calendars, events, to-dos,
journals, alarms, and time zones. A component consists of
properties and possibly other contained components. For example,
an event may contain an alarm component.
An attribute of a particular calendar component. Some calendar Properties - An attribute of a particular component. Some
component properties are applicable to different types of properties are applicable to different types of components. For
calendar components. For example, DTSTART is applicable to example, the "DTSTART" property is applicable to "VEVENT",
VEVENT, VTODO, VJOURNAL calendar components. Other calendar "VTODO", "VJOURNAL" components. Other components are applicable
components are applicable only to an individual type of only to an individual type of calendar component. For example,
calendar component. For example, TZURL is only applicable to the "TZURL" property may only applicable to "VTIMEZONE"
VTIMEZONE calendar components. components.
Calendar Identifier (CalID) Calendar Identifier (CalID) - A globally unique identifier
associated with a calendar. Calendars reside within a CS. See
Qualified Calendar Identifier and Relative Calendar Identifier.
All CalIDs start with "cap:".
A globally unique identifier associated with a calendar. Calendar Policy - A CAP operational restriction on the access or
manipulation of a calendar. These may be outside of the scope of
the CAP protocol. An example of an implementation or site policy
is, "events MUST BE scheduled in unit intervals of one hour".
Calendars reside within a CS. See Qualified Calendar Calendar Property - An attribute of a calendar ("VAGENDA"). The
Identifier and Relative Calendar Identifier. All CalIDs start attribute applies to the calendar, as a whole. For example, the
with "cap:" "CALSCALE" property specifies the calendar scale (e.g., the
"GREGORIAN" value) for the whole calendar.
Calendar Policy Calendar Server - An implementation of a Calendar Store that manages
one or more calendars.
A CAP operational restriction on the access or manipulation of Calendar Store (CS) - The data and service model definition for a
a calendar. These may be outside of the scope of the CAP Calendar Store as defined in this memo. This memo does not
protocol. For example, "events MUST be scheduled in unit specify how the CS is implemented.
intervals of one hour".
Calendar Property Calendar Store Identifier (CSID) - The globally unique identifier
for an individual CS. A CSID consists of the host and port
portions of a "Common Internet Scheme Syntax" part of a URL, as
defined by [RFC1738]. The CSID excludes any reference to a
specific calendar.
An attribute of a calendar (VAGENDA). The attribute applies to Calendar Store Components - Components maintained in a CS specify a
the calendar, as a whole. For example, CALSCALE specifies the grouping of calendar store-wide information.
calendar scale (e.g., GREGORIAN) for the whole calendar.
Calendar Service Calendar Store Properties - Properties maintained in a Calendar
Store calendar store-wide information.
An implementation of a Calendar Store that manages one or more Calendar User (CU) - An entity (often biological) that uses a
calendars. calendaring system.
Calendar Store (CS) Calendar User Agent (CUA) - The client application that a CU
utilizes to access and manipulate a calendar.
The data and service model definition for a Calendar Service. CAP Session - An open communication channel between a CUA and a
Calendar Server. If the CAP session is authenticated, the the CU
is "authenticated" and it is an "authenticated CAP session".
Calendar Store Identifier (CSID) Contained Component / Contained Properties - A component or property
that is contained inside of another component. A "VALARM"
component for example may be contained inside of a "VEVENT"
component. And a "TRIGGER" property could be a contained property
of a "VALARM" component.
The globally unique identifier for an individual CS. A CSID Delegate - A calendar user (sometimes called the delegatee) who has
consists of the host and port portions of a "Common Internet been assigned participation in a scheduled component (e.g.,
Scheme Syntax" part of a URL, as defined by [RFC1738]. VEVENT) by one of the attendees in the scheduled component
(sometimes called the delegator). An example of a delegate is a
team member told to go to a particular meeting in place of another
Attendee who is unable to attend.
Calendar Store Components Designate - A calendar user who is authorized to act on behalf of
another calendar user. An example of a designate is an assistant.
Components maintained in a CS specify a grouping of calendar Experiential - The CUA and CS may implement experimental extensions
store-wide information. to the protocol. They also might have experimental components,
properties, and parameters. These extensions MUST start with "x-"
(or "X-") and should include a vendor prefix (such as "x-myvendor-
"). There is no guarantee that these experimental extensions will
interoperate with other implementations. There is no guarantee
that they will not interact in unpredictable ways with other
vendor experimental extensions. Implementations should limit
sending those extensions to other implementations.
Calendar Store Properties Object - A generic name for any component, property, parameter, or
value type to be used in iCalendar.
Properties maintained in a Calendar Store calendar store-wide Overlapped Booking - A policy which indicates whether or not
information. components with a "TRANSP" property not set to "TRANSPARENT-
NOCONFLICT" or "OPAQUE-NOCONFLICT" value can overlap one another.
When the policy is applied to a calendar it indicates whether or
not the time span of any component (VEVENT, VTODO, ...) in the
calendar can overlap the time span of any other component in the
same calendar. When applied to an individual entry, it indicates
whether or not any other component's time span can overlap that
individual component. If the CS does not allow overlapped
booking, then the CS is unwilling to allow any overlapped bookings
within any calendar in the CS.
Calendar User (CU) 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 "
An entity (often biological) that uses a calendaring system. Qualified Calendar Identifier (Qualified CalID) - A CalID in which
both the scheme and csid of the CAP URI are present.
Calendar User Agent (CUA) Realm - A collection of calendar user accounts, identified by a
The CUA is the client application that a CU utilizes to access string. The name of the Realm is only used in UPNs. In order to
and manipulate a calendar. avoid namespace conflict, the Realm SHOULD be postfixed with an
appropriate DNS domain name. (e.g., the foobar Realm could be
called foobar.example.com).
CAP Session Relative Calendar Identifier (Relative CalID) - An identifier for an
individual calendar in a calendar store. It MUST BE unique within
a calendar store. A Relative CalID consists of the "URL path" of
the "Common Internet Scheme Syntax" portion of a URL, as defined
by [RFC396] and [RFC2718].
An open communication channel between a CUA and a Calendar Session Identity - A UPN associated with a CAP session. A session
Service. gains an identity after successful authentication. The identity
is used in combination with VCAR to determine access to data in
the CS.
Contained Component / Contained Properties User Group (UG) - A collection of Calendar Users and/or User Groups.
These groups are expanded by the CS and may reside either locally
or in an external database or directory. The group membership may
be fixed or dynamic over time.
A component or property that is contained inside a component. Username - A name which denotes a Calendar User within a Realm.
VALARM for example may be contained inside of a VEVENT. And This is part of a UPN.
TRIGGER is a contained property of a VALARM.
Delegate User Principal Name (UPN) - A unique identifier that denotes a CU or
a group of CU. A UPN is a RFC 822 compliant email address, with
exceptions listed below, and in most cases it is deliverable to
the CU. In some cases it is identical to the CU's well known
email address. A CU's UPN MUST never be an e-mail address that is
deliverable to a different person as there is no requirement that
a person's UPN MUST BE their e-mail address. A UPN is formatted
as a user name followed by "@" followed by a Realm in the form of
a valid, and unique, DNS domain name. The user name MUST BE
unique within the Realm. In it's simplest form it looks like
"user@example.com".
A calendar user (sometimes called the delegatee) who has been In certain cases a UPN will not be RFC 822 compliant. When
assigned participation in a scheduled calendar component (e.g., anonymous authentication is used, or anonymous authorization is
VEVENT) by one of the attendees in the scheduled calendar being defined, the special UPN "@" will be used. When
component (sometimes called the delegator). An example of a authentication MUST BE used, but unique identity MUST BE obscured,
delegate is a team member told to go to a particular meeting. a UPN of the form @DNS-domain-name may be used. For example,
"@example.com".
Designate 2. Additions to iCalendar
A calendar user who is authorized to act on behalf of another Several new components, properties, parameters, and value types are
calendar user. An example of a designate is an assistant. added in CAP. This section summarizes those new objects.
Overlapped Booking This memo extends the properties that can go into 'calprops' as
defined in [iCAL] section 4.6 page 51 to allow iTIP objects
transmitted between a CAP aware CUA and the CS to contain the
"TARGET" and "CMD" properties. This memo does not address how a CUA
transmits iTIP or iMIP objects to non CAP programs.
A policy which indicates whether or not OPAQUE events can calprops = 2*(
overlap one another. When the policy is applied to a calendar
it indicates whether or not the time span of any entry (VEVENT,
VTODO, ...) in the calendar can overlap the time span of any
other entry in the same calendar. When applied to an
individual entry, it indicates whether or not any other entry's
time span can overlap that individual entry.
Owner ; 'prodid' and 'version' are both REQUIRED,
; but MUST NOT occur more than once.
;
prodid /version /
One or more CUs or UGs that are listed in the "OWNER" calendar ; These are optional, but MUST NOT occur
property in a calendar. ; more than once.
;
calscale /
method /
target /
iana-prop /
cmd /
Qualified Calendar Identifier (Qualified CalID) ; These are optional, and may occur more
; than once.
;
x-prop
A CalID where both the <scheme> and <csid> are present. In addition a problem exists with the control of "VALARM" components
and their "TRIGGER" properties. A CU may wish to set their own alarm
(local alarms) on components. These local alarms are not to be
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
CS, the following changes apply to the CAP protocol from [iCAL]
section "4.6.6" page 67:
Realm alarmc = "BEGIN" ":" "VALARM" CRLF
A collection of calendar user accounts, identified by a string. alarm-seq
The name of the Realm is only used in UPNs. In order to avoid iana-prop
namespace conflict, the Realm SHOULD be postfixed with an (audioprop / dispprop / emailprop / procprop)
appropriate DNS domain name. (e.g., the foobar Realm could be "END" ":" "VALARM" CRLF
called foobar.example.com).
Relative Calendar Identifier (Relative CalID) alarm-seq = "SEQUENCE" alarmseqparam ":" integer CRLF
An identifier for an individual calendar in a calendar store. alarmseqparam = *( ";" xparam)
It MUST BE unique within a calendar store. A Relative CalID / ";" local-param
consists of the portion of the "scheme part" of a Qualified
CalID following the Calendar Store Identifier. This is the
same as the "URL path" of the "Common Internet Scheme Syntax"
portion of a URL, as defined by [RFC1738].
Session Identity The CUA adds a "SEQUENCE" property to each "VALARM" component as it
books the component. This property along with the "LOCAL" and
"ENABLE" parameters allow the CUA to uniquely identify any VALARM in
any component. The CUA should remove those before forwarding to non
CAP aware CUAs (including iMIP CUAs).
A UPN associated with a CAP session. A session gains an In addition, if a CUA wished to ignore a "TRIGGER" property in a
identity after successful authentication. The identity is used "VALARM" that was supplied to it by the ORGANIZER, the CUA needs a
in combination with CAR to determine access to data in the CS. common way to tag that trigger as disabled. So for the protocol
between a CUA and a CS, the following is a modification to [iCAL]
section "4.8.6.3" page 127:
User Group (UG) trigger = "TRIGGER" 1*(";" enable-param) (trigrel / trigabs)
A collection of Calendar Users and/or User Groups. These Section 6.2.1 and Section 6.2.2.
groups are expanded by the CS and may reside either locally or
in an external database or directory. The group membership may
be fixed or dynamic over time.
Username 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
implementation will be effected.
A name which denotes a Calendar User within a Realm. This is 2.1 New Value Types (summary)
part of a UPN.
User Principal Name (UPN) UPN The UPN value type is text value type restricted to only UPN
values. (Section 6.1.2)
A unique identifier that denotes a CU or a group of CU. A UPN UPN-FILTER Like the UPN value type, but also includes filter rules
is a RFC 822 compliant email address, with exceptions listed that allow wildcards. (Section 6.1.3)
below, and in most cases it is deliverable to the CU. In some
cases it is identical to the CU's well known email address. A
CU's UPN MUST never be an e-mail address that is deliverable to
a different person as there is no requirement that a person's
UPN must be his e-mail address. It consists of a Realm in the
form of a valid, and unique, DNS domain name and a unique
Username. In it's simplest form it looks like
"user@example.com".
In certain cases a UPN will not be RFC 822 compliant. When CALQUERY The "CAL-QUERY" (Section 6.1.1) value type is a query syntax
anonymous authentication is used, or anonymous authorization is that is used by the CUA to specify the rules that apply to a CAP
being defined, the special UPN "@" will be used. When command. In the case of "SEARCH", the query language is used to
authentication must be used, but unique identity must be fetch objects from the CS. When used with "DELETE", the selected
obscured, a UPN of the form @DNS-domain-name may be used. For objects are deleted from the CS. "CAL-QUERY" can also be used
example, "@example.com". Usage of these special cases is with "MOVE" and "MODIFY".
further discussed in the authentication and authorization
sections of this document.
2. CAP Design 2.1.1 New Parameters (summary)
2.1 System Model ENABLE -
The "ENABLE" parameter in CAP is used to tag a "TRIGGER" property
in a component as disabled or enabled. This is used when a
scheduling request arrives and the CU wishes to ignore the trigger
time included. (Section 6.2.1).
Formal Definition: The "ENABLE" parameter is defined by the
following notation:
enable-param = "ENABLE" "=" ("TRUE" / "FALSE")
LOCAL -
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
distributed. (Section 6.2.2).
For example, when inviting others to an event, the ORGANIZERs
booked VEVENT might contain VALARMs, and those VALARMS might be
'alarm be 5 minutes before the meeting'. However other ATTENDEEs,
may have to set their own VALARMs for the same event (assuming
they reply that they will be attending). So, by tagging the
VALARM as local the CUA MUST never forward those local VALARMs to
other CS's or CUAs.
The CUA can not simply delete any VALARMs from components where
the CU is not the ORGANIZER. If it did, any [iTIP] "COUNTER"
would result in the ORGANIZER thinking that the ATTENDEE wished to
also counter with removing those VALARMs. And in addition, any
update to an existing component would re-create those VALARMs in
the ATTENDEEs CS.
Formal Definition: The "LOCAL" parameter is defined by the
following notation:
local-param = "LOCAL" "=" ("TRUE" / "FALSE")
2.1.2 New Properties (summary)
ALLOW-CONFLICT - Some entries in a calendar might not be valid if
other entries were to allowed to overlap the same time span.
Renting a car for example. It would not make sense to allow two
reservations for the same car at the same time. The "ALLOW-
CONFLICT" property takes a boolean value. If FALSE, then
conflicts are not allowed. (Section 7.1)
CSID - Each CS needs its own unique identifier. The "CSID" property
is the official unique identifier for the CS. If the BEEP
'serverName' attribute was suppled in the BEEP 'start' message,
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
'serverName' value. This allows one CS implementation to service
multiple virtual hosts. CS's are not required to support virtual
hosting. If a CS does not support virtual hosting then it must
ignore the BEEP 'serverName'. (Section 7.5)
CALID - Each calendar within a CS needs to be uniquely identifiable.
The "CALID" property identifies a unique calendar within a CS. It
can be a full CALID or a relative CALID. (Section 7.2)
CALMASTER - The "CALMASTER" property specifies the contact
information for the CS. (Section 7.3)
CARID - Access rights can be saved and fetched by unique ID - the
"CARID". (Section 7.4)
CMD - The enumerated list of CAP commands and the options for those
commands, as well as replies are transmitted using the "CMD"
property. (Section 9.1)
DECREED - Some access rights are not changeable by the CUA. When
that is the case, the "DECREED" property value in the "VCAR" will
be TRUE. (Section 7.6)
DEFAULT-CHARSET - The list of charsets supported by the CS. The
first entry MUST BE the default for the CS. (Section 7.7)
DEFAULT-LOCALE - The list of locales supported by the CS. The first
entry in the list is the default locale. (Section 7.8)
DEFAULT-TZID - This is the list of known timezones supported. The
first entry is the default. (Section 7.9)
DEFAULT-VCARS - A list of the CARIDs that will be used to create new
calendars. (Section 7.10)
DENY - The UPNs listed in the "DENY" property of a "VCAR" will
denied access as described in the "VRIGHT" component. (Section
7.11)
EXPAND - This property tells the CS if the query reply should expand
components into multiple instances. The default is FALSE.
(Section 7.12)
GRANT - The UPNs listed in the "GRANT" property of a "VCAR" will
allowed access as described in the "VRIGHT" component. (Section
7.13)
MAXDATE - The maximum date supported by the CS. (Section 7.14)
MINDATE - The minimum date supported by the CS. (Section 7.15)
NAME - Several storeable components such as "VCAR" and "VQUERY" may
have the "NAME" property contained in them to describe in a
various locals the purpose of the component. Components may have
multiple "NAME" properties. (Section 7.16)
OWNER - Each calendar has at least one "OWNER". (xref
target="OWNER"/>) Related to the "OWNER()" (Section 6.1.3) query
clause.
PERMISSION - This property specifies the permission being granted or
denied. Examples are "READ" and "MODIFY". (Section 7.18)
QUERY - Use to hold the CAL-QUERY (Section 7.19) for the component.
QUERYID - A unique id for a stored query. (Section 7.20)
REQUEST-STATUS - The [iCAL] "REQUEST-STATUS" property is extended to
include new error numbers. (Section 7.21)
RESTRICTION - In the final check when granting calendar access
requests, the CS test the results to the value of the
"RESTRICTION" property in the corresponding "VRIGHT" component to
determine if the access meets that restriction. (Section 7.22)
SCOPE - The "SCOPE" property is used in "VRIGHT"s component to
select the subset of data that may be acted upon when checking
access rights. (Section 7.23)
TARGET - The new VCALENDAR property "TARGET" (Section 7.24) 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
it allows more values. (Section 7.25)
2.1.3 New Components (summary)
VAGENDA - CAP allows the fetching and storing of the entire contents
of a calendar. The "VCALENDAR" object is not sufficient to
encapsulate all of the needed data that describes a calendar. The
VAGENDA object is the encapsulating object for an entire calendar.
(Section 8.1)
VCALSTORE - Each CS contains one or more calendars (VAGENDAs), the
VCALSTORE object is the encapsulating object that can hold all of
the "VAGENDA"s along with any components and properties that are
unique to the store level. (Section 8.2)
VCAR - Calendar Access Rights are specified and encapsulated in the
new iCalendar "VCAR" (Section 8.3) component. The "VCAR"
component holds some new properties and at least one "VRIGHT"
component.
VRIGHT - (Section 8.4) This component encapsulates a set of
instructions to the CS that define the rights or restrictions
needed.
VREPLY - (Section 8.5) This component encapsulates a set of data
that can consist of an arbitrary amounts of properties and
components. Its contents is dependent on the command that was
issued.
VQUERY - The search operation makes use of a new component, called
"VQUERY" (Section 8.6) and a new value type "CAL-QUERY" (Section
6.1.1). "VQUERY" is used to fetch objects from the CS.
2.2 Relationship of RFC-2446 (ITIP) and CAP
[iTIP] describes scheduling methods which result in indirect
manipulation of components. In CAP, the "CREATE" command is used to
deposit entities into the store. Other CAP commands such as
"DELETE", "MODIFY" and "MOVE" provide direct manipulation of
components. In the CAP calendar store model, scheduling messages are
conceptually kept separate from other components by their state.
All scheduling operations and are as define in [iTIP]. This memo
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
object is the same as saying an [iTIP] object.
A CUA may create a "BOOKED" entry by depositing a iCalendar object
into the store. This is done by depositing an object that does not
have a "METHOD" property. The CS then knows to set the state of the
object to "BOOKED". If the object has a "METHOD" property then the
object is stored in the "UNPROCESSED" state.
If existing "UNPROCESSED" objects exist in the CS for the same 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
and process them in the CUA as described in [iTIP]. Then if the CUA
wished to book the UID, then the CUA would issue a "CREATE" command
to create the new "BOOKED" object in the CS, followed by a "DELETE"
command to remove any related old [iTIP] objects from the CS. And it
might also involve having the CUA send 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
"UNPROCESSED" objects could be deleted from the CS. Or the CUA could
set those object to the marked for delete.
The marked for delete state is used to keep the object around so that
the CUA can process duplicate requests automatically. If a duplicate
[iTIP] object is deposited into the CS and there exists identical
marked for delete objects, then a CUA acting on behalf of the "OWNER"
can silently drop those duplicate entries.
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,
the CUA can book the object, changing the PARTSTAT parameter to
"DECLINED" in the "ATTENDEE" property that corresponds to their UPN.
Perform an iTIP processing such as sending back a decline. Then mark
that object as marked for delete. Their CUA might be configurable to
automatically drop any updates for that object knowing the CU has
already declined.
When synchronizing with multiple CUAs, the marked for delete state
could be used to inform the synchronization process that an object is
to be deleted. How synchronization is done is not specified in this
memo.
Several "UNPROCESSED" entries can be in the CS for the same UID.
However once consolidated, then only one entry exists in the CS and
that is the booked object. The others MUST BE removed, or have their
state changed to "DELETED".
There MUST NOT BE more than one "BOOKED" entry in a calendar for the
same "UID".
For example, if you were on vacation, you could have a REQUEST to
attend a meeting and several updates to that meeting. Your CUA would
have to "SEARCH" them out of the CS using CAP, process them,
determine what the final state of the object from a possible
combination of user input and programmed logic. Then the CUA would
instruct the CS to create a new booked entry from the consolidated
results. Finally, the CUA could do a "DELETE" or change their state
to "DELETED" for all of these now old scheduling requests in the CS.
See [iTIP] for details on resolving multiple [iTIP] scheduling
entries.
3. CAP Design
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 "Calendar User Agent" (CUA) to send commands to and
receive responses from a "Calendar Service". receive responses from a "Calendar Server" (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.
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 and is used to move exchange. [BEEP] is the transport protocol is used to move these
these encapsulations between a CUA and a CS. CAP profile defines the encapsulations between a CUA and a CS. CAP's [BEEP] profile defines
application protocol. That is, the content and semantics of the the application protocol where the content and semantics of the
messages sent between the CUA and the Calendar Service. messages sent between the CUA and the CS are specified.
2.2 Calendar Store Object Model 3.2 Calendar Store Object Model
[RFC2445] describes components such as events, todos, alarms, and [iCAL] describes components such as events, todos, alarms, and
timezones. [CAP] requires more 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.
[CAP] defines the following new objects which will be discussed in
detail in this memo
Component Description
--------- -----------------------------------------
VCAR An access control object
VQUERY A query object
VAGENDA A container that holds components and which is owned
by one or more CUs.
The conceptual model for a calendar store is shown below. The The conceptual model for a calendar store is shown below. The
calendar store contains VCARs, VQUERYs, VTIMEZONEs, VAGENDAs and calendar store (VCALSTORE - Section 8.2) contains "VCAR"s, "VQUERY"s,
calendar store properties. "VTIMEZONE"s, "VAGENDA"s and calendar store properties.
Calendars (VAGENDAs) contain VEVENTs, VTODOs, VJOURNALs, VCARs, Calendars (VAGENDAs) contain "VEVENT"s, "VTODO"s, "VJOURNAL"s,
VTIMEZONEs, VQUERYs and calendar properties. "VCAR"s, "VTIMEZONE"s, "VFREEBUSY", "VQUERY"s and calendar
properties.
The special keyword VCALSTORE is used to denote the a root of the The component "VCALSTORE" is used to denote the a root of the
calendar store. It is a point from which searches can begin. It is calendar store and contains all of the calendars.
the container for VTIMEZONEs, VQUERYs, and toplevel VAGENDAs.
Calendar Store Calendar Store
VCALSTORE VCALSTORE
| |
+-- properties
+-- VCARs +-- VCARs
+-- VQUERYs +-- VQUERYs
+-- VTIMEZONEs +-- VTIMEZONEs
+-- VAGENDA +-- VAGENDAs
| | | |
| +--properties
| +--VEVENTs | +--VEVENTs
| | | | | |
| | +--VALARMs | | +--VALARMs
| +--VTODOs | +--VTODOs
| | | | | |
| | +--VALARMs | | +--VALARMs
| +--VJOURNALs | +--VJOURNALs
| +--VCARs | +--VCARs
| +--VTIMEZONEs | +--VTIMEZONEs
| +--VQUERYs | +--VQUERYs
| +--VAGENDAs | +--VFREEBUSY
| | | | |
| | +--VEVENTs | | ...
| | | | .
| | | +--VALARMs .
| | +--VTODOs +-- VAGENDAs
| | | | . .
| | | +--VALARMs . .
| | +--VJOURNALs . .
| | +--VCARs
| | +--VTIMEZONEs
| | +--VQUERYs
| | +--VFREEBUSY
| | +--VAGENDAs
| | | |
| | | ...
Calendars within a Calendar Store are identified by their Relative Calendars within a Calendar Store are identified by their unique
CALID. Relative CALID.
2.3 Protocol Model 3.3 Protocol Model
The commands listed below are used to manipulate the data on the CAP uses beep as the transport and authentication protocol.
calendar store.
CAP Commands The initial charset MUST BE UTF-8 for the session in an unknown
----------------------------------------------------------- locale. If the CS supplied the BEEP 'localize' attribute in the BEEP
Command Description '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
create Create a new calendar component. the locales supplied by the BEEP 'localize' attribute. If supplied
the first locale supplied in the BEEP 'localize' attribute MUST BE
the default locale of the CS. The locale is switched only after a
successful reply.
delete Delete calendar components. The "DEFAULT-CHARSET" property of the CS contains the list of
generate-uid Generate one or more unique ids. charsets supported by the CS with the first value being the default
get-capability Query the capabilities the CAP server for new calendars. If the CUA wishes to switch to one of those
identify Set a new identity for calendar access. charsets for the session, the CUA issues the "SET-LOCALE" CAP
modify Modify calendar components. command. The CUA would have to first perform a "GET-CAPABILITY"
move Move calendar components to another container. command on the CS to get the list of charsets supported by the CS.
noop Do nothing. The charset is switched only after a successful reply.
search Search for calendar components.
-----------------------------------------------------------
2.4 Security Model The CUA may switch locales and charsets as needed. There is no
requirement that a CS support multiple locales or charsets.
2.4.1 Calendar User and UPNs 3.3.1 Use of BEEP, MIME and iCalendar
CAP uses the BEEP application protocol over TCP. (refer to [BEEP]
and [BEEPTCP] for more information). The default port that the
Calendar Server listens for connections is on user port 1026.
The BEEP data exchanged in CAP is a iCalendar MIME content that fully
conforms to [iCAL] iCalendar format.
This example tells the CS to generate and return 10 UIDs to be used
by the CUA. (Note throughout this memo, 'C:' refers to what the CUA
sends, 'S:' refers to what the CS sends, 'I:' refers to what the
initiator sends, and 'L:' refers to what the listener sends. Where
initiator and responder are used as defined in [BEEP].)
C: MSG 1 2 . 432 62
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: PRODID:-//someone's prodid
C: CMD;ID=unique-per-cua-123;OPTIONS=10:GENERATE-UID
C: END:VCALENDAR
C: END
NOTE: The following examples will not include the BEEP header and
footer information. Only the iCalendar objects that are sent between
the CUA and CS will be shown as the BEEP payload boundaries are
independent of CAP.
The commands listed below are used to manipulate or access the data
on the calendar store:
ABORT - Sent to halt the processing of any command except ABORT.
(Section 9.1.2)
CONTINUE - Sent to continue processing a command that has had its
specified timeout time reached. (Section 9.1.3)
CREATE - Create a new object on the CS. This can be implied for
iTIP objects. Initiated by the CUA only. (Section 9.1.4)
SET-LOCALE - Tell the CS to use any named locale and charset
supplied. Initiated by the CUA only. (Section 9.9)
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)
GENERATE-UID - Generate one or more unique ids. Initiated by the
CUA only. (Section 9.2)
GET-CAPABILITY - Query the capabilities the other end point of the
session. (Section 9.3)
IDENTIFY - Set a new identity for the session. Initiated by the CUA
only. (Section 9.4)
MODIFY - Modify components. Initiated by the CUA only. (Section
9.5)
MOVE - Move components to another container. Initiated by the CUA
only. (Section 9.6)
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.
(Section 9.7)
SEARCH - Search for components. Initiated by the CUA only.
(Section 9.8)
TIMEOUT - Sent when a specified amount of time has lapsed and a
command has not finished. (Section 9.10)
4. Security Model
The BEEP transport performs all session authentication.
4.1 Calendar User and UPNs
A Calendar User (CU) is an entity that can be authenticated. It is A Calendar User (CU) is an entity that can be authenticated. It is
represented in CAP as a UPN, which is a key part of access rights. represented in CAP as a UPN, which is a key part of access rights.
The UPN representation is independent of the authentication mechanism The UPN representation is independent of the authentication mechanism
used during a particular CUA/CS interaction. This is because UPNs used during a particular CUA/CS interaction. This is because UPNs
are used within VCARs. If the UPN were dependent on the are used within VCARs. If the UPN were dependent on the
authentication mechanism, a VCAR could not be consistently evaluated. authentication mechanism, a VCAR could not be consistently evaluated.
A CU may use one mechanism while using one CUA but the same CU may A CU may use one mechanism while using one CUA but the same CU may
use a different authentication mechanism when using a different CUA, use a different authentication mechanism when using a different CUA,
or while connecting from a different location. or while connecting from a different location.
skipping to change at page 14, line 42 skipping to change at page 24, line 34
SASL's authorization identity feature. (The transmitted SASL's authorization identity feature. (The transmitted
authorization identity may be different than the identity in the authorization identity may be different than the identity in the
client's authentication credentials.) [SASL, section 3]. This also client's authentication credentials.) [SASL, section 3]. This also
permits a CU to authenticate using their own credentials, yet request permits a CU to authenticate using their own credentials, yet request
the access privileges of the identity for which they are proxying the access privileges of the identity for which they are proxying
SASL. Also, the form of authentication identity supplied by a SASL. Also, the form of authentication identity supplied by a
service like TLS may not correspond to the UPNs used to express a service like TLS may not correspond to the UPNs used to express a
server's access rights, requiring a server specific mapping to be server's access rights, requiring a server specific mapping to be
done. The method by which a server determines a UPN, based on the done. The method by which a server determines a UPN, based on the
authentication credentials supplied by a client, is implementation authentication credentials supplied by a client, is implementation
specific. See [BEEP] for authentication details specific. See [BEEP] for authentication details; [BEEP] relies on
SASL.
2.4.1.1 UPNs and Certificates 4.1.1 UPNs and Certificates
When using X.509 certificates for purposes of CAP authentication, the When using X.509 certificates for purposes of CAP authentication, the
UPN should appear in the certificate. Unfortunately there is no UPN should appear in the certificate. Unfortunately there is no
single correct guideline for which field should contain the UPN. single correct guideline for which field should contain the UPN.
From RFC-2459, section 4.1.2.6 (Subject): From RFC-2459, section 4.1.2.6 (Subject):
If subject naming information is present only in the If subject naming information is present only in the subjectAlt-
subjectAlt-Name extension (e.g., a key bound only to an email Name extension (e.g., a key bound only to an email address or
address or URI), then the subject name MUST be an empty URI), then the subject name MUST be an empty sequence and the
sequence and the subjectAltName extension MUST be critical. subjectAltName extension MUST BE critical.
Implementations of this specification MAY use these comparison Implementations of this specification MAY use these comparison
rules to process unfamiliar attribute types (i.e., for name rules to process unfamiliar attribute types (i.e., for name
chaining). This allows implementations to process certificates chaining). This allows implementations to process certificates
with unfamiliar attributes in the subject name. with unfamiliar attributes in the subject name.
In addition, legacy implementations exist where an RFC 822 name In addition, legacy implementations exist where an RFC 822 name is
is embedded in the subject distinguished name as an embedded in the subject distinguished name as an EmailAddress
EmailAddress attribute. The attribute value for EmailAddress attribute. The attribute value for EmailAddress is of type
is of type IA5String to permit inclusion of the character '@', IA5String to permit inclusion of the character '@', which is not
which is not part of the PrintableString character set. part of the PrintableString character set. EmailAddress attribute
EmailAddress attribute values are not case sensitive (e.g., values are not case sensitive (e.g., "fanfeedback@redsox.com" is
"fanfeedback@redsox.com" is the same as the same as "FANFEEDBACK@REDSOX.COM").
"FANFEEDBACK@REDSOX.COM").
Conforming implementations generating new certificates with Conforming implementations generating new certificates with
electronic mail addresses MUST use the rfc822Name in the electronic mail addresses MUST use the rfc822Name in the subject
subject alternative name field (see sec. 4.2.1.7 of [RFC alternative name field (see sec. 4.2.1.7 of [RFC 2459]) to
2459]) to describe such identities. Simultaneous inclusion of describe such identities. Simultaneous inclusion of the
the EmailAddress attribute in the subject distinguished name to EmailAddress attribute in the subject distinguished name to
support legacy implementations is deprecated but permitted. support legacy implementations is deprecated but permitted.
Since no single method of including the UPN in the certificate will Since no single method of including the UPN in the certificate will
work in all cases, CAP implementations MUST support the ability to work in all cases, CAP implementations MUST support the ability to
configure what the mapping will be by the CS administrator. configure what the mapping will be by the CS administrator.
Implementations MAY support multiple mapping definitions, for Implementations MAY support multiple mapping definitions, for
example, the UPN may be found in either the subject alternative name example, the UPN may be found in either the subject alternative name
field, or the UPN may be embedded in the subject distinguished name field, or the UPN may be embedded in the subject distinguished name
as an EmailAddress attribute. as an EmailAddress attribute.
Note: If a CS or CUA is validating data received via iMIP, if the Note: If a CS or CUA is validating data received via iMIP, if the
"ORGANIZER" or "ATTENDEE" property said (e.g.) "ATTENDEE;CN=Joe "ORGANIZER" or "ATTENDEE" property said (e.g.) "ATTENDEE;CN=Joe
Random User: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:juser@example.com" and have it pass validation. Rictus User:MAILTO:jrictus@example.com" and have it pass validation.
This validation will also defeat other attempts at confusion. Note that it is the email addresses that miscompare, the CN
miscompare is irrelevant.
2.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
publish calendar information that does not require any access control publish calendar information that does not require any access control
for viewing or login. Conversely, a user may wish to view for viewing or login. Conversely, a user may wish to view
unrestricted calendar information without revealing their identity. unrestricted calendar information without revealing their identity.
2.4.1.3 User Groups 4.1.3 User Groups
A User Group is used to represent a collection of CUs or other UGs A User Group is used to represent a collection of CUs or other UGs
that can be referenced in VCARs. A UG is represented in CAP as a that can be referenced in VCARs. A UG is represented in CAP as a
UPN. The CUA cannot distinguish between a UPN that represents a CU UPN. The CUA cannot distinguish between a UPN that represents a CU
or a UG. or a UG.
UGs are expanded as necessary by the CS. The CS MAY expand a UG UGs are expanded as necessary by the CS. The CS MAY expand a UG
(including nested UGs) to obtain a list of unique CUs. Duplicate (including nested UGs) to obtain a list of unique CUs. Duplicate
UPNs are filtered during expansion. UPNs are filtered during expansion.
The CS should not preserve UG expansions across operations. A UG may How the UG expansion is maintained across commands is implementation
reference a static list of members, or it may represent a dynamic specific. A UG may reference a static list of members, or it may
list. Each operation SHOULD generate its own expansion in order to represent a dynamic list. Operations SHOULD recognize changes to UG
recognize changes to UG membership. membership.
CAP does not define commands or methods for managing UGs. CAP does not define commands or methods for managing UGs.
2.4.2 Access Rights - Summary 4.2 Access Rights
Access rights are used to grant or deny access to a calendar for a Access rights are used to grant or deny access to calendars,
CU. CAP defines a new component type called a Calendar Access Right components, properties, and parameters in a CS to a CU. CAP defines
(VCAR). Specifically, a VCAR grants, or denies, UPNs the right to a new component type called a Calendar Access Right (VCAR).
Specifically, a "VCAR" component grants, or denies, UPNs the right to
read and write components, properties, and parameters on calendars read and write components, properties, and parameters on calendars
within a CS. within a CS.
The VCAR model does not put any restriction on the sequence in which The VCAR model does not put any restriction on the sequence in which
the object and access rights are created. That is, an event the object and access rights are created. That is, an object
associated with a particular VCAR might be created before or after associated with a particular VCAR might be created before or after
the actual VCAR is defined. In addition, the VCAR and VEVENT the actual VCAR is defined. In addition, the VCAR and VEVENT
definition might be created in the same iCalendar object and passed definition might be created in the same iCalendar object and passed
together in a single object. 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 right
that denies access always takes precedence over the right that grant that denies access always takes precedence over the right that grants
access. access. Any attempt to create a VCAR that conflicts with an
immutable VCAR must fail.
2.4.2.1 Calendar Access Right (VCAR) 4.2.1 Access Control and NOCONFLICT
Access rights within CAP are specified with the "VCAR" calendar The TRANSP property can take on values "TRANSPARENT-NOCONFLICT" and
component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID" "OPAQUE-NOCONFLICT" that prohibit other components from overlapping
component properties. it. This setting overrides access. The "ALLOW-CONFLICT" CS,
Calendar or component setting may also prevent overlap, returning an
error code "6.3".
4.2.2 Calendar Access Right (VCAR)
Access rights within CAP are specified with the "VCAR" component,
"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" properties.
For details on the VCAR syntax please see section Section 2.4.2 4.2.3 Predefined VCARs
2.4.2.2 Predefined VCARs
Predefined calendar access CARIDs that MUST be implemented are: Predefined calendar access CARIDs that MUST BE implemented are:
CARID:READBUSYTIMEINFO - grants all authenticated users the right to CARID:READBUSYTIMEINFO - Specifies the "GRANT" and "DENY" rules that
read VFREEBUSY components. Suggested definition for this VCAR: allow UPNs to read "VFREEBUSY" components. An example definition
for this VCAR is:
BEGIN:VCAR BEGIN:VCAR
CARID:READBUSYTIMEINFO CARID:READBUSYTIMEINFO
BEGIN:VRIGHT BEGIN:VRIGHT
GRANT:* GRANT:*
PERMISSION:READ PERMISSION:READ
SCOPE:SELECT * FROM VFREEBUSY SCOPE:SELECT * FROM VFREEBUSY
END:VRIGHT END:VRIGHT
END:VCAR END:VCAR
CARID:REQUESTONLY - grants to users other than the owner of the CARID:REQUESTONLY - Specifies the "GRANT" and "DENY" rules to UPNs
calendar the right to write new events with the property METHOD set other than the owner of the calendar the ability to write new
to REQUEST. Suggested definition for this VCAR: objects with the property "METHOD" property set to the "REQUEST"
value. This CARID allows the owner to specify which UPNs are
allowed to make scheduling requests. An example definition for
this VCAR is:
BEGIN:VCAR BEGIN:VCAR
CARID:REQUESTONLY CARID:REQUESTONLY
BEGIN:VRIGHT BEGIN:VRIGHT
GRANT:NONOWNER GRANT:NON OWNER()
PERMISSION:WRITE PERMISSION:CREATE
RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST' RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST'
END:VRIGHT END:VRIGHT
END:VCAR END:VCAR
CARID:UPDATEPARTSTATUS - grants all 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 their modify the instances of the "ATTENDEE" property set to one of
calendar adresses in the VEVENT and VTODO components for which the their calendar addresses in any components for any booked
ORGANIZER property is set to the address of the VAGENDA in which the component containing a "ATTENDEE" property. This allows (or
VEVENT or VTODO is stored, given that the submitted value of the denies) a CU the ability to update their own participation status
ATTENDEE property is one of their calendar adresses. Suggested in a calendar where they might not otherwise have MODIFY access.
definition for this VCAR: They are not allowed to change the "ATTENDEE" property value. An
example definition for this VCAR is (This example only effects the
"VEVENT" components):
BEGIN:VCAR BEGIN:VCAR
CARID:UPDATEPARTSTATUS CARID:UPDATEPARTSTATUS
BEGIN:VRIGHT BEGIN:VRIGHT
GRANT:* GRANT:*
PERMISSION:MODIFY PERMISSION:MODIFY
SCOPE:SELECT att FROM VEVENT SCOPE:SELECT ATTENDEE FROM VEVENT
USING_PROPERTIES ATTENDEE att WHERE ATTENDEE = SELF()
WHERE SELF() IN CAL-OWNERS(att) AND ORGANIZER = CURRENT-CALID() AND ORGANIZER = CURRENT-TARGET()
AND STATE() = 'BOOKED'
RESTRICTION:SELECT * FROM VEVENT RESTRICTION:SELECT * FROM VEVENT
WHERE SELF() IN CAL-OWNERS(ATTENDEE) WHERE ATTENDEE = SELF()
END:VRIGHT
BEGIN:VRIGHT
GRANT:*
PERMISSION:MODIFY
SCOPE:SELECT att FROM VTODO
USING_PROPERTIES ATTENDEE att
WHERE SELF() IN CAL-OWNERS(att) AND ORGANIZER = CURRENT-CALID()
RESTRICTION:SELECT * FROM VTODO
WHERE SELF() IN CAL-OWNERS(ATTENDEE)
END:VRIGHT END:VRIGHT
END:VCAR END:VCAR
CARID:DEFAULTOWNER - grants to the owner all permissions on all the CARID:DEFAULTOWNER - Grants to any owner the permission they have
objects in the calendar. Suggested definition for this VCAR: 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:OWNER()
PERMISSION:* PERMISSION:*
SCOPE:SELECT * FROM VAGENDA SCOPE:SELECT * FROM VAGENDA
END:VRIGHT END:VRIGHT
END:VCAR END:VCAR
2.4.2.3 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 are configured by the CS administrator, which apply to all that may be configured by the CS administrator. A reply from the CS
calendars on the server. may dynamically create VCARs that are decreed depending on the
implementation. To the CUA any "VCAR" component with the "DECREED"
property set to "TRUE" can not be changed by the currently
authenticated UPN, and depending on the implementation and other
VCARs; might not be able to be changed by any UPN using 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 an error
will be returned, indicating that the user has insufficient will be returned indicating that the user has insufficient
authorization to perform the operation. The reply to the CUA MUST BE authorization to perform the operation. The reply to the CUA MUST BE
the same as if a non-decreed VCAR caused the failure. the same as if a non-decreed VCAR caused the failure.
The CAP protocol does not define the semantics used to initially The CAP protocol does not define the semantics used to initially
create a decreed VCAR. This administrative task is outside the scope create a decreed VCAR. This administrative task is outside the scope
of the CAP protocol. of the CAP protocol.
For example an implementation or a CS administrator may wish to For example; an implementation or a CS administrator may wish to
define a VCAR that will always allow the calendar owners to have full define a VCAR that will always allow the calendar owners to have full
access to their own calendars. The GRANT property allows the OWNERs access to their own calendars.
all access to their own calendar objects. The DENY property
disallows anyone (UPN=*) from being able to delete or modify this
VCAR.
BEGIN:VCAR
CARID:ctjmocfbr-01
NAME:Users Default Access
DECREED:TRUE
BEGIN:VRIGHT
GRANT:OWNER
PERMISSION:*
SCOPE:SELECT * FROM VAGENDA
END:VRIGHT
BEGIN:VRIGHT
DENY:*
PERMISSION:DELETE
PERMISSION:MODIFY
SCOPE:SELECT * FROM VCAR WHERE CARID = 'ctjmocfbr-01'
END:VRIGHT
END:VCAR
Decreed VCARs MUST BE readable by the calendar owner in standard VCAR Decreed VCARs MUST BE readable by the calendar owner in standard VCAR
format. format.
2.4.3 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" CAP command. The Calendar Service only permits the "IDENTIFY" command. The Calendar Server only permits the operation
operation if the session's authentication credentials are good for if the session's authentication credentials are good for the
the requested identity. The method of checking this permission is requested identity. The method of checking this permission is
implementation dependent, but may be thought of as a mapping from implementation dependent, but may be thought of as a mapping from
authentication credentials to UPNs. The "identify" command allows a authentication credentials to UPNs. The "IDENTIFY" command allows a
single set of authentication credentials to choose from multiple single set of authentication credentials to choose from multiple
identities, and allows multiple sets of authentication credentials to identities, and allows multiple sets of authentication credentials to
assume the same identity. assume the same identity.
For anonymous access the identity of the session is "@", a UPN with a For anonymous access the identity of the session is "@". A UPN with
null Username and null Realm. A UPN with a null Username, but non- a null Username and null Realm is anonymous. A UPN with a null
null Realm, such as "@foo.com" may be used to mean any identity from Username, but non-null Realm, such as "@foo.com" may be used to mean
that Realm, which is useful to grant access rights to all users in a any identity from that Realm, which is useful to grant access rights
given Realm. A UPN with a non-null Username and null Realm, such as to all users in a given Realm. A UPN with a non-null Username and
"bob@" could be a security risk and MUST NOT be used. null Realm, such as "bob@" could be a security risk and MUST NOT be
used.
Since the UPN includes Realm information it may be used to govern Since the UPN includes Realm information it may be used to govern
calendar store access rights across Realms. However, governing calendar store access rights across Realms. However, governing
access rights across Realms is only useful if login access is access rights across Realms is only useful if login access is
available. This could be done through a trusted server relationship available. This could be done through a trusted server relationship
or a temporary account. Note that trusted server relationships are or a temporary account. Note that trusted server relationships are
outside the scope of [CAP]. outside the scope of [CAP].
The "identify" command provides for a weak group implementation. By The "IDENTIFY" command also provides for a weak group implementation.
allowing multiple sets of authentication credentials belonging to By allowing multiple sets of authentication credentials belonging to
different users to identify as the same UPN, that UPN essentially different users to identify as the same UPN, that UPN essentially
identifies a group of people, and may be used for group calendar identifies a group of people, and may be used for group calendar
ownership, or the granting of access rights to a group. ownership, or the granting of access rights to a group.
2.5 Roles 5. CAP URL and Calendar Address
CAP defines methods for managing [RFC2445] objects in a Calendar
Store and exchanging [RFC2445] objects for the purposes of group
calendaring and scheduling between "Calendar Users" (CUs) or "User
Groups" (UGs). There are two distinct roles taken on by CUs in CAP.
The CU who creates an initial event or to-do and invites other CUs as
attendees takes on the role of "Organizer". The CUs asked to
participate in the event or to-do take on the role of "Attendee".
Note that "role" is also a descriptive parameter to the "ATTENDEE"
property. Its use is to convey descriptive context to an "Attendee"
such as "chair", "REQ-PARTICIPANT" or "NON-PARTICIPANT" and has
nothing to do with the scheduling workflow.
2.6 CAP URL
The CAP URL scheme is used to designate calendar stores, and The CAP URL scheme is used to designate calendar stores and calendars
calendars accessible using the CAP protocol. accessible using the CAP protocol.
The CAP URL scheme conform to the generic URL syntax, defined in RFC The CAP URL scheme conform to the generic URL syntax, defined in RFC
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 = scheme ":" [ "//" csid ] [ "/" relcalid ] capurl = "cap://" csid [ "/" relcalid ]
scheme = "cap"
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 'relcalid' is an identifier that uniquely identifies a calendar on a
particular calendar store. There is no implied structure in 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/abcd1234QWER cap://cal.example.com/Company/Holidays
cap://cal.example.com/abcd1234Usr
Relative CAP URLs are permitted and are resolved according to the Relative CAP URLs are permitted and are resolved according to the
rules defined in Section 5 of RFC 2396. rules defined in Section 5 of RFC 2396.
Example of a relative CAP URL: Examples of valid relative CAP URLs:
abcd1234QWER
2.7 Calendar Addresses
Calendar addresses can be described as absolute or relative CAP URLs.
Examples:
cap://cal.example.com/abcd1234QWER
abcd1234QWER
For a user currently authenticated to the CAP server on
cal.example.com, these two calendar addresses refer to the same
calendar.
2.8 Extensions to iCalendar
In mapping the calendar query feature, and access rights onto the
iCalendar format, several extended iCalendar properties and
components are defined by this memo.
The search operation makes use of a new component, called VQUERY.
The component consists of a set of new properties: QUERY, EXPAND,
NAME and QUERYID, that define a search filter. VQUERY is used by the
following CAP commands: "search", "modify", "move" and "delete".
Access rights are specified in the new iCalendar VCAR component.
Calendar are specified by the new VAGENDA component.
2.9 Relationship of RFC 2446 (ITIP) to CAP
[iTIP] describes scheduling methods which result in indirect
manipulation of calendar components. In CAP, the "create" command is
used to submit scheduling requests. Other CAP commands such as
"create", "delete", "modify" and "move" provide direct manipulation
of calendar components. In the CAP calendar store model, scheduling
messages are conceptually kept separate from other calendar
components.
When scheduling is used, the METHOD is saved along with components.
A scheduled component becomes a booked component when its METHOD
property is set to CREATE. For example, a component whose METHOD is
"REQUEST" is scheduled. The component becomes booked when the METHOD
is set to "CREATE".
Several scheduled entries can be in the CS for the same UID. They
are consolidated when booked, or they are removed from the CS.
For example, if you were on vacation, you could have a REQUEST to
attend a meeting and several updates to that meeting. Your CUA would
have to "search" them out of the CS using CAP, process them,
determine what the final state of the object from a possible
combination of user input and programmed logic. Then the CUA would
instruct the CS to "create" a new booked entry or "modify" an
existing entry. Finally, the CUA can do a "delete" of all of these
now old scheduling requests in the CS. See [iTIP] for details on
resolving multiple [iTIP] scheduling entries.
3. Protocol Framework
CAP uses the BEEP application protocol kernel mapped onto TCP (refer
to [BEEP] and [BEEPTCP] for more information). The default port that
the Calendar Service listens for connections on is port --TBD--.
3.1 BEEP Exchange Styles
[BEEP] defines three styles of message exchange:
MSG/ANS,ANS,...,NUL: for one-to-many exchanges.
MSG/RPY: for one-to-one exchanges.
MSG/ERR: for requests the cannot be processed due to an error.
A CAP request, targeted at more than one containers, MUST use a one-
to-many exchange, with a distinct answer associated with each target.
CAP request targeted at a single container MAY use a one-to-one
exchange or a one-to-many exchange. "MSG/ERR" MAY only be used when
an error condition prevents the execution of the request on all the
targeted calendars.
3.2 Use BEEP, MIME and iCalendar
NOTE: This topic is under debate and all CAP commands might drop the
XML wrapper and just send the text/calendar objects and it would
contain the command.
Each BEEP payload exchanged via CAP is a iCalendar MIME content that
fully conforms to [RFC2445].
C: MSG 1 2 . 432 62
C: Content-Type: application/cap+xml
C:
C: <generate-uid num="10"/>
C: END
Otherwise, arbitrary MIME content is included in the BEEP payload
using CDATA.
C: MSG 1 3 . 1023 951
C: Content-type: application/cap+xml
C:
C: <create>
C: <![CDATA[
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: METHOD:REQUEST
C: CMDID:abcd12346
C: BEGIN:VEVENT
C: UID:abcd12345
C: ORGAGNIZER:cap://cal.example.com/mary-relcalid
C: ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.example.com/mary-relcalid
C: ATTENDEE;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:cap://cal.example.com/john-relcalid
C: ATTENDEE;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:cap://cal.example.com/bob-relcalid
C: DTSTART:20010920T180000Z
C: DTEND:20010920T190000Z
C: SUMMARY:Mary invites John and Robert
C: END:VEVENT
C: END:VCALENDAR
C: ]]>
C: </create>
C: END
NOTE: From this point on many of the examples will not include the opqaueXzz123String
BEEP header and footer information. Only the iCalendar objects that UserName/Personal
are sent between the CUA and CS will be shown as the BEEP payload
boundries are independant of CAP.
3.3 Bounded Latency A Calendar addresses can be described as qualified or relative CAP
URLs.
A CUA can associate a maximum latency time to a CAP command with the For a user currently authenticated to the CS on cal.example.com,
"latency" argument. If the CS is unable to complete the request in these two example calendar addresses refer to the same calendar:
the specified amount of time, then the CS sends a "timeout" MSG on
the same channel to which the CUA MUST reply with an "abort" or a
"continue" reply.
Upon receiving an "abort" reply, the CS MUST terminate the command in cap://cal.example.com/abcd1234USR
progress. abcd1234USR
When receiving a "continue" reply the server resumes its work in 6. New Components, Properties, Parameters, and Values
progress. Note that a new latency time MAY be included in a
"continue" reply.
The timeout argument and the "action" MUST both be added to the CAP The following sections contains new components, properties,
command, or nether can be added to a command. The "latency" value parameters, and value definitions.
MUST BE set to the maximum latency time in seconds. The "action"
argument accepts the following values: "ask" and "abort". If the
maximum latency time is exceeded and the "action" argument is set to
"ask", then CS MUST send a "timeout" message to inform the CUA,
otherwise if the argument "action" is set to "abort" the CS can
directly terminate the request and return a request-status code
2.0.3.
Example: The purpose of these is to extend the iCalendar objects in a
compatible way so that existing iCalendar VERSION 2.0 parsers can
still parse the objects without modification.
In this example bill@cal.example.com attempts to read a calendar but 6.1 Property Value Data Types
the latency time he supplies is not sufficient for the server to
complete the command.
C: MSG 1 4 . 2043 680 6.1.1 CAL-QUERY Value Type
C: Content-Type: application/cap+xml
C:
C: <search latency="3" action="ask">
C: <![CDATA[
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: METOD:SEARCH
C: TARGET:relcalid-123
C: CMDID:xyz12346
C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID FROM VEVENT
C: WHERE DTEND >= '19990714T080000Z' AND
C: DTSTART <= '19990715T080000Z'
C: END:VQUERY
C: END:VCALENDAR
C: ]]>
C: </search>
C: END
# After 3 seconds Subject: Registration of text/calendar MIME value type CAL-QUERY
S: MSG 1 2 . 102 64
S: Content-Type: application/cap+xml
S:
S: <timeout cmdid="xyz12346"/>
S: END
If Bill wants to continue and give the server more time he would Value Name: CAL-QUERY
issue a "continue" reply:
C: RPY 1 2 . 166 113 Value Type Purpose: This value type is used to identify values and
C: Content-Type: application/cap+xml contains query statements targeted at locating those values.
C:
C: <continue cmdid="xyz12346" latency="3" action="ask"/>
C: END
If instead, Bill wanted to abort the command and not wait any further This is based on [SQL92] and [SQLCOM].
he would issue an "abort" reply:
C: RPY 1 2 . 166 62 1. For the purpose of a query, all components should be handled as
C: Content-Type: application/cap+xml tables, and the properties of those components, should be handled
C: as columns.
C: <abort cmdid="xyz12346"/>
C: END
S: RPY 1 4 . 2723 114 2. All VAGENDAs and CS's look like tables for the purpose of a
S: QUERY. And all of their properties look like columns in those
S: <request-status code="2.0.3"> tables.
S: Request Aborted by the CUA.
S: </request-status>
S: END
4. New Value Types 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
in the the FROM clause.
4.1 CAL-QUERY Value Type 4. Everything in the SELECT and WHERE clauses MUST BE from the same
component type, or VAGENDA OR VCALSTORE in the FROM clause.
Subject: Registration of text/calendar MIME value type CAL-QUERY 5. When multiple QUERY properties are supplied in a single VQUERY
component, the results returned are the same as the results
returned for multiple VQUERY components having each a single
QUERY property and the results are return in the same order as
the VQUERYs were specified in the original command.
Value Name: CAL-QUERY 6. The '.' is used to separate the table name (component) and column
name (property or component) when selecting a property that is
contained inside of a component that is targeted in the TARGET
property.
Value Type Purpose: This value type is used to identify values 7. A contained component without a '.' is not the same as
and contains query statements targeted at locating those values. "component-name.*". If given as "component-name" (no dot) the
the encapsulating BEGIN/END statement will be supplied for
"component-name".:
This was based on [SQL92] and [SQLCOM]. In this example the '.' is used to separate the TRIGGER property from
NOTE: This grammar is NOT SQL92. its contained component (VALARM) which is contained in any VEVENT in
the selected TARGET (relcalid). All TRIGGER values in any VEVENT in
relcalid would be returned.
(1) For the purpose of a query, all components should be TARGET:relcalid
handled as tables, and the properties of those QUERY:SELECT VALARM.TRIGGER FROM VEVENT
components, should be handled as columns.
(2) All VAGENDAs and CS's look like tables for the purpose of a SELECT VALARM FROM VEVENT WHERE UID = "123"
QUERY. And all of their properties look like columns in
those tables.
(3) You CAN NOT do any cross component-type joins. And that means This return one BEGIN/END VALARM for each VALARM in the VEVENT
you can ONLY have one component, OR one VAGENDA OR one CALSTORE as there is no '.' (dot) in the VALARM:
in the the FROM clause.
(4) Everything in the SELECT and WHERE clauses MUST BE from the BEGIN:VALARM
component type, or VAGENDA OR CALSTORE in the FROM clause. TRIGGER;RELATED=END:PT5M
This includes the values from the USING_PROPERTIES and REPEAT:4
USING_COMPONENTS clauses. ...
END:VALARM
BEGIN:VALARM
TRIGGER;RELATED=START:PT5M
DURATION:PT10M
...
END:VALARM
...
...
(5) The '.' is used to separate the table name (component) If provided as "component-name.*", then only the properties and any
and column name (property) when selecting a property that contained components will be returned:
is contained inside of a component that is targeted in
the TARGET property.
In this example the '.' is used to separate the SELECT VALARM.* FROM VEVENT WHERE UID = "123"
TRIGGER property from its contained component (VALARM)
which is contained in any VEVENT in the selected TARGET
(relcalid). All TRIGGER values in any VEVENT in relcalid
would be returned.
TARGET:relcalid Will return the properties in each VALARM in the VEVENT:
QUERY: SELECT VALARM.TRIGGER FROM VEVENT
(6) A contained component without a '.' it is the same as TRIGGER;RELATED=END:PT5M
<component>.* with the result being a properly formatted REPEAT:4
<component>(s) in the data stream, and correctly formatted ...
in the contained component(s) in iCalendar (RFC2445) format. TRIGGER;RELATED=START:PT5M
DURATION:PT10M
...
...
(a) SELECT VEVENT.<a-property-name> FROM VEVENT (a) SELECT VEVENT.<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: (a) Selects all instances of <a-property-name>
from all VEVENT components. from all VEVENT components.
(b) and (c) Select all VALARM components from all (b) and (c) Select all VALARM components from all
VEVENT components. VEVENT components. (b) would return then in
BEGIN/END VALARM tags. (c) would return all
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 with a TRIGGER property value between the provided
dates and times. dates and times.
NOT VALID: NOT VALID:
(f) SELECT VEVENET.VALARM.TRIGGER FROM VEVENT (f) SELECT VEVENET.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: (g) 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.
(h) 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.
(7) When multiple QUERY properties are supplied in a single VQUERY
component, the results returned are the same as the results
returned for multipled VQUERY components having each a single
QUERY property.
Formal Definition: The value type is defined by the following Formal Definition: The value type is defined by the following
notation: notation:
comp-name = "VEVENT" / "VTODO" / "VJOURNAL" comp-name = "VEVENT" / "VTODO" / "VJOURNAL"
/ "VTIMEZONE" / "VALARM" / "VFREEBUSY" / "VTIMEZONE" / "VALARM" / "VFREEBUSY"
/ "VAGENDA" / "VCAR" / "CALSTORE" / "VAGENDA" / "VCAR" / "VCALSTORE"
/ "VQUERY" / iana-name / x-comp / "VQUERY" / iana-name / x-comp
querycomp = queries / ( queryname queries) / queryname querycomp = queries
queryname = "QUERYNAME" *(";" xparam) ":" text CRLF ; 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
/ queries query / queries query
query = "QUERY" *(";" xparam) ":" cal-query CRLF
; NOTE: There is exactly one space separating ; NOTE: There is exactly one space separating
; the various parts of cal-query ; the various parts of cal-query
; ;
cal-query = "SELECT" SP cap-cols SP cal-query = "SELECT" SP cap-cols SP
"FROM" SP comp-name SP "FROM" SP comp-name SP
*(cauprops SP / capcprops 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
capuprops = "USING_PROPERTIES" SP uprop-list
uprop-list = (cap-col SP cap-local) uprop-list = (cap-col SP cap-local)
/ uprop-list SP cap-col SP cap-local / uprop-list SP cap-col SP cap-local
capcprops = "USING_COMPONENTS" SP cprop-list
cprop-list = (cap-comp cap-local) cprop-list = (cap-comp cap-local)
/ cprop-list SP cap-col SP cap-local / cprop-list SP cap-col SP cap-local
cap-col = ; Any property name found in the component cap-col = ; Any property name found in the component
; named in the comp-tbl used in the FROM clause. ; named in the comp-tbl used in the FROM clause.
; ;
; SELECT ORGANIZER FROM VEVENT ... ; SELECT ORGANIZER FROM VEVENT ...
; ;
; OR ; OR
; ;
skipping to change at page 30, line 27 skipping to change at page 37, line 41
; conflict with any existing or future cap-col name. ; conflict with any existing or future cap-col name.
; This name MUST BE defined in the cap-using and ; This name MUST BE defined in the cap-using and
; can only be used in cap-expr of the same query. ; can only be used in cap-expr of the same query.
; And this name is only known and valid for the ; And this name is only known and valid for the
; provided query and only for the lifetime of ; provided query and only for the lifetime of
; the query. If multiple QUERY properties exist ; the query. If multiple QUERY properties exist
; in the same component, it is only valid and usable ; in the same component, it is only valid and usable
; in the same QUERY property where it was supplied. ; 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-address ")" / "CAL-OWNERS(" cal-address ")"
/ "CURRENT-CALID()" / "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
; column that is being compared. That is you can ; column that is being compared. That is you can
; not compare PRIORITY to "some string" because ; not compare PRIORITY to "some string" because
; PRIORITY has a value type of integer. If it is ; PRIORITY has a value type of integer. If it is
; not preceded by the LIKE element, any '%' and '_' ; not preceded by the LIKE element, any '%' and '_'
skipping to change at page 31, line 22 skipping to change at page 38, line 38
/ cap-factor / cap-factor
cap-factor = cap-colval SP cap-oper SP col-value cap-factor = cap-colval SP cap-oper SP col-value
/ cap-colval SP "NOT LIKE" SP col-value / cap-colval SP "NOT LIKE" SP col-value
/ cap-colval SP "LIKE" SP col-value / cap-colval SP "LIKE" SP col-value
/ cap-colval SP "IS NULL" / cap-colval SP "IS NULL"
/ cap-colval SP "IS NOT NULL" / cap-colval SP "IS NOT NULL"
/ col-value SP "NOT IN" cap-colval" / col-value SP "NOT IN" cap-colval"
/ col-value SP "IN" cap-colval" / col-value SP "IN" cap-colval"
cap-colval = cap-ucol cap-colval = cap-ucolq
/ "PARAM(" cap-ucol "," cap-param ")" / "PARAM(" cap-ucol "," cap-param ")"
cap-oper = "=" cap-oper = "="
/ "!=" / "!="
/ "<" / "<"
/ ">" / ">"
/ "<=" / "<="
/ ">=" / ">="
cap-logical = "AND" / "OR" cap-logical = "AND" / "OR"
skipping to change at page 31, line 45 skipping to change at page 39, line 13
; (value in HEX %x20). ; (value in HEX %x20).
CRLF = ; As defined in RFC 2445. CRLF = ; As defined in RFC 2445.
xparam = ; As defined in RFC 2445. xparam = ; As defined in RFC 2445.
x-prop = ; As defined in RFC 2445. x-prop = ; As defined in RFC 2445.
x-comp = ; As defined in RFC 2445. x-comp = ; As defined in RFC 2445.
4.1.1 CAP-QL notes 6.1.1.1 CAL-OWNERS()
(1) There is no ORDERBY. Sorting will take place in the order the This function returns the list of "OWNERS" for the named calendar.
columns are supplied in the command.
Float and integer values MUST BE sorted by their numeric value. 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
target is a "VAGENDA", it returns the "CALMASTER" value.
This means the result of a sort on an integer value type will be: If called as 'CAL-OWNERS(cal-address)', then it is the equivalent to
the comma separated list of owners for the named calendar id.
6.1.1.2 CURRENT-TARGET()
Is equivalent to the value of the "TARGET" property in the current
command. Used in a CAL-QUERY 'WHERE' clause.
6.1.1.3 [NOT] OWNER()
Returns true if the current UPN is an owner of the current "TARGET".
Used in a CAL-QUERY 'WHERE' clause and in the UPN-FILTER.
6.1.1.4 SELF()
Used in a CAL-QUERY 'WHERE' clause. Returns the UPN of the currently
authenticated CU.
6.1.1.5 STATE()
Returns one of three values, 'BOOKED', 'UNPROCESSED', or 'DELETED'
depending on the state of the object. Used in a CAL-QUERY 'WHERE'
clause.
6.1.1.6 Ordering of Results
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
MAY sort additional columns.
Float and integer values MUST BE sorted by their numeric value. This
means the result of a sort on an integer value type will be:
1, 2, 100, 1000 1, 2, 100, 1000
and not and not
1, 100, 1000, 2 1, 100, 1000, 2
This means the result of a sort on an float value type will be: This means the result of a sort on an float value type will be:
1.1, 2.23, 100.332, 1000.12 1.1, 2.23, 100.332, 1000.12
and not and not
1.1, 100.332, 1000.12, 2.23 1.1, 100.332, 1000.12, 2.23
Date and date time values will be sorted by their equivalent Date and date time values will be sorted by their equivalent value in
value in UTC. No matter what the returned time zone in the result UTC. No matter what the returned time zone in the result set
set returns. This is so that if multiple components are returned returns. This is so that if multiple components are returned each in
each in a unique time zone, the results will be sorted in UTC. a unique time zone, the results will be sorted in UTC. This does not
This does not mean the values must be converted to UTC in the mean the values MUST BE converted to UTC in the data returned to the
data returned to the CUA. It means the CS must do the sort in UTC. CUA. It means the CS must do the sort in UTC.
All other values are sorted according to the locale sorting order All other values are sorted according to the locale sorting order as
as specified in the calendar. Or the CS locale if the calendar specified in the command. Or the calendar locale if known, or the CS
does not have any locale set, or the host operating system locale if the calendar does not have any locale set. And the locale
locale if the CS does not specify a locale. And the locale to to use for the sort is determined in that order.
use for the sort is determined in that order.
(2) The CS MUST sort at least the first column. 6.1.1.7 Date sorting order
The CS MAY sort additional columns.
(3) If the cap-cols is only "*" and nothing else, then: If the cap-cols is only "*" and nothing else and the result set has a
DTSTART, then:
If EXPAND=FALSE sorting will be by the DTSTART value If EXPAND=FALSE sorting will be by the DTSTART value ascending as if
ascending. it were in UTC.
If EXPAND=TRUE sorting will be by the RECURRENCE-ID value If EXPAND=TRUE sorting will be by the RECURRENCE-ID value ascending
ascending. as if it were in UTC.
If one or more DTSTART or RECURRENCE-ID components have If one or more DTSTART or RECURRENCE-ID components have exactly the
exactly the same value, the order for those matching same value, the order for those matching components is unspecified.
components is unspecified.
If the selected component(s) do not contain a DTSTART If the selected component(s) do not contain a DTSTART or a
or a RECURRENCE-ID, then the order is unspecified. RECURRENCE-ID, then the order is unspecified.
(4) All literal values are surrounded by single quotes ('), not If an instance does not have a RECURRENCE-ID and the query compares
double quotes ("), and not without any quotes. If the value RECURRENCE-IDs (comparing a RECURRENCE-ID to the date or date/time of
contains quotes or any other ESCAPED-CHAR, they must be a single instance object), then the CS MUST compare the DTSTART value
backslash escaped as described in section "4.3.11 Text" as if it were a RECURRENCE-ID even for single instance objects that
of RFC2445. Any LIKE wildcard characters that are part do not contain a RECURRENCE-ID.
of any literal data that is preceded by a LIKE clause and
is not intended to mean wildcard search, MUST BE escaped as
described in note (7) below.
(5) When comparing DATE-TIME to DATE value types and when A component with a DATE and no TIME value is returned before objects
comparing DATE to DATE-TIME value types, the result will with both a DATE and TIME value when the dates of those two (or more)
be true if the DATE value is on the same day as the DATE-TIME objects are the same, sorted by date.
value. And they are compared in UTC no matter what time zone
the data may actual have been stored in. 6.1.1.8 Use of single quote
All literal values are surrounded by single quotes ('), not double
quotes ("), and not without any quotes. If the value contains quotes
or any other ESCAPED-CHAR, they MUST BE backslash escaped as
described in section "4.3.11 Text" of RFC2445. Any LIKE wildcard
characters that are part of any literal data that is preceded by a
LIKE clause and is not intended to mean wildcard search, MUST BE
escaped as described in note (7) below.
6.1.1.9 Comparing DATE and DATE-TIME values
When comparing DATE-TIME to DATE value types and when comparing DATE
to DATE-TIME value types, the result will be true if the DATE value
is on the same day as the DATE-TIME value. And they are compared in
UTC no matter what time zone the data may actual have been stored in.
VALUE-1 VALUE-2 Compare Results 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-4) (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 comparing DATE and DATE-TIME values with the LIKE When the DATE or DATE-TIME value is not associated with a time zone,
clause the comparison will be done as if the value is then the CS will compare the value assuming that the no time zone
a RFC2445 DATE or DATE-TIME string value. values are in the calendars default time zone.
When comparing DATE and DATE-TIME values with the LIKE clause the
comparison will be done as if the value is a RFC2445 DATE or DATE-
TIME string value.
LIKE '2002%' will match anything in the year 2002. LIKE '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
two consecutive zeros.
Again all comparisons will be done in UTC. Again all comparisons will be done in UTC.
Using a LIKE value of "%00%, would return any value that 6.1.1.10 DTEND and DURATION
contained two consecutive zeros.
(6) DTEND and DURATION. When a QUERY contains a DTEND value, then the CS MUST also evaluate
any existing DURATION property value and determine if it has an
effective end time that matches the QUERY supplied DTEND value or any
range of values supplied by the QUERY.
When a QUERY contains a DTEND value, then the CS MUST also When a QUERY contains a DURATION value, then the CS MUST also
evaluate any existing DURATION property value and determine evaluate any existing DTEND property value and determine if it has an
if it has an effective end time that matches the QUERY effective duration that matches the QUERY supplied DURATION value or
supplied DTEND value or any range of values supplied by any range of values supplied by the QUERY.
the QUERY.
When a QUERY contains a DURATION value, then the CS MUST As DTEND is the first time that is excluded from a components time
also evaluate any existing DTEND property value and determine range, any DURATION supplied by the QUERY that is exactly one second
if it has an effective duration that matches the QUERY less than DTEND MUST match the QUERY. And if the DURATION ends
supplied DURATION value or any range of values supplied by exactly at the computed DTEND it MUST NOT match.
the QUERY.
As DTEND is the first time that is excluded from a components Any DTEND supplied by the QUERY that is exactly one second more than
time range, any DURATION supplied by the QUERY that is an end time computed from a DURATION MUST match the QUERY. Any end
exactly one second less than DTEND MUST match the QUERY. time that is computed from a DURATION that exactly matches the
And if the DURATION ends exactly at the computed DTEND it supplied DTEND MUST NOT match.
MUST NOT match.
Any DTEND supplied by the QUERY that is exactly one second Given a meeting room reserved with a component that contains (date-
more than an end time computed from a DURATION MUST match the time-example-1):
QUERY. Any end time that is computed from a DURATION that
exactly matches the supplied DTEND MUST NOT match.
(6.1) Given a meeting room reserved with a component
that contains:
DTSTART:20020127T000000Z 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
To: To:
January 27th, 2002,00:59:59 January 27th, 2002,00:59:59
(6.2) Given another meeting room reserved with a component Given another meeting room reserved with a component that contains
that contains: (date-time-example-2):
DTSTART:20020127T000000Z DTSTART:20020127T000000Z
DURATION:P59M59S DURATION:P59M59S
The reservation is really from: The reservation is really from:
January 27th, 2002 00:00:00 January 27th, 2002 00:00:00
To: To:
January 27th, 2002,00:59:59 January 27th, 2002,00:59:59
(6.3) A QUERY that contains: A QUERY that contains:
... VEVENT.DTSTART = '20020127T00000Z' ... VEVENT.DTSTART = '20020127T00000Z'
AND VEVENT.DTEND = '20020127T010000Z' AND VEVENT.DTEND = '20020127T010000Z'
MUST match both (6.1) and (6.2). MUST match both (date-time-example-1) and (date-time-example-2)
(6.4) A QUERY that contains: A QUERY that contains:
... VEVENT.DTSTART = '20020127T00000Z' ... VEVENT.DTSTART = '20020127T00000Z'
AND DURATION = 'P59M59S' AND DURATION = 'P59M59S'
MUST match both (6.1) and (6.2). MUST match both (date-time-example-1) and (date-time-example-2)
(7) [NOT] LIKE notes: 6.1.1.11 [NOT] LIKE
The pattern matching characters is the '%' that matches The pattern matching characters are the '%' that matches zero or more
zero or more characters, and '_' that matches exactly one characters, and '_' that matches exactly one character (where
character (where character does not always mean octet). character does not always mean octet).
LIKE pattern matches always cover the entire string. To match LIKE pattern matches always cover the entire string. To match a
a pattern anywhere within a string, the pattern must start and pattern anywhere within a string, the pattern must start and end with
end with a percent sign. a percent sign.
To match a '%' or '_' in the data and not have it interpreted To match a '%' or '_' in the data and not have it interpreted as a
as a wildcard character, they must be backslash escaped. wildcard character, they MUST BE backslash escaped. That is to
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 Strings compared using the LIKE clause MUST BE performed using case
using case in-sensitive comparisons. ('a' = 'A'). in-sensitive comparisons when the locale allows. (Example: in US-
ASCII the compare assumes 'a' = 'A').
If LIKE is preceded by 'NOT' then there is a match when If LIKE is preceded by 'NOT' then there is a match when the string
the string compare fails. compare fails.
Some property values (such as the 'recur' value type), contain Some property values (such as the 'recur' value type), contain commas
commas and are not multi valued. The CS must understand the and are not multi valued. The CS must understand the objects being
objects being compared and understand how to determine how any compared and understand how to determine how any multi valued or
multi valued or multi instances properties or parameter values multi instances properties or parameter values are separated, quoted,
are separated, quoted, and backslash escaped and perform the and backslash escaped and perform the comparisons as if each value
comparisons as if each value existed by itself and not quoted existed by itself and not quoted or backslash escaped when comparing
or backslash escaped when comparing using the CONTAINS() element. using the IN element.
And see the examples in the next note (8). And see the examples in the next section (IN).
(8) 'col-value SP "NOT IN" cap-colval" 6.1.1.12 Empty vs. NULL
This is similar to the LIKE element, except it does value When used in a CAL-QUERY value, "NULL" means that the property or
matching and not string comparison matches. parameter is not present in the object.
Some iCalendar objects can be multi instance and multi valued. If the property (or parameter) exists, but has no value then "NULL"
The IN operator will return a match if the literal value supplied MUST NOT match.
as part of the 'IN' clause is contained in the value of any
instance of the named property or parameter, or is in any of If the property (or parameter) exists, but has no value then it
the multiple values in the named property or parameter. The matches the empty string '' (quote quote).
'%' and '_' matching characters are not used with the 'IN'
clause and have no special meaning. 6.1.1.13 [NOT] IN
This is similar to the LIKE element, except it does value matching
and not string comparison matches.
Some iCalendar objects can be multi instance and multi valued. The
IN operator will return a match if the literal value supplied as part
of the 'IN' clause is contained in the value of any instance of the
named property or parameter, or is in any of the multiple values in
the named property or parameter. Unlike the 'LIKE' clause, the '%'
and '_' matching characters are not used with the 'IN' clause and
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 FOO:parameter=1,2:x One parameter, two values.
d FOO:parameter="1,2",3:y One parameter, two value. d FOO:parameter="1,2",3:y One parameter, one value.
e FOO:parameter="," e FOO:parameter=",":z One parameter, one value.
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).
'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 (d) and (e). ',' IN parameter would match (e) only.
'%,%' IN parameter would NOT match any.
LIKE(property, "value1%" would match (a) and (b) property LIKE 'value1%' would match (a) and (b)
LIKE(property, 'value%') would match (a) and (b) property LIKE 'value%' would match (a) and (b)
LIKE(parameter, '1%') would match (c) and (d) property LIKE 'x' would match (f) and (c).
LIKE(parameter, '%2%') would match (c) and (d) parameter LIKE '1%' would match (c) and (d)
LIKE(parameter, ',') would NOT match any. parameter LIKE '%2%' would match (c) and (d)
parameter LIKE ',' would match (e) only.
Some property values (such as the 'recur' value type), contain Some property values (such as the 'recur' value type), contain commas
commas and are not multi valued. The CS must understand the and are not multi valued. The CS must understand the objects being
objects being compared and understand how to determine how any compared and understand how to determine how any multi valued or
multi valued or multi instances properties or parameter values multi instances properties or parameter values are separated, quoted,
are separated, quoted, and backslash escaped and perform the and backslash escaped and perform the comparisons as if each value
comparisons as if each value existed by itself and not quoted existed by itself and not quoted or backslash escaped when comparing
or backslash escaped when comparing using the CONTAINS() element. using the IN element.
If IN is preceded by 'NOT' then there is a match when If IN is preceded by 'NOT' then there is a match when the value does
the value does not exist in the property or parameter value. not exist in the property or parameter value.
(9) 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 as in All DATE-TIME and TIME literal values supplied in a WHEN clause MUST
a WHEN clause MUST BE terminated with 'Z'. That means BE terminated with 'Z'. That means that the CUA MUST supply the
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: 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'
It is a syntax error and the CS MUST reject the QUERY. 6.1.1.15 Multiple contained components
4.2 CAP-QL notes
(1) There is no ORDERBY. Sorting will take place in the order the
columns are supplied in the command.
Float and integer values MUST BE sorted by their numeric value.
This means the result of a sort on an integer value type will be:
1, 2, 100, 1000
and not
1, 100, 1000, 2
This means the result of a sort on an float value type will be:
1.1, 2.23, 100.332, 1000.12
and not
1.1, 100.332, 1000.12, 2.23
Date and date time values will be sorted by their equivalent
value in UTC. No matter what the returned time zone is in the
result set. This is so that if multiple components are returned
each in a unique time zone, the results will be sorted in UTC.
This does not mean the values must be converted to UTC in the
data returned to the CUA. It means the CS must do the sort in UTC.
All other values are sorted according to the locale sorting order
as specified in the calendar. Or the CS locale if the calendar
does not have any locale set, or the host operating system
locale if the CS does not specify a locale. And the locale to
use for the sort is determined in that order.
(2) The CS MUST sort at least the first column.
The CS MAY sort additional columns.
(3) If the cap-cols is only "*" and nothing else, then:
If EXPAND=FALSE sorting will be by the DTSTART value
ascending.
If EXPAND=TRUE sorting will be by the RECURRENCE-ID value
ascending.
If one or more DTSTART or RECURRENCE-ID components have
exactly the same value, the order for those matching
components is unspecified.
(4) All literal values are surrounded by single quotes ('), not
double quotes ("), and not without any quotes. If the value
contains quotes or any other ESCAPED-CHAR, they must be
backslash escaped as described in section "4.3.11 Text"
of RFC2445. Any LIKE wildcard characters that are part
of any literal data that is preceded by a LIKE clause and
is not intended to mean wildcard search, MUST BE escaped as
described in note (7) below.
(5) When comparing DATE-TIME to DATE value types and when
comparing DATE to DATE-TIME value types, the result will
be true if the DATE value is on the same day as the DATE-TIME
value (both compared in UTC). And they MUST BE compared in UTC no
matter what time zone the object had been tagged with when the
object was stored in the CS.
VALUE-1 VALUE-2 Compare Results
20020304 20020304T123456 TRUE
(in UTC-3) (in UTC-3)
20020304 20020304T003456 FALSE
(in UTC-4) (in UTC-4)
20020304T003456Z 20020205T003456 FALSE
(in UTC-0) (in UTC-7)
When comparing DATE and DATE-TIME values with the LIKE
clause the comparison will be done as if the value is
a RFC2445 DATE or DATE-TIME string value (again in UTC).
LIKE '2002%' will match anything in the year 2002 (UTC).
LIKE '200201%' will match anything in January 2002 (UTC).
LIKE '%T000000' will match anything at midnight (UTC).
LIKE '____01__T%' will match anything for any year or
time that is in January (UTC).
(Four '_', '01', two '_' 'T%').
Again all comparisons will be done in UTC.
Using a LIKE value of "%00%, would return any value that
contained two consecutive zeros.
(6) DTEND and DURATION.
When a VQUERY contains a DTEND value, then the CS MUST also
evaluate any existing DURATION property value and determine
if it has an effective end time that matches the VQUERY
supplied DTEND value or any range of values supplied by
the VQUERY.
When a VQUERY contains a DURATION value, then the CS MUST
also evaluate any existing DTEND property value and determine
if it has an effective duration that matches the VQUERY
supplied DURATION value or any range of values supplied by
the VQUERY.
As DTEND is the first time that is excluded from a components
time range, any DURATION supplied by the VQUERY that is
exactly one second less than DTEND MUST match the VQUERY.
And if the DURATION ends exactly at the computed DTEND it
MUST NOT match.
Any DTEND supplied by the VQUERY that is exactly one second
more than an end time computed from a DURATION MUST match the
VQUERY. Any end time that is computed from a DURATION that
exactly matches the supplied DTEND MUST NOT match.
(6.1) Given a meeting room reserved with a component
that contains:
DTSTART:20020127T000000Z
DTEND:20020127T010000Z
The reservation is really from:
January 27th, 2002 00:00:00
To:
January 27th, 2002,00:59:59
(6.2) Given another meeting room reserved with a component
that contains:
DTSTART:20020127T000000Z
DURATION:P59M59S
The reservation is really from:
January 27th, 2002 00:00:00
To:
January 27th, 2002,00:59:59
(6.3) A VQUERY that contains:
... VEVENT.DTSTART = '20020127T00000Z'
AND VEVENT.DTEND = '20020127T010000Z'
MUST match both (6.1) and (6.2).
(6.4) A VQUERY that contains:
... VEVENT.DTSTART = '20020127T00000Z'
AND DURATION = 'P59M59S'
MUST match both (6.1) and (6.2).
(7) [NOT] LIKE notes:
The pattern matching characters is the '%' that matches
zero or more characters, and '_' that matches exactly one
character (where character does not always mean octet).
LIKE pattern matches always cover the entire string. To match
a pattern anywhere within a string, the pattern must start and
end with a percent sign.
To match a '%' or '_' in the data and not have it interpreted
as a wildcard character, they must be backslash escaped as
done in [RFC2445]. That is to search for a '%' or '_' in
the string:
LIKE '%\%%' Matches any string with a '%' in it.
LIKE '%\_%' Matches any string with a '_' in it.
Strings compared using the LIKE clause MUST BE performed
using case in-sensitive comparisons. ('a' = 'A').
The CS must understand the objects being compared and
understand how to determine how any multi valued property
or parameter values are separated, quoted, and backslash
escaped and perform the comparisons as if each value existed
by itself and not quoted or backslash escaped when comparing
using the LIKE element.
If LIKE is preceded by 'NOT' then there is a match when
the string compare fails.
(8) [NOT] "CONTAINS(" cap-lhs "," col-literal ")"
This is similar to the LIKE element, except it does value
matching and not string comparison matches.
property:value1,value2
CONTAINS(property, 'value1') would match
CONTAINS(property, 'value') would NOT match
LIKE(property, 'value%') would match
The CS must understand the objects being compared and
understand how to determine how any multi valued property
or parameter values are separated, quoted, and backslash
escaped and perform the comparisons as if each value existed
by itself and not quoted or backslash escaped when comparing
using the CONTAINS() element.
If CONTAINS() is preceded by 'NOT' then there is a match when
the value does not exist in the property or parameter value.
(9) DATE-TIME and TIME values in a WHEN clause.
All DATE-TIME and TIME literal values supplied as in
a WHEN clause MUST BE terminated with 'Z'. That means
that the CUA MUST supply the values in UTC.
Valid:
WHERE alarm.TRIGGER < '20020201T000000Z'
AND alarm.TRIGGER > '20020101T000000Z'
Not valid:
WHERE alarm.TRIGGER < '20020201T000000' All comparisons MUST BE done from the same instance of a contained
AND alarm.TRIGGER > '20020101T000000' component or property and repeated for each instance. As in the
following example that uses a VALARM component contained in a VEVENT.
If any instance of VALARM in VEVENT matches the query and the rest of
the query is satisfied, then the UID, SUMMARY, and DESCRIPTION from
the VEVENT will be returned. If there were two VALARMs in a VEVENT,
then both VALARMs are tested and in this example only when the VEVENT
state is booked:
It is a syntax error and the CS MUST reject the VQUERY. BEGIN:VQUERY
EXPAND:TRUE
QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT
WHERE VALARM.TRIGGER >= '20000101T030405Z'
AND VALARM.TRIGGER <= '20001231T235959Z'
AND STATE() = 'BOOKED'
END:VQUERY
4.3 Example, Query by UID 6.1.1.16 Example, Query by UID
The following example would match the entire content of the VEVENT The following example would match the entire content of a "VEVENT" or
or VTODO with the UID property equal to "uid123" and not expand "VTODO" component with the "UID" property equal to "uid123" and not
any multiple instances of the component. If the CUA does not know expand any multiple instances of the component. If the CUA does not
if "uid123" was a VEVENT, VTODO, VJOURNAL, or any other component, know if "uid123" was a "VEVENT", "VTODO", "VJOURNAL", or any other
then all components that the CUA supports MUST be supplied in a component, then all components that the CUA supports MUST BE supplied
QUERY property. This example assumes the CUA only supports VTODO and in a QUERY property. This example assumes the CUA is only interested
VEVENT. in "VTODO" and "VEVENT" components.
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
4.4 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 that has
an instance greater than or equal to July 1st, 2000 00:00:00 UTC and an instance greater than or equal to July 1st, 2000 00:00:00 UTC and
less than or equal to July 31st, 2000 23:59:59 UTC less than or equal to July 31st, 2000 23:59:59 UTC. This includes
single instance VEVENT objects that do no explicitly contain a
RECURRENCE-ID.
BEGIN:VQUERY BEGIN:VQUERY
EXPAND:TRUE EXPAND:TRUE
QUERY:SELECT * FROM VEVENT QUERY:SELECT * FROM VEVENT
WHERE RECURRENCE-ID >= '20000801T000000Z' WHERE RECURRENCE-ID >= '20000801T000000Z'
AND RECURRENCE-ID <= '20000831T235959Z' AND RECURRENCE-ID <= '20000831T235959Z'
AND METHOD = 'CREATE' AND STATE() = 'BOOKED'
END:VQUERY END:VQUERY
4.5 Query for all Non-Booked Entries 6.1.1.18 Query for all Unprocessed Entries
The following example selects the entire contents of all [ITIP] The following example selects the entire contents of all non-booked
non-booked VTODOs and VEVENTs with their METHOD set to one of "VTODO" and "VEVENT" components with their state of 'UNPROCESSED".
the [ITIP] METHODs. The default for EXPAND is FALSE, so the The default for EXPAND is FALSE, so the recurrence rules will not be
recurrence rules will not be expanded. expanded.
BEGIN:VQUERY BEGIN:VQUERY
QUERYID:Fetch VEVENT and VTODO iTIP components QUERYID:Fetch VEVENT and VTODO iTIP components
NAME;LANG=fr_ca: ...todo...
QUERY:SELECT * FROM VEVENT WHERE QUERY:SELECT * FROM VEVENT WHERE
METHOD = 'REQUEST' OR METHOD = 'ADD' OR METHOD = 'PUBLISH' OR STATE() = 'UNPROCESSED'
METHOD = 'CANCEL' OR METHOD = 'REPLY' OR METHOD = 'COUNTER' OR
METHOD = 'REFRESH' OR METHOD = 'DECLINECOUNTER'
QUERY:SELECT * FROM VTODO WHERE QUERY:SELECT * FROM VTODO WHERE
METHOD = 'REQUEST' OR METHOD = 'ADD' OR METHOD = 'PUBLISH' OR STATE() = 'UNPROCESSED'
METHOD = 'CANCEL' OR METHOD = 'REPLY' OR METHOD = 'COUNTER' OR
METHOD = 'REFRESH' OR METHOD = 'DECLINECOUNTER'
END:VQUERY END:VQUERY
In the above exampe, the QUERY property could have been written as: The following example fetches all "VEVENT" and "VTODO" components
that are booked from the CS.
QUERY:SELECT * FROM VEVENT WHERE METHOD != 'CREATE'
AND METHOD != 'DELETE'
The following example fetches all VEVENT and VTODO booked entries
from the CS.
BEGIN:VQUERY BEGIN:VQUERY
QUERYID:Fetch All Booked VEVENT and VTODO components QUERYID:Fetch All Booked VEVENT and VTODO components
QUERY:SELECT * FROM VEVENT WHERE METHOD = 'CREATE' QUERY:SELECT * FROM VEVENT WHERE STATE() = 'BOOKED'
QUERY:SELECT * FROM VTODO WHERE METHOD = 'CREATE' 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 for all VEVENT and VTODO components
that have been marked for delete (METHOD:DELETE). 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 METHOD = 'DELETE' QUERY:SELECT UID FROM VEVENT WHERE STATE() = 'DELETE'
QUERY:SELECT UID FROM VTODO WHERE METHOD = '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 queries. They could be performed all at once by having all of the
the QUERY property in one BEGIN/END VQUERY component. QUERY property in one BEGIN/END VQUERY component.
4.6 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 DTSTART
from February 1st to February 10th 2000. 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
4.7 Components With Alarms In A Range 6.1.1.20 Query with Components and Alarms In A Range
This example fetches all VEVENTs with an alarm that triggers This example fetches all booked "VEVENT" components with an alarm
within the specified time range. In this case only the UID, SUMMARY, that triggers within the specified time range. In this case only the
and DESCRIPTION will be selected for all booked VEVENTS that have an "UID", "SUMMARY", and "DESCRIPTION" properties will be selected for
alarm between the two date-times. all booked "VEVENTS" components that have an alarm between the two
date-times supplied.
BEGIN:VQUERY BEGIN:VQUERY
EXPAND:TRUE EXPAND:TRUE
QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT QUERY:SELECT UID,SUMMARY,DESCRIPTION FROM VEVENT
USING_COMPONENT VALARM my-alarm WHERE VALARM.TRIGGER >= '20000101T030405Z'
WHERE my-alarm.TRIGGER >= '20000101T030405Z' AND VALARM.TRIGGER <= '20001231T235959Z'
AND my-alarm.TRIGGER <= '20001231T235959Z' AND STATE() = 'BOOKED'
AND METHOD = 'CREATE'
END:VQUERY END:VQUERY
5. Access Rights 6.1.2 UPN Value Type
Access rights within CAP are specified with the "VCAR" calendar
component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID"
component properties.
5.1 Access Control and NOCONFLICT Value Name: UPN
The TRANSP property can take on values (TRANSPARENT-NOCONFLICT, Purpose: This value type is used to identify values that contain user
OPAQUE-NOCONFLICT) that prohibit other events from overlapping it. principal name of CU or group of CU.
This setting overrides access. The ALLOW-CONFLICT Calendar or
component setting may also prevent overlap, returning an error code
"6.3"
6. Commands and Responses Formal Definition: The value type is defined by the following
notation:
CAP commands and responses are described in this section. upn = "@"
/ [ dot-atom-text ] "@" dot-atom-text
As mentioned in Section 3.2, CAP commands are defined by MIME ; dot-atom-text is defined in RFC 2822
objects.
The attributes of a command are described in the "Attributes:" Description: This data type is an identifier that denotes a CU or a
section in the command descriptions below. Similarly the "Elements:" group of CU.
section describes the elements that compose the command. The
"Response:" section, identifies the responses that may be returned by
the server.
In the examples below, lines preceded with "S:" refer to the server Example:
and lines preceded with "C:" refer to the client. Lines in which the
first non-whitespace character is a "#" are editorial comments and
are not part of the protocol.
6.1 Session Commands The following is a UPN for a CU:
6.1.1 "generate-uid" Command jdoe@acme.com
The following is a UPN for a group of CU:
Attributes: staff@acme.com
num: Number of UIDs to generate (1 if omitted). The following is a UPN for an anonymous CU belonging to a specific
realm:
cmdid: A unique id that identifies this command to @acme.com
the CUA and CS.
latency: How long before CS asks you to continue. (optional) The following is a UPN for an anonymous CU:
action: How to handle latencty - MUST BE suppled but @
only when the 'latency' command is supplied.
Response: 6.1.3 UPN-FILTER Value
"uid-list" Value Name: UPN-FILTER
The "generate-uid" command returns one or more unique identifiers Purpose: This value type is used to identify values that contain a
which MUST BE globaly unique. user principal name filter.
Example: Formal Definition: The value type is defined by the following
notation:
C: MSG 1 5 . 2837 60 upn-filter = "OWNER()" /
C: Content-Type: application/cap+xml "NOT OWNER()" /
C: "*" /
C: <generateuid num=5/> [ "*" / dot-atom-text ] "@" ( "*" / dot-atom-text )
C: END
S: RPY 1 5 . 2897 328
S: Content-Type: application/cap+xml
S:
S: <uid-list>
S: <uid>20011121T120000Z-12340@cal.example.com</uid>
S: <uid>20011121T120000Z-12341@cal.example.com</uid>
S: <uid>20011121T120000Z-12342@cal.example.com</uid>
S: <uid>20011121T120000Z-12343@cal.example.com</uid>
S: <uid>20011121T120000Z-12344@cal.example.com</uid>
S: </uid-list>
S: END
6.1.2 "get-capability" Command ; dot-atom-text is defined in RFC 2822
Attributes: Description: The value is used to match user principal names (UPNs).
For "OWNER()" and "NOT OWNER()", see Section 6.1.1.3.
None * Matches all UPNs.
Elements: @ Matches the UPN of anonymous CUs
belonging to the null realm
None @* Matches the UPN of anonymous CUs
belonging to any non-null realm
Response: @realm Matches the UPN of anonymous CUs
belonging to the specified realm.
"capability" *@* Matches the UPN of non-anonymous CUs
belonging to any non-null realm
The "get-capability" command returns information about the Calendar *@realm Matches the UPN of non-anonymous CUs
Server given the current state of the connection with the client. belonging to the specified realm
The values returned may differ depending on current user identify and
the security level of the connection.
Client implementations SHOULD NOT require any capability element user@realm Matches the UPN of the specified CU
beyond those defined in this specification, and MAY ignore any non- belonging to the specified realm
standard, experimental capability elements. Non-standard
experimental capability elements MUST be prefixed with the text "x-".
The prefix SHOULD also include a vendor identifier. For example, "x-
foo-barcapability", for the non-standard "barcapability" capability
of the vendor "foo". It may return different results depending on
the UPN.
Capability Occurs Description user@* Not allowed.
-------------------------------------------------------
cap 1 Container for CAP related elements.
cap-version 1+ Version of CAP. MUST include at Example: The following are examples of this value type:
least "1.0" for this version of
CAP.
prodid 0 or 1 The product id of the CS. DENY:NON OWNER()
query-level 1+ Indicates level of SQL support. 6.2 New Parameter
CAP-QL 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 1+ Indicates level of CAR support. 6.2.1 ENABLE Parameter
CAR-NONE, CAR-MIN or CAR-FULL-1.
If CAR-FUL-1 is supplied then
CAR-MIN MUST BE supplied. CAR = NONE
MUST BE used when query-level of
NONE is supplied. If
date-max 0 or 1 The datetime value in UTC beyond Parameter Name: ENABLE
which the server cannot accept. If
not specified the default is
99991231T235959Z.
date-min 0 or 1 The datetime value prior to which Purpose: This parameter indicates whether or not the "TRIGGER"
the server cannot accept. If not property in a "VALARM" component should be ignored.
specified the default is
00000101T000000Z.
max-component-size Value Type: BOOLEAN
0 or 1 A positive integer value that specifies
the size of the largest iCalendar
object that the server will accept in
octets. Objects larger than this will be
rejected. The absence of this attribute
indicates no limit. This is also the
maximum value of any BEEP payload
the CS will accept or send.
components 1 A comma seperated list of the names of Conformance: This property can be specified in the "TRIGGER"
components that this CS supports. This properties.
includes any components inside of
other components (VALARM and VEVENT
for example). MUST include at least
VCALSTORE, VCALENDAR, and VAGENDA
and at least one of VEVENT, VTODO,
or VJORNAL.
version 1+ Version of iCalendar support. Description: When a non owner sends an iTIP "REQUEST" to a calendar
MUST BE at least "2.0". that object might contain a "VALARM" component. The owner may wish
supported. to have local control over their own CUA and when or how alarms are
triggered.
itip-version 1+ Version(s) of ITIP, MUST include at A CUA may add the "ENABLE" parameter to any "TRIGGER" property before
least "1.0". 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
the "ENABLE" property is not in the "TRIGGER" property, the alarm is
enabled. The CUA should remove the "ENABLE" parameter before
forwarding the component to a non-cap CUA.
recur-accepted 0 or 1 whether the CS accepts recurrence rules If FALSE in the "VCALSTORE", then all "VAGENDA" ALLOW-CONFLICT values
recur-expand 0 or 1 whether or not the CS supports the MUST BE false in the CS.
expansion of recurrence rules.
recur-limit 0 or 1 the maximum number of occurrences or a recurrence
rule that are expanded by the CS
Example: Format Definition: The property is defined by the following notation:
C: MSG 1 6 . 3225 57 allow-conflict = "ALLOW-CONFLICT"
C: Content-Type: application/beep+xml *(";" xparam) ":" boolean CRLF
C:
C: <get-capability/>
C: END
S: RPY 1 6 . 3282 423
S: Content-Type: application/beep+xml
S:
S:
S: <capability>
S: <version>2.0</version>
S: <max-component-size>65536</max-component-size>
S: <itip-version>1.0</itip-version>
S: <cap-version>1.0</cap-version>
S: <car>CAR-FULL-1</car><car>CAR-MIN</car.
S: <query-level>CAP-QL</query-level>
S: <date-min>00000101T000000Z</date-min>
S: <date-max>99991231T235959Z</date-max>
S: <components>
S: VCALSTORE,VAGENDA,VCALENDAR,VEVENT,X-my-vcomp,VALARM
S: </components>
S: </capability>
S: END
6.1.3 "identify" Command Example: The following is an example of this property for a "VAGENDA"
component:
Attribute: ALLOW-CONFLICT:FALSE
upn: The UPN of the new identify to assume. 6.2.2 LOCAL Parameter
Element: Parameter Name: LOCAL
None Purpose: Indicates if the VALARM should be exported to any non-
organizer calendar.
Response: Value Type: BOOLEAN
"result" with one of the following request-status codes: Conformance: This property can be specified in the "SEQUENCE"
properties in a "VALARM" component.
2.0 Successful. Description: When a non owner sends an iTIP "REQUEST" to a calendar
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
triggered.
6.4 Identity not permitted. A CUA may add the "LOCAL" parameter to the "SEQUENCE" property before
booking the component. If the "LOCAL" parameter is set to "FALSE",
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"
property, the alarm is global. The CUA should remove the "LOCAL"
parameter before forwarding the component to a non-cap CUA and to non
organizer calendars.
The "identify" command allows the CUA to set a new identity to be If FALSE in the "VCALSTORE", then all "VAGENDA" ALLOW-CONFLICT values
used for calendar access. MUST BE false in the CS.
The CS determines through an internal mechanism if the credentials Format Definition: The property is defined by the following notation:
supplied at authentication permit the assumption of the selected
identity. If they do, the session assumes the new identity,
otherwise a security error is returned.
If allow-conflict = "ALLOW-CONFLICT"
Example: *(";" xparam) ":" boolean CRLF
C: MSG 1 7 . 3705 47 Example: The following is an example of this property for a "VAGENDA"
C: Content-Type: application/cap+xml component:
C:
C: <identify upn="my-alter-ego"/>
C: END
S: RPY 1 7 . 3752 91 ALLOW-CONFLICT:FALSE
S: Content-Type: application/cap+xml
S:
S: <request-status code="2.0"/>
S: END
6.1.4 "noop" Command 7. New Properties
Arguments: 7.1 ALLOW-CONFLICT Property
None Property Name: ALLOW-CONFLICT
Element: Purpose: This property indicates whether or not the calendar and CS
supports component conflicts. That is, whether or not any of the
components in the calendar can overlap.
None Value Type: BOOLEAN
Response: Property Parameters: Non-standard property parameters can be
specified on this property.
2.0 successful Conformance: This property can be specified in "VAGENDA" and
"VCALSTORE" component.
This command does nothing. It can be sent to the server periodically Description: This property is used to indicate whether components may
to request that the CS does not time out the session. 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,
then conflicts are allowed. If FALSE, the no two components may
conflict.
Example: If FALSE in the "VCALSTORE", then all "VAGENDA" ALLOW-CONFLICT values
MUST BE false in the CS.
C: MSG 1 7 . 3705 47 Format Definition: The property is defined by the following notation:
C: Content-Type: application/cap+xml
C:
C: <noop/>
C: END
S: RPY 1 7 . 3752 91
S: Content-Type: application/cap+xml
S:
S: <request-status code="2.0"/>
S: END
6.2 Calendaring and Scheduling Commands allow-conflict = "ALLOW-CONFLICT"
*(";" xparam) ":" boolean CRLF
6.2.1 Restriction Tables Example: The following is an example of this property for a "VAGENDA"
component:
Calendaring data is sent encapsulated in iCalendar objects The ALLOW-CONFLICT:FALSE
restriction tables listed in the commands below describe the
composition of the iCalendar data for these commands and replies.
The presence column uses the following values to assert whether a 7.2 CALID Property
property is required, is optional and the number of times it may
appear in the iCalendar object. A comment may be provided to further
clarify the presence criteria.
The table below defines the values for the presence column. Property Name: CALID
Presence Property Parameters: Non-standard property parameters can be
Value Description specified on this property.
--------------------------------------------------------------
1 One instance MUST be present
1+ At least one instance MUST be present
0 Instances of this property MUST NOT be present
0+ Multiple instances MAY be present
0 or 1 Up to 1 instance of this property MAY be present
--------------------------------------------------------------
While the tables list every component and property, their purpose is Conformance: This property can be specified in the "VAGENDA".
not to define the meaning of the component or property.
6.2.2 Calendaring Commands Description: This property is used to specify a fully qualified
calid.
Calendaring commands allow a CUA to directly manipulate a calendar. Format Definition: The property is defined by the following notation:
Calendar access rights can be granted for the more generalized access CALID = "CALID" *(";" xparam) ":" calid CRLF
provided by the calendar commands.
There are two kinds of replies. Those that contain an iCalendar Example:
object, and those that do not contain an iCalendar object.
Any reply from the CS that contains an iCalendar object is wrappend CALID:cap://cal.example.com/sdfifgty4321
in a <reply> and </reply> tags.
Any reply from the CS that does not contain an iCalendar object is 7.3 CALMASTER Property
returned in a <request-status code="x.y"/&gt tag. And if this reply
includes any cap command replies. Then they are returned wrapped
between <request-status code="x.y"&gt and </request-status
code="x.y"&gt tags.
6.2.2.1 "create" Command Property Name: CALMASTER
Attributes: Purpose: The property specifies an e-mail address of a person
responsible for the calendar store.
"latency" with "action" (optional) Value Type: URI
Response: Property Parameters: Non-standard property parameters can be
specified on this property.
One "result" iCalendar object per "target" element MUST be Conformance: The property can be specified in a "VCALSTORE"
returned (see Section 3.1) component.
One of the following "request-status" codes MUST be returned: 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
home page or file URI that describes how to contact the calmasters.
2.0 - successfully created the component or calendar Format Definition: The property is defined by the following notation:
6.1 - Target not found calmaster = "CALMASTER" *(";" xparam) ":" uri CRLF
6.3 - Bad args uri = IANA registered uri and defined by RFC 2445
The "create" command is used to create one or more iCalendar objects. Example: The following is an example of this property:
The TARGET property specify the containers where the component(s) CALMASTER:mailto:administrator@example.com
will be created.
The CDATA portion of the command can be any valid [ITIP] object 7.4 CARID Property
or any iCalendar object using the following restriction table.
There MUST BE at least one component inside of the VCALENDAR
object.
Restriction table for the "create" command: Property Name: CARID
Component/Property Presence Comment Purpose: This property specifies the identifier for an access right
------------------- -------- ----------------------------- component.
VCALENDAR 1
. VERSION 1 MUST BE at least 2.0
. TARGET 1+
. METHOD 1 MUST BE the METHOD of the newly
created components.
. CMDID 0 or 1
. [IANA-PROP] 0+ any IANA registered
property
. VAGENDA 0+ Value Type: TEXT
. VAGENDA 0+
. . ALLOW-CONFLICT 0 or 1
. . CALMASTER 0 or 1
. . CALSCALE 0 or 1
. . CREATED 0 or 1
. . DEFAULT-CHARSET 0 or 1
. . DEFAULT-LOCALE 0 or 1
. . DEFAULT-TZID 0 or 1
. . LAST-MODIFIED 0 or 1
. . METHOD 0 or 1 The only valid values are
"CREATE" or "DELETE."
. . NAME 0+
. . OWNER 1+
. . RELATED-TO 0+
. . RELCALID 1
. . TZID 0 or 1
. . X-PROPERTY 0+
. . [IANA-PROP] 0+ any IANA registered
property
. . X-COMPONENT 0+
. VCAR 0+ Property Parameters: Non-standard property parameters can be
. . . CARID 1 specified on this property.
. . . NAME 0+ Note, there MUST NOT be
more than one NAME with
no LANGUAGE parameter,
and there MUST NOT be
more than one NAME with
the same LANGUAGE value.
. . . DECREED 0 This property is outside
the scope of the protocol.
. . . X-PROPERTY 0+
. . . [IANA-PROP] 0+ any IANA registered
property
. . . VRIGHT 1+
. . . . PERMISSION 1+
. . . . DENY 0+ Note, there must be at
least one GRANT or DENY
within the VRIGHT.
. . . . GRANT 0+ Note, there must be at
least one GRANT or DENY
within the VRIGHT.
. . . . SCOPE 0+ Note, there must be at
least one SCOPE if
PERMISSION is set to
"READ", "MODIFY",
"DELETE", or "*".
. . . . RESTRICTION 0 or 0+ Note, allowed only if
PERMISSION is set to
"WRITE", "MODIFY", or "*".
. . . . X-PROPERTY 0+
. . . . [IANA-PROP] 0+ any IANA registered
property
. VQUERY 0+ Conformance: This property MUST BE specified once in a "VCAR"
(For VQUERY minimum values - see the VQUERY sections. component.
Plus each each new VQUERY must have a QUERYID property)
. x-component 0+ Description: This property is used in the "VCAR" component to specify
an identifier.
Restriction Table for the CDATA section of a reply that contains Format Definition: The property is defined by the following notation:
an iCalendar object is any valid [ITIP] response plus any from
this restriction table and the VQUERY responses can contain
any iCalendar properties that are wrapped in BEGIN/END VCALENDAR.
There MUST BE at least one component inside of the VCALENDAR
object.
Component/Property Presence Comment carid = "CARID" *(";" xparam) ":" text CRLF
------------------- -------- -------------------------------
VCALENDAR 1+ Example: The following are examples of this property:
. VERSION 1 MUST BE at least 2.0
. TARGET 1+
. CMDID 0 or 1
. VAGENDA 0+ CARID:xyzzy-007
. . RELCALID 1 CARID:User Rights
. . REQUEST-STATUS 1+
. VCAR 0+ 7.5 CSID Property
. . CARID 1
. . REQUEST-STATUS 1+
. VQUERY 0+ Property Name: CSID
. . QUERYID 0+ One for each QUERYID supplied in "create"
. . REQUEST-STATUS 1+
(Plus the query results)
. x-component 0+ Purpose: The property specifies a the globally unique identifier for
the calendar store.
In the following example, two new top level VAGENDAs are created. Value Type: URI
Note that the CSID of the server is cal.example.com.
C: MSG 1 8 . 3843 480 Property Parameters: Non-standard property parameters can be
C: Content-Type: application/cap+xml specified on this property.
C:
C: <create>
C: <![CDATA[
C: Content-Type: text/calendar
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: CMDID:creation01
C: TARGET:cal.example.com
C: BEGIN:VAGENDA <- data for 1st new calendar
C: RELCALID:relcalz1
C: NAME;LANGUAGE=EN-us:Bill's Soccer Team
C: OWNER:bill
C: CALMASTER:mailto:bill@example.com
C: TZID:US/Pacific
C: END:VAGENDA
C: BEGIN:VAGENDA <- data for 2nd new calendar
C: RELCALID:relcalz2
C: NAME;LANGUAGE=EN-us:Mary's personal calendar
C: OWNER:mary
C: CALMASTER:mailto:mary@example.com
C: TZID:US/Pacific
C: END:VAGENDA
C: END:VCALENDAR
C: />]]>
C: END
When there are multiple TARGET'values in the original command object Conformance: The property can be specified in a "VCALSTORE"
then the replies MUST BE in the exact same order as they were provided component.
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 the CS.
(With the BEEP header and footer removed)
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: CMDID:creation01
S: TARGET:cal.example.com
S: TARGET:cal.example.com
S: BEGIN:VAGENDA <- Reply for 1st calendar create
S: RELCALID:relcalz1
S: REQUEST-STATUS:2.0
S: END:VAGENDA
S: BEGIN:VAGENDA <- Reply for 2nd calendar create
S: RELCALID:relcalz2
S: REQUEST-STATUS:2.0
S: END:VAGENDA
S: END:VCALENDAR
To create a new component in multiple containers simply name Description: The identifier MUST BE globally unique.
all of the containers in the TARGET in the create command. Here
a new VEVENT is created in two TARGETs. In this example, the
VEVENT is one new iTIP REQUEST object in two calendars. The
results would be iCalendar object that conform to the iTIP
replys as defined in iTIP.
C: Content-Type: text/calendar Format Definition: The property is defined by the following notation:
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: CMDID:creation02
C: METHOD:REQUEST
C: TARGET:relcalz1
C: TARGET:relcalz2
C: BEGIN:VEVENT
C: DTSTART:99990307T180000Z
C: UID:abcd12345
C: DTEND:99990307T190000Z
C: SUMMARY:Important Meeting
C: END:VEVENT
C: END:VCALENDAR
The CS reply can be combined when there is exactly one target. csid = "CSID" *(";" xparam) ":" capurl CRLF
If a <create> command deposited two METHOD:REQUEST objects into
the same target, this could be the reply.
S: <result> Example: The following is an example of this property:
S: <![CDATA[
S: Content-Type: text/calendar
S:
S: BEGIN:VCALENDAR CSID:cap://calendar.example.com
S: CMDID:deposit request
S: TARGET:relcalz1
S: VERSION:2.0
S: BEGIN:VEVENT
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: BEGIN:VEVENT
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: END:VCALENDAR
S: >]]>
S: </result>
6.2.2.2 "move" Command 7.6 DECREED Property
Attributes: Property Name: DECREED
"cmdid" Purpose: This property specifies if an access right calendar
component is decreed or not.
Elements: Value Type: BOOLEAN
"max-time": See Section 3.3. Property Parameters: Non-standard property parameters can be
specified on this property.
"target": The "target" element points to the container where Conformance: This property MAY be specified once in a "VCAR"
the components are to be relocated. component.
"select": identifies the component(s) to move. Description: This property is used in the "VCAR" component to specify
whether the component is decreed or not.
Response: Format Definition: The property is defined by the following notation:
One "result" message for each "source" in the "select" element decreed = "DECREED" *(";" xparam) ":" boolean CRLF
is returned (see Section 3.1).
One of the following "request-status" codes MUST be returned: Example: The following is an example of this property:
2.0 - successfully moved the component or calendar DECREED:TRUE
6.1 - Container not found 7.7 DEFAULT-CHARSET Property
6.3 - Bad args Property Name: DEFAULT-CHARSET
The "data" element of each "result" message is subject to the Purpose: This property indicates the default charset.
result restriction table defined below.
The "move" command is used to move components within the CS's Value Type: TEXT
hierarchy of calendars. The access control on the VAGENDA after it
has been moved to its new location in the calstore hierarchy MUST be
at least as secure as it was prior to the move. One way to
accomplish this is to build a list of VCARs that apply to the VAGENDA
in its old hierarchy and and write them into the VAGENDA before
moving it to its new location.
Restriction Table for "data" element of the "result" response: Property Parameters: Non-standard property parameters can be
specified on this property.
Component/Property Presence Comment Conformance: This property can be specified in "VAGENDA" and
------------------- -------- ------------------------------- "VCALSTORE" calendar component.
VCALENDAR 1+ Description: In a "VAGENDA", this property is used to indicate the
. VERSION 1 MUST be 2.0 charset of calendar. If not specified, the default the first value
in the "VCALSTORE" DEFAULT-CHARSET list. The value MUST BE an IANA
registered character set as defined in [RFC 2278].
. VAGENDA 0+ In a "VCALSTORE" it is a comma separated list of charsets supported
. . RELCALID 1 by the CS. The first entry is the default entry for all newly
. . REQUEST-STATUS 1+ created "VAGENDA"s. "UTF-8" MUST BE in the "VCALSTORE" DEFAULT-
CHARSET list.
. VCAR 0+ If a charset name contains a comma (,), then that comma must be
. . CARID 1 backslashed escaped in the value.
. . REQUEST-STATUS 1+
. VEVENT 0+ Format Definition: The property is defined by the following notation:
. . UID 1
. . REQUEST-STATUS 1+
. . VALARM 0 if VEVENT was successfully default-charset = "DEFAULT-CHARSET" *(";" xparam)
saved ":" text CRLF
1+ if there were errors saving
alarms
. . . ALARMID 1
. . . REQUEST-STATUS 1+
. VFREEBUSY 0 Example: The following is an example of this property for a "VAGENDA"
component:
. VJOURNAL 0+ DEFAULT-CHARSET:Shift_JIS,UTF-8
. . UID 1
. . REQUEST-STATUS 1+
. VQUERY 0+ 7.8 DEFAULT-LOCALE Property
. . REQUEST-STATUS 1+
. VTODO 0+ Property Name: DEFAULT-LOCALE
. . UID 1
. . REQUEST-STATUS 1+
. . VALARM 0 if VTODO was successfully
saved
1+ if there were errors saving
alarms
. . . ALARMID 1
. . . REQUEST-STATUS 1+
--------------------------------------------------------- Purpose: This property specifies the default language for text
values.
Example: moving the VAGENDA Nellis to Area-51 Value Type: TEXT
C: MSG 1 12 . 11323 613 Property Parameters: Non-standard property parameters can be
C: Content-Type: multipart/related; boundary="boundary-kljr"; specified on this property.
C: start="1@cal.example.com";
C: type="application/beep+xml"
C:
C: --boundary-kljr
C: Content-Type: application/beep+xml
C: Content-ID: 1@cal.example.com
C:
C: <move id="move01"/>
C: <select>
C: <source csid="cal@example.com" depth=*>
C: <data content="cid:query@cal.example.com"/>
C: </select>
C: <target relcalid="area-51"/>
C: </move>
C: --boundary-kljr
C: Content-Type: text/calendar
C: Content-ID: query@cal.example.com
C:
C: BEGIN:VCALENDAR
C: BEGIN:VQUERY
C: QUERY: SELECT * FROM VAGENDA WHERE RELCALID='Nellis'
C: END:VQUERY
C: END:VCALENDAR
C: --boundary-kljr--
C: END
S: RPY 1 2 . 11936 571
S: Content-Type: multipart/related; boundary="boundary-mnbvd";
S: start="reply@cal.example.com";
S: type="application/beep+xml"
S:
S: --boundary-mnbvd
S: Content-Type: application/beep+xml
S: Content-ID: reply@cal.example.com
S:
S: <result id="move01">
S: <source csid=cal@example.com depth=*>
S: <request-status code="2.0"/>
S: <data content="cid:2@cal.example.com"/>
S: </result>
S: --boundary-mnbvd
S: Content-Type: text/calendar
S: Content-ID: 2@cal.example.com
S:
S: BEGIN:VCALENDAR
S: BEGIN:VAGENDA
S: RELCALID:Nellis
S: REQUEST-STATUS: 2.0
S: END:VAGENDA
S: END:VCALENDAR
S: --boundary-mnbvd--
S: END
6.2.2.3 "delete" Command Conformance: This property can be specified in "VAGENDA" and
"VCALSTORE" components.
Attributes: Description: In a "VAGENDA", this property is used to indicate the
locale of the calendar. The full locale SHOULD be used. The default
and minimum locale is POSIX.
"latency" and "action" (optional see Section xxxx) In a "VCALSTORE" it is a comma separated list of locales supported by
the CS. The first value in the list is the default for all newly
created VAGENDAs. POSIX MUST BE in the list.
Response: Format Definition: The property is defined by the following notation:
One of the following "request-status" codes MUST be returned default-locale = "DEFAULT-LOCALE" *(";" xparam)
for each target supplied and for each object deleted ":" language CRLF
as in that target that is effected.
2.0 - successfully deleted the component or calendar language = Text identifying a locale, as defined in [RFC 2277]
6.1 - Container not found Example: The following is an example of this property:
6.3 - Bad args DEFAULT-LOCALE:en-US.iso-8859-1,POSIX
The "delete" command is used to delete calendars or components. 7.9 DEFAULT-TZID Property
The "select" element specifies the container(s) to delete.
Restriction Table for the "delete" command of the "reply" Property Name: DEFAULT-TZID
response.
Component/Property Presence Comment Purpose: This property specifies the text value that specifies the
------------------- -------- ----------------------------- default time zone for a calendar.
VCALENDAR 1+ Value Type: TEXT
. VERSION 1 MUST be at least 2.0 Property Parameters: Non-standard property parameters can be
. VAGENDA Only if VAGENDAS were specified on this property.
deleted
. CMDID 0+ MUST BE supplied if it was Conformance: This property may be specified once in a "VAGENDA" and
supplied in the delete command. "VCALSTORE" components.
. METHOD 1 MUST BE DELETE Description: In a "VAGENDA" it is the value of the time zone for the
calendar. This time zone is used when as the localtime for object
that contain a date or date-time value without a time zone.
. TARGET 1+ In a "VCALSTORE" it is a comma separated list of TZIDs known to the
CS. Where TZID values are the same as the TZID property as defined
in [iCAL]. The first entry in the list is used as the default TZID
for all newly created calendars. The list MUST contain at least UTC.
. REQUEST-STATUS 1 If the TZID contains a comma (,), the comma must be backslash
escaped.
. VCAR 0+ Only if VCAR components were Format Definition: This property is defined by the following
deleted notation:
. . CARID 1
. . REQUEST-STATUS 1
. VEVENT 0+ Only if VEVENT components default-tzid = "DEFAULT-TZID" *(";" xparam)
were targets of deletion. ":" [tzidprefix] text CRLF
. . UID 1
. . REQUEST-STATUS 0 or 1 Omitted if an embedded VALARM was
the target of the deletion.
. . VALARM 0+ Only if VALARM components
were targets of deletion.
. . . SEQUENCE 1
. . . REQUEST-STATUS 1
. VFREEBUSY 0+ Only if VFREEBUSY was the target Example: The following is an example of this property:
of deletion.
. . UID 1
. . DTSTAMP 1
. . REQUEST-STATUS 1
. VJOURNAL 0+ Only if VJOURNAL components DEFAULT-TZID:US/Eastern,UTC
were targets of deletion.
. . UID 1
. . REQUEST-STATUS 1
. VQUERY 0+ Only if VQUERY components 7.10 DEFAULT-VCARS Property
were targets of deletion.
. UID 1
. REQUEST-STATUS 1
. VTIMEZONE 0+ Only if VTIMEZONE components Property Name: DEFAULT-VCARS
. . TZID were targets of deletion.
. . REQUEST-STATUS 1
. VTODO 0+ Only if VTODO components were Purpose: This property is used to specify the CARIDs of the default
targets of deletion. VCAR components for newly created VAGENDA components.
. . UID 1
. . REQUEST-STATUS 0 or 1 Omitted if an embedded VALARM was
the target of the deletion.
. . VALARM 0+ Only if VALARM components Value Type: TEXT
were targets of deletion.
. . . ALARMID 1
. . . REQUEST-STATUS 1
---------------------------------------------------------- Property Parameters: Non-standard property parameters can be
specified on this property.
Note: If a VAGENDA is deleted then NONE of its contained Conformance: This property MUST BE specified in "VCALSTORE" calendar
components will return any REQUEST-STATUS responses. component and MUST at least specify the following values:
READBUSYTIMEINFO, REQUESTONLY, UPDATEPARTSTATUS, and DEFAULTOWNER.
Example to delete a VEVENT with VEVENT UID 'abcd12345' from Description: This property is used in the "VCALSTORE" calendar
the calendar "relcald-22" from the current CS: component to specify the CARID of the VCAR components that MUST BE
copied in VAGENDA at creation time by the CS. These VCARS components
MUST BE stored in the "VCALSTORE".
C: Content-Type: text/calendar Format Definition: The property is defined by the following notation:
C:
C: BEGIN:VCALENDAR
C: TARGET:relcalid-22
C: METHOD:DELETE
C: CMDID:random but unique per CAU
C: BEGIN:VQUERY
C: QUERY:SELECT * FROM VEVENT WHERE UID = 'abcd12345'
C: END:VQUERY
C: END:VCALENDAR
One or more iCalendar object will be returned that contain def-vcars = "DEFAULT-VCARS" *(";" xparam) ":" text
a REQUEST-STATUS for the deleted components. There could have been *( "," text ) CRLF
more than one component deleted, Any booked and any
number of unprocessed iTIP scheduling components that
matched the QUERY value in the above example. Each
unique METHOD that was deleted from the store MUST BE in a
seperate iCalendar object. This is because only one METHOD is allowed
in an iCalendar object.
6.2.2.4 "modify" Command Example: The following is an example of this property:
Attributes: DEFAULT-VCARS:READBUSYTIMEINFO,REQUESTONLY,
UPDATEPARTSTATUS,DEFAULTOWNER
"latency" and "action" (Optional - see xxx) 7.11 DENY Property
Response: Property Name: DENY
One of the following "request-status" codes MUST be returned: Purpose: This property identifies the UPN(s) being denied access in
the VRIGHT component.
2.0 - successfully modified the component or calendar Value Type: UPN-FILTER
6.1 - Container not found Property Parameters: Non-standard property parameters can be
specified on this property.
6.3 - Bad args Conformance: This property can be specified in "VRIGHT" calendar
components.
The "modify" command is used to modify existing components. The Description: This property is used in the "VRIGHT" component to
TARGET property specifies the calendars were the components define the CU or UG being denied access.
exist that are going to be modified.
The format of the request is three containers inside of VCALENDAR Format Definition: The property is defined by the following notation:
container object:
BEGIN:VCALEDNAR deny = "DENY" *(";" xparam) ":" upn-filter CRLF
<VQUERY>
<OLD-VALUES>
<NEW-VALUES>
END:CALENDAR
The VQUERY selects the components that are to be modified. Example: The following are examples of this property:
The OLD-VALUES is a component and the contents of that component DENY:*
are going to change and may contain information that helps uniquely
identify the original component (SEQUENCE in the example below).
If the CS can not find a component that matches the QUERY and does
not have at least all of the OLD-VALUES, then a 6.1 error is returned.
The NEW-VALUES is a component of the same type as OLD-VALUES and DENY:bob@example.com
NEW-VALUES contains the new data for each selected component. Any
data that is in OLD-VALUES and not in NEW-VALUES is deleted from
the selected component. Any values in NEW-VALUES that was not in
OLD-VALULES is added to the component.
In this example the VEVENT with UID:unique-58 has; the LOCATION and 7.12 EXPAND property
LAST-MODIFIED changed, the VALARM with SEQUENCE:3 has its
TRIGGER disabled, the X-LOCAL property is removed from the VEVENT,
and a COMMENT is added.
Because SEQUENCE is used to locate the VALARM in this example, Property Name: EXPAND
both the OLD-VALUES and the NEW-VALUES contains SEQUENCE:3 and
if SEQUENCE was left out of NEW-VALUES - it would have been deleted.
Example: Purpose: This property is to notify the CS if it should or should not
expand any component with recurrence rules into multiple instances in
a query reply.
C: Content-Type: text/calendar Value Type: BOOLEAN
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: TARGET:my-cal
C: METHOD:MODIFY
C: BEGIN:VQUERY
C: QUERY:SELECT * FROM VEVENT WHERE UID = 'unique-58'
C: END:VQUERY
C: BEGIN:VEVENT
C: LOCATION:building 3
C: LAST-MODIFIED:20020101T123456Z
C: X-LOCAL:some private stuff
C: BEGIN:VALARM
C: SEQUENCE:3
C: TRIGGER;RELATED=END:PT5M
C: END:VALARM
C: END:VEVENT
C: BEGIN:VEVENT
C: LOCATION:building 4
C: LAST-MODIFIED:20020202T010203Z
C: COMMENT:Ignore global trigger.
C: BEGIN:VALARM
C: SEQUENCE:3
C: TRIGGER;ENABLE=FALSE:RELATED=END:PT5M
C: END:VALARM
C: END:VEVENT
C: />]]>
C: </modify>
C: END
X-LOCAL was not supplied in the NEW-VALUES, so it was deleted. Property Parameters: Non-standard property parameters can be
LOCATION was altered, as was LAST-MODIFIED. The VALARM with specified on this property.
SEQUENCE:3 had its TRIGGER disabled, and SEQUENCE did not
change so it was not effected. COMMENT was added.
When it comes to inline ATTACHMENTs, the CUA only needs to uniquely Conformance: This property can be specified in "VQUERY" calendar
identify the contents of the ATTACHE value in the OLD-VALUES in order components.
to delete them. When the CS compares the attachment data it is compared
in it binary form. The ATTACHMENT value supplied by the CUA MUST BE
valid encoded information.
For example, to delete a huge inline attachment from every Description: If a CUA wishes to see all of the instances of a
VEVENT in 'my-cal' that has an ATTACH with the OLD-VALUES: recurring component the CUA sets EXPAND=TRUE in the VQUERY component.
If not specified, the default is FALSE.
BEGIN:VCALENDAR Format Definition: The property is defined by the following notation:
VERSION:2.0
TARGET:my-cal
METHOD:MODIFY
BEGIN:VQUERY
QUERY:SELECT ATTACH FROM VEVENT
END:VQUERY
BEGIN:VEVENT
ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY:
MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U
EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE
...<remander of attachment data NOT supplied> ....
END:VEVENT
BEGIN:VEVENT
END:VEVENT
END:VCALENDAR
Above the NEW-VALUES is empty, so everything in the OLD-VALUES expand = "EXPAND" *(";" xparam) ":" ("TRUE" / "FALSE") CRLF
is deleted.
Furthermore, the following additional restrictions apply: Example: The following are examples of this property:
One can not change the "UID" property of a component. EXPAND:FALSE
EXPAND:TRUE
If a contained component is changed inside of a selected 7.13 GRANT Property
component, and that contained component has multiple
instances, then OLD-VALUES MUST contain information that
uniquely identifies the instance or instances that are
changing.
As all contained components that matching OLD-VALUES will be Property Name: GRANT
modified. In the first modify example above, if SEQUENCE were
to be deleted from both the OLD-VALUES and NEW-VALUES, then all
TRIGGERs that matched the OLD-VALUES in all VALARM in the
selected VEVENTs would be disabled.
The result of the modify MUST BE a valid iCalendar object. Purpose: This property identifies the UPN(s) being granted access in
the VRIGHT component.
If the REQUEST-STATUS is 2.0, then the entire modification was Value Type: UPN-FILTER
successful.
If any error occurred: Property Parameters: Non-standard property parameters can be
specified on this property.
No component will be changed at all. That is, it will Conformance: This property can be specified in "VRIGHT" calendar
appear just as it was prior to the modify and the CAP server components.
SHOULD return a REQUEST-STATUS for each error that occurred.
There MUST BE at least one error reported. Description: This property is used in the "VRIGHT" component to
specify the CU or UG being granted access.
If multiple components are selected, then the UID for each selected Format Definition: The property is defined by the following notation:
component MUST BE returned if the component contains a UID:
S: Content-Type: text/calendar grant = "GRANT" *(";" xparam) ":" upn-filter CRLF
S:
S: BEGIN:VCALENDAR Example: The following are examples of this property:
S: TARGET:relcalid
S: BEGIN:VEVENT
S: UID:123
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: END:VCALENDAR
6.2.2.5 "search" Command GRANT:*
Attributes: GRANT:bob@example.com
"latency" and "action" (Optional - see xxx) 7.14 MAXDATE Property
Response: Property Name: MAXDATE
One iCalendar message per "target" in the "select" element is Purpose: This property specifies the date/time in the future beyond
returned (see Section xxx). which the CS cannot represent.
One of the following "request-status" codes MUST be returned: Value Type: DATE-TIME
2.0 - successfully executed the query Property Parameters: Non-standard property parameters can be
specified on this property.
2.0.9 - success, but some data could not be returned Conformance: The property can be specified in the "VCALSTORE".
6.1 - Container not found Description: The date and time MUST BE a UTC value and end with 'Z'.
6.3 - Bad args Format Definition: The property is defined by the following notation:
The data in each result contains an iCalendar object composed maxdate = "MAXDATE" *(";" xparam) ":" date-time CRLF
of all the selected components. Only "REQUEST-STATUS"
and the properties mentioned in the "SELECT" clause of the
QUERY are included in the components. Each iCalendar object is
tagged with the TARGET property and optional CMDID property.
Searching for Events Example: The following is an example of this property:
In the example below events on March 10,1999 between 080000Z and MAXDATE:20990101T000000Z
190000Z are read. In this case only 4 properties for each event are
returned. Two calendars are specified. Only booked (vs scheduled)
entries are to be returned.
NOTE: BEEP headers and footers not included in the examples below. 7.15 MINDATE Property
C: Content-Type: text/calendar Property Name: MINDATE
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: METHOD:SEARCH
C: CMDID:search01
C: TARGET:relcal2
C: TARGET:relcal3
C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID
C: FROM VEVENT
C: WHERE DTEND >= '19990310T080000Z'
C: AND DTSTART <= '19990310T190000Z'
C: AND METHOD IS 'CREATE'
C: END:VQUERY
C: END:VCALENDAR
S: Content-Type: text/calendar Purpose: This property specifies the date/time in the past prior to
S: which the server cannot represent.
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: METHOD:REPLY
S: TARGET:relacal2
S: CMDID:search01
S: REQUEST-STATUS:2.0
S: BEGIN:VEVENT
S: DTSTART:19990310T090000Z
S: DTEND:19990310T100000Z
S: UID:abcxyz12345
S: SUMMARY:Meet with Sir Elton
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: BEGIN:VEVENT
S: DTSTART:19990310T130000Z
S: DTEND:19990310T133000Z
S: UID:abcxyz8999
S: SUMMARY:Meet with brave Sir Robin
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: END:VCALENDAR
S: Content-Type: text/calendar Value Type: DATE-TIME
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: METHOD:REPLY
S: CMDID:search01
S: TARGET:relcal3
S: REQUEST-STATUS:2.0
S: BEGIN:VEVENT
S: REQUEST-STATUS:2.0
S: DTSTART:19990310T140000Z
S: DTEND:19990310T150000Z
S: UID:123456asdf
S: SUMMARY:Summer Budget
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: END:VCALENDAR
The return values are subject to VCAR filtering. That is, if the Property Parameters: Non-standard property parameters can be
request contains properties to which the UPN does not have access, specified on this property.
those properties will not appear in the return values. If the UPN
has access to at least one property of the component, but has been
denied access to all properties called out in the request, the
response will contain a single REQUEST-STATUS property indicating the
error. That is, the VEVENT components will be the following:
Here the request was successful, but the VEVENT contents Conformance: The property can be specified in the "VCALSTORE".
were not accessable (4.1).
S: Content-Type: text/calendar Description: The date and time MUST BE a UTC value and end with 'Z'.
S:
S: BEGIN:VCALENDAR
S: METHOD:REPLY
S: TARGET:relcalid
S: CMIDID=any-id
S: VERSION:2.0
S: BEGIN:VEVENT
S: REQUEST-STATUS:4.1
S: END:VEVENT
S: END:VCALENDAR
If the UPN has no access to any components at all, the response will Format Definition: The property is defined by the following notation:
simply be an empty data set. The response looks the same if there
the particular components did not exist.
S: Content-Type: text/calendar mindate = "MINDATE" *(";" xparam) ":" date-time CRLF
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: METHOD:REPLY
S: CMDID:some-id
S: TARGET:ralcalid
S: REQUEST-STATUS:2.0
S: END:VCALENDAR
Find alarms within a range of time for booked VEVENTs. Example: The following is an example of this property:
C: Content-Type: text/calendar MINDATE:19710101T000000Z
C:
C: BEGIN:VCALENDAR
C: VERSION:2.0
C: METHOD:SEARCH
C: TARGET:"Doug:Baseball"
C: TARGET:"Steve:Baseball"
C: CMDID:search02
C: BEGIN:VQUERY
C: QUERY:SELECT DTSTART,DTEND,SUMMARY,UID,VALARM
C: FROM VEVENT,VTODO
C: USING_COMPONENT VALARM my-alarm
C: WHERE my-alarm.TRIGGER >= '19990310T080000Z'
C: AND my-alarm.TRIGGER <= '19990310T190000Z'
C: AND METHOD = 'CREATE'
C: END:VQUERY
C: END:VCALENDAR
Here no data was returned for relcal2: 7.16 NAME Property
S: Content-Type: text/calendar Property Name: NAME
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: TARGET:relcal2
S: CMDID:search02
S: METHOD:REPLY
S: REQUEST-STATUS:X.Y <- todo
S: END:VCALENDAR
And here relcal3 did return some resuls: Purpose: This property provides a localizeable display name for a
component.
S: Content-Type: text/calendar Value Type: TEXT
S:
S: BEGIN:VCALENDAR
S: VERSION:2.0
S: METHOD:REPLY
S: TARGET:relcal3
S: CMDID:search02
S: REQUEST-STATUS:2.0
S: BEGIN:VEVENT
S: DTSTART:19990310T130000Z
S: DTEND:19990310T133000Z
S: UID:abcxyz8999
S: SUMMARY:Meet with brave Sir Robin
S: BEGIN:VALARM
S: TRIGGER:19990310T132500Z
S: SUMMARY:Almost time...
S: ACTION:DISPLAY Property Parameters: Non-standard property parameters can be
S: END:VALARM specified on this property.
S: END:VEVENT
S: END:VCALENDAR
In this example bill@example.com reads a day's worth of events from Conformance: This property can be specified in a component.
cap://cal.example.com/opaqueid99. And the optional cmdid is not
supplied as the CUA will not issue another command until this
one completes.
C: BEGIN:VCALENDAR Description: This property is used in the in component to specify a
C: VERSION:2.0 localizeable display name. If more than one NAME property is in a
C: METHOD:SEARCH component, then they MUST have unique LANG parameters. If the LANG
C: TARGET:opaqueid99 parameter is not supplied, then it defaults to the VAGENDAs default
C: BEGIN:VQUERY if the component is in a VAGENDA, or the VCALSTORE default if the
C: QUERY:SELECT DTSTART,DTEND,SUMMARY, UID FROM VEVENT component is stored at the VCALSTORE level.
C: WHERE DTEND >= '19990714T080000Z'
C: AND DTSTART <= '19990715T080000Z'
C: END:VQUERY
C: END:VCALENDAR
If there are multiple targets, each iCalendar reply is contained Format Definition: The property is defined by the following notation:
within its own <reply>.
Stored VQUERY can be used by specifying the property QUERYID name = "NAME" nameparam ":" text CRLF
instead of QUERY.
This matches all calendar store properties. This MUST NOT return any nameparam = *(
VAGENDAs. IT would return all RELATED-TO properties. ; the following is optional,
; but MUST NOT occur more than once
BEGIN:VCALENDAR ( ";" languageparam ) /
VERSION:2.0
METHOD:SEARCH
TARGET:cap://bobo.ex.com
BEGIN:VQUERY
QUERY:SELECT * FROM VCALSTORE
END:VQUERY
END:VCALENDAR
This will match all properties of the VAGENDA relcal4. This MUST NOT ; the following is optional,
return any components. ; and MAY occur more than once
BEGIN:VCALENDAR ( ";" xparam )
VERSION:2.0 )
METHOD:SEARCH
TARGET:cap://bobo.ex.com/relcal4
BEGIN:VQUERY
QUERY:SELECT * FROM VAGENDA
END:VQUERY
END:VCALENDAR
This will fetch all stored VQUERYs. All stored queries MUST BE languageparam = ; As defined in [iCAL].
saved with a QUERYID.
BEGIN:VCALENDAR Example: The following is an example of this property:
VERSION:2.0
METHOD:SEARCH
TARGET:relcal4
BEGIN:VQUERY
QUERY:SELECT VQUERY.* FROM VQUERY.
END:VQUERY
END:VCALENDAR
6.2.2.6 Response Codes NAME:Restrict Guests From Creating VALARMs On VEVENTs
Numeric response codes are returned at both the transfer and 7.17 OWNER Property
application layer. The same set of codes is used in both cases.
The format of these codes is described in [RFC2445], and extend in Property Name: OWNER
[iTIP] and [iMIP]. The following describes new codes added to this
set.
At the application layer response codes are returned as the value of Purpose: The property specifies an owner of the component.
a "REQUEST-STATUS" property. The value type of this property is
modified from that defined in [RFC2445], to make the accompanying
text optional.
Code Description Value Type: UPN
--------------------------------------------------------------
2.0 Success. The parameters vary with the
operation and are specified.
2.0.3 In response to the client issuing an Property Parameters: Non-standard, alternate text representation and
"abort" reply, this reply code indicates language property parameters can be specified on this property.
that any command currently underway was
successfully aborted.
2.0.9 Success of the read operation, but some Conformance: The property MUST BE specified at in a "VAGENDA"
requested information could not be returned component.
due to access control.
3.1.4 Capability not supported. Description: A multi-instanced property indicating the calendar
owner.
4.1 Calendar store access denied. Format Definition: The property is defined by the following notation:
6.3 Attempt to create or modify an event owner = "OWNER" *(";" xparam) ":" upn CRLF
such that it would overlap another event
in either of the following two circum-
stances:
(a) One of the events has a TRANSP Example: The following is an example of this property:
property set to OPAQUE-NOCONFLICT or
TRANSPARENT-NOCONFLICT.
(b) The calendar's ALLOW-CONFLICT OWNER:jsmith@acme.com
property is set to NO. OWNER:jdoe@acme.com
6.XXX [EDITORS NOTE: More are in this memo - 7.18 PERMISSION Property
add here TODO]
7.0 A timeout has occurred. The server was Property Name: PERMISSION
unable to complete the operation in the
requested time.
8.0 A failure has occurred in the Calendar Service Purpose: This property defines a permission that is granted or denied
that prevents the operation from in a VRIGHT component.
succeeding.
8.2 Used to signal that an iCalendar object has Value Type: TEXT
exceeded the server's size limit
8.3 A DATETIME value was too far in the future Property Parameters: Non-standard property parameters can be
represented on this Calendar. specified on this property.
8.4 A DATETIME value was too far in the past Conformance: This property can be specified in "VRIGHT" calendar
to be represented on this Calendar. components.
8.5 An attempt was made to create a new Description: This property is used in the "VRIGHT" component to
object but the unique id specified is define a permission that is granted or denied.
already in use.
9.0 An unrecognized command was received. Format Definition: The property is defined by the following notation:
10.4 The operation has not been performed perm = "PERMISSION" *(";" xparam) ":" permvalue CRLF
because it would cause the resources
(memory, disk, CPU, etc) to exceed the
allocated quota.
--------------------------------------------------------------
7. Initial Registrations permvalue = ( "READ" / "CREATE" / "DELETE" / "MODIFY" / all )
7.1 BEEP Profile Registration all = "*"
Profile Identification: http://iana.org/beep/transient/calsch/ Example: The following is an example of this property:
cap/1.0
Messages exchanged during Channel Creation: none PERMISSION:READ
Messages starting one-to-one exchanges: 7.19 QUERY property
"timeout", "generate-uid", "identify", "get-capability" Property Name: QUERY
Messages in positive replies: Purpose: Specifies the query for the component.
"uid-list", "abort", "continue", "result", "capability" Value Type: CAL-QUERY
Messages in negative replies: Property Parameters: Non-standard property parameters can be
specified on this property.
"error" Conformance: This property can be specified in "VQUERY" components.
Messages in one-to-many exchanges: "create", "search", Description: A "QUERY" is used to specify the CAL-QUERY (Section
"delete", "modify" or "schedule" 6.1.1 for the query.
Message Syntax: c.f., Section 8 Format Definition: The property is defined by the following notation:
Message Semantics: c.f., Section 6 query = "QUERY" *(";" xparam) ":" cal-query CRLF
Contact Information: c.f., the "Author's Address" section of Example: The following is an example of this property:
this memo
7.2 Registration: The System (Well-Known) TCP port number for CAP QUERY:SELECT * FROM VEVENT
A single well-known port (xxxx) is allocated to CAP. 7.20 QUERYID property
Protocol Number: Property Name: QUERYID
TCP Purpose: Specifies a unique ID for a query in the targeted container.
Message Formats, Types, Opcodes, and Sequences: Value Type: TEXT
Section 8 Property Parameters: Non-standard property parameters are specified
on this property.
Functions: Conformance: This property can be specified in "VQUERY" components.
Section 6 Description: A "QUERYID" is used to specify the unique id for a
Use of Broadcast/Multicast: stored query.
none Format Definition: The property is defined by the following notation:
Proposed Name: queryid = "QUERYID" *(";" xparam) ":" text CRLF
Calendar Access Protocol Example: The following are examples of this property:
Short name: QUERYID:Any Text String
QUERYID:fetchUnProcessed
cap 7.21 REQUEST-STATUS property
Contact Information: This description is a revision of the REQUEST-STATUS property for
VCALENDAR version 2.0. The 'statdesc' is optional and the 'extdata'
may be included when 'statdesc' is not provided.
cf., the "Authors' Addresses" section of this draft rstatus = "REQUEST-STATUS" rstatparam ":"
statcode ";" *(statdesc ) ";" *(extdata)
8. CAP DTD rstatparam = *(
; the following is optional,
; but MUST NOT occur more than once
To Be Done. (";" languageparm) /
9. Properties ; the following is optional,
; and MAY occur more than once
[Once definitions are in iCalendar format and are agreed on, should (";" xparam)
be moved into section "Extension to iCalendar"]
9.1 Calendar Store Properties )
The following are properties of the calendar store. statcode = 1*DIGIT *("." 1*DIGIT)
;Hierarchical, numeric return status code
Name Read Value Description statdesc = text
Only Type ;An optional textual status description, content is
-------------------------------------------------------------- ;decided by the implementor. May be empty.
CALMASTER N URI URL of contact address for person
responsible. SHOULD BE
mailto URL.
CSID Y URI The CSID of this calendar extdata = text
store. If not specified, it is ; Textual exception data. For example, the offending
the same as the hostname. ; property name and value or complete property line.
DEFAULT_VCARS N TEXT A multivalued property Example: The following are some possible examples of this property.
containing the default VCARs The COMMA and SEMICOLON separator characters in the property value
for newly created top level are BACKSLASH character escaped because they appear in a text value.
calendars. Each entry is a
CARID. It MUST include at a
minimum
READBUSYTIMEINFO,REQUESTONLY,
UPDATEPARTSTATUS, and
DEFAULTOWNER.
MAXDATE Y DATE-TIME The date/time in the future REQUEST-STATUS:2.0;Success
beyond which the server cannot
represent. If not specified,
then 99991231T235959 will be
assumed.
MINDATE Y DATE-TIME The date/time in the past prior REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01
to which the server cannot
represent. If not specified,
then 00000101T000000 will be
assumed.
CURRENT_DATETIME Y DATE-TIME Current server time. This is REQUEST-STATUS:2.8; Success\, repeating VEVENT ignored. Scheduled
returned as a local time and as a single VEVENT.;RRULE:FREQ=WEEKLY;INTERVAL=2
TZID.
RECUR_ACCEPTED Y BOOLEAN Boolean value will be set to REQUEST-STATUS:4.1;Time conflict. Date/time is busy.
TRUE if the server will accept
recurrence rules. It will be
set to FALSE if the server will
not accept recurrence rules. If
not specified a CUA MUST assume
TRUE.
RECUR_EXPAND Y BOOLEAN If set to TRUE, the CS supports REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE:
the expansion of recurrence MAILTO:jsmith@example.com
rules in the returned set. If set
to FALSE, the CS is incapable
of expanding recurrence rules.
If not specified a CUA MUST assume
TRUE.
RECUR_LIMIT Y INTEGER This numeric value describes REQUEST-STATUS:3.7;;ATTENDEE:MAILTO:jsmith@example.com
how the server handles
unbounded recurrences. The
value is only valid if
RECURRENCE is TRUE. If the
value is 0 it means that the
server supports unbounded
recurrence rules. If it is non-
zero, it is a positive integer
indicating the number of
instances that will be returned
when the server expands an
unbounded recurrence rule when
fetched from the CS. A CUA MUST
query for date ranges when this
value is zero.
VERSION Y TEXT The version of the CS. The REQUEST-STATUS:10.4;Help! That really shouldn't have happened.
default and the only currently
Supported version is "2.0" to
match the [RFC2445] VERSION.
9.2 Calendar Properties 7.22 RESTRICTION Property
Name Read Value Description Property Name: RESTRICTION
Only Type
--------------------------------------------------------------
ALLOW-CONFLICT N BOOLEAN This boolean value indicates
Whether or not the calendar
supports event conflicts. That
is, whether or not any of the
events in the calendar can
overlap. If not specified the
default value is TRUE meaning
that conflicts are allowed.
CALSCALE N TEXT The CALSCALE for this calendar. Purpose: This property defines restrictions on the result value of
If not specified the default is new or existing components.
GREGORIAN.
CHARSET N TEXT The default charset for Value Type: CAL-QUERY
Localized strings in this
calendar. If not specified, the
default is UTF-8.
CHILD Y TEXT A sub-calendars belonging to this Property Parameters: Non-standard property parameters can be
calendar. A calendar may have specified on this property.
multiple sub-calendars, each one
corresponding to a CHILD property.
CREATED Y DATE-TIME The timestamp of the calendar's Conformance: This property can be specified in "VRIGHT" calendar
create date. components, but only when the PERMISSION property is set to "CREATE",
"MODIFY", or "*".
DEFAULT_VCARS N TEXT The default VCARs for newly Description: This property is used in the "VRIGHT" component to
Created top level calendars. define restrictions on the components that can be written (i.e., by
This is a CARID. The default using the "CREATE" or "MOVE" commands) as well as on the values that
value is the value of may take existent calendar store properties, calendar properties,
DEFAULT_VCARS in the VCALSTORE components, and properties (i.e., by using the "MODIFY" command).
table. Accepted values MUST match the specified RESTRICTION.
LANGUAGE N TEXT The default language for Format Definition: The property is defined by the following notation:
localizable strings in this
calendar. There is no default.
This value MUST NOT be empty.
The possible values of this
property are those specified in
RFC-3066.
LAST-MODIFIED N DATE-TIME The timestamp when the restrict = "RESTRICTION" *(";" xparam) ":" cal-query CRLF
Properties of the calendar were
last updated. Default is the
same as CREATED.
NAME N TEXT The display name for this Example: The following are examples of this property:
calendar. It is a localizable
string. If not provided, an
empty value will be returned.
OWNER N URI A multi-instanced property RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST'
indicating the calendar owner.
Each entry returned will be a
UPN. There must be at least one
owner.
PARENT N URI The CALID of this calendar's RESTRICTION:SELECT * FROM VEVENT WHERE
Parent maintained by a CAP SELF() IN CAL-OWNERS(ORGANIZER)
server. An empty value means
the calendar is the top level
parent. The default value is no
parent.
RELCALID N URI A unique identifier within this RESTRICTION:SELECT * FROM VEVENT WHERE 'BUSINESS' IN
cal-store for the calendar. CATEGORIES
There is no default value.
This value MUST NOT be empty.
TOMBSTONE N BOOLEAN TRUE indicator that this 7.23 SCOPE Property
Calendar has been marked as
deleted. The default value is
FALSE.
TZID N TEXT The id of the timezone Property Name: SCOPE
Associated with this calendar.
See TZID in [RFC2445]. The default
value is UTC.
10. Security Considerations Purpose: This property identifies the objects in the CS to which the
access rights applies.
Access rights should be granted cautiously, consult Section 2.4.2 for Value Type: CAL-QUERY
a discussion of the subject.
The "identify" command should be carefully implemented as discussed Property Parameters: Non-standard property parameters can be
in Section 6.1.3. specified on this property.
In addition, since CAP is a profile of the BEEP, consult [BEEP]'s Conformance: This property can be specified in "VRIGHT" calendar
Section 9 for a discussion of BEEP-specific security issues. components.
Although service provisioning is a policy matter, at a minimum, all Description: This property is used in the "VRIGHT" component to
implementations must provide the following tuning profiles: define the set of objects subject to the access right being defined.
for authentication: http://iana.org/beep/SASL/DIGEST-MD5 Format Definition: The property is defined by the following notation:
for confidentiality: http://iana.org/beep/TLS (using the scope = "SCOPE" *(";" xparam) ":" cal-query CRLF
TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher)
for both: http://iana.org/beep/TLS (using the Example: The following is an example of this property:
TLS_RSA_WITH_3DES_EDE_CBC_SHA cipher supporting client-side
certificates)
11. Extensions To iCalendar SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC'
The following section contains new components, properties, 7.24 TARGET Property
parameters, and values.
11.1 Property Value Data Types Property Name: TARGET
11.1.1 UPN Purpose: This property defines the container that the command that is
issued will act upon. It its value is a capurl as defended in
Section 5.
To: ietf-calendar@imc.org Value Type: URI
Subject: Registration of text/calendar MIME value type UPN Property Parameters: Non-standard property parameters can be
specified on this property.
Value Name: UPN Conformance: This property can be specified in a command component.
Purpose: This value type is used to identify values that contain user Description: This properties value is used to specify the container
principal name of CU or group of CU. that the command will effect. When used in a command, the command
will be performed on the container which has a capurl matching the
value.
Formal Definition: The value type is defined by the following Format Definition: The property is specified by the following
notation: notation:
upn = "@" / target = "TARGET" *(";" xparam) ":" capurl CRLF
[ dot-atom-text ] "@" dot-atom-text
; dot-atom-text is defined in RFC 2822 The following is an example of this property:
Description: This data type is an identifier that denotes a CU or a TARGET:cap://mycal.example.com
group of CU. A UPN is a RFC 2822 compliant e-mail address, with TARGET:SomeRelCalid
exceptions listed below, and in most cases it is deliverable to the
CU. In some cases it is identical to the CU's well known email
address. A CU's UPN MUST never be an e-mail address that is
deliverable to a different person as there is no requirement that a
person's UPN must be his e-mail address.
In certain cases a UPN will not be RFC 2822 compliant. When 7.25 TRANSP Property
anonymous authentication is used, or anonymous authorization is being
defined, the special UPN "@" will be used. When authentication must
be used, but unique identity must be obscured, a UPN of the form
@DNS-domain-name may be used.
Example: Property Name: TRANSP
The following is a UPN for a CU: Purpose: This property defines whether an component is transparent or
not to busy time searches. This is a modification to [iCAL] TRANSP
in that it adds some values.
jdoe@acme.com Value Type: TEXT
The following is a UPN for a group of CU: Property Parameters: Non-standard property parameters can be
specified on this property.
staff@acme.com Conformance: This property can be specified in a component.
The following is a UPN for an anonymous CU belonging to Description: Time Transparency is the characteristic of an object
that determines whether it appears to consume time on a calendar.
Objects that consume actual time for the individual or resource
associated with the calendar SHOULD be recorded as OPAQUE, allowing
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
recorded as TRANSPARENT, making them invisible to free-busy time
searches.
@acme.com Format Definition: The property is specified by the following
notation:
The following is a UPN for an anonymous CU: transp = "TRANSP" *(";" xparam) ":" transvalue CRLF
@ transvalue = "OPAQUE" ;Blocks or opaque on busy time searches.
/ "TRANSPARENT" ;Transparent on busy time searches.
11.1.2 UPN Filter / "TRANSPARENT-NOCONFLICT" ; Transparent on busy time
; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects
; can overlap it.
To: ietf-calendar@imc.org / "OPAQUE-NOCONFLICT" ; Opaque on busy time
; searches and no other OPAQUE or OPAQUE-NOCONFLICT objects
; can overlap it.
;
;Default value is OPAQUE
Subject: Registration of text/calendar MIME value type UPN-FILTER 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
overlap it:
Value Name: UPN-FILTER TRANSP:OPAQUE-NOCONFLICT
Purpose: This value type is used to identify values that contain a 8. New Components
user principal name filter.
Formal Definition: The value type is defined by the following 8.1 VAGENDA Component
notation:
upn-filter = "OWNER" / Component Name: VAGENDA
"NONOWNER" /
"*" /
[ "*" / dot-atom-text ] "@" ( "*" / dot-atom-text )
; dot-atom-text is defined in RFC 2822 Purpose: Provide a grouping of properties that defines an agenda.
Description: The value is used to match user principal names (UPNs). Formal Definition: There are two formats of a VAGENDA. (1) When it
is being created, and (2) how it exists in the VCALSTORE. A
"VAGENDA" component in the VCALSTORE is defined by the following
notation table and ABNF notation.
Example: The following are examples of this value type: The following is a summary of the properties of a calendar.
OWNER Matches the UPNs equal to any instance Name Read Description
of the OWNER property of the VAGENDA in Only
which the encapsulating VCAR is stored. ------------------------------------------------------------------
ALLOW-CONFLICT N This boolean value indicates whether or not
the calendar supports object conflicts. That
is, whether or not any of the components in
the calendar can have a time overlap. MUST BE
FALSE if VCALSTORE ALLOW-CONFLICT is FALSE.
NONOWNER Matches all UPNs different from all CALID N A unique identifier within the VCALSTORE for
instances of the OWNER property of the the calendar. MUST NOT BE empty. MUST BE a
VAGENDA in which the encapsulating VCAR relative calid in a VAGENDA.