Network Working Group D. Royer Internet-Draft INET-Consulting Expires: December 13, 2003 June 14, 2003 CAP notification of upcoming VEVENTs, VTODOs or any changes. draft-royer-cap-notify-00 Status of this Memo 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 December 13, 2003. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract This memo describes a method used to ask for and receive notifications. These notifications will be the direct result of a stored VALARM and the notifications or changes to components or the store and are represented in iCalendar format. This is an extensions to CAP. This memo includes a new CAP command types of "REQUEST-NOTIFY", "NOTIFICATION", and "CANCEL-NOTIFY", a new property of "OBSERVER", a new 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 Royer Expires December 13, 2003 [Page 1] Internet-Draft CAP-Notify June 2003 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 them using 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. OBSERVER property . . . . . . . . . . . . . . . . . . . . . . . 6 3. REQUEST-NOTIFY METHOD . . . . . . . . . . . . . . . . . . . . . 6 4. Restriction tables . . . . . . . . . . . . . . . . . . . . . . . 6 5. CAN-NOTIFY CAP Capability . . . . . . . . . . . . . . . . . . . 7 6. Component, Property and Parameter details . . . . . . . . . . . 7 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . 8 Royer Expires December 13, 2003 [Page 2] Internet-Draft CAP-Notify June 2003 1. Introduction 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 CUA (the OBSERVER) or supplied mailto: URLs that VALARM TRIGGERs are ready to be processed. Or that something has changed. When CAP was being developed it was decided that notifications would be deferred until a later time. This memo describe notifications and how they are delivered to the observers. 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 would 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 a CS. 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. BEGIN:VCALENDAR VERSION:2.0 CMD:REQUEST-NOTIFY TARGET:cap://cal.Royer.com/holiday-list 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 Royer Expires December 13, 2003 [Page 3] Internet-Draft CAP-Notify June 2003 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. 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 CS 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 CS creates an ID that is unique to the CS 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 CS. 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 one multiple Royer Expires December 13, 2003 [Page 4] Internet-Draft CAP-Notify June 2003 "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 allowd to observe the other components. BEGIN:VCALENDAR VERSION:2.0 TARGET:cap://cal.Royer.com/holiday-list BEGIN:NOTIFICATION REQUEST-STATUS:2.0 NOTIFYID:a-unique-id-set-by-the-cs 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-cs 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 with the CAP "MODIFY" command. 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. Royer Expires December 13, 2003 [Page 5] Internet-Draft CAP-Notify June 2003 BEGIN:VCALENDAR VERSION:2.0 CMD:CANCEL-NOTIFY TARGET:cap://cal.Royer.com/holiday-list NOTIFYID:a-unique-id-set-by-the-cs 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 2. OBSERVER property The "OBSERVER" property has 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 the 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. 3. REQUEST-NOTIFY METHOD A CUA makes notification requests to the observers 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. 4. Restriction tables To be written ... Royer Expires December 13, 2003 [Page 6] Internet-Draft CAP-Notify June 2003 5. CAN-NOTIFY CAP Capability A CS can 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. 6. Component, Property and Parameter details TODO Author's Address 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 Royer Expires December 13, 2003 [Page 7] Internet-Draft CAP-Notify June 2003 Full Copyright Statement 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Royer Expires December 13, 2003 [Page 8]