| Network Working Group | D.M. Royer |
| INTERNET DRAFT | INET-Consulting |
| <draft-royer-cap-notify-02> | 1 September 2003 |
| Category: Informational | |
| Expires: 1 March 2004 |
This document 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.
This Internet-Draft will expire on 1 March 2004.
Copyright (C) The Internet Society (2003). All Rights Reserved.
This memo describes a method used to ask for and receive notifications. These notifications will be the direct result of a stored components and the notifications or changes to components or the store and are represented in iCalendar format. This is an extensions to iCalendar objects.
This memo has been updated to include non-CAP notificaitons.
This memo includes a new CAP command types of "REQUEST-NOTIFY", "NOTIFICATION", and "CANCEL-NOTIFY", a new property of "OBSERVER", a new iCalendar component "NOTIFICATION", CAP capabilities of "CAN-NOTIFY", "NOTIFY-UPDATES", and "ALLOW-NOTIFY-BOT". A "REQUEST-NOTIFY" command is a request to add an observer to an component in the "TARGET" calendar. In addition the "REQUEST-NOTIFY" command can alert the CUA of changes to specific components or in the calendar or calendar store. Everything is subject to VCAR restrictions.
These are asynchronous notifications must be advertised by the CS and requested by the CUA. This memo discusses how to transport these iCalendar objects and using them with CAP.
In addition if the CS and CUA support the "NOTIFY-UPDATES" capability, then the CS will send "NOTIFICATION" components to the CUA describing the UIDs or TARGETS that have changed since the currently authenticated CU was last connected allowing for easier synchronization.
iCalendar specifies that a component may include a VALARM component. iTIP describes how to perform scheduling, CAP describes how to store and fetch those components.
Notifications as used here are asynchronous messages that inform a registered OBSERVER or supplied mailto: URLs that VALARM TRIGGERs are ready to be processed. Or that something is new or has changed. These observers may or might not be an ATTENDEE or ORGANIZER. They simply need permissions to become an observer.
A CUA-BOT is defined here to mean a CUA that automatically performs operations on behalf of a CU. The CUA-BOT is separate from the CS, however an implementation could provide them in the same application binary program as a CS.
A NOTIFY-BOT is a CUA-BOT that performs these notification operations on behalf of a CU. The components could be stored in a CS and the NOTIFY-BOT would have access to the component for the purpose of sending object to the registered observers.
A CUA informs a CAL-ADDRESS that it wishes to receive notifications by sending a "REQUEST-NOTIFY" command object to an ORGANIZER. This request includes the specific TARGET or component UIDs where the CUA wishes to become an OBSERVER. In addition any CUA may be listed as an observer meaning that if the currently authenticated CUA supports notifications they will happen as requested. Here is an example of a request to be notified:
BEGIN:VCALENDAR VERSION:2.0 CMD:REQUEST-NOTIFY TARGET:mailto:holiday-cal@Royer.com BEGIN:NOTIFY UID:uid-of-interested-component 1 UID:uid-of-interested-component 2 OBSERVER;ALERT="TRIGGER":mailto:Doug+ical-notify@Royer.com OBSERVER;ALERT="TRIGGER":mailto:SomeoneElse@example.com OBSERVER;ALERT="TRIGGER,CHANGED,UPDATES":CUA END:NOTIFY END:VCALENDAR
If the "UID" property is not supplied, then changes as defined in the "ALERT" parameter value the to the "OBSERVER" property will be reported when anything changes to the supplied "TARGET" property value.
Exactly what is done or sent will depend on the "VALARM" property values, if the CU is currently in an active session from a CUA, and as defined in this memo.
The "NOTIFICATION" components will be sent at the "VALARM" component "TRIGGER" value times specified in the "VALARM" component to all registered observers for the listed UIDs when the "ALERT" parameter has a value of "TRIGGER" in the "OBSERVER" property. The inclusion of the "TRIGGER" value in the "ALERT" parameter is the means by which the CUA requests the CS to process or send alarms stored on behalf of the CUA.
If the "ALERT" parameter value contains "CHANGED", then whenever something changes the CS will attempt to deliver a "NOTIFICATION" component to the named observer.
If the "ALERT" parameter value contains "UPDATES" and the CUA has supplied "NOTIFY-UPDATES" in its "GET-CAPABILITY" command reply, and there have been changes to any target or component where the observer is set to "CUA", then the CS will automatically send "NOTIFICATIONS" components to the CUA for all of those previously registered for changes. The "UPDATES" parameter value can only be used when the "OBSERVER" property value is set to "CUA".
The reply from the ORGANIZER is a "NOTIFICATION" component back to the OBSERVER that contains only the REQUEST-NOTIFY, TARGETs, any UIDs and a REQUEST-STATUS back to the CUA. If all "OBSERVER" property values are accepted, then one "NOTIFICATION" component is sent back. The ORGANIZER creates an ID that is unique and supplies that ID back to the CUA in the "NOTIFYID" property. The "NOTIFYID" property is not supplied if all observers are rejected by the ORGANIZER.
BEGIN:VCALENDAR VERSION:2.0 TARGET:cap://cal.Royer.com/holiday-list CMD:REQUEST-NOTIFY BEGIN:NOTIFICATION REQUEST-STATUS:2.0 NOTIFYID:unique-id UID:uid-of-interested-component 1 UID:uid-of-interested-component 2 OBSERVER;ALERT="TRIGGER":mailto:Doug+ical-notify@Royer.com OBSERVER;ALERT="TRIGGER":mailto:SomeoneElse@example.com OBSERVER;ALERT="TRIGGER,CHANGED,UPDATES":CUA END:NOTIFICATION END:VCALENDAR
If not all "OBSERVER" property values are accepted, then multiple "NOTIFICATION" components may be sent back in order to specifically determine what failed. Below 'mailto:SomeoneElse@example.com' was not allowed to observe 'UID:uid-of-interested-component 2' and was allowed to observe the other components.
BEGIN:VCALENDAR VERSION:2.0 TARGET:cap://cal.Royer.com/holiday-list CMD:REPLY BEGIN:NOTIFICATION REQUEST-STATUS:2.0 NOTIFYID:a-unique-id-set-by-the-organizer UID:uid-of-interested-component 1 UID:uid-of-interested-component 2 OBSERVER;ALERT="TRIGGER":mailto:Doug+ical-notify@Royer.com OBSERVER;ALERT="TRIGGER,CHANGED,UPDATES":CUA END:NOTIFICATION BEGIN:NOTIFICATION REQUEST-STATUS:2.0 NOTIFYID:a-unique-id-set-by-the-organizer UID:uid-of-interested-component 1 OBSERVER;ALERT="TRIGGER":mailto:SomeoneElse@example.com NOTIFYID:unique-id END:NOTIFICATION BEGIN:NOTIFICATION REQUEST-STATUS:x.y -- permission denied! UID:uid-of-interested-component 2 OBSERVER;ALERT="TRIGGER":mailto:SomeoneElse@example.com END:NOTIFICATION END:VCALENDAR
"NOTIFICATIONS" components may be removed or modified with the CAP "DELETE" and "MODIFY" commands. The property "NOTIFYID" parameter value can aid in the identification of "NOTIFICATION" components stored in the CS.
When a CS removes a "NOTIFICATION" component and the "OBSERVER" has registered for "CHANGES", then the CS MAY send the observer a "NOTIFICATION" component. The "CMD" value set to "CANCEL-NOTIFY", supplying the "NOTIFYID" property and and an optional "COMMENT" and "UID" properties. No "OBSERVER" properties are supplied if all observers are to be removed. If one or more "OBSERVER" properties are removed, then the removed observers are supplied.
BEGIN:VCALENDAR VERSION:2.0 CMD:CANCEL-NOTIFY TARGET:cap://cal.Royer.com/holiday-list NOTIFYID:a-unique-id-set-by-the-organizer UID:uid-of-interested-component 2 COMMENT:We no longer provide notification services for non local OBSERVERS. OBSERVER:mailto:SomeoneElse@example.com END:VCALENDAR
For observers registered for "TRIGGER" alerts, the "UID" property and "VALARM" "SEQUENCE" property are sent in the "NOTIFICATION" component. The observer knows that it is a "TRIGGER" alert because it has the "SEQUENCE" property from the "VALARM" component.
BEGIN:VCALENDAR VERSION:2.0 CMD:NOTIFICATION TARGET:cap://cal.Royer.com/holiday-list UID:uid-of-interested-component 2 SEQUENCE:3 END:VCALENDAR
Purpose: The value of the "OBSERVER" property is added to the list of interested observers if permissions permit.
Property Parameters: Non-standard property parameters can be specified on this property.
Conformance: The property can be specified in components as specified in this memo.
Description: The "OBSERVER" property allows a value type of 'cal-address'. So it may be an mailto, CAP uri or any IANA registered cal-address type or the string "CUA". The "OBSERVER" property value is the destination address for sending any VALARM at TRIGGER time.
The "OBSERVER" property value may or might not be the same value as the "ATTENDEE" property value in the component or a contained "VALARM" component.
Formal Definition: The property is defined by the following notation:
observerprop = "OBSERVER" observer-params ":" observer-list CRLF observer-params = alert-param other-params other-params ; As defined in [CAP]. observer-list = observer-value *( "," observer-value) observer-value = (cal-address / "CUA") cal-address ; As definded in [CAP].
Purpose: Describes the kinds of alerts requested by the CUA.
Conformance: This parameter can be specified in the "OBSERVER" property.
Formal Definition: The property is defined by the following notation:
; Each unique ALERT value can only be included once.
;
alert-param = "ALERT" "=" 1*( "TRIGGER" / "CHANGED" / "UPDATES" )
Example: The following is an example of this parameter:
OBSERVER;ALERT="TRIGGER,CHANGED,UPDATES":CUA
A CUA makes notification requests to the organizers calendar by sending a CMD:REQUEST-NOTIFY that contains the UID(s) where the notification is requested, and a VALARM component that contains the request action.
A CS may support notifications at three levels:
(1) It can act as a NOTIFY-BOT. This is done by setting "CAN-NOTIFY" in the "GET-CAPABILITY" reply from the CS. This mode is activated if the CUA supplies "CAN-NOTIFY" in the CUAs "GET-CAPABILITY" reply to the CS.
(2) Allowing CUAs to register as a NOTIFY-BOT. This is done by setting the 'ALLOW-NOTIFY-BOT" capability in the "GET-CAPABILITIES" reply form the CS. This mode is activated if the CUA supplies "ALLOW-NOTIFY-BOT" in the CUAs "GET-CAPABILITY" reply to the CS.
For a CS that also supports mode (1) the CS ignores "OBSERVER" properties that have a "CUA" property value for the current session. And it ignores all "OBSERVER" properties where the value equals the currently authenticated UPN for the current session. These are ignored because the CUA has registered as the notification handler.
(3) Allowing each CUA to act as its own notification handler. This is compatibility mode for a CS or CUAs that do not support notifications. This mode is activated when nether of the above two modes are activated at "GET-CAPABILITY" reply time.
Each CUA can only activate one of the above modes.
| Doug Royer | |
| INET-Consulting.com | |
| 1795 W. Broadway #266 | |
| Idaho Falls, Idaho 83402 | |
| US | |
| Phone: | 208-520-4044 |
| Fax: | 866-594-8574 |
| EMail: | Doug@Royer.com |
| URI: | http://Royer.com/People/Doug |
[iCAL] Dawson, F. and Stenerson, D., "Internet Calendaring and
Scheduling Core Object Specification (iCalendar)", RFC 2445,
November 1998 ftp://ftp.isi.edu/in-notes/rfc2445.txt
[iTIP] Silverberg, S., Mansour, S., Dawson, F. and Hopson, R.,
"iCalendar Transport-Independent Interoperability Protocol
(iTIP) Events, BusyTime, To-dos and Journal Entries",
RFC 2446, November 1998 ftp://ftp.isi.edu/in-notes/rfc2446.txt
[iMIP] Dawson, F., Mansour, S. and Silverberg, "iCalendar
Message-Based Interoperability Protocol (iMIP)", RFC 2447,
November 1998 ftp://ftp.isi.edu/in-notes/rfc2447.txt
[CAP] Royer, D., Babics, G., Hill, P. Mansour, S. "Calendar
Access Protocol (CAP)", work in progress,
draft-ietf-calsch-cap-11.txt.
Copyright (C) The Internet Society (2003). 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.
Funding for the RFC editor function is currently provided by the Internet Society.