Network Working Group C. Daboo
Internet-Draft Apple
Intended status: Standards Track July 6, 2009
Expires: January 7, 2010
VALARM Extensions for iCalendar
draft-daboo-valarm-extensions-00
Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79.
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.
This Internet-Draft will expire on January 7, 2010.
Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document.
Abstract
This document defines a set of extensions to the iCalendar VALARM
component to enhance use of alarms and improve interoperability
between clients and servers.
Daboo Expires January 7, 2010 [Page 1]
Internet-Draft VALARM Extensions July 2009
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. Extensible syntax for VALARM . . . . . . . . . . . . . . . . . 3
4. VALARM Unique Identifier . . . . . . . . . . . . . . . . . . . 5
5. VALARM URI Action . . . . . . . . . . . . . . . . . . . . . . 6
6. VALARM Agent Property . . . . . . . . . . . . . . . . . . . . 7
6.1. Alarm Agent Property . . . . . . . . . . . . . . . . . . . 7
6.2. URI Property Parameter . . . . . . . . . . . . . . . . . . 8
7. VALARM Status Property . . . . . . . . . . . . . . . . . . . . 9
7.1. Last Triggered Property . . . . . . . . . . . . . . . . . 10
7.2. Snooze Until Property . . . . . . . . . . . . . . . . . . 11
8. VALARM Included by Reference . . . . . . . . . . . . . . . . . 12
8.1. Unique Identifier Reference Property . . . . . . . . . . . 13
9. Default Alarms in CalDAV . . . . . . . . . . . . . . . . . . . 13
10. Security Considerations . . . . . . . . . . . . . . . . . . . 13
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14
13.1. Normative References . . . . . . . . . . . . . . . . . . . 14
13.2. Informative References . . . . . . . . . . . . . . . . . . 14
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14
Daboo Expires January 7, 2010 [Page 2]
Internet-Draft VALARM Extensions July 2009
1. Introduction
The iCalendar [I-D.ietf-calsify-rfc2445bis] specification defines a
set of components used to describe calendar data. One of those is
the "VALARM" component which appears as a sub-component of "VEVENT"
and "VTODO" components. The "VALARM" component is used to specify a
reminder for an event or to-do. Different alarm actions are possible
as are different ways to specify how the alarm is triggered.
As iCalendar has become more widely used and as client-server
protocols such as CalDAV [RFC4791] have become more popular, several
issues with "VALARM" components have arisen. Most of these relate to
the need to extend the existing "VALARM" component with new
properties and behaviors to allow clients and servers to accomplish
specific tasks in an interoperable manner. For example, clients
typically need a way to specify that an alarm has been dismissed by a
calendar user, or has been "snoozed" by a set amount of time. To
date, this has been done through the use of custom "X-" properties
specific to each client implementation, leading to poor
interoperability.
This specification defines a set of extensions to "VALARM" components
to cover common requirements for alarms not currently addressed in
iCalendar. Each extension is defined in a separate section below.
For the most part, each extension can be supported independently of
the others, though in some cases one extension will require another.
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[RFC2119].
When XML element types in the namespaces "DAV:" and
"urn:ietf:params:xml:ns:caldav" are referenced in this document
outside of the context of an XML fragment, the string "DAV:" and
"CALDAV:" will be prefixed to the element type names respectively.
3. Extensible syntax for VALARM
Section 3.6.6 of [I-D.ietf-calsify-rfc2445bis] defines the syntax for
"VALARM" components and properties within them. However, as written,
it is hard to extend this by adding, e.g., a new property common to
all types of alarm. Since many of the extensions defined in this
document need to extend the base syntax, an alternative form for the
Daboo Expires January 7, 2010 [Page 3]
Internet-Draft VALARM Extensions July 2009
base syntax is defined here, with the goal of simplifying
specification of the extensions.
A "VALARM" calendar component is re-defined by the following
notation:
alarmcext = "BEGIN" ":" "VALARM" CRLF
alarmprop
"END" ":" "VALARM" CRLF
alarmprop = *(
; the following are REQUIRED,
; but MUST NOT occur more than once
action / trigger /
; one set of action properties MUST be
; present and MUST match the action specified
; in the ACTION property
actionprops /
; the following is OPTIONAL,
; and MAY occur more than once
x-prop / iana-prop
)
actionprops = audiopropext / disppropext / emailpropext
audiopropext = *(
; 'duration' and 'repeat' are both OPTIONAL,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat /
; the following is OPTIONAL,
; but MUST NOT occur more than once
attach
)
disppropext = *(
Daboo Expires January 7, 2010 [Page 4]
Internet-Draft VALARM Extensions July 2009
; the following are REQUIRED,
; but MUST NOT occur more than once
description /
; 'duration' and 'repeat' are both OPTIONAL,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat
)
emailpropext = *(
; the following are all REQUIRED,
; but MUST NOT occur more than once
description / summary /
; the following is REQUIRED,
; and MAY occur more than once
attendee /
; 'duration' and 'repeat' are both OPTIONAL,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat
)
4. VALARM Unique Identifier
Several of the other extensions in this specification require
identifying a specific instance of a "VALARM" component in an
iCalendar stream. To aid that, this extension adds a "UID" property
to "VALARM" components to allow a unique identifier to specified.
The value of this unique identifier can then be used to refer
uniquely to the "VALARM" component.
The "UID" property defined here follows the definition in Section
3.8.4.7 of [I-D.ietf-calsify-rfc2445bis]. In particular it MUST be a
globally unique identifier.
Daboo Expires January 7, 2010 [Page 5]
Internet-Draft VALARM Extensions July 2009
The "VALARM" component defined in Section 3 is extended here as:
alarmprop /= *(
; the following is OPTIONAL,
; but MUST NOT occur more than once
uid
)
5. VALARM URI Action
Currently "VALARM" components have actions for audio, display and
email. New types of action are of interest, e.g., SMS, instant
messaging, etc. Rather then specify separate actions for these, an
alternative is to define a "URI" action that allows any URI scheme to
be used as an action, where it makes sense. Thus URI schemes for IM
[RFC3860], SIP [RFC3261], TEL [RFC3966] etc could be used.
This extension defines a new "URI" property value for use with the
"ACTION" property in "VALARM" components. A new set of action
properties is defined for "VALARM" components based on this new
action as defined by the syntax below.
actionvalue /= "URI"
; Adds a new action for a "VALARM"
actionprop /= uriprop
; Re-defines the "VALARM" component to include
; "uriprop" as a new set of action properties
uriprop = *(
; the following are REQUIRED,
; but MUST NOT occur more than once
description / uri /
; 'duration' and 'repeat' are both OPTIONAL,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat
)
Daboo Expires January 7, 2010 [Page 6]
Internet-Draft VALARM Extensions July 2009
6. VALARM Agent Property
With the advent of a standard client/server protocol for calendaring
and scheduling data ([RFC4791]) there is a need to specify which
client or server should handle the presentation of an alarm when it
is triggered. For example, calendar users want to be able to receive
alarms at all times, even when their desktop client might be
unavailable. Since the server is "always on", a service running on
the server could monitor alarm status and when appropriate trigger
those alarms. In addition it may be important for only the server or
the client to be set to handle an alarm - and in some cases only
specific servers or clients.
To address this need, this specification defines an "ALARM-AGENT"
iCalendar property that can be added to any "VALARM" component. This
property specifies whether a client or server or both should be
responsible for processing the alarm when it triggers. In addition,
a "URI" property parameter can be added to uniquely identify the
client or server that should process the alarm. This is defined by
the syntax below.
alarmprop /= *(
; the following is OPTIONAL,
; and MAY occur more than once
alarm-agent
)
6.1. Alarm Agent Property
Property Name: ALARM-AGENT
Purpose: This property specifies whether a client, server, both or
none gets to process an alarm when it is triggered.
Value Type: TEXT
Property Parameters: IANA, non-standard, and URI property parameters
can be specified on this property.
Conformance: This property can be specified within "VALARM" calendar
components.
Daboo Expires January 7, 2010 [Page 7]
Internet-Draft VALARM Extensions July 2009
Description: This property is used to specify who is responsible for
processing an alarm when it is triggered. When the value "SERVER"
is specified, only a server that has a copy of the event is
responsible. When the value "CLIENT" is specified, only a client
that has a copy of the event is responsible. When the value
"BOTH" is specified, either a client or server is responsible.
When the value "NONE" is specified, neither a client nor server is
responsible (i.e. the alarm action is never carried out when it
triggers). If the "URI" property parameter is specified for
"SERVER" or "CLIENT" values, then only the client or server
identified by the "URI" value is responsible. Clients or servers
that are not responsible for the alarm SHOULD NOT process the
alarm action when it is triggered.
Format Definition: This property is defined by the following
notation:
alarm-agent = "ALARM-AGENT" alarmagentparam ":"
alarmagentvalue CRLF
alarmagentparam = *(
; the following is OPTIONAL,
; but MUST NOT occur more than once
(";" uriparam) /
; the following is OPTIONAL,
; and MAY occur more than once
(";" other-param)
)
alarmagentvalue = "SERVER" / "CLIENT" / "BOTH" / "NONE"
/ iana-token / x-name
Example: The following is an example of this property:
ALARM-AGENT:SERVER
6.2. URI Property Parameter
Property Name: URI
Daboo Expires January 7, 2010 [Page 8]
Internet-Draft VALARM Extensions July 2009
Purpose: This property parameter specifies a URI that is related to
the property it is applied to.
Format Definition: This property is defined by the following
notation:
uriparam = "URI" "=" DQUOTE uri DQUOTE
Description: This property parameter is used to specify a URI that
is associated with the property it is applied to. Each property
that allows this parameter to be specified MUST indicate what the
value of the URI represents.
Example: The following is an example of this property:
ALARM-AGENT;URI="http://calendar.example.com":SERVER
7. VALARM Status Property
There is currently no way for a "VALARM" component to indicate the
status of the alarm (e.g., whether it has been triggered or not).
With the advent of a standard client/server protocol for calendaring
and scheduling data ([RFC4791]) it is quite possible for an event
with an alarm to exist on multiple clients in addition to the server.
If each of those is responsible for performing the action when an
alarm triggers then multiple "alerts" are generated by different
devices. In a such a situation a calendar user would like to be able
to "dismiss" the alarm on one device and have it dismissed on the
others too.
In addition, calendar user agents often provide a way for calendar
users to "snooze" an alarm (temporarily dismiss it but have it re-
scheduled to trigger again a short while later). However, there is
no way for a "VALARM" component to indicate that it has been snoozed
and for how long.
Finally, with recurring events that have alarms, it is important to
know when the last alarm in the recurring set was triggered, so that
the client can determine whether any and how many past alarms have
been missed.
To address these needs, this specification adds the following:
o a "STATUS" property to "VALARM" components with values to indicate
wether an alarm is active, inactive, completed (dismissed) or
snoozed.
Daboo Expires January 7, 2010 [Page 9]
Internet-Draft VALARM Extensions July 2009
o a "LAST-TRIGGERED" property to "VALARM" components to indicate
when the alarm was last triggered.
o a "SNOOZE-UNTIL" property to "VALARM" components to indicate when
to trigger an alarm after it has been "snoozed".
This is defined by the syntax below.
alarmprop /= *(
; the following are OPTIONAL,
; but MUST NOT occur more than once
status / last-triggered / snooze-until
)
statvalue /= statvalue-alarm
statvalue-alarm = "ACTIVE" ; Indicates alarm is active and
; waiting to be triggered.
/ "CANCELLED" ; Indicates alarm is inactive
; and won't be triggered.
/ "COMPLETED" ; Indicates alarm has triggered
; and been dismissed.
/ "SNOOZED" ; Indicates alarm has triggered
; and been snoozed.
; Status values for a "VALARM"
7.1. Last Triggered Property
Property Name: LAST-TRIGGERED
Purpose: This property specifies the UTC date and time at which the
corresponding alarm was last triggered.
Value Type: DATE-TIME
Property Parameters: IANA and non-standard property parameters can
be specified on this property.
Conformance: This property can be specified within "VALARM" calendar
components.
Daboo Expires January 7, 2010 [Page 10]
Internet-Draft VALARM Extensions July 2009
Description: This property is used to specify when an alarm was last
triggered. This allows clients to track repeating alarms or
alarms on recurring events or to-dos to ensure that the right
number of missed alarms can be tracked.
Format Definition: This property is defined by the following
notation:
last-triggered = "LAST-TRIGGERED" lasttrigparam ":" datetime CRLF
lasttrigparam = *(
; the following is OPTIONAL,
; and MAY occur more than once
(";" other-param)
)
Example: The following is an example of this property:
LAST-TRIGGERED:20090604T084500Z
7.2. Snooze Until Property
Property Name: SNOOZE-UNTIL
Purpose: This property specifies the UTC date and time at which the
corresponding alarm is to be re-triggered after being "snoozed".
Value Type: DATE-TIME
Property Parameters: IANA and non-standard property parameters can
be specified on this property.
Conformance: This property can be specified within "VALARM" calendar
components.
Description: This property is used to specify when an alarm is
expected to be re-triggered following a "snooze" operation by a
calendar user.
Format Definition: This property is defined by the following
notation:
Daboo Expires January 7, 2010 [Page 11]
Internet-Draft VALARM Extensions July 2009
snooze-until = "SNOOZE-UNTIL" snoozeuntilparam ":"
datetime CRLF
snoozeuntilparam = *(
; the following is OPTIONAL,
; and MAY occur more than once
(";" other-param)
)
Example: The following is an example of this property:
SNOOZE-UNTIL:20090604T085000Z
8. VALARM Included by Reference
In some situations a calendar user might wish to define an alarm to
be used on multiple events or to-dos. This would allow a change to
one alarm to effect the alarms for multiple events or to-dos without
having to modify each "VALARM" component in each event or to-do. One
use for this is for setting up a "default" alarm for a calendar user
- one that gets applied to all new events or to-dos added to the
user's calendar.
TODO: need more text on how properties are "inherited" and
"overridden".
This extension defines a "UID-REFERENCE" property for use with
"VALARM" components. The value of this property is the unique
identifier ("UID" property value) of another "VALARM" component. The
"UID-REFERENCE" property is used in place of normal "VALARM" action
properties as defined by the syntax below.
alarmprop /= *(
; the following is OPTIONAL,
; but MUST NOT occur more than once
uid-ref
)
Daboo Expires January 7, 2010 [Page 12]
Internet-Draft VALARM Extensions July 2009
8.1. Unique Identifier Reference Property
Property Name: UID-REFERENCE
Purpose: This property specifies a reference to another component.
Value Type: TEXT
Property Parameters: Non-standard property parameters can be
specified on this property.
Conformance: This property can be specified within "VALARM" calendar
components.
Format Definition: This property is defined by the following
notation:
uid-ref = "UID-REFERENCE" uidrefparam ":" text CRLF
uidrefparam = *(";" other-param)
Description: This property is used to specify a reference to an
iCalendar "VALARM" component. Its value is equal to the value of
the "UID" property in the component being referenced. When
present in a "VALARM" component, all the properties from the
referenced "VALARM" are applied to the referring component, except
for those that have counter-parts in the referring component. For
example, a "SUMMARY" property defined in a referenced component
can be overridden by a "SUMMARY" in the referring component.
Also, per-instance copies of some properties are required, such as
"LAST-TRIGGERED" and "SNOOZE-UNTIL".
Example: The following is an example of this property:
UID-REFERENCE:19960401T080045Z-4000F192713-0052@example.com
9. Default Alarms in CalDAV
TODO: specify how default alarms for different types of component and
for timed/all-day can be set in WebDAV properties and then referenced
in calendar data, and automatically applied by the server to new
events and new invites.
10. Security Considerations
TODO:talk about importance of stripping VALARMs from incoming iTIP.
Daboo Expires January 7, 2010 [Page 13]
Internet-Draft VALARM Extensions July 2009
Talk about VALARMs being used to "spam" - particularly nasty if the
server handles it.
11. IANA Considerations
TODO: tables registering new properties, parameters and values.
12. Acknowledgments
This specification came about via discussions at the Calendaring and
Scheduling Consortium.
13. References
13.1. Normative References
[I-D.ietf-calsify-rfc2445bis]
Desruisseaux, B., "Internet Calendaring and Scheduling
Core Object Specification (iCalendar)",
draft-ietf-calsify-rfc2445bis-10 (work in progress),
April 2009.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
"Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
March 2007.
13.2. Informative References
[RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,
A., Peterson, J., Sparks, R., Handley, M., and E.
Schooler, "SIP: Session Initiation Protocol", RFC 3261,
June 2002.
[RFC3860] Peterson, J., "Common Profile for Instant Messaging
(CPIM)", RFC 3860, August 2004.
[RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers",
RFC 3966, December 2004.
Daboo Expires January 7, 2010 [Page 14]
Internet-Draft VALARM Extensions July 2009
Author's Address
Cyrus Daboo
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
USA
Email: cyrus@daboo.name
URI: http://www.apple.com/
Daboo Expires January 7, 2010 [Page 15]