Internet Draft Bert Culpepper draft-culpepper-sip-key-events-00.txt InterVoice-Brite, Inc. December 19, 2001 Expires: June 19, 2002 Robert Fairlie-Cuninghame Nuera Communications, Inc. Jean-Francois Mule SIP Event Package for Keys Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 [1]. 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. Abstract This document defines a new SIP event package and presents a framework for defining key event packages to be used by SIP network entities for requesting and reporting state related to keys or buttons. The proposal currently defines key event packages to represent telephone dial pads, feature buttons found on many commercial telephones, standard keyboards as well as the framework to support user or device specific buttons (for instance, a "Double Latte" button). The event package and associated key packages can be used to enable new SIP services where an application or a SIP entity requires user indications that are generated through key- based input which are common to many SIP communications endpoints. Table of Contents 1. Introduction......................................................3 Culpepper/Cuninghame/Mule [Page 1]
Internet Draft SIP Key Events Package December 19, 2001 2. Motivation/Use Cases..............................................3 2.1. Relation To Telephony Tones And Events.........................5 2.2. Example Usage Scenarios........................................5 2.2.1. Example 1: Application Server acting as B2BUA/3pcc.........6 2.2.2. Example 2: Application Server Acting As A Proxy............7 2.3. SIP Call-Control Interaction...................................7 3. Subscription to Key Events........................................8 3.1. Dialog Specific Subscriptions..................................8 3.1.1. Multi-dialog Capable Endpoints.............................8 3.1.2. "Early" Dialog Subscriptions...............................9 3.1.3. Multiple Subscriptions.....................................9 3.2. Non-Dialog Specific Subscriptions..............................9 4. Key-Event Framework and Representation...........................10 4.1. Key-Event Sub-Package Components..............................10 4.2. Key Representations...........................................10 5. Key-Event Sub-package Definitions................................12 5.1. Shared Key-Event States and Properties........................12 5.2. Key Sub-package...............................................13 5.3. Keyboard Sub-Package..........................................14 5.4. Telephone Sub-Package.........................................15 5.5. User Package..................................................15 6. Key-Event Message Body Format....................................16 6.1. Time-Header Format............................................16 6.2. Event-Header Format...........................................17 6.3. Properties-Header Format......................................18 6.4. State-Header Format...........................................20 7. Event Package Definition.........................................20 7.1. Event Package Name............................................20 7.2. Event Package Parameters......................................21 7.3. SUBSCRIBE Bodies..............................................21 7.4. Subscription Duration.........................................21 7.5. NOTIFY Bodies.................................................21 7.6. Notifier Processing of SUBSCRIBE Requests.....................21 7.7. Notifier Generation of NOTIFY Requests........................22 7.7.1. Generating Initial NOTIFY Requests........................22 7.7.1.1. Event Header Processing..............................23 7.7.1.2. Properties Header Processing.........................23 7.7.1.3. State Header Processing..............................24 7.7.2. Generating State Change NOTIFY Requests...................24 7.8. Subscriber Processing of NOTIFY Requests......................25 7.9. Subscriber Generation of SUBSCRIBE Requests...................25 7.10. Pre-loaded Routes in SUBSCRIBE requests......................25 7.11. Handling of Forked Subscriptions.............................26 7.12. Rate of Notifications........................................26 8. Examples.........................................................26 9. Security Considerations..........................................32 10. Minimal Implementation for Key-Event Server Devices............32 Culpepper/Cuninghame/Mule [Page 2]
Internet Draft SIP Key Events Package December 19, 2001 11. Guidelines to Future Sub-Package Authors.......................33 Appendix A. Dialog specific subscriptions, Applies-To Header.......33 IANA Considerations.................................................35 Authors.............................................................35 References..........................................................36 1. Introduction As stated in SIP-specific Event Notification [2], the SIP SUBSCRIBE and NOTIFY methods provide a mechanism by which cooperating SIP [3] endpoints can request and receive asynchronous notification of changes in state related to network resources and calls. This mechanism, when combined with an event package for keys, can be used for requesting and reporting the status of keys and keypads associated with SIP user agents or indeed any SIP device. Communication sessions many times are used as a means to access and deliver services to users. The operation and use of these services almost always require some user interaction with the service. One of the primary means for user interactions with services when using the legacy circuit-switched telecommunications network is via tones generated as a result of a key press on the communications device. While tones can be used in the same manner in IP networks, their use, given the distributed nature of the network, is sub-optimal. In addition, their use limits the user interface of many user devices as well as the range of application services possible. It is for these reasons that a means to transport key presses is needed. 2. Motivation/Use Cases The first and foremost motivation for this proposal is to extend the possibility for user interaction beyond the antiquated telephone dialpad model imposed by limiting interaction to DTMF tones. The proposal is designed to support full keyboards, multiple key instances, user- or device-specific buttons (for instance, a "Double Latte" button). It also aims to provide an extensible framework to allow volume controls, multi-position switches or any other user interface widget to be defined in future Key Event Packages. A secondary goal of the proposal is that devices possessing a simple user interface (such as telephone dialpad) need only implement a smaller subset of the full proposal without losing any interoperability with Application Servers (c.f., Section 10). DTMF has been used in telephony networks as a means for users of network services to provide input and some control of those services. DTMF is also used to signal connection destinations in these networks. This dual role of DTMF does not present problems in circuit-switched networks. However, with telecommunications move to packet networks, separation of these roles is needed. Packet networks enable communications and related services to be deployed in a distributed architecture. An alternative to DTMF for "user Culpepper/Cuninghame/Mule [Page 3]
Internet Draft SIP Key Events Package December 19, 2001 input" is needed in order to better support the distributed application architecture possible in IP networks. Although a standard mechanism exists for the transport of DTMF in IP networks, using it for user input and/or dynamic application control as is done in the PSTN does not carry over into the IP network very well. Receiving tones via RTP is problematic for the detector/generator devices in scenarios where multiple network entities are interested in the events. Replicating media to multiple destinations is not a common feature of endpoints. In addition, the SDP session description to set up media replication is more complicated than that required to set up typical multi-media communications sessions. The mechanism defined here can be used as an alternative to DTMF detection when the detection of these tones is to gather input from a user or provide some user application control independent of any end-to-end media path. The relationship of the mechanism described in this specification to the transport of telephony tones via RTP defined in RFC 2833 [4] is further described in Section 2.1. It is intended that the event notification mechanism defined in this document might be used in scenarios that have the following attributes or requirements: - The amount of data to be conveyed is very small compared to the audio, video, text, etc. data in a session. - Dynamic user control of applications is required. - Collecting device input is needed when the device is not engaged in a session. - Security concerns exist due to multiplication attack possible with DTMF forking. - End-to-end security/privacy between caller and destination system is required. - Multiple Application Servers may be involved along the end-to-end call path. - Authentication and/or Privacy of key sequences between an Application Server and an endpoint is desired. - Reliable delivery of key sequences is required even when short periods of network connectivity problems occur. - Support for a device with a user interface consisting of more than a simple keypad is required. A network entity subscribing to key events at another network entity may be interested in the events as they relate to an established communications session or as they relate to the device itself. Many network-based communications services require the user to identify themselves (for instance, by the user providing a PIN). Pre-paid and post-paid calling card services are a good example where a call- associated event subscription is useful. Key event subscriptions can also be useful outside of communications sessions. For example, an endpoint (SIP phone) may have a dedicated key used to asynchronously invoke some function on a remote network entity. In this case, the remote network entity subscribes to key events at the Culpepper/Cuninghame/Mule [Page 4]
Internet Draft SIP Key Events Package December 19, 2001 SIP phone in a non-dialog specific manner. When a key event of interest occurs, the remote endpoint can act on the event. RFC 2833 does not support notification of key events outside of the context of an established session. 2.1. Relation To Telephony Tones And Events RFC 2833 defines an RTP payload format for telephony tones and signals (including DTMF digits). It allows the transport of such events in the context of an established media session (in SIP, a session must be established with media description in order for endpoints to exchange RFC 2833 events or tones). This mechanism has several advantages: it is independent from any signaling protocol and can be used with SIP, MGCP and other protocols, it eliminates tone distortion, and it provides a reliable means for telephony endpoints to exchange telephony tones within RTP media flows. The purpose of the current document is to provide a general mechanism for SIP entities to request and report the notifications of key events (including keys in keypads or any kind of keyboards). This mechanism is specific to the SIP protocol and is based on SIP events. It offers several advantages: - SIP application servers not involved in the media path can now request and receive key state changes. - SIP entities supporting SUBSCRIBE/NOTIFY now have a generic mechanism to exchange key states. - It allows multiple SIP application servers to receive independent key event notification with each application server only receiving notifications for the key-events that it is interested in. In conclusion, this mechanism can be used in conjunction with RFC 2833 or it can also serve as an alternative to RFC 2833 in the cases where: - Key states beyond telephony tones and signals are desired. - A means for simple SIP telephony applications such as software phones or applications, not necessarily able to generate telephony tones, is needed to interact with applications. - IP telephony gateways wish to conserve DSP resources. - Supporting RFC 2833 for the sole purpose of indicating key presses, or supporting the duplication of RFC 2833 RTP payload events to the signaling planes, is not desirable. 2.2. Example Usage Scenarios As discussed in the previous section, the scenarios described in this section do not preclude the presence of tone data associated with a telephone keypad. Specifically, RFC 2833 may still be employed as an end-to-end media-layer transport mechanism for DTMF tones, that is, as an end-to-end transport mechanism between the caller and destination User Agent. Culpepper/Cuninghame/Mule [Page 5]
Internet Draft SIP Key Events Package December 19, 2001 2.2.1. Example 1: Application Server acting as B2BUA/3pcc In this example the Application Server (AS) will generate the INVITE and BYE requests to perform call control. Due to the nature of this model, the AS can always inherently ensure that it remains on the call path for the duration of the session. The general B2BUA network model is shown in Figure 1. Caller AS Callee +--------+ +---------+ +--------+ | UAC |<--- SIP --->| UAS/UAC |<--- SIP --->| UAS | +--------+ +---------+ +--------+ | | +-------------------- RTP ---------------------+ Figure 1. Application Server (B2BUA/3pcc) Model The above figure depicts a caller establishing a session with the AS, after which the AS establishes a session with the callee. The AS provides one endpointÆs session description to the other endpoint. This results in the media being exchanged between the two endpoints and the SIP signaling occurring between the AS and each endpoint. In this scenario, it is desired for the caller and callee to be able to invoke application services & features by pressing keys on the terminal. The action required by the AS is simple: it sends a SUBSCRIBE to the callerÆs and/or calleeÆs User-Agent as described in section 7.3. The subscription request should be dialog specific. Now the Application Server will receive all endpoint Key Events for the duration of the subscription. If support for multiple Application Servers is desired when using this model, or the caller or callee wishes to subscribe to key events, then the AS will have to act as a proxy (or B2BUA) to forward received SUBSCRIBE/NOTIFY requests between the subscriber and the actual User Agent endpoint. Unless the AS is acting as a transparent B2BUA, dialog references within SUBSCRIBE requests (in this instance the Applies-To header [c.f., Appendix A]) will also need to be modified to remain correct. This model can introduce re-INVITE glare conditions when multiple Application Servers are involved in a session where a key sequence invokes some session modification function at multiple Application Servers. Re-INVITE glare is not a problem specific to this document and is only one consideration of the more general problem of "Multiple AS Interaction". Culpepper/Cuninghame/Mule [Page 6]
Internet Draft SIP Key Events Package December 19, 2001 2.2.2. Example 2: Application Server Acting As A Proxy. In this scenario, the Application Server normally functions as a SIP proxy. The application is co-located with the SIP proxy and may also function as a SIP UA if desired. The network model is shown in Figure 2 below. Caller AS AS Callee +------+ +-------+ +-------+ +------+ | UAC |<-- SIP -->| Proxy |<-- SIP -->| Proxy |<-- SIP -->| UAS | +------+ +-------+ +-------+ +------+ | | +--------------------------- RTP --------------------------+ Figure 2. Application Server (Proxy) Model Any proxy that wants to stay in the signaling path inserts a Record- Route header into the session establishment request. The Record- Route mechanism will ensure the Proxy/AS sees all SIP requests and responses for the dialog established between the caller and callee. Applications deployed using this model do not manage user sessions as a user agent but rather exert call-control over the INVITE dialog and/or conversation space [5] using, for instance, the call control primitives and framework defined in [5] or using some other external mechanism. In this usage example the Application Server desires to take action after a certain sequence of key events occurs during a session. So after possibly record-routing the callerÆs initial INVITE request and forwarding it to the destination system, the AS will send a dialog specific subscription request to the desired User-Agents as described in Section 3.1 (and as for example 1). This allows any and all SIP proxies/AS in the signaling path to receive key-event notifications independently of any other SIP proxy/AS. 2.3. SIP Call-Control Interaction The Key Event Package allows multiple network entities to subscribe to key events for the same SIP session on the same device. Due to this fact, it is possible for multiple Application Servers to take part in the same call and thus the interaction between the servers must be considered. However, solving the problems of multiple AS interaction is beyond the scope of this document. This document simply defines a mechanism whereby Applications can monitor key events on a network device - it is does not specify the call-control mechanisms used by participating entities. Different call control models will have different interaction characteristics. Culpepper/Cuninghame/Mule [Page 7]
Internet Draft SIP Key Events Package December 19, 2001 3. Subscription to Key Events Subscriptions to key events are established, maintained, and terminated as described in the SIP-Specific Event Notification framework specification [2]. Key event subscriptions are indicated with the appropriate value in the Event header of SUBSCRIBE and NOTIFY requests. Details of the events being subscribed to, and being reported are specified in message body of the request. (See sections 5 and 6 for normative descriptions of key events and their message bodies.) As specified later, SUBSCRIBE requests contain message bodies that indicate the events being subscribed to. Once accepted, an "event notification dialog" is established and event state is established in the notifier according to the contents of the SUBSCRIBE message body. It is possible to modify the set of events being subscribed to by sending another SUBSCRIBE request, with a key events message body, for a previously established event notification dialog. In this case, the new message body should replace the state established by a previous SUBSCRIBE. This document describes two types of key event subscriptions. The first is a subscription associated with a SIP dialog or conversation space. That is, the subscription is only valid for key-events directly associated with the session and the subscription ends when the SIP dialog or conversation-space ceases to exist. The term "dialog specific subscription" will be used to describe this type of subscription. The second type of key event subscription described here is a non-dialog associated subscription. Where the subscribing device is interested in key events regardless of what the device is doing. The term "non-dialog specific subscription" will be used to describe this second type of key event subscription. Devices supporting the mechanisms defined in this document MUST support dialog specific subscriptions. Support for non-dialog specific subscriptions is OPTIONAL. 3.1. Dialog Specific Subscriptions A dialog specific subscription is requested by the subscriber by including the Applies-To message header defined in Appendix A. It is hoped that this mechanism is eventually incorporated into the SIP Events draft [2]. Some aspects of this type of subscription are clarified below: 3.1.1. Multi-dialog Capable Endpoints Dialog specific subscriptions can present a challenge to user devices that support multiple simultaneous dialogs but only have a single user interface (keypad, speaker, microphone) that is shared between all session (e.g., a multi-line SIP phone). Most devices of this type have the concept of a single "active" session among the Culpepper/Cuninghame/Mule [Page 8]
Internet Draft SIP Key Events Package December 19, 2001 established sessions. That is, only one session has the use of the shared user interface resources at any point in time. This characteristic should be applied to key event subscriptions, in other words, notifications will only be sent to subscribers (if any) of the dialog with which the keypad is assigned to at the time of the event detection. This behavior is consistent with common circuit-based multi-line telephones. This should not be confused with devices which terminate multiple dialogs but where each dialog is associated with a different user, for instance, a SIP-PSTN gateway. 3.1.2. "Early" Dialog Subscriptions In order for a subscriber to reliably receive all Callee generated key-events from the time a session is fully established/answered, a Callee must be able to receive and setup a dialog specific subscription prior to the associated dialog being fully established. This is accomplished by the caller/AS sending a SUBSCRIBE request after an early dialog has been established (by a provisional INVITE response) but before any final response has been sent by the callee. As with any SUBSCRIBE request received, recipients should process the request according to its policies, however early dialog subscriptions do not produce Key-Event information until the associated dialog is established/answered. It should be remembered that the SIP Events draft requires that a NOTIFY request is generated immediately, however, the NOTIFY will simply not contain Key-Event message bodies until the subscriptionÆs associated device or dialog becomes active (as explained in Section 6). A Caller can also receive a dialog specific subscription for a dialog before it has been fully established. The same issues with authentication and authorization apply as in the previous case, however, the notification of caller key presses before the dialog is fully established may benefit certain applications (for instance, pre-answer or pre-alerting caller pin-code authorization). Thus, when the Applies-To header does not specify a remote tag the early subscription should become active immediately. If the subscriber does specify a remote tag in the Applies-To header, then the subscription is only valid while the caller has an end-to-end association with the specified callee (for instance while early media from the specified callee is being played to the caller). In this case, the subscription is terminated if and when the session is eventually established with a different callee. 3.1.3. Multiple Subscriptions A User-Agent/Notifier MUST support multiple subscriptions for the same dialog from both the same subscriber and from different subscribers. 3.2. Non-Dialog Specific Subscriptions Culpepper/Cuninghame/Mule [Page 9]
Internet Draft SIP Key Events Package December 19, 2001 Key events subscriptions that apply to a device, regardless of any on-going or active SIP dialogs, are established by SUBSCRIBE requests that do not include an Applies-To header. Notifiers that support non-dialog specific subscriptions MUST support multiple subscriptions from the same or different subscribers. 4. Key-Event Framework and Representation The "key-event" SIP Event Package does not in itself define any events but rather defines the framework for "Key-Event Sub-Packages" (which should not be confused with SIP Event Packages or Sub- Packages). Each Key-Event Sub-Package defines the key-events that make up the sub-package along with the states and properties that the constituent key-events may possess. The use of SIP Event Sub-Packages (as defined in [2]) with the Key- Event SIP Event Package is not currently defined and SUBSCRIBE requests for unknown SIP Event Sub-Packages (for instance, "Event: key-event.mysubpackage") SHOULD be rejected with a 489 Bad Event response. 4.1. Key-Event Sub-Package Components All Key-Event Sub-Package definitions consist of the following elements. Sub-Package Name: The name of the sub-package as used in messages. Key-Event Values: This list defines the set of valid key-events of the sub-package. A key-event can have either a numeric value (e.g., 49) or a non-numeric value (e.g., shift). Key-Event States: This component defines the set of states that key- events in the sub-package can have (e.g., keyup or keydown). The sub-package must also define a default state. Key-Event Properties: This list defines any configurable or retrievable properties held by the key-events. Support for any particular sub-package property is NOT REQUIRED unless explicitly stated in the sub-package description. Enumerated Key-Event Sets: In order to simplify subscription, the sub-package can define a number of enumerated key-event sets. These enumerations are entirely equivalent to the set of key-events they represent (e.g., @dialpad = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, * and #} found on common telephones). By design, all key-events in a sub-package share the same states and properties. The actual sub-packages are defined in Section 5. 4.2. Key Representations Culpepper/Cuninghame/Mule [Page 10]
Internet Draft SIP Key Events Package December 19, 2001 The representation of keys in the "key-event" event package has been designed around a few central philosophies. Firstly, all keys that represent the same information must map to the same key-event. For instance, a key representing "1" on a keyboard, keypad, telephone, or vending machine will all map to the same key event; likewise, multiple equivalent keys (e.g., left and right shift keys) will also map to the same key-event. The key- event package does however allow an optional positional indicator to indicate the origin of a particular key event (if multiple equivalent keys are present). The value can be ignored if desired. This arrangement avoids the situation where an application must observe a (possibly unknown) set of equivalent key events. The positional indicator values currently defined are "alt" (alternate) & "keypad" as well as the assumed "pri" (primary) key position. When a keyboard has two or more equivalent keys, one is always defined to be the primary key and the others are defined to be the alternate/keypad positions. For Shift, Ctrl, Alt and similar equivalent keys, the bottom-left most key is defined to be the primary key. If a device has only one instance of a particular key it is always regarded as the primary key regardless of its physical position. The second design philosophy is that the event package is independent of key-cap arrangements on keyboards. A keyboard is represented by two distinct sub-packages: one sub-package represents all characters that are accessible on the keyboard, the second sub- package represents all non-character based keys, for instance, Shift, Caps Lock, Insert, Up, Alt, Pause. [For historical reasons Backspace, Delete, Enter/Carriage-Return & Escape have character representations.] This, for example, means that the representation of capital Q (i.e., 'Q') is independent of the Shift key event. Lastly, all basic keys were designed to have two possible states: up or down. Key presses are signaled by notifying the subscriber when a key transitions into a new state ("keyup" or "keydown" state events). Each state notification is accompanied by state specific information such as key depression start time. The key-event package states have been arranged such that a "keyup" state event includes both key release event time as well as duration of the depression. This arrangement allows the "keydown" state event to be seamlessly delayed or omitted by the notifier and/or ignored by the subscriber. The role of the "keydown" event is to provide rapid notification of key depression. For many applications, the "keydown" event notification is only useful for prolonged key depressions. The key- event package provides a useful mechanism whereby a subscriber application can delay "keydown" notifications to achieve a compromise between key response times and reduced bandwidth (2 SIP messages verse 4 SIP messages per key depression and release). [c.f., Section 5.1 "dwndly" property.] Culpepper/Cuninghame/Mule [Page 11]
Internet Draft SIP Key Events Package December 19, 2001 5. Key-Event Sub-package Definitions This section defines the Sub-Packages for the Key-Event Package. All header and grammar references refer to the "application/key- event" message bodies defined in Section 6. 5.1. Shared Key-Event States and Properties All currently defined sub-packages in this document share the following state and property definitions. These definitions have been grouped together for clarity however the definitions still belong to the individual Key-Event Sub-Packages and not to Key-Event Package as a whole. Future sub-packages may define additional states and/or properties; future sub-packages are also not forced to use existing key-event states and properties if they do not make sense within a new sub-package (e.g., for a slider/dimmer control). (c.f., Section 11 for further guidelines.) Key-Event States: - "keydown" State Parameters: * Start Time of Key Depression: Milliseconds offset from the event-time NTP value specified in the Time-header. Negative values are allowed. - "keyup" State Parameters: * Time of Key Release: Milliseconds offset from the event-time NTP value specified in the Time-header. Negative values are allowed. * Duration of Key Depression: Millisecond duration of key depression. Key-Event Properties: - "exists" SUBSCRIBE Parameters: none NOTIFY Result: positional-indicator *( "," positional-indicator ) [List of non-primary key instances.] Default value: N/A Support: RECOMMENDED Description: Determines which non-primary key-events exist. e.g., "p: key[49].exists()" may yield a result of "p: key[49].exists(keypad)" which indicate that two '1' keys exists: a primary key instance and a keypad key instance. Note: This property only produces a result for key-events possessing non-primary key positions. - "name" SUBSCRIBE Parameters: none Culpepper/Cuninghame/Mule [Page 12]
Internet Draft SIP Key Events Package December 19, 2001 NOTIFY Result: positional-indicator "=" quoted-string *( "," positional-indicator "=" quoted-string ) [Lists of names for all key instances.] Default value: N/A Support: RECOMMENDED Description: The property when requested (e.g., "p: keybd[49].name()" ) returns the printable name of the key-event in the NOTIFY result (e.g., "key[49].name(pri="1", keypad="Keypad 1")" ). The description should be sufficiently detailed such that a user would be able to identify the key from the description. This property can also very useful when the name of the key is configured locally, for instance, a SUBSCRIBE request for "phone[line:*].name()" could conceivably yield a result of "phone[line:1].name(pri="Reception")". - "dwndly": (DownDelay) SUBSCRIBE Parameters: 1*DIGIT (milliseconds delay) NOTIFY Result: 1*DIGIT (milliseconds delay) Default value: 0 Support: OPTIONAL Description: Milliseconds delay that notifier should/will wait before generating a "keydown" state event after a key is depressed. If the key is raised before this duration elapses then only the "keyup" state event will be generated. This allows a tradeoff between key responsiveness (for longer keypresses) and the number of NOTIFY message exchanges per keypress. The NOTIFY result contains a confirmation of the new value. This value (and any change thereof) is local to the subscription in which it is requested. 5.2. Key Sub-package Sub-Package Name: "key" Key-Event Values: Decimal Unicode values [7]. Key-Event States: keydown, keyup (default) Key-Event Properties: name, exists, dwndly Enumerated Key Event Sets: - "@dialpad" = "35,42,48-57" This set represents a standard telephone dialpad: 0-9, *, #. - "@uslatin" = "9-10,32-126" This set represents the printable and white space character key set found on a typical US keyboard (which is a subset of most other keyboards). - "@uslatin2" = "8-10,27,32-127" This set is similar to @uslatin but also includes the non- printable backspace, delete & escape keyboard characters (see notes below). Culpepper/Cuninghame/Mule [Page 13]
Internet Draft SIP Key Events Package December 19, 2001 Notes: For mainly historical reasons, the following keys belong to the key sub-package rather than the keybd sub-package: - Backspace: 8 - Tab: 9 - Enter: (treated as unix '\n') 10 - Escape: 27 - Delete: 127 5.3. Keyboard Sub-Package Sub-Package Name: "keybd" Key-Event Values: "shift": name="Shift" (or "Left/Right Shift" if applicable) "caps": name= "Caps Lock" "ctrl": name="Control" "alt": name="Alt" "home": name="Home" "end" : name="End" "insert": name="Insert" "pgup": name="Page Up" "pgdn": name="Page Down" "up": name="Up" "dn": name="Down" "right": name="Right" "left": name="Left" "pause": name="Pause" "numlk": name="Num Lock" "scrlk": name="Scroll Lock" "prtsc": name="Print Screen" "break": name="Break" + "func:*": name="Function Key x" + "os:*": name=<operating system defined> + "vendor:*": name=<vendor defined> + Key-events of the form "keyname:*" allow for multiple numbered keys to exist. These key-events must be always be used in this numbered key form (e.g., "func:3"). Notes: The names provided for the Key-Event Values should be only regarded as examples. The actual Key Event Name should be sufficient to locate the individual key on the device (including the case when there are multiple key instances). Key-Event States: keydown, keyup (default) Key-Event Properties: name, exists, dwndly Enumerated Key-Event Sets: Culpepper/Cuninghame/Mule [Page 14]
Internet Draft SIP Key Events Package December 19, 2001 - "@basic" = "shift, caps, ctrl, alt, home, end, insert, pgdn, pgup, up, dn, right, left" (basic keyboard) - "@std" = "shift, caps, ctrl, alt, home, end, insert, pgdn, pgup, up, dn, right, left, pause, numlk, scrlk, prtsc, break" (standard keyboard) 5.4. Telephone Sub-Package Sub-Package Name: "phone" Key-Event Values: "hook": name = "Hookswitch" Notes: The state of this button is actually the opposite of the hook switch, that is, the "keyup" state represents the on-hook condition. Normally this key-event would only be available in non-dialog specific subscriptions. "hold": name = "Hold" "conf": name = "Conference" "flash": name = "Flash" "redial": name = "Redial" "transfer": name = "Transfer" + "line:*": name = "Line x" or locally defined + "speed:*": name = "Speed Dial x" or locally defined + "vendor:*": name = <vendor defined> + Key-events of the form "keyname:*" allow for multiple numbered keys to exist. These key-events must be always be used in this numbered key form. Key-Event States: keydown, keyup (default) Key-Event Properties: name, exists, dwndly Enumerated Key-Event Sets: None. 5.5. User Package This sub-package intentionally does not define any key-event values. This package is designed as a sub-package available for any device or user specific key-events and properties. Key-Event Values: None. (see note) Key-Event States: keydown, keyup (default) Key-Event Properties: name, exists, dwndly Enumerated Key-Event Sets: None. (see note) Culpepper/Cuninghame/Mule [Page 15]
Internet Draft SIP Key Events Package December 19, 2001 6. Key-Event Message Body Format A Key-Event SUBSCRIBE or NOTIFY request message body consists of a set of UTF8 header lines. The header lines resemble HTTP header formats however for efficiency all header, sub-package, property, state and key-event names are case-sensitive and multiple headers of the same type are not permitted. Parsers MUST be tolerant of spaces between header tokens. The new MIME type for this message body format is "application/key-event". key-event-message = time-header CRLF [ event-header CRLF ] [ properties-header CRLF ] [ state-header CRLF ] [ future-extension-header CRLF ] The key-event headers may appear in SUBSCRIBE and NOTIFY request message bodies as detailed in the following table: Key-Event Header Where SUB NOT(initial) NOT(update) ---------------- ----- --- --- --- Time-Header (t:) B m m m Event-Header (e:) B m m - Properties-Header (p:) B o o - State-Header (s:) B - o m B indicates that the Key-Event header is valid in the message body of a request. The above "NOTIFY(initial)" description refers to the fact that the NOTIFY request is generated in response to a SUBSCRIBE request and carries initial state information - it does not refer simply to the first NOTIFY sent in a subscription. This is further described in Section 7.7. 6.1. Time-Header Format The time-header indicates the NTP time [6] that the event message was first issued and a message sequence number. The exact starting/ending time of an event often requires greater granularity than is provided by NTP values (in seconds) and so key- event state transitions also include a millisecond offset that is added to this NTP time value. It must also be remembered that the time a key-event message is generated may not always be the same as the time of the actual key-event event (for instance, initial state indications). The sequence number allows the key-event message bodies to be sequenced independently of the application protocol. time-header = "t" ":" event-time sequence-number event-time = 1*DIGIT Culpepper/Cuninghame/Mule [Page 16]
Internet Draft SIP Key Events Package December 19, 2001 sequence-number = 1*DIGIT The event-time is set equal to the NTP time value when the message body was first issued. The sequence-number is a 32-bit non-zero integer that is incremented each time a new Key-Event SUBSCRIBE or NOTIFY message body is generated within the each subscription. The sequence number spaces for the subscriber and notifier are independent. Examples: t: 36539655 1 6.2. Event-Header Format The event-header allows the subscriber to request a set of key- events and the notifier to confirm/indicate the set of key-events subscribed/supported. The event-header in a SUBSCRIBE request body is used to request a subscription to a set of key events. The event header in a NOTIFY request body is used to indicate the actual set of subscribed key events. event-header = "e" ":" [ ( event-set ( "," event-set ) ) | "*" ] event-set = sub-package-name [ key-event-list ] sub-package-name = token key-event-list = "[" key-event-set *( "," key-event-set ) "]" key-event-set = key-event-identifier | key-event-range | enumerated-key-event-set key-event-identifier = key-event-name | key-event-value | key-event-numid | key-event-numidwild key-event-name = token key-event-value = 1*DIGIT key-event-numid = token ":" 1*DIGIT key-event-numidwild = token ":" "*" key-event-range = ( key-event-value "-" key-event-value ) | ( key-event-numid "-" key-event-numid ) enumerated-key-event-set = "@" token If the key-event-list is not present in a SUBSCRIBE request message body (e.g., "e: key") then it is assumed that the subscriber wants to be notified of all available key-events in the sub-package. The key-event-list MUST always be present in NOTIFY requests and indicates all key-events that are subscribed (e.g., e: key[48-57]). Likewise, the "*" wildcard can only appear in SUBSCRIBE request message bodies. Wildcards must be expanded in NOTIFY requests as described in Section 7.7.1. Key-event-ranges with numbered keys (e.g, a "Line 3" telephone button) must have the same key-event type on both sides of the range Culpepper/Cuninghame/Mule [Page 17]
Internet Draft SIP Key Events Package December 19, 2001 (e.g., "phone[line:1-line:10]"). Each numbered key is treated as an independent key-event. An empty event-header ("e:") in a NOTIFY request body indicates that no events are subscribed and it is RECOMMENDED that the NOTIFY request also includes an "Expires: 0" in the SIP header. The event- header is the only key-event header which may be present but empty. Example Key-Event SUBSCRIBE request message body headers: e: key[@dialpad, 65-68], keybd In this example, the subscriber is requesting event notification for keys: 0-9, *, #, A, B, C, D from the key sub-package and all supported keybd sub-package events. e: * In this example the subscriber is requesting a subscription to all key-events supported by the notifier. e: phone[line:*] In this example the subscriber is requesting all available "line" buttons within the phone sub-package. Example Key-Event NOTIFY request body headers for the above SUBSCRIBE message body headers: e: key[@dialpad] In this example the notifier is indicating that subscription only occurred for the key-events 0-9,*,#. e: key[48-57,8,10], keybd[insert,numlk] In this example, the notifier is indicating that subscriptions have been created for the key-events 0-9, Backspace, Enter, Insert & NumLock. e: phone[line:1-line:5] In this example, the notifier is indicating that subscriptions have been created for the "line" buttons 1 through 5. 6.3. Properties-Header Format The properties-header in a SUBSCRIBE request body is used to set or retrieve the properties of subscribed key-events. The properties- header in a NOTIFY request body indicates the value of each of the listed properties. properties-header = "p" ":" properties-set *( "," properties-set ) Culpepper/Cuninghame/Mule [Page 18]
Internet Draft SIP Key Events Package December 19, 2001 properties-set = ( event-set | "*" ) "." property-name "(" [ parameter-list ] ")" property-name = token parameter-list = parameter *( "," parameter ) parameter = *( ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" | "$" | unreserved | escaped | quoted-string ) As with the event-header, "*" wildcards and empty key-event-listÆs can only appear in SUBSCRIBE requests. Wildcards and key-event- listÆs must be expanded in NOTIFY requests as described in Section 5.2. NOTE: The set of key-events that each property operates on is always equal to the intersection of the set of subscribed key-events and the set of key-events requested in the properties-header. Examples for SUBSCRIBE request message body headers: [see Section 8 for the actual description and definition of the properties used in these examples] p: key.dwndly(500) In this example the subscriber is requesting that a value of 500 is assigned to the "dwndly" property of all subscribed "key" sub- package key-events. p: *.exists() In this example the subscriber is requesting to know the existence of all non-primary key instances for all subscribed key-events. p: keybd[ctrl].name() The subscriber is requesting the name of all ctrl key instances. Example NOTIFY request body headers for above SUBSCRIBE examples: p: key[@dialpad].dwndly(500) In response to the above dwndly set request, the notifier is confirming the new value for all subscribed key-events in the key sub-package. p: key[47-58, 10].exists(keypad) The notifier is indicating that in addition to the primary instances of all subscribed key-events, additional key instances for 0-9 & Enter exist on a keypad. p: keybd[ctrl].name(pri="Left Control", alt="Right Control") Culpepper/Cuninghame/Mule [Page 19]
Internet Draft SIP Key Events Package December 19, 2001 In this example, the name property indicates the names for the various control key instances possessed by the device. 6.4. State-Header Format The state-header allows the notifier to indicate the initial key- event states and subsequent key-event state changes. The header only appears in NOTIFY requests. state-header = "s" ":" state-indication *( "," state-indication ) state-indication = event-descriptor "." state-name "(" [ parameter-list ] ")" event-descriptor = sub-package-name "[" key-event-descriptor "]" key-event-descriptor = ( key-event-name | key-event-value | key-event-numid ) [ "(" positional-indicator ")" ] positional-indicator = "pri" | "alt" | "keypad" | token state-name = token An empty positional-indicator infers the request/result applies to the primary key of this key-event type. Examples: s: key[49].keydown(-1532) This example is a keydown state indication for the primary '1' key (Unicode [7] value 49). It indicates that the button was first depressed 1532 milliseconds before the NTP value in the time- header. s: key[49(keypad)].keyup(126,1206) This example is a keyup state indication for the keypad '1' key. It also indicates that the button was released 126 milliseconds after the NTP value in the time-header and was depressed for 1206 milliseconds. 7. Event Package Definition This section contains the formal definition of the Key-events SIP Event Package described in this document. This information is provided to conform to the requirements for SIP Event Packages as outlined in [2]. As part of these requirements this section details how Key-Event message bodies are generated by the subscriber and notifier entities. 7.1. Event Package Name The event package token name for the Key Events package is "key- event". The token name is used in the Event and Allow-Event headers defined in [2]. Culpepper/Cuninghame/Mule [Page 20]
Internet Draft SIP Key Events Package December 19, 2001 7.2. Event Package Parameters There are no parameters used in the Event header for the key-events package/sub-packages. 7.3. SUBSCRIBE Bodies SUBSCRIBE requests for Key-Event subscriptions MUST contain a Key- Event message body if the SIP Expires header value is non-zero. SUBSCRIBE responses do not contain a message body. The Content-Type for the Key-Event message body is "application/key-event". The grammatical specifications for the message body are defined in section 6. 7.4. Subscription Duration Dialog specific subscriptions implicitly end when the associated dialog or conversation-space ends. Please refer to Appendix A.2 & A.3 for recommended dialog specific subscription expiry timeout values. It is recommended that the subscription expiry timeout for non-dialog specific subscriptions be from a few minutes to an hour. As detailed in [2] a SUBSCRIBE with an "Expires: 0" header indicates the termination of a subscription. However, if the accepted SUBSCRIBE message also contains a key-event message body, then the SUBSCRIBE message body should be processed and the normal NOTIFY message body is generated (ignoring any persistent subscription side effects). This mechanism can be used to determine the sub-packages & key-events supported as well as the current property values without creating an ongoing subscription. If the terminating SUBSCRIBE does not contain a Key-Event message body then a NOTIFY request MUST still be sent (with no message body) as described in [2]. 7.5. NOTIFY Bodies NOTIFY requests MUST contain a Key-Event message body if the associated device, dialog or conversation space of the subscription is in an active state. Conversely, the lack of a message body in a NOTIFY request with a non-zero Subscription-Expires header value indicates that the Key-Event subscription state is pending (for example, awaiting authorization or for the associated dialog to become active). NOTIFY responses do not contain a message body. The Content-Type for the Key-Event message body is "application/key- event". The grammatical specifications for the message body are defined in section 6. 7.6. Notifier Processing of SUBSCRIBE Requests The notifier takes the following basic steps: Culpepper/Cuninghame/Mule [Page 21]
Internet Draft SIP Key Events Package December 19, 2001 1. Before processing a received SUBSCRIBE request a state-agent MUST check that the subscriber is authorized to perform the requested subscription (c.f., Section 9 and [2]). 2. If the SUBSCRIBE includes an Applies-To header then the notifier MUST check that the dialog exists and if not, take action as described in Appendix A. 3. The SUBSCRIBE message body is parsed for consistency and a SUBSCRIBE response is generated as described in [2]. 4. The state-agent will then clear existing Key-Event subscription state for this subscription and proceed to generate an Initial NOTIFY request and subscription state as described in Section 7.7.1. 5. If the value of the SUBSCRIBEÆs Expires header is non-zero then the new subscription state information is stored. 7.7. Notifier Generation of NOTIFY Requests This section describes both the generation of NOTIFY requests when the subscription is established or modified by the notifier, and when reporting state changes in the subscribed resource. 7.7.1. Generating Initial NOTIFY Requests The Initial NOTIFY contains complete state information. It can be differentiated from a NOTIFY reporting a change in state by the presence of the event-header in the Key-Event message body. The initial NOTIFY request is generated in response to an accepted SUBSCRIBE request containing a Key-Event message body (although it need not be generated immediately). Generating the Initial NOTIFY request is the most complicated part of this specification, however, the headers were constructed so that the event-, property- and state- headers have a similar syntax and semantics. If the SUBSCRIBE request did not contain a Key-Eevent message body (which infers that the request also has an "Expires: 0" header) then the resulting NOTIFY request will also not have a Key-Event message body. If the SUBSCRIBE request does contain a Key-Event message body but has a "Expires: 0" SIP header then an Initial NOTIFY request is still generated however the subscription is not kept after the Initial NOTIFY request is sent. Otherwise, the Initial NOTIFY message body contains the following information: - A confirmation of the subscribed key-events (event-header). - The result of all key-event property evaluations (properties- header). - The initial state of subscribed key-events that have a non-default state (state-header). Culpepper/Cuninghame/Mule [Page 22]
Internet Draft SIP Key Events Package December 19, 2001 The procedure for generating the Initial NOTIFY request message is as follows. 7.7.1.1. Event Header Processing This section describes how the subscribed key-events set is generated. The subscribed key-events set is placed in the event header of the Initial NOTIFY request. It also forms part of the subscription state information and is used in generating the other headers. The set is formed from the event header in the SUBSCRIBE key-event body. The subscribed key-events set is formed by expanding all wildcards in the requested key-events set and intersecting the resulting key- event set with the supported key-event set. Procedure: An event header of "*" results in a subscribed key-event set equal to the supported key-event set. If the event header does not contain a "*" then the following procedure is performed for each element on the event header line: If the key-event-list for the sub-package is empty (e.g., "e: user") then all supported key-events in the specified sub-package are added to the subscribed key-events set. Otherwise, the following procedure is performed for each element in the key-event-list: For enumerated key-event sets (e.g., "@dialpad"), if all key-events in the set are supported, then the enumerated key-event set is added to the subscribed key-events set. Otherwise the enumerated key- event set is simply replaced by its equivalent key-event list for individual evaluation. All key-event identifiers and ranges are checked against the supported key-event set and supported key-events are added to the subscribed key-event set. The resulting set is the subscribed key-event set. The event header in the NOTIFY body is generated from the subscribed key-event set by grouping together all key-events in the same sub- package. This is done to keep header length down, for example, "key[47-58,10,35]" is preferred over "key[47], key[48], key[49], ...". If the subscribed key-event set is empty then an empty event-header is generated ("e:") and a Subscription-Expires SIP header with an expiry value of zero is placed in the NOTIFY request. 7.7.1.2. Properties Header Processing Culpepper/Cuninghame/Mule [Page 23]
Internet Draft SIP Key Events Package December 19, 2001 The properties header in the SUBSCRIBE message body is evaluated to form the properties header used in the NOTIFY body as follows: Each element in the SUBSCRIBE properties header is checked. If the property is not supported for any sub-package then no action is taken for this element. Otherwise, the input key-event set is calculated (the key-event set on which the property will operate). This set is generated in a similar manner to the subscribed key- event set described in the previous section except that the subscribed key-event set is used instead of the supported key-event set (properties only operate on subscribed key-events) and the requested key-event set is equal to the event-set component of the current header element. The resulting input key-event set is further reduced by removing all key-events for which the property is not supported. At this point, the property is evaluated for each element in the input key-event set. For each evaluation, if the property generated a result then the result is added to the output set, otherwise no action is taken. Like the event header, the properties header is generated from the output set by grouping together all key-events with the same property result (and in the same sub-package). For example, "key[47-58].exists(keypad)" is preferred over "key[47].exists(keypad), key[48].exists(keypad), key[49].exists(keypad), ...". If the output set is empty then the properties header is not added to the message. 7.7.1.3. State Header Processing A state notification is generated for each key-event in the subscribed key-event set for which the current state is not equal to the default state. This set of state notifications form the initial state-header. If all subscribed key-events are in the default state then a state- header is not added to the message. 7.7.2. Generating State Change NOTIFY Requests The message bodies for NOTIFY requests generated in response to key state changes only possess two headers: the time-header and the state-header. The state change information in the state-header is a delta indication of the key-event state. That is, the NOTIFY body only includes the state information of key-events that have changed since the last notification. Further "key-event" NOTIFY requests reporting state changes MUST NOT be sent until a final response is received for the previous "key- event" NOTIFY request, that is, there should be only one outstanding Culpepper/Cuninghame/Mule [Page 24]
Internet Draft SIP Key Events Package December 19, 2001 "key-event" NOTIFY request at any time. This reduces the buffering and sequencing requirements of the subscriber. Instead, multiple key state change notifications MAY be sent in the state-header of a single message (in other words, further state change indications can be added to the end of the state-header if these changes occur before the current NOTIFY is sent). 7.8. Subscriber Processing of NOTIFY Requests The NOTIFY response is generated as described in [2]. NOTIFY responses do not contain key-event Event message bodies. 7.9. Subscriber Generation of SUBSCRIBE Requests The SUBSCRIBE request for "key-event" SIP events is generated as described in [2] with the following clarifications: . the Event header is set to "Event: key-event". . the Content-Type header is set to "Content-Type: application/key-event" if a Key-Event message body is included. . if dialog specific subscription is required then the "Applies- To" header is added as described in Appendix A. The event-header will contain the list of desired key-events to receive notifications for and MAY include wildcards. The properties-header will contain the set of key-event properties which are desired to be set or retrieved. A new "key-event" event SUBSCRIBE request for an existing subscription dialog will entirely replace the subscription state of previous SUBSCRIBE requests in that dialog. If the SIP Expires header has a value of zero then the subscriber application should still expect one further NOTIFY request to be sent by the notifier (as described in [2]). If the SUBSCRIBE request contained a Key-Event message body, then the NOTIFY request should also contain a Key-Event message body if the subscription request was accepted and the desired session was available (for dialog specific subscriptions). When using the "key-event" package, if the SIP Expires header does not have a value of zero then the subscriber application MUST include a Key-Event message body. 7.10. Pre-loaded Routes in SUBSCRIBE requests The following section applies only to dialog-specific subscriptions where the subscriber application is located along the associated INVITE dialog call path and wishes to collect key-events from one of the User Agent endpoints. In order to maximize the likelihood that a SUBSCRIBE request will successfully reach the desired User Agent, it is RECOMMENDED the subscriber place pre-loaded Route headers in the SUBSCRIBE request Culpepper/Cuninghame/Mule [Page 25]
Internet Draft SIP Key Events Package December 19, 2001 to reproduce any Record-Routes established in the associated INVITE dialog. The presence of record-routed Application Level Gateways controlling firewalls and/or NATÆs is a typical example of when this may be helpful. When the subscriber wishes to send a SUBSCRIBE request to the caller, the Route set is constructed (in the manner that the callee would normally use) from the Record-Route and Contact headers in the original INVITE request. When the subscriber wishes to send a SUBSCRIBE request to the callee, the Route set is constructed (in the manner that the caller would normally use) from the Record-Route and Contact headers in the original 200 OK INVITE response. However in the case where the subscriber application is acting as a proxy in the original INVITE dialog (c.f., Usage Scenario 2, Section 2.2.2), then the subscriber should ignore all Record-Route headers up to and including the Record-Route inserted by the subscriber application in the 200 OK INVITE response. 7.11. Handling of Forked Subscriptions A SUBSCRIBE request may fork and arrive at multiple devices. In this case, the subscriber can terminate those subscriptions it wishes by sending a SUBSCRIBE with an Expires value set to 0. It can also respond to any NOTIFYs from a UA with a 481 Transaction Does Not Exist. If the subscriber wishes to accept multiple subscriptions, merging of state is not defined due to the fact that the multiple subscriptions represent the state of multiple devices. A notifier SHOULD return 482 Request Merged response to subsequent multiple subscriptions having the same SUBSCRIBE request transaction id (even if they have differing request-uriÆs). 7.12. Rate of Notifications The use of the Key Events packages should be limited to situations that require limited amount of data to be transported. As each key press can cause a notification (and response) to be sent, this mechanism is inefficient in scenarios where a significant amount of data is to be transferred between two endpoints. However, as key event packages are designed to transport user indications, the rate of notifications should not be much more than ten per second nor more than 10 to 20 events at a time. 8. Examples In the example call flow below, an application server subscribes to the status of a caller's keypad events. NOTIFY requests are sent for two key presses, in addition to the initial NOTIFY indicating Culpepper/Cuninghame/Mule [Page 26]
Internet Draft SIP Key Events Package December 19, 2001 those key-events the notifier supports and their initial state. Via headers are omitted for clarity. Subscriber Notifier | | | F1: SUBSCRIBE | |---------------------->| | F2: 200 OK | |<----------------------| | | | F3: NOTIFY | Init. State: '*' key down |<----------------------| | F4: 200 OK | |---------------------->| | | | F5: NOTIFY | 'A' key pressed and |<----------------------| released quickly | A6: 200 OK | |---------------------->| | | | F5: NOTIFY | '1' key depressed |<----------------------| | A6: 200 OK | |---------------------->| | | | F7: NOTIFY | '*' key released |<----------------------| | F8: 200 OK | |---------------------->| | | | F9: NOTIFY | '1' key released |<----------------------| | F10: 200 OK | |---------------------->| | | | F11: (un)SUBSCRIBE | |---------------------->| | F12: 200 OK | |<----------------------| | | | F13: NOTIFY | |<----------------------| | F14: 200 OK | |---------------------->| | | F1: Subscriber -> Notifier SUBSCRIBE sip:caller@access-22.isp.net SIP/2.0 To: <sip:caller@isp.net> From: <sip:appl@appsrv.sp.com>;tag=2356 Call-Id: 321123@appsrv.sp.com CSeq: 2 SUBSCRIBE Contact: <sip:appl@appsrv.sp.com> Culpepper/Cuninghame/Mule [Page 27]
Internet Draft SIP Key Events Package December 19, 2001 Applies-To: call-id=8347-da8d-7657-ab32@192.144.22.1; local- tag=2342354556; remote-tag=00993k23ff8; attach=cspace Event: key-event Expires: 3600 Content: application/key-event Content-Length: xx t: 36539655 1 e: key, keybd p: *.exists(), *.dwndly(1000) The subscriber is requesting all key and keyboard sub-package key- events and also requesting to know the presence of multiple key instances and a delay in keydown notification of 1000ms. F2: Notifier -> Subscriber SIP/2.0 200 OK To: <sip:caller@isp.net>;tag=789 From: <sip:appl@appsrv.sp.com>;tag=2356 Call-Id: 321123@appsrv.sp.com CSeq: 2 SUBSCRIBE Contact: <sip:caller@isp.net> Expires: 3600 Content-Length: 0 F3: Notifier -> Subscriber NOTIFY sip:appl@appsrv.sp.com SIP/2.0 To: <sip:appl@appsrv.sp.com>;tag=2356 From: <sip:caller@isp.net>;tag=789 Call-Id: 321123@appsrv.sp.com CSeq: 403 NOTIFY Contact: <sip:caller@isp.net> Event: key-event Content: application/key-event Content-Length: xx t: 36539658 1 e: key[@dialpad, 65-68] p: key[@dialpad, 65-68].dwndly(1000) s: key[42].keydown(-1902) The notifier confirms subscribed key-events and property values along with non-default initial key-event states. In this example the notifier has created a subscription for keys { '0' - '9', '*', '#', 'A' - 'D' } and confirms that the dwndly property has been set. All keys except '*' are in the default (keyup) state; '*' has been depressed since 1.902 seconds before the specified NTP time value, that is, the key was depressed at 36539656.098 seconds past the epoch. No multiple key instances exist. F4: Subscriber -> Notifier Culpepper/Cuninghame/Mule [Page 28]
Internet Draft SIP Key Events Package December 19, 2001 SIP/2.0 200 OK To: <sip:appl@appsrv.sp.com>;tag=2356 From: <sip:caller@isp.net>;tag=789 Call-Id: 321123@appsrv.sp.com CSeq: 403 NOTIFY Content-Length: 0 F5: Notifier -> Subscriber NOTIFY sip:appl@appsrv.sp.com SIP/2.0 To: <sip:appl@appsrv.sp.com>;tag=2356 From: <sip:caller@isp.net>;tag=789 Call-Id: 321123@appsrv.sp.com CSeq: 404 NOTIFY Contact: <sip:caller@isp.net> Event: key-event Content: application/key-event Content-Length: xx t: 36539663 2 s: key[65].keyup(17, 537) The Notifier reports that the 'A' key has been pressed and released. As the duration of depression was less that 1000ms, only the keyup state indication has been generated. In this case, the depression can be determined to have started at time 36539662.480 and lasted for 537ms. F6: Subscriber -> Notifier SIP/2.0 200 OK To: <sip:appl@appsrv.sp.com>;tag=2356 From: <sip:caller@isp.net>;tag=789 Call-Id: 321123@appsrv.sp.com CSeq: 404 NOTIFY Content-Length: 0 F7: Notifier -> Subscriber NOTIFY sip:appl@appsrv.sp.com SIP/2.0 To: <sip:appl@appsrv.sp.com>;tag=2356 From: <sip:caller@isp.net>;tag=789 Call-Id: 321123@appsrv.sp.com CSeq: 405 NOTIFY Contact: <sip:caller@isp.net> Event: key-event Content: application/key-event Content-Length: xx t: 36539668 2 s: key[49].keydown(-987) Culpepper/Cuninghame/Mule [Page 29]
Internet Draft SIP Key Events Package December 19, 2001 The Notifier reports that the '1' key was pressed at time 36539667.13. The keydown has been generated because the key has been depressed for more than 1000ms. In this example the NOTIFY request was actually generated at time 36539668.13 which explains the -987ms offset from the NTP time. F8: Subscriber -> Notifier SIP/2.0 200 OK To: <sip:appl@appsrv.sp.com>;tag=2356 From: <sip:caller@isp.net>;tag=789 Call-Id: 321123@appsrv.sp.com CSeq: 405 NOTIFY Content-Length: 0 F9: Notifier -> Subscriber NOTIFY sip:appl@appsrv.sp.com SIP/2.0 To: <sip:appl@appsrv.sp.com>;tag=2356 From: <sip:caller@isp.net>;tag=789 Call-Id: 321123@appsrv.sp.com CSeq: 406 NOTIFY Contact: <sip:caller@isp.net> Event: key-event Content: application/key-event Content-Length: xx t: 36539669 3 s: key[42].keyup(756, 13658) This notification indicates that the '*' key has eventually been released at time 36539669.756. The duration of depression is 13658 milliseconds; this value is consistent with the time of depression indicated in the initial (keydown) state indication of message F3. F10: Subscriber -> Notifier SIP/2.0 200 OK To: <sip:appl@appsrv.sp.com>;tag=2356 From: <sip:caller@isp.net>;tag=789 Call-Id: 321123@appsrv.sp.com CSeq: 406 NOTIFY Content-Length: 0 F11: Notifier -> Subscriber NOTIFY sip:appl@appsrv.sp.com SIP/2.0 To: <sip:appl@appsrv.sp.com>;tag=2356 From: <sip:caller@isp.net>;tag=789 Call-Id: 321123@appsrv.sp.com CSeq: 407 NOTIFY Contact: <sip:caller@isp.net> Culpepper/Cuninghame/Mule [Page 30]
Internet Draft SIP Key Events Package December 19, 2001 Event: key-event Content: application/key-event Content-Length: xx t: 36539672 4 e: key p: key[49].keyup(154, 5141) This notification indicates that the '1' key has been released at time 36539672.154. The duration of depression is 5141 milliseconds; this value is consistent with the time of depression indicated in the (keydown) state indication of message F7. F12: Subscriber -> Notifier SIP/2.0 200 OK To: <sip:appl@appsrv.sp.com>;tag=2356 From: <sip:caller@isp.net>;tag=789 Call-Id: 321123@appsrv.sp.com CSeq: 407 NOTIFY Content-Length: 0 F13: Subscriber -> Notifier SUBSCRIBE sip:caller@access-22.isp.net SIP/2.0 To: <sip:caller@isp.net>;tag=789 From: <sip:appl@appsrv.sp.com>;tag=2356 Call-Id: 321123@appsrv.sp.com CSeq: 3 SUBSCRIBE Contact: <sip:appl@appsrv.sp.com> Applies-To: call-id=8347-da8d-7657-ab32@192.144.22.1; local- tag=2342354556; remote-tag=00993k23ff8; attach=cspace Event: key-event Expires: 0 Content-Length: 0 The subscriber indicates it wishes to terminate the subscription. F14: Notifier -> Subscriber SIP/2.0 200 OK To: <sip:caller@isp.net>;tag=789 From: <sip:appl@appsrv.sp.com>;tag=2356 Call-Id: 321123@appsrv.sp.com CSeq: 3 SUBSCRIBE Contact: <sip:caller@isp.net> Expires: 0 Content-Length: 0 F15: Notifier -> Subscriber NOTIFY sip:appl@appsrv.sp.com SIP/2.0 Culpepper/Cuninghame/Mule [Page 31]
Internet Draft SIP Key Events Package December 19, 2001 To: <sip:appl@appsrv.sp.com>;tag=2356 From: <sip:caller@isp.net>;tag=789 Call-Id: 321123@appsrv.sp.com CSeq: 408 NOTIFY Contact: <sip:caller@isp.net> Subscription-Expires: 0 Content-Length: 0 As described in [1], the notifier must always send one NOTIFY request in response to any accepted SUBSCRIBE request. F16: Subscriber -> Notifier SIP/2.0 200 OK To: <sip:appl@appsrv.sp.com>;tag=2356 From: <sip:caller@isp.net>;tag=789 Call-Id: 321123@appsrv.sp.com CSeq: 408 NOTIFY Content-Length: 0 9. Security Considerations Key-Event Subscriptions are very likely to reveal sensitive information such as pin-numbers and destination numbers. Therefore, it is REQUIRED that devices accepting SUBSCRIBE requests perform some level of authentication before establishing a subscription. When such authentication is not provided by the network layer (e.g., IPSEC or private/trusted networks), then it MUST be provided by the transport-layer (e.g., TLS) or application-layer (e.g., SIP message/header authentication). Likewise, the information provided in the NOTIFY request is also likely to contain sensitive information and so the notifier MUST ensure that the NOTIFY requests are transported securely. Once again, this protection could be provided by the network-layer (e.g., IPSEC encryption or private networks), transport layer (e.g., TLS encryption) or application layer (e.g., S/MIME or SIP message body encryption). Alternatively, it is possible for the notifier to allow unsecured/unauthenticated subscribers to subscribe to key-events which will not divulge sensitive information. For instance, subscriptions to the "*" and "#" keys should not divulge sensitive information but may provide sufficient functionality for some 3pcc/B2BUA pre-paid calling card applications. 10. Minimal Implementation for Key-Event Server Devices Firstly, even a minimal implementation MUST address the security considerations described in the previous section. Culpepper/Cuninghame/Mule [Page 32]
Internet Draft SIP Key Events Package December 19, 2001 When a device does not have any user-defined keys, locally- configured names, multiple key instances or numbered buttons (e.g., a simple DTMF telephone dialpad) then the implementation can be made quite simple. In these cases the "exists" and "name" properties can be deemed OPTIONAL. Also, if remote configuration of "dwndly" is not required then the properties header line could be ignored completely. 11. Guidelines to Future Sub-Package Authors Future sub-packages must not duplicate key-events contained in existing sub-packages. If the relevant sub-package already exists then an extension for the existing sub-package should be proposed rather than a new sub- package. Once published as a standard, new key-event states or enumerated key-event sets MAY NOT be added to an existing sub-package. Only new key-event values and OPTIONAL key-event properties may be added to existing sub-packages. New sub-packages should reuse the states and properties of the existing sub-packages where possible. Appendix A. Dialog specific subscriptions, Applies-To Header The "Applies-To" SIP header is used in SIP requests to indicate the INVITE-initiated dialog that the request is associated with. One of its uses is in SUBSCRIBE and NOTIFY requests with which it is desired to associate a SUBSCRIBE dialog with an INVITE dialog or alternatively with the conversation space [5] associated with the dialog. The Applies-To header is based on the dialog attribute list defined in the SIP call-packages draft [8]. The approach described here for conveying dialog identification differs from that in [8] in that the dialog identification is placed in a message header (whereas [8] encodes this information into the event body itself). The reasons for this change are as follows: - It is desirable to keep the contents of the Key-Event message bodies to be protocol independent. - This approach represents a mechanism for identifying dialogs which is re-usable by many event packages rather than being event specific. - By separating subscription-filtering (SIP) from event processing (Event Package), a SIP device is able to reject subscription Culpepper/Cuninghame/Mule [Page 33]
Internet Draft SIP Key Events Package December 19, 2001 requests for unknown entities/dialogs to be rejected independently of the events requested. - Any interaction between the SIP call-control models and the dialog-specific subscriptions can be handled in an Event Package independent manner. A.1. Applies-To Header This table expands on tables 4 and 5 in RFC 2543 [3], as amended by the changes described in section 4.1 of [2]. Header field where enc e-e ACK BYE CAN INV OPT REG SUB NOT -------------------------------------------------------------------- Applies-To R e - - - - - - o - Applies-To r e - - - - - - - - The Applies-To header's presence indicates the subscription applies to the dialog specified. That is, when the header is present in a SUBSCRIBE it indicates the subscriber wishes to be notified of events that occur in conjunction with the specified dialog or conversation-space at the SIP device. It has the following semantics when used with a SUBSCRIBE request to establish a subscription dialog: - Subscriptions expire implicitly when the associated session dialog/conversation-space terminates. - State changes must only be reported for device events while the device is *actively* associated with the dialog/conversation-space subscribed to. [c.f., Section 3.1.1] If the subscriber places an Applies-To header in the initial SUBSCRIBE request then it MUST also be placed unchanged in all subsequent SUBSCRIBE requests, however, a notifier MUST ignore the Applies-To headers in all but the initial SUBSCRIBE request. [This allows a notifier to restart but ensures that the subscription does not change over time.] Applies-To = "Applies-To" ":" appliesto-component [ "," appliesto-component ] appliesto-component = "call-id" "=" Call-ID | "local-tag" "=" UUID | "remote-tag" "=" UUID | "attach" = ( "dialog" | "cspace" | token ) | future-extension No minimum set of components has been specified for the Applies-To header - it is the responsibility of the generator to ensure that the Applies-To header uniquely identifies a dialog on the target. For most cases it is RECOMMENDED that the Applies-To contains the call-id, local-tag and remote-tag components. The "attach" component indicates whether the subscription is associated to the dialog itself or to the conversation space to Culpepper/Cuninghame/Mule [Page 34]
Internet Draft SIP Key Events Package December 19, 2001 which the dialog currently belongs. The assumed value for the "attach" component (when not present) is "attach=dialog". A.2. Dialog Attached Mode In this mode, the subscription receives key-events from the user endpoint associated with the specified dialog endpoint whenever the user is *actively* communicating through that user endpoint. [An example of a user endpoint in this context could be a single virtual "line" on a multi-line SIP phone.] The subscription is terminated when the dialog is terminated. The RECOMMENDED subscription expiry timeout is on the order of a day. When a subscription is terminated due to dialog termination, the notifier MAY send a NOTIFY with "Subscription-Expires: 0" header however this is deemed unnecessary in most cases. A.3. Conversation Space Attached Mode Just as for dialog attached subscriptions, the subscription receives key-events from the user endpoint associated with the specified dialog endpoint (at the time of subscription) whenever the user is *actively* communicating through that user endpoint. However for conversation space attached dialogs, the subscription is terminated when the conversation space of the user endpoint is reduced to a conversation space containing only the user endpoint (or an empty conversation space). For instance, in this mode the subscription would *not* be terminated when an INVITE with a Replaces header was received from the network but would be terminated when all other participants leave a distributed conference. It is RECOMMENDED that the subscription expiry timeout SHOULD have a value ranging from minutes up to an hour. The notifier MUST send a NOTIFY with Subscription-Expires: 0 header when the subscription terminates. A.4 Handling of non-existent Applies-To dialogs. When a SUBSCRIBE request is received containing an Applies-To header referring to a non-existent dialog then a "481 Applies-To Call Leg Does Not Exist" error response should be sent. IANA Considerations Guidelines for registering key event packages with IANA will be completed in a future draft revision. Authors Robert Fairlie-Cuninghame Nuera Communications, Inc. 50 Victoria Rd Farnborough, Hants GU14-7PG Culpepper/Cuninghame/Mule [Page 35]
Internet Draft SIP Key Events Package December 19, 2001 United Kingdom Phone: +44-1252-548200 Email: rfairlie@nuera.com Bert Culpepper InterVoice-Brite, Inc. 701 International Parkway Heathrow, FL 32746 Phone: 407-357-1536 Email: bert.culpepper@intervoice-brite.com Jean-Francois Mule Email: jfmule@packetizer.com References 1 S. Bradner, "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996. 2 A. Roach, "SIP-Specific Event Notification", Internet-Draft draft-ietf-sip-events-01, November 2001, Work in progress. 3 M. Handley, H. Schulzrinne, E. Schooler, and J. Rosenberg, "SIP: Session Initiation Protocol", RFC 2543, March 1999. 4 H. Schulzrinne, S. Petrack, "RTP Payload for DTMF Digits, Telephony Tones and Telephony Signals", RFC 2833, May 2000. 5 R. Mahy, "A Call Control Model for SIP", Internet-Draft, November 2001, Work in progress. 6 D. Mills, "Network Time Protocol (Version 3)", RFC1305, March 1992. 7 The Unicode Consortium, "The Unicode Standard -- Version 3.0", ISBN 0-201-61633-5. Described at http://www.unicode.org/unicode/standard/versions/Unicode3.0.html 8 J. Rosenberg and H. Schulzrinne, "SIP Event Packages for Call Leg and Conference State", Internet-Draft, July 13, 2001, Work in progress. Culpepper/Cuninghame/Mule [Page 36]