From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc4730.txt | 3139 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3139 insertions(+) create mode 100644 doc/rfc/rfc4730.txt (limited to 'doc/rfc/rfc4730.txt') diff --git a/doc/rfc/rfc4730.txt b/doc/rfc/rfc4730.txt new file mode 100644 index 0000000..b05ad23 --- /dev/null +++ b/doc/rfc/rfc4730.txt @@ -0,0 +1,3139 @@ + + + + + + +Network Working Group E. Burger +Request for Comments: 4730 Cantata Technology, Inc. +Category: Standards Track M. Dolly + AT&T Labs + November 2006 + + + A Session Initiation Protocol (SIP) Event Package + for Key Press Stimulus (KPML) + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The IETF Trust (2006). + +Abstract + + This document describes a SIP Event Package "kpml" that enables + monitoring of Dual Tone Multi-Frequency (DTMF) signals and uses + Extensible Markup Language (XML) documents referred to as Key Press + Markup Language (KPML). The kpml Event Package may be used to + support applications consistent with the principles defined in the + document titled "A Framework for Application Interaction in the + Session Initiation Protocol (SIP)". The event package uses SUBSCRIBE + messages and allows for XML documents that define and describe filter + specifications for capturing key presses (DTMF Tones) entered at a + presentation-free User Interface SIP User Agent (UA). The event + package uses NOTIFY messages and allows for XML documents to report + the captured key presses (DTMF tones), consistent with the filter + specifications, to an Application Server. The scope of this package + is for collecting supplemental key presses or mid-call key presses + (triggers). + + + + + + + + + + + + +Burger & Dolly Standards Track [Page 1] + +RFC 4730 KPML November 2006 + + +Table of Contents + + 1. Introduction ....................................................4 + 1.1. Conventions Used in This Document ..........................5 + 2. Protocol Overview ...............................................5 + 3. Key Concepts ....................................................6 + 3.1. Subscription Duration ......................................6 + 3.2. Timers .....................................................7 + 3.3. Pattern Matches ............................................8 + 3.4. Digit Suppression .........................................12 + 3.5. User Input Buffer Behavior ................................14 + 3.6. DRegex ....................................................16 + 3.6.1. Overview ...........................................16 + 3.6.2. Operation ..........................................18 + 3.7. Monitoring Direction ......................................20 + 3.8. Multiple Simultaneous Subscriptions .......................20 + 4. Event Package Formal Definition ................................21 + 4.1. Event Package Name ........................................21 + 4.2. Event Package Parameters ..................................21 + 4.3. SUBSCRIBE Bodies ..........................................22 + 4.4. Subscription Duration .....................................22 + 4.5. NOTIFY Bodies .............................................22 + 4.6. Subscriber Generation of SUBSCRIBE Requests ...............22 + 4.7. Notifier Processing of SUBSCRIBE Requests .................23 + 4.8. Notifier Generation of NOTIFY Requests ....................25 + 4.9. Subscriber Processing of NOTIFY Requests ..................27 + 4.10. Handling of Forked Requests ..............................28 + 4.11. Rate of Notifications ....................................28 + 4.12. State Agents and Lists ...................................28 + 4.13. Behavior of a Proxy Server ...............................29 + 5. Formal Syntax ..................................................29 + 5.1. DRegex ....................................................29 + 5.2. KPML Request ..............................................30 + 5.3. KPML Response .............................................33 + 6. Enumeration of KPML Status Codes ...............................34 + 7. IANA Considerations ............................................34 + 7.1. SIP Event Package Registration ............................34 + 7.2. MIME Media Type application/kpml-request+xml ..............35 + 7.3. MIME Media Type application/kpml-response+xml .............35 + 7.4. URN Sub-Namespace Registration for + urn:ietf:xml:ns:kpml-request ..............................35 + 7.5. URN Sub-Namespace Registration for + urn:ietf:xml:ns:kpml-response .............................36 + 7.6. KPML Request Schema Registration ..........................37 + 7.7. KPML Response Schema Registration .........................37 + 8. Security Considerations ........................................37 + 9. Examples .......................................................38 + 9.1. Monitoring for Octothorpe .................................38 + + + +Burger & Dolly Standards Track [Page 2] + +RFC 4730 KPML November 2006 + + + 9.2. Dial String Collection ....................................39 + 10. Call Flow Examples ............................................40 + 10.1. Supplemental Digits ......................................40 + 10.2. Multiple Applications ....................................45 + 11. References ....................................................52 + 11.1. Normative References .....................................52 + 11.2. Informative References ...................................53 + Appendix A. Contributors .........................................54 + Appendix B. Acknowledgements .....................................54 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Burger & Dolly Standards Track [Page 3] + +RFC 4730 KPML November 2006 + + +1. Introduction + + This document describes a SIP Event Package "kpml" that enables + monitoring of key presses and utilizes XML documents referred to as + Key Press Markup Language (KPML). KPML is a markup [14] that enables + presentation-free User Interfaces as described in the Application + Interaction Framework [15]. The Key Press Stimulus Package is a SIP + Event Notification Package [5] that uses the SUBSCRIBE and NOTIFY + methods of SIP. The subscription filter and notification report + bodies use the Keypad Markup Language, KPML. + + The "kpml" event package requires the definition of two new MIME + types, two new URN sub-namespaces, and two schemas for the KPML + Request and the KPML Response. The scope of this package is for + collecting supplemental key presses or mid-call key presses + (triggers). This capability allows an Application Server service + provider to monitor (filter) for a set of DTMF patterns at a SIP User + Agent located in either an end-user device or a gateway. + + In particular, the "kpml" event package enables "dumb phones" and + "gateways" that receive signals from dumb phones to report user key- + press events. Colloquially, this mechanism provides for "digit + reporting" or "Dual Tone Multi-Frequency (DTMF) reporting." The + capability eliminates the need for "hair-pinning" (routing media into + and then out of the same device) through a Media Server or + duplicating all the DTMF events, when an Application Server needs to + trigger mid-call service processing on DTMF digit patterns. + + A goal of KPML is to fit in an extremely small memory and processing + footprint. + + The name of the XML document, KPML, reflects its legacy support role. + The public switched telephony network (PSTN) accomplished signaling + by transporting DTMF tones in the bearer channel (in-band signaling) + from the user terminal to the local exchange. + + Voice-over-IP networks transport in-band signals with actual DTMF + waveforms or RFC 2833 [10] packets. In RFC 2833, the signaling + application inserts RFC 2833 named signal packets as well as, or + instead of, generating tones in the media path. The receiving + application receives the signal information in the media stream. + + RFC 2833 tones are ideal for conveying telephone-events point-to- + point in a Real-time Transport Protocol (RTP) stream, as in the + context of straightforward sessions like a 2-party call or a simple, + centrally mixed conference. However, there are other environments + where additional or alternative requirements are needed. These other + environments include protocol translation and complex call control. + + + +Burger & Dolly Standards Track [Page 4] + +RFC 4730 KPML November 2006 + + + An interested application could request notifications of every key + press. However, many of the use cases for such signaling show that + most applications are interested in only one or a few keystrokes. + Thus a mechanism is needed for specifying to the user's interface + what stimuli the application requires. + +1.1. Conventions Used in This Document + + RFC 2119 [1] provides the interpretations for the key words "MUST", + "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", + "RECOMMENDED", "MAY", and "OPTIONAL" found in this document. + + The Application Interaction Framework document [15] provides the + interpretations for the terms "User Device", "SIP Application", and + "User Input". This document uses the term "Application" and + "Requesting Application" interchangeably with "SIP Application". + + Additionally, the Application Interaction Framework document + discusses User Device Proxies. A common instantiation of a User + Device Proxy is a Public Switched Telephone Network (PSTN) gateway. + Because the normative behavior of a presentation-free User Interface + is identical for a presentation-free SIP User Agent and a + presentation-free User Device Proxy, this document uses "User Device" + for both cases. + +2. Protocol Overview + + The "kpml" event package uses explicit subscription notification + requests using the SIP SUBSCRIBE and NOTIFY methods. An Application + that wants to collect digits creates an application/kpml-request+xml + document with the digit patterns of interest to the Application and + places this document in its SUBSCRIBE request. SIP SUBSCRIBE + messages are routed to the User Interface using standard SIP request + routing. KPML Subscriptions do not fork. The KPML request contained + in the SUBSCRIBE message identifies the target media stream by + referencing the dialog identifiers corresponding to the session + responsible for the media stream. Once a subscription is + established, the User Interface sends application/kpml-response+xml + documents in NOTIFY requests when digits are collected or when + timeouts or errors occur. + + A KPML subscription can be persistent or one-shot. Persistent + requests are active until the subscription terminates, the + Application replaces the request, the Application deletes the request + by sending a null document on the dialog, or the Application + explicitly deletes the subscription by sending a SUBSCRIBE with an + expires value of zero (0). + + + + +Burger & Dolly Standards Track [Page 5] + +RFC 4730 KPML November 2006 + + + One-shot requests terminate the subscription upon the receipt of DTMF + values that provide a match. The "persist" KPML element specifies + whether the subscription remains active for the duration specified in + the SUBSCRIBE message or if it automatically terminates upon a + pattern match. + + NOTIFY messages can contain XML documents. If the User Interface + matches a digitmap, the NOTIFY message (response) contains an XML + document that indicates the User Input detected and whether the User + Interface suppressed the representation of User Input, such as tones, + or RFC 2833, from the media streams. If the User Interface + encountered an error condition, such as a timeout, this will also be + reported. + +3. Key Concepts + +3.1. Subscription Duration + + KPML recognizes two types of subscriptions: one-shot and persistent. + Persistent subscriptions have two sub-types: continuous notify and + single-notify. + + One-shot subscriptions terminate after a pattern match occurs and a + report is issued in a NOTIFY message. If the User Interface detects + a key press stimulus that triggers a one-shot KPML event, then the + User Interface (notifier) MUST set the "Subscription-State" in the + NOTIFY message to "terminated". At this point, the User Interface + MUST consider the subscription expired. + + Persistent subscriptions remain active at the User Interface, even + after a match. For continuous-notify persistent subscriptions, the + User Interface will emit a NOTIFY message whenever the User Input + matches a subscribed pattern. For single-notify persistent + subscriptions, the user device will emit a NOTIFY message at the + first match, but will not emit further NOTIFY messages until the + Application issues a new subscription request on the subscription + dialog. + + NOTE: The single-notify persistent subscription enables lock-step + (race-free) quarantining of User Input between different digit + maps. + + The "persist" attribute to the tag in the KPML subscription + body affects the lifetime of the subscription. + + If the "persist" attribute is "one-shot", then once there is a match + (or no match is possible), the subscription ends after the User + Interface notifies the Application. + + + +Burger & Dolly Standards Track [Page 6] + +RFC 4730 KPML November 2006 + + + If the "persist" attribute is "persist" or "single-notify", then the + subscription ends when the Application explicitly ends it or the User + Interface terminates the subscription. + + If the User Interface does not support persistent subscriptions, it + returns a NOTIFY message with the KPML status code set to 531. If + there are digits in the buffer and the digits match an expression in + the SUBSCRIBE filter, the User Interface prepares the appropriate + NOTIFY response message. + + The values of the "persist" attribute are case sensitive. + +3.2. Timers + + To address the various key press collection scenarios, three timers + are defined. They are the extra, critical, and inter-digit timers. + + o The inter-digit timer is the maximum time to wait between digits. + Note: unlike Media Gateway Control Protocol (MGCP) [11] or H.248 + [12], there is no start timer, as that concept does not apply in + the KPML context. + + o The critical timer is the time to wait for another digit if the + collected digits can match more than one potential pattern. + + o The extra timer is the time to wait for another digit if the + collected digits can only match one potential pattern, but a + longer match for this pattern is possible. + + The User Interface MAY support an inter-digit timeout value. This is + the amount of time the User Interface will wait for User Input before + returning a timeout error result on a partially matched pattern. The + application can specify the inter-digit timeout as an integer number + of milliseconds by using the "interdigittimer" attribute to the + tag. The default is 4000 milliseconds. If the User + Interface does not support the specification of an inter-digit + timeout, the User Interface MUST silently ignore the specification. + If the User Interface supports the specification of an inter-digit + timeout, but not to the granularity specified by the value presented, + the User Interface MUST round up the requested value to the closest + value it can support. + + The purpose of the inter-digit timeout is to protect applications + from starting to match a pattern, yet never returning a result. This + can occur, for example, if the user accidentally enters a key that + begins to match a pattern. However, since the user accidentally + entered the key, the rest of the pattern never comes. Moreover, when + the user does enter a pattern, since they have already entered a key, + + + +Burger & Dolly Standards Track [Page 7] + +RFC 4730 KPML November 2006 + + + the pattern may not match or may not match as expected. Likewise, + consider the case where the user thinks they entered a key press, but + the User Interface does not detect the key. This could occur when + collecting ten digits, but the device actually only receives 9. In + this case, the User Interface will wait forever for the tenth key + press, while the user becomes frustrated wondering why the + application is not responding. + + The User Interface MAY support a critical-digit timeout value. This + is the amount of time the User Interface will wait for another key + press when it already has a matched but there is another, + longer that may also match the pattern. The application can + specify the critical-digit timeout as an integer number of + milliseconds by using the "criticaldigittimer" attribute to the + tag. The default is 1000 milliseconds. + + The purpose of the critical-digit timeout is to allow the application + to collect longer matches than the shortest presented. This is + unlike MGCP [11], where the shortest match gets returned. For + example, if the application registers for the patterns "0011", "011", + "00", and "0", the critical-digit timeout enables the User Interface + to distinguish between "0", "00", "011", and "0011". Without this + feature, the only value that the User Interface can detect is "0". + + The User Interface MAY support an extra-digit timeout value. This is + the amount of time the User Interface will wait for another key press + when it already has matched the longest . The application can + specify the extra-digit timeout as an integer number of milliseconds + by using the "extradigittimer" attribute to the tag. The + default is 500 milliseconds. If there is no enterkey specified, then + the User Interface MAY default the exteradigittimer to zero. + + The purpose of the extra-digit timeout is to allow the User Interface + to collect the enterkey. Without this feature, the User Interface + would match the pattern, and the enterkey would be buffered and + returned as the next pattern. + +3.3. Pattern Matches + + During the subscription lifetime, the User Interface may detect a key + press stimulus that triggers a KPML event. In this case, the User + Interface (notifier) MUST return the appropriate KPML document. + + The pattern matching logic works as follows. KPML User Interfaces + MUST follow the logic presented in this section so that different + implementations will perform deterministically on the same KPML + document given the same User Input. + + + + +Burger & Dolly Standards Track [Page 8] + +RFC 4730 KPML November 2006 + + + A kpml request document contains a element with a series of + tags. Each element specifies a potential pattern for + the User Interface to match. The Section 5.1 describes the DRegex, + or digit regular expression, language. + + The pattern match algorithm matches the longest regular expression. + This is the same mode as H.248.1 [12] and not the mode presented by + MGCP [11]. The pattern match algorithm choice has an impact on + determining when a pattern matches. Consider the following KPML + document. + + + + + 0 + 011 + + + + Figure 1: Greedy Matching + + In Figure 1, if we were to match on the first found pattern, the + string "011" would never match. This happens because the "0" rule + would match first. + + While this behavior is what most applications desire, it does come at + a cost. Consider the following KPML document snippet. + + x{7} + x{10} + + Figure 2: Timeout Matching + + Figure 2 shows a typical North American dial plan. From an + application perspective, users expect a seven-digit number to respond + quickly, not waiting the typical inter-digit critical timer (usually + four seconds). Conversely, the user does not want the system to cut + off their ten-digit number at seven digits because they did not enter + the number fast enough. + + One approach to this problem is to have an explicit dial string + terminator. Often, it is the pound key (#). Now, consider the + following snippet. + + + + +Burger & Dolly Standards Track [Page 9] + +RFC 4730 KPML November 2006 + + + x{7}# + x{10}# + + Figure 3: Timeout Matching with Enter + + The problem with the approach in Figure 3 is that the "#" will appear + in the returned dial string. Moreover, one often wants to allow the + user to enter the string without the dial string termination key. In + addition, using explicit matching on the key means one has to double + the number of patterns, e.g., "x{7}", "x{7}#", "x{10}", and "x{10}#". + + The approach used in KPML is to have an explicit "Enter Key", as + shown in the following snippet. + + + x{7} + x{10} + + + Figure 4: Timeout Matching with Enter Key + + In Figure 4, the enterkey attribute to the tag specifies a + string that terminates a pattern. In this situation, if the user + enters seven digits followed by the "#" key, the pattern matches (or + fails) immediately. KPML indicates a terminated nomatch with a KPML + status code 402. + + NOTE: The enterkey is a string. The enterkey can be a sequence of + key presses, such as "**". + + Some patterns look for long-duration key presses. For example, some + applications look for long "#" or long "*". + + KPML uses the "L" modifier to characters to indicate long key + presses. The following KPML document looks for a long pound of at + least 3 seconds. + + + + + + + + + + + + + + + +Burger & Dolly Standards Track [Page 10] + +RFC 4730 KPML November 2006 + + + + + + L# + + + + Long Pound + + The request can specify what constitutes "long" by setting the long + attribute to the . This attribute is an integer + representing the number of milliseconds. If the user presses a key + for longer than "long" milliseconds, the Long modifier is true. The + default length of the long attribute is 2500 milliseconds. + + User Interfaces MUST distinguish between long and short input when + the KPML document specifies both in a document. However, if there is + not a corresponding long key press pattern in a document, the User + Interface MUST match the key press pattern irrespective of the length + of time the user presses the key. + + As an example, in the following snippet in Figure 6, the User + Interface discriminates between a long "*" and a normal "*", but any + length "#" will match the pattern. + + + * + L* + # + + + Figure 6: Long and Short Matching + + Some User Interfaces are unable to present long key presses. An + example is an old private branch exchange (PBX) phone set that emits + fixed-length tones when the user presses a key. To address this + issue, the User Interface MAY interpret a succession of presses of a + single key to be equivalent to a long key press of the same key. The + Application indicates it wants this behavior by setting the + "longrepeat" attribute to the to "true". + + The KPML document specifies if the patterns are to be persistent by + setting the "persist" attribute to the tag to "persist" or + "single-notify". Any other value, including "one-shot", indicates + + + +Burger & Dolly Standards Track [Page 11] + +RFC 4730 KPML November 2006 + + + the request is a one-shot subscription. If the User Interface does + not support persistent subscriptions, it returns a KPML document with + the KPML status code set to 531. If there are digits in the buffer + and the digits match an expression in the KPML document, the User + Interface emits the appropriate kpml notification. + + Note the values of the "persist" attribute are case sensitive. + + Some User Interfaces may support multiple regular expressions in a + given pattern request. In this situation, the application may wish + to know which pattern triggered the event. + + KPML provides a "tag" attribute to the tag. The "tag" is an + opaque string that the User Interface sends back in the notification + report upon a match in the digit map. In the case of multiple + matches, the User Interface MUST choose the longest match in the KPML + document. If multiple matches match the same length, the User + Interface MUST choose the first expression listed in the subscription + KPML document based on KPML document order. + + If the User Interface cannot support multiple regular expressions in + a pattern request, the User Interface MUST return a KPML document + with the KPML status code set to 532. If the User Interface cannot + support the number of regular expressions in the pattern request, the + User Interface MUST return a KPML document with the KPML status code + set to 534. + + NOTE: We could mandate a minimum number of regular expressions + that a User Interface must support per subscription request and + globally. However, such minimums tend to become designed-in, + hard-coded limits. For guidance, one should be able to easily + handle tens of expressions per subscription and thousands + globally. A good implementation should have effectively no + limits. That said, to counter possible denial-of-service attacks, + implementers of User Interfaces should be aware of the 534 and 501 + status codes and feel free to use them. + +3.4. Digit Suppression + + Under basic operation, a KPML User Interface will transmit in-band + tones (RFC 2833 [10] or actual tone) in parallel with User Input + reporting. + + NOTE: If KPML did not have this behavior, then a User Interface + executing KPML could easily break called applications. For + example, take a personal assistant that uses "*9" for attention. + If the user presses the "*" key, KPML will hold the digit, looking + for the "9". What if the user just enters a "*" key, possibly + + + +Burger & Dolly Standards Track [Page 12] + +RFC 4730 KPML November 2006 + + + because they accessed an interactive voice response (IVR) system + that looks for "*"? In this case, the "*" would get held by the + User Interface, because it is looking for the "*9" pattern. The + user would probably press the "*" key again, hoping that the + called IVR system just did not hear the key press. At that point, + the User Interface would send both "*" entries, as "**" does not + match "*9". However, that would not have the effect the user + intended when they pressed "*". + + On the other hand, there are situations where passing through tones + in-band is not desirable. Such situations include call centers that + use in-band tone spills to initiate a transfer. + + For those situations, KPML adds a suppression tag, "pre", to the + tag. There MUST NOT be more than one 
 tag in any given
+    tag.
+
+   If there is only a single  and a single , suppression
+   processing is straightforward.  The end-point passes User Input until
+   the stream matches the regular expression 
.  At that point, the
+   User Interface will continue collecting User Input, but will suppress
+   the generation or pass-through of any in-band User Input.
+
+   If the User Interface suppressed stimulus, it MUST indicate this by
+   including the attribute "suppressed" with a value of "true" in the
+   notification.
+
+   Clearly, if the User Interface is processing the KPML document
+   against buffered User Input, it is too late to suppress the
+   transmission of the User Input, as the User Interface has long sent
+   the stimulus.  This is a situation where there is a 
+   specification, but the "suppressed" attribute will not be "true" in
+   the notification.  If there is a 
 tag that the User Interface
+   matched and the User Interface is unable to suppress the User Input,
+   it MUST set the "suppressed" attribute to "false".
+
+   A KPML User Interface MAY perform suppression.  If it is not capable
+   of suppression, it ignores the suppression attribute.  It MUST set
+   the "suppressed" attribute to "false".  In this case, the pattern to
+   match is the concatenated pattern of pre+value.
+
+   At some point in time, the User Interface will collect enough User
+   Input to the point it matches a 
 pattern.  The interdigittimer
+   attribute indicates how long to wait for the user to enter stimulus
+   before reporting a time-out error.  If the interdigittimer expires,
+   the User Interface MUST issue a time-out report, transmit the
+   suppressed User Input on the media stream, and stop suppression.
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 13]
+
+RFC 4730                          KPML                     November 2006
+
+
+   Once the User Interface detects a match and it sends a NOTIFY request
+   to report the User Input, the User Interface MUST stop suppression.
+   Clearly, if subsequent User Input matches another 
 expression,
+   then the User Interface MUST start suppression.
+
+   After suppression begins, it may become clear that a match will not
+   occur.  For example, take the expression
+
+   
*8
xxx[2-9]xxxxxx
+
+   At the point the User Interface receives "*8", it will stop
+   forwarding stimulus.  Let us say that the next three digits are
+   "408".  If the next digit is a zero or one, the pattern will not
+   match.
+
+      NOTE: It is critically important for the User Interface to have a
+      sensible inter-digit timer.  This is because an errant dot (".")
+      may suppress digit sending forever.
+
+   Applications should be very careful to indicate suppression only when
+   they are fairly sure the user will enter a digit string that will
+   match the regular expression.  In addition, applications should deal
+   with situations such as no-match or time-out.  This is because the
+   User Interface will hold digits, which will have obvious User
+   Interface issues in the case of a failure.
+
+3.5.  User Input Buffer Behavior
+
+   User Interfaces MUST buffer User Input upon receipt of an
+   authenticated and accepted subscription.  Subsequent KPML documents
+   apply their patterns against the buffered User Input.  Some
+   applications use modal interfaces where the first few key presses
+   determine what the following key presses mean.  For a novice user,
+   the application may play a prompt describing what mode the
+   application is in.  However, "power users" often barge through the
+   prompt.
+
+   User Interfaces MUST NOT provide a subscriber with digits that were
+   detected prior to the authentication and authorization of that
+   subscriber.  Without prohibition, a subscriber might be able to gain
+   access to calling card or other information that predated the
+   subscriber's participation in the call.  Note that this prohibition
+   MUST be applied on a per-subscription basis.
+
+   KPML provides a  tag in the  element.  The default is
+   not to flush User Input.  Flushing User Input has the effect of
+   ignoring key presses entered before the installation of the KPML
+   subscription.  To flush User Input, include the tag
+
+
+
+Burger & Dolly              Standards Track                    [Page 14]
+
+RFC 4730                          KPML                     November 2006
+
+
+   yes in the KPML subscription document.  Note that this
+   directive affects only the current subscription dialog/id
+   combination.
+
+   Lock-step processing of User Input is where the User Interface issues
+   a notification, the Application processes the notification while the
+   User Interface buffers additional User Input, the Application
+   requests more User Input, and only then does the User Interface
+   notify the Application based on the collected User Input.  To direct
+   the User Interface to operate in lock-step mode, set the 
+   attribute persist="single-notify".
+
+   The User Interface MUST be able to process no.  This
+   directive is effectively a no-op.
+
+   Other string values for  may be defined in the future.  If the
+   User Interface receives a string it does not understand, it MUST
+   treat the string as a no-op.
+
+   If the user presses a key that cannot match any pattern within a
+    tag, the User Interface MUST discard all buffered key presses
+   up to and including the current key press from consideration against
+   the current or future KPML documents on a given dialog.  However, as
+   described above, once there is a match, the User Interface buffers
+   any key presses the user entered subsequent to the match.
+
+      NOTE: This behavior allows applications to receive only User Input
+      that is of interest to them.  For example, a pre-paid application
+      only wishes to monitor for a long pound.  If the user enters other
+      stimulus, presumably for other applications, the pre-paid
+      application does not want notification of that User Input.  This
+      feature is fundamentally different than the behavior of Time
+      Division Multiplexer (TDM)-based equipment where every application
+      receives every key press.
+
+   To limit reports to only complete matches, set the "nopartial"
+   attribute to the  tag to "true".  In this case, the User
+   Interface attempts to match a rolling window over the collected User
+   input.
+
+   KPML subscriptions are independent.  Thus, it is not possible for the
+   current document to know if a following document will enable barging
+   or want User Input flushed.  Therefore, the User Interface MUST
+   buffer all User Input, subject to the forced_flush caveat described
+   below.
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 15]
+
+RFC 4730                          KPML                     November 2006
+
+
+   On a given SUBSCRIBE dialog with a given id, the User Interface MUST
+   buffer all User Input detected between the time of the report and the
+   receipt of the next document, if any.  If the next document indicates
+   a buffer flush, then the interpreter MUST flush all collected User
+   Input from consideration from KPML documents received on that dialog
+   with the given event id.  If the next document does not indicate
+   flushing the buffered User Input, then the interpreter MUST apply the
+   collected User Input (if possible) against the digit maps presented
+   by the script's  tags.  If there is a match, the interpreter
+   MUST follow the procedures in Section 5.3.  If there is no match, the
+   interpreter MUST flush all of the collected User Input.
+
+   Given the potential for needing an infinite buffer for User Input,
+   the User Interface MAY discard the oldest User Input from the buffer.
+   If the User Interface discards digits, when the User Interface issues
+   a KPML notification, it MUST set the forced_flush attribute of the
+    tag to "true".  For future use, the Application MUST
+   consider any non-null value, other than "false", that it does not
+   understand to be the same as "true".
+
+      NOTE: The requirement to buffer all User Input for the entire
+      length of the session is not onerous under normal operation.  For
+      example, if one has a gateway with 8,000 sessions, and the gateway
+      buffers 50 key presses on each session, the requirement is only
+      400,000 bytes, assuming one byte per key press.
+
+   Unless there is a suppress indicator in the digit map, it is not
+   possible to know if the User Input is for local KPML processing or
+   for other recipients of the media stream.  Thus, in the absence of a
+   suppression indicator, the User Interface transmits the User Input to
+   the far end in real time, using either RFC 2833, generating the
+   appropriate tones, or both.
+
+3.6.  DRegex
+
+3.6.1.  Overview
+
+   This subsection is informative in nature.
+
+   The Digit REGular EXpression (DRegex) syntax is a telephony-oriented
+   mapping of POSIX Extended Regular Expressions (ERE) [13].
+
+   KPML does not use full POSIX ERE for the following reasons.
+
+   o  KPML will often run on high density or extremely low power and
+      memory footprint devices.
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 16]
+
+RFC 4730                          KPML                     November 2006
+
+
+   o  Telephony application convention uses the star symbol ("*") for
+      the star key and "x" for any digit 0-9.  Requiring the developer
+      to escape the star ("\*") and expand the "x" ("[0-9]") is error
+      prone.  This also leads DRegex to use the dot (".") to indicate
+      repetition, which was the function of the unadorned star in POSIX
+      ERE.
+
+   o  Implementation experience with MGCP [11] and H.248.1 [12] has been
+      that implementers and users have a hard time understanding the
+      precedence of the alternation operator ("|").  This is due both to
+      an under-specification of the operator in those documents and
+      conceptual problems for users.  Thus, the SIPPING Working Group
+      concluded that DRegex should not support alternation.  That said,
+      each KPML  element may contain multiple regular
+      expressions ( elements).  Thus, it is straightforward to
+      have pattern alternatives (use multiple  elements) without
+      the problems associated with the alternation operator ("|").
+      Thus, DRegex does not support the POSIX alternation operator.
+
+   o  DRegex includes character classes (characters enclosed in square
+      brackets).  However, the negation operator inside a character
+      class only operates on numbers.  That is, a negation class
+      implicitly includes A-D, *, and #.  Including A-D, *, and # in a
+      negation operator is a no-op.  Those familiar with POSIX would
+      expect negation of the digits 4 and 5 (e.g., "[^45]") to include
+      all other characters (including A-D, R, *, and #), while those
+      familiar with telephony digit maps would expect negation to
+      implicitly exclude non-digit characters.  Since the complete
+      character set of DRegex is very small, constructing a negation
+      class using A-D, R, *, and # requires the user to specify the
+      positive inverse mapping.  For example, to specify all key
+      presses, including A-D and *, except #, the specification would be
+      "[0-9A-D*]" instead of "[^#R]".
+
+   The following table shows the mapping from DRegex to POSIX ERE.
+
+                          +--------+-----------+
+                          | DRegex | POSIX ERE |
+                          +--------+-----------+
+                          | *      | \*        |
+                          | .      | *         |
+                          | x      | [0-9]     |
+                          | [xc]   | [0-9c]    |
+                          +--------+-----------+
+
+                   Table 1: DRegex to POSIX ERE Mapping
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 17]
+
+RFC 4730                          KPML                     November 2006
+
+
+   The first substitution, which replaces a star for an escaped star, is
+   because telephony application designers are used to using the star
+   for the (very common) star key.  Requiring an escape sequence for
+   this common pattern would be error prone.  In addition, the usage
+   found in DRegex is the same as found in MGCP [11] and H.248.1 [12].
+
+   Likewise, the use of the dot instead of star is common usage from
+   MGCP and H.248.1, and reusing the star in this context would also be
+   confusing and error prone.
+
+   The "x" character is a common indicator of the digits 0 through 9.
+   We use it here, continuing the convention.  Clearly, for the case
+   "[xc]", where c is any character, the substitution is not a blind
+   replacement of "[0-9]" for "x", as that would result in "[[0-9]c]",
+   which is not a legal POSIX ERE.  Rather, the substitution for "[xc]"
+   is "[0-9c]".
+
+      NOTE: "x" does not include the characters *, #, R, or A through D.
+
+   Users need to take care not to confuse the DRegex syntax with POSIX
+   EREs.  They are NOT identical.  In particular, there are many
+   features of POSIX EREs that DRegex does not support.
+
+   As an implementation note, if one makes the substitutions described
+   in the above table, then a standard POSIX ERE engine can parse the
+   digit string.  However, the mapping does not work in the reverse
+   (POSIX ERE to DRegex) direction.  DRegex only implements the
+   normative behavior described below.
+
+3.6.2.  Operation
+
+   White space is removed before parsing DRegex.  This enables sensible
+   pretty printing in XML without affecting the meaning of the DRegex
+   string.
+
+   The following rules demonstrate the use of DRegex in KPML.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 18]
+
+RFC 4730                          KPML                     November 2006
+
+
+   +---------+---------------------------------------------------------+
+   | Entity  | Matches                                                 |
+   +---------+---------------------------------------------------------+
+   | c       | digits 0-9, *, #, R, and A-D (case insensitive)         |
+   | *       | the * character                                         |
+   | #       | the # character                                         |
+   | R       | The R (Register Recall) key                             |
+   | [c]     | Any character in selector                               |
+   | [^d]    | Any digit (0-9) not in selector                         |
+   | [r1-r2] | Any character in range from r1 to r2, inclusive         |
+   | x       | Any digit 0-9                                           |
+   | {m}     | m repetitions of previous pattern                       |
+   | {m,}    | m or more repetitions of previous pattern               |
+   | {,n}    | At most n (including zero) repetitions of previous      |
+   |         | pattern                                                 |
+   | {m,n}   | At least m and at most n repetitions of previous        |
+   |         | pattern                                                 |
+   | Lc      | Match the character c if it is "long"; c is a digit 0-9 |
+   |         | and A-D, #, or *.                                       |
+   +---------+---------------------------------------------------------+
+
+                              DRegex Entities
+
+   For ranges, the A-D characters are disjoint from the 0-9 characters.
+   If the device does not have an "R" key, the device MAY report a hook
+   flash as an R character.
+
+       +--------------+--------------------------------------------+
+       | Example      | Description                                |
+       +--------------+--------------------------------------------+
+       | 1            | Matches the digit 1                        |
+       | [179]        | Matches 1, 7, or 9                         |
+       | [2-9]        | Matches 2, 3, 4, 5, 6, 7, 8, 9             |
+       | [^15]        | Matches 0, 2, 3, 4, 6, 7, 8, 9             |
+       | [02-46-9A-D] | Matches 0, 2, 3, 4, 6, 7, 8, 9, A, B, C, D |
+       | x            | Matches 0, 1, 2, 3, 4, 5, 6, 7, 8, 9       |
+       | *6[179#]     | Matches *61, *67, *69, or *6#              |
+       | x{10}        | Ten digits (0-9)                           |
+       | 011x{7,15}   | 011 followed by seven to fifteen digits    |
+       | L*           | Long star                                  |
+       +--------------+--------------------------------------------+
+
+                              DRegex Examples
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 19]
+
+RFC 4730                          KPML                     November 2006
+
+
+3.7.  Monitoring Direction
+
+   SIP identifies dialogs by their dialog identifier.  The dialog
+   identifier is the remote-tag, local-tag, and Call-ID entities defined
+   in RFC 3261 [4].
+
+   One method of determining the dialog identifier, particularly for
+   third-party applications, is the SIP Dialog Package [17].
+
+   For most situations, such as a monaural point-to-point call with a
+   single codec, the stream to monitor is obvious.  In such situations
+   the Application need not specify which stream to monitor.
+
+   But there may be ambiguity in specifying only the SIP dialog to
+   monitor.  The dialog may specify multiple SDP streams that could
+   carry key press events.  For example, a dialog may have multiple
+   audio streams.  Wherever possible, the User Interface MAY apply local
+   policy to disambiguate which stream or streams to monitor.  In order
+   to have an extensible mechanism for identifying streams, the
+   mechanism for specifying streams is as an element content to the
+    tag.  The only content defined today is the
+   reverse tag.
+
+   By default, the User Interface monitors key presses emanating from
+   the User Interface.  Given a dialog identifier of Call-ID, local-tag,
+   and remote-tag, the User Interface monitors the key presses
+   associated with the local-tag.
+
+   In the media proxy case, and potentially other cases, there is a need
+   to monitor the key presses arriving from the remote user agent.  The
+   optional  element to the  tag specifies which stream
+   to monitor.  The only legal value is "reverse", which means to
+   monitor the stream associated with the remote-tag.  The User
+   Interface MUST ignore other values.
+
+      NOTE: The reason this is a tag is so individual stream selection,
+      if needed, can be addressed in a backwards-compatible way.
+      Further specification of the stream to monitor is the subject of
+      future standardization.
+
+3.8.  Multiple Simultaneous Subscriptions
+
+   An Application MAY register multiple User Input patterns in a single
+   KPML subscription.  If the User Interface supports multiple,
+   simultaneous KPML subscriptions, the Application installs the
+   subscriptions either in a new SUBSCRIBE-initiated dialog or on an
+   existing SUBSCRIBE-initiated dialog with a new event id tag.  If the
+   User Interface does not support multiple, simultaneous KPML
+
+
+
+Burger & Dolly              Standards Track                    [Page 20]
+
+RFC 4730                          KPML                     November 2006
+
+
+   subscriptions, the User Interface MUST respond with an appropriate
+   KPML status code.
+
+   Some User Interfaces may support multiple key press event
+   notification subscriptions at the same time.  In this situation, the
+   User Interface honors each subscription individually and
+   independently.
+
+   A SIP user agent may request multiple subscriptions on the same
+   SUBSCRIBE dialog, using the id parameter to the kpml event request.
+
+   One or more SIP user agents may request independent subscriptions on
+   different SIP dialogs, although reusing the same dialog for multiple
+   subscriptions is NOT RECOMMENDED.
+
+   If the User Interface does not support multiple, simultaneous
+   subscriptions, the User Interface MUST return a KPML document with
+   the KPML status code set to 533 on the dialog that requested the
+   second subscription.  The User Interface MUST NOT modify the state of
+   the first subscription on account of the second subscription attempt.
+
+4.  Event Package Formal Definition
+
+4.1.  Event Package Name
+
+   This document defines a SIP Event Package as defined in RFC 3265 [5].
+   The event-package token name for this package is:
+
+           "kpml"
+
+4.2.  Event Package Parameters
+
+   This package defines three Event Package parameters: call-id, remote-
+   tag, and local-tag.  These parameters MUST be present, to identify
+   the subscription dialog.  The User Interface matches the local-tag
+   against the to tag, the remote-tag against the from tag, and the
+   call-id against the Call-ID.
+
+   The ABNF for these parameters is below.  It refers to many
+   constructions from the ABNF of RFC 3261, such as EQUAL, DQUOTE, and
+   token.
+
+   call-id     =  "call-id" EQUAL ( token / DQUOTE callid DQUOTE )
+                    ;; NOTE: any DQUOTEs inside callid MUST be escaped!
+   remote-tag  =  "remote-tag" EQUAL token
+   local-tag   =  "local-tag" EQUAL token
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 21]
+
+RFC 4730                          KPML                     November 2006
+
+
+   If any call-ids contain embedded double-quotes, those double-quotes
+   MUST be escaped using the backslash-quoting mechanism.  Note that the
+   call-id parameter may need to be expressed as a quoted string.  This
+   is because the ABNF for the callid production and the word
+   production, which is used by callid (both from RFC 3261 [1]), allow
+   some characters (such as "@", "[", and ":") that are not allowed
+   within a token.
+
+4.3.  SUBSCRIBE Bodies
+
+   Applications using this event package include an application/
+   kpml-request+xml body in SUBSCRIBE requests to indicate which digit
+   patterns they are interested in.  The syntax of this body type is
+   formally described in Section 5.2.
+
+4.4.  Subscription Duration
+
+   The subscription lifetime should be longer than the expected call
+   time.  Subscriptions to this event package MAY range from minutes to
+   weeks.  Subscriptions in hours or days are more typical and are
+   RECOMMENDED.  The default subscription duration for this event
+   package is 7200 seconds.
+
+      Subscribers MUST be able to handle the User Interface returning an
+      Expires value smaller than the requested value.  Per RFC 3265 [5],
+      the subscription duration is the value returned by the Notifier in
+      the 200 OK Expires header.
+
+4.5.  NOTIFY Bodies
+
+   NOTIFY requests can contain application/kpml-response+xml (KPML
+   Response) bodies.  The syntax of this body type is formally described
+   in Section 5.3.  NOTIFY requests in immediate response to a SUBSCRIBE
+   request MUST NOT contain a body unless they are notifying the
+   subscriber of an error condition or previously buffered digits.
+
+   Notifiers MAY send notifications with any format acceptable to the
+   subscriber (based on the subscriber's inclusion of these formats in
+   an Accept header).  A future extension MAY define other NOTIFY
+   bodies.  If no "Accept" header is present in the SUBSCRIBE, the body
+   type defined in this document MUST be assumed.
+
+4.6.  Subscriber Generation of SUBSCRIBE Requests
+
+   A kpml request document contains a  element with a series of
+    tags.  Each  element specifies a potential pattern for
+   the User Interface to match.  Section 5.1 describes the DRegex, or
+   digit regular expression, language.
+
+
+
+Burger & Dolly              Standards Track                    [Page 22]
+
+RFC 4730                          KPML                     November 2006
+
+
+   KPML specifies key press event notification filters.  The MIME type
+   for KPML requests is application/kpml-request+xml.
+
+   The KPML request document MUST be well formed and SHOULD be valid.
+   KPML documents MUST conform to XML 1.0 [14] and MUST use UTF-8
+   encoding.
+
+   Because of the potentially sensitive nature of the information
+   reported by KPML, subscribers SHOULD use sips: and MAY use S/MIME on
+   the content.
+
+   Subscribers MUST be prepared for the notifier to insist on
+   authentication of the subscription request.  Subscribers MUST be
+   prepared for the notifier to insist on using a secure communication
+   channel.
+
+4.7.  Notifier Processing of SUBSCRIBE Requests
+
+   The user information transported by KPML is potentially sensitive.
+   For example, it could include calling card or credit card numbers.
+   Thus the User Interface (notifier) MUST authenticate the requesting
+   party in some way before accepting the subscription.
+
+   User Interfaces MUST implement SIP Digest authentication as required
+   by RFC 3261 [4] and MUST implement the sips: scheme and TLS.
+
+   Upon authenticating the requesting party, the User Interface
+   determines if the requesting party has authorization to monitor the
+   user's key presses.  The default authorization policy is to allow a
+   KPML subscriber who can authenticate with a specific identity to
+   monitor key presses from SIP sessions in which the same or equivalent
+   authenticated identity is a participant.  In addition, KPML will
+   often be used, for example, between "application servers"
+   (subscribers) and PSTN gateways (notifiers) operated by the same
+   domain or federation of domains.  In this situation a notifier MAY be
+   configured with a list of subscribers which are specifically trusted
+   and authorized to subscribe to key press information related to all
+   sessions in a particular context.
+
+   The User Interface returns a Contact URI that may have GRUU [9]
+   properties in the Contact header of a SIP INVITE, 1xx, or 2xx
+   response.
+
+   After authorizing the request, the User Interface checks to see if
+   the request is to terminate a subscription.  If the request will
+   terminate the subscription, the User Interface does the appropriate
+   processing, including the procedures described in Section 5.2.
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 23]
+
+RFC 4730                          KPML                     November 2006
+
+
+   If the request has no KPML body, then any KPML document running on
+   that dialog and addressed by the event id, if present, immediately
+   terminates.  This is a mechanism for unloading a KPML document while
+   keeping the SUBSCRIBE-initiated dialog active.  This can be important
+   for secure sessions that have high costs for session establishment.
+   The User Interface follows the procedures described in Section 5.2.
+
+   If the dialog referenced by the kpml subscription does not exist, the
+   User Interface follows the procedures in Section 5.3.  Note the User
+   Interface MUST issue a 200 OK to the SUBSCRIBE request before issuing
+   the NOTIFY, as the SUBSCRIBE itself is well formed.
+
+   If the request has a KPML body, the User Interface parses the KPML
+   document.  The User Interface SHOULD validate the XML document
+   against the schema presented in Section 5.2.  If the document is not
+   valid, the User Interface rejects the SUBSCRIBE request with an
+   appropriate error response and terminates the subscription.  If there
+   is a loaded KPML document on the subscription, the User Interface
+   unloads the document.
+
+   In addition, if there is a loaded KPML document on the subscription,
+   the end device unloads the document.
+
+   Following the semantics of SUBSCRIBE, if the User Interface receives
+   a resubscription, the User Interface MUST terminate the existing KPML
+   request and replace it with the new request.
+
+   It is possible for the INVITE usage of the dialog to terminate during
+   key press collection.  The cases enumerated here are explicit
+   subscription termination, automatic subscription termination, and
+   underlying (INVITE-initiated) dialog termination.
+
+   If a SUBSCRIBE request has an expires of zero (explicit SUBSCRIBE
+   termination), includes a KPML document, and there is buffered User
+   Input, then the User Interface attempts to process the buffered
+   digits against the document.  If there is a match, the User Interface
+   MUST generate the appropriate KPML report with the KPML status code
+   of 200.  The SIP NOTIFY body terminates the subscription by setting
+   the subscription state to "terminated" and a reason of "timeout".
+
+   If the SUBSCRIBE request has an expires of zero and no KPML body or
+   the expires timer on the SUBSCRIBE-initiated dialog fires at the User
+   Interface (notifier), then the User Interface MUST issue a KPML
+   report with the KPML status code 487, Subscription Expired.  The
+   report also includes the User Input collected up to the time the
+   expires timer expired or when the subscription with expires equal to
+   zero was processed.  This could be the null string.
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 24]
+
+RFC 4730                          KPML                     November 2006
+
+
+   Per the mechanisms of RFC 3265 [5], the User Interface MUST terminate
+   the SIP SUBSCRIBE dialog.  The User Interface does this via the SIP
+   NOTIFY body transporting the final report described in the preceding
+   paragraph.  In particular, the subscription state will be
+   "terminated" and a reason of "timeout".
+
+   Terminating the subscription when a dialog terminates ensures
+   reauthorization (if necessary) for attaching to subsequent
+   subscriptions.
+
+   If a SUBSCRIBE request references a dialog that is not present at the
+   User Interface, the User Interface MUST generate a KPML report with
+   the KPML status code 481, Dialog Not Found.  The User Interface
+   terminates the subscription by setting the subscription state to
+   "terminated".
+
+   If the KPML document is not valid, the User Interface generates a
+   KPML report with the KPML status code 501, Bad Document.  The User
+   Interface terminates the subscription by setting the subscription
+   state to "terminated".
+
+   If the document is valid but the User Interface does not support a
+   namespace in the document, the User Interface MUST respond with a
+   KPML status code 502, Namespace Not Supported.
+
+4.8.  Notifier Generation of NOTIFY Requests
+
+   Immediately after a subscription is accepted, the Notifier MUST send
+   a NOTIFY with the current location information as appropriate based
+   on the identity of the subscriber.  This allows the Subscriber to
+   resynchronize its state.
+
+   The User Interface (notifier in SUBSCRIBE/NOTIFY parlance) generates
+   NOTIFY requests based on the requirements of RFC 3265 [5].
+   Specifically, if a SUBSCRIBE request is valid and authorized, it will
+   result in an immediate NOTIFY.
+
+   The KPML payload distinguishes between an initial NOTIFY and a NOTIFY
+   informing of key presses.  If there is no User Input buffered at the
+   time of the SUBSCRIBE (see below) or the buffered User Input does not
+   match the new KPML document, then the immediate NOTIFY MUST NOT
+   contain a KPML body.  If User Interface has User Input buffered that
+   results in a match using the new KPML document, then the NOTIFY MUST
+   return the appropriate KPML document.
+
+   The NOTIFY in response to a SUBSCRIBE request has no KPML if there
+   are no matching buffered digits.  An example of this is in Figure 10.
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 25]
+
+RFC 4730                          KPML                     November 2006
+
+
+   If there are buffered digits in the SUBSCRIBE request that match a
+   pattern, then the NOTIFY message in response to the SUBSCRIBE request
+   MUST include the appropriate KPML document.
+
+   NOTIFY sip:application@example.com SIP/2.0
+   Via: SIP/2.0/UDP proxy.example.com
+   Max-Forwards: 70
+   To: 
+   From: 
+   Call-Id: 439hu409h4h09903fj0ioij
+   Subscription-State: active; expires=7200
+   CSeq: 49851 NOTIFY
+   Event: kpml
+
+                    Figure 10: Immediate NOTIFY Example
+
+   All subscriptions MUST be authenticated, particularly those that
+   match on buffered input.
+
+   KPML specifies the key press notification report format.  The MIME
+   type for KPML reports is application/kpml-response+xml.  The default
+   MIME type for the kpml event package is application/
+   kpml-response+xml.
+
+   If the requestor is not using a secure transport protocol such as TLS
+   for every hop (e.g., by using a sips: URI), the User Interface SHOULD
+   use S/MIME to protect the user information in responses.
+
+   When the user enters key presses that match a  tag, the User
+   Interface will issue a report.
+
+   After reporting, the interpreter terminates the KPML session unless
+   the subscription has a persistence indicator.  If the subscription
+   does not have a persistence indicator, the User Interface MUST set
+   the state of the subscription to "terminated" in the NOTIFY report.
+
+   If the subscription does not have a persistence indicator, to collect
+   more digits, the requestor must issue a new request.
+
+      NOTE: This highlights the "one shot" nature of KPML, reflecting
+      the balance of features and ease of implementing an interpreter.
+
+   KPML reports have two mandatory attributes, code and text.  These
+   attributes describe the state of the KPML interpreter on the User
+   Interface.  Note the KPML status code is not necessarily related to
+   the SIP result code.  An important example of this is where a legal
+   SIP subscription request gets a normal SIP 200 OK followed by a
+   NOTIFY, but there is something wrong with the KPML request.  In this
+
+
+
+Burger & Dolly              Standards Track                    [Page 26]
+
+RFC 4730                          KPML                     November 2006
+
+
+   case, the NOTIFY would include the KPML status code in the KPML
+   report.  Note that from a SIP perspective, the SUBSCRIBE and NOTIFY
+   were successful.  Also, if the KPML failure is not recoverable, the
+   User Interface will most likely set the Subscription-State to
+   "terminated".  This lets the SIP machinery know the subscription is
+   no longer active.
+
+   If a pattern matches, the User Interface will emit a KPML report.
+   Since this is a success report, the code is "200", and the text is
+   "OK".
+
+   The KPML report includes the actual digits matched in the digit
+   attribute.  The digit string uses the conventional characters '*' and
+   '#' for star and octothorpe, respectively.  The KPML report also
+   includes the tag attribute if the regex that matched the digits had a
+   tag attribute.
+
+   If the subscription requested digit suppression and the User
+   Interface suppressed digits, the suppressed attribute indicates
+   "true".  The default value of suppressed is "false".
+
+      NOTE: KPML does not include a timestamp.  There are a number of
+      reasons for this.  First, what timestamp would it include?  Would
+      it be the time of the first detected key press?  The time the
+      interpreter collected the entire string?  A range?  Second, if the
+      RTP timestamp is a datum of interest, why not simply get RTP in
+      the first place?  That all said, if it is really compelling to
+      have the timestamp in the response, it could be an attribute to
+      the  tag.
+
+   Note that if the monitored (INVITE-initiated) dialog terminates, the
+   notifier still MUST explicitly terminate the KPML subscriptions
+   monitoring that dialog.
+
+4.9.  Subscriber Processing of NOTIFY Requests
+
+   If there is no KPML body, it means the SUBSCRIBE was successful.
+   This establishes the dialog if there is no buffered User Input to
+   report.
+
+   If there is a KPML document, and the KPML status code is 200, then a
+   match occurred.
+
+   If there is a KPML document, and the KPML status code is between 400
+   and 499, then an error occurred with User Input collection.  The most
+   likely cause is a timeout condition.
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 27]
+
+RFC 4730                          KPML                     November 2006
+
+
+   If there is a KPML document, and the KPML status code is between 500
+   and 599, then an error occurred with the subscription.  See Section 6
+   for more on the meaning of KPML status codes.
+
+   The subscriber MUST be mindful of the subscription state.  The User
+   Interface may terminate the subscription at any time.
+
+4.10.  Handling of Forked Requests
+
+   Forked requests are NOT ALLOWED for this event type.  This can be
+   ensured if the Subscriptions to this event package are sent to SIP
+   URIs that have GRUU properties.
+
+4.11.  Rate of Notifications
+
+   The User Interface MUST NOT generate messages faster than 25 messages
+   per second, or one message every 40 milliseconds.  This is the
+   minimum time period for MF digit spills.  Even 30-millisecond DTMF,
+   as one sometimes finds in Japan, has a 20-millisecond off time,
+   resulting in a 50-millisecond interdigit time.  This document
+   strongly RECOMMENDS AGAINST using KPML for digit-by-digit messaging,
+   such as would be the case if the only  is "x".
+
+   The sustained rate of notification shall be no more than 100 Notifies
+   per minute.
+
+   The User Interface MUST reliably deliver notifications.  Because
+   there is no meaningful metric for throttling requests, the User
+   Interface SHOULD send NOTIFY messages over a congestion-controlled
+   transport, such as TCP.
+
+      Note that all SIP implementations are already required to
+      implement SIP over TCP.
+
+4.12.  State Agents and Lists
+
+   KPML requests are sent to a specific SIP URI, which may have GRUU
+   properties, and they attempt to monitor a specific stream that
+   corresponds with a specific target dialog.  Consequently,
+   implementers MUST NOT define state agents for this event package or
+   allow subscriptions for this event package to resource lists using
+   the event list extension [18].
+
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 28]
+
+RFC 4730                          KPML                     November 2006
+
+
+4.13.  Behavior of a Proxy Server
+
+   There are no additional requirements on a SIP Proxy, other than to
+   transparently forward the SUBSCRIBE and NOTIFY methods as required in
+   SIP.
+
+5.  Formal Syntax
+
+5.1.  DRegex
+
+   The following definition follows RFC 4234 [2].  The definition of
+   DIGIT is from RFC 4234, namely, the characters "0" through "9".  Note
+   the DRegexCharacter is not a HEXDIG from RFC 4234.  In particular,
+   DRegexCharacter includes neither "E" nor "F".  Note that
+   DRegexCharacter is case insensitive.
+
+   DRegex           = 1*( DRegexPosition [ RepeatCount ] )
+   DRegexPosition   = DRegexSymbol / DRegexSet
+   DRegexSymbol     = [ "L" ] DRegexCharacter
+   DRegexSet        = "[" 1*DRegexSetList "]"
+   DRegexSetList    = DRegexCharacter [ "-" DRegexCharacter ]
+   DRegexCharacter  = DIGIT / "A" / "B" / "C" / "D" / "R" / "*" / "#" /
+                            "a" / "b" / "c" / "d" / "r"
+   RepeatCount      = "." / "{" RepeatRange "}"
+   RepeatRange      = Count / ( Count "," Count ) /
+                              ( Count "," ) / ( "," Count )
+   Count            = 1*DIGIT
+
+                              ABNF for DRegex
+
+   Note that future extensions to this document may introduce other
+   characters for DRegexCharacter, in the scheme of H.248.1 [12] or
+   possibly as named strings or XML namespaces.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 29]
+
+RFC 4730                          KPML                     November 2006
+
+
+5.2.  KPML Request
+
+   The following syntax for KPML requests uses the XML Schema [8].
+
+   
+   
+     
+       
+         IETF Keypad Markup Language Request
+         
+       
+       
+         
+           
+             
+               
+                 
+                 
+               
+             
+           
+           
+             
+               
+                 
+                   
+                     
+                       Default is to not flush buffer
+                     
+                   
+                   
+                     
+                       
+                     
+                   
+                 
+                 
+                   
+                     
+                       Key press notation is a string to allow
+                       for future extension of non-16 digit
+                       keypads or named keys
+                     
+                   
+
+
+
+Burger & Dolly              Standards Track                    [Page 30]
+
+RFC 4730                          KPML                     November 2006
+
+
+                   
+                     
+                       
+                         
+                           
+                             
+                           
+                         
+                       
+                       
+                     
+                     
+                   
+                 
+               
+               
+                 
+                   Default is "one-shot"
+                   
+                 
+                 
+                   
+                     
+                     
+                     
+                   
+                 
+               
+               
+                 
+                   Default is 4000 (ms)
+                   
+                 
+               
+               
+                 
+                   Default is 1000 (ms)
+                   
+                 
+               
+               
+
+
+
+Burger & Dolly              Standards Track                    [Page 31]
+
+RFC 4730                          KPML                     November 2006
+
+
+                 
+                   Default is 500 (ms)
+                   
+                 
+               
+               
+               
+               
+                 
+                   Default is false
+                   
+                 
+               
+               
+                 
+                   No default enterkey
+                   
+                 
+               
+             
+           
+         
+         
+       
+     
+   
+
+                  Figure 12: XML Schema for KPML Requests
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 32]
+
+RFC 4730                          KPML                     November 2006
+
+
+5.3.  KPML Response
+
+   The following syntax for KPML responses uses the XML Schema [8].
+
+   
+   
+     
+       
+         IETF Keypad Markup Language Response
+         
+       
+       
+         
+         
+         
+         
+         
+           
+             
+               String for future use for e.g., number of digits lost.
+             
+           
+         
+         
+         
+           
+             Matches tag from regex in request
+             
+           
+         
+       
+     
+   
+
+                       XML Schema for KPML Responses
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 33]
+
+RFC 4730                          KPML                     November 2006
+
+
+6.  Enumeration of KPML Status Codes
+
+   KPML status codes broadly follow their SIP counterparts.  Codes that
+   start with a 2 indicate success.  Codes that start with a 4 indicate
+   failure.  Codes that start with a 5 indicate a server failure,
+   usually a failure to interpret the document or to support a requested
+   feature.
+
+   KPML clients MUST be able to handle arbitrary status codes by
+   examining the first digit only.
+
+   Any text can be in a KPML report document.  KPML clients MUST NOT
+   interpret the text field.
+
+        +------+--------------------------------------------------+
+        | Code | Text                                             |
+        +------+--------------------------------------------------+
+        | 200  | Success                                          |
+        | 402  | User Terminated without Match                    |
+        | 423  | Timer Expired                                    |
+        | 481  | Dialog Not Found                                 |
+        | 487  | Subscription Expired                             |
+        | 501  | Bad Document                                     |
+        | 502  | Namespace Not Supported                          |
+        | 531  | Persistent Subscriptions Not Supported           |
+        | 532  | Multiple Regular Expressions Not Supported       |
+        | 533  | Multiple Subscriptions on a Dialog Not Supported |
+        | 534  | Too Many Regular Expressions                     |
+        +------+--------------------------------------------------+
+
+                        Table 4: KPML Status Codes
+
+7.  IANA Considerations
+
+   This document registers a new SIP Event Package, two new MIME types,
+   and two new XML namespaces.
+
+7.1.  SIP Event Package Registration
+
+   Package name:  kpml
+   Type:  package
+   Contact:  Eric Burger, 
+   Change Controller:  SIPPING Working Group delegated from the IESG
+   Published Specification:  RFC 4730
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 34]
+
+RFC 4730                          KPML                     November 2006
+
+
+7.2.  MIME Media Type application/kpml-request+xml
+
+   MIME media type name:  application
+   MIME subtype name:  kpml-request+xml
+   Required parameters:  none
+   Optional parameters:  Same as charset parameter application/xml as
+      specified in XML Media Types [3]
+   Encoding considerations:  See RFC 3023 [3].
+   Security considerations:  See Section 10 of RFC 3023 [3] and
+      Section 8 of RFC 4730
+   Interoperability considerations:  See RFC 2023 [3] and RFC 4730
+   Published specification:  RFC 4730
+   Applications which use this media type:  Session-oriented
+      applications that have primitive User Interfaces.
+   Change controller:  SIPPING Working Group delegated from the IESG
+   Personal and email address for further information:  Eric Burger
+      
+   Intended usage:  COMMON
+
+7.3.  MIME Media Type application/kpml-response+xml
+
+   MIME media type name:  application
+   MIME subtype name:  kpml-response+xml
+   Required parameters:  none
+   Optional parameters:  Same as charset parameter application/xml as
+      specified in XML Media Types [3]
+   Encoding considerations:  See RFC 3023 [3].
+   Security considerations:  See Section 10 of RFC 3023 [3] and
+      Section 8 of RFC 4730
+   Interoperability considerations:  See RFC 2023 [3] and RFC 4730
+   Published specification:  RFC 4730
+   Applications which use this media type:  Session-oriented
+      applications that have primitive User Interfaces.
+   Change controller:  SIPPING Working Group delegated from the IESG
+   Personal and email address for further information:  Eric Burger
+      
+   Intended usage:  COMMON
+
+7.4.  URN Sub-Namespace Registration for urn:ietf:xml:ns:kpml-request
+
+   URI: urn:ietf:params:xml:ns:kpml-request
+
+   Registrant Contact: The IESG 
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 35]
+
+RFC 4730                          KPML                     November 2006
+
+
+   XML:
+
+   
+   
+   
+     
+       
+       Key Press Markup Language Request
+     
+     
+       
Namespace for Key Press Markup Language Request

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

+       

+   RFC 4730.
+       

+     
+   
+
+7.5.  URN Sub-Namespace Registration for urn:ietf:xml:ns:kpml-response
+
+   URI: urn:ietf:params:xml:ns:kpml-response
+
+   Registrant Contact: The IESG 
+
+   XML:
+
+   
+   
+   
+     
+       
+       Key Press Markup Language Response
+     
+     
+       
Namespace for Key Press Markup Language Response

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

+       

+   RFC 4730.
+       

+     
+   
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 36]
+
+RFC 4730                          KPML                     November 2006
+
+
+7.6.  KPML Request Schema Registration
+
+   Per RFC 3688 [7], IANA registered the XML Schema for KPML as
+   referenced in Section 5.2 of RFC 4730.
+
+   URI: urn:ietf:params:xml:schema:kpml-request
+
+   Registrant Contact: 
+
+7.7.  KPML Response Schema Registration
+
+   Per RFC 3688 [7], IANA registered the XML Schema for KPML as
+   referenced in Section 5.3 of RFC 4730.
+
+   URI: urn:ietf:params:xml:schema:kpml-response
+
+   Registrant Contact: IETF, SIPPING Work Group , Eric
+   Burger .
+
+8.  Security Considerations
+
+   The user information transported by KPML is potentially sensitive.
+   For example, it could include calling card or credit card numbers.
+   This potentially private information could be provided accidentally
+   if the notifier does not properly authenticate or authorize a
+   subscription.  Similarly private information (such as a credit card
+   number or calling card number) could be revealed to an otherwise
+   legitimate subscriber (one operating an IVR) if digits buffered
+   earlier in the session are provided unintentionally to the new
+   subscriber.
+
+   Likewise, an eavesdropper could view KPML digit information if it is
+   not encrypted, or an attacker could inject fraudulent notifications
+   unless the messages or the SIP path over which they travel are
+   integrity protected.
+
+   Therefore, User Interfaces MUST NOT downgrade their own security
+   policy.  That is, if a User Interface policy is to restrict
+   notifications to authenticated and authorized subscribers over secure
+   communications, then the User Interface must not accept an
+   unauthenticated, unauthorized subscription over an insecure
+   communication channel.
+
+   As an XML markup, all of the security considerations of RFC 3023 [3]
+   and RFC 3406 [6] MUST be met.  Pay particular attention to the
+   robustness requirements of parsing XML.
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 37]
+
+RFC 4730                          KPML                     November 2006
+
+
+   Key press information is potentially sensitive.  For example, it can
+   represent credit card, calling card, or other personal information.
+   Hijacking sessions allow unauthorized entities access to this
+   sensitive information.  Therefore, signaling SHOULD be secure, e.g.,
+   use of TLS and sips: SHOULD be used.  Moreover, the information
+   itself is sensitive so S/MIME or other appropriate mechanisms SHOULD
+   be used.
+
+   Subscriptions MUST be authenticated in some manner.  As required by
+   the core SIP [4] specification, all SIP implementations MUST support
+   digest authentication.  In addition, User Interfaces MUST implement
+   support for the sips: scheme and SIP over TLS.  Subscribers MUST
+   expect the User Interface to demand the use of an authentication
+   scheme.  If the local policy of a User Interface is to use
+   authentication or secure communication channels, the User Interface
+   MUST reject subscription requests that do not meet that policy.
+
+   User Interfaces MUST begin buffering User Input upon receipt of an
+   authenticated and accepted subscription.  This buffering is done on a
+   per-subscription basis.
+
+9.  Examples
+
+   This section is informative in nature.  If there is a discrepancy
+   between this section and the normative sections above, the normative
+   sections take precedence.
+
+9.1.  Monitoring for Octothorpe
+
+   A common need for pre-paid and personal assistant applications is to
+   monitor a conversation for a signal indicating a change in user focus
+   from the party they called through the application to the application
+   itself.  For example, if you call a party using a pre-paid calling
+   card, and the party you call redirects you to voice mail, digits you
+   press are for the voice mail system.  However, many applications have
+   a special key sequence, such as the octothorpe (#, or pound sign) or
+   *9, that terminate the called party session and shift the user's
+   focus to the application.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 38]
+
+RFC 4730                          KPML                     November 2006
+
+
+   Figure 16 shows the KPML for long octothorpe.
+
+   
+   
+     
+       L#
+     
+   
+
+                    Figure 16: Long Octothorpe Example
+
+   The regex value L indicates the following digit needs to be a long-
+   duration key press.
+
+9.2.  Dial String Collection
+
+   In this example, the User Interface collects a dial string.  The
+   application uses KPML to quickly determine when the user enters a
+   target number.  In addition, KPML indicates what type of number the
+   user entered.
+
+   
+   
+     
+       0
+       00
+       7[x][x][x]
+       9xxxxxxx
+       9401xxxxxxx
+       9xxxxxxxxxx
+       91xxxxxxxxxx
+       011x.
+     
+   
+
+                 Figure 17: Dial String KPML Example Code
+
+   Note the use of the "tag" attribute to indicate which regex matched
+   the dialed string.  The interesting case here is if the user entered
+   "94015551212".  This string matches both the "9401xxxxxxx" and
+
+
+
+Burger & Dolly              Standards Track                    [Page 39]
+
+RFC 4730                          KPML                     November 2006
+
+
+   "9xxxxxxxxxx" regular expressions.  Both expressions are the same
+   length.  Thus the KPML interpreter will pick the "9401xxxxxxx"
+   string, as it occurs first in document order.  Figure 18 shows the
+   response.
+
+   
+   
+
+                   Figure 18: Dial String KPML Response
+
+10.  Call Flow Examples
+
+10.1.  Supplemental Digits
+
+   This section gives a non-normative example of an application that
+   collects supplemental digits.  Supplemental digit collection is where
+   the network requests additional digits after the caller enters the
+   destination address.  A typical supplemental dial string is four
+   digits in length.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 40]
+
+RFC 4730                          KPML                     November 2006
+
+
+   Ingress Gateway      Application Server       Egress Gateway
+          |                      |                      |
+          |                      |                      |
+          |                      |                      |
+          |(1) INVITE            |                      |
+          |-------------------------------------------->|
+          |                      |                      |
+          |                      |                      |
+          |(2) 200 OK            |                      |
+          |<--------------------------------------------|
+          |                      |                      |
+          |                      |                      |
+          |(3) ACK               |                      |
+          |-------------------------------------------->|
+          |                      |                      |
+          |                      |                      |
+          |(4) SUBSCRIBE (one-shot)                     |
+          |<---------------------|                      |
+          |                      |                      |
+          |                      |                      |
+          |(5) 200 OK            |                      |
+          |--------------------->|                      |
+          |                      |                      |
+          |                      |                      |
+          |(6) NOTIFY            |                      |
+          |--------------------->|                      |
+          |                      |                      |
+          |                      |                      |
+          |(7) 200 OK            |                      |
+          |<---------------------|                      |
+          |                      |                      |
+          |                      |                      |
+          |(8)                   |                      |
+          |......................|                      |
+          |                      |                      |
+          |                      |                      |
+          |(9) NOTIFY (digits)   |                      |
+          |--------------------->|                      |
+          |                      |                      |
+          |                      |                      |
+          |(10) 200 OK           |                      |
+          |<---------------------|                      |
+          |                      |                      |
+          |                      |                      |
+          |                      |                      |
+          |                      |                      |
+
+                 Figure 19: Supplemental Digits Call Flow
+
+
+
+Burger & Dolly              Standards Track                    [Page 41]
+
+RFC 4730                          KPML                     November 2006
+
+
+   In messages (1-3), the ingress gateway establishes a dialog with an
+   egress gateway.  The application learns the dialog ID through out-of-
+   band mechanisms, such as the Dialog Package or being co-resident with
+   the egress gateway.  Part of the ACK message is below, to illustrate
+   the dialog identifiers.
+
+   ACK sip:gw@subA.example.com SIP/2.0
+   Via: ...
+   Max-Forwards: ...
+   Route: ...
+   From: ;tag=jfh21
+   To: ;tag=onjwe2
+   Call-ID: 12345592@subA.example.com
+   ...
+
+   In message (4), the application the requests that gateway collect a
+   string of four key presses.
+
+   SUBSCRIBE sip:gw@subA.example.com SIP/2.0
+   Via: SIP/2.0/TCP client.subB.example.com;branch=q4i9ufr4ui3
+   From: ;tag=567890
+   To: 
+   Call-ID: 12345601@subA.example.com
+   CSeq: 1 SUBSCRIBE
+   Contact: 
+   Max-Forwards: 70
+   Event: kpml ;remote-tag="sip:phn@example.com;tag=jfh21"
+               ;local-tag="sip:gw@subA.example.com;tag=onjwe2"
+               ;call-id="12345592@subA.example.com"
+   Expires: 7200
+   Accept: application/kpml-response+xml
+   Content-Type: application/kpml-request+xml
+   Content-Length: 292
+
+   
+   
+     
+       xxxx
+     
+   
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 42]
+
+RFC 4730                          KPML                     November 2006
+
+
+   Message (5) is the acknowledgement of the subscription request.
+
+   SIP/2.0 200 OK
+   Via: SIP/2.0/TCP subB.example.com;branch=q4i9ufr4ui3;
+        received=192.168.125.12
+   From: ;tag=567890
+   To: ;tag=1234567
+   Call-ID: 12345601@subA.example.com
+   CSeq: 1 SUBSCRIBE
+   Contact: 
+   Expires: 3600
+   Event: kpml
+
+   Message (6) is the immediate notification of the subscription.
+
+   NOTIFY sip:ap@client.subB.example.com SIP/2.0
+   Via: SIP/2.0/UDP subA.example.com;branch=gw27id4993
+   To: ;tag=567890
+   From: ;tag=1234567
+   Call-ID: 12345601@subA.example.com
+   CSeq: 1000 NOTIFY
+   Contact: 
+   Event: kpml
+   Subscription-State: active;expires=3599
+   Max-Forwards: 70
+   Content-Length: 0
+
+   Message (7) is the acknowledgement of the notification message.
+
+   SIP/2.0 200 OK
+   Via: SIP/2.0/TCP subA.example.com;branch=gw27id4993
+   To: ;tag=567890
+   From: ;tag=1234567
+   Call-ID: 12345601@subA.example.com
+   CSeq: 1000 NOTIFY
+
+   Some time elapses (8).
+
+   The user enters the input.  The device provides the notification of
+   the collected digits in message (9).  Since this was a one-shot
+   subscription, note the Subscription-State is "terminated".
+
+
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 43]
+
+RFC 4730                          KPML                     November 2006
+
+
+   NOTIFY sip:ap@client.subB.example.com SIP/2.0
+   Via: SIP/2.0/UDP subA.example.com;branch=gw27id4993
+   To: ;tag=567890
+   From: ;tag=1234567
+   Call-ID: 12345601@subA.example.com
+   CSeq: 1001 NOTIFY
+   Contact: 
+   Event: kpml
+   Subscription-State: terminated
+   Max-Forwards: 70
+   Content-Type: application/kpml-response+xml
+   Content-Length: 258
+
+   
+   
+
+   Message (10) is the acknowledgement of the notification.
+
+   SIP/2.0 200 OK
+   Via: SIP/2.0/TCP subA.example.com;branch=gw27id4993
+   To: ;tag=567890
+   From: ;tag=1234567
+   Call-ID: 12345601@subA.example.com
+   CSeq: 1001 NOTIFY
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 44]
+
+RFC 4730                          KPML                     November 2006
+
+
+10.2.  Multiple Applications
+
+   This section gives a non-normative example of multiple applications.
+   One application collects a destination number to call.  That
+   application then waits for a "long pound."  During the call, the call
+   goes to a personal assistant application, which interacts with the
+   user.  In addition, the personal assistant application looks for a
+   "short pound."
+
+   For clarity, we do not show the INVITE dialogs.
+
+   Gateway           Card Application      Personal Assistant
+      |                      |                      |
+      |                      |                      |
+      |                      |                      |
+      |(1) SUBSCRIBE (persistent)                   |
+      |<---------------------|                      |
+      |                      |                      |
+      |                      |                      |
+      |(2) 200 OK            |                      |
+      |--------------------->|                      |
+      |                      |                      |
+      |                      |                      |
+      |(3) NOTIFY            |                      |
+      |--------------------->|                      |
+      |                      |                      |
+      |                      |                      |
+      |(4) 200 OK            |                      |
+      |<---------------------|                      |
+      |                      |                      |
+      |                      |                      |
+      |(5)                   |                      |
+      |......................|                      |
+      |                      |                      |
+      |                      |                      |
+      |(6) NOTIFY (tag=card) |                      |
+      |--------------------->|                      |
+      |                      |                      |
+      |                      |                      |
+      |(7) 200 OK            |                      |
+      |<---------------------|                      |
+      |                      |                      |
+      |                      |                      |
+      |(8)                   |                      |
+      |......................|                      |
+      |                      |                      |
+      |                      |                      |
+      |(9) NOTIFY (tag=number)                      |
+
+
+
+Burger & Dolly              Standards Track                    [Page 45]
+
+RFC 4730                          KPML                     November 2006
+
+
+      |--------------------->|                      |
+      |                      |                      |
+      |                      |                      |
+      |(10) 200 OK           |                      |
+      |<---------------------|                      |
+      |                      |                      |
+      |                      |                      |
+      |(11) SUBSCRIBE        |                      |
+      |<--------------------------------------------|
+      |                      |                      |
+      |                      |                      |
+      |(12) 200 OK           |                      |
+      |-------------------------------------------->|
+      |                      |                      |
+      |                      |                      |
+      |(13) NOTIFY           |                      |
+      |-------------------------------------------->|
+      |                      |                      |
+      |                      |                      |
+      |(14) 200 OK           |                      |
+      |<--------------------------------------------|
+      |                      |                      |
+      |                      |                      |
+      |(15)                  |                      |
+      |.............................................|
+      |                      |                      |
+      |                      |                      |
+      |(16) NOTIFY (tag=number)                     |
+      |-------------------------------------------->|
+      |                      |                      |
+      |                      |                      |
+      |(17) 200 OK           |                      |
+      |<--------------------------------------------|
+      |                      |                      |
+      |                      |                      |
+      |(18)                  |                      |
+      |.............................................|
+      |                      |                      |
+      |                      |                      |
+      |(19) NOTIFY (tag=#)   |                      |
+      |-------------------------------------------->|
+      |                      |                      |
+      |                      |                      |
+      |(20) 200 OK           |                      |
+      |<--------------------------------------------|
+      |                      |                      |
+      |                      |                      |
+      |(21)                  |                      |
+
+
+
+Burger & Dolly              Standards Track                    [Page 46]
+
+RFC 4730                          KPML                     November 2006
+
+
+      |.............................................|
+      |                      |                      |
+      |                      |                      |
+      |(22) NOTIFY (tag=number)                     |
+      |-------------------------------------------->|
+      |                      |                      |
+      |                      |                      |
+      |(23) 200 OK           |                      |
+      |<--------------------------------------------|
+      |                      |                      |
+      |                      |                      |
+      |(24)                  |                      |
+      |.............................................|
+      |                      |                      |
+      |                      |                      |
+      |(25) NOTIFY (L#)      |                      |
+      |--------------------->|                      |
+      |                      |                      |
+      |                      |                      |
+      |(26) 200 OK           |                      |
+      |<---------------------|                      |
+      |                      |                      |
+      |                      |                      |
+      |                      |                      |
+      |                      |                      |
+
+                 Figure 27: Multiple Application Call Flow
+
+   Message (1) is the subscription request for the card number.
+
+   SUBSCRIBE sip:gw@subA.example.com SIP/2.0
+   Via: SIP/2.0/TCP client.subB.example.com;branch=3qo3j0ouq
+   From: ;tag=978675
+   To: 
+   Call-ID: 12345601@subA.example.com
+   CSeq: 20 SUBSCRIBE
+   Contact: 
+   Max-Forwards: 70
+   Event: kpml ;remote-tag=""
+               ;local-tag="sip:gw@subA.example.com;tag=oi43jfq"
+               ;call-id="12345598@subA.example.com"
+   Expires: 7200
+   Accept: application/kpml-response+xml
+   Content-Type: application/kpml-request+xml
+   Content-Length: 339
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 47]
+
+RFC 4730                          KPML                     November 2006
+
+
+   
+   
+     
+       x{16}
+       x{10}
+     
+   
+
+   Messages (2-4) are not shown, for brevity.  Message (6) is the
+   notification of the card number.
+
+   NOTIFY sip:ap@client.subB.example.com SIP/2.0
+   Via: SIP/2.0/UDP subA.example.com;branch=3qo3j0ouq
+   To: ;tag=978675
+   From: ;tag=9783453
+   Call-ID: 12345601@subA.example.com
+   CSeq: 3001 NOTIFY
+   Contact: 
+   Event: kpml
+   Subscription-State: active;expires=3442
+   Max-Forwards: 70
+   Content-Type: application/kpml-response+xml
+   Content-Length: 271
+
+   
+   
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 48]
+
+RFC 4730                          KPML                     November 2006
+
+
+   Message (7) is the acknowledgement of the notification.  Time goes by
+   in (8).  Message (9) is the notification of the dialed number.
+
+   NOTIFY sip:ap@client.subB.example.com SIP/2.0
+   Via: SIP/2.0/UDP subA.example.com;branch=3qo3j0ouq
+   To: ;tag=978675
+   From: ;tag=9783453
+   Call-ID: 12345601@subA.example.com
+   CSeq: 3001 NOTIFY
+   Contact: 
+   Event: kpml
+   Subscription-State: active;expires=3542
+   Max-Forwards: 70
+   Content-Type: application/kpml-response+xml
+   Content-Length: 278
+
+   
+   
+
+   Message (11) is the request for long-pound monitoring.
+
+   SUBSCRIBE sip:gw@subA.example.com SIP/2.0
+   Via: SIP/2.0/TCP client.subB.example.com;branch=3qo3j0ouq
+   From: ;tag=978675
+   To: 
+   Call-ID: 12345601@subA.example.com
+   CSeq: 21 SUBSCRIBE
+   Contact: 
+   Max-Forwards: 70
+   Event: kpml ;remote-tag=""
+               ;local-tag="sip:gw@subA.example.com;tag=oi43jfq"
+               ;call-id="12345598@subA.example.com"
+   Expires: 7200
+   Accept: application/kpml-response+xml
+   Content-Type: application/kpml-request+xml
+   Content-Length: 295
+
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 49]
+
+RFC 4730                          KPML                     November 2006
+
+
+   
+   
+     
+       L#
+     
+   
+
+   Message (13) is the request from the personal assistant application
+   for number and pound sign monitoring.
+
+   SUBSCRIBE sip:gw@subA.example.com SIP/2.0
+   Via: SIP/2.0/TCP pahost.example.com;branch=xzvsadf
+   From: ;tag=4rgj0f
+   To: 
+   Call-ID: 93845@pahost.example.com
+   CSeq: 21 SUBSCRIBE
+   Contact: 
+   Max-Forwards: 70
+   Event: kpml ;remote-tag=""
+               ;local-tag="sip:gw@subA.example.com;tag=oi43jfq"
+               ;call-id="12345598@subA.example.com"
+   Expires: 7200
+   Accept: application/kpml-response+xml
+   Content-Type: application/kpml-request+xml
+   Content-Length: 332
+
+   
+   
+     
+       x{10}
+       #
+     
+   
+
+
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 50]
+
+RFC 4730                          KPML                     November 2006
+
+
+   Message (18) is the notification of the number collected.
+
+   NOTIFY sip:pa@example.com SIP/2.0
+   Via: SIP/2.0/UDP subA.example.com;branch=xzvsadf
+   To: ;tag=4rgj0f
+   From: ;tag=9788823
+   Call-ID: 93845@pahost.example.com
+   CSeq: 3021 NOTIFY
+   Contact: 
+   Event: kpml
+   Subscription-State: active;expires=3540
+   Max-Forwards: 70
+   Content-Type: application/kpml-response+xml
+   Content-Length: 278
+
+   
+   
+
+   Message (21) is the notification of pound sign detected.
+
+   NOTIFY sip:pa@example.com SIP/2.0
+   Via: SIP/2.0/UDP subA.example.com;branch=xzvsadf
+   To: ;tag=4rgj0f
+   From: ;tag=9788823
+   Call-ID: 93845@pahost.example.com
+   CSeq: 3022 NOTIFY
+   Contact: 
+   Event: kpml
+   Subscription-State: active;expires=3540
+   Max-Forwards: 70
+   Content-Type: application/kpml-response+xml
+   Content-Length: 264
+
+   
+   
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 51]
+
+RFC 4730                          KPML                     November 2006
+
+
+   Message (27) is the notification of long pound to the card
+   application.
+
+   NOTIFY sip:ap@client.subB.example.com SIP/2.0
+   Via: SIP/2.0/UDP subA.example.com;branch=3qo3j0ouq
+   To: ;tag=978675
+   From: ;tag=9783453
+   Call-ID: 12345601@subA.example.com
+   CSeq: 3037 NOTIFY
+   Contact: 
+   Event: kpml
+   Subscription-State: active;expires=3216
+   Max-Forwards: 70
+   Content-Type: application/kpml-response+xml
+   Content-Length: 256
+
+   
+   
+
+11.  References
+
+11.1.  Normative References
+
+   [1]  Bradner, S., "Key words for use in RFCs to Indicate Requirement
+        Levels", BCP 14, RFC 2119, March 1997.
+
+   [2]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
+        Specifications: ABNF", RFC 4234, October 2005.
+
+   [3]  Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types",
+        RFC 3023, January 2001.
+
+   [4]  Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
+        Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP:
+        Session Initiation Protocol", RFC 3261, June 2002.
+
+   [5]  Roach, A., "Session Initiation Protocol (SIP)-Specific Event
+        Notification", RFC 3265, June 2002.
+
+   [6]  Daigle, L., van Gulik, D., Iannella, R., and P. Faltstrom,
+        "Uniform Resource Names (URN) Namespace Definition Mechanisms",
+        BCP 66, RFC 3406, October 2002.
+
+
+
+Burger & Dolly              Standards Track                    [Page 52]
+
+RFC 4730                          KPML                     November 2006
+
+
+   [7]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
+        January 2004.
+
+   [8]  Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML
+        Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502,
+        May 2001.
+
+11.2.  Informative References
+
+   [9]   Rosenberg, J., "Obtaining and Using Globally Routable User
+         Agent (UA) URIs (GRUU) in the  Session Initiation Protocol
+         (SIP)", Work in Progress, June 2006.
+
+   [10]  Schulzrinne, H. and S. Petrack, "RTP Payload for DTMF Digits,
+         Telephony Tones and Telephony Signals", RFC 2833, May 2000.
+
+   [11]  Andreasen, F. and B. Foster, "Media Gateway Control Protocol
+         (MGCP) Version 1.0", RFC 3435, January 2003.
+
+   [12]  Groves, C., Pantaleo, M., Anderson, T., and T. Taylor, "Gateway
+         Control Protocol Version 1", RFC 3525, June 2003.
+
+   [13]  Institute of Electrical and Electronics Engineers, "Information
+         Technology - Portable Operating System Interface (POSIX) - Part
+         1: Base Definitions, Chapter 9", IEEE Standard 1003.1,
+         June 2001.
+
+   [14]  Bray, T., Paoli, J., Sperberg-McQueen, C., and E. Maler,
+         "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C
+         REC REC-xml-20001006, October 2000.
+
+   [15]  Rosenberg, J., "A Framework for Application Interaction in the
+         Session Initiation Protocol  (SIP)", Work in Progress,
+         July 2005.
+
+   [16]  Burger, E., Van Dyke, J., and A. Spitzer, "Media Server Control
+         Markup Language (MSCML) and Protocol", RFC 4722, November 2006.
+
+   [17]  Rosenberg, J., Schulzrinne, H., and R. Mahy, "An INVITE-
+         Initiated Dialog Event Package for the Session Initiation
+         Protocol (SIP)", RFC 4235, November 2005.
+
+   [18]  Roach, A., Campbell, B., and J. Rosenberg, "A Session
+         Initiation Protocol (SIP) Event Notification Extension for
+         Resource Lists", RFC 4662, August 2006.
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 53]
+
+RFC 4730                          KPML                     November 2006
+
+
+Appendix A.  Contributors
+
+   Ophir Frieder of the Illinois Institute of Technology collaborated on
+   the development of the buffer algorithm.
+
+   Jeff Van Dyke worked enough hours and wrote enough text to be
+   considered an author under the old rules.
+
+   Robert Fairlie-Cuninghame, Cullen Jennings, Jonathan Rosenberg, and
+   we were the members of the Application Stimulus Signaling Design
+   Team.  All members of the team contributed to this work.  In
+   addition, Jonathan Rosenberg postulated DML in his "A Framework for
+   Stimulus Signaling in SIP Using Markup" draft.
+
+   This version of KPML has significant influence from MSCML [16], the
+   SnowShore Media Server Control Markup Language.  Jeff Van Dyke and
+   Andy Spitzer were the primary contributors to that effort.
+
+   Rohan Mahy did a significant reorganization of the content, as well
+   as providing considerable moral support in the production of this
+   document.
+
+   That said, any errors, misinterpretation, or fouls in this document
+   are our own.
+
+Appendix B.  Acknowledgements
+
+   Hal Purdy and Eric Cheung of AT&T Laboratories helped immensely
+   through many conversations and challenges.
+
+   Steve Fisher of AT&T Laboratories suggested the digit suppression
+   syntax and provided excellent review of the document.
+
+   Terence Lobo of SnowShore Networks made it all work.
+
+   Jerry Kamitses, Swati Dhuleshia, Shaun Bharrat, Sunil Menon, and
+   Bryan Hill helped with clarifying the buffer behavior and DRegex
+   syntax.
+
+   Silvano Brewster and Bill Fenner of AT&T Laboratories and Joe Zebarth
+   of Nortel helped considerably with making the text clear and DRegex
+   tight.
+
+   Bert Culpepper and Allison Mankin gave an early version of this
+   document a good scouring.
+
+   Scott Hollenbeck provided XML and MIME review.  Tim Bray pointed out
+   the general issue of UTF-8 versus UTF-16 with XML.
+
+
+
+Burger & Dolly              Standards Track                    [Page 54]
+
+RFC 4730                          KPML                     November 2006
+
+
+Authors' Addresses
+
+   Eric Burger
+   Cantata Technology, Inc.
+   18 Keewaydin Dr.
+   Salem, NH  03079
+   USA
+
+   EMail: eburger@cantata.com
+
+
+   Martin Dolly
+   AT&T Labs
+
+   EMail: mdolly@att.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 55]
+
+RFC 4730                          KPML                     November 2006
+
+
+Full Copyright Statement
+
+   Copyright (C) The IETF Trust (2006).
+
+   This document is subject to the rights, licenses and restrictions
+   contained in BCP 78, and except as set forth therein, the authors
+   retain all their rights.
+
+   This document and the information contained herein are provided on an
+   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
+   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST,
+   AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
+   THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
+   IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+   PURPOSE.
+
+Intellectual Property
+
+   The IETF takes no position regarding the validity or scope of any
+   Intellectual Property Rights or other rights that might be claimed to
+   pertain to the implementation or use of the technology described in
+   this document or the extent to which any license under such rights
+   might or might not be available; nor does it represent that it has
+   made any independent effort to identify any such rights.  Information
+   on the procedures with respect to rights in RFC documents can be
+   found in BCP 78 and BCP 79.
+
+   Copies of IPR disclosures made to the IETF Secretariat and any
+   assurances of licenses to be made available, or the result of an
+   attempt made to obtain a general license or permission for the use of
+   such proprietary rights by implementers or users of this
+   specification can be obtained from the IETF on-line IPR repository at
+   http://www.ietf.org/ipr.
+
+   The IETF invites any interested party to bring to its attention any
+   copyrights, patents or patent applications, or other proprietary
+   rights that may cover technology that may be required to implement
+   this standard.  Please address the information to the IETF at
+   ietf-ipr@ietf.org.
+
+Acknowledgement
+
+   Funding for the RFC Editor function is currently provided by the
+   Internet Society.
+
+
+
+
+
+
+Burger & Dolly              Standards Track                    [Page 56]
+
-- 
cgit v1.2.3