idnits 2.17.1 draft-ietf-sipping-kpml-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 17. -- Found old boilerplate from RFC 3978, Section 5.5 on line 2432. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2443. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2450. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2456. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (July 23, 2006) is 6484 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0-9' on line 756 -- Looks like a reference, but probably isn't: '0-9c' on line 757 == Missing Reference: '179' is mentioned on line 831, but not defined -- Looks like a reference, but probably isn't: '2-9' on line 832 -- Looks like a reference, but probably isn't: '02-46-9A-D' on line 834 == Unused Reference: '10' is defined on line 2304, but no explicit reference was found in the text == Unused Reference: '11' is defined on line 2308, but no explicit reference was found in the text == Unused Reference: '12' is defined on line 2311, but no explicit reference was found in the text == Unused Reference: '14' is defined on line 2318, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (ref. '2') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 3023 (ref. '3') (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 3265 (ref. '5') (Obsoleted by RFC 6665) ** Obsolete normative reference: RFC 3406 (ref. '6') (Obsoleted by RFC 8141) -- Possible downref: Non-RFC (?) normative reference: ref. '8' == Outdated reference: A later version (-15) exists of draft-ietf-sip-gruu-08 -- Obsolete informational reference (is this intentional?): RFC 1889 (ref. '10') (Obsoleted by RFC 3550) -- Obsolete informational reference (is this intentional?): RFC 2327 (ref. '11') (Obsoleted by RFC 4566) -- Obsolete informational reference (is this intentional?): RFC 2616 (ref. '12') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2833 (ref. '13') (Obsoleted by RFC 4733, RFC 4734) -- Obsolete informational reference (is this intentional?): RFC 3525 (ref. '16') (Obsoleted by RFC 5125) Summary: 7 errors (**), 0 flaws (~~), 8 warnings (==), 17 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SIPPING E. Burger 3 Internet-Draft Cantata Technology, Inc. 4 Intended status: Standards Track M. Dolly 5 Expires: January 24, 2007 AT&T Labs 6 July 23, 2006 8 A Session Initiation Protocol (SIP) Event Package for Key Press Stimulus 9 (KPML) 10 draft-ietf-sipping-kpml-08 12 Status of this Memo 14 By submitting this Internet-Draft, each author represents that any 15 applicable patent or other IPR claims of which he or she is aware 16 have been or will be disclosed, and any of which he or she becomes 17 aware will be disclosed, in accordance with Section 6 of BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as Internet- 22 Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 This Internet-Draft will expire on January 24, 2007. 37 Copyright Notice 39 Copyright (C) The Internet Society (2006). 41 Abstract 43 This document describes a SIP Event Package "kpml" that enables 44 monitoring of DTMF signals and uses XML documents referred to as Key 45 Press Markup Language (KPML). The kpml Event Package may be used to 46 support applications consistent with the principles defined in the 47 document titled "A Framework for Application Interaction in the 48 Session Initiation Protocol (SIP)". The event package uses SUBSCRIBE 49 messages and allows for XML documents that define and describe filter 50 specifications for capturing key presses (DTMF Tones) entered at a 51 presentation-free User Interface SIP User Agent (UA). The event 52 package uses NOTIFY messages and allows for XML documents to report 53 the captured key presses (DTMF tones), consistent with the filter 54 specifications, to an Application Server. The scope of this package 55 is for collecting supplemental key presses or mid-call key presses 56 (triggers). 58 Conventions used in this document 60 RFC2119 [1] provides the interpretations for the key words "MUST", 61 "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", 62 "RECOMMENDED", "MAY", and "OPTIONAL" found in this document. 64 The Application Interaction Framework document [19] provides the 65 interpretations for the terms "User Device", "SIP Application", and 66 "User Input". This document uses the term "Application" and 67 "Requesting Application" interchangeably with "SIP Application". 69 Additionally, the Application Interaction Framework document 70 discusses User Device Proxies. A common instantiation of a User 71 Device Proxy is a Public Switched Telephone Network (PSTN) gateway. 72 Because the normative behavior of a presentation free User Interface 73 is identical for a presentation free SIP User Agent and a 74 presentation free User Device Proxy, this document uses "User Device" 75 for both cases. 77 Table of Contents 79 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 80 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 81 3. Key Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 6 82 3.1. Subscription Duration . . . . . . . . . . . . . . . . . . 7 83 3.2. Timers . . . . . . . . . . . . . . . . . . . . . . . . . . 8 84 3.3. Pattern Matches . . . . . . . . . . . . . . . . . . . . . 9 85 3.4. Digit Suppression . . . . . . . . . . . . . . . . . . . . 13 86 3.5. User Input Buffer Behavior . . . . . . . . . . . . . . . . 15 87 3.6. DRegex . . . . . . . . . . . . . . . . . . . . . . . . . . 17 88 3.6.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 17 89 3.6.2. Operation . . . . . . . . . . . . . . . . . . . . . . 18 90 3.7. Monitoring Direction . . . . . . . . . . . . . . . . . . . 20 91 3.8. Multiple Simultaneous Subscriptions . . . . . . . . . . . 20 92 4. Event Package Formal Definition . . . . . . . . . . . . . . . 21 93 4.1. Event Package Name . . . . . . . . . . . . . . . . . . . . 21 94 4.2. Event Package Parameters . . . . . . . . . . . . . . . . . 21 95 4.3. SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . 22 96 4.4. Subscription Duration . . . . . . . . . . . . . . . . . . 22 97 4.5. NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . 22 98 4.6. Subscriber generation of SUBSCRIBE requests . . . . . . . 22 99 4.7. Notifier processing of SUBSCRIBE requests . . . . . . . . 23 100 4.8. Notifier generation of NOTIFY requests . . . . . . . . . . 25 101 4.9. Subscriber processing of NOTIFY requests . . . . . . . . . 27 102 4.10. Handling of Forked Requests . . . . . . . . . . . . . . . 28 103 4.11. Rate of notifications . . . . . . . . . . . . . . . . . . 28 104 4.12. State Agents and Lists . . . . . . . . . . . . . . . . . . 28 105 4.13. Behavior of a Proxy Server . . . . . . . . . . . . . . . . 28 106 5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 28 107 5.1. DRegex . . . . . . . . . . . . . . . . . . . . . . . . . . 29 108 5.2. KPML Request . . . . . . . . . . . . . . . . . . . . . . . 29 109 5.3. KPML Response . . . . . . . . . . . . . . . . . . . . . . 32 110 6. Enumeration of KPML Status Codes . . . . . . . . . . . . . . . 33 111 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 112 7.1. SIP Event Package Registration . . . . . . . . . . . . . . 34 113 7.2. MIME Media Type application/kpml-request+xml . . . . . . . 34 114 7.3. MIME Media Type application/kpml-response+xml . . . . . . 35 115 7.4. URN Sub-Namespace Registration for 116 urn:ietf:xml:ns:kpml-request . . . . . . . . . . . . . . . 35 117 7.5. URN Sub-Namespace Registration for 118 urn:ietf:xml:ns:kpml-response . . . . . . . . . . . . . . 36 119 7.6. KPML Request Schema Registration . . . . . . . . . . . . . 37 120 7.7. KPML Response Schema Registration . . . . . . . . . . . . 37 121 8. Security Considerations . . . . . . . . . . . . . . . . . . . 37 122 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 123 9.1. Monitoring for Octothorpe . . . . . . . . . . . . . . . . 38 124 9.2. Dial String Collection . . . . . . . . . . . . . . . . . . 39 126 10. Call Flow Examples . . . . . . . . . . . . . . . . . . . . . . 40 127 10.1. Supplemental Digits . . . . . . . . . . . . . . . . . . . 40 128 10.2. Multiple Applications . . . . . . . . . . . . . . . . . . 44 129 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 52 130 11.1. Normative References . . . . . . . . . . . . . . . . . . . 52 131 11.2. Informative References . . . . . . . . . . . . . . . . . . 53 132 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 54 133 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 54 134 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 55 135 Intellectual Property and Copyright Statements . . . . . . . . . . 56 137 1. Introduction 139 This document describes a SIP Event Package "kpml" that enables 140 monitoring of key presses and utilizes XML documents referred to as 141 Key Press Markup Language (KPML). KPML is a markup [18] that enables 142 presentation-free User Interfaces as described in the Application 143 Interaction Framework [19]. The Key Press Stimulus Package is a SIP 144 Event Notification Package [5] that uses the SUBSCRIBE and NOTIFY 145 methods of SIP. The subscription filter and notification report 146 bodies use the Keypad Markup Language, KPML. 148 The "kpml" event package requires the definition of two new MIME 149 types, two new URN Sub-Namespaces, and two Schemas for the KPML 150 Request and the KPML Response. The scope of this package is for 151 collecting supplemental key presses or mid-call key presses 152 (triggers). This capability allows an Application Server service 153 provider to monitor (filter) for a set of DTMF patterns at a SIP User 154 Agent located either in an end user device or a gateway. 156 In particular, the "kpml" event package enables "dumb phones" and 157 "gateways" which receive signals from dumb phones to report user key- 158 press events. Colloquially, this mechanism provides for "digit 159 reporting" or "Dual-Tone Multi-Frequency (DTMF) reporting." The 160 capability eliminates the need for "hair-pinning" (routing media into 161 and then out of the same device) through a Media Server or 162 duplicating all the DTMF events, when an Application Server needs to 163 trigger mid-call service processing on DTMF digit patterns. 165 A goal of KPML is to fit in an extremely small memory and processing 166 footprint. 168 The name of the XML document, KPML, reflects its legacy support role. 169 The public switched telephony network (PSTN) accomplished signaling 170 by transporting DTMF tones in the bearer channel (in-band signaling) 171 from the user terminal to the local exchange. 173 Voice-over-IP networks transport in-band signals with actual DTMF 174 waveforms or RFC2833 [13] packets. In RFC2833, the signaling 175 application inserts RFC2833 named signal packets as well as, or 176 instead of, generating tones in the media path. The receiving 177 application receives the signal information in the media stream. 179 RFC2833 tones are ideal for conveying telephone-events point-to-point 180 in an RTP stream, as in the context of straightforward sessions like 181 a 2-party call or simple, centrally mixed conference. However, there 182 are other environments where additional or alternative requirements 183 are needed. These other environments include protocol translation 184 and complex call control. 186 An interested application could request notifications of every key 187 press. However, many of the use cases for such signaling show that 188 most applications are interested in only one or a few keystrokes. 189 Thus a mechanism is needed for specifying to the user's interface 190 what stimuli the application requires. 192 2. Protocol Overview 194 The "kpml" event package uses explicit subscription notification 195 requests using the SIP SUBSCRIBE and NOTIFY methods. An Application 196 that wants to collect digits creates an application/kpml-request+xml 197 document with the digit patterns of interest to the Application, and 198 places this document in its SUBSCRIBE request. SIP SUBSCRIBE 199 messages are routed to the User Interface using standard SIP request 200 routing. KPML Subscriptions do not fork. The KPML request contained 201 in the SUBSCRIBE message identifies the target media stream by 202 referencing the dialog identifiers corresponding to the session 203 responsible for the media stream. Once a subscription is 204 established, the User Interface sends application/kpml-response+xml 205 documents in NOTIFY requests when digits are collected or timeouts or 206 errors occur. 208 A KPML subscription can be persistent or one-shot. Persistent 209 requests are active until either the subscription terminates, the 210 Application replaces the request or the Application deletes the 211 request by sending a null document on the dialog, or the Application 212 explicitly deletes the subscription by sending a SUBCRIBE with an 213 expires value of zero (0). 215 One-shot requests terminate the subscription upon the receipt of DTMF 216 values which provide a match. The "persist" KPML element specifies 217 whether the subscription remains active for the duration specified in 218 the SUBSCRIBE message or if it automatically terminates upon a 219 pattern match. 221 NOTIFY messages can contain XML documents. If the User Interface 222 matches a digitmap, the NOTIFY message (response) contains an XML 223 document that indicates the User Input detected and whether the User 224 Interface suppressed the representation of User Input, such as tones, 225 or RFC2833, from the media streams. If the User Interface 226 encountered an error condition, such as a timeout, this will also be 227 reported. 229 3. Key Concepts 230 3.1. Subscription Duration 232 KPML recognizes two types of subscriptions: one-shot and persistent. 233 Persistent subscriptions have two sub-types: continuous notify and 234 single-notify. 236 One-shot subscriptions terminate after a pattern match occurs and a 237 report is issued in a NOTIFY message. If the User Interface detects 238 a key press stimulus that triggers a one-shot KPML event, then the 239 User Interface (notifier) MUST set the "Subscription-State" in the 240 NOTIFY message to "terminated". At this point the User Interface 241 MUST consider the subscription expired. 243 Persistent subscriptions remain active at the User Interface, even 244 after a match. For continuous notify persistent subscriptions, the 245 User Interface will emit a NOTIFY message whenever the User Input 246 matches a subscribed pattern. For single-notify persistent 247 subscriptions, the user device will emit a NOTIFY message at the 248 first match, but will not emit further NOTIFY messages until the 249 Application issues a new subscription request on the subscription 250 dialog. 252 NOTE: The single-notify persistent subscription enables lock step 253 (race-free) quarantining of User Input between different digit 254 maps. 256 The "persist" attribute to the tag in the KPML subscription 257 body affects the lifetime of the subscription. 259 If the "persist" attribute is "one-shot", then once there is a match 260 (or no match is possible), the subscription ends after the User 261 Interface notifies the Application. 263 If the "persist" attribute is "persist" or "single-notify", then the 264 subscription ends when the Application explicitly ends it or the User 265 Interface terminates the subscription. 267 If the User Interface does not support persistent subscriptions, it 268 returns a NOTIFY message with the KPML status code set to 531. If 269 there are digits in the buffer and the digits match an expression in 270 the SUBSCRIBE filter, the User Interface prepares the appropriate 271 NOTIFY response message. 273 The values of the "persist" attribute are case sensitive. 275 3.2. Timers 277 To address the various key press collection scenarios, three timers 278 are defined. They are the extra, critical, and inter-digit timers. 279 o The inter-digit timer is the maximum time to wait between digits. 280 Note: unlike MGCP [15] or H.248 [16], there is no start timer, as 281 that concept does not apply in the KPML context. 282 o The critical timer is the time to wait for another digit if the 283 collected digits can match more than one potential pattern. 284 o The extra timer is the time to wait for another digit if the 285 collected digits can only match one potential pattern, but a 286 longer match for this pattern is possible. 288 The User Interface MAY support an inter-digit timeout value. This is 289 the amount of time the User Interface will wait for User Input before 290 returning a timeout error result on a partially matched pattern. The 291 application can specify the inter-digit timeout as an integer number 292 of milliseconds by using the "interdigittimer" attribute to the 293 tag. The default is 4000 milliseconds. If the User 294 Interface does not support the specification of an inter-digit 295 timeout, the User Interface MUST silently ignore the specification. 296 If the User Interface supports the specification of an inter-digit 297 timeout, but not to the granularity specified by the value presented, 298 the User Interface MUST round up the requested value to the closest 299 value it can support. 301 The purpose of the inter-digit timeout is to protect applications 302 from starting to match a pattern, yet never return a result. This 303 can occur, for example, if the user accidentally enters a key that 304 begins to match a pattern. However, since the user accidentally 305 entered the key, the rest of the pattern never comes. Moreover, when 306 the user does enter a pattern, since they have already entered a key, 307 the pattern may not match, or may not match as expected. Likewise, 308 consider the case where the user thinks they entered a key press, but 309 the User Interface does not detect the key. This could occur when 310 collecting ten digits, but the device actually only receives 9. In 311 this case, the User Interface will wait forever for the tenth key 312 press, while the user becomes frustrated wondering why the 313 application is not responding. 315 The User Interface MAY support a critical-digit timeout value. This 316 is the amount of time the User Interface will wait for another key 317 press when it already has a matched but there is another, 318 longer that may also match the pattern. The application can 319 specify the critical-digit timeout as an integer number of 320 milliseconds by using the "criticaldigittimer" attribute to the 321 tag. The default is 1000 milliseconds. 323 The purpose of the critical-digit timeout is to allow the application 324 to collect longer matches than the shortest presented. This is 325 unlike MGCP [15], where the shortest match gets returned. For 326 example, if the application registers for the patterns "0011", "011", 327 "00", and "0", the critical-digit timeout enables the User Interface 328 to distinguish between "0", "00", "011", "0011". Without this 329 feature, the only value that the User Interface can detect is "0". 331 The User Interface MAY support an extra-digit timeout value. This is 332 the amount of time the User Interface will wait for another key press 333 when it already has matched the longest . The application can 334 specify the extra-digit timeout as an integer number of milliseconds 335 by using the "extradigittimer" attribute to the tag. The 336 default is 500 milliseconds. If there is no enterkey specified, then 337 the User Interface MAY default the exteradigittimer to zero. 339 The purpose of the extra-digit timeout is to allow the User Interface 340 to collect the enterkey. Without this feature, the User Interface 341 would match the pattern, and the enterkey would be buffered and 342 returned as the next pattern. 344 3.3. Pattern Matches 346 During the subscription lifetime, the User Interface may detect a key 347 press stimulus that triggers a KPML event. In this case, the User 348 Interface (notifier) MUST return the appropriate KPML document. 350 The pattern matching logic works as follows. KPML User Interfaces 351 MUST follow the logic presented in this section so that different 352 implementations will perform deterministically on the same KPML 353 document given the same User Input. 355 A kpml request document contains a element with a series of 356 tags. Each element specifies a potential pattern for 357 the User Interface to match. The Section 5.1 describes the DRegex, 358 or digit regular expression, language. 360 The pattern match algorithm matches the longest regular expression. 361 This is the same mode as H.248.1 [16] and not the mode presented by 362 MGCP [15]. The pattern match algorithm choice has an impact on 363 determining when a pattern matches. Consider the following KPML 364 document. 366 367 372 373 0 374 011 375 376 378 Figure 1: Greedy Matching 380 In Figure 1, if we were to match on the first found pattern, the 381 string "011" would never match. This happens because the "0" rule 382 would match first. 384 While this behavior is what most applications desire, it does come at 385 a cost. Consider the following KPML document snippet. 387 x{7} 388 x{10} 390 Figure 2: Timeout Matching 392 Figure 2 shows a typical North American dial plan. From an 393 application perspective, users expect a seven-digit number to respond 394 quickly, not waiting the typical inter-digit critical timer (usually 395 four seconds). Conversely, the User does not want the system to cut 396 off their ten-digit number at seven digits because they did not enter 397 the number fast enough. 399 One approach to this problem is to have an explicit dial string 400 terminator. Often, it is the pound key (#). Now, consider the 401 following snippet. 403 x{7}# 404 x{10}# 406 Figure 3: Timeout Matching with Enter 408 The problem with the approach in Figure 3 is that the "#" will appear 409 in the returned dial string. Moreover, one often wants to allow the 410 user to enter the string without the dial string termination key. In 411 addition, using explicit matching on the key means one has to double 412 the number of patterns, e.g., "x{7}", "x{7}#", "x{10}", and "x{10}#". 414 The approach used in KPML is to have an explicit "Enter Key", as 415 shown in the following snippet. 417 418 x{7} 419 x{10} 420 422 Figure 4: Timeout Matching with Enter Key 424 In Figure 4, the enterkey attribute to the tag specifies a 425 string that terminates a pattern. In this situation, if the user 426 enters seven digits followed by the "#" key, the pattern matches (or 427 fails) immediately. KPML indicates a terminated nomatch with a KPML 428 status code 402. 429 NOTE: The enterkey is a string. The enterkey can be a sequence of 430 key presses, such as "**". 432 Some patterns look for long duration key presses. For example, some 433 applications look for long "#" or long "*". 435 KPML uses the "L" modifier to characters to indicate long key 436 presses. The following KPML document looks for a long pound of at 437 least 3 seconds. 439 440 445 446 L# 447 448 450 Long Pound 452 The request can specify what constitutes "long" by setting the long 453 attribute to the . This attribute is an integer 454 representing the number of milliseconds. If the user presses a key 455 for longer than "long" milliseconds, the Long modifier is true. The 456 default length of the long attribute is 2500 milliseconds. 458 User Interfaces MUST distinguish between long and short input when 459 the KPML document specifies both in a document. However, if there is 460 not a corresponding long key press pattern in a document, the User 461 Interface MUST match the key press pattern irrespective of the length 462 of time the user presses the key. 464 As an example, in the following snippet in Figure 6, the User 465 Interface discriminates between a long "*" and a normal "*", but any 466 length "#" will match the pattern. 468 469 * 470 L* 471 # 472 474 Figure 6: Long and Short Matching 476 Some User Interfaces are unable to present long key presses. An 477 example is an old private branch exchange (PBX) phone set that emits 478 fixed-length tones when the user presses a key. To address this 479 issue, the User Interface MAY interpret a succession of presses of a 480 single key to be equivalent to a long key press of the same key. The 481 Application indicates it wants this behavior by setting the 482 "longrepeat" attribute to the to "true". 484 The KPML document specifies if the patterns are to be persistent by 485 setting the "persist" attribute to the tag to "persist" or 486 "single-notify". Any other value, including "one-shot", indicates 487 the request is a one-shot subscription. If the User Interface does 488 not support persistent subscriptions, it returns a KPML document with 489 the KPML status code set to 531. If there are digits in the buffer 490 and the digits match an expression in the KPML document, the User 491 Interface emits the appropriate kpml notification. 493 Note the values of the "persist" attribute are case sensitive. 495 Some User Interfaces may support multiple regular expressions in a 496 given pattern request. In this situation, the application may wish 497 to know which pattern triggered the event. 499 KPML provides a "tag" attribute to the tag. The "tag" is an 500 opaque string that the User Interface sends back in the notification 501 report upon a match in the digit map. In the case of multiple 502 matches, the User Interface MUST chose the longest match in the KPML 503 document. If multiple matches match the same length, the User 504 Interface MUST chose the first expression listed in the subscription 505 KPML document based on KPML document order. 507 If the User Interface cannot support multiple regular expressions in 508 a pattern request, the User Interface MUST return a KPML document 509 with the KPML status code set to 532. If the User Interface cannot 510 support the number of regular expressions in the pattern request, the 511 User Interface MUST return a KPML document with the KPML status code 512 set to 534. 514 NOTE: We could mandate a minimum number of regular expressions a 515 User Interface must support per subscription request and globally. 516 However, such minimums tend to become designed-in, hard-coded 517 limits. For guidance, one should be able to easily handle tens of 518 expressions per subscription and thousands globally. A good 519 implementation should have effectively no limits. That said, to 520 counter possible denial of service attacks, implementers of User 521 Interfaces should be aware of the 534 and 501 status codes, and 522 feel free to use them. 524 3.4. Digit Suppression 526 Under basic operation, a KPML User Interface will transmit in-band 527 tones (RFC2833 [13] or actual tone) in parallel with User Input 528 reporting. 530 NOTE: If KPML did not have this behavior, then a User Interface 531 executing KPML could easily break called applications. For 532 example, take a personal assistant that uses "*9" for attention. 533 If the user presses the "*" key, KPML will hold the digit, looking 534 for the "9". What if the user just enters a "*" key, possibly 535 because they accessed an IVR system that looks for "*"? In this 536 case, the "*" would get held by the User Interface, because it is 537 looking for the "*9" pattern. The user would probably press the 538 "*" key again, hoping that the called IVR system just did not hear 539 the key press. At that point, the User Interface would send both 540 "*" entries, as "**" does not match "*9". However, that would not 541 have the effect the user intended when they pressed "*". 543 On the other hand, there are situations where passing through tones 544 in-band is not desirable. Such situations include call centers that 545 use in-band tone spills to initiate a transfer. 547 For those situations, KPML adds a suppression tag, "pre", to the 548 tag. There MUST NOT be more than one 
 tag in any given
549	    tag.

551	   If there is only a single  and a single , suppression
552	   processing is straightforward.  The end-point passes User Input until
553	   the stream matches the regular expression 
.  At that point, the
554	   User Interface will continue collecting User Input, but will suppress
555	   the generation or pass-through of any in-band User Input.

557	   If the User Interface suppressed stimulus, it MUST indicate this by
558	   including the attribute "suppressed" with a value of "true" in the
559	   notification.

561	   Clearly, if the User Interface is processing the KPML document
562	   against buffered User Input, it is too late to suppress the
563	   transmission of the User Input, as the User Interface has long sent
564	   the stimulus.  This is a situation where there is a 
565	   specification, but the "suppressed" attribute will not be "true" in
566	   the notification.  If there is a 
 tag that the User Interface
567	   matched and the User Interface is unable to suppress the User Input,
568	   it MUST set the "suppressed" attribute to "false".

570	   A KPML User Interface MAY perform suppression.  If it is not capable
571	   of suppression, it ignores the suppression attribute.  It MUST set
572	   the "suppressed" attribute to "false".  In this case, the pattern to
573	   match is the concatenated pattern of pre+value.

575	   At some point in time, the User Interface will collect enough User
576	   Input to the point it matches a 
 pattern.  The interdigittimer
577	   attribute indicates how long to wait for the user enters stimulus
578	   before reporting a time-out error.  If the interdigittimer expires,
579	   the User Interface MUST issue a time-out report, transmit the
580	   suppressed User Input on the media stream, and stop suppression.

582	   Once the User Interface detects a match and it sends a NOTIFY request
583	   to report the User Input, the User Interface MUST stop suppression.
584	   Clearly, if subsequent User Input matches another 
 expression,
585	   then the User Interface MUST start suppression.

587	   After suppression begins, it may become clear that a match will not
588	   occur.  For example, take the expression
589	   
*8
xxx[2-9]xxxxxx
590	   At the point the User Interface receives "*8", it will stop
591	   forwarding stimulus.  Let us say that the next three digits are
592	   "408".  If the next digit is a zero or one, the pattern will not
593	   match.

595	      NOTE: It is critically important for the User Interface to have a
596	      sensible inter-digit timer.  This is because an errant dot (".")
597	      may suppress digit sending forever.

599	   Applications should be very careful to indicate suppression only when
600	   they are fairly sure the user will enter a digit string that will
601	   match the regular expression.  In addition, applications should deal
602	   with situations such as no-match or time-out.  This is because the
603	   User Interface will hold digits, which will have obvious User
604	   Interface issues in the case of a failure.

606	3.5.  User Input Buffer Behavior

608	   User Interfaces MUST buffer User Input upon receipt of an
609	   authenticated and accepted subscription.  Subsequent KPML documents
610	   apply their patterns against the buffered User Input.  Some
611	   applications use modal interfaces where the first few key presses
612	   determine what the following key presses mean.  For a novice user,
613	   the application may play a prompt describing what mode the
614	   application is in.  However, "power users" often barge through the
615	   prompt.

617	   User Interfaces MUST NOT provide a subscriber with digits that were
618	   detected prior to the authentication and authorization of that
619	   subscriber.  Without prohibition, a subscriber might be able to gain
620	   access to calling card or other information that predated the
621	   subscriber's participation in the call.  Note that this prohibition
622	   MUST be applied on a per-subscription basis.

624	   KPML provides a  tag in the  element.  The default is
625	   not to flush User Input.  Flushing User Input has the effect of
626	   ignoring key presses entered before the installation of the KPML
627	   subscription.  To flush User Input, include the tag
628	   yes
629	   in the KPML subscription document.  Note that this directive affects
630	   only the current subscription dialog/id combination.

632	   Lock step processing of User Input is where the User Interface issues
633	   a notification, the Application processes the notification while the
634	   User Interface buffers additional User Input, the Application
635	   requests more User Input, and only then does the User Interface
636	   notify the Application based on the collected User Input.  To direct
637	   the User Interface to operate in lock-step mode, set the 
638	   attribute persist="single-notify".

640	   The User Interface MUST be able to process no.  This
641	   directive is effectively a no-op.

643	   Other string values for  may be defined in the future.  If the
644	   User Interface receives a string it does not understand, it MUST
645	   treat the string as a no-op.

647	   If the user presses a key that cannot match any pattern within a
648	    tag, the User Interface MUST discard all buffered key presses
649	   up to and including the current key press from consideration against
650	   the current or future KPML documents on a given dialog.  However, as
651	   described above, once there is a match, the User Interface buffers
652	   any key presses the user entered subsequent to the match.

654	      NOTE: This behavior allows for applications to receive only User
655	      Input that is of interest to them.  For example, a pre-paid
656	      application only wishes to monitor for a long pound.  If the user
657	      enters other stimulus, presumably for other applications, the pre-
658	      paid application does not want notification of that User Input.
659	      This feature is fundamentally different than the behavior of TDM-
660	      based equipment where every application receives every key press.

662	   To limit reports to only complete matches, set the "nopartial"
663	   attribute to the  tag to "true".  In this case, the User
664	   Interface attempts to match a rolling window over the collected User
665	   input.

667	   KPML subscriptions are independent.  Thus it is not possible for the
668	   current document to know if a following document will enable barging
669	   or want User Input flushed.  Therefore, the User Interface MUST
670	   buffer all User Input, subject to the forced_flush caveat described
671	   below.

673	   On a given SUBSCRIBE dialog with a given id, the User Interface MUST
674	   buffer all User Input detected between the time of the report and the
675	   receipt of the next document, if any.  If the next document indicates
676	   a buffer flush, then the interpreter MUST flush all collected User
677	   Input from consideration from KPML documents received on that dialog
678	   with the given event id.  If the next document does not indicate
679	   flushing the buffered User Input, then the interpreter MUST apply the
680	   collected User Input (if possible) against the digit maps presented
681	   by the script's  tags.  If there is a match, the interpreter
682	   MUST follow the procedures in Section 5.3.  If there is no match, the
683	   interpreter MUST flush all of the collected User Input.

685	   Given the potential for needing an infinite buffer for User Input,
686	   the User Interface MAY discard the oldest User Input from the buffer.
687	   If the User Interface discards digits, when the User Interface issues
688	   a KPML notification, it MUST set the forced_flush attribute of the
689	    tag to "true".  For future use, the Application MUST
690	   consider any non-null value, other than "false" that it does not
691	   understand, to be the same as "true".
692	      NOTE: The requirement to buffer all User Input for the entire
693	      length of the session is not Onerous under normal operation.  For
694	      example, if one has a gateway with 8,000 sessions, and the gateway
695	      buffers 50 key presses on each session, the requirement is only
696	      400,000 bytes, assuming one byte per key press.

698	   Unless there is a suppress indicator in the digit map, it is not
699	   possible to know if the User Input is for local KPML processing or
700	   for other recipients of the media stream.  Thus, in the absence of a
701	   suppression indicator, the User Interface transmits the User Input to
702	   the far end in real time, using either RFC2833, generating the
703	   appropriate tones, or both.

705	3.6.  DRegex

707	3.6.1.  Overview

709	   This subsection is informative in nature.

711	   The Digit REGular EXpression (DRegex) syntax is a telephony-oriented
712	   mapping of POSIX Extended Regular Expressions (ERE) [17].

714	   KPML does not use full POSIX ERE for the following reasons.
715	   o  KPML will often run on high density or extremely low power and
716	      memory footprint devices.
717	   o  Telephony application convention uses the star symbol ("*") for
718	      the star key and "x" for any digit 0-9.  Requiring the developer
719	      to escape the star ("\*") and expand the "x" ("[0-9]") is error
720	      prone.  This also leads DRegex to use the dot (".") to indicate
721	      repetition, which was the function of the unadorned star in POSIX
722	      ERE.
723	   o  Implementation experience with MGCP [15] and H.248.1 [16] has been
724	      that implementers and users have a hard time understanding the
725	      precedence of the alternation operator ("|").  This is due both to
726	      an under specification of the operator in those documents and
727	      conceptual problems for users.  Thus the SIPPING Working Group
728	      concluded that DRegex should not support alternation.  That said,
729	      each KPML  element may contain multiple regular
730	      expressions ( elements).  Thus it is straightforward to
731	      have pattern alternatives (use multiple  elements) without
732	      the problems associated with the alternation operator ("|").  Thus
733	      DRegex does not support the POSIX alternation operator.
734	   o  DRegex includes character classes (characters enclosed in square
735	      brackets).  However, the negation operator inside a character
736	      class only operates on numbers.  That is, a negation class
737	      implicitly includes A-D, *, and #.  Including A-D, *, and # in a
738	      negation operator is a no-op.  Those familiar with POSIX would
739	      expect negation of the digits 4 and 5, e.g., "[^45]", to include
740	      all other characters (including A-D, R, *, and #), while those
741	      familiar with telephony digit maps would expect negation to
742	      implicitly exclude non-digit characters.  Since the complete
743	      character set of DRegex is very small, constructing a negation
744	      class using A-D, R, *, and # requires the user to specify the
745	      positive inverse mapping.  For example, to specify all key
746	      presses, including A-D and *, except #, the specification would be
747	      "[0-9A-D*]" instead of "[^#R]".

749	   The following table shows the mapping from DRegex to POSIX ERE.

751	                          +--------+-----------+
752	                          | DRegex | POSIX ERE |
753	                          +--------+-----------+
754	                          | *      | \*        |
755	                          | .      | *         |
756	                          | x      | [0-9]     |
757	                          | [xc]   | [0-9c]    |
758	                          +--------+-----------+

760	                   Table 1: DRegex to POSIX ERE Mapping

762	   The first substitution, which replaces a star for an escaped star, is
763	   because telephony application designers are used to using the star
764	   for the (very common) star key.  Requiring an escape sequence for
765	   this common pattern would be error prone.  In addition, the usage
766	   found in DRegex is the same as found in MGCP [15] and H.248.1 [16].

768	   Likewise, the use of the dot instead of star is common usage from
769	   MGCP and H.248.1, and reusing the star in this context would also be
770	   confusing and error prone.

772	   The "x" character is a common indicator of the digits 0 through 9.
773	   We use it here, continuing the convention.  Clearly, for the case
774	   "[xc]", where c is any character, the substitution is not a blind
775	   replacement of "[0-9]" for "x", as that would result in "[[0-9]c]",
776	   which is not a legal POSIX ERE.  Rather, the substitution for "[xc]"
777	   is "[0-9c]".

779	      NOTE: "x" does not include the characters *, #, R, nor A through
780	      D.

782	   Users need to take care not to confuse the DRegex syntax with POSIX
783	   EREs.  They are NOT identical.  In particular there are many features
784	   of POSIX EREs that DRegex does not support.

786	   As an implementation note, if one makes the substitutions described
787	   in the above table, then a standard POSIX ERE engine can parse the
788	   digit string.  However, the mapping does not work in the reverse
789	   (POSIX ERE to DRegex) direction.  DRegex only implements the
790	   normative behavior described below.

792	3.6.2.  Operation

794	   White space is removed before parsing DRegex.  This enables sensible
795	   pretty printing in XML without affecting the meaning of the DRegex
796	   string.

798	   The following rules demonstrate the use of DRegex in KPML.

800	   +---------+---------------------------------------------------------+
801	   | Entity  | Matches                                                 |
802	   +---------+---------------------------------------------------------+
803	   | c       | digits 0-9, *, #, R, and A-D (case insensitive)         |
804	   | *       | the * character                                         |
805	   | #       | the # character                                         |
806	   | R       | The R (Register Recall) key                             |
807	   | [c]     | Any character in selector                               |
808	   | [^d]    | Any digit (0-9) not in selector                         |
809	   | [r1-r2] | Any character in range from r1 to r2, inclusive         |
810	   | x       | Any digit 0-9                                           |
811	   | {m}     | m repetitions of previous pattern                       |
812	   | {m,}    | m or more repetitions of previous pattern               |
813	   | {,n}    | At most n (including zero) repetitions of previous      |
814	   |         | pattern                                                 |
815	   | {m,n}   | at least m and at most n repetitions of previous        |
816	   |         | pattern                                                 |
817	   | Lc      | Match the character c if it is "long"; c is a digit 0-9 |
818	   |         | and A-D, #, or *.                                       |
819	   +---------+---------------------------------------------------------+

821	                              DRegex Entities

823	   For ranges, the A-D characters are disjoint from the 0-9 characters.
824	   If the device does not have an "R" key, the device MAY report a hook
825	   flash as an R character.

827	       +--------------+--------------------------------------------+
828	       | Example      | Description                                |
829	       +--------------+--------------------------------------------+
830	       | 1            | Matches the digit 1                        |
831	       | [179]        | Matches 1, 7, or 9                         |
832	       | [2-9]        | Matches 2, 3, 4, 5, 6, 7, 8, 9             |
833	       | [^15]        | Matches 0, 2, 3, 4, 6, 7, 8, 9             |
834	       | [02-46-9A-D] | Matches 0, 2, 3, 4, 6, 7, 8, 9, A, B, C, D |
835	       | x            | Matches 0, 1, 2, 3, 4, 5, 6, 7, 8, 9       |
836	       | *6[179#]     | Matches *61, *67, *69, or *6#              |
837	       | x{10}        | Ten digits (0-9)                           |
838	       | 011x{7,15}   | 011 followed by seven to fifteen digits    |
839	       | L*           | Long star                                  |
840	       +--------------+--------------------------------------------+

842	                              DRegex Examples

844	3.7.  Monitoring Direction

846	   SIP identifies dialogs by their dialog identifier.  The dialog
847	   identifier is the remote-tag, local-tag, and Call-ID entities defined
848	   in RFC3261 [4].

850	   One method of determining the dialog identifier, particularly for
851	   third-party applications, is the SIP Dialog Package [21].

853	   For most situations, such as a monaural point-to-point call with a
854	   single codec, the stream to monitor is obvious.  In such situations
855	   the Application need not specify which stream to monitor.

857	   But there may be ambiguity in specifying only the SIP dialog to
858	   monitor.  The dialog may specify multiple SDP streams that could
859	   carry key press events.  For example, a dialog may have multiple
860	   audio streams.  Wherever possible, the User Interface MAY apply local
861	   policy to disambiguate which stream or streams to monitor.  In order
862	   to have an extensible mechanism for identifying streams, the
863	   mechanism for specifying streams is as an element content to the
864	    tag.  The only content defined today is the
865	   reverse tag.

867	   By default, the User Interface monitors key presses emanating from
868	   the User Interface.  Given a dialog identifier of Call-ID, local-tag,
869	   and remote-tag, the User Interface monitors the key presses
870	   associated with the local-tag.

872	   In the media proxy case, and potentially other cases, there is a need
873	   to monitor the key presses arriving from the remote user agent.  The
874	   optional  element to the  tag specifies which stream
875	   to monitor.  The only legal value is "reverse", which means to
876	   monitor the stream associated with the remote-tag.  The User
877	   Interface MUST ignore other values.
878	      NOTE: The reason this is a tag is so individual stream selection,
879	      if needed, can be addressed in a backwards-compatible way.
880	      Further specification of the stream to monitor is the subject of
881	      future standardization.

883	3.8.  Multiple Simultaneous Subscriptions

885	   An Application MAY register multiple User Input patterns in a single
886	   KPML subscription.  If the User Interface supports multiple,
887	   simultaneous KPML subscriptions, the Application installs the
888	   subscriptions either in a new SUBSCRIBE-initiated dialog or on an
889	   existing SUBSCRIBE-initiated dialog with a new event id tag.  If the
890	   User Interface does not support multiple, simultaneous KPML
891	   subscriptions, the User Interface MUST respond with an appropriate
892	   KPML status code.

894	   Some User Interfaces may support multiple key press event
895	   notification subscriptions at the same time.  In this situation, the
896	   User Interface honors each subscription individually and
897	   independently.

899	   A SIP user agent may request multiple subscriptions on the same
900	   SUBSCRIBE dialog, using the id parameter to the kpml event request.

902	   One or more SIP user agents may request independent subscriptions on
903	   different SIP dialogs, although reusing the same dialog for multiple
904	   subscriptions is NOT RECOMMENDED.

906	   If the User Interface does not support multiple, simultaneous
907	   subscriptions, the User Interface MUST return a KPML document with
908	   the KPML status code set to 533 on the dialog that requested the
909	   second subscription.  The User Interface MUST NOT modify the state of
910	   the first subscription on account of the second subscription attempt.

912	4.  Event Package Formal Definition

914	4.1.  Event Package Name

916	   This document defines a SIP Event Package as defined in RFC 3265 [5].
917	   The event-package token name for this package is:

919	           "kpml"

921	4.2.  Event Package Parameters

923	   This package defines three Event Package parameters: call-id, remote-
924	   tag, and local-tag.  These parameters MUST be present, to identify
925	   the subscription dialog.  The User Interface matches the local-tag
926	   against the to tag, the remote-tag against the from tag, and the
927	   call-id against the Call-ID.

929	   call-id = "call-id" EQUAL ( token / DQUOTE callid DQUOTE )
930	   ;; NOTE: any DQUOTEs inside callid MUST be escaped!
931	   remote-tag = "remote-tag" EQUAL token
932	   local-tag = "local-tag" EQUAL token

934	   If any call-ids contain embedded double-quotes, those double-quotes
935	   MUST be escaped using the backslash-quoting mechanism.  Note that the
936	   call-id parameter may need to be expressed as a quoted string.  This
937	   is because the ABNF for the callid production and the word
938	   production, which is used by callid (both from RFC 3261 [1]), allow
939	   some characters (such as "@", "[", and ":") that are not allowed
940	   within a token.

942	4.3.  SUBSCRIBE Bodies

944	   Applications using this event package include an application/
945	   kpml-request+xml body in SUBSCRIBE requests to indicate which digit
946	   patterns they are interested in.  The syntax of this body type is
947	   formally described in Section 5.2

949	4.4.  Subscription Duration

951	   The subscription lifetime should be longer than the expected call
952	   time.  Subscriptions to this event package MAY range from minutes to
953	   weeks.  Subscriptions in hours or days are more typical and are
954	   RECOMMENDED.  The default subscription duration for this event
955	   package is 7200 seconds.
956	      Subscribers MUST be able to handle the User Interface returning an
957	      Expires value smaller than the requested value.  Per RFC3265 [5],
958	      the subscription duration is the value returned by the Notifier in
959	      the 200 OK Expires header.

961	4.5.  NOTIFY Bodies

963	   NOTIFY requests can contain application/kpml-response+xml (KPML
964	   Response) bodies.  The syntax of this body type is formally described
965	   in Section 5.3.  NOTIFY requests in immediate response to a SUBSCRIBE
966	   request MUST NOT contain a body unless notifying the subscriber of an
967	   error condition or previously buffered digits.

969	   Notifiers MAY send notifications with any format acceptable to the
970	   subscriber (based on the subscriber inclusion of these formats in an
971	   Accept header).  A future extension MAY define other NOTIFY bodies.
972	   If no "Accept" header is present in the SUBSCRIBE, the body type
973	   defined in this document MUST be assumed.

975	4.6.  Subscriber generation of SUBSCRIBE requests

977	   A kpml request document contains a  element with a series of
978	    tags.  Each  element specifies a potential pattern for
979	   the User Interface to match.  The Section 5.1 describes the DRegex,
980	   or digit regular expression, language.

982	   KPML specifies key press event notification filters.  The MIME type
983	   for KPML requests is application/kpml-request+xml.

985	   The KPML request document MUST be well formed and SHOULD be valid.
986	   KPML documents MUST conform to XML 1.0 [18] and MUST use UTF-8
987	   encoding.

989	   Because of the potentially sensitive nature of the information
990	   reported by KPML, subscribers SHOULD use sips: and MAY use S/MIME on
991	   the content.

993	   Subscribers MUST be prepared for the notifier to insist on
994	   authentication of the subscription request.  Subscribers MUST be
995	   prepared for the notifier to insist on using a secure communication
996	   channel.

998	4.7.  Notifier processing of SUBSCRIBE requests

1000	   The user information transported by KPML is potentially sensitive.
1001	   For example, it could include calling card or credit card numbers.
1002	   Thus the User Interface (notifier) MUST authenticate the requesting
1003	   party in some way before accepting the subscription.

1005	   User Interfaces MUST implement SIP Digest authentication as required
1006	   by RFC3261 [4] and MUST implement the sips: scheme and TLS.

1008	   Upon authenticating the requesting party, the User Interface
1009	   determines if the requesting party has authorization to monitor the
1010	   user's key presses.  Determining authorization policies and
1011	   procedures is beyond the scope of this specification.

1013	   The User Interface returns a Contact URI that may have GRUU [9]
1014	   properties in the Contact header of a SIP INVITE, 1xx, or 2xx
1015	   response.

1017	   After authorizing the request, the User Interface checks to see if
1018	   the request is to terminate a subscription.  If the request will
1019	   terminate the subscription, the User Interface does the appropriate
1020	   processing, including the procedures described in Section 5.2.

1022	   If the request has no KPML body, then any KPML document running on
1023	   that dialog, and addressed by the event id, if present, immediately
1024	   terminates.  This is a mechanism for unloading a KPML document while
1025	   keeping the SUBSCRIBE-initiated dialog active.  This can be important
1026	   for secure sessions that have high costs for session establishment.
1027	   The User Interface follows the procedures described in Section 5.2.

1029	   If the dialog referenced by the kpml subscription does not exist, the
1030	   User Interface follows the procedures in Section 5.3.  Note the User
1031	   Interface MUST issue a 200 OK to the SUBSCRIBE request before issuing
1032	   the NOTIFY, as the SUBSCRIBE itself is well formed.

1034	   If the request has a KPML body, the User Interface parses the KPML
1035	   document.  The User Interface SHOULD validate the XML document
1036	   against the schema presented in Section 5.2.  If the document is not
1037	   valid, the User Interface rejects the SUBSCRIBE request with an
1038	   appropriate error response and terminates the subscription.  If there
1039	   is a loaded KPML document on the subscription, the User Interface
1040	   unloads the document.

1042	   In addition, if there is a loaded KPML document on the subscription,
1043	   the end device unloads the document.

1045	   Following the semantics of SUBSCRIBE, if the User Interface receives
1046	   a resubscription, the User Interface MUST terminate the existing KPML
1047	   request and replace it with the new request.

1049	   It is possible for the INVITE usage of the dialog to terminate during
1050	   key press collection.  The cases enumerated here are explicit
1051	   subscription termination, automatic subscription termination, and
1052	   underlying (INVITE-initiated) dialog termination.

1054	   If a SUBSCRIBE request has an expires of zero (explicit SUBSCRIBE
1055	   termination), includes a KPML document, and there is buffered User
1056	   Input, then the User Interface attempts to process the buffered
1057	   digits against the document.  If there is a match, the User Interface
1058	   MUST generate the appropriate KPML report with the KPML status code
1059	   of 200.  The SIP NOTIFY body terminates the subscription by setting
1060	   the subscription state to "terminated" and a reason of "timeout".

1062	   If the SUBSCRIBE request has an expires of zero and no KPML body or
1063	   the expires timer on the SUBSCRIBE-initiated dialog fires at the User
1064	   Interface (notifier), then the User Interface MUST issue a KPML
1065	   report with the KPML status code 487, Subscription Expired.  The
1066	   report also includes the User Input collected up to the time the
1067	   expires timer expired or when the subscription with expires equal to
1068	   zero was processed.  This could be the null string.

1070	   Per the mechanisms of RFC3265 [5], the User Interface MUST terminate
1071	   the SIP SUBSCRIBE dialog.  The User Interface does this via the SIP
1072	   NOTIFY body transporting the final report described in the preceding
1073	   paragraph.  In particular, the subscription state will be
1074	   "terminated" and a reason of "timeout".

1076	   Terminating the subscription when a dialog terminates ensures
1077	   reauthorization (if necessary) for attaching to subsequent
1078	   subscriptions.

1080	   If a SUBSCRIBE request references a dialog that is not present at the
1081	   User Interface, the User Interface MUST generate a KPML report with
1082	   the KPML status code 481, Dialog Not Found.  The User Interface
1083	   terminates the subscription by setting the subscription state to
1084	   "terminated".

1086	   If the KPML document is not valid, the User Interface generates a
1087	   KPML report with the KPML status code 501, Bad Document.  The User
1088	   Interface terminates the subscription by setting the subscription
1089	   state to "terminated".

1091	   If the document is valid but the User Interface does not support a
1092	   namespace in the document, the User Interface MUST respond with a
1093	   KPML status code 502, Namespace Not Supported.

1095	4.8.  Notifier generation of NOTIFY requests

1097	   Immediately after a subscription is accepted, the Notifier MUST send
1098	   a NOTIFY with the current location information as appropriate based
1099	   on the identity of the subscriber.  This allows the Subscriber to
1100	   resynchronize its state.

1102	   The User Interface (notifier in SUBSCRIBE/NOTIFY parlance) generates
1103	   NOTIFY requests based on the requirements of RFC3265 [5].
1104	   Specifically, if a SUBSCRIBE request is valid and authorized, it will
1105	   result in an immediate NOTIFY.

1107	   The KPML payload distinguishes between an initial NOTIFY and a NOTIFY
1108	   informing of key presses.  If there is no User Input buffered at the
1109	   time of the SUBSCRIBE (see below) or the buffered User Input does not
1110	   match the new KPML document, then the immediate NOTIFY MUST NOT
1111	   contain a KPML body.  If User Interface has User Input buffered that
1112	   result in a match using the new KPML document, then the NOTIFY MUST
1113	   return the appropriate KPML document.

1115	   The NOTIFY in response to a SUBSCRIBE request has no KPML if there
1116	   are no matching buffered digits.  An example of this is in Figure 10.

1118	   If there are buffered digits in the SUBSCRIBE request that match a
1119	   pattern, then the NOTIFY message in response to the SUBSCRIBE request
1120	   MUST include the appropriate KPML document.

1122	   NOTIFY sip:application@example.com SIP/2.0
1123	   Via: SIP/2.0/UDP proxy.example.com
1124	   Max-Forwards: 70
1125	   To: 
1126	   From: 
1127	   Call-Id: 439hu409h4h09903fj0ioij
1128	   Subscription-State: active; expires=7200
1129	   CSeq: 49851 NOTIFY
1130	   Event: kpml

1132	                    Figure 10: Immediate NOTIFY Example

1134	   All subscriptions MUST be authenticated, particularly those that
1135	   match on buffered input.

1137	   KPML specifies the key press notification report format.  The MIME
1138	   type for KPML reports is application/kpml-response+xml.  The default
1139	   MIME type for the kpml event package is application/
1140	   kpml-response+xml.

1142	   If the requestor is not using a secure transport protocol such as TLS
1143	   for every hop (e.g., by using a sips: URI), the User Interface SHOULD
1144	   use S/MIME to protect the user information in responses.

1146	   When the user enters key press(es) that match a  tag, the User
1147	   Interface will issue a report.

1149	   After reporting, the interpreter terminates the KPML session unless
1150	   the subscription has a persistence indicator.  If the subscription
1151	   does not have a persistence indicator, the User Interface MUST set
1152	   the state of the subscription to "terminated" in the NOTIFY report.

1154	   If the subscription does not have a persistence indicator, to collect
1155	   more digits the requestor must issue a new request.

1157	      NOTE: This highlights the "one shot" nature of KPML, reflecting
1158	      the balance of features and ease of implementing an interpreter.

1160	   KPML reports have two mandatory attributes, code and text.  These
1161	   attributes describe the state of the KPML interpreter on the User
1162	   Interface.  Note the KPML status code is not necessarily related to
1163	   the SIP result code.  An important example of this is where a legal
1164	   SIP subscription request gets a normal SIP 200 OK followed by a
1165	   NOTIFY, but there is something wrong with the KPML request.  In this
1166	   case, the NOTIFY would include the KPML status code in the KPML
1167	   report.  Note that from a SIP perspective, the SUBSCRIBE and NOTIFY
1168	   were successful.  Also, if the KPML failure is not recoverable, the
1169	   User Interface will most likely set the Subscription-Sate to
1170	   "terminated".  This lets the SIP machinery know the subscription is
1171	   no longer active.

1173	   If a pattern matches, the User Interface will emit a KPML report.
1174	   Since this is a success report, the code is "200" and the text is
1175	   "OK".

1177	   The KPML report includes the actual digits matched in the digit
1178	   attribute.  The digit string uses the conventional characters '*' and
1179	   '#' for star and octothorpe respectively.  The KPML report also
1180	   includes the tag attribute if the regex that matched the digits had a
1181	   tag attribute.

1183	   If the subscription requested digit suppression and the User
1184	   Interface suppressed digits, the suppressed attribute indicates
1185	   "true".  The default value of suppressed is "false".

1187	      NOTE: KPML does not include a timestamp.  There are a number of
1188	      reasons for this.  First, what timestamp would in include?  Would
1189	      it be the time of the first detected key press?  The time the
1190	      interpreter collected the entire string?  A range?  Second, if the
1191	      RTP timestamp is a datum of interest, why not simply get RTP in
1192	      the first place?  That all said, if it is really compelling to
1193	      have the timestamp in the response, it could be an attribute to
1194	      the  tag.

1196	   Note that if the monitored (INVITE-initiated) dialog terminates, the
1197	   Notifier still MUST explicitly terminate the KPML subscriptions
1198	   monitoring that dialog.

1200	4.9.  Subscriber processing of NOTIFY requests

1202	   If there is no KPML body, it means the SUBSCRIBE was successful.
1203	   This establishes the dialog if there is no buffered User Input to
1204	   report.

1206	   If there is a KPML document, and the KPML status code is 200, then a
1207	   match occurred.

1209	   If there is a KPML document, and the KPML status code is between 400
1210	   and 499, then an error occurred with User Input collection.  The most
1211	   likely cause is a timeout condition.

1213	   If there is a KPML document, and the KPML status code is between 500
1214	   and 599, then an error occurred with the subscription.  See Section 6
1215	   for more on the meaning of KPML status codes.

1217	   The subscriber MUST be mindful of the subscription state.  The User
1218	   Interface may terminate the subscription at any time.

1220	4.10.  Handling of Forked Requests

1222	   Forked requests are NOT ALLOWED for this event type.  This can be
1223	   ensured if the Subscriptions to this event package are sent to SIP
1224	   URIs which have GRUU properties.

1226	4.11.  Rate of notifications

1228	   The User Interface MUST NOT generate messages faster than 25 messages
1229	   per second, or one message every 40 milliseconds.  This is the
1230	   minimum time period for MF digit spills.  Even 30-millisecond DTMF,
1231	   as one sometimes finds in Japan, has a 20-millisecond off time,
1232	   resulting in a 50-millisecond interdigit time.  This document
1233	   strongly RECOMMENDS AGAINST using KPML for digit-by-digit messaging,
1234	   such as would be the case if the only  is "x".

1236	   The sustained rate of notification shall be no more than 100 Notifies
1237	   per minute.

1239	   The User Interface MUST reliably deliver notifications.  Because
1240	   there is no meaningful metric for throttling requests, the User
1241	   Interface SHOULD send NOTIFY messages over a congestion-controlled
1242	   transport, such as TCP.
1243	      Note that all SIP implementations are already required to
1244	      implement SIP over TCP.

1246	4.12.  State Agents and Lists

1248	   KPML requests are sent to a specific SIP URI, which may have GRUU
1249	   properties, and attempt to monitor a specific stream that corresponds
1250	   with a specific target dialog.  Consequently, implementers MUST NOT
1251	   define state agents for this event package nor allow subscriptions
1252	   for this event package to resource lists using the event list
1253	   extension [22].

1255	4.13.  Behavior of a Proxy Server

1257	   There are no additional requirements on a SIP Proxy, other than to
1258	   transparently forward the SUBSCRIBE and NOTIFY methods as required in
1259	   SIP.

1261	5.  Formal Syntax
1262	5.1.  DRegex

1264	   The following definition follows RFC2234 [2].  The definition of
1265	   DIGIT is from RFC2234, namely the characters "0" through "9".  Note
1266	   the DRegexCharacater is not a HEXDIG from RFC2234.  In particular,
1267	   DRegexCharacter neither includes "E" nor "F".  Note that
1268	   DRegexCharacter is case insensitive.

1270	   DRegex           = 1*( DRegexPosition [ RepeatCount ] )
1271	   DRegexPosition   = DRegexSymbol / DRegexSet
1272	   DRegexSymbol     = [ "L" ] DRegexCharacter
1273	   DRegexSet        = "[" 1*DRegexSetList "]"
1274	   DRegexSetList    = DRegexCharacter [ "-" DRegexCharacter ]
1275	   DRegexCharacter  = DIGIT / "A" / "B" / "C" / "D" / "R" / "*" / "#" /
1276	                            / "a" / "b" / "c" / "d" / "r"
1277	   RepeatCount      = "." / "{" RepeatRange "}"
1278	   RepeatRange      = Count / ( Count "," Count ) /
1279	                              ( Count "," ) / ( "," Count )
1280	   Count            = 1*DIGIT

1282	                              ABNF for DRegex

1284	   Note that future extensions to this document may introduce other
1285	   characters for DRegexCharacter, in the scheme of H.248.1 [16] or
1286	   possibly as named strings or XML namespaces.

1288	5.2.  KPML Request

1290	   The following syntax for KPML requests uses the XML Schema [8].

1292	   
1293	   
1298	     
1299	       
1300	         IETF Keypad Markup Language Request
1301	         
1302	       
1303	       
1304	         
1305	           
1306	             
1307	               
1308	                 
1309	                 

1311	               
1312	             
1313	           
1314	           
1315	             
1316	               
1317	                 
1318	                   
1319	                     
1320	                       Default is to not flush buffer
1321	                     
1322	                   
1323	                   
1324	                     
1325	                       
1326	                     
1327	                   
1328	                 
1329	                 
1330	                   
1331	                     
1332	                       Key press notation is a string to allow
1333	                       for future extension of non-16 digit
1334	                       keypads or named keys
1335	                     
1336	                   
1337	                   
1338	                     
1339	                       
1340	                         
1341	                           
1342	                             
1343	                           
1344	                         
1345	                       
1346	                       
1347	                     
1348	                     
1350	                   
1351	                 
1352	               
1353	               
1354	                 
1355	                   Default is "one-shot"
1356	                   
1357	                 
1358	                 
1359	                   
1360	                     
1361	                     
1362	                     
1363	                   
1364	                 
1365	               
1366	               
1369	                 
1370	                   Default is 4000 (ms)
1371	                   
1372	                 
1373	               
1374	               
1377	                 
1378	                   Default is 1000 (ms)
1379	                   
1380	                 
1381	               
1382	               
1385	                 
1386	                   Default is 500 (ms)
1387	                   
1388	                 
1389	               
1390	               
1392	               
1394	               
1396	                 
1397	                   Default is false
1398	                   
1399	                 
1400	               
1401	               
1403	                 
1404	                   No default enterkey
1405	                   
1406	                 

1408	               
1409	             
1410	           
1411	         
1412	         
1414	       
1415	     
1416	   

1418	                  Figure 12: XML Schema for KPML Requests

1420	5.3.  KPML Response

1422	   The following syntax for KPML responses uses the XML Schema [8].

1424	   
1425	   
1430	     
1431	       
1432	         IETF Keypad Markup Language Response
1433	         
1434	       
1435	       
1436	         
1438	         
1440	         
1442	         
1444	         
1446	           
1447	             
1448	               String for future use for e.g., number of digits lost.
1449	             
1450	           
1451	         
1452	         
1454	         
1455	           
1456	             Matches tag from regex in request
1457	             
1458	           
1459	         
1460	       
1461	     
1462	   

1464	                       XML Schema for KPML Responses

1466	6.  Enumeration of KPML Status Codes

1468	   KPML status codes broadly follow their SIP counterparts.  Codes that
1469	   start with a 2 indicate success.  Codes that start with a 4 indicate
1470	   failure.  Codes that start with a 5 indicate a server failure,
1471	   usually a failure to interpret the document or to support a requested
1472	   feature.

1474	   KPML clients MUST be able to handle arbitrary status codes by
1475	   examining the first digit only.

1477	   Any text can be in a KPML report document.  KPML clients MUST NOT
1478	   interpret the text field.

1480	        +------+--------------------------------------------------+
1481	        | Code | Text                                             |
1482	        +------+--------------------------------------------------+
1483	        | 200  | Success                                          |
1484	        | 402  | User Terminated Without Match                    |
1485	        | 423  | Timer Expired                                    |
1486	        | 481  | Dialog Not Found                                 |
1487	        | 487  | Subscription Expired                             |
1488	        | 501  | Bad Document                                     |
1489	        | 502  | Namespace Not Supported                          |
1490	        | 531  | Persistent Subscriptions Not Supported           |
1491	        | 532  | Multiple Regular Expressions Not Supported       |
1492	        | 533  | Multiple Subscriptions on a Dialog Not Supported |
1493	        | 534  | Too Many Regular Expressions                     |
1494	        +------+--------------------------------------------------+

1496	                        Table 4: KPML Status Codes

1498	7.  IANA Considerations

1500	   This document registers a new SIP Event Package, two new MIME types,
1501	   and two new XML namespaces.

1503	7.1.  SIP Event Package Registration

1505	   Package name:  kpml
1506	   Type:  package
1507	   Contact:  Eric Burger, 
1508	   Change Controller:  SIPPING Working Group delegated from the IESG
1509	   Published Specification:  RFCXXXX

1511	7.2.  MIME Media Type application/kpml-request+xml

1513	   MIME media type name:  application
1514	   MIME subtype name:  kpml-request+xml
1515	   Required parameters:  none
1516	   Optional parameters:  Same as charset parameter application/xml as
1517	      specified in XML Media Types [3]
1518	   Encoding considerations:  See RFC3023 [3].
1519	   Security considerations:  See Section 10 of RFC3023 [3] and Section 8
1520	      of RFCXXXX
1521	   Interoperability considerations:  See RFC2023 [3] and RFCXXXX
1522	   Published specification:  RFCXXXX
1523	   Applications which use this media type:  Session-oriented
1524	      applications that have primitive User Interfaces.
1525	   Change controller:  SIPPING Working Group delegated from the IESG
1526	   Personal and email address for further information:  Eric Burger
1527	      
1528	   Intended usage:  COMMON

1530	7.3.  MIME Media Type application/kpml-response+xml

1532	   MIME media type name:  application
1533	   MIME subtype name:  kpml-resposne+xml
1534	   Required parameters:  none
1535	   Optional parameters:  Same as charset parameter application/xml as
1536	      specified in XML Media Types [3]
1537	   Encoding considerations:  See RFC3023 [3].
1538	   Security considerations:  See Section 10 of RFC3023 [3] and Section 8
1539	      of RFCXXXX
1540	   Interoperability considerations:  See RFC2023 [3] and RFCXXXX
1541	   Published specification:  RFCXXXX
1542	   Applications which use this media type:  Session-oriented
1543	      applications that have primitive User Interfaces.
1544	   Change controller:  SIPPING Working Group delegated from the IESG
1545	   Personal and email address for further information:  Eric Burger
1546	      
1547	   Intended usage:  COMMON

1549	7.4.  URN Sub-Namespace Registration for urn:ietf:xml:ns:kpml-request

1551	   URI: urn:ietf:params:xml:ns:kpml-request

1553	   Registrant Contact: IETF, SIPPING Work Group , Eric
1554	   Burger .

1556	   XML:

1558	   
1559	   
1561	   
1562	     
1563	       
1565	       Key Press Markup Language Request
1566	     
1567	     
1568	       
Namespace for Key Press Markup Language Request

1569	       
urn:ietf:params:xml:ns:kpml-request

1570	       

1571	   RFCXXXX.
1572	       

1573	     
1574	   

1576	7.5.  URN Sub-Namespace Registration for urn:ietf:xml:ns:kpml-response

1578	   URI: urn:ietf:params:xml:ns:kpml-response

1580	   Registrant Contact: IETF, SIPPING Work Group , Eric
1581	   Burger .

1583	   XML:

1585	   
1586	   
1588	   
1589	     
1590	       
1592	       Key Press Markup Language Response
1593	     
1594	     
1595	       
Namespace for Key Press Markup Language Response

1596	       
urn:ietf:params:xml:ns:kpml-response

1597	       

1598	   RFCXXXX.
1599	       

1600	     
1601	   

1603	7.6.  KPML Request Schema Registration

1605	   Per RFC3688 [7], please register the XML Schema for KPML as
1606	   referenced in Section 5.2 of RFCXXXX.

1608	   URI: Please assign.

1610	   Registrant Contact: IETF, SIPPING Work Group , Eric
1611	   Burger .

1613	7.7.  KPML Response Schema Registration

1615	   Per RFC3688 [7], please register the XML Schema for KPML as
1616	   referenced in Section 5.3 of RFCXXXX.

1618	   URI: Please assign.

1620	   Registrant Contact: IETF, SIPPING Work Group , Eric
1621	   Burger .

1623	8.  Security Considerations

1625	   The user information transported by KPML is potentially sensitive.
1626	   For example, it could include calling card or credit card numbers.
1627	   This potentially private information could be provided accidentally
1628	   if the notifier does not properly authenticate or authorize a
1629	   subscription.  Similarly private information (such as a credit card
1630	   number or calling card number) could be revealed to an otherwise
1631	   legitimate subscriber (one operating an IVR) if digits buffered
1632	   earlier in the session are provided unintentionally to the new
1633	   subscriber.

1635	   Likewise, an eavesdropper could view KPML digit information if it is
1636	   not encrypted, or an attacker could inject fraudulent notifications
1637	   unless the messages or the SIP path over which they travel are
1638	   integrity protected.

1640	   Therefore, User Interfaces MUST NOT downgrade their own security
1641	   policy.  That is, if a User Interface policy is to restrict
1642	   notifications to authenticated and authorized subscribers over secure
1643	   communications, then the User Interface must not accept an
1644	   unauthenticated, unauthorized subscription over an insecure
1645	   communication channel.

1647	   As an XML markup, all of the security considerations of RFC3023 [3]
1648	   and RFC3406 [6] must be met.  Pay particular attention to the
1649	   robustness requirements of parsing XML.

1651	   Key press information is potentially sensitive.  For example, it can
1652	   represent credit card, calling card, or other personal information.
1653	   Hijacking sessions allow unauthorized entities access to this
1654	   sensitive information.  Therefore, signaling SHOULD be secure, e.g.,
1655	   use of TLS and sips: SHOULD be used.  Moreover, the information
1656	   itself is sensitive; therefore the use of S/MIME or other appropriate
1657	   mechanism SHOULD be used.

1659	   Subscriptions MUST be authenticated in some manner.  As required by
1660	   the core SIP [4] specification, all SIP implementations MUST support
1661	   digest authentication.  In addition, User Interfaces MUST implement
1662	   support for the sips: scheme and SIP over TLS.  Subscribers MUST
1663	   expect the User Interface to demand the use of an authentication
1664	   scheme.  If the local policy of a User Interface is to use
1665	   authentication or secure communication channels, the User Interface
1666	   MUST reject subscription requests that do not meet that policy.

1668	   User Interfaces MUST begin buffering User Input upon receipt of an
1669	   authenticated and accepted subscription.  This buffering is done on a
1670	   per subscription basis.

1672	9.  Examples

1674	   This section is informative in nature.  If there is a discrepancy
1675	   between this section and the normative sections above, the normative
1676	   sections take precedence.

1678	9.1.  Monitoring for Octothorpe

1680	   A common need for pre-paid and personal assistant applications is to
1681	   monitor a conversation for a signal indicating a change in user focus
1682	   from the party they called through the application to the application
1683	   itself.  For example, if you call a party using a pre-paid calling
1684	   card and the party you call redirects you to voice mail, digits you
1685	   press are for the voice mail system.  However, many applications have
1686	   a special key sequence, such as the octothorpe (#, or pound sign) or
1687	   *9 that terminate the called party session and shift the user's focus
1688	   to the application.

1690	   Figure 16 shows the KPML for long octothorpe.

1692	   
1693	   
1698	     
1699	       L#
1700	     
1701	   

1703	                    Figure 16: Long Octothorpe Example

1705	   The regex value L indicates the following digit needs to be a long-
1706	   duration key press.

1708	9.2.  Dial String Collection

1710	   In this example, the User Interface collects a dial string.  The
1711	   application uses KPML to quickly determine when the user enters a
1712	   target number.  In addition, KPML indicates what type of number the
1713	   user entered.

1715	   
1716	   
1721	     
1722	       0
1723	       00
1724	       7[x][x][x]
1725	       9xxxxxxx
1726	       9401xxxxxxx
1727	       9xxxxxxxxxx
1728	       91xxxxxxxxxx
1729	       011x.
1730	     
1731	   

1733	                 Figure 17: Dial String KPML Example Code

1735	   Note the use of the "tag" attribute to indicate which regex matched
1736	   the dialed string.  The interesting case here is if the user entered
1737	   "94015551212".  This string matches both the "9401xxxxxxx" and
1738	   "9xxxxxxxxxx" regular expressions.  Both expressions are the same
1739	   length.  Thus the KPML interpreter will pick the "9401xxxxxxx"
1740	   string, as it occurs first in document order.  Figure 18 shows the
1741	   response.

1743	   
1744	   

1752	                   Figure 18: Dial String KPML Response

1754	10.  Call Flow Examples

1756	10.1.  Supplemental Digits

1758	   This section gives a non-normative example of an application that
1759	   collects supplemental digits.  Supplemental digit collection is where
1760	   the network requests additional digits after the caller enters the
1761	   destination address.  A typical supplemental dial string is four
1762	   digits in length.

1764	   Ingress Gateway      Application Server       Egress Gateway
1765	          |                      |                      |
1766	          |                      |                      |
1767	          |                      |                      |
1768	          |(1) INVITE            |                      |
1769	          |-------------------------------------------->|
1770	          |                      |                      |
1771	          |                      |                      |
1772	          |(2) 200 OK            |                      |
1773	          |<--------------------------------------------|
1774	          |                      |                      |
1775	          |                      |                      |
1776	          |(3) ACK               |                      |
1777	          |-------------------------------------------->|
1778	          |                      |                      |
1779	          |                      |                      |
1780	          |(4) SUBSCRIBE (one-shot)                     |
1781	          |<---------------------|                      |
1782	          |                      |                      |
1783	          |                      |                      |
1784	          |(5) 200 OK            |                      |
1785	          |--------------------->|                      |
1786	          |                      |                      |
1787	          |                      |                      |
1788	          |(6) NOTIFY            |                      |
1789	          |--------------------->|                      |
1790	          |                      |                      |
1791	          |                      |                      |
1792	          |(7) 200 OK            |                      |
1793	          |<---------------------|                      |
1794	          |                      |                      |
1795	          |                      |                      |
1796	          |(8)                   |                      |
1797	          |......................|                      |
1798	          |                      |                      |
1799	          |                      |                      |
1800	          |(9) NOTIFY (digits)   |                      |
1801	          |--------------------->|                      |
1802	          |                      |                      |
1803	          |                      |                      |
1804	          |(10) 200 OK           |                      |
1805	          |<---------------------|                      |
1806	          |                      |                      |
1807	          |                      |                      |
1808	          |                      |                      |
1809	          |                      |                      |

1811	                 Figure 19: Supplemental Digits Call Flow

1813	   In messages (1-3), the ingress gateway establishes a dialog with an
1814	   egress gateway.  The application learns the dialog ID through out-of-
1815	   band mechanisms, such as the Dialog Package or being co-resident with
1816	   the egress gateway.  Part of the ACK message is below, to illustrate
1817	   the dialog identifiers.

1819	   ACK sip:gw@subA.example.com SIP/2.0
1820	   Via: ...
1821	   Max-Forwards: ...
1822	   Route: ...
1823	   From: ;tag=jfh21
1824	   To: ;tag=onjwe2
1825	   Call-ID: 12345592@subA.example.com
1826	   ...

1828	   In message (4), the application requests the gateway collect a string
1829	   of four key presses.

1831	   SUBSCRIBE sip:gw@subA.example.com SIP/2.0
1832	   Via: SIP/2.0/TCP client.subB.example.com;branch=q4i9ufr4ui3
1833	   From: ;tag=567890
1834	   To: 
1835	   Call-ID: 12345601@subA.example.com
1836	   CSeq: 1 SUBSCRIBE
1837	   Contact: 
1838	   Max-Forwards: 70
1839	   Event: kpml ;remote-tag="sip:phn@example.com;tag=jfh21"
1840	               ;local-tag="sip:gw@subA.example.com;tag=onjwe2"
1841	               ;call-id="12345592@subA.example.com"
1842	   Expires: 7200
1843	   Accept: application/kpml-response+xml
1844	   Content-Type: application/kpml-request+xml
1845	   Content-Length: 292

1847	   
1848	   
1853	     
1854	       xxxx
1855	     
1856	   

1858	   Message (5) is the acknowledgement of the subscription request.

1860	   SIP/2.0 200 OK
1861	   Via: SIP/2.0/TCP subB.example.com;branch=q4i9ufr4ui3;
1862	        received=192.168.125.12
1863	   From: ;tag=567890
1864	   To: ;tag=1234567
1865	   Call-ID: 12345601@subA.example.com
1866	   CSeq: 1 SUBSCRIBE
1867	   Contact: 
1868	   Expires: 3600
1869	   Event: kpml

1871	   Message (6) is the immediate notification of the subscription.

1873	   NOTIFY sip:ap@client.subB.example.com SIP/2.0
1874	   Via: SIP/2.0/UDP subA.example.com;branch=gw27id4993
1875	   To: ;tag=567890
1876	   From: ;tag=1234567
1877	   Call-ID: 12345601@subA.example.com
1878	   CSeq: 1000 NOTIFY
1879	   Contact: 
1880	   Event: kpml
1881	   Subscription-State: active;expires=3599
1882	   Max-Forwards: 70
1883	   Content-Length: 0

1885	   Message (7) is the acknowledgment of the notification message.

1887	   SIP/2.0 200 OK
1888	   Via: SIP/2.0/TCP subA.example.com;branch=gw27id4993
1889	   To: ;tag=567890
1890	   From: ;tag=1234567
1891	   Call-ID: 12345601@subA.example.com
1892	   CSeq: 1000 NOTIFY

1894	   Some time elapses (8).

1896	   The user enters the input.  The device provides the notification of
1897	   the collected digits in message (9).  Since this was a one-shot
1898	   subscription, note the Subscription-State is "terminated".

1900	   NOTIFY sip:ap@client.subB.example.com SIP/2.0
1901	   Via: SIP/2.0/UDP subA.example.com;branch=gw27id4993
1902	   To: ;tag=567890
1903	   From: ;tag=1234567
1904	   Call-ID: 12345601@subA.example.com
1905	   CSeq: 1001 NOTIFY
1906	   Contact: 
1907	   Event: kpml
1908	   Subscription-State: terminated
1909	   Max-Forwards: 70
1910	   Content-Type: application/kpml-response+xml
1911	   Content-Length: 258

1913	   
1914	   

1922	   Message (10) is the acknowledgement of the notification.

1924	   SIP/2.0 200 OK
1925	   Via: SIP/2.0/TCP subA.example.com;branch=gw27id4993
1926	   To: ;tag=567890
1927	   From: ;tag=1234567
1928	   Call-ID: 12345601@subA.example.com
1929	   CSeq: 1001 NOTIFY

1931	10.2.  Multiple Applications

1933	   This section gives a non-normative example of multiple applications.
1934	   One application collects a destination number to call.  That
1935	   application then waits for a "long pound."  During the call, the call
1936	   goes to a personal assistant application, which interacts with the
1937	   user.  In addition, the personal assistant application looks for a
1938	   "short pound."

1940	   For clarity, we do not show the INVITE dialogs.

1942	   Gateway           Card Application      Personal Assistant
1943	      |                      |                      |
1944	      |                      |                      |
1945	      |                      |                      |
1946	      |(1) SUBSCRIBE (persistent)                   |
1947	      |<---------------------|                      |
1948	      |                      |                      |
1949	      |                      |                      |
1950	      |(2) 200 OK            |                      |
1951	      |--------------------->|                      |
1952	      |                      |                      |
1953	      |                      |                      |
1954	      |(3) NOTIFY            |                      |
1955	      |--------------------->|                      |
1956	      |                      |                      |
1957	      |                      |                      |
1958	      |(4) 200 OK            |                      |
1959	      |<---------------------|                      |
1960	      |                      |                      |
1961	      |                      |                      |
1962	      |(5)                   |                      |
1963	      |......................|                      |
1964	      |                      |                      |
1965	      |                      |                      |
1966	      |(6) NOTIFY (tag=card) |                      |
1967	      |--------------------->|                      |
1968	      |                      |                      |
1969	      |                      |                      |
1970	      |(7) 200 OK            |                      |
1971	      |<---------------------|                      |
1972	      |                      |                      |
1973	      |                      |                      |
1974	      |(8)                   |                      |
1975	      |......................|                      |
1976	      |                      |                      |
1977	      |                      |                      |
1978	      |(9) NOTIFY (tag=number)                      |
1979	      |--------------------->|                      |
1980	      |                      |                      |
1981	      |                      |                      |
1982	      |(10) 200 OK           |                      |
1983	      |<---------------------|                      |
1984	      |                      |                      |
1985	      |                      |                      |
1986	      |(11) SUBSCRIBE        |                      |
1987	      |<--------------------------------------------|
1988	      |                      |                      |
1989	      |                      |                      |
1990	      |(12) 200 OK           |                      |
1991	      |-------------------------------------------->|
1992	      |                      |                      |
1993	      |                      |                      |
1994	      |(13) NOTIFY           |                      |
1995	      |-------------------------------------------->|
1996	      |                      |                      |
1997	      |                      |                      |
1998	      |(14) 200 OK           |                      |
1999	      |<--------------------------------------------|
2000	      |                      |                      |
2001	      |                      |                      |
2002	      |(15)                  |                      |
2003	      |.............................................|
2004	      |                      |                      |
2005	      |                      |                      |
2006	      |(16) NOTIFY (tag=number)                     |
2007	      |-------------------------------------------->|
2008	      |                      |                      |
2009	      |                      |                      |
2010	      |(17) 200 OK           |                      |
2011	      |<--------------------------------------------|
2012	      |                      |                      |
2013	      |                      |                      |
2014	      |(18)                  |                      |
2015	      |.............................................|
2016	      |                      |                      |
2017	      |                      |                      |
2018	      |(19) NOTIFY (tag=#)   |                      |
2019	      |-------------------------------------------->|
2020	      |                      |                      |
2021	      |                      |                      |
2022	      |(20) 200 OK           |                      |
2023	      |<--------------------------------------------|
2024	      |                      |                      |
2025	      |                      |                      |
2026	      |(21)                  |                      |
2027	      |.............................................|
2028	      |                      |                      |
2029	      |                      |                      |
2030	      |(22) NOTIFY (tag=number)                     |
2031	      |-------------------------------------------->|
2032	      |                      |                      |
2033	      |                      |                      |
2034	      |(23) 200 OK           |                      |
2035	      |<--------------------------------------------|
2036	      |                      |                      |
2037	      |                      |                      |
2038	      |(24)                  |                      |
2039	      |.............................................|
2040	      |                      |                      |
2041	      |                      |                      |
2042	      |(25) NOTIFY (L#)      |                      |
2043	      |--------------------->|                      |
2044	      |                      |                      |
2045	      |                      |                      |
2046	      |(26) 200 OK           |                      |
2047	      |<---------------------|                      |
2048	      |                      |                      |
2049	      |                      |                      |
2050	      |                      |                      |
2051	      |                      |                      |

2053	                 Figure 27: Multiple Application Call Flow

2055	   Message (1) is the subscription request for the card number.

2057	   SUBSCRIBE sip:gw@subA.example.com SIP/2.0
2058	   Via: SIP/2.0/TCP client.subB.example.com;branch=3qo3j0ouq
2059	   From: ;tag=978675
2060	   To: 
2061	   Call-ID: 12345601@subA.example.com
2062	   CSeq: 20 SUBSCRIBE
2063	   Contact: 
2064	   Max-Forwards: 70
2065	   Event: kpml ;remote-tag=""
2066	               ;local-tag="sip:gw@subA.example.com;tag=oi43jfq"
2067	               ;call-id="12345598@subA.example.com"
2068	   Expires: 7200
2069	   Accept: application/kpml-response+xml
2070	   Content-Type: application/kpml-request+xml
2071	   Content-Length: 339

2073	   
2074	   
2079	     
2080	       x{16}
2081	       x{10}
2082	     
2083	   

2085	   Messages 2-4 are not shown for brevity.  Message (6) is the
2086	   notification of the card number.

2088	   NOTIFY sip:ap@client.subB.example.com SIP/2.0
2089	   Via: SIP/2.0/UDP subA.example.com;branch=3qo3j0ouq
2090	   To: ;tag=978675
2091	   From: ;tag=9783453
2092	   Call-ID: 12345601@subA.example.com
2093	   CSeq: 3001 NOTIFY
2094	   Contact: 
2095	   Event: kpml
2096	   Subscription-State: active;expires=3442
2097	   Max-Forwards: 70
2098	   Content-Type: application/kpml-response+xml
2099	   Content-Length: 271

2101	   
2102	   

2110	   Message (7) is the acknowledgement of the notification.  Time goes by
2111	   in (8).  Message (9) is the notification of the dialed number.

2113	   NOTIFY sip:ap@client.subB.example.com SIP/2.0
2114	   Via: SIP/2.0/UDP subA.example.com;branch=3qo3j0ouq
2115	   To: ;tag=978675
2116	   From: ;tag=9783453
2117	   Call-ID: 12345601@subA.example.com
2118	   CSeq: 3001 NOTIFY
2119	   Contact: 
2120	   Event: kpml
2121	   Subscription-State: active;expires=3542
2122	   Max-Forwards: 70
2123	   Content-Type: application/kpml-response+xml
2124	   Content-Length: 278

2126	   
2127	   

2135	   Message (11) is the request for long-pound monitoring.

2137	   SUBSCRIBE sip:gw@subA.example.com SIP/2.0
2138	   Via: SIP/2.0/TCP client.subB.example.com;branch=3qo3j0ouq
2139	   From: ;tag=978675
2140	   To: 
2141	   Call-ID: 12345601@subA.example.com
2142	   CSeq: 21 SUBSCRIBE
2143	   Contact: 
2144	   Max-Forwards: 70
2145	   Event: kpml ;remote-tag=""
2146	               ;local-tag="sip:gw@subA.example.com;tag=oi43jfq"
2147	               ;call-id="12345598@subA.example.com"
2148	   Expires: 7200
2149	   Accept: application/kpml-response+xml
2150	   Content-Type: application/kpml-request+xml
2151	   Content-Length: 295

2153	   
2154	   
2159	     
2160	       L#
2161	     
2162	   

2164	   Message (13) is the request from the personal assistant application
2165	   for number and pound sign monitoring.

2167	   SUBSCRIBE sip:gw@subA.example.com SIP/2.0
2168	   Via: SIP/2.0/TCP pahost.example.com;branch=xzvsadf
2169	   From: ;tag=4rgj0f
2170	   To: 
2171	   Call-ID: 93845@pahost.example.com
2172	   CSeq: 21 SUBSCRIBE
2173	   Contact: 
2174	   Max-Forwards: 70
2175	   Event: kpml ;remote-tag=""
2176	               ;local-tag="sip:gw@subA.example.com;tag=oi43jfq"
2177	               ;call-id="12345598@subA.example.com"
2178	   Expires: 7200
2179	   Accept: application/kpml-response+xml
2180	   Content-Type: application/kpml-request+xml
2181	   Content-Length: 332

2183	   
2184	   
2189	     
2190	       x{10}
2191	       #
2192	     
2193	   

2195	   Message (18) is the notification of the number collected.

2197	   NOTIFY sip:pa@example.com SIP/2.0
2198	   Via: SIP/2.0/UDP subA.example.com;branch=xzvsadf
2199	   To: ;tag=4rgj0f
2200	   From: ;tag=9788823
2201	   Call-ID: 93845@pahost.example.com
2202	   CSeq: 3021 NOTIFY
2203	   Contact: 
2204	   Event: kpml
2205	   Subscription-State: active;expires=3540
2206	   Max-Forwards: 70
2207	   Content-Type: application/kpml-response+xml
2208	   Content-Length: 278

2210	   
2211	   

2218	   Message (21) is the notification of pound sign detected.

2220	   NOTIFY sip:pa@example.com SIP/2.0
2221	   Via: SIP/2.0/UDP subA.example.com;branch=xzvsadf
2222	   To: ;tag=4rgj0f
2223	   From: ;tag=9788823
2224	   Call-ID: 93845@pahost.example.com
2225	   CSeq: 3022 NOTIFY
2226	   Contact: 
2227	   Event: kpml
2228	   Subscription-State: active;expires=3540
2229	   Max-Forwards: 70
2230	   Content-Type: application/kpml-response+xml
2231	   Content-Length: 264

2233	   
2234	   

2242	   Message (27) is the notification of long pound to the card
2243	   application.

2245	   NOTIFY sip:ap@client.subB.example.com SIP/2.0
2246	   Via: SIP/2.0/UDP subA.example.com;branch=3qo3j0ouq
2247	   To: ;tag=978675
2248	   From: ;tag=9783453
2249	   Call-ID: 12345601@subA.example.com
2250	   CSeq: 3037 NOTIFY
2251	   Contact: 
2252	   Event: kpml
2253	   Subscription-State: active;expires=3216
2254	   Max-Forwards: 70
2255	   Content-Type: application/kpml-response+xml
2256	   Content-Length: 256

2258	   
2259	   

2267	11.  References

2269	11.1.  Normative References

2271	   [1]  Bradner, S., "Key words for use in RFCs to Indicate Requirement
2272	        Levels", BCP 14, RFC 2119, March 1997.

2274	   [2]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
2275	        Specifications: ABNF", RFC 2234, November 1997.

2277	   [3]  Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types",
2278	        RFC 3023, January 2001.

2280	   [4]  Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
2281	        Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP:
2282	        Session Initiation Protocol", RFC 3261, June 2002.

2284	   [5]  Roach, A., "Session Initiation Protocol (SIP)-Specific Event
2285	        Notification", RFC 3265, June 2002.

2287	   [6]  Daigle, L., van Gulik, D., Iannella, R., and P. Faltstrom,
2288	        "Uniform Resource Names (URN) Namespace Definition Mechanisms",
2289	        BCP 66, RFC 3406, October 2002.

2291	   [7]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2292	        January 2004.

2294	   [8]  Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML
2295	        Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502,
2296	        May 2001.

2298	11.2.  Informative References

2300	   [9]   Rosenberg, J., "Obtaining and Using Globally Routable User
2301	         Agent (UA) URIs (GRUU) in the  Session Initiation Protocol
2302	         (SIP)", draft-ietf-sip-gruu-08 (work in progress), June 2006.

2304	   [10]  Schulzrinne, H., Casner, S., Frederick, R., and V. Jacobson,
2305	         "RTP: A Transport Protocol for Real-Time Applications",
2306	         RFC 1889, January 1996.

2308	   [11]  Handley, M. and V. Jacobson, "SDP: Session Description
2309	         Protocol", RFC 2327, April 1998.

2311	   [12]  Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L.,
2312	         Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol --
2313	         HTTP/1.1", RFC 2616, June 1999.

2315	   [13]  Schulzrinne, H. and S. Petrack, "RTP Payload for DTMF Digits,
2316	         Telephony Tones and Telephony Signals", RFC 2833, May 2000.

2318	   [14]  Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model with
2319	         Session Description Protocol (SDP)", RFC 3264, June 2002.

2321	   [15]  Andreasen, F. and B. Foster, "Media Gateway Control Protocol
2322	         (MGCP) Version 1.0", RFC 3435, January 2003.

2324	   [16]  Groves, C., Pantaleo, M., Anderson, T., and T. Taylor, "Gateway
2325	         Control Protocol Version 1", RFC 3525, June 2003.

2327	   [17]  Institute of Electrical and Electronics Engineers, "Information
2328	         Technology - Portable Operating System Interface (POSIX) - Part
2329	         1: Base Definitions, Chapter 9", IEEE Standard 1003.1,
2330	         June 2001.

2332	   [18]  Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler,
2333	         "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C
2334	         REC REC-xml-20001006, October 2000.

2336	   [19]  Rosenberg, J., "A Framework for Application Interaction in the
2337	         Session Initiation Protocol  (SIP)",
2338	         draft-ietf-sipping-app-interaction-framework-05 (work in
2339	         progress), July 2005.

2341	   [20]  Burger, E., Van Dyke, J., and A. Spitzer, "Media Server Control
2342	         Markup Language (MSCML) and Protocol", draft-vandyke-mscml-09
2343	         (work in progress), June 2006.

2345	   [21]  Rosenberg, J., Schulzrinne, H., and R. Mahy, "An INVITE-
2346	         Initiated Dialog Event Package for the Session Initiation
2347	         Protocol (SIP)", RFC 4235, November 2005.

2349	   [22]  Roach, A., Rosenberg, J., and B. Campbell, "A Session
2350	         Initiation Protocol (SIP) Event Notification Extension for
2351	         Resource Lists", draft-ietf-simple-event-list-07 (work in
2352	         progress), January 2005.

2354	Appendix A.  Contributors

2356	   Ophir Frieder of the Illinois Institute of Technology collaborated on
2357	   the development of the buffer algorithm.

2359	   Jeff Van Dyke worked enough hours and wrote enough text to be
2360	   considered an author under the old rules.

2362	   Robert Fairlie-Cuninghame, Cullen Jennings, Jonathan Rosenberg, and
2363	   we were the members of the Application Stimulus Signaling Design
2364	   Team.  All members of the team contributed to this work.  In
2365	   addition, Jonathan Rosenberg postulated DML in his "A Framework for
2366	   Stimulus Signaling in SIP Using Markup" draft.

2368	   This version of KPML has significant influence from MSCML [20], the
2369	   SnowShore Media Server Control Markup Language.  Jeff Van Dyke and
2370	   Andy Spitzer were the primary contributors to that effort.

2372	   Rohan Mahy did a significant reorganization of the content, as well
2373	   as providing considerable moral support in the production of this
2374	   document.

2376	   That said, any errors, misinterpretation, or fouls in this document
2377	   are our own.

2379	Appendix B.  Acknowledgements

2381	   Hal Purdy and Eric Cheung of AT&T Laboratories helped immensely
2382	   through many conversations and challenges.

2384	   Steve Fisher of AT&T Laboratories suggested the digit suppression
2385	   syntax and provided excellent review of the document.

2387	   Terence Lobo of SnowShore Networks made it all work.

2389	   Jerry Kamitses, Swati Dhuleshia, Shaun Bharrat, Sunil Menon, and
2390	   Bryan Hill helped with clarifying the buffer behavior and DRegex
2391	   syntax.

2393	   Silvano Brewster and Bill Fenner of AT&T Laboratories, and Joe
2394	   Zebarth of Nortel helped considerably with making the text clear and
2395	   DRegex tight.

2397	   Bert Culpepper and Allison Mankin gave an early version of this
2398	   document a good scouring.

2400	   Scott Hollenbeck provided XML and MIME review.  Tim Bray pointed out
2401	   the general issue of UTF-8 versus UTF-16 with XML.

2403	Authors' Addresses

2405	   Eric Burger
2406	   Cantata Technology, Inc.
2407	   18 Keewaydin Dr.
2408	   Salem, NH  03079
2409	   USA

2411	   Email: eburger@cantata.com

2413	   Martin Dolly
2414	   AT&T Labs

2416	   Email: mdolly@att.com

2418	Full Copyright Statement

2420	   Copyright (C) The Internet Society (2006).

2422	   This document is subject to the rights, licenses and restrictions
2423	   contained in BCP 78, and except as set forth therein, the authors
2424	   retain all their rights.

2426	   This document and the information contained herein are provided on an
2427	   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
2428	   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
2429	   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
2430	   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
2431	   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
2432	   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

2434	Intellectual Property

2436	   The IETF takes no position regarding the validity or scope of any
2437	   Intellectual Property Rights or other rights that might be claimed to
2438	   pertain to the implementation or use of the technology described in
2439	   this document or the extent to which any license under such rights
2440	   might or might not be available; nor does it represent that it has
2441	   made any independent effort to identify any such rights.  Information
2442	   on the procedures with respect to rights in RFC documents can be
2443	   found in BCP 78 and BCP 79.

2445	   Copies of IPR disclosures made to the IETF Secretariat and any
2446	   assurances of licenses to be made available, or the result of an
2447	   attempt made to obtain a general license or permission for the use of
2448	   such proprietary rights by implementers or users of this
2449	   specification can be obtained from the IETF on-line IPR repository at
2450	   http://www.ietf.org/ipr.

2452	   The IETF invites any interested party to bring to its attention any
2453	   copyrights, patents or patent applications, or other proprietary
2454	   rights that may cover technology that may be required to implement
2455	   this standard.  Please address the information to the IETF at
2456	   ietf-ipr@ietf.org.

2458	Acknowledgment

2460	   Funding for the RFC Editor function is provided by the IETF
2461	   Administrative Support Activity (IASA).