Keypad Stimulus Protocol (KPML)SnowShore Networks, Inc.285 Billerica Rd.ChelmsfordMA01824-4120USAe.burger@ieee.orgAT&T Labsmdolly@att.com
Transport
SIPPINGSIPMedia Services
The Key Press Stimulus Protocol uses the SIP SUBSCRIBE/NOTIFY mechanism and Keypad Markup Language (KPML) to provide instructions to SIP User Agents for the reporting of user key presses.
RFC2119 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.
In the narrative discussion, the "user device" is a User Agent that will report stimulus. it could be, for example, a SIP phone, edge media processor, or media gateway. An "application" is a User Agent requesting the user device to report stimulus. The "user" is an entity that stimulates the user device. In English, the user device is a phone, the application is an application server or proxy server, and the user presses keys to generate stimulus.
This document describes the Key Press Stimulus Protocol. The Key Press Stimulus Protocol exchanges messages using the SUBSCIBE and NOTIFY methods of SIP with message bodies formed from the Keypad Markup Language, KPML. KPML is a markup that enables "dumb phones" to report user key-press events. Colloquially, this mechanism provides for "digit reporting" or "DTMF reporting."
A goal of KPML is to fit in an extremely small memory and processing footprint. Note KPML has a corresponding lack of functionality. For those applications that require more functionality, please refer to VoiceXML and MSCML.We strongly discourage the use of non-validating XML parsers, as one can expect problems with future versions of KPML.
The name of the markup, KPML, reflects its legacy support role. The public switched telephony network (PSTN) accomplished end-to-end signaling by transporting Dual-Tone, Multi-Frequency (DTMF) tones in the bearer channel. This is in-band signaling.
From the point of view of an application being signaled, what is important is the fact the stimulus occurred, not the tones used to transport the stimulus. For example, an application may ask the caller to press the "1" key. What the application cares about is the key press, not that there were two cosine waves of 697 Hz and 1209 Hz transmitted.
A SIP-signaled network transports end-to-end signaling with RFC2833 packets. In RFC2833, the signaling application inserts RFC2833 named signal packets as well as or instead of generating tones in the media path. The receiving application gets the signal information, which is what it wanted in the first place.
RFC2833 correlates the time the end user pressed a digit with the user's media. However, out-of-band signaling methods, as are appropriate for user device to application signaling, do not need millisecond accuracy. On the other hand, they do need reliability, which RFC2833 does not provide.
An interested application could request notifications of every key press. However, many of the use cases for such signaling has the application interested in only one or a few keystrokes. Thus we need a mechanism for specifying to the user device what stimulus the application would like notification of.
There are two usage models for the protocol. Functionally, they are both equivalent. However, it is useful to understand the use cases.The first model is that of a SIP User Agent (UA) that directly interacts, on a given dialog, with the end device. shows a two-party SIP dialog. In this scenario, the SIP UA requests the End Point to report on key press events that would normally emanate from End Point port B. This could represent, for example, a toll by-pass scenario where the End Point is an ingress gateway and the SIP UA is an egress gateway.In this case, the requesting User Agent requests digit notification on the same dialog established for the call, between SIP ports A and X.The second model is that of a third-party application that is interested in entered key presses. shows an established two-party SIP dialog between the End Point and the SIP UA. The requesting application addresses the particular media stream by referencing the established dialog identifier referring to the dialog between SIP ports A and X.The third model is that of a media proxy. A media proxy is a media relay in the terminology of RFC1889. However, in addition to the RTP forwarding capability of a RFC1889 media relay, the media proxy can also do light media processing, such as tone detection, tone transcoding (tones to RFC2833, and so on.The Requesting Application uses dialog identifiers to identify the stream to monitor. The default is to monitor the media entering the End Point. For example, if the Requesting Application in uses the dialog represented by SIP ports V-C, then the media coming from SIP UAa RTP port W gets monitored. Likewise, the dialog represented by A-X directs the End Point to monitor the media coming from SIP UAb RTP Port Y.The default leg to monitor is the leg represented by the local tag of the SIP dialog at the monitoring End Point. A requesting application MAY request monitoring of the leg represented by the remote tag of the SIP dialog at the monitoring End Point.Not all End Point devices are able to monitor the remote media stream. However, the End Point MUST be able to report on local (End Point-generated) key press events.If the requesting application wishes to monitor both legs at a given End Point, the application will establish two subscriptions, one for each leg. describes how to specify to the End Point which leg of the dialog to monitor.The key press stimulus protocol uses explicit subscription requests and notification requests, using the semantics of SUBSCRIBE/NOTIFY.Following the semantics of SUBSCRIBE, if the user device receives a second subscription on the same dialog, the user device MUST terminate the existing KPML request (if any) and replace it with the new request.An application may register multiple digit patterns in a single KPML request.If the user device supports multiple, simultaneous KPML requests, the application registers the separate requests either in a new SUBSCRIBE-initiated dialog or on an existing SUBSCRIBE-initiated dialog with a new event id tag.If the user device does not support multiple, simultaneous KPML requests, it responds with an error response code. See for more information.A KPML request can be persistent or one-shot. Persistent requests are active until either the dialog terminates, including normal subscription expiration, the client replaces them, the client deletes them by sending a null document on the dialog, or the client deletes the subscription by sending a SUBCRIBE with an expires of zero (0).Standard SUBSCRIBE processing dictates the end point sends a NOTIFY response if it receives a SUBSCRIBE with an expires of zero. One-shot requests terminate themselves once a match occurs. The "persist" KPML element specifies whether the subscription remains registered for the duration specified in the SUBSCRIBE message or if it automatically terminates after a pattern matches.
KPML requests route to the user device using standard SIP request routing. A KPML request identifies the leg in question in one of two ways. The first method is to send the request on an existing, INVITE-initiated dialog. The second method is to explicitly identify the call leg by its dialog identifiers.
Response messages are KPML documents (messages). If the user device matched a digit map, the response indicates the digits detected and whether the user device suppressed digits. If the user device had an error, such as a timeout, it will indicate that instead.
The Key Press Stimulus Protocol uses the SIPSUBSCRIBE/NOTIFY mechanism.The registration of a digit map is simply setting a digit event notification filter. When the device detects the digits, it sends an event notification to the application.The following sub-sections are the formal specification of the KPML SIP-specific event notification package.The name for the Key Press Stimulus Protocol package is "kpml".The "leg" parameter identifies the call leg being monitored.If the "leg" parameter is not present, the SUBSCRIBE MUST be on an established INVITE-initiated SIP dialog. In this case, the leg the end device monitors is the call leg associated with the established dialog. If there is no corresponding dialog or call leg, the end device will send a 481 result code in a KPML notification.
NOTE: The SUBSCRIBE may succeed, resulting in a SIP 200 OK. However, the "current state" will be the KPML 481 result, and the subscription state will be "terminated."SIP identifies call legs by their dialog identifier. The dialog identifier is the remote-tag, local-tag, and Call-ID entities. To identify a specific dialog, all three of these parameters MUST be present. Usually, the local-tag is the To: entity with the To tag, the remote-tag is the From: entity including tag, and the call-id matches the Call-ID. Although semantically different, the important entities are the To: and From: tags.Note 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 End Point 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 <stream> tag. The only content defined today is the <reverse/> tag.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.The BNF for these parameters is as follows. The definitions of callid, token, EQUAL, SWS, and DQUOTE are from RFC3261.
call-id = "call-id" EQUAL DQUOTE callid DQUOTE
from-tag = "from-tag" EQUAL token
to-tag = "to-tag" EQUAL token
The call-id parameter is a quoted string. This is because the BNF for word (which is used by callid) allows for characters not allowed within token. One usually just copies these elements from the Call-Id, to, and from fields of the SIP INVITE.One can use any method of determining the dialog identifier. One method available, particularly for third-party applications, is the SIP Dialog Package.Key press filtering requests use KPML, as described in . The MIME type for KPML is application/kpml+xml.Because of the potentially sensitive nature of the information reported by KPML, subscribers SHOULD use sips: and SHOULD consider the use of S/MIME on the content.Subscribers MUST be prepared for the notifier to insist on authentication at a minimum and encryption as a likelihood.The subscription lifetime should be longer than the expected call time. The default subscription lifetime (Expires value) MUST be 7200 seconds. This two-hour subscription time is entirely arbitrary. Please contact the editor if you have a better suggestion, and why.Subscribers MUST be able to handle the end device returning an Expires value smaller than the requested value. Per RFC3265, the subscription duration is the value returned by the end device in the 200 OK response Expires entity.The key press notification uses KPML, as described in . The MIME type for KPML is application/kpml+xml. The default MIME type for the kpml event package is application/kpml+xml.If the requestor is not using a secure transport protocol such as TLS (e.g., by using a sips: URI), the end device SHOULD use S/MIME to protect the user information in responses.The user information transported by KPML is potentially sensitive. For example, it could include calling card or credit card numbers. Thus the first action of the end device (notifier) SHOULD be to authenticate the requesting party.End devices MUST support digest authentication at a minimum.End devices MUST support the sips: scheme and TLS.Upon authenticating the requesting party, the end device determines if the requesting party has authorization to monitor the user's key presses. Determining authorization policies and procedures is beyond the scope of this specification.
NOTE: While it would be good to require both authorization and user notification for KPML, some uses, such as lawful intercept pen registers, have very strict authorization requirements yet have a requirement of no user notification. Conversely, pre-paid applications running on a private network may have no authorization requirements and already have implicit user acceptance of key press monitoring. Thus we cannot give any guidelines here.After authorizing the request (RECOMMENDED), the end device checks to see if the request is to terminate a subscription. If the request will terminate the subscription, the end device does the appropriate processing, including the procedures described in .If the request has no KPML body, than 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, such as TLS. The end device follows the procedures described in .If the SUBSCRIBE request arrived on an INVITE-initiated dialog, and there is no "leg" parameter to the kpml subscription, then the KPML document acts upon the call legs created by the INVITE-initiated dialog.If the SUBSCRIBE request has a "leg" parameter to the kpml subscription, then the KPML document acts upon the call leg referred to by the "leg" parameter. If appropriate, the end device SHOULD validate the requestor has authorization to monitor a given leg.If the SUBSCRIBE request has a "leg" parameter to the kpml subscription, but the referenced leg does not exist, the end device follows the procedures in Note the end device MUST issue a 200 OK before issuing the NOTIFY, as the SUBSCRIBE itself is well-formed.If the request has a KPML body, the end device parses the KPML document. The end device SHOULD validate the XML document against the schema presented in . If the document is not valid, the end device performs the procedures described in . If there is a loaded KPML document on the dialog (and given event id, if present), the end device unloads the document.If the KPML document is valid, and the end device is capable of performing the monitoring, the end device performs the filtering specified by the KPML document. See for the specification of KPML.The end device (notifier in SUBSCRIBE/NOTIFY parlance) generates NOTIFY requests based on the requirements of RFC3265. Specifically, unless a SUBSCRIBE request is not valid, all SUBSCRIBE requests will result in an immediate NOTIFY.The KPML payload distinguishes between a NOTIFY that RFC3265 mandates and a NOTIFY informing of key presses. If there are no digits quarantined at the time of the SUBSCRIBE (see below) or the quarantined digits do not match the new KPML document, then the immediate NOTIFY MUST NOT contain a KPML body. If end device has digits quarantined that result in a digit match using the new KPML document, then the NOTIFY MUST return the appropriate KPML document.During the subscription lifetime, the end device may detect a key press stimulus that triggers a KPML event. In this case, the end device (notifier) MUST return the appropriate KPML document.Once a user starts to enter digits, it is highly likely they will enter all of the digits of interest within a specific time period. There is a temporal locality of reference for key presses. It is possible for users to accidentally press a key, however. Moreover, users may start pressing a key and then be lost as to what to do next. For applications to handle this situation, KPML allows applications to request notification if the user starts to enter digits but then stops before a digit map matches.Once the end point detects a key press that matches the first character of a digit map, the end point starts the interdigit timer specified in the <pattern> tag. Every subsequent key press detected restarts the interdigit timer. If the interdigit timer expires, the end point generates a KPML report with the KPML status code 423, Timer Expired. The report also includes the digits collected up to the time the timer expired. This could be the null string. After sending the NOTIFY, the end point will resume quarantining additional detected digits.Applications may have different requirements for the interdigit timer. For example, applications targeted to user populations that tend to key in information slowly may require longer interdigit timers. The specification of the interdigit timer is in milliseconds. The default value is 4000, for 4 seconds. A value of zero indicates disabling the interdigit timer. The End Device MUST round up the requested interdigit timer to the nearest time increment it is capable of detecting.It is possible for a 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 request, and there are quarantined digits, then the end device attempts to process the quarantined digits against the document. If there is a match, the end device generates 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 subscription was on a SUBSCRIBE-initiated dialog, and there are no more active event id's associated with the dialog, then the end point MUST consider the dialog terminated. If the subscription was on an INVITE-initiated dialog, then the end point MAY release KPML-specific resources related to the dialog, but it MUST NOT alter the state of the INVITE-initiated dialog.If the requesting party issues a SUBSCRIBE with an expires of zero and no KPML body or the expires timer on the SUBSCRIBE-initiated dialog fires at the end device (notifier), then the end device issues a KPML report with the KPML status code 487, Subscription Expired. The report also includes the digits 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. Also, note that the digits in this case cannot match a digit map. If they did, the end device would have generated a KPML match report if they did.Again, per the mechanisms of RFC3265, the end device will terminate the SIP SUBSCRIBE dialog. The end device 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". If the subscription was on a SUBSCRIBE-initiated dialog, then the end point MUST consider the dialog terminated. If the subscription was on an INVITE-initiated dialog, then the end point MAY release KPML-specific resources related to the dialog, but it MUST NOT alter the state of the INVITE-initiated dialog.If a SUBSCRIBE request references a dialog that is not present at the endpoint, usually by specifying a dialog identifier through the leg parameter to the kpml event package, the end point generates a KPML report with the KPML status code 481, Dialog Not Found. The end device terminates the subscription by setting the subscription state to "terminated". If the subscription was on a SUBSCRIBE-initiated dialog, and there are no more active event id's associated with the dialog, then the end point MUST consider the dialog terminated. If the subscription was on an INVITE-initiated dialog, then the end point MAY release KPML-specific resources related to the dialog, but it MUST NOT alter the state of the INVITE-initiated dialog.IMPORTANT: The end device can invoke this procedure if the dialog underlying a subscription terminates. For example, a SUBSCRIBE-initiated dialog subscribes to the state of a different dialog (call) via the leg kpml parameter. That different call may terminate before the SUBSCRIBE-initiated dialog terminates. In this case, the end device MUST terminate the SUBSCRIBE-initiated dialog. This ensures reauthorization (if necessary) for attaching to subsequent call legs.If the KPML document is not valid, the end device generates a KPML report with the KPML status code 501, Bad Document. The end device terminates the subscription by setting the subscription state to "terminated". If the subscription was on a SUBSCRIBE-initiated dialog, and there are no more active event id's associated with the dialog, then the end point MUST consider the dialog terminated. If the subscription was on an INVITE-initiated dialog, then the end point MAY release KPML-specific resources related to the dialog, but it MUST NOT alter the state of the INVITE-initiated dialog.A one-shot kpml subscription is one that the KPML document does not mark as persistent. If the end device detects a key press stimulus that triggers a one-shot KPML event, then the end device (notifier) MUST set the "Subscription-State" in the NOTIFY message to "terminated". At this point the end device MUST consider the subscription destroyed. The end device MUST quarantine digits per the controls specified in .For persistent kpml subscriptions, the KPML document remains active for the lifetime of the subscription. If there is no KPML body, it means the SUBSCRIBE was successful. This establishes the dialog if there are no quarantined digits 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 4xx, then an error occurred with digit collection. The most likely cause is a timeout condition.If there is a KPML document, and the KPML status code is 5xx, then an error occurred with the subscription. See for more on the meaning of error codes.The subscriber MUST be mindful of the subscription state. The end device may terminate the subscription at any time.The SUBSCRIBE behavior described in ensures that it is only possible to have a subscription where there is an active (e.g., voice) dialog. Thus the case of multiple subscription installation cannot occur.The end device MUST NOT generate messages faster than 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 <regex> is "x".Because there is no meaningful metric for throttling requests. In addition, the end device MUST reliably deliver notifications. Thus the end device SHOULD send NOTIFY messages over a congestion-controlled transport, such as TCP or SCTP.End devices MUST at a minimum implement SIP over TCP.Not applicable.The Key Press Stimulus Protocol exchanges KPML messages. There are two, mutually exclusive elements to KPML: the request and response.A KPML request document (message) contains a <request> entity containing a <pattern> tag with a series of <regex> tags. The <regex> element specifies a digit pattern for the device to report on. describes the DRegex, or digit regular expression, language.Some devices can buffer entered digits. Subsequent KPML requests first apply their patterns against the buffered digits. Some applications use modal interfaces where the first few key presses determine what the following digits 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.The protocol provides a <flush> tag in the <pattern> element. The default is not to flush digits. Flushing digits means the user device flushes any buffered digits. This has the effect of ignoring digits entered before the KPML request. To flush digits, the KPML includes <flush>yes</flush>.The End Device MUST be able to receive <flush>no</flush>. This directive is effectively a no-op.Other string values for <flush> may be defined in the future. If the End Device receives a string it does not understand, it MUST treat the string as a no-op.If the user presses a key not matched by the <regex> tags, the user device MUST discard the key press from consideration against the current or future KPML messages. However, as described above, once there is a match, the user device quarantines any key presses the user entered subsequent to the match.NOTE: This behavior allows for applications to only receive digits that interest them. For example, a pre-paid application only wishes to monitor for a long pound. If the user enters other digits, presumably for other systems, the pre-paid applicationd does not want notification of those digits. This feature is fundamentally different than the behavior of every system receiving every digit that TDM-based equipment provides.The end device MAY support an inter-digit timeout value. This is the amount of time the end device 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 <pattern> tag. The default is 4000 milliseconds. If the end device does not support the specification of an inter-digit timeout, the end device MUST silently ignore the specification. If the end device supports the specification of an inter-digit timeout, but not to the granularity specified by the value presented, the end device MUST round up the requested value to the closest value it can support.KPML messages are independent. Thus it is not possible for the current document to know if a following document will enable barging or want the digits flushed. Therefore, the user device MUST quarantine all digits detected between the time of the report and the interpretation of the next script, if any. If the next script indicates a buffer flush, then the interpreter MUST flush all collected digits from consideration from KPML documents received on that dialog with the given event id. If the next script does not indicate flushing the quarantine digits, then the interpreter MUST apply the collected digits (if possible) against the digit maps presented by the script's <regex> tags. If there is a match, the interpreter MUST follow the procedures in If there is no match, the interpreter MUST flush all of the collected digits.Unless there is a suppress indicator in the digit map, it is not possible to know if the signaled digits are for local KPML processing or for other recipients of the media stream. Thus, in the absence of a digit suppression indicator, the user device transmits the digits to the far end in real time, using either RFC2833, generating the appropriate tones, or both.The section Digit Suppression describes the operation of the suppress indicator.The pattern matching logic works as follows. KPML endpoints MUST follow the logic presented in this section so that multiple implementations will perform deterministically on the same KPML document given the same key press input.The pattern match algorithm matches the longest regular expression. This is the same mode as H.248.1 and not the mode presented by MGCP. The pattern match algorithm choice has an impact on determining when a pattern matches. Consider the following KPML document.0011
]]>In , 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}
]]> is a typical NANP 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). From a user's perspective, they do 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. Typically, it is the pound key (#). Now, consider the following snippet.x{7}#
x{10}#
]]>The problem with the approach in is that the digit collector will still look for a digit after the "#" in the seven-digit case. Worse yet, the "#" will appear in the returned dial string.The approach used in KPML is to have an explicit "Enter Key", as shown in the following snippet.xxxxxxxxxxxxxxxxx
]]>In the enterkey parameter to the <pattern> 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.To address the various key press collection scenarios, we define three timers. The timers are the critical timer (criticaltimer), the inter-digit timer (interdigittimer), and the extra digit timer (extradigittimer). The critical timer is the time to wait for another digit if the collected digits can match a pattern. The extra timer is the time to wait after the longest match has occurred (presumably for the return key). The inter-digit timer inter-digit timer is the time to wait between digits in all other cases. Note there is no start timer, as that concept does not apply in the KPML context.All of these timers are parameters to the <pattern> tag.Some patterns look for long duration key presses. For example, some applications look for long "#" or long "*".KPML uses the "L" modifier to <regex> characters to indicate long key presses. The following KPML document looks for long pound.L#
]]>The request can specify what constitutes "long" by setting the long attribute to the <pattern>. This attribute is an integer representing the number of milliseconds. If the user presses a key for longer than longtimer milliseconds, the Long modifier is true.
NOTE: It is a local matter at the end device to consider multiple presses of the same key during the longtimer period to be equivalent to the Long version of that key. This is to support end devices that do not generate continuous key press tones.Under basic operation, a KPML endpoint will transmit in-band tones (RFC2833 or actual tone) in parallel with digit reporting.NOTE: If KPML did not have this behavior, then a user device 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 because they accessed an IVR system that looks for "*"? In this case, the "*" would get held by the user device, 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 device 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 effect a transfer.For those situations, KPML adds a digit suppression tag, "pre", to the <regex> tag. There MUST NOT be more than one <pre> in any given <regex>.If there is only a single <pattern> and a single <regex>, the suppression processing is straightforward. The end-point passes digits until the stream matches the regular expression pre. At that point, the endpoint will continue collecting digits, but will suppress the generation or pass-through of any in-band digits.If the endpoint suppressed digits, it MUST indicate this by including the attribute "suppressed" with a value of "yes" in the digit report.Clearly, if the end device is processing the KPML document against quarantined digits, it is too late to suppress digits, as the end device has long sent the digits. This is a situation where there is a <pre> specification, but the "suppressed" attribute is not "yes" in the digit report.A KPML endpoint MAY perform digit suppression. If it is not capable of digit suppression, it ignores the digit suppression attribute and will never send a suppressed indication in the digit report. In this case, it will match concatenated patterns of pre+value.At some point in time, the endpoint will collect enough digits to the point it hits a <pre> pattern. The interdigittimer attribute indicates how long to wait once the user enters digits before reporting a time-out error. If the interdigittimer expires, the endpoint MUST issue a time-out report, transmit the suppressed digits on the media stream, and stop suppressing digit transmission.Once the end device detects a match and it sends a NOTIFY request to report the digit string, the end device MUST stop digit suppression. Clearly, if subsequent digits match another <pre> expression, then the end device MUST start digit suppression.After digit suppression begins, it may become clear that a match will not occur. For example, take the expression "<regex> <pre>*8</pre>xxx[2-9]xxxxxx</regex>". At the point the endpoint receives "*8", it will stop forwarding digits. 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 endpoint to have a sensible inter-digit timer. This is because an errant dot (".") may suppress digit sending forever. See for setting the inter-digit timer.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 endpoint will hold digits, which will have obvious user interface issues in the case of a failure.The KPML document specifies if the patterns are to be persistent by setting the persistent attribute to the <pattern> tag to "true". Otherwise, the request will be a one-shot subscription. If the end device does not support persistent subscriptions, it returns a KPML document with the KPML result code set to 531. If there are digits in the quarantine buffer and the digits match an expression in the KPML document, the end device prepares the appropriate KPML document.Some end devices 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 <regex> tag. The "tag" is an opaque string that the end device sends back in the notification report upon a match in the digit map. In the case of multiple matches, the end device MUST chose the longest match in the KPML document. If multiple matches match the same length, the end device MUST chose the first expression listed in the subscription KPML document based on KPML document order.If the end device does not support multiple regular expressions in a pattern request, the end device MUST return a KPML document with the KPML result code set to 532.By default, the end device monitors key presses emanating from the device. Given a dialog identifier of Call-ID, local-tag, and remote-tag, the end device 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 <stream> element to the >request> tag specifies which stream to monitor. The only legal value is "reverse", which means to monitor the stream associated with the remote-tag. The end point 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.Some end devices may support multiple key press event notification subscriptions at the same time. In this situation, the end device 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. In the body of the SUBSCRIBE is a leg parameter that indicates which leg to monitor. describes the dialog addressing mechanism in detail.If the end device does not support multiple, simultaneous subscriptions, the end device MUST return a KPML document with the KPML result code set to 533 on the dialog that requested the second subscription. The end device MUST NOT modify the state of the first subscription on the account of the second subscription attempt.
When the user enters key press(es) that match a <regex> tag, the end device 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 end device 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. If your goal is to build an IVR session, we strongly suggest you investigate more appropriate technologies such as VoiceXML or MSCML.KPML reports have two mandatory attributes, code and text. These attributes describe the state of the KPML interpreter on the end device. Note the KPML 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 case, the NOTIFY would include the KPML failure 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 end device will most likely set the Subscription-Sate to terminated. This lets the SIP machinery know the subscription is no longer active.If a pattern matches, the end device 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 end device 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 in 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 <response> tag.There are a few circumstances in which the end device will emit a no match report. They are an immediate NOTIFY in response to SUBSCRIBE request (no digits detected yet), a request for service not supported by end device, or a failure of a digit map to match a string (timeout).The NOTIFY in response to a SUBSCRIBE request has no KPML if there are no matching quarantined digits. An example of this is in .If there are quarantined 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.
From:
Call-Id: 439hu409h4h09903fj0ioij
Subscription-State: active; expires=7200
CSeq: 49851 NOTIFY
Event: kpml
]]>The Digit REGular EXpression (DRegex) syntax follows the Unix egrep and Java Regular Expression syntax.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 describe the use of DRegex in KPML.EntityMatchesdigitdigit 0-9 and A-D[digit selector]Any digit in selector[^digit selector]Any digit NOT in selector[digit-range]Any digit in rangexAny digit 0-9.Zero or more repetitions of previous pattern|Alternation{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 patternLdigitMatch the digit if it is "long"ExampleDescription1Matches the digit 1[179]Matches 1, 7, or 9[^01]Matches 2, 3, 4, 5, 6, 7, 8, 9[2-9]Matches 2, 3, 4, 5, 6, 7, 8, 9xAny single digit2|3Matches 2 or 3; same as [23]00|011Matches the string 00 or 0110.Zero or more occurrences of 0[2-9].Zero or more occurrences of 2-9011x{7,15}011 followed by seven to fifteen digitsL*Long star
The following syntax in uses the XML Schema.
IETF Keypad Markup Language
]]>KPML failure 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.CodeText200Success402User Terminated Without Match423Timer Expired481Dialog (call leg) Not Found487Subscription Expired501Bad Document531Persistent Subscriptions Not Supported532Multiple or Alternate Regular Expressions Not Supported533Multiple Subscriptions on a Call Leg Not Supportedapplicationkpml+xmlnonecharsetThis parameter has identical semantics to the charset parameter of the "application/xml" media type as specified in XML Media Types.
Encoding considerations: See RFC3023.
Interoperability considerations: See RFC2023 and this document.
Published specification: This document.
Applications which use this media type: Session-oriented applications that have primitive user interfaces.
Intended usage: COMMON
URI: urn:ietf:params:xml:ns:kpmlRegistrant Contact: Eric Burger <eburger@ietf.org>XML:
Key Press Markup Language
]]>Please register the XML Schema for KPML as referenced in .As an XML markup, all of the security considerations of RFC3023 and RFC3406 apply. Pay particular attention to the robustness requirements of parsing XML.Key press information is potentially sensitive. 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. Thus if TLS is not used, S/MIME or other appropriate mechanism SHOULD be used.End devices implementing this specification MUST implement TLS and SHOULD implement S/MIME at a minimum.This section is informative in nature. If there is a discrepancy between this section and the normative sections above, the normative sections take precedence.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 leg and shift the user's focus to the application. shows the KPML for long octothorpe. Note that the href is really on one line, but divided for clarity.L#
]]>The regex value L indicates the following digit needs to be a long-duration key press.In this example, the user device 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.000
7[x][x][x]9xxxxxxx9401xxxxxxx9xxxxxxxxxx91xxxxxxxxxx011x.
]]>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 "9xxxxxxxxxx" regular expressions. By following the rules described in , the KPML interpreter will pick the "9401xxxxxxx" string, as it occurs first in document order (both expressions match the same length). shows the response.
]]>
This is an example where one would probably be better off using a full scripting language such as VoiceXML or MSCML or a device control language such as H.248.1.
In this example, an application requests the user device to send the user's signaling directly to the platform in HTTP, rather than monitoring the entire RTP stream. shows a voice mail menu, where presumably the application played a "Press K to keep the message, R to replay the message, and D to delete the message" prompt. In addition, the application does not want the user to be able to barge the prompt.
yes573
]]>
NOTE: This usage of KPML is clearly inferior to using a device control protocol like H.248.1. From the application's point of view, it has to do the low-level prompt-collect logic. Granted, it is relatively easy to change the key mappings for a given menu. However, often more of the call flow than a given menu mapping gets changed. Thus there would be little value in such a mapping to KPML. We STRONGLY suggest using a real scripting language such as VoiceXML or MSCML for this purpose.
This section describes a successful subscription and notification from an Application with an End Device ("User A") in an INVITE-Initiated dialog. Note the Application can be a Record-Route Proxy, a B2BUA, or another end device.|
| 100 TRYING F2 |
|<---------------|
| 180 F3 |
|<---------------|
| 200 OK F4 |
|<---------------|
| ACK F5 |
|--------------->|
| Media Session |
|<==============>|
| SUBSCRIBE F6 | Application Subscribes to "***" from User A
|<---------------|
| 200 OK F7 |
|--------------->|
| NOTIFY F8 | Immediate Notify indicating monitoring
|--------------->|
| 200 OK F9 |
|<---------------|
| . |
| : |
| NOTIFY F10 |
|--------------->| Notification of detection of "***"
| 200 OK F11 |
|<---------------|
| |
]]>Connection setup between User A and an Application subscribing to a DTMF event of "***" at User A. Application
INVITE sip:UserB@subB.example.com SIP/2.0
Via: SIP/2.0/UDP client.subA.example.com:5060;branch=z9hG4bK74
Max-Forwards: 70
From: ;tag=1234567
To:
Call-ID: 12345601@subA.example.com
CSeq: 1 INVITE
Contact:
Route:
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, SUBCRIBE, NOTIFY
Allow-Events: kpml
Supported: replaces
Content-Type: application/sdp
Content-Length: ...
v=0
o=UserA 2890844526 2890844526 IN IP4 client.subA.example.com
s=Session SDP
c=IN IP4 client.subA.example.com
t=3034423619 0
m=audio 49170 RTP/AVP 0
a=rtpmap:0 PCMU/8000
F2 100 Trying Application --> User A
SIP/2.0 100 Trying
Via: SIP/2.0/UDP client.subA.example.com:5060;branch=z9hG4bK74
;received=192.168.12.22
From: ;tag=1234567
To:
Call-ID: 12345601@subA.example.com
CSeq: 1 INVITE
Content-Length: 0
F3 180 Ringing Application --> User A
SIP/2.0 180 Ringing
Via: SIP/2.0/UDP client.subA.example.com:5060;branch=z9hG4bK74
;received=192.168.12.22
Record-Route:
From: ;tag=1234567
To: ;tag=567890
Call-ID: 12345601@subA.example.com
CSeq: 1 INVITE
Contact:
Content Length: 0
F4 200 OK Application --> User A
SIP/2.0 200 OK
Via: SIP/2.0/UDP client.subA.example.com:5060;branch=z9hG4bK74
;received=192.168.12.22
Record-Route:
From: ;tag=1234567
To: ;tag=567890
Call-ID: 12345601@subA.example.com
CSeq: 1 INVITE
Contact:
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, SUBSCRIBE, NOTIFY
Supported: replaces
Content-Type: application/sdp
Content-Length: ...
v=0
o=UserB 2890844527 2890844527 IN IP4 client.subB.example.com
s=Session SDP
c=IN IP4 client.subB.example.com
t=3034423619 0
m=audio 3456 RTP/AVP 0
a=rtpmap:0 PCMU/8000
F5 ACK User A --> Application
ACK sip:UserB@subB.example.com SIP/2.0
Via: SIP/2.0/UDP client.subA.example.com:5060;branch=z9hG4bK74
Max-Forwards: 70
Route:
From: ;tag=1234567
To: ;tag=567890
Call-ID: 12345601@subA.example.com
CSeq: 1 ACK
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, NOTIFY
Supported: replaces
Content-Length: 0
F6 SUBSCRIBE Application --> User A
SUBSCRIBE sip:UserA@subA.example.com SIP/2.0
Max-Forwards: 70
From: ;tag=567890
To: ;tag=1234567
Call-ID: 12345601@subA.example.com
CSeq: 1 SUBSCRIBE
Contact:
Event: kpml
Expires: 7200
Accept: application/kpml+xml
Content-Type: application/kmpl+xml
Content-Length: ...
F7 200 OK User A --> Application
SIP/2.0 200 OK
To: ;tag=1234567
From: ;tag=567890
Call-ID: 12345601@subA.example.com
CSeq: 1 SUBSCRIBE
Contact:
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, SUBSCRIBE, NOTIFY
Supported: replaces
Content-Length: 0
F8 NOTIFY User A --> Application
NOTIFY sip:UserB@subB.example.com SIP/2.0
Max-Forwards: 70
From: ;tag=1234567
To: ;tag=567890
Call-ID: 12345601@subA.example.com
CSeq: 2 NOTIFY
Subscription-State: active;expires=3600
Content-Type: application/kpml+xml
Content-Length: ...
Event: kpml
F9 200 OK Application --> User A
SIP/2.0 200 OK
From: ;tag=1234567
To: ;tag=567890
Call-ID: 12345601@subA.example.com
CSeq: 2 NOTIFY
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, SUBSCRIBE, NOTIFY
Supported: replaces
Content-Type: application/sdp
Content-Length: 0
F10 NOTIFY User A --> Application
NOTIFY sip:UserB@subB.example.com SIP/2.0
Max-Forwards: 70
From: ;tag=1234567
To: ;tag=567890
Call-ID: 12345601@subA.example.com
CSeq: 3 NOTIFY
Subscription-State: active;expires=3125
Content-Type: application/kpml+xml
Content-Length: ...
Event: kpml
F11 200 OK Application --> User A
SIP/2.0 200 OK
From: ;tag=1234567
To:
Call-ID: 12345601@subA.com
JVD: CSeq: 3 NOTIFY
Contact:
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, SUBSCRIBE, NOTIFY
Supported: replaces
Content-Type: application/sdp
Content-Length: 0
]]>Coming soon!Coming soon!Key words for use in RFCs to Indicate Requirement LevelsXML Media TypesSIP: Session Initiation ProtocolSession Initiation Protocol (SIP)-Specific Event NotificationUniform Resource Names (URN) Namespace Definition MechanismsXML Schema Part 1: StructuresRTP: A Transport Protocol for Real-Time ApplicationsGMD FokusHardenbergplatz 2BerlinD-10623DEschulzrinne@fokus.gmd.dePrecept Software, Inc.21580 Stevens Creek BoulevardSuite 207CupertinoCA95014UScasner@precept.comXerox Palo Alto Research Center3333 Coyote Hill RoadPalo AltoCA94304USfrederic@parc.xerox.comLawrence Berkeley National LaboratoryMS 46a-1121BerkeleyCA94720USvan@ee.lbl.govThis memorandum describes RTP, the real-time transport protocol. RTP provides end-to-end network transport functions suitable for applications transmitting real-time data, such as audio, video or simulation data, over multicast or unicast network services. RTP does not address resource reservation and does not guarantee quality-of- service for real-time services. The data transport is augmented by a control protocol (RTCP) to allow monitoring of the data delivery in a manner scalable to large multicast networks, and to provide minimal control and identification functionality. RTP and RTCP are designed to be independent of the underlying transport and network layers. The protocol supports the use of RTP-level translators and mixers.SDP: Session Description Protocol
Information Sciences Institute
c/o MIT Laboratory for Computer Science
545 Technology Square
CambridgeMA02139USmjh@isi.edu
Lawrence Berkeley Laboratory
MS 46a-1121
BerkeleyCA94720USvan@ee.lbl.gov
Applications
multimediaSDP
This document defines the Session Description Protocol, SDP. SDP is
intended for describing multimedia sessions for the purposes of
session announcement, session invitation, and other forms of
multimedia session initiation.
This document is a product of the Multiparty Multimedia Session
Control (MMUSIC) working group of the Internet Engineering Task
Force. Comments are solicited and should be addressed to the working
group's mailing list at confctrl@isi.edu and/or the authors.
Hypertext Transfer Protocol -- HTTP/1.1University of California, Irvine, Information and Computer ScienceIrvineCA92697-3425US+1 949 824 1715fielding@ics.uci.eduWorld Wide Web Consortium, MIT Laboratory for Computer Science545 Technology SquareCambridgeMA02139US+1 617 258 8682jg@w3.orgCompaq Computer Corporation, Western Research Laboratory250 University AvenuePalo AltoCA94301USmogul@wrl.dec.comWorld Wide Web Consortium, MIT Laboratory for Computer Science545 Technology SquareCambridgeMA02139US+1 617 258 8682frystyk@w3.orgXerox Corporation3333 Coyote Hill RoadPalo AltoCA94034USmasinter@parc.xerox.comMicrosoft Corporation1 Microsoft WayRedmondWA98052USpaulle@microsoft.comWorld Wide Web Consortium, MIT Laboratory for Computer Science545 Technology SquareCambridgeMA02139US+1 617 258 8682timbl@w3.orgThe Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. It is a generic, stateless, protocol which can be used for many tasks beyond its use for hypertext, such as name servers and distributed object management systems, through extension of its request methods, error codes and headers. A feature of HTTP is the typing and negotiation of data representation, allowing systems to be built independently of the data being transferred.HTTP has been in use by the World-Wide Web global information initiative since 1990. This specification defines the protocol referred to as "HTTP/1.1", and is an update to RFC 2068.RTP Payload for DTMF Digits, Telephony Tones and Telephony SignalsSupport for IPv6 in Session Description Protocol (SDP)Media Gateway Control Protocol (MGCP) Version 1.0Gateway Control Protocol Version 1Voice Extensible Markup Language (VoiceXML) Version 2.0World Wide Web ConsortiumExtensible Markup Language (XML) 1.0 (Second Edition)Speech Recognition Grammar Specification Version 1.0
Basic Network Media Services with SIP
SnowShore Networks, Inc.285 Billerica Rd.ChelmsfordMA01824-4120USAe.burger@ieee.orgSnowShore Networks, Inc.285 Billerica Rd.ChelmsfordMA01824-4120USAjvandyke@snowshore.comSnowShore Networks, Inc.285 Billerica Rd.ChelmsfordMA01824-4120USAwoof@snowshore.comMedia Server Control Markup Language (MSCML) and ProtocolSnowShore Networks, Inc.SnowShore Networks, Inc.SnowShore Networks, Inc.An INVITE Inititiated Dialog Event Package for the Session Initiation Protocol (SIPJeff 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 I 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, the SnowShore Media Server Control Markup Language. Jeff Van Dyke and Andy Spitzer were the primary contributors to that effort.That said, any errors, misinterpretation, or fouls in this document are my own.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.Terence Lobo of SnowShore Networks made it all work.