| Network Working Group | C. Daboo |
| Internet-Draft | Apple |
| Intended status: Standards Track | October 18, 2012 |
| Expires: April 19, 2013 |
VALARM Extensions for iCalendar
draft-daboo-valarm-extensions-00
This document defines a set of extensions to the iCalendar VALARM component to enhance use of alarms and improve interoperability between clients and servers.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http:/⁠/⁠datatracker.ietf.org/⁠drafts/⁠current/⁠.
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."
This Internet-Draft will expire on April 19, 2013.
Copyright (c) 2012 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 (http:/⁠/⁠trustee.ietf.org/⁠license-⁠info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
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.
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.
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 base syntax is defined here, with the goal of simplifying specification of the extensions.
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 = *(
; 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
)
A "VALARM" calendar component is re-defined by the following notation:
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.
alarmprop /= *(
; the following is OPTIONAL,
; but MUST NOT occur more than once
uid
)
The "VALARM" component defined in Section 3 is extended here as:
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.
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
)
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.
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.
alarmprop /= *(
; the following is OPTIONAL,
; and MAY occur more than once
alarm-agent
)
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.
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
ALARM-AGENT:SERVER
uriparam = "URI" "=" DQUOTE uri DQUOTE
ALARM-AGENT;URI="http://calendar.example.com":SERVER
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.
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"
To address these needs, this specification adds the following:
This is defined by the syntax below.
last-triggered = "LAST-TRIGGERED" lasttrigparam ":" datetime CRLF
lasttrigparam = *(
; the following is OPTIONAL,
; and MAY occur more than once
(";" other-param)
)
LAST-TRIGGERED:20090604T084500Z
snooze-until = "SNOOZE-UNTIL" snoozeuntilparam ":"
datetime CRLF
snoozeuntilparam = *(
; the following is OPTIONAL,
; and MAY occur more than once
(";" other-param)
)
SNOOZE-UNTIL:20090604T085000Z
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".
alarmprop /= *(
; the following is OPTIONAL,
; but MUST NOT occur more than once
uid-ref
)
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.
uid-ref = "UID-REFERENCE" uidrefparam ":" text CRLF
uidrefparam = *(";" other-param)
UID-REFERENCE:19960401T080045Z-4000F192713-0052@example.com
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.
TODO:talk about importance of stripping VALARMs from incoming iTIP. Talk about VALARMs being used to "spam" - particularly nasty if the server handles it.
TODO: tables registering new properties, parameters and values.
This specification came about via discussions at the Calendaring and Scheduling Consortium.
| [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.M. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, March 2007. |
| [I-D.ietf-calsify-rfc2445bis] | Desruisseaux, B, "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", Internet-Draft draft-ietf-calsify-rfc2445bis-10, April 2009. |
| [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. |