RFC 4730
A Session Initiation Protocol (SIP) Event Package for Key Press Stimulus (KPML)
RFC 4730: KPML, the SIP Event Package for Key Presses 💖
Okay bestie, this is RFC 4730 ✨ Its full title is A Session Initiation Protocol (SIP) Event Package for Key Press Stimulus (KPML). It came from the Network Working Group and is a Standards Track doc, dated November 2006 🎀. The authors are E. Burger from Cantata Technology, Inc. and M. Dolly from AT&T Labs 🫶. The header has no Obsoletes or Updates line, so this one doesn't replace or change any older RFC 💅.
Status of This Memo 📜
This document is an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements 🔥. If you want to know where the protocol stands in standardization, check the current edition of "Internet Official Protocol Standards" (STD 1) 🧐. Distribution of this memo is unlimited 🌸.
Copyright Notice ©️
Copyright (C) The IETF Trust (2006) 🦋
Abstract 🧚
So this doc describes a SIP Event Package called "kpml" 💜. It lets you monitor Dual Tone Multi-Frequency (DTMF) signals, which are the beeps your keypad makes, and it uses XML documents called Key Press Markup Language (KPML) to do it 🎹. The kpml Event Package may be used for apps that follow the rules in the document "A Framework for Application Interaction in the Session Initiation Protocol (SIP)" 🌈.
The package uses SUBSCRIBE messages to carry XML filter specs. Those specs decide which key presses (DTMF tones) to capture from a presentation-free User Interface SIP User Agent (UA) 🍓. It then uses NOTIFY messages to send back XML reports of the captured key presses, matching those filters, to an Application Server ⭐. The scope is collecting supplemental key presses or mid-call key presses, which are called triggers 💅.
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
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 .....................................541. Introduction ✨
This doc describes the SIP Event Package "kpml", which lets you monitor key presses using XML documents called Key Press Markup Language (KPML) 💖. KPML is a markup [14] that makes presentation-free User Interfaces possible, 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 🦋. Both the subscription filter bodies and the notification report bodies are written in the Keypad Markup Language, KPML 🍓.
The "kpml" event package needs two new MIME types, two new URN sub-namespaces, and two schemas, one for the KPML Request and one for the KPML Response 📜. Its scope is collecting supplemental key presses or mid-call key presses (triggers) 🔥. This lets an Application Server service provider monitor (filter) for a set of DTMF patterns at a SIP User Agent, whether that UA lives in an end-user device or a gateway 👑.
Here's the big moment: the "kpml" event package lets "dumb phones" and "gateways" that receive signals from dumb phones report user key-press events 😭. People also call this "digit reporting" or "Dual Tone Multi-Frequency (DTMF) reporting" 🌸. It skips the need for "hair-pinning" (sending media into a device and then right back out of it) through a Media Server, and it skips duplicating every DTMF event 💅. That matters when an Application Server needs to trigger mid-call service processing on DTMF digit patterns 🙈.
A goal of KPML is to fit into an extremely small memory and processing footprint 🧚.
The name KPML reflects its legacy support role 🎀. The public switched telephony network (PSTN) signaled by carrying DTMF tones in the bearer channel (in-band signaling) from the user terminal to the local exchange 🕰️.
Voice-over-IP networks carry in-band signals either as actual DTMF waveforms or as RFC 2833 [10] packets 🌈. In RFC 2833, the signaling application inserts RFC 2833 named signal packets, either alongside or instead of generating tones in the media path 💜. The receiving application gets the signal information from the media stream 🫶.
RFC 2833 tones are great for sending telephone-events point-to-point in a Real-time Transport Protocol (RTP) stream. That covers straightforward sessions like a 2-party call or a simple, centrally mixed conference 💖. But other environments need something extra or different, like protocol translation and complex call control 🔥.
An interested application could ask for notifications of every key press 😳. Still, most of the use cases for this signaling show that applications only care about one or a few keystrokes ⭐. So there needs to be a mechanism for telling the user's interface which stimuli the application requires 💅.
1.1. Conventions Used in This Document 📚
RFC 2119 [1] gives the meanings of the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" as they're used here 🎀.
The Application Interaction Framework document [15] defines "User Device", "SIP Application", and "User Input". This document uses "Application" and "Requesting Application" interchangeably with "SIP Application" 🦋.
The Application Interaction Framework also talks about User Device Proxies 🧐. A common example of a User Device Proxy is a Public Switched Telephone Network (PSTN) gateway 🌸. The normative behavior of a presentation-free User Interface is the same for a presentation-free SIP User Agent and for a presentation-free User Device Proxy. So this document just says "User Device" for both 🫶.
2. Protocol Overview 🌈
The "kpml" event package uses explicit subscription notification requests through the SIP SUBSCRIBE and NOTIFY methods 💜. An Application that wants to collect digits builds an application/kpml-request+xml document with the digit patterns it cares about, then puts that document in its SUBSCRIBE request 🍓. SIP SUBSCRIBE messages get routed to the User Interface using standard SIP request routing 🦋. KPML Subscriptions do not fork. 🙅♀️ The KPML request inside the SUBSCRIBE message points at the target media stream by referencing the dialog identifiers of the session that owns that media stream 🎹. Once the subscription is set up, the User Interface sends application/kpml-response+xml documents in NOTIFY requests, either when digits are collected or when timeouts or errors happen 🔥.
A KPML subscription can be persistent or one-shot 💖. A persistent request stays active until one of these happens: 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) 😭.
A one-shot request terminates the subscription as soon as the User Interface receives DTMF values that give a match 🎯. The "persist" KPML element decides whether the subscription stays active for the duration given in the SUBSCRIBE message, or whether it automatically terminates on a pattern match ✨.
NOTIFY messages can contain XML documents 📦. If the User Interface matches a digitmap, the NOTIFY message (response) includes an XML document that says what User Input was detected and whether the User Interface suppressed the representation of that User Input (like tones, or RFC 2833) from the media streams 👑. If the User Interface runs into an error condition, like a timeout, that gets reported too 🙈.
3. Key Concepts 🧚♀️
3.1. Subscription Duration 💖
okay so KPML has two kinds of subscriptions: one-shot and persistent. Persistent ones split again into two sub-types: continuous notify and single-notify. it's giving choose-your-own-adventure 🦋
One-shot subscriptions are done once a pattern matches and a report goes out in a NOTIFY message. So if the User Interface picks up a key press that triggers a one-shot KPML event, the User Interface (notifier) MUST set the "Subscription-State" in the NOTIFY message to "terminated". Then the User Interface MUST consider the subscription expired 💀
Persistent subscriptions stick around at the User Interface even after a match ✨ For continuous-notify ones, the User Interface sends a NOTIFY message every single time the User Input matches a subscribed pattern. For single-notify ones, the user device sends a NOTIFY at the first match and then goes quiet. No more NOTIFYs until the Application sends a brand 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. iykyk, and it's honestly so clean 🔥
The persist attribute on the <pattern> tag in the KPML subscription body controls how long the subscription lives 🎀
If persist is "one-shot", then once there's a match (or no match is possible), the subscription ends after the User Interface notifies the Application.
If persist is "persist" or "single-notify", the subscription ends when the Application explicitly ends it, or when the User Interface terminates it.
If the User Interface doesn't support persistent subscriptions, it returns a NOTIFY message with the KPML status code set to 531. And if there are digits in the buffer that match an expression in the SUBSCRIBE filter, the User Interface prepares the appropriate NOTIFY response message 🧚
Heads up: the values of the persist attribute are case sensitive, so "Persist" is not the same as "persist" 🙅
3.2. Timers ⏰
To handle all the different key press collection scenarios, three timers are defined: the extra, critical, and inter-digit timers. 🌈
- 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.
- The critical timer is the time to wait for another digit if the collected digits can match more than one potential pattern.
- 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 how long the User Interface will wait for User Input before returning a timeout error result on a partially matched pattern. The application can set the inter-digit timeout as an integer number of milliseconds using the interdigittimer attribute on the <pattern> tag. The default is 4000 milliseconds. If the User Interface doesn't support setting an inter-digit timeout, the User Interface MUST silently ignore the specification. If it does support setting one, but not at the granularity of the value presented, the User Interface MUST round up the requested value to the closest value it can support 🍓
The whole point of the inter-digit timeout is to stop applications from starting to match a pattern and then never getting a result 😭 This can happen when the user accidentally presses a key that begins to match a pattern. Since the key was an accident, the rest of the pattern never comes. And when the user does enter a pattern after that accidental key, the pattern may not match, or may not match the way the application expects. Another case: the user thinks they pressed a key, but the User Interface never detected it. That could happen when collecting ten digits but the device only actually receives 9. The User Interface would then wait forever for the tenth key press, while the user gets super frustrated wondering why the application isn't responding 💅
The User Interface MAY support a critical-digit timeout value. This is how long the User Interface will wait for another key press when it already has a matched <regex>, but another, longer <regex> could also match the pattern. The application can set the critical-digit timeout as an integer number of milliseconds using the criticaldigittimer attribute on the <pattern> tag. The default is 1000 milliseconds.
The purpose of the critical-digit timeout is to let the application collect longer matches instead of only the shortest one. 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 lets the User Interface tell apart "0", "00", "011", and "0011". Without this feature, the only value the User Interface can detect is "0" 👑
The User Interface MAY support an extra-digit timeout value. This is how long the User Interface will wait for another key press when it has already matched the longest <regex>. The application can set the extra-digit timeout as an integer number of milliseconds using the extradigittimer attribute on the <pattern> tag. The default is 500 milliseconds. If there is no enterkey specified, the User Interface MAY default the exteradigittimer to zero.
The purpose of the extra-digit timeout is to give the User Interface time 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 🎀
okay so during the subscription lifetime, the User Interface might detect a key press stimulus that triggers a KPML event 👀. when that happens, the User Interface (notifier) MUST return the appropriate KPML document 💅.
the pattern matching logic is giving precision ✨. KPML User Interfaces MUST follow the logic in this section so that different implementations perform deterministically on the same KPML document given the same User Input. everyone gets the same answer, no drama 🫶.
a kpml request document has a <pattern> element with a series of <regex> tags. each <regex> element is a potential pattern for the User Interface to match 🧚. Section 5.1 explains the DRegex (digit regular expression) language 📚.
the pattern match algorithm matches the longest regular expression 🏆. this is the same mode as H.248.1 [12], not the mode MGCP [11] uses 💀. the pattern match algorithm choice really affects when a pattern counts as a match. check this doc:
<?xml version="1.0" encoding="UTF-8"?>
<kpml-request xmlns="urn:ietf:params:xml:ns:kpml-request"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"urn:ietf:params:xml:ns:kpml-request kpml-request.xsd"
version="1.0">
<pattern>
<regex>0</regex>
<regex>011</regex>
</pattern>
</kpml-request>Figure 1: Greedy Matching
in Figure 1, if we matched on the first pattern we found, the string "011" would never match, because the "0" rule would win first 😭.
while this behavior is what most applications want, it does come with a cost 🙈. check this snippet:
<regex>x{7}</regex>
<regex>x{10}</regex>Figure 2: Timeout Matching
Figure 2 is a typical North American dial plan 📞. apps want a seven-digit number to respond quickly, not wait for the usual inter-digit critical timer (usually four seconds) ⏳. but users also don't want their ten-digit number cut off at seven digits just because they typed too slowly 😤.
one approach is an explicit dial string terminator, often the pound key (#) 🔑. like this:
<regex>x{7}#</regex>
<regex>x{10}#</regex>Figure 3: Timeout Matching with Enter
the problem with Figure 3 is that the "#" shows up in the returned dial string 🙅. plus, people often want to enter the string without the terminator key. and matching the key explicitly means you have to double the number of patterns, e.g., "x{7}", "x{7}#", "x{10}", and "x{10}#" 😩.
KPML does it differently with an explicit "Enter Key" 🌸:
<pattern enterkey="#">
<regex>x{7}</regex>
<regex>x{10}</regex>
</pattern>Figure 4: Timeout Matching with Enter Key
in Figure 4, the enterkey attribute on the <pattern> tag specifies a string that ends a pattern 🎯. so if the user enters seven digits followed by the "#" key, the pattern matches (or fails) immediately ⚡. KPML indicates a terminated nomatch with 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 apps look for a long "#" or a long "*" 🍓.
KPML uses the "L" modifier on <regex> characters to mean long key presses ✨. this doc looks for a long pound of at least 3 seconds:
<?xml version="1.0" encoding="UTF-8"?>
<kpml-request xmlns="urn:ietf:params:xml:ns:kpml-request"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"urn:ietf:params:xml:ns:kpml-request kpml-request.xsd"
version="1.0">
<pattern long="3000">
<regex>L#</regex>
</pattern>
</kpml-request>Long Pound
the request can say what counts as "long" by setting the long attribute on the <pattern>. it's an integer representing 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 🫣. but if there isn't a corresponding long key press pattern in a document, the User Interface MUST match the key press pattern irrespective of how long the user presses the key 💫. in the snippet below, the User Interface tells a long "" apart from a normal "", but any length "#" will match 👑:
<pattern>
<regex tag="short_star">*</regex>
<regex tag="long_star">L*</regex>
<regex>#</regex>
</pattern>Figure 6: Long and Short Matching
some User Interfaces can't 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, the User Interface MAY interpret a succession of presses of a single key as equivalent to a long key press of the same key 🔁. the Application indicates it wants this by setting the "longrepeat" attribute on the <pattern> to "true" 💜.
the KPML document says whether patterns are persistent by setting the "persist" attribute on the <pattern> tag to "persist" or "single-notify". any other value, including "one-shot", means the request is a one-shot subscription 🎀. if the User Interface doesn't support persistent subscriptions, it returns a KPML document with KPML status code 531 🙃. if there are digits in the buffer and they 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 🙈 (it's giving strict).
some User Interfaces may support multiple regular expressions in a given pattern request. in that case, the application may want to know which pattern triggered the event 🕵️.
KPML gives the <regex> tag a "tag" attribute. the "tag" is an opaque string that the User Interface sends back in the notification report upon a match in the digit map 🏷️. when there are multiple matches, the User Interface MUST choose the longest match in the KPML document. if multiple matches are 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 🙈
okay so, by default a KPML User Interface sends in-band tones (RFC 2833 [10] or the actual tone) at the same time it reports User Input. 🎀
bestie, if KPML didn't do this, a User Interface running KPML could totally break the apps it's connected to 😭 picture a personal assistant that uses "9" to get its attention. If the user presses "", KPML holds that digit because it's waiting for a "9". Now what if the user only wanted a plain "" because they're stuck in an IVR (interactive voice response) system that listens for ""? The UI holds the "" since it's looking for "9", so the user presses "" again, hoping the IVR just missed the first one. At that point the UI sends both "" entries, because "*" doesn't match "9". But that's not what the user meant when they pressed "*" 💀
Now, passing tones through in-band isn't always wanted, ngl. Call centers that use in-band tone spills to start a transfer are a big example 🦋
For those situations, KPML adds a suppression tag, "pre", to the <regex> tag. There MUST NOT be more than one <pre> tag in any given <regex> tag. 🚫
If there's only a single <pattern> and a single <regex>, suppression is pretty straightforward ✨ The endpoint passes User Input along until the stream matches the regular expression <pre>. At that point, the User Interface keeps collecting User Input, but it suppresses 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's too late to suppress the transmission, because the User Interface already sent the stimulus. So this is a case where there's a <pre> specification, but the suppressed attribute won't be "true" in the notification. If there's a <pre> tag that the User Interface matched and it's unable to suppress the User Input, it MUST set the suppressed attribute to "false". 😤
A KPML User Interface MAY perform suppression. If it isn't 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, the User Interface will collect enough User Input to match a <pre> pattern. The interdigittimer attribute says 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. ⏰
Once the User Interface detects a match and sends a NOTIFY request to report the User Input, the User Interface MUST stop suppression. Clearly, if subsequent User Input matches another <pre> 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:
<regex><pre>*8</pre>xxx[2-9]xxxxxx</regex>At the point the User Interface receives "*8", it will stop forwarding stimulus. Let's say the next three digits are "408". If the next digit is a zero or one, the pattern won't match. 🙈
NOTE: It is critically important for the User Interface to have a sensible inter-digit timer, because an errant dot (".") may suppress digit sending forever. 😱
Applications should be very careful to indicate suppression only when they're fairly sure the user will enter a digit string that matches the regular expression. Applications should also deal with situations like no-match or time-out, since the User Interface will hold digits, and that causes obvious User Interface issues when something fails. 💅
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 decide what the following key presses mean. For a novice user, the application may play a prompt describing what mode it's in. But "power users" often barge right through the prompt 🏃♀️
User Interfaces MUST NOT provide a subscriber with digits that were detected before that subscriber was authenticated and authorized. Without this prohibition, a subscriber might be able to get access to calling card or other information that predated their participation in the call. Note that this prohibition MUST be applied on a per-subscription basis. 🔐
KPML provides a <flush> tag in the <pattern> element. The default is not to flush User Input. Flushing User Input means ignoring key presses entered before the KPML subscription was installed. To flush User Input, include the tag <flush>yes</flush> 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 that 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 tell the User Interface to operate in lock-step mode, set the <pattern> attribute persist="single-notify". 🔒
The User Interface MUST be able to process <flush>no</flush>. This directive is effectively a no-op. 🫠
Other string values for <flush> may be defined in the future. If the User Interface receives a string it doesn't understand, it MUST treat the string as a no-op. 🔮
If the user presses a key that cannot match any pattern within a <regex> 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 enters after the match. 🗑️
NOTE: This behavior lets applications receive only the User Input that's actually of interest to them. For example, a pre-paid application only wants to monitor for a long pound. If the user enters other stimulus, presumably for other applications, the pre-paid application doesn't want a notification about that User Input. This feature is fundamentally different from 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 on the <pattern> tag to "true". In this case, the User Interface attempts to match a rolling window over the collected User Input. 🪟
KPML subscriptions are independent. So the current document can't know whether a following document will enable barging or want User Input flushed. That's why the User Interface MUST buffer all User Input, subject to the forced_flush caveat described below. 🤷♀️
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 for 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 <regex> tags. If there's a match, the interpreter MUST follow the procedures in Section 5.3. If there's no match, the interpreter MUST flush all of the collected User Input. 🎯
Given the potential need for an infinite buffer for User Input, the User Interface MAY discard the oldest User Input from the buffer. If the User Interface discards digits, then when it issues a KPML notification, it MUST set the forced_flush attribute of the <response> tag to "true". For future use, the Application MUST consider any non-null value, other than "false", that it doesn't understand to be the same as "true". 🗂️
NOTE: Buffering all User Input for the entire length of the session isn't onerous under normal operation. For example, if you have 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. That's nothing, bestie 💖
Unless there's a suppress indicator in the digit map, it's not possible to know whether the User Input is for local KPML processing or for other recipients of the media stream. So, without a suppression indicator, the User Interface transmits the User Input to the far end in real time, using RFC 2833, generating the appropriate tones, or both. 📡
3.6. DRegex 💜
3.6.1. Overview
okay so this part is informative, meaning it's just vibes and background, not a rule 💅 ✨
The Digit REGular EXpression (DRegex) syntax is a telephony-friendly remix of POSIX Extended Regular Expressions (ERE) [13] 🎀
KPML does NOT use full POSIX ERE, and here's why, bestie 🫶
- KPML will often run on high density or extremely low power and memory footprint devices 🔋💀
- telephony people already use the star symbol ("") for the star key and "x" for any digit 0-9. making devs write escapes like "*" and expand "x" into "[0-9]" is so error prone 😭 this is also why DRegex uses the dot (".") for repetition, which is what the plain star did in POSIX ERE 🦋
- implementers and users kept struggling with the precedence of the alternation operator ("|") in MGCP [11] and H.248.1 [12] 🙈 the under-specification in those docs plus confusing concepts for users made it a mess. so the SIPPING Working Group decided DRegex should NOT support alternation. but no worries, each KPML <pattern> element can hold multiple regular expressions (<regex> elements), so you get pattern alternatives without the "|" drama 🌸 DRegex does not support the POSIX alternation operator, period ✨
- DRegex has character classes (characters in square brackets), but the negation operator inside a class ONLY works on numbers 🔢 so a negation class implicitly includes A-D, , and #, and listing those in a negation is a no-op. POSIX people would expect "[^45]" to include everything else (A-D, R, *, #), while telephony digit map people would expect it to exclude non-digits. since the DRegex character set is tiny, building a negation with A-D, R, *, and # means you spell out the positive inverse instead. for example, all key presses including A-D and * except # is "[0-9A-D]" instead of "[^#R]" 🍓
here's the mapping from DRegex to POSIX ERE 👑
+--------+-----------+
| DRegex | POSIX ERE |
+--------+-----------+
| * | \* |
| . | * |
| x | [0-9] |
| [xc] | [0-9c] |
+--------+-----------+
Table 1: DRegex to POSIX ERE Mappingthe first swap (star to escaped star) is because telephony designers are used to the star key showing up all the time, so making them escape it would be error prone 💖 and the usage matches MGCP [11] and H.248.1 [12] too.
the dot instead of star is also straight from MGCP and H.248.1, and reusing the star here would be confusing and error prone 🙃
the "x" character is the common shorthand for digits 0 through 9, so DRegex keeps it, continuing the convention ✨ but for "[xc]", where c is any character, you can't just blindly swap "[0-9]" in for "x", because "[[0-9]c]" is NOT legal POSIX ERE 💀 the right substitution for "[xc]" is "[0-9c]" 🫧
NOTE: "x" does NOT include the characters *, #, R, or A through D. 🚫
users need to be careful not to mix DRegex up with POSIX EREs, bestie. they are NOT identical 😭 DRegex skips a lot of POSIX ERE features ✨
implementation side note: if you make the substitutions in the table above, a standard POSIX ERE engine can parse the digit string 🧚 but the mapping does NOT work backwards (POSIX ERE to DRegex). DRegex only implements the normative behavior described below 🌈
3.6.2. Operation
white space is removed before DRegex gets parsed. this lets you pretty print in XML without changing what the DRegex string means 🎀
here are the rules showing how DRegex works in KPML 💅
+---------+---------------------------------------------------------+
| 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 Entitiesfor ranges, the A-D characters are disjoint from the 0-9 characters 🧩 and if the device doesn't have an "R" key, the device MAY report a hook flash as an R character 📞
here are some DRegex examples, bestie 🦋
+--------------+--------------------------------------------+
| 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 Examples3.7. Monitoring Direction
SIP identifies dialogs by their dialog identifier 🦋 that's the remote-tag, local-tag, and Call-ID entities defined in RFC 3261 [4].
one way to figure out the dialog identifier, especially for third-party apps, is the SIP Dialog Package [17] ✨
for most situations, like a monaural point-to-point call with a single codec, the stream to monitor is obvious 🎧 so the Application doesn't need to say which stream to monitor 💖
but specifying only the SIP dialog can be ambiguous 🥺 the dialog may list multiple SDP streams that could carry key press events, like when a dialog has multiple audio streams. wherever possible, the User Interface MAY apply local policy to figure out which stream or streams to monitor 🔍 to keep stream identification extensible, the mechanism is element content inside the <stream> tag. the only content defined today is <stream>reverse</stream> 🫶
by default, the User Interface monitors key presses coming from the User Interface itself. 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 maybe other cases), you need to monitor key presses arriving from the remote user agent 📡 the optional <stream> element on the <request> tag specifies which stream to monitor. the only legal value is "reverse", which means 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 ever needed, can be added in a backwards-compatible way. more specifying of the stream to monitor is future standardization stuff 🔮
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 them 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 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 that case, 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 because 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 ✨
okay so this package has three Event Package parameters: call-id, remote-tag, and local-tag 🎀. These parameters MUST be present, because they're how the subscription dialog gets identified 🦋. 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 is below. it borrows a bunch of stuff from the ABNF of RFC 3261, like 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 tokenif any call-ids have embedded double-quotes, those double-quotes MUST be escaped using the backslash-quoting mechanism 🙈 the call-id parameter might need to be written as a quoted string, and the reason is kind of iconic. the ABNF for the callid production and the word production (both from RFC 3261 [1]) allow some characters, like "@", "[", and ":", that are NOT allowed inside a token. so it's not me being extra, it's the grammar being sus 💀
4.3. SUBSCRIBE Bodies
applications using this event package include an application/kpml-request+xml body in SUBSCRIBE requests to say which digit patterns they're into 🍓 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, bestie ⏰ subscriptions to this event package MAY range from minutes to weeks. hours or days are more typical though, and those are RECOMMENDED 💜 the default subscription duration for this event package is 7200 seconds.
Subscribers MUST be able to handle the User Interface returning anExpiresvalue smaller than the requested value. Per RFC 3265 [5], the subscription duration is the value returned by the Notifier in the 200 OKExpiresheader. 🌸
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 sent in immediate response to a SUBSCRIBE request MUST NOT contain a body, unless they're telling the subscriber about an error condition or previously buffered digits 🙅♀️
Notifiers MAY send notifications in any format the subscriber accepts (based on the subscriber's inclusion of these formats in an Accept header) 💅 a future extension MAY define other NOTIFY bodies. and if there's no "Accept" header in the SUBSCRIBE, the body type defined in this document MUST be assumed ✨
4.6. Subscriber Generation of SUBSCRIBE Requests
okay so a kpml request document has a <pattern> element with a bunch of <regex> tags inside it. each <regex> element is a potential pattern for the User Interface to match 🎯 Section 5.1 explains the DRegex, or digit regular expression, language, so go check that out 📖
KPML is all about 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 the info KPML reports can be super sensitive, subscribers SHOULD use sips: and MAY use S/MIME on the content 🔐
and subscribers MUST be prepared for the notifier to insist on authentication of the subscription request. subscribers MUST also be prepared for the notifier to insist on using a secure communication channel. no cap, be ready for the gatekeeper 🫣
4.7. Notifier Processing of SUBSCRIBE Requests
the user information KPML carries is potentially sensitive. like, it could include calling card or credit card numbers 😭 so the User Interface (notifier) MUST authenticate the requesting party in some way before accepting the subscription. non-negotiable, bestie 👑
User Interfaces MUST implement SIP Digest authentication as required by RFC 3261 [4], and MUST implement the sips: scheme and TLS 🔒
after authenticating the requesting party, the User Interface figures out whether that party is allowed to monitor the user's key presses. the default authorization policy lets a KPML subscriber who can authenticate with a specific identity monitor key presses from SIP sessions where that same (or an equivalent authenticated) identity is a participant 🦋 KPML will also often get used between "application servers" (subscribers) and PSTN gateways (notifiers) run by the same domain or federation of domains. in that setup a notifier MAY be configured with a list of subscribers that are specifically trusted and authorized to subscribe to key press info for 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 whether the request is meant to terminate a subscription. if it is, the User Interface does the appropriate processing, including the procedures described in Section 5.2 🙌
if the request has no KPML body, then any KPML document running on that dialog and addressed by the event id (if there is one) immediately terminates. this is basically a way to unload a KPML document while keeping the SUBSCRIBE-initiated dialog alive ✨ it can be a big deal for secure sessions where setting up the session is expensive 💸 the User Interface follows the procedures described in Section 5.2.
if the dialog referenced by the kpml subscription doesn't exist, the User Interface follows the procedures in Section 5.3. the User Interface MUST issue a 200 OK to the SUBSCRIBE request before issuing the NOTIFY, because 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's already a loaded KPML document on the subscription, the User Interface unloads it 🧹
and also, if there's a loaded KPML document on the subscription, the end device unloads the document 💅
following the semantics of SUBSCRIBE, if the User Interface gets a resubscription, the User Interface MUST terminate the existing KPML request and replace it with the new one 🔁
it's possible for the INVITE usage of the dialog to terminate during key press collection 😳 the cases 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's buffered User Input, then the User Interface tries to process the buffered digits against the document. if there's 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 up to when the subscription with expires equal to zero was processed. this could be the null string 🫠
per the mechanisms of RFC 3265 [5], the User Interface MUST terminate the SIP SUBSCRIBE dialog. it does this through the SIP NOTIFY body carrying the final report described in the paragraph before this one. specifically, the subscription state will be "terminated" and a reason of "timeout" ⏳
terminating the subscription when a dialog terminates makes sure reauthorization (if it's needed) happens before attaching to any later subscriptions 🛡️
if a SUBSCRIBE request references a dialog that isn't 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 isn't 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" 🙃
and last but not least: if the document is valid but the User Interface doesn't 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
Okay so, right after a subscription gets accepted, the Notifier MUST send a NOTIFY with the current location info, as appropriate for who the subscriber is 💅. That's how the Subscriber gets to resynchronize its state 🔄 no vibes lost.
The User Interface (notifier in SUBSCRIBE/NOTIFY parlance) makes NOTIFY requests following the rules in RFC 3265 [5]. Specifically, if a SUBSCRIBE request is valid and authorized, it gets an immediate NOTIFY ✨.
The KPML payload tells apart an initial NOTIFY from a NOTIFY that reports key presses 🎀. If there's no User Input buffered at the time of the SUBSCRIBE (see below), or the buffered User Input doesn't match the new KPML document, then the immediate NOTIFY MUST NOT contain a KPML body 🙈. But if the User Interface has buffered User Input 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 🦋.
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: <sip:application@example.com>
From: <sip:endpoint@example.net>
Call-Id: 439hu409h4h09903fj0ioij
Subscription-State: active; expires=7200
CSeq: 49851 NOTIFY
Event: kpmlFigure 10: Immediate NOTIFY Example
All subscriptions MUST be authenticated 🔐, especially the ones that match on buffered input. No exceptions, bestie 🫶.
KPML is the one that specifies the key press notification report format 📝. The MIME type for KPML reports is application/kpml-response+xml, and the default MIME type for the kpml event package is also application/kpml-response+xml 💖.
If the requestor isn't using a secure transport protocol like TLS for every hop (for example, 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 <regex> 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, the requestor must issue a new request to collect more digits 🔁.
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. Heads up: the KPML status code is not necessarily related to the SIP result code 👀. A big example of this is when a legal SIP subscription request gets a normal SIP 200 OK followed by a NOTIFY, but something is wrong with the KPML request 💀. In that case, the NOTIFY would include the KPML status code in the KPML report. 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" ⚰️. That 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 <response> tag. ⏰
Note that if the monitored (INVITE-initiated) dialog terminates, the notifier still MUST explicitly terminate the KPML subscriptions monitoring that dialog 🚪. No loose ends allowed 🧹.
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 ⏳.
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, so stay alert 💜.
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 <regex> 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] 🙅♀️. Not doing that, periodt 💅.
4.13. Behavior of a Proxy Server
There are no additional requirements on a SIP Proxy 🧚. The only job is to transparently forward the SUBSCRIBE and NOTIFY methods as required in SIP 📨. Easy.
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*DIGITABNF 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 🦋. Stay tuned, bestie 👑.
5.2. KPML Request
okay so KPML requests get described with the XML Schema [8] (same structure-y vibe as before, it's giving organized 🎀). Here's the whole schema, bestie 💖
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="urn:ietf:params:xml:ns:kpml-request"
xmlns="urn:ietf:params:xml:ns:kpml-request"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xs:element name="kpml-request">
<xs:annotation>
<xs:documentation>IETF Keypad Markup Language Request
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="stream" minOccurs="0">
<xs:complexType>
<xs:choice>
<xs:element name="reverse" minOccurs="0"/>
<xs:any namespace="##other"/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name="pattern">
<xs:complexType>
<xs:sequence>
<xs:element name="flush" minOccurs="0">
<xs:annotation>
<xs:documentation>
Default is to not flush buffer
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string"/>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="regex" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
Key press notation is a string to allow
for future extension of non-16 digit
keypads or named keys
</xs:documentation>
</xs:annotation>
<xs:complexType mixed="true">
<xs:choice>
<xs:element name="pre" minOccurs="0">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string"/>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:any namespace="##other"/>
</xs:choice>
<xs:attribute name="tag" type="xs:string"
use="optional"/>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="persist" use="optional">
<xs:annotation>
<xs:documentation>Default is "one-shot"
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="one-shot"/>
<xs:enumeration value="persist"/>
<xs:enumeration value="single-notify"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="interdigittimer"
type="xs:integer"
use="optional">
<xs:annotation>
<xs:documentation>Default is 4000 (ms)
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="criticaldigittimer"
type="xs:integer"
use="optional">
<xs:annotation>
<xs:documentation>Default is 1000 (ms)
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="extradigittimer"
type="xs:integer"
use="optional">
<xs:annotation>
<xs:documentation>Default is 500 (ms)
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="long" type="xs:integer"
use="optional"/>
<xs:attribute name="longrepeat" type="xs:boolean"
use="optional"/>
<xs:attribute name="nopartial" type="xs:boolean"
use="optional">
<xs:annotation>
<xs:documentation>Default is false
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="enterkey" type="xs:string"
use="optional">
<xs:annotation>
<xs:documentation>No default enterkey
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="version" type="xs:string"
use="required"/>
</xs:complexType>
</xs:element>
</xs:schema>Figure 12: XML Schema for KPML Requests
5.3. KPML Response
Same deal for responses: the syntax uses the XML Schema [8] ✨
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="urn:ietf:params:xml:ns:kpml-response"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="urn:ietf:params:xml:ns:kpml-response"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xs:element name="kpml-response">
<xs:annotation>
<xs:documentation>IETF Keypad Markup Language Response
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:attribute name="version" type="xs:string"
use="required"/>
<xs:attribute name="code" type="xs:string"
use="required"/>
<xs:attribute name="text" type="xs:string"
use="required"/>
<xs:attribute name="suppressed" type="xs:boolean"
use="optional"/>
<xs:attribute name="forced_flush" type="xs:string"
use="optional">
<xs:annotation>
<xs:documentation>
String for future use for e.g., number of digits lost.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="digits" type="xs:string"
use="optional"/>
<xs:attribute name="tag" type="xs:string" use="optional">
<xs:annotation>
<xs:documentation>Matches tag from regex in request
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:complexType>
</xs:element>
</xs:schema>XML Schema for KPML Responses
6. Enumeration of KPML Status Codes 💅
KPML status codes basically copy their SIP cousins 👯♀️ Anything starting with a 2 means success ✨, a 4 means failure 🥲, and a 5 means a server failure 💀. That last one usually happens when the server can't interpret the document or doesn't support a feature that got requested.
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, so don't go reading into it, bestie 🙈
+------+--------------------------------------------------+
| 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 is registering a new SIP Event Package, two new MIME types, and two new XML namespaces. Literally a whole haul 🎀
7.1. SIP Event Package Registration
Package name: kpml
Type: package
Contact: Eric Burger, <e.burger@ieee.org>
Change Controller: SIPPING Working Group delegated from the IESG
Published Specification: RFC 47307.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
<e.burger@ieee.org>
Intended usage: COMMON7.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
<e.burger@ieee.org>
Intended usage: COMMON7.4. URN Sub-Namespace Registration for urn:ietf:xml:ns:kpml-request
URI: urn:ietf:params:xml:ns:kpml-request
Registrant Contact: The IESG <iesg@ietf.org>
XML:
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C/DTD XHTML Basic 1.0//EN"
"http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type"
content="text/html;charset=iso-8859-1"/>
<title>Key Press Markup Language Request</title>
</head>
<body>
<h1>Namespace for Key Press Markup Language Request</h1>
<h2>urn:ietf:params:xml:ns:kpml-request</h2>
<p>
<a href="ftp://ftp.rfc-editor.org/in-notes/RFC4730.txt">RFC 4730</a>.
</p>
</body>
</html>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 <iesg@ietf.org>
XML:
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C/DTD XHTML Basic 1.0//EN"
"http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type"
content="text/html;charset=iso-8859-1"/>
<title>Key Press Markup Language Response</title>
</head>
<body>
<h1>Namespace for Key Press Markup Language Response</h1>
<h2>urn:ietf:params:xml:ns:kpml-response</h2>
<p>
<a href="ftp://ftp.rfc-editor.org/in-notes/rfc4730.txt">RFC 4730</a>.
</p>
</body>
</html>7.6. KPML Request Schema Registration 💅
Okay so, per RFC 3688 [7], IANA registered the XML Schema for KPML that's referenced in Section 5.2 of RFC 4730. It's giving official paperwork energy 📋✨
URI: urn:ietf:params:xml:schema:kpml-request
Registrant Contact: <iesg@ietf.org>
7.7. KPML Response Schema Registration 🎀
Same slay here: per RFC 3688 [7], IANA registered the XML Schema for KPML that's referenced in Section 5.3 of RFC 4730. Main character registrations only 👑
URI: urn:ietf:params:xml:schema:kpml-response
Registrant Contact: IETF, SIPPING Work Group <sipping@ietf.org>, Eric Burger <e.burger@ieee.org>.
8. Security Considerations 🔐
Bestie, this section is serious, so read it slowly 🥺 The user information KPML carries is potentially sensitive. It could include calling card or credit card numbers 💀 That potentially private info could leak out by accident if the notifier doesn't properly authenticate or authorize a subscription. Similarly, private info (like a credit card or calling card number) could be revealed to an otherwise legitimate subscriber (one operating an IVR) if digits buffered earlier in the session get passed along to the new subscriber by mistake 😭
Likewise, an eavesdropper could view KPML digit info if it isn't encrypted, and an attacker could inject fraudulent notifications unless the messages or the SIP path they travel over 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 🧠
Key press information is potentially sensitive 💖 It can represent credit card, calling card, or other personal information. Hijacking sessions lets unauthorized entities get at this sensitive information, which is lowkey terrifying. 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, so it's the friendly how-to part 🌸 If there's a discrepancy between this section and the normative sections above, the normative sections take precedence. Read the rules first, then the vibes!
9.1. Monitoring for Octothorpe 📞
A super common need for pre-paid and personal assistant apps is monitoring a conversation for a signal that says the user's focus is shifting from the party they called through the app to the app itself 👀 For example, if you call a party using a pre-paid calling card, and that party redirects you to voice mail, the digits you press are for the voice mail system. However, a lot of apps have a special key sequence, like the octothorpe (#, or pound sign) or *9, that ends the called party session and shifts the user's focus to the application 🍓
Figure 16 shows the KPML for long octothorpe 💅
<?xml version="1.0"?>
<kpml-request xmlns="urn:ietf:params:xml:ns:kpml-request"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"urn:ietf:params:xml:ns:kpml-request kpml-request.xsd"
version="1.0">
<pattern>
<regex>L#</regex>
</pattern>
</kpml-request>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 figure out when the user has entered a target number. On top of that, KPML tells you what type of number the user entered. Iconic multitasking 🙌
<?xml version="1.0"?>
<kpml-request xmlns="urn:ietf:params:xml:ns:kpml-request"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"urn:ietf:params:xml:ns:kpml-request kpml-request.xsd"
version="1.0">
<pattern>
<regex tag="local-operator">0</regex>
<regex tag="ld-operator">00</regex>
<regex tag="vpn">7[x][x][x]</regex>
<regex tag="local-number7">9xxxxxxx</regex>
<regex tag="RI-number">9401xxxxxxx</regex>
<regex tag="local-number10">9xxxxxxxxxx</regex>
<regex tag="ddd">91xxxxxxxxxx</regex>
<regex tag="iddd">011x.</regex>
</pattern>
</kpml-request>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 is if the user entered "94015551212". This string matches both the "9401xxxxxxx" and "9xxxxxxxxxx" regular expressions. Both expressions are the same length, so the KPML interpreter will pick "9401xxxxxxx" because it occurs first in document order. Plot twist 🤯 Figure 18 shows the response.
<?xml version="1.0"?>
<kpml-response xmlns="urn:ietf:params:xml:ns:kpml-resposne"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"urn:ietf:params:xml:ns:kpml-response kpml-response.xsd"
version="1.0"
code="200" text="OK"
digits="94015551212" tag="RI-number"/>Figure 18: Dial String KPML Response
10. Call Flow Examples 🦋✨
10.1. Supplemental Digits 🎀
Okay so this section is a non-normative example (just a demo, not a rule 💅) of an app that collects supplemental digits. That's when the network asks for more digits after the caller has already typed in the destination address. A typical supplemental dial string is four digits long 🔢✨
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 FlowMessages (1-3) are where the ingress gateway sets up a dialog with an egress gateway 🦋 The app figures out the dialog ID through out-of-band stuff, like the Dialog Package or just by living on the same box as the egress gateway 🧚 Here's a bit of the ACK so you can see the dialog identifiers in action 👀
ACK sip:gw@subA.example.com SIP/2.0
Via: ...
Max-Forwards: ...
Route: ...
From: <sip:phn@example.com>;tag=jfh21
To: <sip:gw@subA.example.com>;tag=onjwe2
Call-ID: 12345592@subA.example.com
...In message (4), the app asks the gateway to collect a string of four key presses 🔥 This is the big SUBSCRIBE moment, bestie 💖
SUBSCRIBE sip:gw@subA.example.com SIP/2.0
Via: SIP/2.0/TCP client.subB.example.com;branch=q4i9ufr4ui3
From: <sip:ap@subB.example.com>;tag=567890
To: <sip:gw@subA.example.com>
Call-ID: 12345601@subA.example.com
CSeq: 1 SUBSCRIBE
Contact: <sip:ap@client.subB.example.com>
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
<?xml version="1.0" encoding="UTF-8"?>
<kpml-request xmlns="urn:ietf:params:xml:ns:kpml-request"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"urn:ietf:params:xml:ns:kpml-request kpml-request.xsd"
version="1.0">
<pattern persist="one-shot">
<regex>xxxx</regex>
</pattern>
</kpml-request>Message (5) is the 200 OK that says "yep, got your subscription" ✅
SIP/2.0 200 OK
Via: SIP/2.0/TCP subB.example.com;branch=q4i9ufr4ui3;
received=192.168.125.12
From: <sip:ap@subB.example.com>;tag=567890
To: <sip:gw@subA.example.com>;tag=1234567
Call-ID: 12345601@subA.example.com
CSeq: 1 SUBSCRIBE
Contact: <sip:gw27@subA.example.com>
Expires: 3600
Event: kpmlMessage (6) is the instant NOTIFY that goes out right after the subscription is set up 📬
NOTIFY sip:ap@client.subB.example.com SIP/2.0
Via: SIP/2.0/UDP subA.example.com;branch=gw27id4993
To: <sip:ap@subB.example.com>;tag=567890
From: <sip:gw@subA.example.com>;tag=1234567
Call-ID: 12345601@subA.example.com
CSeq: 1000 NOTIFY
Contact: <sip:gw27@subA.example.com>
Event: kpml
Subscription-State: active;expires=3599
Max-Forwards: 70
Content-Length: 0Message (7) is the 200 OK that acknowledges that NOTIFY 🫶
SIP/2.0 200 OK
Via: SIP/2.0/TCP subA.example.com;branch=gw27id4993
To: <sip:ap@subB.example.com>;tag=567890
From: <sip:gw@subA.example.com>;tag=1234567
Call-ID: 12345601@subA.example.com
CSeq: 1000 NOTIFYSome time elapses (8) ⏳ literally just vibing
The user types in their input 📱 Then the device sends the collected digits over in message (9). Since this was a one-shot subscription, look at that Subscription-State: it says "terminated" 💀 Bye bye subscription 👋
NOTIFY sip:ap@client.subB.example.com SIP/2.0
Via: SIP/2.0/UDP subA.example.com;branch=gw27id4993
To: <sip:ap@subB.example.com>;tag=567890
From: <sip:gw@subA.example.com>;tag=1234567
Call-ID: 12345601@subA.example.com
CSeq: 1001 NOTIFY
Contact: <sip:gw27@subA.example.com>
Event: kpml
Subscription-State: terminated
Max-Forwards: 70
Content-Type: application/kpml-response+xml
Content-Length: 258
<?xml version="1.0" encoding="UTF-8"?>
<kpml-response xmlns="urn:ietf:params:xml:ns:kpml-response"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"urn:ietf:params:xml:ns:kpml-response kpml-response.xsd"
version="1.0"
code="200" text="OK"
digits="4336"/>Message (10) is the 200 OK that acknowledges that notification, and it's a wrap on this one 🎬
SIP/2.0 200 OK
Via: SIP/2.0/TCP subA.example.com;branch=gw27id4993
To: <sip:ap@subB.example.com>;tag=567890
From: <sip:gw@subA.example.com>;tag=1234567
Call-ID: 12345601@subA.example.com
CSeq: 1001 NOTIFY10.2. Multiple Applications 🌈
Also non-normative (just an example, no rules here 🙈). Here one app collects a destination number to call. That app then waits for a "long pound." During the call, the call gets routed to a personal assistant app that chats with the user 💁♀️ And on top of that, the personal assistant is also watching for a "short pound." Multi-app energy, iconic 👑
For clarity, we're not showing the INVITE dialogs in this one 🦋
Okay so this is the whole multiple application call flow, and it's giving full choreography 💃 The gateway is juggling a card application and a personal assistant at the same time, and every single message has a job. Let's go 🦋
Figure 27 shows the whole dance, from the first SUBSCRIBE to the last NOTIFY.
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) |
|--------------------->| |
| | |
| | |
|(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) | |
|.............................................|
| | |
| | |
|(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: <sip:ap@subB.example.com>;tag=978675
To: <sip:gw@subA.example.com>
Call-ID: 12345601@subA.example.com
CSeq: 20 SUBSCRIBE
Contact: <sip:ap@client.subB.example.com>
Max-Forwards: 70
Event: kpml ;remote-tag="<sip:phn@example.com;tag=jfi23>"
;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
<?xml version="1.0" encoding="UTF-8"?>
<kpml-request xmlns="urn:ietf:params:xml:ns:kpml-request"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"urn:ietf:params:xml:ns:kpml-request kpml-request.xsd"
version="1.0">
<pattern persist="persist">
<regex tag="card">x{16}</regex>
<regex tag="number">x{10}</regex>
</pattern>
</kpml-request>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: <sip:ap@subB.example.com>;tag=978675
From: <sip:gw@subA.example.com>;tag=9783453
Call-ID: 12345601@subA.example.com
CSeq: 3001 NOTIFY
Contact: <sip:gw27@subA.example.com>
Event: kpml
Subscription-State: active;expires=3442
Max-Forwards: 70
Content-Type: application/kpml-response+xml
Content-Length: 271
<?xml version="1.0" encoding="UTF-8"?>
<kpml-response xmlns="urn:ietf:params:xml:ns:kpml-response"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"urn:ietf:params:xml:ns:kpml-response kpml-response.xsd"
version="1.0"
code="200" text="OK"
digits="9999888877776666"/>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: <sip:ap@subB.example.com>;tag=978675
From: <sip:gw@subA.example.com>;tag=9783453
Call-ID: 12345601@subA.example.com
CSeq: 3001 NOTIFY
Contact: <sip:gw27@subA.example.com>
Event: kpml
Subscription-State: active;expires=3542
Max-Forwards: 70
Content-Type: application/kpml-response+xml
Content-Length: 278
<?xml version="1.0" encoding="UTF-8"?>
<kpml-response xmlns="urn:ietf:params:xml:ns:kpml-response"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"urn:ietf:params:xml:ns:kpml-response kpml-response.xsd"
version="1.0"
code="200" text="OK"
digits="2225551212" tag="number"/>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: <sip:ap@subB.example.com>;tag=978675
To: <sip:gw@subA.example.com>
Call-ID: 12345601@subA.example.com
CSeq: 21 SUBSCRIBE
Contact: <sip:ap@client.subB.example.com>
Max-Forwards: 70
Event: kpml ;remote-tag="<sip:phn@example.com;tag=jfi23>"
;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
<?xml version="1.0" encoding="UTF-8"?>
<kpml-request xmlns="urn:ietf:params:xml:ns:kpml-request"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"urn:ietf:params:xml:ns:kpml-request kpml-request.xsd"
version="1.0">
<pattern persist="single-notify">
<regex>L#</regex>
</pattern>
</kpml-request>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: <sip:pa@example.com>;tag=4rgj0f
To: <sip:gw@subA.example.com>
Call-ID: 93845@pahost.example.com
CSeq: 21 SUBSCRIBE
Contact: <sip:pa12@pahost.example.com>
Max-Forwards: 70
Event: kpml ;remote-tag="<sip:phn@example.com;tag=jfi23>"
;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
<?xml version="1.0" encoding="UTF-8"?>
<kpml-request xmlns="urn:ietf:params:xml:ns:kpml-request"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"urn:ietf:params:xml:ns:kpml-request kpml-request.xsd"
version="1.0">
<pattern persist="persist">
<regex tag="number">x{10}</regex>
<regex tag="#">#</regex>
</pattern>
</kpml-request>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: <sip:pa@example.com>;tag=4rgj0f
From: <sip:gw@subA.example.com>;tag=9788823
Call-ID: 93845@pahost.example.com
CSeq: 3021 NOTIFY
Contact: <sip:gw27@subA.example.com>
Event: kpml
Subscription-State: active;expires=3540
Max-Forwards: 70
Content-Type: application/kpml-response+xml
Content-Length: 27811. References 📚
bestie, this is the reading list 🧚 Some of these are the must-read foundations and some are just context, and I've sorted them into normative and informative so you know which ones are actually load-bearing.
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.
[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.
Appendix A. Contributors 🎀
Ophir Frieder of the Illinois Institute of Technology collaborated on the development of the buffer algorithm. Iconic behind-the-scenes energy ✨
Jeff Van Dyke worked enough hours and wrote enough text to be considered an author under the old rules. Literally a whole authorship arc 😭
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. The squad 👑
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. The support system we all need 🫶
That said, any errors, misinterpretation, or fouls in this document are our own. Accountability is giving 💅
Appendix B. Acknowledgements 🌈
Hal Purdy and Eric Cheung of AT&T Laboratories helped immensely through many conversations and challenges. Real ones 🙌
Steve Fisher of AT&T Laboratories suggested the digit suppression syntax and provided excellent review of the document. Brilliant brain moment 🧠✨
Terence Lobo of SnowShore Networks made it all work. The one who made it happen 🔥
Jerry Kamitses, Swati Dhuleshia, Shaun Bharrat, Sunil Menon, and Bryan Hill helped with clarifying the buffer behavior and DRegex syntax. Clarity queens 👑
Silvano Brewster and Bill Fenner of AT&T Laboratories and Joe Zebarth of Nortel helped considerably with making the text clear and DRegex tight. Tight and clear, no notes 💜
Bert Culpepper and Allison Mankin gave an early version of this document a good scouring. Early review that really went in 🧽
Scott Hollenbeck provided XML and MIME review. Tim Bray pointed out the general issue of UTF-8 versus UTF-16 with XML. Encoding drama, but make it educational 🍓
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
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. Thank you to the people keeping the lights on ✨
📦 where this page comes from
- ietf: rfc4730 2006-11
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms