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

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

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

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

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

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

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

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

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

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

607	3.5  User Input Buffer Behavior

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

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

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

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

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

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

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

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

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

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

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

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

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

708	3.6  DRegex

710	3.6.1  Overview

712	   This subsection is informative in nature.

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

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

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

754	                         +--------+-----------+
755	                         | DRegex | POSIX ERE |
756	                         +--------+-----------+
757	                         | *      | \*        |
758	                         | .      | *         |
759	                         | x      | [0-9]     |
760	                         | [xc]   | [0-9c]    |
761	                         +--------+-----------+

763	                  Table 1: DRegex to POSIX ERE Mapping

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

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

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

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

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

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

794	3.6.2  Operation

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

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

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

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	3.7  Monitoring Direction

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

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

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

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

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

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

881	3.8  Multiple Simultaneous Subscriptions

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

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

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

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

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

910	4.  Event Package Formal Definition

912	4.1  Event Package Name

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

917	   	"kpml"

919	4.2  Event Package Parameters

921	   This package does not define any event package parameters.

923	4.3  SUBSCRIBE Bodies

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

930	4.4  Subscription Duration

932	   The subscription lifetime should be longer than the expected call
933	   time.  Subscriptions to this event package MAY range from minutes to
934	   weeks.  Subscriptions in hours or days are more typical and are
935	   RECOMMENDED.  The default subscription duration for this event
936	   package is 7200 seconds.
937	      Subscribers MUST be able to handle the User Interface returning an
938	      Expires value smaller than the requested value.  Per RFC3265 [5],
939	      the subscription duration is the value returned by the Notifier in
940	      the 200 OK Expires header.

942	4.5  NOTIFY Bodies

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

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

956	4.6  Subscriber generation of SUBSCRIBE requests

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

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

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

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

974	   Subscribers MUST be prepared for the notifier to insist on
975	   authentication of the subscription request.  Subscribers MUST be
976	   prepared for the notifier to insist on using a secure communication
977	   channel.

979	4.7  Notifier processing of SUBSCRIBE requests

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

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

989	   Upon authenticating the requesting party, the User Interface
990	   determines if the requesting party has authorization to monitor the
991	   user's key presses.  Determining authorization policies and
992	   procedures is beyond the scope of this specification.

994	   The User Interface MUST return a Contact URI that has GRUU [8]
995	   properties in the Contact header of a SIP INVITE, 1xx, or 2xx
996	   response.

998	   After authorizing the request, the User Interface checks to see if
999	   the request is to terminate a subscription.  If the request will
1000	   terminate the subscription, the User Interface does the appropriate
1001	   processing, including the procedures described in Section 5.2.

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

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

1015	   If the request has a KPML body, the User Interface parses the KPML
1016	   document.  The User Interface SHOULD validate the XML document
1017	   against the schema presented in Section 5.2.  If the document is not
1018	   valid, the User Interface rejects the SUBSCRIBE request with an
1019	   appropriate error response and terminates the subscription.  If there
1020	   is a loaded KPML document on the subscription, the User Interface
1021	   unloads the document.

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

1026	   Following the semantics of SUBSCRIBE, if the User Interface receives
1027	   a resubscription, the User Interface MUST terminate the existing KPML
1028	   request and replace it with the new request.

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

1035	   If a SUBSCRIBE request has an expires of zero (explicit SUBSCRIBE
1036	   termination), includes a KPML document, and there is buffered User
1037	   Input, then the User Interface attempts to process the buffered
1038	   digits against the document.  If there is a match, the User Interface
1039	   MUST generate the appropriate KPML report with the KPML status code
1040	   of 200.  The SIP NOTIFY body terminates the subscription by setting
1041	   the subscription state to "terminated" and a reason of "timeout".

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

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

1057	   Terminating the subscription when a dialog terminates ensures
1058	   reauthorization (if necessary) for attaching to subsequent
1059	   subscriptions.

1061	   If a SUBSCRIBE request references a dialog that is not present at the
1062	   User Interface, the User Interface MUST generate a KPML report with
1063	   the KPML status code 481, Dialog Not Found.  The User Interface
1064	   terminates the subscription by setting the subscription state to
1065	   "terminated".

1067	   If the KPML document is not valid, the User Interface generates a
1068	   KPML report with the KPML status code 501, Bad Document.  The User
1069	   Interface terminates the subscription by setting the subscription
1070	   state to "terminated".

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

1076	4.8  Notifier generation of NOTIFY requests

1078	   Immediately after a subscription is accepted, the Notifier MUST send
1079	   a NOTIFY with the current location information as appropriate based
1080	   on the identity of the subscriber.  This allows the Subscriber to
1081	   resynchronize its state.

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

1088	   The KPML payload distinguishes between an initial NOTIFY and a NOTIFY
1089	   informing of key presses.  If there is no User Input buffered at the
1090	   time of the SUBSCRIBE (see  below) or the buffered User Input does
1091	   not match the new KPML document, then the immediate NOTIFY MUST NOT
1092	   contain a KPML body.  If User Interface has User Input buffered that
1093	   result in a match using the new KPML document, then the NOTIFY MUST
1094	   return the appropriate KPML document.

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

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

1103	   NOTIFY sip:application@example.com SIP/2.0
1104	   Via: SIP/2.0/UDP proxy.example.com
1105	   Max-Forwards: 70
1106	   To: 
1107	   From: 
1108	   Call-Id: 439hu409h4h09903fj0ioij
1109	   Subscription-State: active; expires=7200
1110	   CSeq: 49851 NOTIFY
1111	   Event: kpml

1113	                  Figure 10: Immediate NOTIFY Example

1115	   All subscriptions MUST be authenticated, particularly those that
1116	   match on buffered input.

1118	   KPML specifies the key press notification report format.  The MIME
1119	   type for KPML reports is application/kpml-response+xml.  The default
1120	   MIME type for the kpml event package is
1121	   application/kpml-response+xml.

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

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

1130	   After reporting, the interpreter terminates the KPML session unless
1131	   the subscription has a persistence indicator.  If the subscription
1132	   does not have a persistence indicator, the User Interface MUST set
1133	   the state of the subscription to "terminated" in the NOTIFY report.

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

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

1141	   KPML reports have two mandatory attributes, code and text.  These
1142	   attributes describe the state of the KPML interpreter on the User
1143	   Interface.  Note the KPML status code is not necessarily related to
1144	   the SIP result code.  An important example of this is where a legal
1145	   SIP subscription request gets a normal SIP 200 OK followed by a
1146	   NOTIFY, but there is something wrong with the KPML request.  In this
1147	   case, the NOTIFY would include the KPML status code in the KPML
1148	   report.  Note that from a SIP perspective, the SUBSCRIBE and NOTIFY
1149	   were successful.  Also, if the KPML failure is not recoverable, the
1150	   User Interface will most likely set the Subscription-Sate to
1151	   "terminated".  This lets the SIP machinery know the subscription is
1152	   no longer active.

1154	   If a pattern matches, the User Interface will emit a KPML report.
1155	   Since this is a success report, the code is "200" and the text is
1156	   "OK".

1158	   The KPML report includes the actual digits matched in the digit
1159	   attribute.  The digit string uses the conventional characters '*' and
1160	   '#' for star and octothorpe respectively.  The KPML report also
1161	   includes the tag attribute if the regex that matched the digits had a
1162	   tag attribute.

1164	   If the subscription requested digit suppression and the User
1165	   Interface suppressed digits, the suppressed attribute indicates
1166	   "true".  The default value of suppressed is "false".

1168	      NOTE: KPML does not include a timestamp.  There are a number of
1169	      reasons for this.  First, what timestamp would in include?  Would
1170	      it be the time of the first detected key press?  The time the
1171	      interpreter collected the entire string?  A range?  Second, if the
1172	      RTP timestamp is a datum of interest, why not simply get RTP in
1173	      the first place?  That all said, if it is really compelling to
1174	      have the timestamp in the response, it could be an attribute to
1175	      the  tag.

1177	   Note that if the monitored (INVITE-initiated) dialog terminates, the
1178	   Notifier still MUST explicitly terminate the KPML subscriptions
1179	   monitoring that dialog.

1181	4.9  Subscriber processing of NOTIFY requests

1183	   If there is no KPML body, it means the SUBSCRIBE was successful.
1184	   This establishes the dialog if there is no buffered User Input to
1185	   report.

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

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

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

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

1201	4.10  Handling of Forked Requests

1203	   Forked requests are NOT ALLOWED for this event type.  Subscriptions
1204	   to this event package MUST only be sent to SIP URIs which have GRUU
1205	   properties.

1207	4.11  Rate of notifications

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

1217	   The sustained rate of notification shall be no more than 100 Notifies
1218	   per minute.

1220	   The User Interface MUST reliably deliver notifications.  Because
1221	   there is no meaningful metric for throttling requests, the User
1222	   Interface SHOULD send NOTIFY messages over a congestion-controlled
1223	   transport, such as TCP.
1224	      Note that all SIP implementations are already required to
1225	      implement SIP over TCP.

1227	4.12  State Agents and Lists

1229	   KPML requests are sent to a specific SIP URI that has GRUU properties
1230	   and attempt to monitor a specific stream that corresponds with a
1231	   specific target dialog.  Consequently, implementers MUST NOT define
1232	   state agents for this event package nor allow subscriptions for this
1233	   event package to resource lists using the event list extension [22].

1235	4.13  Behavior of a Proxy Server

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

1241	5.  Formal Syntax

1243	5.1  DRegex

1245	   The following definition follows RFC2234 [2].  The definition of
1246	   DIGIT is from RFC2234, namely the characters "0" through "9".  Note
1247	   the DRegexCharacater is not a HEXDIG from RFC2234.  In particular,
1248	   DRegexCharacter neither includes "E" nor "F".  Note that
1249	   DRegexCharacter is case insensitive.

1251	   DRegex           = 1*( DRegexPosition [ RepeatCount ] )
1252	   DRegexPosition   = DRegexSymbol / DRegexSet
1253	   DRegexSymbol     = [ "L" ] DRegexCharacter
1254	   DRegexSet        = "[" 1*DRegexSetList "]"
1255	   DRegexSetList    = DRegexCharacter [ "-" DRegexCharacter ]
1256	   DRegexCharacter  = DIGIT / "A" / "B" / "C" / "D" / "*" / "#" /
1257	   				         / "a" / "b" / "c" / "d"
1258	   RepeatCount      = "." / "{" RepeatRange "}"
1259	   RepeatRange      = Count / ( Count "," Count ) /
1260	                              ( Count "," ) / ( "," Count )
1261	   Count            = 1*DIGIT

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

1267	5.2  KPML Request

1269	   The following syntax for KPML requests uses the XML Schema [9].

1271	   
1272	   
1277	     
1278	       
1279	         IETF Keypad Markup Language Request
1280	         
1281	       
1282	       
1283	         
1284	           
1285	             
1286	               
1287	                 
1288	                 
1289	               
1290	             
1291	           
1292	           
1293	             
1294	               
1295	                 
1296	                   
1297	                     
1298	                       Default is to not flush buffer
1299	                     
1300	                   
1301	                   
1302	                     
1303	                       
1304	                     
1305	                   
1306	                 
1307	                 
1308	                   
1309	                     
1310	                       Key press notation is a string to allow
1311	                       for future extension of non-16 digit
1312	                       keypads or named keys
1313	                     
1314	                   
1315	                   
1316	                     
1317	                       
1318	                         
1319	                           
1320	                             
1321	                           
1322	                         

1324	                       
1325	                       
1326	                     
1327	                     
1329	                   
1330	                 
1331	               
1332	               
1333	                 
1334	                   Default is "one-shot"
1335	                   
1336	                 
1337	                 
1338	                   
1339	                     
1340	                     
1341	                     
1342	                   
1343	                 
1344	               
1345	               
1348	                 
1349	                   Default is 4000 (ms)
1350	                   
1351	                 
1352	               
1353	               
1356	                 
1357	                   Default is 1000 (ms)
1358	                   
1359	                 
1360	               
1361	               
1364	                 
1365	                   Default is 500 (ms)
1366	                   
1367	                 
1368	               
1369	               
1371	               
1373	               
1375	                 
1376	                   Default is false
1377	                   
1378	                 
1379	               
1380	               
1382	                 
1383	                   No default enterkey
1384	                   
1385	                 
1386	               
1387	             
1388	           
1389	         
1390	         
1392	       
1393	     
1394	   

1396	                Figure 12: XML Schema for KPML Requests

1398	5.3  KPML Response

1400	   The following syntax for KPML responses uses the XML Schema [9].

1402	   
1403	   
1408	     
1409	       
1410	         IETF Keypad Markup Language Response
1411	         
1412	       
1413	       
1414	         
1416	         
1418	         
1420	         
1422	         
1424	           
1425	             
1426	               String for future use for e.g., number of digits lost.
1427	             
1428	           
1429	         
1430	         
1432	         
1433	           
1434	             Matches tag from regex in request
1435	             
1436	           
1437	         
1438	       
1439	     
1440	   

1442	6.  Enumeration of KPML Status Codes

1444	   KPML status codes broadly follow their SIP counterparts.  Codes that
1445	   start with a 2 indicate success.  Codes that start with a 4 indicate
1446	   failure.  Codes that start with a 5 indicate a server failure,
1447	   usually a failure to interpret the document or to support a requested
1448	   feature.

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

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

1456	      +------+--------------------------------------------------+
1457	      | Code | Text                                             |
1458	      +------+--------------------------------------------------+
1459	      | 200  | Success                                          |
1460	      | 402  | User Terminated Without Match                    |
1461	      | 423  | Timer Expired                                    |
1462	      | 481  | Dialog Not Found                                 |
1463	      | 487  | Subscription Expired                             |
1464	      | 501  | Bad Document                                     |
1465	      | 502  | Namespace Not Supported                          |
1466	      | 531  | Persistent Subscriptions Not Supported           |
1467	      | 532  | Multiple Regular Expressions Not Supported       |
1468	      | 533  | Multiple Subscriptions on a Dialog Not Supported |
1469	      | 534  | Too Many Regular Expressions                     |
1470	      +------+--------------------------------------------------+

1472	                       Table 4: KPML Status Codes

1474	7.  IANA Considerations

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

1479	7.1  SIP Event Package Registration

1481	   Package name: kpml
1482	   Type: package
1483	   Contact: Eric Burger, 
1484	   Change Controller: SIPPING Working Group delegated from the IESG
1485	   Published Specification: RFCXXXX

1487	7.2  MIME Media Type application/kpml-request+xml

1489	   MIME media type name: application
1490	   MIME subtype name: kpml-request+xml
1491	   Required parameters: none
1492	   Optional parameters: Same as charset parameter application/xml as
1493	      specified in XML Media Types [3]
1494	   Encoding considerations: See RFC3023 [3].
1495	   Security considerations: See Section 10 of RFC3023 [3] and Section 8
1496	      of RFCXXXX
1497	   Interoperability considerations: See RFC2023 [3] and RFCXXXX
1498	   Published specification: RFCXXXX
1499	   Applications which use this media type: Session-oriented applications
1500	      that have primitive User Interfaces.

1502	   Change controller: SIPPING Working Group delegated from the IESG
1503	   Personal and email address for further information: Eric Burger
1504	      
1505	   Intended usage: COMMON

1507	7.3  MIME Media Type application/kpml-response+xml

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

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

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

1530	   Registrant Contact: IETF, SIPPING Work Group , Eric
1531	   Burger .

1533	   XML:

1535	   
1536	   
1538	   
1539	     
1540	       
1542	       Key Press Markup Language Request
1543	     
1544	     
1545	       
Namespace for Key Press Markup Language Request

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

1547	       

1548	   RFCXXXX.
1549	       


1551	     
1552	   

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

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

1558	   Registrant Contact: IETF, SIPPING Work Group , Eric
1559	   Burger .

1561	   XML:

1563	   
1564	   
1566	   
1567	     
1568	       
1570	       Key Press Markup Language Response
1571	     
1572	     
1573	       
Namespace for Key Press Markup Language Response

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

1575	       

1576	   RFCXXXX.
1577	       

1578	     
1579	   

1581	7.6  KPML Request Schema Registration

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

1586	   URI: Please assign.

1588	   Registrant Contact: IETF, SIPPING Work Group , Eric
1589	   Burger .

1591	7.7  KPML Response Schema Registration

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

1596	   URI: Please assign.

1598	   Registrant Contact: IETF, SIPPING Work Group , Eric
1599	   Burger .

1601	8.  Security Considerations

1603	   The user information transported by KPML is potentially sensitive.
1604	   For example, it could include calling card or credit card numbers.
1605	   This potentially private information could be provided accidentally
1606	   if the notifier does not properly authenticate or authorize a
1607	   subscription.  Similarly private information (such as a credit card
1608	   number or calling card number) could be revealed to an otherwise
1609	   legitimate subscriber (one operating an IVR) if digits buffered
1610	   earlier in the session are provided unintentionally to the new
1611	   subscriber.

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

1618	   Therefore, User Interfaces MUST NOT downgrade their own security
1619	   policy.  That is, if a User Interface policy is to restrict
1620	   notifications to authenticated and authorized subscribers over secure
1621	   communications, then the User Interface must not accept an
1622	   unauthenticated, unauthorized subscription over an insecure
1623	   communication channel.

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

1629	   Key press information is potentially sensitive.  For example, it can
1630	   represent credit card, calling card, or other personal information.
1631	   Hijacking sessions allow unauthorized entities access to this
1632	   sensitive information.  Therefore, signaling SHOULD be secure, e.g.,
1633	   use of TLS and sips: SHOULD be used.  Moreover, the information
1634	   itself is sensitive; therefore the use of S/MIME or other appropriate
1635	   mechanism SHOULD be used.

1637	   Subscriptions MUST be authenticated in some manner.  As required by
1638	   the core SIP [4] specification, all SIP implementations MUST support
1639	   digest authentication.  In addition, User Interfaces MUST implement
1640	   support for the sips: scheme and SIP over TLS.  Subscribers MUST
1641	   expect the User Interface to demand the use of an authentication
1642	   scheme.  If the local policy of a User Interface is to use
1643	   authentication or secure communication channels, the User Interface
1644	   MUST reject subscription requests that do not meet that policy.

1646	   User Interfaces MUST begin buffering User Input upon receipt of an
1647	   authenticated and accepted subscription.  This buffering is done on a
1648	   per subscription basis.

1650	9.  Examples

1652	   This section is informative in nature.  If there is a discrepancy
1653	   between this section and the normative sections above, the normative
1654	   sections take precedence.

1656	9.1  Monitoring for Octothorpe

1658	   A common need for pre-paid and personal assistant applications is to
1659	   monitor a conversation for a signal indicating a change in user focus
1660	   from the party they called through the application to the application
1661	   itself.  For example, if you call a party using a pre-paid calling
1662	   card and the party you call redirects you to voice mail, digits you
1663	   press are for the voice mail system.  However, many applications have
1664	   a special key sequence, such as the octothorpe (#, or pound sign) or
1665	   *9 that terminate the called party session and shift the user's focus
1666	   to the application.

1668	   Figure 16 shows the KPML for long octothorpe.

1670	   
1671	   
1676	     
1677	       L#
1678	     
1679	   

1681	                   Figure 16: Long Octothorpe Example

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

1686	9.2  Dial String Collection

1688	   In this example, the User Interface collects a dial string.  The
1689	   application uses KPML to quickly determine when the user enters a
1690	   target number.  In addition, KPML indicates what type of number the
1691	   user entered.

1693	   
1694	   
1699	     
1700	       0
1701	       00
1702	       7[x][x][x]
1703	       9xxxxxxx
1704	       9401xxxxxxx
1705	       9xxxxxxxxxx
1706	       91xxxxxxxxxx
1707	       011x.
1708	     
1709	   

1711	                Figure 17: Dial String KPML Example Code

1713	   Note the use of the "tag" attribute to indicate which regex matched
1714	   the dialed string.  The interesting case here is if the user entered
1715	   "94015551212".  This string matches both the "9401xxxxxxx" and
1716	   "9xxxxxxxxxx" regular expressions.  Both expressions are the same
1717	   length.  Thus the KPML interpreter will pick the "9401xxxxxxx"
1718	   string, as it occurs first in document order.  Figure 18 shows the
1719	   response.

1721	   
1722	   

1730	                  Figure 18: Dial String KPML Response

1732	10.  Call Flow Examples

1734	10.1  Supplemental Digits

1736	   This section gives a non-normative example of an application that
1737	   collects supplemental digits.  Supplemental digit collection is where
1738	   the network requests additional digits after the caller enters the
1739	   destination address.  A typical supplemental dial string is four
1740	   digits in length.

1742	   Ingress Gateway      Application Server       Egress Gateway
1743	          |                      |                      |
1744	          |                      |                      |
1745	          |                      |                      |
1746	          |(1) INVITE            |                      |
1747	          |-------------------------------------------->|
1748	          |                      |                      |
1749	          |                      |                      |
1750	          |(2) 200 OK            |                      |
1751	          |<--------------------------------------------|
1752	          |                      |                      |
1753	          |                      |                      |
1754	          |(3) ACK               |                      |
1755	          |-------------------------------------------->|
1756	          |                      |                      |
1757	          |                      |                      |
1758	          |(4) SUBSCRIBE (one-shot)                     |
1759	          |<---------------------|                      |
1760	          |                      |                      |
1761	          |                      |                      |
1762	          |(5) 200 OK            |                      |
1763	          |--------------------->|                      |
1764	          |                      |                      |
1765	          |                      |                      |
1766	          |(6) NOTIFY            |                      |
1767	          |--------------------->|                      |
1768	          |                      |                      |
1769	          |                      |                      |
1770	          |(7) 200 OK            |                      |
1771	          |<---------------------|                      |
1772	          |                      |                      |
1773	          |                      |                      |
1774	          |(8)                   |                      |
1775	          |......................|                      |
1776	          |                      |                      |
1777	          |                      |                      |
1778	          |(9) NOTIFY (digits)   |                      |
1779	          |--------------------->|                      |
1780	          |                      |                      |
1781	          |                      |                      |
1782	          |(10) 200 OK           |                      |
1783	          |<---------------------|                      |
1784	          |                      |                      |
1785	          |                      |                      |
1786	          |                      |                      |
1787	          |                      |                      |
1788	                Figure 19: Supplemental Digits Call Flow

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

1796	   ACK sip:gw@subA.example.com SIP/2.0
1797	   Via: ...
1798	   Max-Forwards: ...
1799	   Route: ...
1800	   From: ;tag=jfh21
1801	   To: ;tag=onjwe2
1802	   Call-ID: 12345592@subA.example.com
1803	   ...

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

1808	   SUBSCRIBE sip:gw@subA.example.com SIP/2.0
1809	   Via: SIP/2.0/TCP client.subB.example.com;branch=q4i9ufr4ui3
1810	   From: ;tag=567890
1811	   To: 
1812	   Call-ID: 12345601@subA.example.com
1813	   CSeq: 1 SUBSCRIBE
1814	   Contact: 
1815	   Max-Forwards: 70
1816	   Event: kpml ;remote-tag=""
1817	               ;local-tag="sip:gw@subA.example.com;tag=onjwe2"
1818	               ;call-id="12345592@subA.example.com"
1819	   Expires: 7200
1820	   Accept: application/kpml-response+xml
1821	   Content-Type: application/kpml-request+xml
1822	   Content-Length: 292

1824	   
1825	   
1830	     
1831	       xxxx
1832	     
1833	   

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

1837	   SIP/2.0 200 OK
1838	   Via: SIP/2.0/TCP subB.example.com;branch=q4i9ufr4ui3;
1839	        received=192.168.125.12
1840	   From: ;tag=567890
1841	   To: ;tag=1234567
1842	   Call-ID: 12345601@subA.example.com
1843	   CSeq: 1 SUBSCRIBE
1844	   Contact: 
1845	   Expires: 3600
1846	   Event: kpml

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

1850	   NOTIFY sip:ap@client.subB.example.com SIP/2.0
1851	   Via: SIP/2.0/UDP subA.example.com;branch=gw27id4993
1852	   To: ;tag=567890
1853	   From: ;tag=1234567
1854	   Call-ID: 12345601@subA.example.com
1855	   CSeq: 1000 NOTIFY
1856	   Contact: 
1857	   Event: kpml
1858	   Subscription-State: active;expires=3599
1859	   Max-Forwards: 70
1860	   Content-Length: 0

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

1864	   SIP/2.0 200 OK
1865	   Via: SIP/2.0/TCP subA.example.com;branch=gw27id4993
1866	   To: ;tag=567890
1867	   From: ;tag=1234567
1868	   Call-ID: 12345601@subA.example.com
1869	   CSeq: 1000 NOTIFY

1871	   Some time elapses (8).

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

1877	   NOTIFY sip:ap@client.subB.example.com SIP/2.0
1878	   Via: SIP/2.0/UDP subA.example.com;branch=gw27id4993
1879	   To: ;tag=567890
1880	   From: ;tag=1234567
1881	   Call-ID: 12345601@subA.example.com
1882	   CSeq: 1001 NOTIFY
1883	   Contact: 
1884	   Event: kpml
1885	   Subscription-State: terminated
1886	   Max-Forwards: 70
1887	   Content-Type: application/kpml-response+xml
1888	   Content-Length: 258

1890	   
1891	   

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

1901	   SIP/2.0 200 OK
1902	   Via: SIP/2.0/TCP subA.example.com;branch=gw27id4993
1903	   To: ;tag=567890
1904	   From: ;tag=1234567
1905	   Call-ID: 12345601@subA.example.com
1906	   CSeq: 1001 NOTIFY

1908	10.2  Multiple Applications

1910	   This section gives a non-normative example of multiple applications.
1911	   One application collects a destination number to call.  That
1912	   application then waits for a "long pound."  During the call, the call
1913	   goes to a personal assistant application, which interacts with the
1914	   user.  In addition, the personal assistant application looks for a
1915	   "short pound."

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

1919	   Gateway           Card Application      Personal Assistant
1920	      |                      |                      |
1921	      |                      |                      |
1922	      |                      |                      |
1923	      |(1) SUBSCRIBE (persistent)                   |
1924	      |<---------------------|                      |
1925	      |                      |                      |
1926	      |                      |                      |
1927	      |(2) 200 OK            |                      |
1928	      |--------------------->|                      |
1929	      |                      |                      |
1930	      |                      |                      |
1931	      |(3) NOTIFY            |                      |
1932	      |--------------------->|                      |
1933	      |                      |                      |
1934	      |                      |                      |
1935	      |(4) 200 OK            |                      |
1936	      |<---------------------|                      |
1937	      |                      |                      |
1938	      |                      |                      |
1939	      |(5)                   |                      |
1940	      |......................|                      |
1941	      |                      |                      |
1942	      |                      |                      |
1943	      |(6) NOTIFY (tag=card) |                      |
1944	      |--------------------->|                      |
1945	      |                      |                      |
1946	      |                      |                      |
1947	      |(7) 200 OK            |                      |
1948	      |<---------------------|                      |
1949	      |                      |                      |
1950	      |                      |                      |
1951	      |(8)                   |                      |
1952	      |......................|                      |
1953	      |                      |                      |
1954	      |                      |                      |
1955	      |(9) NOTIFY (tag=number)                      |
1956	      |--------------------->|                      |
1957	      |                      |                      |
1958	      |                      |                      |
1959	      |(10) 200 OK           |                      |
1960	      |<---------------------|                      |
1961	      |                      |                      |
1962	      |                      |                      |
1963	      |(11) SUBSCRIBE        |                      |
1964	      |<--------------------------------------------|
1965	      |                      |                      |
1966	      |                      |                      |
1967	      |(12) 200 OK           |                      |
1968	      |-------------------------------------------->|
1969	      |                      |                      |
1970	      |                      |                      |
1971	      |(13) NOTIFY           |                      |
1972	      |-------------------------------------------->|
1973	      |                      |                      |
1974	      |                      |                      |
1975	      |(14) 200 OK           |                      |
1976	      |<--------------------------------------------|
1977	      |                      |                      |
1978	      |                      |                      |
1979	      |(15)                  |                      |
1980	      |.............................................|
1981	      |                      |                      |
1982	      |                      |                      |
1983	      |(16) NOTIFY (tag=number)                     |
1984	      |-------------------------------------------->|
1985	      |                      |                      |
1986	      |                      |                      |
1987	      |(17) 200 OK           |                      |
1988	      |<--------------------------------------------|
1989	      |                      |                      |
1990	      |                      |                      |
1991	      |(18)                  |                      |
1992	      |.............................................|
1993	      |                      |                      |
1994	      |                      |                      |
1995	      |(19) NOTIFY (tag=#)   |                      |
1996	      |-------------------------------------------->|
1997	      |                      |                      |
1998	      |                      |                      |
1999	      |(20) 200 OK           |                      |
2000	      |<--------------------------------------------|
2001	      |                      |                      |
2002	      |                      |                      |
2003	      |(21)                  |                      |
2004	      |.............................................|
2005	      |                      |                      |
2006	      |                      |                      |
2007	      |(22) NOTIFY (tag=number)                     |
2008	      |-------------------------------------------->|
2009	      |                      |                      |
2010	      |                      |                      |
2011	      |(23) 200 OK           |                      |
2012	      |<--------------------------------------------|
2013	      |                      |                      |
2014	      |                      |                      |
2015	      |(24)                  |                      |
2016	      |.............................................|
2017	      |                      |                      |
2018	      |                      |                      |
2019	      |(25) NOTIFY (L#)      |                      |
2020	      |--------------------->|                      |
2021	      |                      |                      |
2022	      |                      |                      |
2023	      |(26) 200 OK           |                      |
2024	      |<---------------------|                      |
2025	      |                      |                      |
2026	      |                      |                      |
2027	      |                      |                      |
2028	      |                      |                      |

2030	               Figure 27: Multiple Application Call Flow

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

2034	   SUBSCRIBE sip:gw@subA.example.com SIP/2.0
2035	   Via: SIP/2.0/TCP client.subB.example.com;branch=3qo3j0ouq
2036	   From: ;tag=978675
2037	   To: 
2038	   Call-ID: 12345601@subA.example.com
2039	   CSeq: 20 SUBSCRIBE
2040	   Contact: 
2041	   Max-Forwards: 70
2042	   Event: kpml ;remote-tag=""
2043	               ;local-tag="sip:gw@subA.example.com;tag=oi43jfq"
2044	               ;call-id="12345598@subA.example.com"
2045	   Expires: 7200
2046	   Accept: application/kpml-response+xml
2047	   Content-Type: application/kpml-request+xml
2048	   Content-Length: 339

2050	   
2051	   
2056	     
2057	       x{16}
2058	       x{10}
2059	     
2060	   

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

2065	   NOTIFY sip:ap@client.subB.example.com SIP/2.0
2066	   Via: SIP/2.0/UDP subA.example.com;branch=3qo3j0ouq
2067	   To: ;tag=978675
2068	   From: ;tag=9783453
2069	   Call-ID: 12345601@subA.example.com
2070	   CSeq: 3001 NOTIFY
2071	   Contact: 
2072	   Event: kpml
2073	   Subscription-State: active;expires=3442
2074	   Max-Forwards: 70
2075	   Content-Type: application/kpml-response+xml
2076	   Content-Length: 271

2078	   
2079	   

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

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

2103	   
2104	   

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

2114	   SUBSCRIBE sip:gw@subA.example.com SIP/2.0
2115	   Via: SIP/2.0/TCP client.subB.example.com;branch=3qo3j0ouq
2116	   From: ;tag=978675
2117	   To: 
2118	   Call-ID: 12345601@subA.example.com
2119	   CSeq: 21 SUBSCRIBE
2120	   Contact: 
2121	   Max-Forwards: 70
2122	   Event: kpml ;remote-tag=""
2123	               ;local-tag="sip:gw@subA.example.com;tag=oi43jfq"
2124	               ;call-id="12345598@subA.example.com"
2125	   Expires: 7200
2126	   Accept: application/kpml-response+xml
2127	   Content-Type: application/kpml-request+xml
2128	   Content-Length: 295

2130	   
2131	   
2136	     
2137	       L#
2138	     
2139	   

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

2144	   SUBSCRIBE sip:gw@subA.example.com SIP/2.0
2145	   Via: SIP/2.0/TCP pahost.example.com;branch=xzvsadf
2146	   From: ;tag=4rgj0f
2147	   To: 
2148	   Call-ID: 93845@pahost.example.com
2149	   CSeq: 21 SUBSCRIBE
2150	   Contact: 
2151	   Max-Forwards: 70
2152	   Event: kpml ;remote-tag=""
2153	               ;local-tag="sip:gw@subA.example.com;tag=oi43jfq"
2154	               ;call-id="12345598@subA.example.com"
2155	   Expires: 7200
2156	   Accept: application/kpml-response+xml
2157	   Content-Type: application/kpml-request+xml
2158	   Content-Length: 332

2160	   
2161	   
2166	     
2167	       x{10}
2168	       #
2169	     
2170	   

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

2174	   NOTIFY sip:pa@example.com SIP/2.0
2175	   Via: SIP/2.0/UDP subA.example.com;branch=xzvsadf
2176	   To: ;tag=4rgj0f
2177	   From: ;tag=9788823
2178	   Call-ID: 93845@pahost.example.com
2179	   CSeq: 3021 NOTIFY
2180	   Contact: 
2181	   Event: kpml
2182	   Subscription-State: active;expires=3540
2183	   Max-Forwards: 70
2184	   Content-Type: application/kpml-response+xml
2185	   Content-Length: 278

2187	   
2188	   

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

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

2211	   
2212	   

2220	   Message (27) is the notification of long pound to the card
2221	   application.

2223	   NOTIFY sip:ap@client.subB.example.com SIP/2.0
2224	   Via: SIP/2.0/UDP subA.example.com;branch=3qo3j0ouq
2225	   To: ;tag=978675
2226	   From: ;tag=9783453
2227	   Call-ID: 12345601@subA.example.com
2228	   CSeq: 3037 NOTIFY
2229	   Contact: 
2230	   Event: kpml
2231	   Subscription-State: active;expires=3216
2232	   Max-Forwards: 70
2233	   Content-Type: application/kpml-response+xml
2234	   Content-Length: 256

2236	   
2237	   

2245	11.  References

2247	11.1  Normative References

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

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

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

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

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

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

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

2272	   [8]  Rosenberg, J., "Obtaining and Using Globally Routable User Agent
2273	        (UA) URIs (GRUU) in the  Session Initiation Protocol (SIP)",
2274	        draft-ietf-sip-gruu-01 (work in progress), February 2004.

2276	   [9]  Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML
2277	        Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502,
2278	        May 2001.

2280	11.2  Informative References

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

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

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

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

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

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

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

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

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

2314	   [19]  Rosenberg, J., "A Framework for Application Interaction in the
2315	         Session Initiation Protocol  (SIP)",
2316	         draft-ietf-sipping-app-interaction-framework-01 (work in
2317	         progress), February 2004.

2319	   [20]  Burger, E., Van Dyke, J. and A. Spitzer, "Media Server Control
2320	         Markup Language (MSCML) and Protocol", draft-vandyke-mscml-04
2321	         (work in progress), March 2004.

2323	   [21]  Rosenberg, J. and H. Schulzrinne, "An INVITE Inititiated Dialog
2324	         Event Package for the Session Initiation  Protocol (SIP",
2325	         draft-ietf-sipping-dialog-package-02 (work in progress), June
2326	         2003.

2328	   [22]  Roach, A., Rosenberg, J. and B. Campbell, "A Session Initiation
2329	         Protocol (SIP) Event Notification Extension for  Resource
2330	         Lists", draft-ietf-simple-event-list-05 (work in progress),
2331	         August 2004.

2333	Authors' Addresses

2335	   Eric Burger
2336	   Brooktrout Technology, Inc.
2337	   18 Keewaydin Dr.
2338	   Salem, NH  03079
2339	   USA

2341	   EMail: eburger@brooktrout.com

2343	   Martin Dolly
2344	   AT&T Labs

2346	   EMail: mdolly@att.com

2348	Appendix A.  Contributors

2350	   Ophir Frieder of the Illinois Institute of Technology collaborated on
2351	   the development of the buffer algorithm.

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

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

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

2366	   Rohan Mahy did a significant reorganization of the content, as well
2367	   as providing considerable moral support in the production of this
2368	   document.

2370	   That said, any errors, misinterpretation, or fouls in this document
2371	   are our own.

2373	Appendix B.  Acknowledgements

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

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

2381	   Terence Lobo of SnowShore Networks made it all work.

2383	   Jerry Kamitses, Swati Dhuleshia, Shaun Bharrat, Sunil Menon, and
2384	   Bryan Hill helped with clarifying the buffer behavior and DRegex
2385	   syntax.

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

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

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

2397	Intellectual Property Statement

2399	   The IETF takes no position regarding the validity or scope of any
2400	   Intellectual Property Rights or other rights that might be claimed to
2401	   pertain to the implementation or use of the technology described in
2402	   this document or the extent to which any license under such rights
2403	   might or might not be available; nor does it represent that it has
2404	   made any independent effort to identify any such rights.  Information
2405	   on the procedures with respect to rights in RFC documents can be
2406	   found in BCP 78 and BCP 79.

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

2415	   The IETF invites any interested party to bring to its attention any
2416	   copyrights, patents or patent applications, or other proprietary
2417	   rights that may cover technology that may be required to implement
2418	   this standard.  Please address the information to the IETF at
2419	   ietf-ipr@ietf.org.

2421	   The IETF has been notified of intellectual property rights claimed in
2422	   regard to some or all of the specification contained in this
2423	   document.  For more information consult the online list of claimed
2424	   rights.

2426	Disclaimer of Validity

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

2436	Copyright Statement

2438	   Copyright (C) The Internet Society (2004).  This document is subject
2439	   to the rights, licenses and restrictions contained in BCP 78, and
2440	   except as set forth therein, the authors retain all their rights.

2442	Acknowledgment

2444	   Funding for the RFC Editor function is currently provided by the
2445	   Internet Society.