idnits 2.17.1 draft-culpepper-sip-key-events-01.txt: -(322): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1386): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1603): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == There are 14 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 2 longer pages, the longest (page 40) being 63 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 558: '... property is NOT REQUIRED unless expli...' RFC 2119 keyword, line 606: '... Support: RECOMMENDED...' RFC 2119 keyword, line 620: '... Support: RECOMMENDED...' RFC 2119 keyword, line 637: '... Support: OPTIONAL...' RFC 2119 keyword, line 778: '...mitted. Parsers MUST be tolerant of s...' (36 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 1, 2002) is 8092 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '1' on line 1918 looks like a reference -- Missing reference section? '2' on line 1963 looks like a reference -- Missing reference section? '3' on line 1423 looks like a reference -- Missing reference section? '4' on line 206 looks like a reference -- Missing reference section? '5' on line 350 looks like a reference -- Missing reference section? '49' on line 1868 looks like a reference -- Missing reference section? '7' on line 1016 looks like a reference -- Missing reference section? '6' on line 803 looks like a reference -- Missing reference section? '48-57' on line 917 looks like a reference -- Missing reference section? '8' on line 917 looks like a reference -- Missing reference section? '10' on line 1088 looks like a reference -- Missing reference section? '47-58' on line 1120 looks like a reference -- Missing reference section? '35' on line 1088 looks like a reference -- Missing reference section? '47' on line 1121 looks like a reference -- Missing reference section? '48' on line 1121 looks like a reference -- Missing reference section? '42' on line 1838 looks like a reference -- Missing reference section? '65' on line 1779 looks like a reference -- Missing reference section? 'RFC' on line 1990 looks like a reference -- Missing reference section? 'BC' on line 1991 looks like a reference -- Missing reference section? 'JFM' on line 1992 looks like a reference Summary: 4 errors (**), 0 flaws (~~), 4 warnings (==), 24 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Draft Bert Culpepper 3 draft-culpepper-sip-key-events-01.txt InterVoice-Brite, Inc. 4 March 1, 2002 5 Expires: September, 2002 Robert Fairlie-Cuninghame 6 Nuera Communications, Inc. 8 Jean-Francois Mule 9 CableLabs 11 SIP Event Package for Keys 13 Status of this Memo 15 This document is an Internet-Draft and is in full conformance with 16 all provisions of Section 10 of RFC2026 [1]. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six 24 months and may be updated, replaced, or obsoleted by other documents 25 at any time. It is inappropriate to use Internet- Drafts as 26 reference material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This particular draft is intended to be discussed in the SIPPING 35 Working Group. Discussion of it therefore belongs on that list. The 36 charter for SIPPING working group may be found at 37 http://www.ietf.org/html.charters/sipping-charter.html 39 Abstract 41 This document defines a protocol independent message format for 42 requesting and reporting state related to keys or buttons. The 43 document also defines a SIP Event Package to make use of this 44 extensible framework through the SIP SUBSCRIBE & NOTIFY messages. 45 The draft currently defines key event sub-packages to represent the 46 state of telephone dial pads, feature buttons found on many 47 commercial telephones, standard keyboards as well as support for 48 user or device specific buttons (for instance, a "Double Latte" 49 button). The event package and associated key packages can be used 50 to enable new SIP services where an application or SIP entity 51 requires notification of user interface activity either associated 52 with a particular SIP session or simply in relation to the device 53 itself. 55 Table of Contents 57 0. Changes since draft-culpepper-key-events-00....................3 58 1. Introduction...................................................4 59 2. Motivation/Use Cases...........................................4 60 2.1. Relation To Telephony Tones And Events.........................6 61 2.2. Example Usage Scenarios........................................6 62 2.2.1. Example 1: Application Server acting as B2BUA/3pcc........6 63 2.2.2. Example 2: Application Server Acting As A Proxy...........7 64 2.3. SIP Call-Control Interaction...................................8 65 Part A -- Introducing a protocol independent Key-Event message format.8 66 3. Terminology....................................................8 67 4. Key-Event Messages.............................................9 68 5. Key Representations...........................................10 69 6. Key-Event Framework...........................................11 70 7. Key-Event Sub-Package Definitions.............................11 71 7.1. Shared Key-Event States and Properties........................12 72 7.2. Key Sub-package...............................................13 73 7.3. Keyboard Sub-Package..........................................14 74 7.4. Telephone Sub-Package.........................................15 75 7.5. User Package..................................................15 76 8. Key-Event Message Body Format.................................16 77 8.1. Time-Header Format............................................16 78 8.2. Instance-Header Format........................................17 79 8.3. Event-Header Format...........................................17 80 8.4. Properties-Header Format......................................18 81 8.5. State-Header Format...........................................20 82 9. Key-Event Message Generation..................................20 83 9.1. Generating a Session Request message..........................20 84 9.2. Generating a Session Response message.........................21 85 9.2.1. Event Header Processing..................................21 86 9.2.2. Properties Header Processing.............................22 87 9.2.3. State Header Processing..................................22 88 9.3. Generating Key-Event Notification messages....................22 89 10. Minimal Implementation for Key-Event Notifiers................23 90 11. Guidelines to Future Sub-Package Authors......................23 91 12. MIME type information for the Key-Event Message Format........23 92 Part B -- The use of SIP SUBSCRIBE & NOTIFY for Key-Event Transport..24 93 13. Subscription to Key Events....................................24 94 13.1. Non-Dialog Specific Subscriptions..........................24 95 13.2. Dialog Specific Subscriptions..............................25 96 13.2.1. Dialog Attached Mode...................................25 97 13.2.2. Conversation Space Attached Mode.......................25 98 13.2.3. Multi-dialog Capable Endpoints.........................25 99 13.2.4. "Early" Dialog Subscriptions...........................26 100 13.2.5. Multiple Subscriptions.................................26 101 14. Instance-Header format for SIP Dialog Specific Subscriptions..27 102 15. SIP specific Key-Event error handling.........................27 103 15.1. Handling of unacceptable instance-header values............27 104 15.2. Handling of unknown key-event-set enumerations.............28 105 16. Event Package Definition......................................28 106 16.1. Event Package Name.........................................28 107 16.2. Event Package Parameters...................................28 108 16.3. SUBSCRIBE Bodies...........................................28 109 16.4. Subscription Duration......................................29 110 16.5. NOTIFY Bodies..............................................29 111 16.6. Notifier Processing of SUBSCRIBE Requests..................29 112 16.7. Notifier Generation of NOTIFY Requests.....................30 113 16.7.1. Generating Initial NOTIFY Requests.....................30 114 16.7.2. Generating Subsequent NOTIFY Requests..................30 115 16.8. Subscriber Processing of NOTIFY Requests...................30 116 16.9. Subscriber Generation of SUBSCRIBE Requests................31 117 16.10. Pre-loaded Routes in SUBSCRIBE requests....................31 118 16.11. Handling of Forked Subscriptions...........................32 119 16.12. Rate of Notifications......................................32 120 17. Examples......................................................32 121 18. Security Considerations.......................................38 122 19. IANA Considerations...........................................38 123 19.1. Key-Event Package Registration.............................38 124 19.2. Key-Event Sub-Package Registration.........................39 125 20. Authors.......................................................39 126 21. References....................................................40 128 0. Changes since draft-culpepper-key-events-00 130 - Substantial reorganization of draft. The draft is now split into 131 two parts: a protocol independent Key-Event Message Format section 132 and a SIP Events specific section. This allows other authors to 133 write transport profiles for other protocols. 135 - Removed Applies-To header and replaced it will a protocol 136 dependent hole in the application/key-event message body 137 (instance-header). 139 - Updated to reflect draft-ietf-sip-events-04 changes. 141 1. Introduction 143 As stated in SIP-specific Event Notification [2], the SIP SUBSCRIBE 144 and NOTIFY methods provide a mechanism by which cooperating SIP [3] 145 endpoints can request and receive asynchronous notification of 146 changes in state related to network resources and calls. This 147 mechanism, when combined with an event package for keys, can be used 148 for requesting and reporting the status of keys and keypads 149 associated with SIP user agents or indeed any SIP device. 151 Communication sessions many times are used as a means to access and 152 deliver services to users. The operation and use of these services 153 almost always require some user interaction with the service. One 154 of the primary means for user interactions with services when using 155 the legacy circuit-switched telecommunications network is via tones 156 generated as a result of a key press on the communications device. 157 While tones can be used in the same manner in IP networks, their 158 use, given the distributed nature of the network, is sub-optimal. 159 In addition, their use limits the user interface of many user 160 devices as well as the range of application services possible. It 161 is for these reasons that a means to transport key presses is 162 needed. 164 2. Motivation/Use Cases 166 The first and foremost motivation for this proposal is to extend the 167 possibility for user interaction beyond the antiquated telephone 168 dialpad model imposed by limiting interaction to DTMF tones. The 169 proposal is designed to support full keyboards, multiple key 170 instances, user- or device-specific buttons (for instance, a "Double 171 Latte" button). It also aims to provide an extensible framework to 172 allow volume controls, multi-position switches or any other user 173 interface widget to be defined in future Key Event Packages. A 174 secondary goal of the proposal is that devices possessing a simple 175 user interface (such as telephone dialpad) need only implement a 176 smaller subset of the full proposal without losing any 177 interoperability with Application Servers (c.f., section 10). 179 DTMF has been used in telephony networks as a means for users of 180 network services to provide input and some control of those 181 services. DTMF is also used to signal connection destinations in 182 these networks. This dual role of DTMF does not present problems in 183 circuit-switched networks. However, with telecommunications move to 184 packet networks, separation of these roles is needed. Packet 185 networks enable communications and related services to be deployed 186 in a distributed architecture. An alternative to DTMF for "user 187 input" is needed in order to better support the distributed 188 application architecture possible in IP networks. 190 Although a standard mechanism exists for the transport of DTMF tones 191 in IP networks, using it for user input and/or dynamic application 192 control as is done in the PSTN does not carry over into the IP 193 network very well. Receiving tones via RTP is problematic for the 194 detector/generator devices in scenarios where multiple network 195 entities are interested in the events. Replicating media to 196 multiple destinations is not a common feature of endpoints. In 197 addition, the SDP session description to set up media replication is 198 more complicated than that required to set up typical multi-media 199 communications sessions. 201 The mechanism defined here can be used as an alternative to DTMF 202 detection when the detection of these tones is to gather input from 203 a user or provide some user application control independent of any 204 end-to-end media path. The relationship of the mechanism described 205 in this specification to the transport of telephony tones via RTP 206 defined in RFC 2833 [4] is further described in Section 2.1. 208 It is intended that the event notification mechanism defined in this 209 document might be used in scenarios that have the following 210 attributes or requirements: 212 - The amount of data to be conveyed is very small compared to the 213 audio, video, text, etc. data in a session. 214 - Dynamic user control of applications is required. 215 - Collecting device input is needed when the device is not engaged 216 in a session. 217 - Security concerns exist due to multiplication attack possible with 218 DTMF forking. 219 - End-to-end security/privacy between caller and destination system 220 is required. 221 - Multiple Application Servers may be involved along the end-to-end 222 call signaling path. 223 - Authentication and/or Privacy of key sequences between an 224 Application Server and an endpoint is desired. 225 - Reliable delivery of key sequences is required even when short 226 periods of network connectivity problems occur. 227 - Support for a device with a user interface consisting of more than 228 a simple keypad is required. 230 A network entity subscribing to key events at another network entity 231 may be interested in the events as they relate to an established 232 communications session or as they relate to the device itself. Many 233 network-based communications services require the user to identify 234 themselves (for instance, by the user providing a PIN). Pre-paid 235 and post-paid calling card services are a good example where a call- 236 associated event subscription is useful. Key event subscriptions 237 can also be useful outside of communications sessions. For example, 238 an endpoint (SIP phone) may have a dedicated key used to 239 asynchronously invoke some function on a remote network entity. In 240 this case, the remote network entity subscribes to key events at the 241 SIP phone in a non-dialog specific manner. When a key event of 242 interest occurs, the remote endpoint can act on the event. RFC 2833 243 does not support notification of key events outside of the context 244 of an established session. 246 2.1. Relation To Telephony Tones And Events 248 RFC 2833 defines an RTP payload format for telephony tones and 249 signals (including DTMF digits). It allows the transport of such 250 events in the context of an established media session (in SIP, a 251 session must be established with media description in order for 252 endpoints to exchange RFC 2833 events or tones). This mechanism has 253 several advantages: it is independent from any signaling protocol 254 and can be used with SIP, MEGACO, MGCP and other protocols, it 255 eliminates tone distortion, and it provides a reliable means for 256 telephony endpoints to exchange telephony tones within RTP media 257 flows. 259 The purpose of the current document is to provide a general 260 mechanism for SIP entities to request and report the notifications 261 of key events (including keys in keypads or any kind of keyboards). 262 This mechanism is specific to the SIP protocol and is based on SIP 263 events (although the actual Key-Event Message Format is defined in a 264 protocol independent manner). It offers several advantages: 266 - SIP application servers not involved in the media path can now 267 request and receive key state changes. 268 - SIP entities supporting SUBSCRIBE/NOTIFY now have a generic 269 mechanism to exchange key states. 270 - It allows multiple SIP application servers to receive independent 271 key event notification with each application server only receiving 272 notifications for the key-events that it is interested in. 274 In conclusion, this mechanism can be used in conjunction with RFC 275 2833 or it can also serve as an alternative to RFC 2833 in the cases 276 where: 278 - Key states beyond telephony tones and signals are desired. 279 - A means for simple SIP telephony applications such as software 280 phones or applications, not necessarily able to generate telephony 281 tones, is needed to interact with applications. 282 - IP telephony gateways wish to conserve DSP resources. 283 - Supporting RFC 2833 for the sole purpose of indicating key 284 presses, or supporting the duplication of RFC 2833 RTP payload 285 events to the signaling planes, is not desirable. 287 2.2. Example Usage Scenarios 289 As discussed in the previous section, the scenarios described in 290 this section do not preclude the presence of tone data associated 291 with a telephone keypad. Specifically, RFC 2833 may still be 292 employed as an end-to-end media-layer transport mechanism for DTMF 293 tones, that is, as an end-to-end transport mechanism between the 294 caller and destination User Agent. 296 2.2.1. Example 1: Application Server acting as B2BUA/3pcc 297 In this example the Application Server (AS) will generate the INVITE 298 and BYE requests to perform call control. Due to the nature of this 299 model, the AS can always inherently ensure that it remains on the 300 call signaling path for the duration of the session. The general 301 B2BUA network model is shown in Figure 1. 303 Caller AS Callee 304 +--------+ +---------+ +--------+ 305 | UAC |<--- SIP --->| UAS/UAC |<--- SIP --->| UAS | 306 +--------+ +---------+ +--------+ 307 | | 308 +-------------------- RTP ---------------------+ 310 Figure 1. Application Server (B2BUA/3pcc) Model 312 The above figure depicts a caller establishing a session with the 313 AS, after which the AS establishes a session with the callee. The 314 AS provides one endpoint�s session description to the other 315 endpoint. This results in the media being exchanged between the two 316 endpoints and the SIP signaling occurring between the AS and each 317 endpoint. 319 In this scenario, it is desired for the caller and callee to be able 320 to invoke application services & features by pressing keys on the 321 terminal. The action required by the AS is simple: it sends a 322 SUBSCRIBE to the caller�s and/or callee�s User-Agent as described in 323 section 16.9. The subscription request should be dialog specific. 324 Now the Application Server will receive all endpoint Key Events for 325 the duration of the subscription. 327 2.2.2. Example 2: Application Server Acting As A Proxy. 329 In this scenario, the Application Server normally functions as a SIP 330 proxy. The application is co-located with the SIP proxy and may 331 also function as a SIP UA if desired. The network model is shown in 332 Figure 2 below. 334 Caller AS AS Callee 335 +------+ +-------+ +-------+ +------+ 336 | UAC |<-- SIP -->| Proxy |<-- SIP -->| Proxy |<-- SIP -->| UAS | 337 +------+ +-------+ +-------+ +------+ 338 | | 339 +--------------------------- RTP --------------------------+ 341 Figure 2. Application Server (Proxy) Model 343 Any proxy that wants to stay in the signaling path inserts a Record- 344 Route header into the session establishment request. The Record- 345 Route mechanism will ensure the Proxy/AS sees all SIP requests and 346 responses for the dialog established between the caller and callee. 347 Applications deployed using this model do not manage user sessions 348 as a user agent but rather exert call-control over the INVITE dialog 349 and/or conversation space [5] using, for instance, the call control 350 primitives and framework defined in [5] or using some other external 351 mechanism. 353 In this usage example the Application Server desires to take action 354 after a certain sequence of key events occurs during a session. So 355 after possibly record-routing the caller�s initial INVITE request 356 and forwarding it to the destination system, the AS will send a 357 dialog specific subscription request to the desired User-Agents as 358 described in Section 16.7 (and as for example 1). This allows any 359 and all SIP proxies/AS in the signaling path to receive key-event 360 notifications independently of any other SIP proxy/AS. 362 2.3. SIP Call-Control Interaction 364 The Key Event Package allows multiple network entities to subscribe 365 to key events for the same SIP session on the same device. Due to 366 this fact, it is possible for multiple Application Servers to take 367 part in the same call and thus the interaction between the servers 368 must be considered. 370 However, solving the problems of multiple AS interaction is beyond 371 the scope of this document. This document simply defines a 372 mechanism whereby Applications can monitor key events on a network 373 device - it is does not specify the call-control mechanisms used by 374 participating entities. Different call control models will have 375 different interaction characteristics. 377 Part A -- Introducing a protocol independent Key-Event message format 379 The following section introduces a transport protocol independent 380 message format for the requesting and transport of Key-Events. Part 381 A of this draft is intentionally protocol neutral such that the 382 resulting message format is adaptable to any reliable, bi- 383 directional transport mechanism. Part B of this draft details the 384 use of Part A within the context of a SIP Event Package [2] using 385 the SIP SUBSCRIBE and NOTIFY methods (an example of a transport 386 mechanism profile). If there is sufficient non-SIP related interest, 387 Part A will be split out into separate internet draft. 389 The message format presented in Part A does not specify a complete 390 protocol. However, the combination of the Key-Event Message Format 391 and the transport mechanism profile (Part B) should specify a 392 complete protocol. 394 When the Key-Event Messages are transported as MIME message bodies, 395 the MIME content type for this message format is "application/key- 396 event" and is officially defined in section 12. 398 3. Terminology 400 To avoid confusion and to maintain a protocol neutral terminology, 401 the following terms will be used in this section of the document. 403 Requestor: the entity requesting Key-Event notification from a target 404 entity (the Notifier). 406 Notifier: the entity to which the Requestor is requesting to be 407 notified of Key-Events. 409 Transport Mechanism: The protocol mechanism used to reliably route 410 and deliver messages between the Requestor and Notifier. It is the 411 responsibility of the transport mechanism to inform the Requestor 412 and Notifier when a Key-Event Session is terminated due to network 413 or endpoint failure. The transport mechanism should also provide a 414 mechanism whereby the Notifier (and optionally the Requestor) can 415 indicate its desire to terminate an active Key-Event Session. The 416 transport mechanism is not prescribed by the Key-Event Message 417 Format. 419 Subscription: the state information held by the Notifier regarding 420 the key event notifications successfully requested by a particular 421 Requestor. 423 Key-Event Session: the time period when a subscription for key-events 424 has been established (or in the process of being established). 426 4. Key-Event Messages 428 The Key-Event Message Format consists of the following three message 429 types: 431 Key-Event Session Request: The Requestor sends a Session Request to 432 the Notifier to request key-event notification and/or determine a 433 Notifier�s capabilities. In effect the Session Request creates a 434 subscription to a set of key-events for which the Notifier will 435 send notifications. 437 Key-Event Session Response: The Notifier, in response to a Session 438 Request will send this message to indicate the full state of the 439 subscription created by the Session Request and the current full 440 state of all subscribed key-events. 442 Key-Event Notification: A Notifier normally sends a Notification 443 whenever the state of any subscribed key-event changes. Each 444 notification contains a state delta from the previous Key-Event 445 Notification message. 447 A typical Key-Event Session message flow: 449 Requestor Notifier 450 | | 451 | Session Request | 452 |---------------------->| 453 | Session Response | 454 |<----------------------| 455 | | 456 | Notification | 457 |<----------------------| 458 | Notification Ack | 459 |---------------------->| 460 | | 461 | Notification | 462 |<----------------------| 463 | Notification Ack | 464 |---------------------->| 465 | | 467 A Key-Event Session can be renegotiated or terminated by the 468 Requestor by sending another Session Request message. This Session 469 Request message replaces all state established by the previous 470 Session Request and will always solicit a Session Response. A Session 471 Request with no requested events terminates a Key-Event Session. 473 5. Key Representations 475 The representation of keys in the key-event message format has been 476 designed around a few central philosophies. 478 Firstly, all keys that represent the same information must map to 479 the same key-event. For instance, a key representing "1" on a 480 keyboard, keypad, telephone, or vending machine will all map to the 481 same key event; likewise, multiple equivalent keys (e.g., left and 482 right shift keys) will also map to the same key-event. The key- 483 event package does however allow an optional positional indicator to 484 indicate the origin of a particular key event (if multiple 485 equivalent keys are present). The value can be ignored if desired. 486 This arrangement avoids the situation where an application must 487 observe a (possibly unknown) set of equivalent key events. 489 The positional indicator values currently defined are "alt" 490 (alternate) & "keypad" as well as the assumed "pri" (primary) key 491 position. When a keyboard has two or more equivalent keys, one is 492 always defined to be the primary key and the others are defined to 493 be the alternate/keypad positions. For Shift, Ctrl, Alt and similar 494 equivalent keys, the bottom-left most key is defined to be the 495 primary key. If a device has only one instance of a particular key 496 it is always regarded as the primary key regardless of its physical 497 position. 499 The second design philosophy is that the event package is 500 independent of key-cap arrangements on keyboards. A keyboard is 501 represented by two distinct sub-packages: one sub-package represents 502 all characters that are accessible on the keyboard, the second sub- 503 package represents all non-character based keys, for instance, 504 Shift, Caps Lock, Insert, Up, Alt, Pause. [For historical reasons 505 Backspace, Delete, Enter/Carriage-Return & Escape have character 506 representations.] This, for example, means that the representation 507 of capital Q (i.e., 'Q') is independent of the Shift key event. 509 Lastly, all basic keys were designed to have two possible states: up 510 or down. Key presses are signaled by notifying the requestor when a 511 key transitions into a new state ("keyup" or "keydown" state 512 events). Each state notification is accompanied by state specific 513 information such as key depression start time. The key-event 514 package states have been arranged such that a "keyup" state event 515 includes both key release event time as well as duration of the 516 depression. 518 This arrangement allows the "keydown" state event to be seamlessly 519 delayed or omitted by the Notifier and/or ignored by the Requestor. 520 The role of the "keydown" event is to provide rapid notification of 521 key depression. For many applications, the "keydown" event 522 notification is only useful for prolonged key depressions. The key- 523 event package provides a useful mechanism whereby a Requestor 524 application can delay "keydown" notifications to achieve a 525 compromise between key response times and reduced bandwidth (1 or 2 526 notify messages per key depression and release). [c.f., Section 7.1 527 "dwndly" property.] 529 6. Key-Event Framework 531 The Key-Event Message Format does not in itself define key events 532 but rather defines the framework for specifying "Key-Event Sub- 533 Packages". Each Key-Event Sub-Package defines the key-events that 534 make up the sub-package along with the states and properties that 535 the constituent key-events may possess. 537 In section 7, this document defines Key-Event Sub-Packages for 538 standard keyboards, telephones and user-defined buttons. Section 11 539 provides guidelines for future sup-package authors. 541 7. Key-Event Sub-Package Definitions 543 All Key-Event Sub-Package definitions consist of the following 544 components: 546 Sub-Package Name: The name of the sub-package as used in messages. 548 Key-Event Values: This list defines the set of valid key-events of 549 the sub-package. A key-event can have either a numeric value (e.g., 550 49) or a non-numeric value (e.g., shift). 552 Key-Event States: This component defines the set of states that key- 553 events in the sub-package can have (e.g., keyup or keydown). The 554 sub-package must also define a default state. 556 Key-Event Properties: This list defines any configurable or 557 retrievable properties held by the key-events. Support for any 558 particular sub-package property is NOT REQUIRED unless explicitly 559 stated in the sub-package description. 561 Enumerated Key-Event Sets: In order to simplify subscription, the 562 sub-package can define a number of enumerated key-event sets. These 563 enumerations are entirely equivalent to the set of key-events they 564 represent (e.g., @dialpad = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, * and 565 #} found on common telephones). 567 By design, all key-events in a sub-package share the same states and 568 properties. 570 7.1. Shared Key-Event States and Properties 572 All currently defined sub-packages in this document share the 573 following state and property definitions. 575 These definitions have been grouped together for clarity however the 576 definitions still belong to the individual Key-Event Sub-Packages. 577 Future sub-packages may define additional states and/or properties; 578 future sub-packages are also not forced to use existing key-event 579 states and properties if they do not make sense within a new sub- 580 package (e.g., for a slider/dimmer control). (c.f., Section 11 for 581 further guidelines.) 583 Key-Event States: 585 - "keydown" 586 State Parameters: 587 * Start Time of Key Depression: Milliseconds offset from the 588 event-time NTP value specified in the Time-header. Negative 589 values are allowed. 591 - "keyup" 592 State Parameters: 593 * Time of Key Release: Milliseconds offset from the event-time 594 NTP value specified in the Time-header. Negative values are 595 allowed. 596 * Duration of Key Depression: Millisecond duration of key 597 depression. 599 Key-Event Properties: 601 - "exists" 602 Request Parameters: none 603 Response Result: positional-indicator *("," positional-indicator) 604 [List of non-primary key instances.] 605 Default value: N/A 606 Support: RECOMMENDED 607 Description: Determines which non-primary key-events exist. 608 e.g., "p: key[49].exists()" may yield a result of 609 "p: key[49].exists(keypad)" which indicate that two '1' keys 610 exists: a primary key instance and a keypad key instance. 611 Note: This property only produces a result for key-events 612 possessing non-primary key positions. 614 - "name" 615 Request Parameters: none 616 Response Result: positional-indicator "=" quoted-string 617 *( "," positional-indicator "=" quoted-string ) 618 [Lists of names for all key instances.] 619 Default value: N/A 620 Support: RECOMMENDED 621 Description: 622 The property when requested (e.g., "p: keybd[49].name()" ) 623 returns the printable name of the key-event in the Session 624 Response result (e.g., "key[49].name(pri="1", keypad="Keypad 625 1")" ). 626 The description should be sufficiently detailed such that a 627 user would be able to identify the key from the description. 628 This property can also very useful when the name of the key 629 is configured locally, for instance, a Session Request for 630 "phone[line:*].name()" could conceivably yield a result of 631 "phone[line:1].name(pri="Reception")". 633 - "dwndly": (DownDelay) 634 Request Parameters: 1*DIGIT (milliseconds delay) 635 Response Result: 1*DIGIT (milliseconds delay) 636 Default value: 0 637 Support: OPTIONAL 638 Description: Milliseconds delay that Notifier should/will 639 wait before generating a "keydown" state event after a key is 640 depressed. If the key is raised before this duration elapses 641 then only the "keyup" state event will be generated. This 642 allows a tradeoff between key responsiveness (for longer 643 keypresses) and the number of Key-Event Notification messages 644 per keypress. The Session Response result contains a 645 confirmation of the new value. 646 This value (and any change thereof) is local to the Key-Event 647 Session in which it is requested. 649 7.2. Key Sub-package 651 Sub-Package Name: "key" 653 Key-Event Values: Decimal Unicode values [7]. 655 Key-Event States: keydown, keyup (default) 657 Key-Event Properties: name, exists, dwndly 659 Enumerated Key Event Sets: 660 - "@dialpad" = "35,42,48-57" 661 This set represents a standard telephone dialpad: 0-9, *, #. 662 - "@uslatin" = "9-10,32-126" 663 This set represents the printable and white space character 664 key set found on a typical US keyboard (which is a subset of 665 most other keyboards). 666 - "@uslatin2" = "8-10,27,32-127" 667 This set is similar to @uslatin but also includes the non- 668 printable backspace, delete & escape keyboard characters (see 669 notes below). 671 Notes: 672 For mainly historical reasons, the following keys belong to 673 the key sub-package rather than the keybd sub-package: 674 - Backspace: 8 675 - Tab: 9 676 - Enter: (treated as unix '\n') 10 677 - Escape: 27 678 - Delete: 127 680 7.3. Keyboard Sub-Package 682 Sub-Package Name: "keybd" 684 Key-Event Values: 685 "shift": name="Shift" (or "Left/Right Shift" if applicable) 686 "caps": name= "Caps Lock" 687 "ctrl": name="Control" 688 "alt": name="Alt" 689 "home": name="Home" 690 "end" : name="End" 691 "insert": name="Insert" 692 "pgup": name="Page Up" 693 "pgdn": name="Page Down" 694 "up": name="Up" 695 "dn": name="Down" 696 "right": name="Right" 697 "left": name="Left" 698 "pause": name="Pause" 699 "numlk": name="Num Lock" 700 "scrlk": name="Scroll Lock" 701 "prtsc": name="Print Screen" 702 "break": name="Break" 703 + "func:*": name="Function Key x" 704 + "os:*": name= 705 + "vendor:*": name= 707 + Key-events of the form "keyname:*" allow for multiple 708 numbered keys to exist. These key-events must be always be 709 used in this numbered key form (e.g., "func:3"). 711 Notes: 712 The names provided for the Key-Event Values should be only 713 regarded as examples. The actual Key Event Name should be 714 sufficient to locate the individual key on the device 715 (including the case when there are multiple key instances). 717 Key-Event States: keydown, keyup (default) 719 Key-Event Properties: name, exists, dwndly 720 Enumerated Key-Event Sets: 721 - "@basic" = "shift, caps, ctrl, alt, home, end, insert, pgdn, 722 pgup, up, dn, right, left" 723 (basic keyboard) 724 - "@std" = "shift, caps, ctrl, alt, home, end, insert, pgdn, 725 pgup, up, dn, right, left, pause, numlk, scrlk, prtsc, 726 break" 727 (standard keyboard) 729 7.4. Telephone Sub-Package 731 Sub-Package Name: "phone" 733 Key-Event Values: 734 "hook": name = "Hookswitch" 735 Notes: The state of this button is actually the opposite of 736 the hook switch, that is, the "keyup" state represents the 737 on-hook condition. Normally this key-event would only be 738 available in non-dialog specific subscriptions. 739 "hold": name = "Hold" 740 "conf": name = "Conference" 741 "flash": name = "Flash" 742 "redial": name = "Redial" 743 "transfer": name = "Transfer" 744 + "line:*": name = "Line x" or locally defined 745 + "speed:*": name = "Speed Dial x" or locally defined 746 + "vendor:*": name = 748 + Key-events of the form "keyname:*" allow for multiple 749 numbered keys to exist. These key-events must be always be 750 used in this numbered key form. 752 Key-Event States: keydown, keyup (default) 754 Key-Event Properties: name, exists, dwndly 756 Enumerated Key-Event Sets: None. 758 7.5. User Package 760 This sub-package intentionally does not define any key-event values. 761 This package is designed as a sub-package available for any device 762 or user specific key-events and properties. 764 Key-Event Values: None. (see note) 766 Key-Event States: keydown, keyup (default) 768 Key-Event Properties: name, exists, dwndly 770 Enumerated Key-Event Sets: None. (see note) 772 8. Key-Event Message Body Format 774 A Key-Event message body consists of a set of UTF8 header lines. 775 The header lines resemble HTTP header formats however for efficiency 776 all header, sub-package, property, state and key-event names are 777 case-sensitive and multiple headers of the same type are not 778 permitted. Parsers MUST be tolerant of spaces between header 779 tokens. 781 key-event-message = time-header CRLF 782 [ instance-header CRLF ] 783 [ event-header CRLF ] 784 [ properties-header CRLF ] 785 [ state-header CRLF ] 786 [ future-extension-header CRLF ] 788 The individual key-event headers may appear in Key-Event messages as 789 detailed in the following table: 791 Key-Event Header Request Response Notification 792 ---------------- ------- -------- ------------ 793 Time-Header (t:) m m m 794 Instance-Header (i:) o - - 795 Event-Header (e:) m m - 796 Properties-Header (p:) o o - 797 State-Header (s:) - o m 799 m = mandatory; o = optional; otherwise, the header is not allowed. 801 8.1. Time-Header Format 803 The time-header indicates the NTP time [6] that the event message 804 was first issued and a message sequence number. 806 The exact starting/ending time of an event often requires greater 807 granularity than is provided by NTP values (in seconds) and so key- 808 event state transitions also include a millisecond offset that is 809 added to this NTP time value. It must also be remembered that the 810 time a key-event message is generated may not always be the same as 811 the time of the actual key-event event (for instance, initial state 812 indications). 814 The sequence number allows the key-event message bodies to be 815 sequenced independently of the transport protocol. 817 time-header = "t:" event-time sequence-number 818 event-time = 1*DIGIT 819 sequence-number = 1*DIGIT 821 The event-time is set equal to the NTP time value when the message 822 body was first issued. The sequence-number is a 32-bit non-zero 823 integer that is incremented each time a new message is generated 824 within each key-event session. The sequence number spaces for the 825 Requestor and Notifier are independent. 827 Examples: 829 t: 36539655 1 831 8.2. Instance-Header Format 833 This optional header allows for a protocol specific identifier to be 834 placed in a Session Request message to identify the target endpoint 835 instance (and association parameters) when the transport mechanism 836 cannot provide such functionality. 838 instance-header = "i:" *( ";" | "/" | "?" | ":" | "@" | "&" | "=" 839 | "+" | "$" | SP | TAB | unreserved | escaped ) 841 The header�s format and interpretation must be specified in the 842 transport mechanism profile if used. 844 8.3. Event-Header Format 846 The event-header allows the Requestor to request a set of key-events 847 and the Notifier to confirm/indicate the set of key-events 848 subscribed/supported. 850 The event-header in a Session Request is used to request a 851 subscription to a set of key events. The event header in a Session 852 Response is used to indicate the actual set of subscribed key 853 events. 855 event-header = "e:" [ ( event-set ( "," event-set ) ) | "*" ] 856 event-set = sub-package-name [ key-event-list ] 857 sub-package-name = token 858 key-event-list = "[" key-event-set *( "," key-event-set ) "]" 859 key-event-set = key-event-identifier | key-event-range | 860 enumerated-key-event-set 861 key-event-identifier = key-event-name | key-event-value | 862 key-event-numid | key-event-numidwild 863 key-event-name = token 864 key-event-value = 1*DIGIT 865 key-event-numid = token ":" 1*DIGIT 866 key-event-numidwild = token ":" "*" 867 key-event-range = ( key-event-value "-" key-event-value ) | 868 ( key-event-numid "-" key-event-numid ) 869 enumerated-key-event-set = "@" token 871 If the key-event-list is not present in a Session Request message 872 (e.g., "e: key") then it is assumed that the Requestor wants to be 873 notified of all available key-events in the sub-package. The key- 874 event-list MUST always be present in Session Response messages and 875 indicates all key-events that are subscribed (e.g., e: key[48-57]). 877 Likewise, the "*" wildcard can only appear in Session Request 878 messages. Wildcards must be expanded in Session Response messages 879 as described in Section 9.2. 881 Key-event-ranges with numbered keys (e.g, a "Line 3" telephone 882 button) must have the same key-event type on both sides of the range 883 (e.g., "phone[line:1-line:10]"). Each numbered key is treated as an 884 independent key-event. 886 An empty event-header ("e:") in a Session Request or Response 887 message indicates the termination of the Key-Event Session. The 888 event-header is the only key-event header which may be present but 889 empty. 891 Example Session Request message headers: 893 e: key[@dialpad, 65-68], keybd 895 In this example, the Requestor is requesting event notification 896 for keys: 0-9, *, #, A, B, C, D from the key sub-package and all 897 supported keybd sub-package events. 899 e: * 901 In this example the Requestor is requesting a subscription to all 902 key-events supported by the Notifier. 904 e: phone[line:*] 906 In this example the Requestor is requesting all available "line" 907 buttons within the phone sub-package. 909 Example Session Response headers for the above Session Request 910 message headers: 912 e: key[@dialpad] 914 In this example the Notifier is indicating that subscription only 915 occurred for the key-events 0-9,*,#. 917 e: key[48-57,8,10], keybd[insert,numlk] 919 In this example, the Notifier is indicating that subscriptions 920 have been created for the key-events 0-9, Backspace, Enter, Insert 921 & NumLock. 923 e: phone[line:1-line:5] 925 In this example, the Notifier is indicating that subscriptions 926 have been created for the "line" buttons 1 through 5. 928 8.4. Properties-Header Format 929 The properties-header in a Session Request message is used to set or 930 retrieve the properties of subscribed key-events. The properties- 931 header in a Session Response message indicates the value of each of 932 the listed properties. 934 properties-header = "p:" properties-set *( "," properties-set ) 935 properties-set = ( event-set | "*" ) "." property-name 936 "(" [ parameter-list ] ")" 937 property-name = token 938 parameter-list = parameter *( "," parameter ) 939 parameter = *( ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" 940 | "$" | SP | TAB | unreserved | escaped | quoted-string ) 942 As with the event-header, "*" wildcards and empty key-event-list�s 943 can only appear in Session Request messages. Wildcards and key- 944 event-list�s must be expanded in Session Response messages as 945 described in Section 7.2. 947 NOTE: The set of key-events that each property operates on is always 948 equal to the intersection of the set of subscribed key-events and 949 the set of key-events requested in the properties-header. 951 Examples for Session Request message headers: 953 p: key.dwndly(500) 955 In this example the Requestor is requesting that a value of 500 is 956 assigned to the "dwndly" property for all subscribed "key" sub- 957 package key-events. 959 p: *.exists() 961 In this example the Requestor is requesting to know the existence 962 of all non-primary key instances for all subscribed key-events. 964 p: keybd[ctrl].name() 966 The Requestor is requesting the name of all ctrl key instances. 968 Example Session Response message headers for above Session Request 969 message examples: 971 p: key[@dialpad].dwndly(500) 973 In response to the above dwndly set request, the Notifier is 974 confirming the new value for all subscribed key-events in the key 975 sub-package. 977 p: key[47-58, 10].exists(keypad) 979 The Notifier is indicating that in addition to the primary 980 instances of all subscribed key-events, additional key instances 981 for 0-9 & Enter exist on a keypad. 983 p: keybd[ctrl].name(pri="Left Control", alt="Right Control") 985 In this example, the name property indicates the names for the 986 various control key instances possessed by the device. 988 8.5. State-Header Format 990 The state-header allows the Notifier to indicate the initial key- 991 event states and subsequent key-event state changes. The header 992 only appears in Session Response and Notification messages. In a 993 Session Response message the state header gives key-event state 994 information for all subscribed key-events in non-default states. In 995 a Notification message the state header only indicates a change in 996 key-event state. 998 state-header = "s:" state-indication *( "," state-indication ) 999 state-indication = event-descriptor "." state-name 1000 "(" [ parameter-list ] ")" 1001 event-descriptor = sub-package-name "[" key-event-descriptor "]" 1002 key-event-descriptor = ( key-event-name | key-event-value | 1003 key-event-numid ) 1004 [ "(" positional-indicator ")" ] 1005 positional-indicator = "pri" | "alt" | "keypad" | token 1006 state-name = token 1008 An empty positional-indicator infers the request/result applies to 1009 the primary key of this key-event type. 1011 Examples: 1013 s: key[49].keydown(-1532) 1015 This example is a keydown state indication for the primary '1' key 1016 (Unicode [7] value 49). It indicates that the button was first 1017 depressed 1532 milliseconds before the NTP value in the time- 1018 header. 1020 s: key[49(keypad)].keyup(126,1206) 1022 This example is a keyup state indication for the keypad '1' key. 1023 It also indicates that the button was released 126 milliseconds 1024 after the NTP value in the time-header and was depressed for 1206 1025 milliseconds. 1027 9. Key-Event Message Generation 1029 9.1. Generating a Session Request message 1031 The Session Request message is generated to establish, renegotiate 1032 or terminate a Key-Event Session. The values placed in the 1033 message�s time-, instance-, event- and properties- headers are 1034 described in the relevant sections of section 8. 1036 9.2. Generating a Session Response message 1038 A Session Response message is generated in response to a Session 1039 Request. Generating the Initial NOTIFY request is the most 1040 complicated part of this specification, however, the headers were 1041 constructed so that the event-, property- and state- headers have a 1042 similar syntax and semantics. 1044 The procedure for generating the Response is decomposed into the 1045 procedures for generating each of the possible Session Response 1046 message headers. 1048 9.2.1. Event Header Processing 1050 This section describes how the subscribed key-events set is 1051 generated and how the Session Response event-header is derived from 1052 this set. The subscribed key-events set also forms part of the 1053 subscription state information and is used in generating the other 1054 headers. The set is formed from the event header in the Session 1055 Request message. 1057 To summarize, the subscribed key-events set is formed by expanding 1058 all wildcards in the requested key-events set and intersecting the 1059 resulting key-event set with the supported key-event set. 1061 Procedure: 1063 An event header of "*" results in a subscribed key-event set equal 1064 to the supported key-event set. If the event header does not 1065 contain a "*" then the following procedure is performed for each 1066 element on the event header line: 1068 If the key-event-list for the sub-package is empty (e.g., "e: user") 1069 then all supported key-events in the specified sub-package are added 1070 to the subscribed key-events set. Otherwise, the following 1071 procedure is performed for each element in the key-event-list: 1073 For enumerated key-event sets (e.g., "@dialpad"), if all key-events 1074 in the set are supported, then the enumerated key-event set is added 1075 to the subscribed key-events set. Otherwise the enumerated key- 1076 event set is simply replaced by its equivalent key-event list for 1077 individual evaluation. 1079 All key-event identifiers and ranges are checked against the 1080 supported key-event set and supported key-events are added to the 1081 subscribed key-event set. 1083 The resulting set is the subscribed key-event set. 1085 The event header in the Session Response message is generated from 1086 the subscribed key-events set by grouping together all key-events in 1087 the same sub-package. This is done to keep header length down, for 1088 example, "key[47-58,10,35]" is preferred over "key[47], key[48], 1089 key[49], ...". 1091 If the subscribed key-event set is empty then an empty event-header 1092 is generated ("e:") and the subscription is terminated after the 1093 message is delivered. 1095 9.2.2. Properties Header Processing 1097 The properties header in the Session Request message is evaluated to 1098 form the properties header used in the Session Response message as 1099 follows: 1101 Each element in the Session Request properties header is checked. 1102 If the property is not supported for any sub-package then no action 1103 is taken for this element. Otherwise, the input key-event set is 1104 calculated (the key-event set on which the property will operate). 1105 This set is generated in a similar manner to the subscribed key- 1106 event set described in the previous section except that the 1107 subscribed key-event set is used instead of the supported key-event 1108 set (properties only operate on subscribed key-events) and the 1109 requested key-event set is equal to the event-set of the current 1110 properties header element. The resulting input key-event set is 1111 further reduced by removing all key-events for which the property is 1112 not supported. At this point, the property is evaluated for each 1113 element in the input key-event set. For each evaluation, if the 1114 property generated a result then the result is added to the output 1115 set, otherwise no action is taken. 1117 Like the event header, the properties header is generated from the 1118 output set by grouping together all key-events with the same 1119 property result (and in the same sub-package). For example, 1120 "key[47-58].exists(keypad)" is preferred over 1121 "key[47].exists(keypad), key[48].exists(keypad), 1122 key[49].exists(keypad), ...". 1124 If the output set is empty then the properties header is not added 1125 to the message. 1127 9.2.3. State Header Processing 1129 A state notification is generated for each key-event in the 1130 subscribed key-event set for which the current state is not equal to 1131 the default state. This set of state notifications forms the 1132 Session Response state-header. 1134 If all subscribed key-events are in the default state then a state- 1135 header is not added to the message. 1137 9.3. Generating Key-Event Notification messages 1139 Notification messages generated in response to key state changes 1140 only possess two headers: the time-header and the state-header. 1142 The information in the state-header is a delta indication of the 1143 key-event state. In other words, each Notification message only 1144 includes the state information of key-events that have changed since 1145 the last notification. 1147 10. Minimal Implementation for Key-Event Notifiers 1149 Firstly, even a minimal implementation MUST address the security 1150 considerations prescribed in each transport profile. 1152 When a device does not have any user-defined keys, locally- 1153 configured names, multiple key instances or numbered buttons (e.g., 1154 a simple DTMF telephone dialpad) then the implementation can be made 1155 quite simple. In these cases the "exists" and "name" properties can 1156 be deemed OPTIONAL. If remote configuration of "dwndly" is also not 1157 required then the properties header line MAY be ignored completely. 1159 This allows simple devices to scale down to a simple implementation 1160 without affecting the functionality available to more complicated 1161 user interface devices. 1163 11. Guidelines to Future Sub-Package Authors 1165 Future sub-packages must not duplicate key-events contained in 1166 existing sub-packages. 1168 If the relevant sub-package already exists then an extension for the 1169 existing sub-package should be proposed rather than a new sub- 1170 package. 1172 Once published as a standard, new key-event states or enumerated 1173 key-event sets SHOULD NOT be added to an existing sub-package. Only 1174 new key-event values and OPTIONAL key-event properties may be added 1175 to existing sub-packages. 1177 New sub-packages should reuse the states and properties of the 1178 existing sub-packages where possible. 1180 12. MIME type information for the Key-Event Message Format 1182 The MIME definition for the key state message bodies defined in this 1183 document follows. 1185 Media type name: application 1186 Media subtype name: key-event 1187 Required parameters: none 1188 Optional parameters: none 1189 Encoding scheme: text 1191 The media subtype is used to indicate the message content as defined 1192 in this document. A typical header would look like the following. 1194 Content-Type: application/key-event 1196 Part B -- The use of SIP SUBSCRIBE & NOTIFY for Key-Event Transport 1198 This section describes the transport of key state data defined in 1199 Part A using the SIP Event Notification framework. 1201 13. Subscription to Key Events 1203 Subscriptions to key events are established, maintained, and 1204 terminated as described in the SIP-Specific Event Notification 1205 framework specification [2]. Key event subscriptions are indicated 1206 using "key-event" for the event-type in the Event header of 1207 SUBSCRIBE and NOTIFY requests. Details of the events being 1208 subscribed to and being reported are specified in message body of 1209 the Key-Event Session request. (See sections 7 and 8 for normative 1210 descriptions of Key-Event Sub-Packages and their message bodies.) 1212 As specified later, SUBSCRIBE requests contain Key-Event Session 1213 Request message bodies that indicate the events being subscribed to. 1214 Once accepted, an "event notification dialog" is established and 1215 event state is established in the Notifier according to the contents 1216 of the SUBSCRIBE message body. It is possible to modify the set of 1217 events being subscribed to by sending another SUBSCRIBE request, 1218 with a key events message body, for a previously established event 1219 notification dialog. In this case, the new message body should 1220 replace the state established by a previous SUBSCRIBE. 1222 This document describes two types of key-event subscriptions. The 1223 first is a subscription associated with a SIP dialog or conversation 1224 space. That is, the subscription is only valid for key-events 1225 directly associated with the specified session and the subscription 1226 ends when the SIP dialog or conversation-space ceases to exist. The 1227 term "dialog specific subscription" will be used to describe this 1228 type of subscription. The second type of key-event subscription 1229 described here is a non-dialog associated subscription. Where the 1230 subscribing device is interested in key events regardless of what 1231 the device is doing. The term "non-dialog specific subscription" 1232 will be used to describe this second type of key event subscription. 1233 Devices supporting the mechanisms defined in this document MUST 1234 support dialog specific subscriptions. Support for non-dialog 1235 specific subscriptions is OPTIONAL. 1237 13.1. Non-Dialog Specific Subscriptions 1239 Key-Event subscriptions that apply to a device, regardless of any 1240 on-going or active SIP dialogs, are established by SUBSCRIBE 1241 requests that do not include an instance-header in the Session 1242 Request message body. Notifiers that support non-dialog specific 1243 subscriptions MUST support multiple concurrent subscriptions from 1244 the same or different subscribers. 1246 13.2. Dialog Specific Subscriptions 1248 A dialog specific subscription is requested by the subscriber by 1249 including an instance-header in the Session Request message body of 1250 the SUBSCRIBE request. This header identifies the particulars of 1251 the dialog specific subscription; the format of the inserted header 1252 is described in section 14. 1254 There are two modes of dialog specific subscriptions: dialog 1255 attached mode and conversation-space attached mode. The primary 1256 difference between the two modes is the conditions under which the 1257 subscription terminates. 1259 13.2.1. Dialog Attached Mode 1261 In this mode, the subscription receives key-events from the user 1262 endpoint associated with the specified dialog whenever the user is 1263 *actively* communicating through that user endpoint. [An example of 1264 a user endpoint in this context could be a single virtual "line" on 1265 a multi-line SIP phone.] 1267 The subscription is terminated when the dialog is terminated. The 1268 RECOMMENDED subscription expiry timeout is on the order of a day. 1269 When a subscription is terminated due to dialog termination, the 1270 Notifier MAY send a NOTIFY with "Subscription-State: 1271 terminated;reason=noresource" header however this is deemed 1272 unnecessary in most cases. 1274 13.2.2. Conversation Space Attached Mode 1276 Just as for dialog attached subscriptions, the subscription receives 1277 key-events from the user endpoint associated with the specified 1278 dialog (at the time of subscription) whenever the user is *actively* 1279 communicating through that user endpoint. 1281 However for conversation space attached dialogs, the subscription is 1282 terminated when the conversation space of the user endpoint is 1283 reduced to a conversation space containing only the user endpoint 1284 (or an empty conversation space). For instance, in this mode the 1285 subscription would *not* be terminated when an INVITE with a 1286 Replaces header was received from the network but would be 1287 terminated when all other participants leave a distributed 1288 conference. It is RECOMMENDED that the subscription expiry timeout 1289 have a value ranging from minutes up to an hour. The Notifier MUST 1290 send a NOTIFY with "Subscription-State: terminated; 1291 reason=noresource" header when the subscription terminates. 1293 13.2.3. Multi-dialog Capable Endpoints 1295 Dialog specific subscriptions can present a challenge to user 1296 devices that support multiple simultaneous dialogs but only have a 1297 single user interface (keypad, speaker, microphone) that is shared 1298 between all session (e.g., a multi-line SIP phone). Most devices of 1299 this type have the concept of a single "active" session among the 1300 established sessions. That is, only one session has the use of the 1301 shared user interface resources at any point in time. This 1302 characteristic should be applied to key event subscriptions, in 1303 other words, notifications will only be sent to subscribers (if any) 1304 of the dialog with which the keypad is assigned to at the time of 1305 the event detection. This behavior is consistent with common 1306 circuit-based multi-line telephones. 1308 This should not be confused with devices which terminate multiple 1309 dialogs but where each dialog is associated with a different user, 1310 for instance, a SIP-PSTN gateway. 1312 13.2.4. "Early" Dialog Subscriptions 1314 In order for a subscriber to reliably receive all Callee generated 1315 key-events from the time a session is fully established/answered, a 1316 Callee must be able to receive and setup a dialog specific 1317 subscription prior to the associated dialog being fully established. 1318 This is accomplished by the caller/AS sending a SUBSCRIBE request 1319 after an early dialog has been established (by a provisional INVITE 1320 response) but before any final response has been sent by the callee. 1321 As with any SUBSCRIBE request received, recipients should process 1322 the request according to its policies, however early dialog 1323 subscriptions do not produce Key-Event information until the 1324 associated dialog is established/answered. It should be remembered 1325 that the SIP Events draft requires that a NOTIFY request is 1326 generated immediately, however, the NOTIFY will simply not contain 1327 Key-Event message bodies until the subscription�s associated device 1328 or dialog becomes active. 1330 A Caller can also receive a dialog specific subscription for a 1331 dialog before it has been fully established. The same issues with 1332 authentication and authorization apply as in the previous case, 1333 however, the notification of caller key presses before the dialog is 1334 fully established may benefit certain applications (for instance, 1335 pre-answer or pre-alerting caller pin-code authorization). Thus, 1336 when the instance-header does not specify a remote tag the early 1337 subscription should become active immediately. If the subscriber 1338 does specify a remote tag in the instance-header, then the 1339 subscription is only valid while the caller has an end-to-end 1340 association with the specified callee (for instance while early 1341 media from the specified callee is being played to the caller). In 1342 this case, the subscription is terminated if and when the session is 1343 eventually established with a different callee. 1345 13.2.5. Multiple Subscriptions 1347 A User-Agent/Notifier MUST support multiple concurrent subscriptions 1348 for the same dialog from both the same subscriber and from different 1349 subscribers. 1351 14. Instance-Header format for SIP Dialog Specific Subscriptions 1353 The purposed of an instance-header in the key-event message body of 1354 a SUBSCRIBE request is to identify a SIP dialog and specify the 1355 subscription attachment mode; in a SIP SUBSCRIBE, the header�s 1356 presence indicates that the subscription is dialog specific. 1358 If a subscriber places an instance-header in the initial SUBSCRIBE 1359 request then it MUST also be placed unchanged in all subsequent 1360 SUBSCRIBE requests for the SIP dialog specified initially. However, 1361 a Notifier MUST ignore the instance-header in all but the initial 1362 SUBSCRIBE request. 1364 This allows a Notifier to restart but ensures that the 1365 subscription does not change over time. Notifiers can ignore 1366 the instance-header in SUBSCRIBE requests that refresh 1367 subscriptions since SUBSCRIBE established dialogs are 1368 identified by the Call-ID, Local-Tag, and Remote-Tag present in 1369 the initial SUBSCRIBE request. 1371 instance-header = "i:" instance-component *("," instance-component ) 1372 instance-component = "call-id" "=" Call-ID 1373 | "local-tag" "=" UUID 1374 | "remote-tag" "=" UUID 1375 | "attach" = ( "dialog" | "cspace" | token ) 1376 | future-extension 1378 No minimum set of components has been specified for the instance- 1379 header - it is the responsibility of the generator to ensure that 1380 the instance-header uniquely identifies a dialog on the target. To 1381 ensure uniqueness it is RECOMMENDED that the instance-header contain 1382 the call-id, local-tag and remote-tag components. 1384 If none of the "call-id", "local-tag", "remote-tag" components are 1385 present then it is assumed that the dialog specific subscription is 1386 associated with the subscription�s own dialog "call-id", "local-tag" 1387 & "remote-tag" values. This does not preclude the use of the attach 1388 component. 1390 The "attach" component indicates whether the subscription is 1391 associated to the dialog itself or to the conversation space to 1392 which the dialog currently belongs (as described in section 13.2). 1393 The assumed value for the "attach" component (when not present) is 1394 "attach=dialog". 1396 15. SIP specific Key-Event error handling 1398 15.1. Handling of unacceptable instance-header values. 1400 When a SUBSCRIBE request is received containing an instance-header 1401 referring to a non-existent or unacceptable dialog then the Notifier 1402 SHOULD generate a NOTIFY request with a "Subscription-State: 1403 terminated;reason=noresource" SIP header. 1405 15.2. Handling of unknown key-event-set enumerations. 1407 When a Notifier receives a Key-Event Session Request with an unknown 1408 key-event-set enumeration in a supported key-event sub-package 1409 (e.g., "e: key[@polish]") then the Notifier MUST generate a SIP 1410 Warning header in the Initial NOTIFY request. Unknown key-event-set 1411 enumerations in the "user" sub-package MAY be silently ignored. 1413 The "warn-text" of the SIP Warning header SHOULD include the unknown 1414 enumeration, for instance: 1416 Warning: 390 host53.company.com "Unknown key-event-set enumeration: 1417 key[@polish]" 1419 The subscription should proceed as normal with the unknown key- 1420 event-set enumerations ignored. 1422 A warn-code of 390 is chosen as the information to be conveyed falls 1423 in the miscellaneous category (as defined in [3]) and to allow 1424 automated actions to occur. For example, a subscriber can modify the 1425 subscription and use Key-Event values instead of using an enumerated 1426 Key-Event set. 1428 16. Event Package Definition 1430 This section contains the formal definition of the Key-events SIP 1431 Event Package described in this document. This information is 1432 provided to conform to the requirements for SIP Event Packages as 1433 outlined in [2]. As part of these requirements this section details 1434 how Key-Event message bodies are generated by the subscriber and 1435 Notifier entities. 1437 16.1. Event Package Name 1439 The event package token name for the Key Events package is "key- 1440 event". The token name is used in the Event and Allow-Event headers 1441 defined in [2]. 1443 16.2. Event Package Parameters 1445 There are no parameters used in the Event header for the key-events 1446 package/sub-packages. 1448 16.3. SUBSCRIBE Bodies 1450 SUBSCRIBE requests for Key-Event subscriptions MUST contain a Key- 1451 Event message body if the SIP Expires header value is non-zero and 1452 MAY contain one if the SIP Expires header value is zero. SUBSCRIBE 1453 responses do not contain a message body. The Content-Type for the 1454 Key-Event message body is "application/key-event". The grammatical 1455 specifications for the message body are defined in section 8. 1457 16.4. Subscription Duration 1459 Dialog specific subscriptions implicitly end when the associated 1460 dialog or conversation-space ends. Please refer to section 13.2.1 & 1461 13.2.2 for recommended dialog specific subscription expiry timeout 1462 values. It is recommended that the subscription expiry timeout for 1463 non-dialog specific subscriptions be from a few minutes to an hour. 1465 As detailed in [2] a SUBSCRIBE with an "Expires: 0" header indicates 1466 the termination of a subscription. However, if the accepted 1467 SUBSCRIBE message also contains a Session Request message body, then 1468 the SUBSCRIBE message body should be processed and the normal NOTIFY 1469 Session Response message body is generated (ignoring any persistent 1470 subscription side effects). This mechanism can be used to determine 1471 the sub-packages & key-events supported as well as the current 1472 property values without creating an ongoing subscription. 1474 If the terminating SUBSCRIBE does not contain a Key-Event message 1475 body then a NOTIFY request MUST still be sent (with no message body) 1476 as described in [2]. 1478 16.5. NOTIFY Bodies 1480 NOTIFY requests MUST contain a Key-Event message body if the 1481 associated device, dialog or conversation space of the subscription 1482 is in an active state. Conversely, the lack of a message body in a 1483 NOTIFY request with a non-zero Subscription-Expires header value 1484 indicates that the Key-Event subscription state is pending (for 1485 example, awaiting authorization or for the associated dialog to 1486 become active). NOTIFY responses do not contain a message body. 1487 The Content-Type for the Key-Event message body is "application/key- 1488 event". The grammatical specifications for the message body are 1489 defined in section 8. 1491 16.6. Notifier Processing of SUBSCRIBE Requests 1493 The Notifier takes the following basic steps: 1495 1. Before processing a received SUBSCRIBE request a state-agent MUST 1496 check that the subscriber is authorized to perform the requested 1497 subscription (c.f., Section 18 and [2]). 1499 2. If the SUBSCRIBE includes an instance-header in the key-event 1500 message body then the Notifier MUST check that the dialog exists and 1501 if not, take action as described in section 15. 1503 3. The SUBSCRIBE message body is parsed for consistency and a 1504 SUBSCRIBE response is generated as described in [2]. 1506 4. The state-agent will then clear existing Key-Event subscription 1507 state for this subscription and proceed to generate a Key-Event 1508 Session Response message body in a NOTIFY request as described in 1509 Section 16.7.1. 1511 5. If the value of the SUBSCRIBE�s Expires header is non-zero then 1512 the new subscription state information is stored. 1514 16.7. Notifier Generation of NOTIFY Requests 1516 This section describes both the generation of NOTIFY requests when 1517 the subscription is established or modified by the Notifier, and 1518 when reporting state changes in the subscribed resource. 1520 16.7.1. Generating Initial NOTIFY Requests 1522 The Initial NOTIFY request is generated when the subscription state 1523 initially transitions to "active" or a subsequent SUBSCRIBE message 1524 is received by the Notifier. The initial NOTIFY request may only 1525 contain a Session Response message body which is generated in 1526 response to the accepted SUBSCRIBE request (although it need not be 1527 generated immediately). The Initial NOTIFY request always reports 1528 complete state information and can be differentiated from a NOTIFY 1529 reporting a change in state by the presence of the event-header in 1530 the Key-Event message body. 1532 If the SUBSCRIBE request did not contain a Key-Event message body 1533 (which infers that the request also has an "Expires: 0" header) then 1534 the resulting NOTIFY request will also not have a Key-Event message 1535 body. If the SUBSCRIBE request does contain a Session Request 1536 message body but has a "Expires: 0" SIP header then an Initial 1537 NOTIFY Session Response request is still generated however the 1538 subscription is not kept after the Initial NOTIFY request is sent. 1540 The Key-Event Session Request message body in the Initial NOTIFY 1541 request contains the following information: 1542 - A confirmation of the subscribed key-events (event-header). 1543 - The result of all key-event property evaluations (properties- 1544 header). 1545 - The initial state of subscribed key-events that have a non-default 1546 state (state-header). 1548 16.7.2. Generating Subsequent NOTIFY Requests 1550 NOTIFY requests that are not generated in response to an accepted 1551 SUBSCRIBE request MAY include a Key-Event Notification message body 1552 to indicate a change in key-event state. 1554 Once a NOTIFY request with an application/key-event message body has 1555 been sent, further "key-event" NOTIFY messages can be delayed until 1556 a final response is received for the NOTIFY request. Thus, the key- 1557 event state-header MAY contain multiple key-state changes. 1559 16.8. Subscriber Processing of NOTIFY Requests 1560 The NOTIFY response is generated as described in [2]. NOTIFY 1561 responses do not contain key-event Event message bodies. 1563 16.9. Subscriber Generation of SUBSCRIBE Requests 1565 The SUBSCRIBE request for "key-event" SIP events is generated as 1566 described in [2] with the following clarifications: 1567 . the Event header is set to "Event: key-event". 1568 . the Content-Type header is set to "Content-Type: 1569 application/key-event" if a Key-Event message body is included. 1570 . if dialog specific subscription is required then the instance- 1571 header is added to the Key-Event message body as described in 1572 section 13.2. 1574 The event-header will contain the list of desired key-events to 1575 receive notifications for and MAY include wildcards. The 1576 properties-header will contain the set of key-event properties for 1577 which the subscriber wishes to set or retrieved the value of. 1579 A new "key-event" SUBSCRIBE request for an existing subscription 1580 dialog will entirely replace the subscription state of previous 1581 SUBSCRIBE requests in that dialog. 1583 If the SIP Expires header has a value of zero then the subscriber 1584 application can still always expect at least one further NOTIFY 1585 request to be sent by the Notifier (as described in [2]). 1587 When using the "key-event" package, if the SIP Expires header does 1588 not have a value of zero then the subscriber application MUST 1589 include a Key-Event message body. 1591 16.10. Pre-loaded Routes in SUBSCRIBE requests 1593 The following section applies only to dialog-specific subscriptions 1594 where the subscriber application is located along the associated 1595 INVITE dialog signaling path and wishes to collect key-events from 1596 one of the User Agent endpoints. 1598 In order to maximize the likelihood that a SUBSCRIBE request will 1599 successfully reach the desired User Agent, it is RECOMMENDED the 1600 subscriber place pre-loaded Route headers in the SUBSCRIBE request 1601 to reproduce any Record-Routes established in the associated INVITE 1602 dialog. The presence of record-routed Application Level Gateways 1603 controlling firewalls and/or NAT�s is a typical example of when this 1604 may be helpful. 1606 When the subscriber wishes to send a SUBSCRIBE request to the 1607 caller, the Route set is constructed (in the manner that the callee 1608 would normally use) from the Record-Route and Contact headers in the 1609 original INVITE request. 1611 When the subscriber wishes to send a SUBSCRIBE request to the 1612 callee, the Route set is constructed (in the manner that the caller 1613 would normally use) from the Record-Route and Contact headers in the 1614 original 200 OK INVITE response. However in the case where the 1615 subscriber application is acting as a proxy in the original INVITE 1616 dialog (c.f., Usage Scenario 2, Section 2.2.2), then the subscriber 1617 should ignore all Record-Route headers up to and including the 1618 Record-Route inserted by the subscriber application in the 200 OK 1619 INVITE response. 1621 16.11. Handling of Forked Subscriptions 1623 A SUBSCRIBE request may fork and arrive at multiple devices. In 1624 this case, the subscriber can terminate those subscriptions it 1625 wishes by sending a SUBSCRIBE with an Expires value set to 0. It 1626 can also respond to any NOTIFYs from a UA with a 481 Transaction 1627 Does Not Exist. 1629 If the subscriber wishes to accept multiple subscriptions, merging 1630 of state is not defined due to the fact that the multiple 1631 subscriptions represent the state of multiple devices. 1633 A Notifier SHOULD return 482 Request Merged response to subsequent 1634 multiple subscriptions having the same SUBSCRIBE request transaction 1635 id (even if they have differing request-uri�s). 1637 16.12. Rate of Notifications 1639 The use of the Key Events packages should be limited to situations 1640 that require limited amount of data to be transported. As each key 1641 press can cause a notification (and response) to be sent, this 1642 mechanism is inefficient in scenarios where a significant amount of 1643 data is to be transferred between two endpoints. However, as key 1644 event packages are designed to transport user indications, the rate 1645 of notifications should not be much more than ten per second nor 1646 more than 10 to 20 events at a time. 1648 17. Examples 1650 In the example call flow below, an application server subscribes to 1651 the status of a caller's keypad events. NOTIFY requests are sent 1652 for two key presses, in addition to the initial NOTIFY indicating 1653 those key-events the Notifier supports and their initial state. Via 1654 headers are omitted for clarity. 1656 Subscriber Notifier 1657 | | 1658 | F1: SUBSCRIBE | 1659 |---------------------->| 1660 | F2: 200 OK | 1661 |<----------------------| 1662 | | 1663 | F3: NOTIFY | Init. State: '*' key down 1664 |<----------------------| 1665 | F4: 200 OK | 1666 |---------------------->| 1667 | | 1668 | F5: NOTIFY | 'A' key pressed and 1669 |<----------------------| released quickly 1670 | A6: 200 OK | 1671 |---------------------->| 1672 | | 1673 | F5: NOTIFY | '1' key depressed 1674 |<----------------------| 1675 | A6: 200 OK | 1676 |---------------------->| 1677 | | 1678 | F7: NOTIFY | '*' key released 1679 |<----------------------| 1680 | F8: 200 OK | 1681 |---------------------->| 1682 | | 1683 | F9: NOTIFY | '1' key released 1684 |<----------------------| 1685 | F10: 200 OK | 1686 |---------------------->| 1687 | | 1688 | F11: (un)SUBSCRIBE | 1689 |---------------------->| 1690 | F12: 200 OK | 1691 |<----------------------| 1692 | | 1693 | F13: NOTIFY | 1694 |<----------------------| 1695 | F14: 200 OK | 1696 |---------------------->| 1697 | | 1699 F1: Subscriber -> Notifier 1701 SUBSCRIBE sip:caller@access-22.isp.net SIP/2.0 1702 To: 1703 From: ;tag=2356 1704 Call-Id: 321123@appsrv.sp.com 1705 CSeq: 2 SUBSCRIBE 1706 Contact: 1707 Event: key-event 1708 Expires: 3600 1709 Content: application/key-event 1710 Content-Length: xx 1712 t: 36539655 1 1713 i: call-id=8347-da8d-7657-ab32@192.144.22.1; local-tag=2342354556; 1714 remote-tag=00993k23ff8; attach=cspace 1715 e: key, keybd 1716 p: *.exists(), *.dwndly(1000) 1717 The subscriber is requesting all key and keyboard sub-package key- 1718 events and also requesting to know the presence of multiple key 1719 instances and a delay in keydown notification of 1000ms. 1721 F2: Notifier -> Subscriber 1723 SIP/2.0 200 OK 1724 To: ;tag=789 1725 From: ;tag=2356 1726 Call-Id: 321123@appsrv.sp.com 1727 CSeq: 2 SUBSCRIBE 1728 Contact: 1729 Expires: 3600 1730 Content-Length: 0 1732 F3: Notifier -> Subscriber 1734 NOTIFY sip:appl@appsrv.sp.com SIP/2.0 1735 To: ;tag=2356 1736 From: ;tag=789 1737 Call-Id: 321123@appsrv.sp.com 1738 CSeq: 403 NOTIFY 1739 Contact: 1740 Event: key-event 1741 Content: application/key-event 1742 Content-Length: xx 1744 t: 36539658 1 1745 e: key[@dialpad, 65-68] 1746 p: key[@dialpad, 65-68].dwndly(1000) 1747 s: key[42].keydown(-1902) 1749 The Notifier confirms subscribed key-events and property values 1750 along with non-default initial key-event states. In this example 1751 the Notifier has created a subscription for keys { '0' - '9', '*', 1752 '#', 'A' - 'D' } and confirms that the dwndly property has been set. 1753 All keys except '*' are in the default (keyup) state; '*' has been 1754 depressed since 1.902 seconds before the specified NTP time value, 1755 that is, the key was depressed at 36539656.098 seconds past the 1756 epoch. No multiple key instances exist. 1758 F4: Subscriber -> Notifier 1760 SIP/2.0 200 OK 1761 To: ;tag=2356 1762 From: ;tag=789 1763 Call-Id: 321123@appsrv.sp.com 1764 CSeq: 403 NOTIFY 1765 Content-Length: 0 1767 F5: Notifier -> Subscriber 1768 NOTIFY sip:appl@appsrv.sp.com SIP/2.0 1769 To: ;tag=2356 1770 From: ;tag=789 1771 Call-Id: 321123@appsrv.sp.com 1772 CSeq: 404 NOTIFY 1773 Contact: 1774 Event: key-event 1775 Content: application/key-event 1776 Content-Length: xx 1778 t: 36539663 2 1779 s: key[65].keyup(17, 537) 1781 The Notifier reports that the 'A' key has been pressed and released. 1782 As the duration of depression was less that 1000ms, only the keyup 1783 state indication has been generated. In this case, the depression 1784 can be determined to have started at time 36539662.480 and lasted 1785 for 537ms. 1787 F6: Subscriber -> Notifier 1789 SIP/2.0 200 OK 1790 To: ;tag=2356 1791 From: ;tag=789 1792 Call-Id: 321123@appsrv.sp.com 1793 CSeq: 404 NOTIFY 1794 Content-Length: 0 1796 F7: Notifier -> Subscriber 1798 NOTIFY sip:appl@appsrv.sp.com SIP/2.0 1799 To: ;tag=2356 1800 From: ;tag=789 1801 Call-Id: 321123@appsrv.sp.com 1802 CSeq: 405 NOTIFY 1803 Contact: 1804 Event: key-event 1805 Content: application/key-event 1806 Content-Length: xx 1808 t: 36539668 2 1809 s: key[49].keydown(-987) 1811 The Notifier reports that the '1' key was pressed at time 1812 36539667.13. The keydown has been generated because the key has 1813 been depressed for more than 1000ms. In this example the NOTIFY 1814 request was actually generated at time 36539668.13 which explains 1815 the -987ms offset from the NTP time. 1817 F8: Subscriber -> Notifier 1818 SIP/2.0 200 OK 1819 To: ;tag=2356 1820 From: ;tag=789 1821 Call-Id: 321123@appsrv.sp.com 1822 CSeq: 405 NOTIFY 1823 Content-Length: 0 1825 F9: Notifier -> Subscriber 1827 NOTIFY sip:appl@appsrv.sp.com SIP/2.0 1828 To: ;tag=2356 1829 From: ;tag=789 1830 Call-Id: 321123@appsrv.sp.com 1831 CSeq: 406 NOTIFY 1832 Contact: 1833 Event: key-event 1834 Content: application/key-event 1835 Content-Length: xx 1837 t: 36539669 3 1838 s: key[42].keyup(756, 13658) 1840 This notification indicates that the '*' key has eventually been 1841 released at time 36539669.756. The duration of depression is 13658 1842 milliseconds; this value is consistent with the time of depression 1843 indicated in the initial (keydown) state indication of message F3. 1845 F10: Subscriber -> Notifier 1847 SIP/2.0 200 OK 1848 To: ;tag=2356 1849 From: ;tag=789 1850 Call-Id: 321123@appsrv.sp.com 1851 CSeq: 406 NOTIFY 1852 Content-Length: 0 1854 F11: Notifier -> Subscriber 1856 NOTIFY sip:appl@appsrv.sp.com SIP/2.0 1857 To: ;tag=2356 1858 From: ;tag=789 1859 Call-Id: 321123@appsrv.sp.com 1860 CSeq: 407 NOTIFY 1861 Contact: 1862 Event: key-event 1863 Content: application/key-event 1864 Content-Length: xx 1866 t: 36539672 4 1867 e: key 1868 p: key[49].keyup(154, 5141) 1869 This notification indicates that the '1' key has been released at 1870 time 36539672.154. The duration of depression is 5141 milliseconds; 1871 this value is consistent with the time of depression indicated in 1872 the (keydown) state indication of message F7. 1874 F12: Subscriber -> Notifier 1876 SIP/2.0 200 OK 1877 To: ;tag=2356 1878 From: ;tag=789 1879 Call-Id: 321123@appsrv.sp.com 1880 CSeq: 407 NOTIFY 1881 Content-Length: 0 1883 F13: Subscriber -> Notifier 1885 SUBSCRIBE sip:caller@access-22.isp.net SIP/2.0 1886 To: ;tag=789 1887 From: ;tag=2356 1888 Call-Id: 321123@appsrv.sp.com 1889 CSeq: 3 SUBSCRIBE 1890 Contact: 1891 Event: key-event 1892 Expires: 0 1893 Content-Length: 0 1895 The subscriber indicates it wishes to terminate the subscription. 1897 F14: Notifier -> Subscriber 1899 SIP/2.0 200 OK 1900 To: ;tag=789 1901 From: ;tag=2356 1902 Call-Id: 321123@appsrv.sp.com 1903 CSeq: 3 SUBSCRIBE 1904 Contact: 1905 Expires: 0 1906 Content-Length: 0 1908 F15: Notifier -> Subscriber 1910 NOTIFY sip:appl@appsrv.sp.com SIP/2.0 1911 To: ;tag=2356 1912 From: ;tag=789 1913 Call-Id: 321123@appsrv.sp.com 1914 CSeq: 408 NOTIFY 1915 Contact: 1916 Subscription-Expires: 0 1917 Content-Length: 0 1918 As described in [1], the Notifier must always send one NOTIFY 1919 request in response to any accepted SUBSCRIBE request. 1921 F16: Subscriber -> Notifier 1923 SIP/2.0 200 OK 1924 To: ;tag=2356 1925 From: ;tag=789 1926 Call-Id: 321123@appsrv.sp.com 1927 CSeq: 408 NOTIFY 1928 Content-Length: 0 1930 18. Security Considerations 1932 Key-Event Subscriptions are very likely to reveal sensitive 1933 information such as pin-numbers and destination numbers. Therefore, 1934 it is REQUIRED that devices accepting SUBSCRIBE requests perform 1935 some level of authentication before establishing a subscription. 1936 When such authentication is not provided by the network layer (e.g., 1937 IPSEC or private/trusted networks), then it MUST be provided by the 1938 transport-layer (e.g., TLS) or application-layer (e.g., SIP 1939 message/header authentication). 1941 Likewise, the information provided in the NOTIFY request is also 1942 likely to contain sensitive information and so the Notifier MUST 1943 ensure that the NOTIFY requests are transported securely. Once 1944 again, this protection could be provided by the network-layer (e.g., 1945 IPSEC encryption or private networks), transport layer (e.g., TLS 1946 encryption) or application layer (e.g., S/MIME or SIP message body 1947 encryption). 1949 Alternatively, it is possible for the Notifier to allow 1950 unsecured/unauthenticated subscribers to subscribe to key-events 1951 that will not divulge sensitive information. For instance, 1952 subscriptions to the "*" and "#" keys should not divulge sensitive 1953 information but may provide sufficient functionality for some 1954 3pcc/B2BUA pre-paid calling card applications. 1956 19. IANA Considerations 1958 Section 12 provides the registration information needed to register 1959 the "application/key-event" MIME type with IANA. 1961 19.1. Key-Event Package Registration 1963 This document specifies an event package as defined in [2]. The 1964 following information is specified as required by "SIP-Specific 1965 Event Notification" [RFC xxxx]. 1967 Package Name: key-events 1968 Type: package 1969 Contact: Robert Fairlie-Cuninghame , Bert 1970 Culpepper , Jean-Francois Mule 1971 1973 19.2. Key-Event Sub-Package Registration 1975 This document defines a Key-Event Sub-Package namespace that should 1976 be maintained by a centralized coordinating organization. Sub- 1977 Package names share the same namespace. The following Key-Event 1978 Sub-Package registration information is specified in anticipation of 1979 the mechanisms and namespace defined in this document being accepted 1980 in the IETF. 1982 Sub-Package Name Contact Reference 1983 ---------------- ------------ --------------- 1984 Key [RFC,BC,JFM] [RFC xxxx] 1985 Keyboard [RFC,BC,JFM] [RFC xxxx] 1986 Telephone [RFC,BC,JFM] [RFC xxxx] 1987 User [RFC,BC,JFM] [RFC xxxx] 1989 People: 1990 [RFC] Robert Fairlie-Cuninghame 1991 [BC] Bert Culpepper 1992 [JFM] Jean-Francois Mule 1994 References: 1995 [RFC xxxx] B. Culpepper, R. Fairlie-Cuninghame, J. Mule, "SIP Event 1996 Package for Keys", March 2002. 1998 Guidelines for registering key event packages with IANA will be 1999 completed in a future draft revision. 2001 20. Authors 2003 Robert Fairlie-Cuninghame 2004 Nuera Communications, Inc. 2005 50 Victoria Rd 2006 Farnborough, Hants GU14-7PG 2007 United Kingdom 2008 Phone: +44-1252-548200 2009 Email: rfairlie@nuera.com 2011 Bert Culpepper 2012 InterVoice-Brite, Inc. 2013 701 International Parkway 2014 Heathrow, FL 32746 2015 Phone: 407-357-1536 2016 Email: bert.culpepper@intervoice-brite.com 2018 Jean-Francois Mule 2019 Cable Television Laboratories, Inc. 2020 400 Centennial Parkway 2021 Louisville, CO 80027-1266 2022 Phone: 303-661-3708 2023 Email: jf.mule@cablelabs.com 2025 21. References 2027 1 S. Bradner, "The Internet Standards Process -- Revision 3", BCP 2028 9, RFC 2026, October 1996. 2030 2 A. Roach, "SIP-Specific Event Notification", Internet-Draft 2031 draft-ietf-sip-events-04, February 2002, Work in progress. 2033 3 M. Handley, H. Schulzrinne, E. Schooler, and J. Rosenberg, "SIP: 2034 Session Initiation Protocol", RFC 2543, March 1999. 2036 4 H. Schulzrinne, S. Petrack, "RTP Payload for DTMF Digits, 2037 Telephony Tones and Telephony Signals", RFC 2833, May 2000. 2039 5 R. Mahy, "A Call Control Model for SIP", Internet-Draft, November 2040 2001, Work in progress. 2042 6 D. Mills, "Network Time Protocol (Version 3)", RFC1305, March 2043 1992. 2045 7 The Unicode Consortium, "The Unicode Standard -- Version 3.0", 2046 ISBN 0-201-61633-5. Described at 2047 http://www.unicode.org/unicode/standard/versions/Unicode3.0.html