Internet Draft CAP March 10, 2000
Network Working Group Steve Mansour/Netscape
Internet Draft Frank Dawson/Lotus
<draft-ietf-calsch-cap-02.txt> Doug Royer/Software.com
Alexander Taler/CS&T
Paul Hill/MIT
Expires six months from: March 10, 2000
Calendar Access Protocol (CAP)
Status of this Memo
This memo is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Task
Force (IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet- Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt .
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Distribution of this document is unlimited.
Copyright Statement
Copyright (C) The Internet Society 2000. All Rights Reserved.
Abstract
The Calendar Access Protocol (CAP) is an Internet protocol that
permits a Calendar User (CU) to utilize a Calendar User Agent (CUA) to
access an [RFC2445] based Calendar Store (CS). This memo defines the
CAP specification.
The CAP definition is based on requirements identified by the Internet
Engineering Task Force (IETF) Calendaring and Scheduling (CALSCH)
Working Group. More information about the IETF CALSCH 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
Mansour/Dawson/Royer/Taler/Hill 1 Expires September 2000
Internet Draft CAP March 10, 2000
http://www.ietf.org/html.charters/calsch-charter.html. Refer to the
references within this memo for further information on how to access
these various documents.
Mansour/Dawson/Royer/Taler/Hill 2 Expires September 2000
Internet Draft CAP March 10, 2000
Table of Contents
1. Introduction ................................................... 3
1.1. Formatting Conventions ....................................... 3
1.2. Related Documents ............................................ 3
1.3. Definitions .................................................. 4
2. CAP Design ..................................................... 10
2.1. System Model ................................................. 10
2.2. Calendar Store Object Model .................................. 11
2.3. Protocol Model ............................................... 11
2.4. Security Model ............................................... 13
2.4.1. Authentication, Credentials, and Identity .................. 14
2.4.2. Calendar User and UPNs ..................................... 14
2.4.2.1. UPNs and Certificates .................................... 15
2.4.2.2. Anonymous Users and Authentication ....................... 16
2.4.2.3. Required Security Mechanisms ............................. 16
2.4.2.4. TLS Ciphersuites ......................................... 17
2.4.3. User Groups ................................................ 17
2.4.4. Access Rights .............................................. 18
2.4.4.1. VCalendar Access Right (VCAR) ........................... 18
2.4.4.2. Decreed VCARs ............................................ 19
2.4.4.3. Inheritance .............................................. 19
2.4.5. CAP session identity ....................................... 19
2.5. Roles ........................................................ 20
2.6. Calendar Addresses ........................................... 21
2.7. Extensions to iCalendar ...................................... 21
2.8. Relationship of RFC 2446 (ITIP) to CAP ....................... 22
2.9. VCalendar Access Rights (VCARs) .............................. 23
2.10. Query Schema ................................................ 23
3. State Diagram .................................................. 23
4. Protocol Framework ............................................. 25
4.1. CAP Application Layer ........................................ 25
4.2. CAP Transfer Protocol ........................................ 25
4.3. Response Format .............................................. 25
4.4. Auto-logout Timer ............................................ 26
4.5. Bounded Latency .............................................. 26
4.6. Data Elements ................................................ 27
5. Formal Command Syntax .......................................... 27
5.1. Searching and Filtering ...................................... 27
5.1.1. Grammar For Search Mechanism ............................... 27
6. Access Rights .................................................. 28
6.1. VCAR Inheritance ............................................. 28
6.2. Access Control and NOCONFLICT ................................ 28
7. Commands and Responses ......................................... 29
7.1. Transfer Protocol Commands ................................... 29
7.1.1. Initial Connection ......................................... 29
7.1.2. ABORT Command .............................................. 30
7.1.3. AUTHENTICATE Command ....................................... 30
7.1.3.1. AUTHENTICATE ANONYMOUS ................................... 33
7.1.4. CALIDEXPAND Command ........................................ 34
7.1.5. CAPABILITY Command ......................................... 35
7.1.6. CONTINUE Command ........................................... 36
7.1.7. DISCONNECT Command ......................................... 37
7.1.8. IDENTIFY Command ........................................... 38
Mansour/Dawson/Royer/Taler/Hill Expires September 2000
Internet Draft CAP March 10, 2000
7.1.9. SENDDATA Command ........................................... 38
7.1.10. STARTTLS Command .......................................... 38
7.1.10.1. UPNEXPAND Method ........................................ 39
7.2. Application Protocol Commands ................................ 40
7.2.1. Calendaring Commands ....................................... 40
7.2.1.1. CREATE Method ............................................ 40
7.2.1.1.1. Creating New Calendars ................................. 41
7.2.1.2. DELETE Method ............................................ 43
7.2.1.3. GENERATEUID Method ....................................... 44
7.2.1.4. MODIFY Method ............................................ 44
7.2.1.5. MOVE Method .............................................. 45
7.2.1.6. NOOP Method .............................................. 46
7.2.1.7. READ Method .............................................. 46
7.2.2. Scheduling Commands ........................................ 50
7.2.2.1. Reading out scheduling components ........................ 50
7.2.2.2. PUBLISH .................................................. 51
7.2.2.3. REQUEST .................................................. 52
7.2.2.4. REPLY .................................................... 52
7.2.2.5. ADD ...................................................... 52
7.2.2.6. CANCEL ................................................... 52
7.2.2.7. REFRESH .................................................. 52
7.2.2.8. COUNTER .................................................. 52
7.2.2.9. DECLINECOUNTER ........................................... 52
7.2.3. iTIP Examples .............................................. 52
7.2.3.1. Sending and Receiving an iTIP request .................... 52
7.2.3.2. Handling an iTIP refresh ................................. 55
7.2.3.3. Sending and accepting an iTIP counter .................... 56
7.2.3.4. Declining an iTIP counter ................................ 57
8. Response Codes ................................................. 58
8.1. Minimum CS query implementation .............................. 60
8.1.1. Query by UID ............................................... 60
8.1.2. Query by Date / Date-Time range ............................ 60
8.1.2.1. Date/Date-Time query with subset of properties ........... 60
8.1.3. <TBD> ...................................................... 60
9. Detailed SQL Schema ............................................ 60
9.1. iCalendar Store Schema ....................................... 62
9.1.1. ACTION schema .............................................. 62
9.1.2. ATTACH schema .............................................. 63
9.1.3. ATTENDEE schema ............................................ 63
9.1.4. CALSTORE schema ............................................ 63
9.1.5. CHILDREN schema ............................................ 64
9.1.6. CLASS schema ............................................... 64
9.1.7. CN schema .................................................. 64
9.1.8. COMMENT schema ............................................. 64
9.1.9. CONTACT schema ............................................. 64
9.1.10. CREATED schema ............................................ 65
9.1.11. CUTYPE schema ............................................. 65
9.1.12. DAYLIGHT_STANDARD schema .................................. 65
9.1.13. DESCRIPTION schema ........................................ 65
9.1.14. DIR schema ................................................ 66
9.1.15. DTEND schema .............................................. 66
9.1.16. DTSTAMP schema ............................................ 66
9.1.17. DUE schema ................................................ 66
Mansour/Dawson/Royer/Taler/Hill Expires September 2000
Internet Draft CAP March 10, 2000
9.1.18. DURATION schema ........................................... 67
9.1.19. EXDATE schema ............................................. 67
9.1.20. EXRULE schema ............................................. 67
9.1.21. FBTYPE schema ............................................. 67
9.1.22. FMTTYPE schema ............................................ 67
9.1.23. FREEBUSY schema ........................................... 68
9.1.24. GEO schema ................................................ 68
9.1.25. LANGUAGE schema ........................................... 68
9.1.26. LAST_MODIFIED schema ...................................... 68
9.1.27. MEMBER schema ............................................. 68
9.1.28. METHOD schema ............................................. 69
9.1.29. ORGANIZER schema .......................................... 69
9.1.30. OWNERS schema ............................................. 69
9.1.31. PARTSTAT schema ........................................... 69
9.1.32. PERCENT_COMPLETE schema ................................... 70
9.1.33. PRIORITY schema ........................................... 70
9.1.34. RDATE schema .............................................. 70
9.1.35. RECUR schema .............................................. 70
9.1.36. RECURRENCE_ID schema ...................................... 71
9.1.37. RELATED_TO schema ......................................... 72
9.1.38. REPEAT schema ............................................. 72
9.1.39. RESOURCES schema .......................................... 72
9.1.40. ROLE schema ............................................... 72
9.1.41. RRULE schema .............................................. 73
9.1.42. SEQUENCE schema ........................................... 73
9.1.43. STATUS schema ............................................. 73
9.1.44. SUMMARY schema ............................................ 73
9.1.45. TRANSP schema ............................................. 73
9.1.46. TRIGGER schema ............................................ 74
9.1.47. TZID schema ............................................... 74
9.1.48. UID schema ................................................ 74
9.1.49. URL schema ................................................ 74
9.1.50. VALARM schema ............................................. 75
9.1.51. VCALENDAR schema .......................................... 75
9.1.52. VCAR schema ............................................... 75
9.1.53. VEVENT schema ............................................. 75
9.1.54. VFREEBUSY schema .......................................... 76
9.1.55. VJOURNAL schema ........................................... 77
9.1.56. VQUERY schema ............................................. 77
9.1.57. VTIMEZONE schema .......................................... 78
9.1.58. VTODO schema .............................................. 78
9.1.59. X_PROP schema ............................................. 79
9.1.60. XPARAM schema ............................................. 79
9.2. Query example ................................................ 79
10. Examples ...................................................... 79
10.1. Authentication Examples ..................................... 79
10.1.1. Login Using Kerberos V4 ................................... 79
10.1.2. Error Scenarios ........................................... 80
10.2. Read Examples ............................................... 81
10.2.1. Read From A Single Calendar ............................... 81
10.2.2. Read From Multiple Calendars .............................. 82
10.2.3. Timeouts .................................................. 83
10.2.4. Using the Calendar Parent, Children Properties ............ 84
Mansour/Dawson/Royer/Taler/Hill Expires September 2000
Internet Draft CAP March 10, 2000
10.2.5. An example that depends on VEVENT.DTSTART and VALARM.DT-
START ........................................................ 84
11. Implementation Issues ......................................... 84
12. Properties .................................................... 84
12.1. Calendar Store Properties ................................... 84
12.2. Calendar Properties ......................................... 85
13. Security Considerations ....................................... 87
14. Changes to iCalendar .......................................... 87
14.1. Time Transparency ........................................... 88
14.2. RIGHTS Value Type ........................................... 89
14.3. VCAR Calendar Component ..................................... 92
14.4. GRANT Component Property .................................... 94
14.5. DENY Component Property ..................................... 94
14.6. VCAR Identifier Component Property .......................... 95
15. CAP Entities Registration ..................................... 96
15.1.1. Define the Entity ......................................... 97
15.1.2. Post the entity definition ................................ 98
15.1.3. Allow a comment period .................................... 98
15.1.4. Submit the entity for approval ............................ 98
15.2. Property Change Control ..................................... 98
16. IANA Considerations ........................................... 99
17. Acknowledgments ............................................... 99
18. Bibliography .................................................. 99
19. Author's Address .............................................. 100
20. Full Copyright Statement ...................................... 101
Mansour/Dawson/Royer/Taler/Hill Expires September 2000
Internet Draft CAP March 10, 2000
1. Introduction
This document specifies how a Calendar User Agent (CUA) interacts with a
Calendar Store (CS) to manage calendar information. In particular, it
specifies how to query, create, modify, and delete iCalendar components
(e.g., events, to-dos, or daily journal entries). It further specifies
how to search for available busy time information.
This protocol is based on request/response form of protocol data units,
sent from a client CUA to a calendar server. The protocol data units
leverage the standard iCalendar format [RFC2445] for conveying CS
related information.
1.1. Formatting Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
Calendaring and scheduling roles are referred to in quoted-strings of
text with the first character of each word in upper case. For example,
"Organizer" refers to a role of a "Calendar User" (CU) within the
protocol defined by this memo. Calendar components defined by [RFC2445]
are referred to with capitalized, quoted-strings of text. All calendar
components start with the letter "V". For example, "VEVENT" refers to
the event calendar component, "VTODO" refers to the to-do calendar
component and "VJOURNAL" refers to the daily journal calendar component.
Calendar access methods defined by this memo, as well as scheduling
methods defined by [RFC2446], are referred to with capitalized, quoted-
strings of text. For example, "CREATE" refers to the method for creating
a calendar component on a calendar, "READ" refers to the method for
reading calendar components.
Properties defined by this memo are referred to with capitalized,
quoted-strings of text, followed by the word "property". For example,
"ATTENDEE" property refers to the iCalendar property used to convey the
calendar address of a "Calendar User". Property parameters defined by
this memo are referred to with lower case, quoted-strings of text,
followed by the word "parameter". For example, "value" parameter refers
to the iCalendar property parameter used to override the default data
type for a property value. 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 order
to minimize the table length.
1.2. Related Documents
Implementers will need to be familiar with several other memos that,
along with this one, describe the Internet calendaring and scheduling
Mansour/Dawson/Royer/Taler/Hill 3 Expires September 2000
Internet Draft CAP March 10, 2000
standards. This document,
[RFC2445] specifies the objects, data types, properties and property
parameters used in the protocols, along with the methods for
representing and encoding them;
[RFC2446] specifies an interoperability protocol for scheduling between
different implementations. The related documents are:
[RFC2447] specifies an Internet email binding for [RFC2446].
[iRIP] specifies a real-time binding for [RFC2446].
This memo does not attempt to repeat the specification of concepts or
definitions from these other memos. Where possible, references are made
to the memo that provides for the specification of these concepts or
definitions.
1.3. Definitions
Authentication ID (AuthID)
A tuple of username, realm, and authentication method, used by the
Calendar Service internally to identify a successfully authenticated
CAP session.
Calendar
A collection of logically related objects or entities each of which
may be associated with a calendar date and possibly time of day. These
entities can include other calendar properties or calendar components.
In addition, a calendar might be hierarchically related to other sub-
calendars. 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)
The standard Internet protocol that permits a Calendar User Agent to
access and manipulate a calendar residing on a Calendar Store.
Calendar Access Rights (CAR)
The mechanism for specifying the CAP operations ("ACTIONS") that a
particular calendar user ("UPN") are granted or denied permission to
perform on a given calendar entity ("OBJECT"). The calendar access
rights are specified with the "VCAR" calendar components within a CS
and calendar.
Mansour/Dawson/Royer/Taler/Hill 4 Expires September 2000
Internet Draft CAP March 10, 2000
Calendar Collection
A collection of Calendars, Resource Calendars, and/or other Calendar
Collections. These collections are expanded by the CS and may reside
either locally or in an external database or directory. The calendars
in the collection may be fixed or dynamic over time.
Calendar Component
An entity within a calendar. Some types of calendar components include
events, to-dos, 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
An attribute of a particular calendar component. Some calendar
component properties are applicable to different types of calendar
components. For example, DTSTART is applicable to VEVENT, VTODO,
VJOURNAL calendar components. Other calendar components are applicable
only to an individual type of calendar component. For example, TZURL
is only applicable to VTIMEZONE calendar components.
Calendar Identifier (CalID)
A globally unique identifier associated with a calendar. Calendars
reside within a CS. See Qualified Calendar Identifier and Relative
Calendar Identifier.
Calendar Policy
A CAP operational restriction on the access or manipulation of a
calendar. For example, "events MUST be scheduled in unit intervals of
one hour".
Calendar Properties
An attribute of a calendar. The attribute applies to the calendar, as
a whole. For example, CALSCALE specifies the calendar scale (e.g.,
GREGORIAN) for the whole calendar.
Calendar Service
An implementation of a Calendar Store that manages one or more
calendars.
Mansour/Dawson/Royer/Taler/Hill 5 Expires September 2000
Internet Draft CAP March 10, 2000
Calendar Store (CS)
The data and service model definition for a Calendar Service.
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 [RFC2396].
Calendar Store Components
Components maintained in a CS specify a grouping of calendar store-
wide information. Calendar store components can be accessed using CAP.
Calendar Store Properties
Properties maintained in a Calendar Store calendar store-wide
information. Calendar store properties can be accessed using CAP.
Calendar User (CU)
An entity (often biological) that uses a calendaring system.
Calendar User Agent (CUA)
The CUA is the client application that a CU or UG utilizes to access
and manipulate a calendar.
Calendaring and Scheduling System
The computer sub-system that provides the services for accessing,
manipulating calendars and scheduling calendar components.
CAP Session
An open communication channel between a CAP CUA and a CAP CS.
Connected Mode
A mobile computing mode where the CUA is directly connected to the CS.
Delegate
Mansour/Dawson/Royer/Taler/Hill 6 Expires September 2000
Internet Draft CAP March 10, 2000
Is a calendar user (sometimes called the delegatee) who has been
assigned participation in a scheduled calendar component (e.g.,
VEVENT) by one of the attendees in the scheduled calendar component
(sometimes called the delegator). An example of a delegate is a team
member told to go to a particular meeting.
Designate
Is a calendar user who is authorized to act on behalf of another
calendar user. An example of a designate is an assistant.
Disconnected Mode
A mobile computing mode where a CUA can be disconnected from a CS.
When the CUA is disconnected, it is in the disconnected mode.
Fan Out
The calendaring and scheduling process by which a calendar operation
on one calendar is also performed on every other calendar specified in
the operation. This may include the calendar associated with TARGET
calendar property.
Hierarchical Calendars
A CS feature where a calendar have a hierarchical relationship with
another calendar in the CS. The top-most calendar in the hierarchical
relationship has the CS as its parent. There may be multiple top-most
calendars in a given CS. Within a given hierarchical relationship, all
sub-calendars have a calendar with a "parent" topographical
relationship. In addition, sub-calendars may have a relationship with
another calendar that has a "child" topographical relationship. In
addition, a calendar may have a relationship such that one or more
calendars have a "sibling" topographical relationship with the
calendar. The hierarchical calendar feature is not a storage
relationship of the calendars within the CS. Instead it is a feature
that relates access control rights to calendar content between
different calendars in the CS. The hierarchical relationship of a
calendar is specified in the "PARENT" and "CHILDREN" calendar
properties.
High Bandwidth Connection
A communications connection supporting high transfer rates; transfer
rates commonly found within a LAN.
Mansour/Dawson/Royer/Taler/Hill 7 Expires September 2000
Internet Draft CAP March 10, 2000
Local Store
A CS which is on the same platform as the CUA.
Low Bandwidth Connection
A communications connection supporting slow transfer rates; transfer
rates commonly found in remote access technology.
Overlapped Booking
A policy which indicates whether or not OPAQUE events can overlap one
another. When the policy is applied to a calendar it indicates whether
or not any OPAQUE events in the calendar can overlap. When applied to
an individual event, it indicates whether or not it can be overlapped
by any other OPAQUE event.
Owner
One or more CUs or UGs that have "OWNER" calendar access rights for a
calendar. The owner is specified in the "OWNER" calendar property.
Qualified Calendar Identifier (Qualified CalID)
A CalID where both the <scheme> and <csid> are present.
Realm
A collection of calendar user accounts, identified by a string. The
name of the realm is only used in UPNs. In order to avoid namespace
conflict, the realm SHOULD be postfixed with an appropriate DNS domain
name. (eg: the foobar realm could be called foobar.example.com).
Relative Calendar Identifier (Relative CalID)
An identifier for an individual calendar in a calendar store. It is
unique within a calendar store. It is recommended to be globally
unique. A Relative CalID 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 [RFC2396].
Remote Store
A CS which is not on the same platform as the CUA.
Mansour/Dawson/Royer/Taler/Hill 8 Expires September 2000
Internet Draft CAP March 10, 2000
Resource Calendar (RC)
A non-human Calendar, associated with an organizational resource.
There is no syntactic difference between an RC and a Calendar.
Session Identity
A UPN associated with a CAP session. A session gains an identity after
successful authentication. The identity is used in combination with
CAR to determine access to data in the CS.
Sub-calendars
Calendars that have a "child" hierarchical relationship with another
calendar, its "parent".
User Group (UG)
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.
User Name
A name which denotes a Calendar User within a realm. This is part of a
UPN.
User Principal Name (UPN)
An identifier that denotes a unique CU. A UPN is an 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 deliverable to a
different person. 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 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. For example, "@example.com". Usage of these special
cases is further discussed in the authentication and authorization
sections of this document.
Mansour/Dawson/Royer/Taler/Hill 9 Expires September 2000
Internet Draft CAP March 10, 2000
2. CAP Design
2.1. System Model
The system model describes the high level components of a calendar
system and how they interact with each other.
CAP is used by a "Calendar User Agent" (CUA) to send commands to and
receive responses from a "Calendar Service" (CS). The CUA prepares an
MIME encapsulated iCalendar object containing a command, sends it to the
CS, and receives an iCalendar object as a response. There are two
distinct protocols in operation to accomplish this exchange. The
Transfer Protocol is used to move iCalendar objects between a CUA and a
CS. The Application Protocol defines the content and semantics of the
iCalendar objects sent between the CUA and the CS. This document defines
both the Transfer Protocol and the Application Protocol.
In the diagram below, a user uses CUA1 to communicate with CS1 using
CAP. The CUA must authenticate the Calendar User (CU) so that access to
calendars on CS1 can be controlled. The CUA can then view, create, edit,
and delete calendars, calendar properties, and calendar components
subject to the access rights.
CAP servers support fanout. Fanout allows a CUA to communicate with a
single CS to perform scheduling operations with calendars on multiple
CSs. That is, a Calendar User (CU) can book events on or read events
from calendars on other calendar stores. To accomplish this, a CAP
server has several options:
CS1 MAY play the role of a CUA and use CAP to access CS2;
CS1 MAY be able to play the role of a CUA and use [iRIP] to
interoperate with the possible iRIP support in CS2;
CS1 MUST be able play the role of a CUA and use [RFC2447] to
interoperate with other CUAs.
Storage Agent
+-----+ +-----+
| | CAP | | CAP
CUA1 ------| CS1 |-----------| CS2 |--------- CUA2
| | | | A
| | | | |
| | | | |
+-----+ +-----+ |
| IMIP |
+---------------------------------+
Mansour/Dawson/Royer/Taler/Hill 10 Expires September 2000
Internet Draft CAP March 10, 2000
Note that the fanout feature in CAP is a convenience to the CUA. It
is perfectly valid for the CUA to assume the responsibility for
fanout if it wishes. That is, [RFC2447] messages could also be sent
from CUA1 to CUA2.
2.2. Calendar Store Object Model
The conceptual model for a calendar store is shown below. The calendar
store contains calendars, VTIMEZONEs, VCARs, and calendar store
properties.
Calendars contain VEVENTs, VTODOs, VJOURNALs, VALARMs, VCARs, and
calendar properties. Calendars may also contain other calendars.
+---------Calendar Store-----------------------------+
| |
| |
| VCARs |
| +--calendars-------------------------+ |
| Properties | | |
| | +--calendars--------+ VEVENTs | |
| VTIMEZONEs | | | VTODOs | |
| | | VEVENTs | VJOURNALs | |
| | | VCARs | VALARMs | |
| | | +---+ VTODOs | VCARs | |
| | | | | VALARMs | Calendar | |
| | | +---+ VJOURNALs | Properties | |
| | | VTIMEZONEs | VTIMEZONEs | |
| | | Calendar | VSCHEDULE | |
| | | Properties | | |
| | | VSCHEDULE | | |
| | +-------------------+ | |
| +------------------------------------+ |
+----------------------------------------------------+
Calendars within a Calendar Store are identified by their Relative
CALID.
In this model, VSCHEDULE is a queue of scheduling messages that have not
yet been applied to the calendar. Items in VSCHEDULE are discussed in
more detail below.
2.3. Protocol Model
A generic transfer-layer, Calendar Server Transfer Protocol (CSTP), is
used to move data objects between a CUA and the CS. CSTP commands are
listed below and their usage and semantics are defined in section 7 of
this document.
Mansour/Dawson/Royer/Taler/Hill 11 Expires September 2000
Internet Draft CAP March 10, 2000
CSTP Commands
-------------------------------------------------------------------------
Command Description
-------------------------------------------------------------------------
ABORT Stop a command whose latency time has been exceeded.
AUTHENTICATE Authenticate a UPN.
CONTINUE Continue the execution of a command whose latency
time has been exceeded.
IDENTIFY Set a new identity for calendar access.
DISCONNECT Terminate a connection with the server.
SENDDATA Send a data object MIME encapsulated iCalendar.
STARTTLS Negotiate transport level security using [TLS]
-------------------------------------------------------------------------
Application-level commands are used to manipulate data on the calendar
store. They are listed below and discussed in detail in section 7.
CAP Calendaring Commands
-------------------------------------------------------------------------
Command Description
-------------------------------------------------------------------------
CREATE Create a new calendar or component
DELETE Delete a calendar or component
GENERATEUID Generate one or more unique ids
MODIFY Change a calendar or component
MOVE Move a calendar
READ Read a calendar properties or components
-------------------------------------------------------------------------
CAP Scheduling Commands
-------------------------------------------------------------------------
Command Description
-------------------------------------------------------------------------
PUBLISH Publish a calendar entry to one
or more calendars.
Mansour/Dawson/Royer/Taler/Hill 12 Expires September 2000
Internet Draft CAP March 10, 2000
REQUEST Schedule a calendar entry with
one or more calendars.
REPLY Response to a scheduling request.
ADD Add one or more instances to an
existing calendar entry.
CANCEL Cancel one or more instances to
an existing calendar entry.
REFRESH A request for the latest version
of a calendar entry.
COUNTER A request for a change (a
counter-proposal) to a calendar
entry.
DECLINECOUNTER Decline a counter proposal.
-------------------------------------------------------------------------
2.4. Security Model
Authentication to the CS will be performed using SASL [RFC2222].
As noted in the CAP system model section, a variety of connectivity
scenarios are possible. This complicates the security model
considerably, and a thorough familiarity with the concepts is required
to ensure interoperability.
Basic threats to a Calendaring and Scheduling System include:
(1) Unauthorized access to data via data-fetching operations,
(2) Unauthorized access to reusable client authentication
information by monitoring others' access,
(3) Unauthorized access to data by monitoring others' access,
(4) Unauthorized modification of data,
(5) Unauthorized or excessive use of resources (denial of
service), and
(6) Spoofing of CS: Tricking a client into believing that
information came from the CS when in fact it did not, either by
modifying data in transit or misdirecting the client's
connection.
Threats (1), (4), (5) and (6) are due to hostile clients. Threats (2),
and (3) are due to hostile agents on the path between client and server,
or posing as a server.
CAP can be protected with the following security mechanisms:
Mansour/Dawson/Royer/Taler/Hill 13 Expires September 2000
Internet Draft CAP March 10, 2000
(1) Client authentication by means of the SASL [RFC2222] mechanism
set, possibly backed by the TLS credentials exchange mechanism,
(2) Client authorization by means of access control based on the
requestor's authenticated identity,
(3) Data integrity protection by means of the TLS protocol or
data-integrity SASL mechanisms,
(4) Protection against snooping by means of the TLS protocol or
data-encrypting SASL mechanisms,
(5) Resource limitation by means of administrative limits on service
controls, and
(6) Server authentication by means of the TLS protocol or SASL
mechanism.
Imposition of access controls (authorizations) is done by means of
VCARs, an overview is provided in section <fwd ref>, and a detailed
syntax is provided in section <fwd ref>. Authentication is explained in
detail in section <fwd ref>.
2.4.1. Authentication, Credentials, and Identity
Generically, authentication credentials are the evidence supplied by one
party to another, asserting the identity of the supplying party (e.g. a
user) who is attempting to establish an association with the other party
(typically a server). Authentication is the process of generating,
transmitting, and verifying these credentials and thus the identity they
assert. An authentication identity is the name presented in a
credential.
There are many forms of authentication credentials. The form used
depends upon the particular authentication mechanism negotiated by the
parties. For example: X.509 certificates, Kerberos tickets, simple
identity and password pairs. Note that an authentication mechanism may
constrain the form of authentication identities used with it.
SASL only provides a protocol to negotiate a mutually acceptable
authentication mechanism. SASL itself does not constrain or dictate the
form of the authentication identities used to perform the
authentication.
2.4.2. Calendar User and UPNs
A Calendar User(CU) is an entity that can be authenticated. It is
represented in CAP as a UPN. A UPN is the owner of a calendar and the
subject of access rights. The UPN representation is independent of the
authentication mechanism used during a particular CUA/CS interaction.
This is because UPNs are used within VCARs. If the UPN were dependant on
the authentication mechanism, a VCAR could not be consistently
evaluated. A CU may use one mechanism while using one CUA but the same
CU may use a different authentication mechanism when using a different
Mansour/Dawson/Royer/Taler/Hill 14 Expires September 2000
Internet Draft CAP March 10, 2000
CUA, or while connecting from a different location.
The user may also have multiple UPNs for various purposes.
Note that the immutability of the user's UPN may be achieved by using
SASL's authorization identity feature. (The transmitted authorization
identity may be different than the identity in the client's
authentication credentials.) [RFC2222, section 3] This also permits a CU
to authenticate using their own credentials, yet request the access
privileges of the identity for which they are proxying [RFC2222]. Also,
the form of authentication identity supplied by a service like TLS may
not correspond to the UPNs used to express a server's access control
policy, requiring a server-specific mapping to be done. The method by
which a server composes and validates an authorization identity from the
authentication credentials supplied by a client is implementation-
specific.
For Calendaring and Scheduling Systems that are integrated with a
directory system, the CS MUST support the ability to configure which
schema attribute stores the UPN. The CS MAY allow one or more attributes
to be searched for the UPN.
2.4.2.1. UPNs and Certificates
When using X.509 certificates for purposes of CAP authentication, the
UPN should appear in the certificate. Unfortunately there is no single
correct guideline for which field should contain the UPN.
From RFC-2459, section 4.1.2.6 (Subject):
If subject naming information is present only in the subjectAltName
extension (e.g., a key bound only to an email address or URI), then
the subject name MUST be an empty sequence and the subjectAltName
extension MUST be critical.
Implementations of this specification MAY use these comparison rules
to process unfamiliar attribute types (i.e., for name chaining).
This allows implementations to process certificates with unfamiliar
attributes in the subject name.
In addition, legacy implementations exist where an RFC 822 name is
embedded in the subject distinguished name as an EmailAddress
attribute. The attribute value for EmailAddress is of type
IA5String to permit inclusion of the character '@', which is not
part of the PrintableString character set. EmailAddress attribute
values are not case sensitive (e.g., "fanfeedback@redsox.com" is the
same as "FANFEEDBACK@REDSOX.COM").
Conforming implementations generating new certificates with
electronic mail addresses MUST use the rfc822Name in the subject
alternative name field (see sec. 4.2.1.7 [of RFC 2459]) to describe
Mansour/Dawson/Royer/Taler/Hill 15 Expires September 2000
Internet Draft CAP March 10, 2000
such identities. Simultaneous inclusion of the EmailAddress
attribute in the subject distinguished name to support legacy
implementations is deprecated but permitted.
Since no single method of including the UPN in the certificate will work
in all cases, CAP implementations MUST support the ability to configure
what the mapping will be by the CS administrator. Implementations MAY
support multiple mapping definitions, for example, the UPN may be found
in either the subject alternative name field, or the UPN may be embedded
in the subject distinguished name as an EmailAddress attribute.
Note: If a CS or CUA is validating data received via iMIP, if the
"ORGANIZER" or "ATTENDEE" property said (e.g.) "ATTENDEE;CN=Joe Random
User:juser@example.com" then the email address should be checked against
the UPN, and the CN should also be checked. This is so the "ATTENDEE"
property couldn't be munged to something misleading like
"ATTENDEE;CN=Joe Rictus User:juser@example.com" and have it pass
validation. This validation will also defeat other attempts at
confusion.
2.4.2.2. Anonymous Users and Authentication
Anonymous access is often desirable. For example an organization may
publish calendar information that does not require any access control
for viewing or login. Conversely, a user may wish to view unrestricted
calendar information without revealing their identity.
CAP implementations MUST support anonymous authentication, as defined in
section <fwd ref 7.1.3>.
CAP implementations MAY support anonymous authentication with TLS, as
defined in section <fwd ref 7.1.3.2>.
2.4.2.3. Required Security Mechanisms
The following implementation conformance requirements are in place:
(1) For a read-only, public CS, anonymous authentication,
described in section <fwd ref 7.1.3.1>, can be used.
(2) Implementations providing password-based authenticated access
MUST support authentication using Digest, as described in
section <fwd ref>. This provides client authentication with
protection against passive eavesdropping attacks, but does
not provide protection against active intermediary attacks.
(3) For a CS needing session protection and authentication, the Start
TLS extended operation, and either the simple authentication choice
or the SASL EXTERNAL mechanism, are to be used together.
Mansour/Dawson/Royer/Taler/Hill 16 Expires September 2000
Internet Draft CAP March 10, 2000
Implementations SHOULD support authentication with a password as
described in section <fwd ref>, and SHOULD support authentication
with a certificate as described in section <fwd ref>. Together,
these can provide integrity and disclosure protection of
transmitted data, and authentication of client and server,
including protection against active intermediary attacks.
2.4.2.4. TLS Ciphersuites
The following ciphersuites defined in [RFC 2246] MUST NOT be used for
confidentiality protection of passwords or data:
TLS_NULL_WITH_NULL_NULL TLS_RSA_WITH_NULL_MD5 TLS_RSA_WITH_NULL_SHA
The following ciphersuites defined in [RFC 2246] can be cracked easily
(less than a week of CPU time on a standard CPU in 1997). The client
and server SHOULD carefully consider the value of the password or data
being protected before using these ciphersuites:
TLS_RSA_EXPORT_WITH_RC4_40_MD5 TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5
TLS_RSA_EXPORT_WITH_DES40_CBC_SHA
TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA
TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA
TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
TLS_DH_anon_EXPORT_WITH_RC4_40_MD5
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA
The following ciphersuites are vulnerable to man-in-the-middle attacks,
and SHOULD NOT be used to protect passwords or sensitive data, unless
the network configuration is such that the danger of a man-in-the-middle
attack is tolerable:
TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 TLS_DH_anon_WITH_RC4_128_MD5
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA TLS_DH_anon_WITH_DES_CBC_SHA
TLS_DH_anon_WITH_3DES_EDE_CBC_SHA
A client or server that supports TLS MUST support at least
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA.
2.4.3. User Groups
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 UPN. The
CUA cannot distinguish between a UPN that represents a CU or a UG.
UGs are expanded as necessary by the CS. The CS MUST accept a CUA
request for UG expansion, although the CS may be configured to restrict
some responses. The CS MAY expand a UG (including nested UGs) to obtain
a list of unique CUs. Duplicate UPNs are filtered during expansion.
Mansour/Dawson/Royer/Taler/Hill 17 Expires September 2000
Internet Draft CAP March 10, 2000
Incomplete expansion should be treated as a failure.
[ Editor's Note: We need to explore the issue and impact of directory
permissions and precedence.]
The CS SHOULD not preserve UG expansions across operations. A UG may
reference a static list of members, or it may represent a dynamic list.
Each operation SHOULD generate its own expansion in order to recognize
changes to UG membership. However, during fan out to other CSs, the
originating CS SHOULD expand all UGs so that the target CS receives only
a list of unique CUs. This is to prevent confusion when two CSs do not
share the same UG database or directory.
[Editor's Note: Doug had an issue here relating to multiple CUs not
having a common directory. We think the above text resolves this]
CAP does not define commands or methods for managing UGs.
Examples:
Small UG - The Three Stooges. There is only and always three at any
one time.
Large UG - The MIT graduating class of 1999. This is a static list.
Dynamic UG - The IETF membership, which is a large and changing list
of members.
Nested UG - The National Football League, made up of the AFC and
NFC, which are made up of 3 divisions each...
2.4.4. Access Rights
In simple terms, access rights are used to grant or deny access to a
calendar for a CU. CAP defines a new component type called a VCalendar
Access Right (VCAR). Specifically, a VCAR grants, or denies, UPNs the
right to read and write components, properties, and parameters on
calendars within a CS.
The VCAR model does not put any restriction on the sequence in which the
object and access rights are created. That is, an event associated with
a particular VCAR might be created before or after the actual VCAR is
defined. In addition, the VCAR and VEVENT definition might be created in
the same iCalendar object and passed together in a single command.
All rights MUST be denied unless specifically granted; individual VCARs
MUST be specifically granted to an authenticated CU.
2.4.4.1. VCalendar Access Right (VCAR)
Access rights within CAP are specified with the "VCAR" calendar
component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID"
component properties.
Mansour/Dawson/Royer/Taler/Hill 18 Expires September 2000
Internet Draft CAP March 10, 2000
Properties within an iCalendar object are unordered. This also is the
case for the "GRANT", "DENY" and "CARID" properties. Likewise,
there is no implied ordering required for components of a "RIGHTS" value
type other than that specified by the ABNF. [ editor's note, this
requires a lot of review. We think that this paragraph may be incorrect.
]
For details on the VCAR syntax please see section <forward ref>
2.4.4.2. Decreed VCARs
[editor's note: new concept. This will also require some syntax
modification 14.4. This section is being actively discussed on the
working group list, 2/3/2000.]
A CS MAY choose to implement and allow persistent immutable VCARs, that
are configured by the CS Administrator, which apply to all calendars on
the server.
When a user attempts to modify a decreed VCAR and error will be
returned,indicating that the user has insufficient authorization to
perform the operation.
The CAP protocol does not define the semantics used to initially create
a decreed VCAR. This administrative task is out side the scope of the
CAP protocol.
2.4.4.3. Inheritance
Calendars inherit VCARs from their parent.
VCARs specified in a calendar or a sub-calendar override all inherited
VCARs.
2.4.5. CAP session identity
A CAP session has an associated set of authentication credentials, 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.
The CUA may change the identity of a CAP session by calling the
"IDENTIFY" command. The Calendar Service only permits the operation if
the session's authentication credentials are good for the requested
identity. The method of checking this permission is implementation
dependent, but may be thought of as a mapping from authentication
credentials to UPNs. The "IDENTIFY" command allows a single set of
authentication credentials to choose from multiple identities, and
allows multiple sets of authentication credentials to assume the same
identity.
Mansour/Dawson/Royer/Taler/Hill 19 Expires September 2000
Internet Draft CAP March 10, 2000
For anonymous access the identity of the session is "@", a UPN with a
null username and null realm. A UPN with a null username, but non-null
realm, such as "@foo.com" may be used to mean any identity from that
realm, which is useful to grant access rights to all users in a given
realm. A UPN with a non-null username and null realm, such as "bob@"
could be a security risk and must not be used.
Since the UPN includes realm information it may be used to govern
calendar store access rights across realms. However, governing access
rights across realms is only useful if login access is available. This
could be done through a trusted server relationship or a temporary
account.
The "IDENTIFY" command provides for a weak group implementation. By
allowing multiple sets of authentication credentials belonging to
different users to identify as the same UPN, that UPN essentially
identifies a group of people, and may be used for group calendar
ownership, or the granting of access rights to a group.
Examples:
Small UG - The Three Stooges. There will always be three, it will
not change.
Large UG - The MIT graduating class of 1999. This is a static list.
Dynamic UG - The IETF membership, which is a large and changing
list of members.
Nested UG - The National Football League, made up of the AFC and
NFC, which are made up of 3 divisions each...
2.5. Roles
CAP defines methods for managing [RFC2445] objects on 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 or UGs as attendees
takes on the role of "Organizer". The CUs or UGs asked to participate in
the group 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.
Mansour/Dawson/Royer/Taler/Hill 20 Expires September 2000
Internet Draft CAP March 10, 2000
2.6. Calendar Addresses
Calendar addresses are URIs that are modeled after [RFC2396]. CAP uses
the following forms of URI.
[[<scheme>]://<csid>[:<port>]/]<relativeCALID>
where:
<scheme> is "cap"
<csid> is the Calendar Store ID. It is the network address of the
computer on which the CAP server is running.
<port> is optional. Its default value is 5229. The port must be present
if the CAP server does not listen on the default port.
<relativeCALID> is an identifier that uniquely identifies the calendar
on a particular calendar store. There is no implied structure in a
Relative CALID. It is an arbitrary string of 7 bit ASCII characters. It
may refer to the calendar of a user or of a resource such as a
conference room. It MUST be unique within the calendar store. It is
recommended that the Relative CALID be globally unique.
If the <scheme> and <csid> are present the calendar address is said to
be "qualified". Senders are required to supply the <relativeCALID>
portion of the address. A qualified calendar address is required when
the <csid> of the target calendar address differs from that of the CAP
server receiving the command.
Examples:
cap://calendar.example.com/user1
://calendar.example.com/user1
user1
cap://calendar.example.com/conferenceRoomA
cap://calendar.example.com/89798-098-zytytasd
For a user currently authenticated to a CAP server on
calendar.example.com, the first three addresses refer to the same
calendar.
2.7. Extensions to iCalendar
In mapping the CAP command set, query feature, and access rights onto
the iCalendar format, several extended iCalendar methods and components
are defined by this memo.
* The search function is specified with the new iCalendar QUERY
method. The QUERY method makes use of a new component, called
VQUERY, that contains the search filter. The component consists of
Mansour/Dawson/Royer/Taler/Hill 21 Expires September 2000
Internet Draft CAP March 10, 2000
a set of new properties: SCOPE, MAXRESULTS, MAXRESULTSSIZE, QUERY
and QUERYNAME, that define the search filter.
* Access control is specified the the new iCalendar VCAR component.
* The iCalendar METHOD property format has been updated with new
values.
* A new iCalendar component, VCOMMAND, has been added. VCOMMANDs
are needed to fully specify CAP commands.
* TARGET is a new property within the VCOMMAND component. It
indicates the calendars to which the command applies
2.8. Relationship of RFC 2446 (ITIP) to CAP
[RFC2446] describes scheduling methods which result in indirect
manipulation of calendar components. CAP methods provide direct
manipulation of calendar components. In the CAP calendar store model,
scheduling messages are kept separate from other calendar components.
This is modeled with the VSCHEDULE queue. Note that this is a conceptual
model, the actual storage details are left to implementations. The model
is shown pictorially as follows:
+-----------------VCALENDAR-------------------+
| |
| +-----------+ +-------VSCHEDULE---------+ |
| | VEVENTs | | PUBLISH messages | |
| | VTODOs | | REQUEST messages | |
| | VJOURNALs | | REPLY messages | |
| | | | ADD messages | |
| | | | CANCEL messages | |
| | | | REFRESH messages | |
| | | | COUNTER messages | |
| | | | DECLINECOUNTER messages | |
| +-----------+ +-------------------------+ |
+---------------------------------------------+
The METHOD is saved along with components. Scheduled components become
booked components when the METHOD changes from an ITIP method to the CAP
storage method. For example, a component whose METHOD is "REQUEST" is
scheduled. The component becomes booked when the METHOD is changed to
"CREATED".
[ed note: need to clean up the terminology here. We havent discussed
"booked"]
Mansour/Dawson/Royer/Taler/Hill 22 Expires September 2000
Internet Draft CAP March 10, 2000
2.9. VCalendar Access Rights (VCARs)
In simple terms, VCARs are used to grant or deny access to a calendar
for a CU or UG. Specifically, they grant User Principal Names (UPNs) the
rights to read and write components, properties, and parameters on
calendars within a calendar store.
The model does not put any restriction on the sequence in which the
object and access rights are created. That is, an event associated with
a particular VCAR might be created before or after the actual VCAR is
defined. In addition, the VCAR and VEVENT definition might be created in
the same iCalendar object and passed together in a single SENDDATA
command.
VCAR principals can be CU or UG UPNs. Whenever VCARs are evaluated, all
referenced User Groups MUST be evaluated as an expanded list. UG
expansion SHOULD NOT persist across operations.
[Editor's Note: This is where we need to define precedence rules.]
2.10. Query Schema
<TBD> breif paragraph on summary of VQUERY.
3. State Diagram
This section describes the states of the transport connection between a
CUA and a CS. The state diagram is shown below. State names shown with
first letter capitalized. The commands used to switch between states are
shown next to an arrow connecting the states. The commands are listed in
all capital letters. A condition that causes a state to change is shown
in lower case letters.
Mansour/Dawson/Royer/Taler/Hill 23 Expires September 2000
Internet Draft CAP March 10, 2000
STARTTLS /
CAPABILITY
+-------+
| | +---------------+
| +-----------+ AUTHENTICATE | |
+-->| Connected |-------------->| Authenticated |
+-----------+ | |
| +---------------+
| |
| |
| |
| | +-----+ STARTTLS /
| V | | CAPABILITY /
| +---------------+ | IDENTIFY
| | |<-+
| | Identified |<----+
| +--------| | |
| | +---------------+ | command
| | | | completes
V |DISCONNECT | |
+--------------+ | |SENDDATA |
| Disconnected |<--+ | |
+--------------+ | | ABORT
A | |
| V |
| DISCONNECT +---------------+ |
+--------------------| Receive |--+
| |<--+
+---------------+ |
| | CONTINUTE
+----+
The connection begins the Connected state when a CUA connects to a CAP
server. The capabilities of the CS are reported in the response from the
CS. From this state, the CUA can issue the DISCONNECT command to
terminate the connection, the CAPABILITY, STARTTLS, or AUTHENTICATE
commands. One use of the CAPABILITY command at this stage is to
determine the supported authentication mechanisms supported by the
server. Once the STARTTLS command has been successfully executed from
either the Connected or Authenticated state, it must not be executed
again.
If an AUTHENTICATE command is successful, the connection enters the
Authenticated state and then immediately goes to the IDENTIFIED state.
While in the Identified state, allow CALIDEXPAND and UPNEXPAND commands.
From here the CUA can issue the CAPABILITY command. The capabilities the
server offers in the Authenticated state may be different than those in
the Connected state. The CUA can also use the IDENTIFY command to change
the identity of the user subject to access control. The connection
remains in the Authenticated state after the CAPABILITY command
Mansour/Dawson/Royer/Taler/Hill 24 Expires September 2000
Internet Draft CAP March 10, 2000
completes. The CUA can issue the DISCONNECT command to terminate the
connection. The SENDDATA command can be used to send a request to read,
write, modify, or delete data on the server.
After the SENDDATA command has been issued the connection enters the
Receive state while the CUA awaits and reads a server reply. Normally,
the server handles the command, sends a reply which is read by the CUA
and the connection returns to the Authenticated state. The CUA may have
issued the SENDATA command with a maximum latency time. This informs the
server that the CUA expects a response within the maximum latency time,
even if the command was not completed. When the server is unable to
complete the command in the maximum latency time, it issues an
appropriate reply code and waits for the CUA to tell it how to proceed.
If the CUA issues a CONTINUE command the server continues processing the
command and the connection remains in the Receive state. If the CUA
issues the ABORT command the server need not process the command any
further and the connection returns to the Authenticated state. The
DISCONNECT command can also be issued from the Receive state.
4. Protocol Framework
4.1. CAP Application Layer
The CAP application layer is used for the manipulation of the calendar
store. Commands and responses are transmitted between the CUA and CS
inside "VCALENDAR" component wrappers. Commands are specified as the
value of a "METHOD" property, and responses are specified as the value
of a "REQUEST-STATUS" property.
4.2. CAP Transfer Protocol
The CAP transfer protocol defines the format of data transmitted between
a CUA and the CS.
CAP transfer protocol commands are transmitted using the underlying
transport. The transport used is a TCP/IP socket connection between the
CUA and the CS. The default port that the CS listens for connections on
is port 5229.
Messages sent between the CUA and CS are formatted as a command followed
by any associated data:
<command> [<command data>]
4.3. Response Format
Server responses consist of a response code and any parameters:
<transfer-level response-code> [response args] [; debug text ; more
Mansour/Dawson/Royer/Taler/Hill 25 Expires September 2000
Internet Draft CAP March 10, 2000
text] <CRLF>.<CRLF> [<application-data>] <CRLF>.<CRLF>
The response codes are defined in Section 8. The debug text is human-
readable information for protocol debugging and is optional.
The optional application-data begins on the next line.
The response is terminated with the second <CRLF> "." <CRLF> sequence.
Any <CRLF> "." sequences which appear in the transmitted data must be
quoted by placing an additional "." between the <CRLF> and the ".". For
example, the following sequences of characters in the application data:
.
..2
...3
are quoted as follows:
..
...2
....3
No other tagged command sequence can be sent until the second special
terminating character sequence <CRLF>.<CRLF> has been sent.
4.4. Auto-logout Timer
If a server has an inactivity auto-logout timer, that timer MUST be of
at least 15 minutes duration. The receipt of ANY command from the client
during that interval MAY reset the auto-logout timer, subject to CS
administrators policy. A CUA may be discouraged from attempts to do
usless things only to keep the connection alive.
When a timeout occurs, the server drops the connection to the CUA.
4.5. Bounded Latency
[CAP] is designed so that the CUA can either obtain an immediate
response from a request or discover within a specified amount of time
that the request could not be completed in the requested amount of time.
When the CUA initiates a command that the server cannot complete within
the specified latency time, the server returns an appropriate response
code. The CUA then issues either a CONTINUE or ABORT command. The ABORT
command immediately terminates the command in progress and the
connection returns to the Authenticated state. The CONTINUE command
instructs the server to continue processing the command.
Mansour/Dawson/Royer/Taler/Hill 26 Expires September 2000
Internet Draft CAP March 10, 2000
4.6. Data Elements
The data elements for CAP are MIME encapsulated iCalendar objects.
5. Formal Command Syntax
5.1. Searching and Filtering
This section describes CAPs searching and filtering entities within a
remote store. It is based on the Standard Query Language (SQL) defined
by [SQL].
The QUERY property value MUST be a valid QUERY value type. This new
value type is defined to be a "name=value" value type grammar, similar
in syntax to the format already in use for the iCalendar RECUR value
type. Each "name" is the name of a valid SQL statement component (e.g.,
SELECT, WHERE, etc.). Each "value" is valid string associated with one
of these SQL statement components.
[Editor's note: We need to precisely define what part of SQL were using
and why we chose what we did.]
Examples needed:
Grant someone access to June events
Grant someone access to events during the month of June. (i.e., based
on the current system date, if it's prior to June or after June you
don't have access)
Example for denying access to a specific property:
DENY:UPN=FOO;ACTION=*;OBJECT=CLASS
*scope vcar to a component *scope Grant, Deny of a VCAR
5.1.1. Grammar For Search Mechanism
SEARCH = "BEGIN:VQUERY" CRLF
[scope] [maxresults] [maxsize] querycomp
"END:VQUERY" CRLF
scope = "SCOPE:" comp-name ("," comp-name)*
comp-name = "VEVENT" / "VTODO" / "VJOURNAL" / "VTIMEZONE"
/ "VALARM" / "VFREEBUSY" / "VCAR" / iana-name / x-name
maxresults = integer
maxsize = integer
Mansour/Dawson/Royer/Taler/Hill 27 Expires September 2000
Internet Draft CAP March 10, 2000
querycomp = (query) / (queryname query) / queryname
queryname = "QUERYNAME:" text
query = "QUERY:" queryrule
queryrule = capselect capwhere caporderby ...
capselect = <any valid SQL string that goes into a SELECT clause>
capwhere = <any valid SQL string that goes into a WHERE clause>
caporderby = <any valid SQL string that goes into a ORDERBY
clause>
6. Access Rights
Access rights within CAP are specified with the "VCAR" calendar
component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID"
component properties.
Individual calendar access rights MUST be specifically granted to an
authenticated calendar user (i.e., UPN); all rights are denied unless
specifically granted.
Properties within a VCAR must be evaluated in the order provided.
6.1. VCAR Inheritance
Calendar access rights specified in a calendar store are inherited as
default calendar access rights for any calendar in the parent calendar
store. Likewise, any calendar access rights specified in a root calendar
are inherited as default calendar access rights for any sub- calendar to
the root calendar. By implication, calendar access rights specified in a
sub-calendar are inherited as default calendar access rights for any
calendars that are hierarchically below the sub- calendar.
Calendar access rights specified in a calendar override any default
calendar access rights. Calendar access rights specified within a sub-
calendar override any default calendar access rights.
6.2. Access Control and NOCONFLICT
The TRANSP property can take on values (TRANSPARENT-NOCONFLICT, OPAQUE-
NOCONFLICT) that prohibit other events from overlapping it. This setting
overrides access While access control may allow a UPN to store an event
on a particular calendar. , the CONFLICTS Calendar or component setting
may prevent it, returning an error code "6.3"
Mansour/Dawson/Royer/Taler/Hill 28 Expires September 2000
Internet Draft CAP March 10, 2000
7. Commands and Responses
CAP commands and responses are described in this section.
Command arguments, identified by "Arguments:" in the command
descriptions below, are described by function, not by syntax. The
precise syntax of command arguments is described in the Formal Syntax
section.
Some commands cause specific server data to be returned; these are
identified by "Data:" in the command descriptions below. See the
response descriptions in the Responses section for information on these
responses, and the Formal Syntax section for the precise syntax of these
responses.
The "Result:" in the command description refers to the possible status
responses to a command, and any special interpretation of these status
responses.
Commands have the general form:
<command> [arguments...]
where <command> is a command listed in the table above. A command MAY
have arguments. Arguments are defined in the detailed command
definitions below.
Responses to commands have the following general form:
responseCode [sep transportDescr sep [applicationDescr]]
CRLF "." CRLF
In the examples below, lines preceded with "S:" refer to the sender and
lines preceded with "R:" refer to the receiver. Lines in which the first
non-whitespace character is a "#" are editorial comments and are not
part of the protocol.
7.1. Transfer Protocol Commands
7.1.1. Initial Connection
Arguments: none
Data: none
Result: 2.0 - success.
8.1 - server too busy
Upon session startup, the server sends a response of 2.0 to indicate
that it is ready to receive commands. A response of 8.1 indicates that
the server is too busy to accept the connection. In addition, the
Mansour/Dawson/Royer/Taler/Hill 29 Expires September 2000
Internet Draft CAP March 10, 2000
general capabilities of the CS are reported in the response from the CS.
These capabilities may be different than those reported in the
authenticated state.
The supported authentication mechanisms. There may be 1 or more.
CAPVERSION
IRIPVERSION
7.1.2. ABORT Command
Arguments: none
Data: none
Result: 2.0 - success
2.2 - no command is in progress
The ABORT command is issued by the CUA to stop a command whose latency
time has been exceeded. When the latency time is specified on the
SENDATA command, the CS must issue a reply to the CUA within the
specified time. It may be a reply code indicating that the CS has not
yet processed the request. The CUA must then tell the server whether to
continue or abort.
The CUA can issue the ABORT command at any time after the SENDATA
command has been completed but before receiving a reply.
7.1.3. AUTHENTICATE Command
Arguments: <SASL mechanism name> [<initial data>]
Data: continuation data may be requested
Result:
2.0 - Authenticate completed, now in authenticated
state.
6.0 - Failed authentication.
6.1 - Authorization identity refused.
6.2 - Sender aborted authentication, authentication
exchange cancelled.
6.3 - Unsupported Authentication Mechanism.
6.x - Temporary failure (back end authentication
server down).
6.x - Authentication exchange cancelled.
6.x - Authentication mechanism too weak.
Mansour/Dawson/Royer/Taler/Hill 30 Expires September 2000
Internet Draft CAP March 10, 2000
6.x - Encryption required.
6.x - Pass phrase expired. The pass phrase was
correct but expired. The user will have to
contact a pass phrase change server prior to
authenticating.
6.x - The user is valid but the server does not
have an entry in the authentication database
for the requested mechanism (e.g., DIGEST-
MD5). If the user successfully authenticates
using a plain text password, then the back
end back end entry will be updated. Note
that if the client chooses to fall back to
plain text password authentication it should
enable an encryption layer or get user-con-
firmation that a one-time transition is ac-
ceptable.
6.x - User account disabled. The user will have to
contact the system administrator to get the
account re-enabled.
9.1 - Unexpected command.
The capabilities of the CS in the authenticated state are reported in
the response from the CS. These may be different than the capabilities
in the Connected, but unauthenticated state.
The AUTHENTICATE command is used by the CUA to identify the user to the
CS. CAP supports a number of authentication methods, the [SASL]
specification for authentication is the preferred method.
If STARTTLS is negotiated prior to the AUTHENTICATE command, the client
MUST discard all information about the CS capabilities fetched prior to
the TLS negotiation. In particular, the value of supported SASL
Mechanisms MAY be different after TLS has been negotiated.
If a SASL security layer is negotiated, the client MUST discard all
information about the CS capabilities fetched prior to SASL. In
particular, if the client is configured to support multiple SASL
mechanisms, it SHOULD fetch supported SASL Mechanisms both before and
after the SASL security layer is negotiated and verify that the value
has not changed after the SASL security layer was negotiated. This
detects active attacks which remove supported SASL mechanisms from the
supported SASL Mechanisms list.
<initial data> is an optional parameter which can be used for mechanisms
which require an initial response from the CUA.
The AUTHENTICATE command is followed by an authentication protocol
exchange, in the form of a series of CS challenges and CUA responses,
per the relevant RFC that describes the specific SASL mechanism being
used.
Mansour/Dawson/Royer/Taler/Hill 31 Expires September 2000
Internet Draft CAP March 10, 2000
Cancelling the authentication process during its negotiation is
implementation specific and not within scope of the CAP specification.
If a security layer was negotiated it comes into effect for the CS
starting with the first octet transmitted after the CRLF which follows
the 2.0 reply code, and for the CUA starting with the first octet after
the CRLF of its last response in the authentication exchange. Encrypted
data is transmitted as described in [SASL].
The service name specified by this protocol's profile of SASL is "cap".
[Note: this must be registered with IANA, has anyone done this yet?]
The result of the AUTHENTICATE command includes data indicating the
identity which has been assigned to the session, derived from the
supplied authentication credentials, and/or authorization identifier. A
CAP session does not have an identity until the CUA has issued the
"AUTHENTICATE" command.
The CUA may not issue the "AUTHENTICATE" command multiple times, even if
the first attempt was aborted. If a CUA attempts to do this the CS must
terminate the session.
Data returned in response to a successful login is:
The following examples illustrate the various possibilities for an
authentication protocol exchange.
Here are examples of a successful authentication:
C: AUTHENTICATE KERBEROS_V4
S: AmFYig==
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
S: or//EoAADZI=
C: DiAF5A4gA+oOIALuBkAAmw==
S: 2.0
S: .
S: Content-Type:text/calendar; method=REQUEST; charset=US-ASCII
S: Content-Transfer-Encoding: 7bit
S:
S: BEGIN:VCALENDAR
S: PRODID:-//ACME/CAPserver//EN
S: VERSION:2.1
S: IDENTITY=bill@example.com
S: CAPVERSION=1.0
S: ITIPVERSION=1.0
S: AUTH=KERBEROS_V4
S: AUTH=DIGEST_MD5
S: CAR=CAR-FULL-1
S: MINDATE=19700101T000000Z
S: MAXDATE=20370201T000000Z
S: END:VCALENDAR
S: .
Mansour/Dawson/Royer/Taler/Hill 32 Expires September 2000
Internet Draft CAP March 10, 2000
This example shows a failed authentication:
C: AUTHENTICATE KERBEROS_V4
S: AmFYig==
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
S: .
S: 6.0
S: .
S: .
7.1.3.1. AUTHENTICATE ANONYMOUS
RFC-2245 defines the Anonymous SASL mechanism. This RFC states that "the
mechanism consists of a single message from the client to the server.
The client sends optional trace information in the form of a human
readable string. The trace information should take one of three forms:
an Internet email address, an opaque string which does not contain the
'@' character and can be interpreted by the system administrator of the
client's domain, or nothing. For privacy reasons, an Internet email
address should only be used with permission from the user."
RFC-2245 goes on to state, "A client which uses the user's correct email
address as trace information without explicit permission may violate
that user's privacy." Information about who accesses an anonymous CS on
a sensitive subject (e.g., AA meeting times and locations) has strong
privacy needs. "Clients should not send the email address without
explicit permission of the user and should offer the option of supplying
no trace token -- thus only exposing the source IP address and time."
Example of CUA using the Capability command followed by an anonymous
authentication:
C: CAPABILITY
S: 2.0
S:CAPVERSION=1.0
S:AUTH=KERBEROS_V4
S:AUTH=DIGEST_MD5
S:AUTH=ANONYMOUS
S:.
C:AUTHENTICATE ANONYMOUS
S:+
C:c21yaGM=
S:2.0
Subsequent to the initial Anonymous Authentication with a CS, a CUA will
have to provide a UPN for some CAP operations. For anonymous access the
UPN that MUST be used by the CUA is "@", a UPN with a null username and
null realm. The user's normal UPN MUST not be used for the subsequent
CAP operations.
Mansour/Dawson/Royer/Taler/Hill 33 Expires September 2000
Internet Draft CAP March 10, 2000
Note that the CS implementation may have internal audit logs that use
the user's asserted UPN as trace information. However, this UPN will not
appear on the wire after the initial SASL anonymous authentication.
Use of the "@" UPN and wild-carding of UPNs within VCARs are covered in
Section <forward ref>.
7.1.4. CALIDEXPAND Command
Arguments: CalID
Data: no specific data for this command
Result: 2.0 Successful, and requested data follows
2.1 Permission Denied
2.2 Requested CSID not found
2.3 Result exceeds MAXEXPANDLIST
2.4 Misc. EXPAND error
Return the members of the argument CalID. Successful result yields one
or more Calendars and/or Resource Calendars. More than one C or RC
returned implies that the CalID was a CC.
Example:
Example #1: Request lookup of CSID which is a Calendar Collection
C: CALIDEXPAND cap://cal.example.com/calid14
S: 2.0 cap://cal.example.com/calid14
S: cap://cal.example.com/calid2
S: cap://cal.example.com/calid5
S: cap://cal.example.com/calid66
S: .
Example #2: Request lookup of a CSID which is a Resource Calendar
C: CALIDEXPAND cap://cal.example.com/conf5
S: 2.0 cap://cal.example.com/conf5
S: cap://cal.example.com/conf5
S: .
Example #3: Request CSID which exceeds MAXCALIDEXPANDLIST
C: CALIDEXPAND cap://cal.example.com/calid76
S: 2.0 cap://cal.example.com/calid76
S: cap://cal.example.com/calid3
S: cap://cal.example.com/calid12
S: cap://cal.example.com/calid21
S: cap://cal.example.com/calid33
S: 2.3 Expansion resulted in too much data
S: .
Mansour/Dawson/Royer/Taler/Hill 34 Expires September 2000
Internet Draft CAP March 10, 2000
Example #4: CS loses contact with directory server during CALIDEXPAND
C: CALIDEXPAND cap://cal.example.com/calid76
S: 2.0 cap://cal.example.com/calid76
S: cap://cal.example.com/calid3
S: cap://cal.example.com/calid5
S: 2.4 Lost contact with directory server
S: .
7.1.5. CAPABILITY Command
Arguments: none
Data: none
Result: capabilities as described below
The CAPABILTY command returns information about the CAP server given the
current state of the connection with the client. The values returned may
differ depending on whether the connection is in the Connected or the
Authenticated state. The return values may also be different for a
secure versus a non-secure connection.
Client implementations SHOULD NOT require any capability name beyond
those defined in this specification, and MAY ignore any non-standard,
experimental capability names. Non-standard capability names are
prefixed with the text "X-". The prefix SHOULD also include a short
character vendor identifier For example, "X-FOO-BARCAPABILITY", for the
non-standard "BARCAPABILITY" capability of the implementor "FOO". This
command may return different results in the Connected state versus the
Authenticated state. It may also return different results depending on
the UPN.
Capability Occurs Description
-----------------------------------------------------------------------
CAPrev1 1 Revision of CAP, must be "CAPrev1"
IRIPrev1 0 or 1 Revision of IRIP, MAY be present. If
present, it MUST be "IRIPrev1"
CAR 0 or 1 Indicates level of CAR support CAR-MIN
or CAR-FULL-1
Mansour/Dawson/Royer/Taler/Hill 35 Expires September 2000
Internet Draft CAP March 10, 2000
MAXICALOBJECTSIZE 0 or 1 An integer value that specifies The
largest ICAL object the server will ac-
cept in bytes. Objects larger than this
will be rejected. A value of zero (0)
indicates unlimited.
MAXDATE 0 or 1 The datetime value beyond which the
server cannot accept.
MAXCALIDEXPANDLIST 0 or 1 An integer value that specifies the max-
imum number of CalIDs that can be re-
turned by the CALIDEXPAND Command. A
value of zero (0) indicates unlimited.
MAXUPNEXPANDLIST 0 or 1 An integer value that specifies the max-
imum number of UPNs that can be returned
by the UPNEXPAND Command. A value of
zero (0) indicates unlimited.
MINDATE 0 or 1 The datetime value prior to which the
server cannot accept.
Example:
C: CAPABILTIY
S: 2.0
S: .
S: CAPVERSION=1.0
S: ITIPVERSION=1.0
S: AUTH=KERBEROS_V4
S: AUTH=DIGEST_MD5
S: .
7.1.6. CONTINUE Command
Arguments: latency time in seconds (optional)
Data: none
Result: results from the command in progress
2.0.2 - reply pending.
The CONTINUE command is issued by the client in response to a SENDATA
timeout. When a timeout value is specified on the SENDDATA command, the
server must issue a reply to the client within the specified time. If
the latency time has elapsed prior to the server completing the command
it returns a timeout response code. If the client wants the server to
continue processing the command it responds with the CONTINUE command.
If latencyTime is present, it must be a positive integer that specifies
Mansour/Dawson/Royer/Taler/Hill 36 Expires September 2000
Internet Draft CAP March 10, 2000
the maximum number of seconds the client will wait for the next
response. If it is omitted, the receiver waits an indefinite period of
time for the response.
In this example, the client requests a response from the server every 10
seconds.
C: SENDDATA:10
C: Content-Type:text/calendar; method=READ; component=VEVENT
C:
C: BEGIN:VCALENDAR
# etc
C: END:VCALENDAR
C: .
# after 10 seconds...
S: .
S: 2.0.2
S: .
S: .
C: CONTINUE:10
S: 2.0
S: .
S: Content-type:text/calendar; Method=RESPONSE;Component=VDATA;
S: Optinfo=VERSION:2.1
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: CALID:cap://cal.example.com/relcal2
# etc.
S: END:VCALENDAR
S: .
7.1.7. DISCONNECT Command
Arguments: none
Data:
Result: 2.0
The DISCONNECT command is used by a client to terminate a connection.
It always succeeds.
Example:
C: DISCONNECT
# [ed. Note: should the client now wait for a response from the
server
# before disconnecting? ]
S: 2.0
S: .
S: .
Mansour/Dawson/Royer/Taler/Hill 37 Expires September 2000
Internet Draft CAP March 10, 2000
C: <drops connection>
S: <drops connection>
7.1.8. IDENTIFY Command
Arguments: Identity to assume
Data: None
Result: 2.0
6.4 Identity not permitted
The "IDENTIFY" command allows the CUA to select a new identity to be
used for calendar access. This command may only be called in the
Identified State.
The CS determines through an internal mechanism if the credentials
supplied at authentication permit the assumption of the selected the
identity. If they do the session assumes the new identity, otherwise a
security error is returned.
7.1.9. SENDDATA Command
Arguments: [latencyTime]
Data: a MIME encapsulated iCalendar object
Result: 2.0.1 - Server will now accept input until <CRLF>.<CRLF>
is encountered.
The SENDDATA command is used to send calendar requests and commands to
the server. After a response code of 2.0.1 is issued the CUA sends a
MIME encapsulated iCalendar object to the server. The end of this MIME
data is signaled by the special sequence <CRLF>.<CRLF> .
7.1.10. STARTTLS Command
Arguments: None
Data: None
Result: 2.0
6.5 TLS not supported
The "STARTTLS" command is issued by the CUA to indicate to the CS that
it wishes to negotiate transport level security using [TLS]. If the CS
does not support TLS it returns status code 6.5. If the CS supports TLS
it issues an initial response of 2.0.12 indicating that the CUA should
Mansour/Dawson/Royer/Taler/Hill 38 Expires September 2000
Internet Draft CAP March 10, 2000
proceed with TLS negotiation. Once the TLS negotiation is complete the
server returns the response code 2.0.
After issuing the "STARTTLS" command the CUA issues the "AUTHENTICATE"
command. The SASL external mechanism may be used if the CUA wishes to
use the authentication id which was used in the TLS negotiation.
The CUA MUST NOT issue a "STARTTLS" if it has already issued an
"AUTHENTICATE" or "STARTTLS" command in this session. If a CUA does
this the CS must terminate the session.
The following examples illustrate the use of the "STARTTLS" command:
Unsupported TLS:
C: STARTTLS
S: 6.5
Supported TLS:
C: STARTTLS
S: 2.0.12
<tls negotiation>
S: 2.0
S: .
S: .
7.1.10.1. UPNEXPAND Method
Arguments: UPN
Data: no specific data for this command
Result: 2.0 - success
2.1 Permission Denied
2.2 Requested UPN not found
2.3 Result exceeds MAXUPNEXPANDLIST
2.4 Misc. UPNEXPAND error
Return the members of the argument UPN. Successful result yields one or
more CalIDs. More than one CalID returned implies that the UPN was a
UG.
Example #1: Request lookup of a UPN which is a CU
C: UPNEXPAND upn@example.com
S: 2.0 upn@example.com
S: cap://cal.example.com/calid3
S: .
Example #2: Request lookup of UPN which is a UG
Mansour/Dawson/Royer/Taler/Hill 39 Expires September 2000
Internet Draft CAP March 10, 2000
C: UPNEXPAND group@example.com
S: 2.0 group@example.com
S: cap://cal.example.com/calid3
S: cap://cal.example.com/calid6
S: cap://cal.example.com/calid1342
S: .
Example #3: Request lookup exceeds MAXUPNEXPANDLIST
C: UPNEXPAND group@example.com
S: 2.0 group@example.com
S: cap://cal.example.com/calid3
S: cap://cal.example.com/calid12
S: cap://cal.example.com/calid21
S: cap://cal.example.com/calid33
S: 2.3 Lookup resulted in too much data
S: .
Example #4: CS loses contact with directory server during UPNEXPAND
C: UPNEXPAND group@example.com
S: 2.0 group@example.com
S: cap://cal.example.com/calid3
S: cap://cal.example.com/calid5
S: 2.4 Lost contact with directory server
S: .
7.2. Application Protocol Commands
7.2.1. Calendaring Commands
The following methods provide a set of calendaring commands in CAP.
Calendaring commands (or methods) allow a CU to directly manipulate a
calendar.
Calendar access rights can be granted for the more generalized access
provided by the calendar commands.
7.2.1.1. CREATE Method
Arguments: none
Data: no specific data for this command
Result: 2.0 - successfully created the component or calendar
6.0 - Permission denied
6.1 - Container(s) not found
6.2 - Calendar or component already exists
6.3 -
Bad args
Mansour/Dawson/Royer/Taler/Hill 40 Expires September 2000
Internet Draft CAP March 10, 2000
The CREATE method is used to create a new iCalendar object of type
objtype. The property TARGET specifies the container(s) for the create.
The type of object wrapped inside of the VCALENDAR/CREATE object is the
object type(s) being created. When creating a new calendar at the top
level, the CSID is specified. Otherwise the container will be a CalID.
7.2.1.1.1. Creating New Calendars
Example to create a new calendar named "Bill's Soccer Team" in several
different containers. In the following example, the client is in the
Authenticated state with CS cal.example.com.
C: SENDDATA
C: CONTENT-TYPE: text/calendar;method=CREATE;component=VCOMMAND
C: Content-Transfer-Encoding:7bit
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1
C: BEGIN:VCOMMAND
C: METHOD:CREATE
C: TARGET:cap://cal.example.com/
C: TARGET:relcal4
C: TARGET://bobo.ex.com/
C: TARGET:relcal5
C: TARGET:cap://cal.example.com/relcal8
C: TARGET:relcal9
C: BEGIN:VCALENDAR
C: RELCALID:relcalz
C: NAME:CHARSET=us-ascii;LANGUAGE=EN-us:Bill's Soccer Team
C: OWNER:bill
C: OWNER:mary
C: CALMASTER:mailto:bill@example.com
C: TZID:US_PST
C: BEGIN:VCAR
C: CARID:12345
C: GRANT:UPN=bill;ACTION=*;OBJECT=*
C: GRANT:UPN=mary;ACTION=read;OBJECT=*
C: END:VCAR
C: END:VCALENDAR
C: END:VCOMMAND
C: END:VCALENDAR
C: .
S: 6.0 cap://cal.example.com/
S: 2.0 cap://cal.example.com/relcal4 cap://cal.example.com/relcalz
S: 3.1.4 cap://bobo.ex.com/
S: 6.2 cap://cal.example.com/relcal5
S: 3.1.5 cap://cal.example.com/relcal8
S: 7.0 cap://cal.example.com/relcal9
If the example above, the Relative CALID is specified. The values for
this property must be unique on a CS. That is the reason for the 3.1.5
error response.
Mansour/Dawson/Royer/Taler/Hill 41 Expires September 2000
Internet Draft CAP March 10, 2000
In the example below, the Relative CalID is not specified. So, the CAP
server will generate one for each calendar successfully created. The
value of the Relative CalID appears as the second parameter on the
response code.
S: 6.0 cap://cal.example.com/
S: 2.0 cap://cal.example.com/relcal4 cap://cal.example.com/rand123
S: 3.1.4 cap://bobo.ex.com/
S: 6.2 cap://cal.example.com/relcal5
S: 3.1.4 cap://cal.example.com/relcal8
S: 2.0 cap://cal.example.com/relcal9 cap://cal.example.com/rand456
Example to create a new component.
C: SENDDATA
C: Content-Type:text/calendar; method=CREATE; charset=US-ASCII
C: Content-Transfer-Encoding:7bit
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1
C: CMDID:abcde
C: METHOD:CREATE
C: TARGET:cap://cal.foo.com/relcal1
C: TARGET:relcal2
C: BEGIN:VEVENT
C: DTSTART:19990307T180000Z
C: UID:abcd12345
C: DTEND:19990307T190000Z
C: SUMMARY:Important Meeting
C: END:VEVENT
C: END:VCALENDAR
C: .
S: 2.0
S: Content-Type:text/calendar; method=RESPONSE; OPTINFO="CMDID:abcde"
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: CMDID:abcde
S: METHOD:RESPONSE
S: BEGIN:VEVENT
S: REQUEST-STATUS:2.0;cap://cal.foo.com/relcal1 abcd12345
S: REQUEST-STATUS:2.0;cap://cal.foo.com/relcal2 abcd12345
S: END:VEVENT
S: END:VCALENDAR
The responce returns the calendar (CALID) and UID of the component so
that the CUA can match up the REQUEST-STATUS from multiple objects
created on multiple calendards (TARGETs).
Mansour/Dawson/Royer/Taler/Hill 42 Expires September 2000
Internet Draft CAP March 10, 2000
7.2.1.2. DELETE Method
Arguments: none
Data: no specific data for this command
Result: 2.0 - successfully deleted the component or calendar
Permission
Calendar or component not found
Bad args
Container(s) not found
The DELETE method is used to delete a calendar or component. The TARGET
properties specify the container(s) for the delete. When deleting a
calendar at the top level, the CSID is specified. Otherwise the
container will be a CalID.
Example to delete a VEVENT with UID 'abcd12345':
C: SENDDATA
C: Content-Type:text/calendar; method=DELETE; component=VCOMMAND
C: Content-Transfer-Encoding:7bit
C:
C: BEGIN:VCALENDAR
C: BEGIN:VCOMMAND
C: METHOD:DELETE
C: TARGET:cap://cal.foo.com/bill
C: BEGIN:VQUERY
C: SCOPE:VEVENT
C: QUERY SELECT="UID"
C: WHERE (UID EQ abcd12345)
C: END:VQUERY
C: END:VCOMMAND
C: END:VCALENDAR
C: .
S: 2.0
S: .
And an example to delete the 'MrBill' calendar:
C: SENDDATA
C: Content-Type:text/calendar; method=DELETE; component=VCOMMAND
C: Content-Transfer-Encoding:7bit
C:
C: BEGIN:VCALENDAR
C: BEGIN:VCOMMAND
C: METHOD:DELETE
C: TARGET:cap://cal.foo.com/MrBill
C: END:VCOMMAND
C: END:VCALENDAR
C: .
S: 2.0
S: .
Mansour/Dawson/Royer/Taler/Hill 43 Expires September 2000
Internet Draft CAP March 10, 2000
C: SENDDATA C:
7.2.1.3. GENERATEUID Method
Arguments: Number of UIDs to generate.
Data: new uids
Result: 2.0
GENERATEUID returns one or more new unique identifier which MUST be
unique on the server's calendar store. It is recommended that the return
value be a globally unique id.
Example:
C: GENERATEUID 2
S: 2.0 abcde1234567-asdf-lkhh abcde1234567-asdf-3455
[Editors note: this example needs work. It's not packaged right]
7.2.1.4. MODIFY Method
Arguments: none
Data: no specific data for this command
Result: 2.0 - successfully modified the component or calendar
Permission
Calendar or component not found
Bad args
Container(s) not found
The MODIFY method is used to change an existing calendar or component.
TARGET specify the container(s) of the modification. When modifying a
calendar at the top level, the CSID is specified. Otherwise the
container will be a CalID.
The format of the request is two or three containers inside of a
VCOMMAND container:
BEGIN:VCOMMAND
[VQUERY]
OLD-VALUES
NEW-VALUES
END:VCOMMAND
If a VQUERY is present, then only objects matching the query results are
modified.
In the example below, the start and end time of the event with UID
abcd12345 is changed and the LOCATION property is removed.
Mansour/Dawson/Royer/Taler/Hill 44 Expires September 2000
Internet Draft CAP March 10, 2000
C: SENDDATA
C: Content-type:text/calendar; Method=MODIFY; Component=VCOMMAND
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1
C: METHOD:MODIFY
C: TARGET:relcal2
C: BEGIN:VCOMMAND
C: BEGIN:VQUERY
C: SCOPE:VEVENT
C: QUERY:SELECT UID WHERE (UID EQ abcd12345)
C: END:VQUERY
C: BEGIN:VEVENT
C: DTSTART:19990421T160000Z
C: DTEND:19990421T163000Z
C: LOCATION:Joe's Diner
C: END:VEVENT
C: BEGIN:VEVENT
C: DTSTART:19990421T160000Z
C: DTEND:19990421T163000Z
C: END:VEVENT
C: END:VCOMMAND
C: END:VCALENDAR
C: .
S: 2.0 cap://cal.example.com/relcal2
And in this example, all instances of "Building 6" are replaced by "New
office lobby" in VEVENTs:
C: SENDDATA
C: Content-type:text/calendar; Method=MODIFY; Component=VCOMMAND
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1
C: METHOD:MODIFY
C: TARGET:relcal2
C: BEGIN:VCOMMAND
C: BEGIN:VEVENT
C: LOCATION:Building 6
C: END:VEVENT
C: BEGIN:VEVENT
C: LOCATION:New office lobby
C: END:VEVENT
C: END:VCOMMAND
C: END:VCALENDAR
C: .
S: 2.0 cap://cal.example.com/relcal2
7.2.1.5. MOVE Method
Arguments: ContainerId
Mansour/Dawson/Royer/Taler/Hill 45 Expires September 2000
Internet Draft CAP March 10, 2000
Data: data as described below
Result: 2.0 - success
2.2 - will attempt operation on the remote cap server
Permission
Calendar already exists
Bad args
Parent Calendar(s) not found
This method is used to move a calendar within the CS's hierarchy of
calendars.
[Editors Note: there could be VCAR issues with this... if a VCAR's scope
of influence is limited to a calendar, we are probably OK. We should
discuss this one]
7.2.1.6. NOOP Method
Arguments: none
Data: none
Result: 2.0 - success
This method does nothing. It can be sent to the server periodically to
request that the CS not time out the session.
7.2.1.7. READ Method
Arguments: ContainerId
Data: data as described below
Result: 2.0 - successful and the requested data follows
2.2 - will attempt read on the remote cap server
Permission
Bad args
Read Events
In the example below events on March 10,1999 between 080000Z and 190000Z
are read. In this case only 4 properties for each event are returned.
Two calendars are specified. Only booked (vs scheduled) entries are to
be returned.
C: SENDDATA
C: Content-type:text/calendar; Method=READ; Component=VQUERY
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1
C: METHOD:READ
Mansour/Dawson/Royer/Taler/Hill 46 Expires September 2000
Internet Draft CAP March 10, 2000
C: CMDID:xyz12345
C: TARGET:relcal2
C: TARGET:cap://bobo.ex.com/relcal3
C: BEGIN:VQUERY
C: QUERY:SELECT (DTSTART,DTEND,SUMMARY,UID)
C: FROM VEVENT
C: WHERE (DTEND >= 19990310T080000Z AND
C: DTSTART <= 19990310T190000Z AND
METHOD EQ CREATE)
C: ORDERBY (DTSTART ASC, DTEND, UID, SUMMARY)
C: END:VQUERY
C: END:VCALENDAR
C: .
S: 2.0 cap://cal.example.com/relcal2
S: Content-type:text/calendar; Method=RESPONSE;
S: Optinfo=VERSION:2.1
S: Content-Transfer-Encoding: 7bit
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: METHOD:RESPONSE
S: BEGIN:VEVENT
S: DTSTART:19990310T090000Z
S: DTEND:19990310T100000Z
S: UID:abcxyz12345
S: SUMMARY:Meet with Sir Elton
S: END:VEVENT
S: BEGIN:VEVENT
S: DTSTART:19990310T130000Z
S: DTEND:19990310T133000Z
S: UID:abcxyz8999
S: SUMMARY:Meet with brave brave Sir Robin
S: END:VEVENT
S: END:VCALENDAR
S: .
S: 2.0 cap://bobo.ex.com/relcal3
S: Content-type:text/calendar; Method=RESPONSE;Component=VDATA;
S: Optinfo=VERSION:2.1
S: Content-Transfer-Encoding: 7bit
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: METHOD:RESPONSE
S: BEGIN:VDATA
S: BEGIN:VEVENT
S: DTSTART:19990310T140000Z
S: DTEND:19990310T150000Z
S: UID:123456asdf
S: SUMMARY:Summer Budget
S: END:VEVENT
S: END:VDATA
S: END:VCALENDAR
S: .
Mansour/Dawson/Royer/Taler/Hill 47 Expires September 2000
Internet Draft CAP March 10, 2000
The return values are subject to VCAR filtering. That is, if the request
contains properties to which the UPN does not have access, those
properties will not appear in the return values. If the UPN has access
to at least one property of events, but has been denied access to all
properties called out in the request, the response will contain a single
RESPONSE-CODE property indicating the error. That is, the VEVENT
components will be the following:
S: 2.0 cap://bobo.ex.com/sally
S: Content-type:text/calendar; Method=RESPONSE;Component=VDATA;
S: Optinfo=VERSION:2.1
S: Content-Transfer-Encoding: 7bit
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: BEGIN:VDATA
S: BEGIN:VEVENT
S: RESPONSE-CODE:3.8
S: END:VEVENT
S: END:VDATA
S: END:VCALENDAR
S: .
If the UPN has no access to any events at all, the response will simply
be an empty data set. The response looks the same if there are
particular events to which the requester has been denied access.
S: 2.0 cap://bobo.ex.com/sally
S: Content-type:text/calendar; Method=RESPONSE;Component=VDATA;
S: Optinfo=VERSION:2.1
S: Content-Transfer-Encoding: 7bit
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: BEGIN:VDATA
S: END:VDATA
S: END:VCALENDAR
S: .
Find alarms within a range of time for booked (METHOD EQ CREATE)
VEVENTs.
C: SENDDATA
C: Content-type:text/calendar; Method=READ; Component=VQUERY
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1
C: METHOD:READ
C: CMDID:xyz12345
C: TARGET:relcal2
C: TARGET:cap://bobo.ex.com/relcal3
C: BEGIN:VQUERY
C: QUERY:SELECT (VEVENT.DTSTART,
Mansour/Dawson/Royer/Taler/Hill 48 Expires September 2000
Internet Draft CAP March 10, 2000
VEVENT.DTEND,VEVENT.SUMMARY, VEVENT.UID,
VALARM.*)
C: FROM VEVENT,VTODO
C: WHERE (VALARM.TRIGGER >= 19990310T080000Z AND
C: VALARM.TRIGGER <= 19990310T190000Z AND
METHOD EQ CREATE)
C: ORDERBY (VALARM.TRIGGER ASC)
C: END:VQUERY
C: END:VCALENDAR
C: .
S: 2.0 cap://bobo.ex.com/relcal3
S: Content-type:text/calendar; Method=RESPONSE;
S: Optinfo=VERSION:2.1
S: Content-Transfer-Encoding: 7bit
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: METHOD:RESPONSE
S: CMDID:xyz12345
S: TARGET:cap://bobo.ex.com/relcal3
S: BEGIN:VEVENT
S: DTSTART:19990310T130000Z
S: DTEND:19990310T133000Z
S: UID:abcxyz8999
S: SUMMARY:Meet with brave brave Sir Robin
S: BEGIN:VALARM
S: TRIGGER:19990310T132500Z
S: SUMMARY:Almost time..
S: ACTION:DISPLAY
S: END:VALARM
S: END:VEVENT
S: END:VCALENDAR
S: .
S: 2.0 cap://bobo.ex.com/relcal2
S: Content-type:text/calendar; Method=RESPONSE;
S: Optinfo=VERSION:2.1
S: Content-Transfer-Encoding: 7bit
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: METHOD:RESPONSE
S: CMDID:xyz12345
S: TARGET:cap://bobo.ex.com/relcal2
S: BEGIN:VEVENT
S: REQUEST-STATUS:2.0
S: END:VEVENT
S: END:VCALENDAR
S: .
Mansour/Dawson/Royer/Taler/Hill 49 Expires September 2000
Internet Draft CAP March 10, 2000
7.2.2. Scheduling Commands
The following provide a set of scheduling commands (or methods) in CAP.
Scheduling commands allow a CU to indirectly manipulate a calendar by
asking another CU to perform an operation on their calendar. For
example, CU-A can request CU-B to add a meeting to their calendar; in
effect inviting CU-B to the meeting.
Calendar access rights can be granted for scheduling commands without
granting rights for more generalized access with the calendar commands.
[Editors Note: This section needs to be completed by adding the
restriction tables for each of these iTIP methods. The basis for the
text is to be taken from [RFC2446].]
7.2.2.1. Reading out scheduling components
A CU might be invided to a meeting. If the CU had been invided by CAP,
the entry in the CU calendar will be scheduled, but not booked. So a
CUA will need to look for scheduled entries in the calendar and present
them to the CU or automaticly decide if the invitation is to be acceped
or processed.
Example: The little league coach places the teams entire schedule into
your calendar. Lets say that every game and practice is on a Firday
night and your calendar now has this iTIP scheduling data:
BEGIN:VCALENDAR
VERSION:2.0
METHOD:PUBLISH
BEGIN:VEVENT
DTSTAMP;TZID=US/Pacific:20000229T180000
DTSTART;TZID=US/Pacific:20000303T180000
ORGANIZER:coach@little.league.com
SUMMARY: Schedule of games and practice
UID:1-coarch@little.league.com
SEQUENCE:0
DESCRIPTION:Please have your child at the field
and ready to play by 6pm.
RRULE:FREQ=WEEKLY;COUNT=10
END:VEVENT
END:VCALENDAR
At this point the above VEVENT is not booked in your calendar, It is
simpley scheduled. A CUA would fetch this and all other scheduled
VEVENTs from your calendar with:
C: SENDDATA
C: Content-type:text/calendar; Method=READ; Component=VQUERY
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1
Mansour/Dawson/Royer/Taler/Hill 50 Expires September 2000
Internet Draft CAP March 10, 2000
C: METHOD:READ
C: CMDID:xyz12345
C: TARGET:relcal2
C: BEGIN:VQUERY
C: QUERY:SELECT (VEVENT.*)
C: FROM VEVENT
C: WHERE (METHOD != CREATE)
C: END:VQUERY
C: END:VCALENDAR
C: .
The the CUA and CU could determine which scheduling items were to remain
on the calendar. Each scheduling component could be deleted or updated
with METHOD:MODIFY to change the METHOD from PUBLISH, REQUEST, REPLY,
ADD, CANCEL, REFRESH, COUNTER, or DECLINE-COUNTER to what the CU and CUA
had decided.
In some cases the CUA could automaticly do the work and inform the CU.
An example of this is CANCEL. If configured to process METHOD:CANCEL it
could METHOD:DELETE the component an inform the CU that the booked
component had been canceled.
The CUA MUST process the scheduled components in the order sent. Some
optimization could be done by the CUA. One example is if a PUBLISH and
later a CANCEL for the same component with the same SEQUENCE number were
scheduled, but not booked. The CUA might never inform the CU and just
treat it as if the PUBLISH had never been received by doing a
METHOD:DELETE on both entries.
It is important to note that scheduled components do not show up in busy
time as BUSY. Only when they are booked does the TRANSP:OPAQUE property
take effect. A CS implementation could mark the time as TENTATIVE.
This is an implementation and administrative choice.
7.2.2.2. PUBLISH
Arguments:
Data: data as described below
Result: 2.0 - success
2.2 - will attempt operation on the remote cap server
Permission
Calendar already exists
Bad args
Parent Calendar(s) not found
This method is used to move a calendar within the CS's hierarchy of
calendars. If the CU wishes to keep the published entry. A
METHOD:MODIFY changing the entries METHOD from PUBLISH to CREATE would
be done, booking the entry. Or METHOD:DELETE if the CU did not wish
this scheduled item to exist in their calendar.
Mansour/Dawson/Royer/Taler/Hill 51 Expires September 2000
Internet Draft CAP March 10, 2000
7.2.2.3. REQUEST
7.2.2.4. REPLY
7.2.2.5. ADD
7.2.2.6. CANCEL
7.2.2.7. REFRESH
7.2.2.8. COUNTER
7.2.2.9. DECLINECOUNTER
7.2.3. iTIP Examples
The following examples describe scenarios for the handling of incoming
iTIP data. An appropriate sort-order for the handling of incoming iTIP
is by UID, Recurrence-id, sequence, dtstamp. This processing may be
optimized, for instance, REFRESHs could be processed last.
As an update to [RFC2446], data with the "COUNTER" method should be
processed even if the Sequence number is stale.
7.2.3.1. Sending and Receiving an iTIP request
In this example A invites B and C to a meeting, B accepts the meeting
and C rejects it. The calendars for A, B and C are relcal1, relcal2 and
relcal3 respectively, and are all on the same server, "cal.foo.com". A
lot of these described actions are performed by the CUAs and not the
users themselves, the CUAs are called A-c, B-c and C-c respectively.
A wishes to create a meeting with B and C, so A-c uses CAP to send the
following iTIP request to relcal2 and relcal3, while logged in to
"cal.foo.com".
BEGIN:VCALENDAR
VERSION:2.1
CMDID:xhj-dd
METHOD:REQUEST
TARGET:cap://cal.foo.com/relcal2
TARGET:relcal3
BEGIN:VEVENT
UID:abcd12345
DTSTART:19990307T180000Z
Mansour/Dawson/Royer/Taler/Hill 52 Expires September 2000
Internet Draft CAP March 10, 2000
DTEND:19990307T190000Z
ORGANIZER:cap://cal.foo.com/relcal1
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.com/relcal2
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.com/relcal3
SUMMARY:Important Meeting
END:VEVENT
END:VCALENDAR
An incoming event (indicated by the value of the "METHOD" property) then
appears in relcal2 and relcal3, with the following data:
BEGIN:VEVENT
METHOD:REQUEST
UID:abcd12345
DTSTART:19990307T180000Z
DTEND:19990307T190000Z
ORGANIZER:cap://cal.foo.com/relcal1
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.com/relcal2
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.com/relcal3
SUMMARY:Important Meeting
END:VEVENT
B-c and C-c must search for such incoming events, they do so using the
following CAP search:
BEGIN:VCALENDAR
VERSION:2.1
METHOD:READ
CMDID:xhr-de
TARGET:relcal2
# or TARGET:relcal3
BEGIN:VQUERY
QUERY:SELECT (ALL);
FROM VEVENT;
WHERE (METHOD == REQUEST);
END:VQUERY
END:VCALENDAR
In response to this search they get the above event. B-c and C-c must
then crack open the VEVENT, find the UID and determine if there is
already an event on their calendar with that UID. To do this they use
the following search:
BEGIN:VCALENDAR
VERSION:2.1
METHOD:READ
CMDID:xhr-df
TARGET:relcal2
BEGIN:VQUERY
QUERY:SELECT (*)
FROM VEVENT
WHERE (UID == abcd12345 AND METHOD == CREATE)
END:VQUERY
Mansour/Dawson/Royer/Taler/Hill 53 Expires September 2000
Internet Draft CAP March 10, 2000
END:VCALENDAR
We assume that the event is not already in their relcal2 or relcal3.
B-c prompts B who decides to accept the meeting request, and B-c creates
a copy of the event in relcal2, with the "PARTSTAT" parameter set to
ACCEPTED. B-c also sends this copy to the Organizer at relcal1 as an
iTIP REPLY, preserving the CMDID:
BEGIN:VCALENDAR
VERSION:2.1
CMDID:xhj-dd
METHOD:REPLY
TARGET:cap://cal.foo.com/relcal1
BEGIN:VEVENT
UID:abcd12345
DTSTART:19990307T180000Z
DTEND:19990307T190000Z
ORGANIZER:cap://cal.foo.com/relcal1
ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.foo.com/relcal2
SUMMARY:Important Meeting
END:VEVENT
END:VCALENDAR
C, on the other hand, decides to decline the meeting, and C-c sends a
reply to the Organizer to that effect, as follows:
BEGIN:VCALENDAR
VERSION:2.1
CMDID:xhj-dd
METHOD:REPLY
TARGET:cap://cal.foo.com/relcal1
BEGIN:VEVENT
UID:abcd12345
DTSTART:19990307T180000Z
DTEND:19990307T190000Z
ORGANIZER:cap://cal.foo.com/relcal1
ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3
SUMMARY:Important Meeting
END:VEVENT
END:VCALENDAR
It is preferable that C-c store the event in relcal3 even though it has
been declined. Storing the event in relcal3 allows subsequent iTIP
messages to be interpreted correctly. The "PARTSTAT" parameter indicates
that the event was refused.
After receiving the replies from relcal2 and relcal3, A-c updates the
version of the event in relcal1 to indicate the new participation
statii:
BEGIN:VEVENT
METHOD:REQUEST
Mansour/Dawson/Royer/Taler/Hill 54 Expires September 2000
Internet Draft CAP March 10, 2000
UID:abcd12345
DTSTART:19990307T180000Z
DTEND:19990307T190000Z
ORGANIZER:cap://cal.foo.com/relcal1
ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.foo.com/relcal2
ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3
SUMMARY:Important Meeting
END:VEVENT
A-c then sends a new iTIP request to relcal2 only, indicating the
updated information.
7.2.3.2. Handling an iTIP refresh
A little bit later, C is thinking about accepting the event in the
previous example, but first wants to check the current state of the
event. To find the current state C-c uses the iTIP "REFRESH" method,
sending the following to relcal1:
BEGIN:VCALENDAR
VERSION:2.1
CMDID:xud-pn
METHOD:REFRESH
TARGET:cap://cal.foo.com/relcal1
BEGIN:VEVENT
UID:abcd12345
ORGANIZER:cap://cal.foo.com/relcal1
ATTENDEE:cap://cal.foo.com/relcal3
DTSTAMP:19990306T202333Z
END:VEVENT
END:VCALENDAR
A-c finds the refresh as an incoming iTIP, and searches for the
corresponding event. Having found the event (with no changes since the
last example) A-c then verifies that relcal3 is in fact an Attendee of
the event and is thus allowed to request a refresh. (In the case of a
published event things are more complicated.) A-c packages the event up
as an iTIP request and sends it to relcal3:
BEGIN:VCALENDAR
VERSION:2.1
CMDID: xud-pn
METHOD:REQUEST
TARGET:cap://cal.foo.com/relcal3
BEGIN:VEVENT
UID:abcd12345
DTSTART:19990307T180000Z
DTEND:19990307T190000Z
ORGANIZER:cap://cal.foo.com/relcal1
ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.foo.com/relcal2
ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3
SUMMARY:Important Meeting
Mansour/Dawson/Royer/Taler/Hill 55 Expires September 2000
Internet Draft CAP March 10, 2000
SEQUENCE:0
DTSTAMP:19990306T204333Z
END:VEVENT
END:VCALENDAR
[Ed. - should the CMDID match that of the REFRESH?]
7.2.3.3. Sending and accepting an iTIP counter
Having received the latest copy of the event C wishes to propose a venue
for the event, using an iTIP COUNTER. To do this C-c sends the following
to relcal1:
BEGIN:VCALENDAR
VERSION:2.1
CMDID:zzykjjk
METHOD:COUNTER
TARGET:cap://cal.foo.com/relcal1
BEGIN:VEVENT
UID:abcd12345
DTSTART:19990307T180000Z
DTEND:19990307T190000Z
ORGANIZER:cap://cal.foo.com/relcal1
ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3
SUMMARY:Important Meeting
LOCATION:La Belle Province
COMMENT:My favourite restaurant, I'll definitely go if it's there.
END:VEVENT
END:VCALENDAR
Having sent the information to relcal1, C-c shouldn't store the new
details in relcal3. If C-c updated the version in relcal3 and relcal1
did not reply to the counter, then relcal3 would have incorrect
information. Instead C-c preserves the correct information and waits for
a response from relcal1. A CUA implementation may wish to preserve this
information itself, externally to the CS.
In order to receive an iTIP counter A-c follows the same search as for
other iTIP data, first find the incoming message, next find any matching
events in the calendar store.
Having found the matching event, A reviews the proposed changes and
decides to accept the COUNTER. To do this, A-c modifies the version in
relcal1 (bumping the sequence number) to:
BEGIN:VEVENT METHOD:CREATE UID:abcd12345 DTSTART:19990307T180000Z
DTEND:19990307T190000Z ORGANIZER:cap://cal.foo.com/relcal1
ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.foo.com/relcal2
ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3 SUMMARY:Important
Meeting LOCATION:La Belle Province SEQUENCE:1 END:VEVENT
A-c then sends the updated version as a request to both relcal2 and
Mansour/Dawson/Royer/Taler/Hill 56 Expires September 2000
Internet Draft CAP March 10, 2000
relcal3:
BEGIN:VCALENDAR
VERSION:2.1
CMDID:xup-po
METHOD:REQUEST
TARGET:cap://cal.foo.com/relcal2
TARGET:cap://cal.foo.com/relcal3
BEGIN:VEVENT
UID:abcd12345
DTSTART:19990307T180000Z
DTEND:19990307T190000Z
ORGANIZER:cap://cal.foo.com/relcal1
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.com/relcal2
ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.com/relcal3
SUMMARY:Important Meeting
LOCATION:La Belle Province
SEQUENCE:1
DTSTAMP:19990307T054339Z
END:VEVENT
END:VCALENDAR
7.2.3.4. Declining an iTIP counter
B does not like the new location and also counters the event, B-c sends
the following iTIP:
BEGIN:VCALENDAR
VERSION:2.1
CMDID:xim-ef
METHOD:COUNTER
TARGET:cap://cal.foo.com/relcal1
BEGIN:VEVENT
UID:abcd12345
DTSTART:19990307T180000Z
DTEND:19990307T190000Z
ORGANIZER:cap://cal.foo.com/relcal1
ATTENDEE:cap://cal.foo.com/relcal2
SUMMARY:Important Meeting
LOCATION:Au Coin Dor=E9
END:VEVENT
END:VCALENDAR
However, C does not accept the counter, and C-c replies with a decline
counter:
BEGIN:VCALENDAR
VERSION:2.1
CMDID:xim-ef
METHOD:DECLINE-COUNTER
TARGET:cap://cal.foo.com/relcal2
BEGIN:VEVENT
Mansour/Dawson/Royer/Taler/Hill 57 Expires September 2000
Internet Draft CAP March 10, 2000
DTSTAMP:19990307T093245Z
UID:abcd12345
ORGANIZER:cap://cal.foo.com/relcal1
SEQUENCE:1
END:VEVENT
END:VCALENDAR
Fortunately B-c kept the original information when sending the counter,
and there is no problem when no information is returned in the DECLINE-
COUNTER.
8. Response Codes
Numeric response codes are returned at both the transfer and application
layer. The same set of codes is used in both cases.
[Editors Note: Do we want to use the same set of codes?]
The format of these codes is described in [RFC2445], and extend in
[RFC2446] and [RFC2447]. The following describes new codes added to this
set.
At the application layer response codes are returned as the value of a
"REQUEST-STATUS" property. The value type of this property is modified
from that defined in [RFC2445], to make the accompanying text optional.
Code Params Description
----------------------------------------------------------
2.0 varies Success, The parameters vary with the
operation and are specified.
2.0.1 none Success, send data, terminate with
<CRLF>.<CRLF>
2.0.2 A reply is pending. It could not be com-
pleted in the specified amount of time.
The server awaits a CONTINUE or ABORT
command.
2.0.3 In response to the client issuing an
ABORT command, this reply code indicates
that any command currently underway was
successfully aborted.
Mansour/Dawson/Royer/Taler/Hill 58 Expires September 2000
Internet Draft CAP March 10, 2000
2.0.6 An operation is being attempted on a re-
mote server. This response indicates
that the server has not yet been con-
tacted but an attempt will be made to
contact it after the command has been
sent.
3.1.4 Capability not supported.
4.1 Calendar store access denied.
6.1 Authenticate failure: unsupported au-
thentication mechanism, credentials re-
jected.
6.2 Sender aborted authentication, authenti-
cation exchange cancelled.
6.3 Attempt to create or modify an event
such that it would overlap another event
in either of the following two circum-
stances:
(a) One of the events has a TRANSP prop-
erty set to OPAQUE-NOCONFLICT or TRANS-
PARENT-NOCONFLICT.
(b) The calendar's ALLOW-CONFLICT prop-
erty is set to NO.
7.0 A timeout has occurred. The server was
unable to complete the operation in the
requested time.
8.0 A failure has occurred in the Receiver
that prevents the operation from suc-
ceeding.
8.1 Sent when a session cannot be estab-
lished because the CAP Server is too
busy.
8.2 Used to signal that an ICAL object has
exceeded the server's size limit
8.3 A DATETIME value was too large to be
represented on this Calendar.
8.4 A DATETIME value was too far in the past
to be represented on this Calendar.
Mansour/Dawson/Royer/Taler/Hill 59 Expires September 2000
Internet Draft CAP March 10, 2000
8.5 An attempt was made to create a new ob-
ject but the unique id specified is al-
ready in use.
8.6 ID clash
9.0 An unrecognized command was received.
10.1 Accompanied by an alternate address. The
RECIPIENT specified should be contacted
at the given alternate address. The re-
ferral address MUST follow the reply
code.
10.2 The server is shutting down.
10.4 The operation has not be performed be-
cause it would cause the resources (mem-
ory, disk,CPU, etc) to exceed the allo-
cated quota.
10.5 The ITIP message has been queued too too
long. Delivery has been aborted.
----------------------------------------------------------
8.1. Minimum CS query implementation
The following is a MUST for a CS implementation.
8.1.1. Query by UID
<TBD>
8.1.2. Query by Date / Date-Time range
<TBD>
8.1.2.1. Date/Date-Time query with subset of properties
<TBD>
8.1.3. <TBD>
<TBD>
9. Detailed SQL Schema
This section describes a conceptual schema for object model in CAP. It
is used as the basis for querying data managed by the CS. This is only a
conceptual schema. Implementations can use any schema they like so long
as they are prepared to map CAP queries that are expressed in this
conceptual schema. Implementations are not required to use SQL database
technology. The protocol is designed such that a CUA does not need to
Mansour/Dawson/Royer/Taler/Hill 60 Expires September 2000
Internet Draft CAP March 10, 2000
understand SQL. The CUA just sends strings that happen to be valid SQL
queries.
This schema is based on SQL-92 [SQL] along with the [SQLCOM]
corrections.
Properties than can occur multiple times are intended to be put in
separate tables. For example
BEGIN:VEVENT
UID:1
DTSTART:19990326T201400Z
ORGANIZER:mailto:sam@abc.COM
SUMMARY:I have 2 attachments
ATTACHMENT;FMTTYPE=audio/basic:ftp://host.com/pub/sounds/bell.au
ATTACHMENT;FMTTYPE=audio/basic:ftp://host.com/pub/sounds/bell2.au
END:VEVENT
There are two ATTACHMENT properties each having a unique value. These
are kept in separate tables. This is diagrammed below. The diagram is
not a complete representation of the VEVENT table. It is an abbreviated
table used to illustrate how properties that can occur multiple times
are intended to be represented.
+----------------------------------------------------------------------+
| ABBREVIATED VEVENT TABLE |
+----+-----------------+---------------------+--------------+----------+
| | | | | |
|UID |DTSTART |ORGANIZER |SUMMARY |ATTACH_KEY|
+----+-----------------+---------------------+--------------+----------+
|1 |19990326T201400Z |mailto:sam@abc.com |I have 2 at- |123 |
| | | |tachments | |
+----+-----------------+---------------------+--------------+----------+
|999 |19700101T000000Z |mailto:user@host.com |I have no | |
| | | |attachments | |
+----+-----------------+---------------------+--------------+----------+
Mansour/Dawson/Royer/Taler/Hill 61 Expires September 2000
Internet Draft CAP March 10, 2000
+-----------------------------------------------------------------------+
| ABBREVIATED ATTACH_KEY TABLE |
+------------+------------------------------------+---------------------+
| | | |
|ATTACH_KEY |VALUE | INLINE_BLOB |
+------------+------------------------------------+---------------------+
|123 |ftp://host.com/pub/sounds/bell.au | |
+------------+------------------------------------+---------------------+
|123 |ftp://host.com/pub/sounds/bell2.au | |
+------------+------------------------------------+---------------------+
|234 | | MIICajCCAdO-gAw- |
| | | IBAgICBEU <...re- |
| | | mainder of "BASE64" |
| | | encoded binary da- |
| | | ta...> |
+------------+------------------------------------+---------------------+
9.1. iCalendar Store Schema
The following defines the schema for an iCalendar object and the
components, properties, and parameters defined and used in [RFC2445],
[RFC2446], [RFC2447], and [CAP].
NOTES:
CURRENT_DATETIME would not be stored in the database. It
is selectable and read only.
When supporting virtual hosts, there could be more than
one row in the CALSTORE table. And then the CSID MUST
not be empty.
TIMESTAMP(14) is the SQL value equivelant of DATE-TIME.
FLOAT(7,3) is an SQL 3x3 floating number (xxx.yyy).
9.1.1. ACTION schema
/*
* If VALUE is NULL, then OTHER_VALUE contains non-rfc2445 value .
*/
CREATE TABLE ACTION (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE ENUM("AUDIO", "DISPLAY", "EMAIL",
"PROCEDURE") NOT NULL,
OTHER_VALU TEXT,
XPARAM INTEGER /* VALUE_KEY */
);
Mansour/Dawson/Royer/Taler/Hill 62 Expires September 2000
Internet Draft CAP March 10, 2000
9.1.2. ATTACH schema
/*
* VALUE is a FILE uri. The data is decoded (per ENCODING) prior to being
* stored into the file
*/
CREATE TABLE ATTACH (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE VARCHAR(255) NOT NULL,
ISBINARY ENUM("T", "F") DEFAULT "F",
FMTTYPE INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.3. ATTENDEE schema
CREATE TABLE ATTENDEE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT,
CUTYPE INTEGER, /* VALUE_KEY */
MEMBER INTEGER, /* VALUE_KEY */
ROLE INTEGER, /* VALUE_KEY */
PARTSTAT INTEGER, /* VALUE_KEY */
RSVP ENUM("T", "F") DEFAULT "F",
DELEGATED_TO INTEGER, /* VALUE_KEY */
DELEGATED_FROM INTEGER, /* VALUE_KEY */
CN INTEGER, /* VALUE_KEY */
DIR INTEGER, /* VALUE_KEY */
LANGUAGE INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.4. CALSTORE schema
CREATE TABLE CALSTORE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
CSID VARCHAR(255) NOT NULL,
CALMASTER TINYTEXT NOT NULL,
DEFAULT_VCAR INTEGER, /* VALUE_KEY */
MAXDATE TIMESTAMP(14) NOT NULL
DEFAULT "99991231235959",
MINDATE TIMESTAMP(14) NOT NULL
DEFAULT "00000101000000",
CURRENT_DATETIME TIMESTAMP(14) NOT NULL,
RECUR_ACCEPTED ENUM("T", "F") NOT NULL DEFAULT "T",
RECUR_EXPAND ENUM("T", "F") NOT NULL DEFAULT "T",
RECUR_LIMIT INTEGER DEFAULT 0,
VERSION VARCHAR(10) NOT NULL DEFAULT "2.0"
);
Mansour/Dawson/Royer/Taler/Hill 63 Expires September 2000
Internet Draft CAP March 10, 2000
9.1.5. CHILDREN schema
CREATE TABLE CHILDREN (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY, /* KEY_VALUE */
CALID VARCHAR(255)
);
9.1.6. CLASS schema
CREATE TABLE CLASS (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE ENUM("PUBLIC", "PRIVATE",
"CONFIDENTIAL",
"<other>") NOT NULL,
OTHER_VALUE TEXT,
XPARAM INTEGER /* VALUE_KEY */
);
9.1.7. CN schema
CREATE TABLE CN (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE VARCHAR(255) NOT NULL
);
9.1.8. COMMENT schema
CREATE TABLE COMMENT (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT NOT NULL,
ALTREP INTEGER, /* VALUE_KEY */
LANGUAGE INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.9. CONTACT schema
CREATE TABLE CONTACT (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TINYTEXT NOT NULL,
ALTREP VARCHAR(255),
LANGUAGE INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
Mansour/Dawson/Royer/Taler/Hill 64 Expires September 2000
Internet Draft CAP March 10, 2000
9.1.10. CREATED schema
CREATE TABLE CREATED (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TIMESTAMP(14) NOT NULL,
VALUETYPE INTEGER NOT NULL, /* VALUE_KEY */
TZID INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.11. CUTYPE schema
CREATE TABLE CUTYPE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE ENUM("INDIVIDUAL",
"GROUP",
"RESOURCE",
"ROOM",
"UNKNOWN",
"<other>") NOT NULL,
OTHER_VALUE TINYTEXT
);
9.1.12. DAYLIGHT_STANDARD schema
CREATE TABLE DAYLIGHT_STANDARD (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
DTSTART INTEGER NOT NULL, /* VALUE_KEY */
TZOFFSETFROM INTEGER NOT NULL, /* SECONDS */
TZOFFSETTO INTEGER NOT NULL, /* SECONDS */
COMMENT INTEGER, /* VALUE_KEY */
RDATE INTEGER, /* VALUE_KEY */
RRULE INTEGER, /* VALUE_KEY */
TZNAME TINYTEXT,
XPROP INTEGER /* VALUE_KEY */
);
9.1.13. DESCRIPTION schema
CREATE TABLE DESCRIPTION (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT,
ALTREP INTEGER, /* VALUE_KEY */
Mansour/Dawson/Royer/Taler/Hill 65 Expires September 2000
Internet Draft CAP March 10, 2000
LANGUAGE INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.14. DIR schema
CREATE TABLE DIR (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT
);
9.1.15. DTEND schema
CREATE TABLE DTEND (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TIMESTAMP(14) NOT NULL,
VALUETYPE INTEGER NOT NULL, /* VALUE_KEY */
TZID INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.16. DTSTAMP schema
CREATE TABLE DTSTART (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TIMESTAMP(14) NOT NULL,
VALUETYPE INTEGER NOT NULL, /* VALUE_KEY */
TZID INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.17. DUE schema
CREATE TABLE DUE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TIMESTAMP(14) NOT NULL,
VALUETYPE INTEGER NOT NULL, /* VALUE_KEY */
TZID INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
Mansour/Dawson/Royer/Taler/Hill 66 Expires September 2000
Internet Draft CAP March 10, 2000
9.1.18. DURATION schema
CREATE TABLE DURATION (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE INTEGER, /* SECONDS */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.19. EXDATE schema
CREATE TABLE EXDATE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TIMESTAMP(14) NOT NULL,
VALUETYPE INTEGER NOT NULL, /* VALUE_KEY */
TZID INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.20. EXRULE schema
CREATE TABLE EXRULE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE INTEGER NOT NULL, /* VALUE_KEY (RECUR) */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.21. FBTYPE schema
CREATE TABLE FBTYPE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE ENUM("FREE", "BUSY",
"BUSY-UNAVALIBLE",
"BUSY-TENTATIVE",
"<other>") NOT NULL,
OTHER_VALUE TINYTEXT
);
9.1.22. FMTTYPE schema
CREATE TABLE FMTTYPE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TINYTEXT
);
Mansour/Dawson/Royer/Taler/Hill 67 Expires September 2000
Internet Draft CAP March 10, 2000
9.1.23. FREEBUSY schema
CREATE TABLE FREEBUSY (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE_FROM TIMESTAMP(14) NOT NULL,
VALUE_TO TIMESTAMP(14),
DURATION INTEGER, /* SECONDS */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.24. GEO schema
CREATE TABLE GEO (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
LATITUDE FLOAT(7,3),
LONGITUDE FLOAT(7,3),
XPARAM INTEGER /* VALUE_KEY */
);
9.1.25. LANGUAGE schema
CREATE TABLE LANGUAGE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TINYTEXT
);
9.1.26. LAST_MODIFIED schema
CREATE TABLE LAST_MODIFIED (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TIMESTAMP(14) NOT NULL,
XPARAM INTEGER /* VALUE_KEY */
);
9.1.27. MEMBER schema
CREATE TABLE MEMBER (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT
);
Mansour/Dawson/Royer/Taler/Hill 68 Expires September 2000
Internet Draft CAP March 10, 2000
9.1.28. METHOD schema
CREATE TABLE METHOD (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE ENUM("PUBLISH",
"REQUEST",
"REFRESH",
"CANCEL",
"ADD",
"REPLY",
"COUNTER",
"DECLINE-COUNTER",
"CREATE",
"DELETE",
"MODIFY",
"MOVE",
"READ",
"<other>") NOT NULL,
OTHER_VALUE TEXT
);
9.1.29. ORGANIZER schema
CREATE TABLE ORGANIZER (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT NOT NULL,
CN INTEGER, /* VALUE_KEY */
DIR INTEGER, /* VALUE_KEY */
SENT_BY INTEGER, /* VALUE_KEY */
LANGUAGE INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.30. OWNERS schema
CREATE TABLE OWNERS (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TINYTEXT NOT NULL
);
9.1.31. PARTSTAT schema
CREATE TABLE PARTSTAT (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE ENUM("NEEDS-ACTION",
"ACCEPTED",
"DECLINED",
Mansour/Dawson/Royer/Taler/Hill 69 Expires September 2000
Internet Draft CAP March 10, 2000
"TENTATIVE",
"DELEGATED",
"COMPLETED",
"IN-PROCESS",
"<other>")
NOT NULL DEFAULT "NEEDS-ACTION",
OTHER_VALUE TINYTEXT
);
9.1.32. PERCENT_COMPLETE schema
CREATE TABLE PERCENT_COMPLETE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE INTEGER NOT NULL,
XPARAM INTEGER /* VALUE_KEY */
);
9.1.33. PRIORITY schema
CREATE TABLE PRIORITY (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE INTEGER NOT NULL,
XPARAM INTEGER /* VALUE_KEY */
);
9.1.34. RDATE schema
/* VALUETYPE (D) = DATE, (T) = DATE-TIME, (P) = PERIOD */
CREATE TABLE RDATE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TIMESTAMP(14) NOT NULL,
VALUETYPE ENUM("D", "T", "P") NOT NULL DEFAULT "T",
TZID INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.35. RECUR schema
CREATE TABLE RECUR (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
FREQ ENUM("SECONDLY", "MINUTELY", "HOURLY",
"DAILY", "WEEKLY", "MONTHLY", "YEARLY"),
UNTIL TIMESTAMP(14),
COUNT INTEGER,
INTERVAL_VAL INTEGER,
Mansour/Dawson/Royer/Taler/Hill 70 Expires September 2000
Internet Draft CAP March 10, 2000
BYSECOND SET("1", "2", "3", "4", "5", "6", "7", "8",
"9", "10", "11", "12", "13", "14", "15",
"16", "17", "18", "19", "20", "21", "22",
"23", "24", "25", "26", "27", "28", "29",
"30", "31", "32", "33", "34", "35", "36",
"37", "38", "39", "40", "41", "42", "43",
"44", "45", "46", "47", "47", "48", "49",
"50", "51", "52", "53", "54", "55", "56",
"57", "58", "59"),
BYMINUTE SET("1", "2", "3", "4", "5", "6", "7", "8",
"9", "10", "11", "12", "13", "14", "15",
"16", "17", "18", "19", "20", "21", "22",
"23", "24", "25", "26", "27", "28", "29",
"30", "31", "32", "33", "34", "35", "36",
"37", "38", "39", "40", "41", "42", "43",
"44", "45", "46", "47", "47", "48", "49",
"50", "51", "52", "53", "54", "55", "56",
"57", "58", "59"),
BYHOUR SET("1", "2", "3", "4", "5", "6", "7", "8",
"9", "10", "11", "12", "13", "14", "15",
"16", "17", "18", "19", "20", "21", "22",
"23"),
BYDAY TINYTEXT,
BYMONTHDAY SET("1", "2", "3", "4", "5", "6", "7", "8",
"9", "10", "11", "12", "13", "14", "15",
"16", "17", "18", "19", "20", "21", "22",
"23", "24", "25", "26", "27", "28", "29",
"30", "31", "-1", "-2", "-3", "-4", "-5",
"-6", "-7", "-8", "-9", "-10", "-11",
"-12", "-13", "-14", "-15", "-16", "-17",
"-18", "-19", "-20", "-21", "-22", "-23",
"-24", "-25", "-26", "-27", "-28", "-29",
"-30", "-31"),
BYYEARDAY TINYTEXT,
BYWEEKNO TINYTEXT,
BYMONTH SET("1", "2", "3", "4", "5", "6", "7", "8",
"9", "10", "11", "12"),
BYSETPOS TINYTEXT,
WKST SET("SU", "MO", "TU", "WE", "TH", "FR", "SA"),
XPARAM INTEGER /* VALUE_KEY */
);
9.1.36. RECURRENCE_ID schema
CREATE TABLE RECURRENCE_ID (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TIMESTAMP(14) NOT NULL,
VALUETYPE INTEGER NOT NULL, /* VALUE_KEY */
RANGE ENUM("THISANDPRIOR", "THISANDFUTURE"),
TZID INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
Mansour/Dawson/Royer/Taler/Hill 71 Expires September 2000
Internet Draft CAP March 10, 2000
);
9.1.37. RELATED_TO schema
CREATE TABLE RELATED_TO (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT,
RELTYPE ENUM("PARENT", "CHILD", "SIBLING",
"<other>"),
OTHER_RELTYPE TINYTEXT,
XPARAM INTEGER /* VALUE_KEY */
);
9.1.38. REPEAT schema
CREATE TABLE REPEAT (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE INTEGER NOT NULL DEFAULT 0,
XPARAM INTEGER /* VALUE_KEY */
);
9.1.39. RESOURCES schema
CREATE TABLE RESOURCES (
VALUE_Y INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT NOT NULL,
ALTREP INTEGER, /* VALUE_KEY */
LANGUAE INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.40. ROLE schema
CREATE TABLE ROLE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE ENUM("CHAIR", "REQ-PARTICIPANT",
"OPT-PARTICIPANT",
"NON-PARTICIPANT",
"<other>")
NOT NULL DEFAULT "REQ-PARTICIPANT",
OTHER_VALUE TINYTEXT
);
Mansour/Dawson/Royer/Taler/Hill 72 Expires September 2000
Internet Draft CAP March 10, 2000
9.1.41. RRULE schema
CREATE TABLE RRULE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE INTEGER NOT NULL, /* VALUE_KEY (RECUR) */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.42. SEQUENCE schema
CREATE TABLE SEQUENCE (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY DEFAULT 0,
VALUE INTEGER NOT NULL,
XPARAM INTEGER /* VALUE_KEY */
);
9.1.43. STATUS schema
CREATE TABLE STATUS (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE ENUM("TENTATIVE",
"CONFIRMED",
"CANCELLED",
"NEEDS-ACTION",
"COMPLETED",
"IN-PROCESS",
"DRAFT",
"FINAL") NOT NULL,
XPARAM INTEGER /* VALUE_KEY */
);
9.1.44. SUMMARY schema
CREATE TABLE SUMMARY (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TINYTEXT,
ALTREP INTEGER, /* VALUE_KEY */
LANGUAGE INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.45. TRANSP schema
CREATE TABLE TRANSP (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
Mansour/Dawson/Royer/Taler/Hill 73 Expires September 2000
Internet Draft CAP March 10, 2000
VALUE ENUM("OPQQUE", "TRANSPARENT",
"OPAQUE-NOCONFLICTS",
"TRANSPARENT-NOCONFLICTS")
NOT NULL DEFAULT "TRANSPARENT",
XPARAM INTEGER /* VALUE_KEY */
);
9.1.46. TRIGGER schema
CREATE TABLE TRIGGER (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUETYPE INTEGER NOT NULL, /* VALUE_KEY */
VALUE_DT TIMESTAMP(14),
VALUE_P INTEGER, /* SECONDS */
RELATED INTEGER, /* VALUE_KEY */
XPARAM INTEGER /* VALUE_KEY */
);
9.1.47. TZID schema
CREATE TABLE TZID (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT
);
9.1.48. UID schema
CREATE TABLE UID (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT,
XPARAM INTEGER /* VALUE_KEY */
);
9.1.49. URL schema
CREATE TABLE URL (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT,
XPARAM INTEGER /* VALUE_KEY */
);
Mansour/Dawson/Royer/Taler/Hill 74 Expires September 2000
Internet Draft CAP March 10, 2000
9.1.50. VALARM schema
CREATE TABLE VALARM (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
ACTION INTEGER NOT NULL, /* VALUE_KEY */
ATTACH INTEGER,
DESCRIPTION INTEGER, /* VALUE_KEY */
DURATION INTEGER, /* VALUE_KEY */
REPEAT INTEGER, /* VALUE_KEY */
SUMMARY INTEGER, /* VALUE_KEY */
TRIGGER INTEGER, /* VALUE_KEY */
X_PROP INTEGER /* VALUE_KEY */
);
9.1.51. VCALENDAR schema
CREATE TABLE VCALENDAR (
VALUE_KEY INTEGER NOT NULL,
ALLOW_CONFLICTS ENUM("T", "F") DEFAULT "T",
CALSCALE TINYTEXT NOT NULL,
CHARSET TINYTEXT NOT NULL,
CHILDREN INTEGER, /* VALUE_KEY */
CREATED INTEGER, /* VALUE_KEY */
DEFAULT_VCAR INTEGER NOT NULL, /* VALUE_KEY */
LANGUAGE INTEGER, /* VALUE_KEY */
LAST_MODIFIED INTEGER, /* VALUE_KEY */
NAME TINYTEXT,
OWNERS INTEGER, /* VALUE_KEY */
PARENT INTEGER, /* VALUE_KEY */
RELCALID VARCHAR(255) NOT NULL PRIMARY KEY,
TOMESTONE ENUM("T", "F") NOT NULL DEFAULT "T",
TZID INTEGER NOT NULL /* VALUE_KEY */
);
9.1.52. VCAR schema
CREATE TABLE VCAR (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TINYTEXT
/*<TODO>*/
);
9.1.53. VEVENT schema
The METHOD value will be CREATE for booked entries. Or it must be a
valid scheduling METHOD such as PUBLISH, REQUEST, REPLY, ADD, CANCEL,
REFRESH, COUNTER or DECLINE-COUNTER.
Mansour/Dawson/Royer/Taler/Hill 75 Expires September 2000
Internet Draft CAP March 10, 2000
CREATE TABLE VEVENT (
ATTACH INTEGER, /* VALUE_KEY */
ATTENDEE INTEGER, /* VALUE_KEY */
CATEGORIES INTEGER, /* VALUE_KEY */
CLASS INTEGER, /* VALUE_KEY */
COMMENT INTEGER, /* VALUE_KEY */
CONTACT INTEGER, /* VALUE_KEY */
CREATED INTEGER, /* VALUE_KEY */
DESCRIPTION INTEGER, /* VALUE_KEY */
DTEND INTEGER, /* VALUE_KEY */
DTSTAMP INTEGER, /* VALUE_KEY */
DTSTART INTEGER, /* VALUE_KEY */
DURATION INTEGER, /* VALUE_KEY */
EXDATE INTEGER, /* VALUE_KEY */
EXRULE INTEGER, /* VALUE_KEY */
GEO INTEGER, /* VALUE_KEY */
LAST_MODIFIED INTEGER, /* VALUE_KEY */
LOCATION INTEGER, /* VALUE_KEY */
METHOD INTEGER, /* VALUE_KEY */
ORGANIZER INTEGER, /* VALUE_KEY */
PRIORITY INTEGER, /* VALUE_KEY */
RECURRENCE_ID INTEGER, /* VALUE_KEY */
RDATE_KEY INTEGER, /* VALUE_KEY */
RELATED_TO INTEGER, /* VALUE_KEY */
RESOURCES INTEGER, /* VALUE_KEY */
RRULE INTEGER, /* VALUE_KEY */
SUMMARY INTEGER, /* VALUE_KEY */
SEQUENCE INTEGER, /* VALUE_KEY */
STATUS INTEGER, /* VALUE_KEY */
TRANSP INTEGER, /* VALUE_KEY */
UID INTEGER, /* VALUE_KEY */
URL INTEGER, /* VALUE_KEY */
X_PROP_KEY INTEGER, /* VALUE_KEY */
VALARM_KEY INTEGER /* VALUE_KEY */
);
9.1.54. VFREEBUSY schema
An implementation may not actually have a VFREEBUSY table as the
information may be produced dynamicly. However a CS MUST appear to
provide this table as this may be how a CUA chooses to query for
VFREEBUSY information while using [CAP]. Example, it probably would not
make any sense for ATTENDEE to exist in this table, yet a CUA may wish
to ask for the VFREEBUSY for an ATTENDEE.
CREATE TABLE VFREEBUSY (
ATTENDEE INTEGER, /* VALUE_KEY */
COMMENT INTEGER, /* VALUE_KEY */
CONTACT INTEGER, /* VALUE_KEY */
DTEND INTEGER, /* VALUE_KEY */
Mansour/Dawson/Royer/Taler/Hill 76 Expires September 2000
Internet Draft CAP March 10, 2000
DTSTAMP INTEGER, /* VALUE_KEY */
DTSTART INTEGER, /* VALUE_KEY */
FREEBUSY INTEGER, /* VALUE_KEY */
METHOD INTEGER, /* VALUE_KEY */
ORGANIZER INTEGER, /* VALUE_KEY */
X_PROP_KEY INTEGER, /* VALUE_KEY */
URL INTEGER /* VALUE_KEY */
);
9.1.55. VJOURNAL schema
The METHOD value will be CREATE for booked entries. Or it must be a
valid scheduling METHOD such as PUBLISH, REQUEST, REPLY, ADD, CANCEL,
REFRESH, COUNTER or DECLINE-COUNTER.
CREATE TABLE VJOURNAL (
ATTACH_KEY INTEGER, /* VALUE_KEY */
CATEGORIES INTEGER, /* VALUE_KEY */
CLASS INTEGER, /* VALUE_KEY */
COMMENT INTEGER, /* VALUE_KEY */
CONTACT INTEGER, /* VALUE_KEY */
CREATED INTEGER, /* VALUE_KEY */
DESCRIPTION INTEGER, /* VALUE_KEY */
DTSTAMP INTEGER, /* VALUE_KEY */
DTSTART INTEGER, /* VALUE_KEY */
EXDATE INTEGER, /* VALUE_KEY */
EXRULE INTEGER, /* VALUE_KEY */
LAST_MODIFIED INTEGER, /* VALUE_KEY */
METHOD INTEGER, /* VALUE_KEY */
ORGANIZER INTEGER, /* VALUE_KEY */
RDATE INTEGER, /* VALUE_KEY */
RECURRENCE_ID INTEGER, /* VALUE_KEY */
RELATED_TO INTEGER, /* VALUE_KEY */
RRULE INTEGER, /* VALUE_KEY */
SEQUENCE INTEGER, /* VALUE_KEY */
STATUS INTEGER, /* VALUE_KEY */
SUMMARY INTEGER, /* VALUE_KEY */
UID INTEGER, /* VALUE_KEY */
X_PROP INTEGER /* VALUE_KEY */
);
9.1.56. VQUERY schema
Stored VQUERYs will use the following schema.
CREATE TABLE VQUERY (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TINYTEXT, /* QUERYNAME */
SCOPE TINYTEXT,
MAXRESULTS INTEGER,
Mansour/Dawson/Royer/Taler/Hill 77 Expires September 2000
Internet Draft CAP March 10, 2000
MAXSIZE INTEGER,
CARSELECT TEXT,
CARWHERE TEXT,
CARORDERBY TEXT,
X_PROP INTEGER /* VALUE_KEY */
);
9.1.57. VTIMEZONE schema
CREATE TABLE VTIMEZONE (
DAYLIGHT INTEGER NOT NULL, /* VALUE_KEY */
STANDARD INTEGER NOT NULL, /* VALUE_KEY */
TZID INTEGER NOT NULL, /* VALUE_KEY */
TZURL INTEGER, /* VALUE_KEY */
X_PROP_KEY INTEGER /* VALUE_KEY */
);
9.1.58. VTODO schema
The METHOD value will be CREATE for booked entries. Or it must be a
valid scheduling METHOD such as PUBLISH, REQUEST, REPLY, ADD, CANCEL,
REFRESH, COUNTER or DECLINE-COUNTER.
CREATE TABLE VTODO (
ATTENDEE INTEGER, /* VALUE_KEY */
ATTACH INTEGER, /* VALUE_KEY */
CATEGORIES INTEGER, /* VALUE_KEY */
CLASS INTEGER, /* VALUE_KEY */
COMMENT INTEGER, /* VALUE_KEY */
CONTACT INTEGER, /* VALUE_KEY */
CREATED INTEGER NOT NULL, /* VALUE_KEY */
DESCRIPTION INTEGER, /* VALUE_KEY */
DTSTAMP INTEGER NOT NULL, /* VALUE_KEY */
DTSTART INTEGER NOT NULL, /* VALUE_KEY */
DUE INTEGER, /* VALUE_KEY */
DURATION INTEGER, /* VALUE_KEY */
EXDATE INTEGER, /* VALUE_KEY */
EXRULE INTEGER, /* VALUE_KEY */
GEO INTEGER, /* VALUE_KEY */
LAST_MODIFIED INTEGER NOT NULL, /* VALUE_KEY */
LOCATION INTEGER, /* VALUE_KEY */
METHOD INTEGER, /* VALUE_KEY */
ORGANIZER INTEGER, /* VALUE_KEY */
PERCENT_COMPLETE INTEGER, /* VALUE_KEY */
PRIORITY INTEGER, /* VALUE_KEY */
RDATE INTEGER, /* VALUE_KEY */
RECURRENCE_ID INTEGER, /* VALUE_KEY */
RESOURCES INTEGER, /* VALUE_KEY */
RRULE INTEGER, /* VALUE_KEY */
SEQUENCE INTEGER, /* VALUE_KEY */
Mansour/Dawson/Royer/Taler/Hill 78 Expires September 2000
Internet Draft CAP March 10, 2000
SUMMARY INTEGER NOT NULL, /* VALUE_KEY */
UID INTEGER NOT NULL PRIMARY KEY, /* VALUE_KEY */
URL INTEGER, /* VALUE_KEY */
X_PROP INTEGER, /* VALUE_KEY */
VALARM INTEGER /* VALUE_KEY */
);
9.1.59. X_PROP schema
CREATE TABLE X_PROP (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT NOT NULL,
NAME TEXT NOT NULL,
PARAMS INTEGER /* VALUE_KEY (XPARAM)*/
);
9.1.60. XPARAM schema
CREATE TABLE XPARAM (
VALUE_KEY INTEGER NOT NULL PRIMARY KEY,
VALUE TEXT NOT NULL,
NAME TEXT NOT NULL
);
9.2. Query example
<TBD>
10. Examples
For all the examples in this section, the authenticated user is
user@example.com.
10.1. Authentication Examples
10.1.1. Login Using Kerberos V4
Use Kerberos V4 to authenticate as bill@example.com to the CAP server on
cal.example.com.
C: <connect to cal.example.com on port ...>
S: 2.0
S: .
C: CAPABILTY
S: CAPVERSION=1.0
Mansour/Dawson/Royer/Taler/Hill 79 Expires September 2000
Internet Draft CAP March 10, 2000
S: ITIPVERSION=1.0
S: AUTH=KERBEROS_V4
S: AUTH=DIGEST_MD5
S: .
C: AUTHENTICATE KERBEROS_V4
S: AmFYig==
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
S: or//EoAADZI=
C: DiAF5A4gA+oOIALuBkAAmw==
S: 2.0
S: IDENTITY=bill@example.com
S: CAPVERSION=1.0
S: ITIPVERSION=1.0
S: AUTH=KERBEROS_V4
S: AUTH=DIGEST_MD5
S: CAR=CAR-FULL-1
S: MINDATE=19700101T000000Z
# who knows this date (end of the 32 bit number)?
S: MAXDATE=20370201T000000Z
S: .
10.1.2. Error Scenarios
Use of SASL Authorization Identity is not supported. Use the IDENTITY
command instead. If you attempt to use the Authorization Identity, an
error status will be returned.
C: AUTHENTICATE KERBEROS_V4
S: AmFYig==
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
S: or//EoAADZI=
C: DiAF5A4gA+oOIALuBkAAmw==
S: 6.1
S: .
Sender aborted authentication:
C: AUTHENTICATE KERBEROS_V4
S: AmFYig==
C: .
S: 6.2
S: .
Unsupported mechanism:
C: AUTHENTICATE Experimental_Auth
S: 6.3
S: .
Mansour/Dawson/Royer/Taler/Hill 80 Expires September 2000
Internet Draft CAP March 10, 2000
10.2. Read Examples
10.2.1. Read From A Single Calendar
In this example bill@example.com reads a day's worth of events from
cap://cal.example.com/opaqueid99.
C: SENDDATA
C: Content-type:text/calendar; Method=READ; Component=VQUERY
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1
C: METHOD:READ
C: CMDID:xyz12345
C: TARGET:cap://cal.example.com/opaqueid99
C: BEGIN:VQUERY
C: QUERY:SELECT (VEVENT.DTSTART,VEVENT.DTEND,SUMMARY,UID);
C: FROM VEVENTTABLE;
C: WHERE (VEVENT.DTEND >= 19990714T080000Z AND
C: VEVENT.DTSTART <= 19990715T080000Z);
C: ORDERBY (VEVENT.DTSTART ASC, VEVENT.DTEND, UID, SUMMARY)
C: END:VQUERY
C: END:VCALENDAR
C: .
# this response code means that the transport successfully
# delivered the data.
S: 2.0 ; got the request OK ; really
S: .
S: Content-type:text/calendar; Method=RESPONSE;
S: Optinfo=VERSION:2.1
S: Content-Transfer-Encoding: 7bit
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: METHOD:RESPONSE
S: TARGET:cap://cal.example.com/opaqueid99
S: CMDID:xyz12345
S: RESPONSE-STATUS:2.0
S: BEGIN:VEVENT
S: DTSTART:19990714T200000Z
S: DTEND:19990714T210000Z
S: UID:000444888929922
S: SUMMARY:Blah bla
S: END:VEVENT
S: BEGIN:VEVENT
S: UID:0034848098038888989443
S: SUMMARY:meeting
S: DTEND:19990714T233000Z
S: DTSTART:19990714T223000Z
S: END:VEVENT
S: END:VCALENDAR
S: .
Mansour/Dawson/Royer/Taler/Hill 81 Expires September 2000
Internet Draft CAP March 10, 2000
10.2.2. Read From Multiple Calendars
In this example bill@example.com reads a day's worth of events from
cap://cal.example.com/opaqueid101 and cap://cal.example.com/opaqueid103
C: SENDDATA
C: Content-type:text/calendar; Method=READ; Component=VQUERY
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1
C: METHOD:READ
C: CMDID:xyz12346
C: TARGET:cap://cal.example.com/opaqueid101
C: TARGET:opaqueid103
C: BEGIN:VQUERY
C: QUERY:SELECT (DTSTART,DTEND,SUMMARY,UID);
C: FROM VEVENT;
C: WHERE (DTEND >= 19990714T080000Z AND
C: DTSTART <= 19990715T080000Z);
C: ORDERBY (DTSTART ASC, DTEND, UID, SUMMARY)
C: END:VQUERY
C: END:VCALENDAR
C: .
S: 2.0
S: .
S: Content-Type:multipart/mixed;boundary="--FEE3790DC7E35189CA67"
S:
S: ----FEE3790DC7E35189CA67
S: Content-type:text/calendar; Method=RESPONSE;
S: Optinfo=VERSION:2.1
S: Content-Transfer-Encoding: 7bit
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
S: METHOD:RESPONSE
S: TARGET:cap://cal.example.com/opaqueid103
S: CMDID:xyz12346
S: RESPONSE-CODE:2.0
S: BEGIN:VEVENT
S: UID:0034848098038888989443
S: SUMMARY:meeting
S: DTEND:19990714T233000Z
S: DTSTART:19990714T223000Z
S: END:VEVENT
S: END:VCALENDAR
S:
S: ----FEE3790DC7E35189CA67CE2C
S: Content-type:text/calendar; Method=RESPONSE;
S: Optinfo=VERSION:2.1
S: Content-Transfer-Encoding: 7bit
S:
S: BEGIN:VCALENDAR
S: VERSION:2.1
Mansour/Dawson/Royer/Taler/Hill 82 Expires September 2000
Internet Draft CAP March 10, 2000
S: METHOD:RESPONSE
S: TARGET:cap://cal.example.com/opaqueid101
S: CMDID:xyz12346
S: RESPONSE-CODE:4.1 ; access denied
S: END:VCALENDAR
S:
S: ----FEE3790DC7E35189CA67CE2C
S: .
10.2.3. Timeouts
In this example bill@example.com attempts to read a calendar but the
latency time he supplies is not sufficient for the server to complete
the command.
C: SENDDATA 3
C: Content-type:text/calendar; Method=READ; Component=VQUERY
C:
C: BEGIN:VCALENDAR
C: VERSION:2.1
C: METHOD:READ
C: CMDID:xyz12346
C: TARGET:cap://cal.example.com/opaqueid101
C: TARGET:opaqueid103
C: BEGIN:VQUERY
C: QUERY:SELECT (DTSTART,DTEND,SUMMARY,UID);
C: FROM VEVENT;
C: WHERE (DTEND >= 19990714T080000Z AND
C: DTSTART <= 19990715T080000Z);
C: ORDERBY (DTSTART ASC, DTEND, UID, SUMMARY)
C: END:VQUERY
C: END:VCALENDAR
C: .
S: 7.0 ; timeout
S: .
S: .
If Bill wants to continue and give the server more time he would issue a
CONTINUE command:
C: CONTINUE 10
If Bill wants to abort the command and not wait any further he would
issue an ABORT command:
C: ABORT
S: 2.0
S: .
S: .
Mansour/Dawson/Royer/Taler/Hill 83 Expires September 2000
Internet Draft CAP March 10, 2000
10.2.4. Using the Calendar Parent, Children Properties
10.2.5. An example that depends on VEVENT.DTSTART and VALARM.DTSTART
11. Implementation Issues
1. What are the minimum component properties set required to create a
new VEVENT, VTODO and VJOURNAL?. PROPOSAL: DTSTART, SUMMARY and UID.
2. What is the state of all undefined properties? PROPOSAL: Not defined.
So a query will not return them, if they are selected.
12. Properties
[Editors Note: These extensions/changes to iCalendar need to be
reformatted to conform to the IANA registration process defined in
section 7 of [RFC2445].]
12.1. Calendar Store Properties
The following are properties of the calendar store.
Name Read Value Description
Only Type
--------------------------------------------------------------------------
CALMASTER N URI The email address for a responsable
person. MUST be a mailto URL.
CSID Y URI The CSID of this calendar store.
If not specified, it is the same as
the hostname or virtual host name.
DEFAULT_VCARS N TEXT A multivalued property containing
the default VCARs for newly created
top level calendars. Each entry is
a CARID It MUST include at a mini-
mum READBUSYTIMEINFO, REQUESTONLY,
UPDATEPARTSTATUS, and DEFAULTOWNER.
MAXDATE Y DATE-TIME The date/time in the future beyond
which the server cannot represent.
If not specified, then
99991231T235959 will be assumed.
Mansour/Dawson/Royer/Taler/Hill 84 Expires September 2000
Internet Draft CAP March 10, 2000
MINDATE Y DATE-TIME The date/time in the past prior to
which the server cannot represent.
If not specified, then
00000101T000000 will be assumed.
CURRENT_DATETIME Y DATE-TIME Current server time. This is re-
turned as a local time and TZID.
RECUR_ACCEPTED Y BOOLEAN Boolean value will be set to TRUE
if the server will accept recur-
rence 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 the
expansion of recurrence rules. If
set to FALSE, the CS is incapabale
of expanding recurrence rules. If
not specified a CUA MUST assume
TRUE.
RECUR_LIMIT Y INTEGER This numeric value describes how
the server handles unbounded recur-
rences. 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 inte-
ger indicating the number of in-
stances that will be created when
the server expands an unbounded re-
currence 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 default
and the only currently supported
version is "2.0" to match the
[RFC2445] VERSION.
[Editors Note: Can/MUST the server unzip RRULES/EXRULES?]
12.2. Calendar Properties
Mansour/Dawson/Royer/Taler/Hill 85 Expires September 2000
Internet Draft CAP March 10, 2000
Name Read Value Description
Only Type
-------------------------------------------------------------------------
ALLOW-CONFLICTS N BOOLEAN This boolean value indicates
whether or not the calendar sup-
ports 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 thie calendar. If
not specified the default is GREGO-
RIAN.
CHARSET N TEXT The default charset for localized
strings in this calendar. If not
specified, the default is UTF-8.
CHILDREN Y TEXT The list of sub-calendars belonging
to this calendar. An empty list
means no children. The results may
be a comma seperated list of chil-
dren. Each entry returned is a
CALID. The default is an empty
list.
CREATED Y DATE-TIME The timestamp of the calendar's
create date.
DEFAULT_VCAR N TEXT The default VCARs for newly created
top level calendars. This is a
CARID. The defalut value is the
value of DEFAULT_VCAR in the CAL-
STORE table.
T}
LANGUAGE N TEXT The default language for localiz-
able strings in this calendar.
There is no default.
LAST-MODIFIED N DATE-TIME The timestamp when the properties
of the calendar were last updated.
NAME N TEXT The display name for this calendar.
It is a localizable string. If not
provided, an empty value will be
returned.
Mansour/Dawson/Royer/Taler/Hill 86 Expires September 2000
Internet Draft CAP March 10, 2000
OWNERS N URI A multi instanced property indicat-
ing the calendar owner. Each entry
returned will be a UPN. There must
be at least one owner.
PARENT N URI The CALID of this calendars parent
maintained by a CAP server. An
empty value means the calendar is
the top level parent. The default
value is no parent.
RELCALID N URI A unique name for the calendar.
There is no default value and this
value MUST NOT be empty.
TOMBSTONE N BOOLEAN TRUE indicator that this calendar
has been marked as deleted. The
default value is FALSE.
TZID N TEXT The id of the timezone associated
with this calendar. See TZID in
[RFC2445]. The default value is
GMT.
13. Security Considerations
For the mandatory SASL mechanism that CAP specifies, the mechanism
support is:
? MUST authentication ? MUST authorization ? MAY impersonation
The security issue:
+---------+ +----------+
CUA1 ------ | CS1 |--------CAP----------| CS2 |-----CUA2
| calF | | calA |
+---------+ +----------+
14. Changes to iCalendar
[Editors Note: These extensions/changes to iCalendar need to be
reformatted to conform to the IANA registration process defined in
section 7 of [RFC2445].]
Mansour/Dawson/Royer/Taler/Hill 87 Expires September 2000
Internet Draft CAP March 10, 2000
14.1. Time Transparency
Property Name: TRANSP
Purpose: This property defines whether an event is transparent or not to
busy time searches.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be specified
on this property.
Conformance: This property can be specified once in a "VEVENT" calendar
component.
Description: Time Transparency is the characteristic of an event that
determines whether it appears to consume time on a calendar. Events 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 events, 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.
Format Definition: The property is specified by the following notation:
transp = "TRANSP" tranparam ":" transvalue CRLF
tranparam = *(";" xparam)
transvalue = "OPAQUE" ;Blocks or opaque on busy time searches.
/ "TRANSPARENT" ;Transparent on busy time searches.
/ "TRANSPARENT-NOCONFLICT" ; Transparent on busy time
; searches and no other OPAQUE
; or OPAQUE-NOCONFLICT event
; can overlap it.
/ "OPAQUE-NOCONFLICT" ; Opaque on busy time
; searches and no other OPAQUE
; or OPAQUE-NOCONFLICT event
; can overlap it.
;
;Default value is OPAQUE
Example: The following is an example of this property for an event that
is transparent or does not block on free/busy time searches:
TRANSP:TRANSPARENT
The following is an example of this property for an event that is opaque
or blocks on free/busy time searches:
Mansour/Dawson/Royer/Taler/Hill 88 Expires September 2000
Internet Draft CAP March 10, 2000
TRANSP:OPAQUE
The following is an example of this property for an event that is opaque
or blocks on free/busy time searches plus no other event can overlap it:
TRANSP:OPAQUE-NOCONFLICT
14.2. RIGHTS Value Type
Value Name: RIGHTS
Purpose: This value type is used to identify properties whose value is a
calendar access rights.
Formal Definition: The value type is defined by the following notation:
carrights = [princ] (carref / cardef) CRLF
princ = "UPN" "=" (text / all / "OWNER" / "NONOWNER" / "ANONYMOUS")
carref = ";" "CARREF" "=" text *("," text)
cardef = action object *("," action object)
action = ";" "ACTION" "=" act-type *("," act-type)
act-type = ("CREATE" / "MODIFY" / "DELETE" / "READ" / all)
object = ";" "OBJECT" "=" (csprop *("," csprop) [propvalue])
/ (calprop *("," calprop) [propvalue])
/ (component *("," component)) [compvalue]
/ (compprop *("," compprop) [propvalue])
/ (compparam *("," compparam) [paramvalue])
csprop = csprop2 / all / iana-name
csprop2 = <any calendar store property defined in [CAP]>
propvalue = propvalue2 / all / self / iana-name
propvalue2 = <any value appropriate for the named property>
calprop = calprop2 / all / iana-name
calprop2 = <any calendar property name defined in [RFC2445] or
[CAP]>
component = component2 / all / iana-name
component2 = <any calendar component defined in [RFC2445] or
[CAP]>
Mansour/Dawson/Royer/Taler/Hill 89 Expires September 2000
Internet Draft CAP March 10, 2000
compprop = compprop2 / all / iana-name
compprop2 = <any component property name defined in [RFC2445] or
[CAP]>
compparam = compparm2 / all / iana-name
compparm2 = <any component parameter name defined in [RFC2445] or
[CAP]>
compvalue = ";" "VALUE" "=" ((component2 *("," component2))
/ all / iana-name)
paramvalue = paramvalue2 / all / iana-name
paramvalue2 = <any value appropriate for the named parameter>
all = "*"
self = "SELF" ; Only valid for ATTENDEE value.
; When OBJECT=ATTENDEE;VALUE=SELF.
iana-name = <A name registered with IANA>
Description: The value type is a structured value consisting of a list
of one or more access control rights rule parts. Each rule part is
defined by a "NAME=VALUE" pair. The rule parts are separated from each
other by the SEMICOLON character (US-ASCII decimal 59). The rule parts
are not ordered in any particular sequence, unless otherwise specified
by the ABNF.
Within one carrights all matches of multiple OBJECT and VALUE pairs must
be true for the GRANT or DENY to apply.
The UPN rule part specifies the CU or UG to which the VCARs applies.
The value of this rule part is either a quoted text specifying a UPN or
an unquoted text specifying a keyword enumerating a standard
authenticated user type. If the value is the keyword is *, then the rule
applies to all authenticated calendar users (i.e., all UPNs). If the
value is the keyword OWNER, then the rule applies to any of the owners
of the calendar store or calendar. If the value is the keyword NONOWNER,
then the rule applies to a UPN that is not the owner of the calendar
store or calendar. If this rule part is not specified in the value, then
the calendar access rights do not apply to any UPN. In this case, the
calendar access rights can be defined for reference by another instance
of a calendar access rights. For example, a complex set of calendar
access rights can be defined once and referenced many times in the
rights specified for individual calendar users.
The CARREF rule part specifies a reference to a particular "VCAR"
calendar component. The text is matched to a CARID property value within
a "VCAR" calendar component. This allows for a particular set of
calendar access rights to be defined once and referenced multiple times.
Mansour/Dawson/Royer/Taler/Hill 90 Expires September 2000
Internet Draft CAP March 10, 2000
The "VCAR" identifier specified by this rule part is unique to the
calendar store.
Predefined calendar access CARIDs that MUST be implememnetd (CAR-MIN)
are:
CARID:READBUSYTIMEINFO - Specifies rights for reading VFREEBUSY
components by anonymous and known users. Suggested VCAR to allow all
users to read VFREEBUSY components:
BEGIN:VCAR
CARID:READBUSYTIMEINFO
GRANT:UPN=*;ACTION=READ;OBJECTS=VFREEBUSY;VALUE=*
END:VCAR
CARID:REQUESTONLY - Specifies rights for creating new event
invitations, to-do assignments and journal entries by users other
than the owner of the calendar. Suggested VCAR to allow access by
nonowners to submit REQUESTs:
BEGIN:VCAR
CARID:REQUESTONLY
GRANT:UPN=NONOWNER;ACTION=CREATE;OBJECT=*
;OBJECT=METHOD;VALUE=REQUEST
END:VCAR
CARID:UPDATEPARTSTATUS - Specifies rights for a user to modify their
participation status in a calendar they do not own. Suggested VCAR
to allow users to update their own participation status:
BEGIN:VCAR
CARID:UPDATEPARTSTATUS
GRANT:UPN=*;ACTION=MODIFY
;OBECT=PARTSTAT:VALUE=*
;OBJECT=ATTENDEE;VALUE=SELF
END:VCAR
CARID:DEFAULTOWNER - Specifies the default access for any owner of a
calendar. Suggested VCAR to all owners access to their own
calendars:
BEGIN:VCAR
CARID:DEFAULTOWNER
GRANT:UPN=OWNER;ACTION=*;OBJECT=*;VALUE=*;
END:VCAR
The ACTION rule part defines one or more CAP actions that are allowed
for the UPN. The valid values are CREATE, COPY, DELETE, MODIFY, MOVE,
READ, corresponding to the calendar commands; PUBLISH, REQUEST, REPLY,
ADD, CANCEL, REFRESH, COUNTER, DECLINECOUNTER, corresponding to the
scheduling commands; and ALL, meaning all of calendaring commands and
scheduling commands. Multiple ACTION enumerations can be specified as a
COMMA character (US-ASCII decimal 44) separated list of ACTION
Mansour/Dawson/Royer/Taler/Hill 91 Expires September 2000
Internet Draft CAP March 10, 2000
enumerated values. The text ALL is the same as specifying the enumerated
values "CREATE, MODIFY, DELETE, READ".
The OBJECT rule part defines the calendar store property, calendar
property, calendar component, component property, or parameter that the
ACTION is restricted to. Multiple OBJECT enumerations can be specified
as a COMMA character (US-ASCII decimal 44) separated list of OBJECT
enumerated values. The value ALL specifies any and all valid objects.
The VALUE rule part specifies the restricted values for the OBJECT rule
part. Multiple VALUE strings can be specified as a COMMA character (US-
ASCII decimal 44) separated list of VALUE strings. The text ALL
specifies any and all valid values. If an OBJECT rule part is specified
but no corresponding VALUE rule part is specified, then the rule applies
to any and all valid values of the specified OBJECT(s).
Example: The following is a rule which specifies access rights for "foo"
calendar user to read busy time values:
UPN="foo@host.com";ACTION=READ;OBJECT=DTSTART,DTEND
14.3. VCAR Calendar Component
Component Name: "VCAR"
Purpose: Provide a grouping of calendar access rights.
Format Definition: A "VCAR" calendar component is defined by the
following notation:
aclc = "BEGIN" ":" "VCAR" CRLF
carprop
"END" ":" "VCAR" CRLF
carprop = carid 1*(grant / deny)
Description: A "VCAR" calendar component is a grouping of calendar
access rights component properties.
The "CARID" property specifies the local identifier for the "VCAR"
calendar component. The "GRANT" property specifies calendar access
rights granted to an UPN. The "DENY" property specifies calendar access
rights denied from an UPN.
Example: In the following example, the UPN "foo@host.com" has read
access to the "DTSTART" and "DTEND" calendar properties. No other access
is specified:
BEGIN:VCAR
CARID:"View Start and End Times"
GRANT:UPN=foo@host.com;ACTION="READ";OBJECT=DTSTART,DTEND
END:VEVENT
Mansour/Dawson/Royer/Taler/Hill 92 Expires September 2000
Internet Draft CAP March 10, 2000
In this example, all UPNs are given read access to "DTSTART" and
"DTEND". "All CUs and UGs" are specified by the UPN value "*". Note
that this enumerated UPN value is not in quotes.:
BEGIN:VCAR
CARID:"View Start and End Times 2"
GRANT:UPN=*;ACTION=READ;OBJECT=DTSTART,DTEND
END:VCAR
In this example, rights are specified for all UPNs to read components
classified as PUBLIC:
BEGIN:VCAR
CARID:"View PUBLIC Start and End Times"
GRANT:UPN=*;ACTION=READ;OBJECT=DTSTART;DTEND
DENY:UPN=*;ACTION=READ;OBJECT=CLASS;VALUE=PUBLIC,
CONFIDENTIAL
END:VCAR
In this example, rights are specified for all UPNs to read or modify
existing components classified as PUBLIC:
BEGIN:VCAR
CARID:"Read and Modify PUBLIC Calendar Entries"
GRANT:UPN=*;ACTION=READ,MODIFY;OBJECT=*
DENY:UPN=*;ACTION=READ,MODIFY;OBJECT=CLASS;VALUE=PRIVATE,
CONFIDENTIAL
END:VCAR
In this example, full calendar access rights are given to the OWNER and
a hypothetical administrator is given access rights to specify calendar
access rights. If no other rights are specified, only these two UPNs can
specify calendar access rights:
BEGIN:VCAR
CARID:"Only OWNER or ADMIN Settable CARs"
GRANT:UPN=OWNER;ACTION=*;OBJECT=*
GRANT:UPN=cal-admin@host.com;ACTION=*;
OBJECT=VCAR,CARID,GRANT,DENY
END:VCAR
In this example, rights to create, read, modify or delete calendar
access rights are denied to all UPNs. This example would disable
providing different access rights to the calendar store or calendar.
This calendar access rights should not be specified, as they the ability
to change calendar access; even for the owner or administrator:
BEGIN:VCAR
CARID:"No CAR At All"
DENY:UPN=*;OBJECT=VCAR,CARID,GRANT,DENY
ENG:VCAR
Mansour/Dawson/Royer/Taler/Hill 93 Expires September 2000
Internet Draft CAP March 10, 2000
14.4. GRANT Component Property
Property Name: GRANT
Purpose: This property specifies those access rights granted to a UPN.
Value Type: RIGHTS
Property Parameters: Only non-standard property parameters can be
specified on this property.
Conformance: This property can only be specified in "VCAR" calendar
component.
Description: This property is used to grant calendar access rights to a
UPN.
Format Definition: The property is defined by the following notation:
grant = "GRANT" rightsparam ":" carrights CRLF
rightsparam = *(";" xparam)
14.5. DENY Component Property
Property Name: DENY
Purpose: This property specifies those access rights denied from a UPN.
Value Type: RIGHTS
Property Parameters: Only non-standard property parameters can be
specified on this property.
Conformance: This property can only be specified in "VCAR" calendar
component.
Description: This property is used to deny calendar access rights to a
UPN.
Format Definition: The property is defined by the following notation:
DENY = "DENY" rightsparam ":" carrights CRLF
rightsparam = *(";" xparam)
Example: In the following example, any UPN who is not the owner is
denied rights to create, modify or delete entries:
DENY:UPN=NONOWNER;ACTION=CREATE,MODIFY,DELETE;OBJECT=*
Mansour/Dawson/Royer/Taler/Hill 94 Expires September 2000
Internet Draft CAP March 10, 2000
14.6. VCAR Identifier Component Property
Property Name: CARID
Purpose: This property specifies the identifier for a "VCAR" calendar
component.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be specified
on this property.
Conformance: This property can be specified in "VCAR" calendar
component.
Description: This property permits previously defined sets of calendar
access rights to be specified with a reference. This capability
facilitates repetitively specifying calendar access rights.
Format Definition: The property is defined by the following notation:
CARID = "CARID" textparam ":" text CRLF
Example: The following is an example of this property:
CARID:"Restrict Guests From Creating ALARMs On Events"
14.8 REQUEST-STATUS property
This description is a revision of the REQUEST-STATUS property for
VCALENDAR version 2.1.
rstatus = "REQUEST-STATUS" rstatparam ":"
statcode [";" statdesc [";" extdata]]
rstatparam = *(
; the following is optional,
; but MUST NOT occur more than once
(";" languageparm) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)
statcode = 1*DIGIT *("." 1*DIGIT)
;Hierarchical, numeric return status code
statdesc = text
Mansour/Dawson/Royer/Taler/Hill 95 Expires September 2000
Internet Draft CAP March 10, 2000
;An optional textual status description, content is
;decided by the implementor. May be empty.
extdata = text
;Textual exception data. For example, the offending property
;name and value or complete property line.
Example: The following are some possible examples of this property. The
COMMA and SEMICOLON separator characters in the property value are
BACKSLASH character escaped because they appear in a text value.
REQUEST-STATUS:2.0;Success
REQUEST-STATUS:2.0;Success despite braindead LDAP implementation
REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01
REQUEST-STATUS:2.8; Success, repeating event ignored. Scheduled
as a single event.;RRULE:FREQ=WEEKLY;INTERVAL=2
REQUEST-STATUS:4.1;Event conflict. Date/time is busy.
REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE:
MAILTO:jsmith@host.com
REQUEST-STATUS:3.7;;ATTENDEE:MAILTO:jsmith@host.com
REQUEST-STATUS:10.4;Help! That really shouldnt have happened.
15. CAP Entities Registration
This section provides the process for registration of new or modified
CAP entities.
15.1 Registration of New and Modified CAP Entities New CAP entities are
registered by the publication of an IETF Request for Comment (RFC).
Changes to a CAP entity are registered by the publication of a revision
of the RFC defining the method.
15.2 Registration of New Entities
This section defines procedures by which new entities (i.e., components,
properties, parameters, enumerated values or restriction tables) for a
CAP entity can be registered with the IANA.
Non-standard, experimental entities can be used by bilateral agreement,
provided the associated properties names follow the "X-" convention.
Such non-standard entities are non-IANA entities and need not be
registered using this process.
The procedures defined here are designed to allow public comment and
Mansour/Dawson/Royer/Taler/Hill 96 Expires September 2000
Internet Draft CAP March 10, 2000
review of new CAP entities, while posing only a small impediment to the
definition of new properties.
Registration of a new CAP entity is accomplished by the following steps.
15.1.1. Define the Entity
A CAP entity is defined by completing the following template.
To: ietf-calendar@imc.org
Subject: Registration of CAP entity XXX
Entity name:
Entity purpose:
Description:
CAP terminology changes:
CAP data model changes:
CAP system model changes:
Conformance considerations:
Format definition:
Examples:
The meaning of each field in the template is as follows.
Entity name: The name of the entity.
Entity purpose: The purpose of the entity (e.g., Extends the CAP command
set to poll for notifications, etc.). Give a short but clear
description.
Description: Any special notes about the entity, how it is to be used,
etc.
CAP terminology changes: Any change or additions to the existing CAP
terminology needs to be specified.
CAP data model changes: Any of the valid property parameters for the
property needs to be specified.
CAP system model changes:
Conformance: A clear summary of how and where this CAP entity extension
MUST, MAY, SHOULD or can be used. Any changes or impact to the existing
conformance definition for CAP should be explained. The impact to
implementations conforming to the existing CAP specification should be
clearly described.
Format definition: The ABNF for each element of the CAP entity needs to
be specified.
Examples: One or more examples of instances of the CAP entity and each
of its usage scenarios needs to be specified.
Mansour/Dawson/Royer/Taler/Hill 97 Expires September 2000
Internet Draft CAP March 10, 2000
15.1.2. Post the entity definition
The entity description MUST be posted to the new entity discussion list,
ietf-calendar@imc.org.
15.1.3. Allow a comment period
Discussion on the new entity MUST be allowed to take place on the list
for a minimum of two weeks. Consensus MUST be reached on the property
before proceeding to the next step.
15.1.4. Submit the entity for approval
Once the two-week comment period has elapsed, and the proposer is
convinced consensus has been reached on the entity, the registration
application should be submitted to the Method Reviewer for approval.
The Method Reviewer is appointed by the Application Area Directors and
can either accept or reject the entity registration. An accepted
registration should be passed on by the Method Reviewer to the IANA for
inclusion in the official IANA method registry. The registration can be
rejected for any of the following reasons. 1) Insufficient comment
period; 2) Consensus not reached; 3) Technical deficiencies raised on
the list or elsewhere have not been addressed. The Method Reviewers
decision to reject an entity can be appealed by the proposer to the
IESG, or the objections raised can be addressed by the proposer and the
entity resubmitted.
[Ed note: John Stracke to review any updates]
15.2. Property Change Control
Existing CAP entities can be changed using the same process by which
they were registered.
1. Define the change 2. Post the change 3. Allow a comment period 4.
Submit the entity for approval
Note that the original author or any other interested party can propose
a change to an existing CAP entity, but that such changes should only be
proposed when there are serious omissions or errors in the published
memo. The Method Reviewer can object to a change if it is not backward
compatible, but is not required to do so.
CAP entity definitions can never be deleted from the IANA registry, but
entities which are no longer believed to be useful can be declared
OBSOLETE by adding this text to their "Entity purpose" field.
Mansour/Dawson/Royer/Taler/Hill 98 Expires September 2000
Internet Draft CAP March 10, 2000
16. IANA Considerations
This memo defines IANA registered extensions to the attributes defined
by iCalendar, as defined in [RFC2445], and iTIP, as defined in
[RFC2426].
IANA registration proposals for iCalendar and iTIP are to be mailed to
the registration agent for the "text/calendar" MIME content-type,
<MAILTO: ietf-calendar@imc.org> using the format defined in section 7 of
[RFC2445].
17. Acknowledgments
The following have individuals were major contributors in the drafting
and discussion of this memo:
Harald Alvestrand, Mario Bonin, Andre Courtemanche, Dave Crocker, Pat
Egen, Gilles Fortin, Jeff Hodges, Alex Hoppman, Bruce Kahn, Lisa
Lippert, David Madeo, Bob Mahoney, Bob Morgan, Pete O'Leary, Richard
Shusterman, Tony Small, John Stracke, Mark Wahl.
18. Bibliography
[RFC1521] N. Borenstein and N. Freed, "MIME (Multipurpose Internet Mail
Extensions) Part One: Mechanisms for Internet Draft UTF-825 July 1996
Specifying and Describing the Format of Internet Message Bodies", RFC
1521, Bellcore, Innosoft, September 1993.
[TLS] Dierks, Allen, "The TLS Protocol", RFC 2246, January 1999
[RFC2608] Guttman, Perkins, Veizades, Day, "Service Location protocol,
Version 2", RFC2608, June 1999.
[RFC2609] Guttman, Perkins, Kempf, "Service Templates and Service:
Schemes", RFC2609, June 1999.
[RFC2396] Berners-Lee, Fielding, Masinter, "Uniform Resource Identifiers
(URI): Generic Syntax", RFC 2396, August 1998.
[RFC2445] Dawson, Stenerson, "Internet Calendaring and Scheduling Core
Object Specification (iCalendar)", RFC 2445, November 1998
[RFC2446] Silverberg, Mansour, Dawson, Hopson, "iCalendar Transport-
Independent Interoperability Protocol (iTIP)", RFC 2446, November 1998
[RFC2447] Dawson, Mansour, Silverberg, "iCalendar Message-Based
Interoperability Protocol (iMIP)", RFC 2445, November 1998
[SQL] "Database Language SQL", ANSI/ISO/IEC 9075: 1992, aka ANSI
X3.135-1992, aka FiPS PUB 127-2
Mansour/Dawson/Royer/Taler/Hill 99 Expires September 2000
Internet Draft CAP March 10, 2000
[SQLCOM] ANSI/ISO/IEC 9075:1992/TC-1-1995, Technical corrigendum 1 to
ISO/IEC 9075: 1992, also adopted as Amendment 1 to ANSI X3.135.1992
[UNICODE] The Unicode Consortium, "The Unicode Standard --Worldwide
Character Encoding -- Version 1.0", Addison-Wesley, Volume 1, 1991,
Volume 2, 1992. UTF-8 is described in Unicode Technical Report #4.
[US-ASCII] Coded Character Set--7-bit American Standard Code for
Information Interchange, ANSI X3.4-1986.
19. Author's Address
The following address information is provided in a vCard v3.0, the RFC
2426 electronic business card format.
BEGIN:VCARD
VERSION:3.0
N:Dawson;Frank
FN:Frank Dawson
ORG:Lotus Development Corporation
ADR;TYPE=WORK,POSTAL,PARCEL:;;6544 Battleford Drive;Raleigh;NC;
27613-3502;US
TEL;TYPE=PREF,WORK,MSG:+1-617-693-8728
TEL;TYPE=WORK,MSG:+1-919-676-9515
TEL;TYPE=WORK,FAX:+1-919-676-9515
EMAIL;TYPE=INTERNET,PREF:Frank_Dawson@Lotus.com
EMAIL;TYPE=INTERNET:fdawson@earthlink.net
URL;TYPE=X-HOME:http://home.earthlink.net/~fdawson
END:VCARD
BEGIN:VCARD
VERSION:3.0
N:Mansour;Steve
FN:Steve Mansour
ORG:Netscape
ADR;TYPE=WORK,POSTAL,PARCEL:;;501 E Middlfield Road;Mountain
View;CA;94043;US
TEL;WORK;MSG:+1-650-937-2378
TEL;WORK;FAX:+1-650-937-2103
EMAIL;INTERNET:sman@netscape.com
END:VCARD
BEGIN:VCARD
VERSION: 3.0
FN:Doug Royer
N:Royer,Doug
ORG:Software.com
ADR;TYPE=WORK,POSTAL,PARCEL:Suite 106;;530 E. Montecito St;
Santa Barbara;CA;93103;US
TEL;TYPE=PREF,WORK,MSG:805-957-1790 x541
TEL;TYPE=WORK,MSG:650-364-6538
TEL;TYPE=WORK,FAX:805-957-1544
EMAIL;TYPE=INTERNET,PREF:Doug.Royer@Software.com
Mansour/Dawson/Royer/Taler/Hill 100 Expires September 2000
Internet Draft CAP March 10, 2000
EMAIL;TYPE=INTERNET:Doug@Royer.com
URL;TYPE=X-HOME:http://Royer.com/People/Doug
END:VCARD
BEGIN:VCARD
VERSION:3.0
FN:Alexander Taler
N:Taler;Alexander
ORG:CS&T
ADR;TYPE=WORK,POSTAL,PARCEL:;;3333 Graham Boulevard;Montreal;QC;
H3R 3L5;Canada
TEL;TYPE=WORK,VOICE:514-733-8500
TEL;TYPE=FAX:514-733-8878
EMAIL;TYPE=INTERNET:alext@cst.ca
END:VCARD
20. Full Copyright Statement
"Copyright (C) The Internet Society (2000). All Rights Reserved. This
document and translations of it may be copied and furnished to others,
and derivative works that comment on or otherwise explain it or assist
in its implementation may be prepared, copied, published and
distributed, in whole or in part, without restriction of any kind,
provided that the above copyright notice and this paragraph are included
on all such copies and derivative works. However, this document itself
may not be modified in any way, such as by removing the copyright notice
or references to the Internet Society or other Internet organizations,
except as needed for the purpose of developing Internet standards in
which case the procedures for copyrights defined in the Internet
Standards process MUST be followed, or as required to translate it into
languages other than English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns. This
document and the information contained herein is provided on an "AS IS"
basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE
DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE
ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE.
Mansour/Dawson/Royer/Taler/Hill 101 Expires September 2000