RFC 4596
Guidelines for Usage of the Session Initiation Protocol (SIP) Caller Preferences Extension
RFC 4596: Guidelines for Usage of the Session Initiation Protocol (SIP) Caller Preferences Extension 🎀
Okay bestie, this one is by J. Rosenberg and P. Kyzivat, both from Cisco Systems, and it's an Informational doc in the Network Working Group, dated July 2006. Its title block doesn't list anything it obsoletes or updates. 🦋
Status of This Memo 📜
This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited.
Copyright Notice ©️
Copyright (C) The Internet Society (2006).
Abstract 💅
This document contains guidelines for usage of the Caller Preferences Extension to the Session Initiation Protocol (SIP). It demonstrates the benefits of caller preferences with specific example applications, provides use cases to show proper operation, provides guidance on the applicability of the registered feature tags, and describes a straightforward implementation of the preference and capability matching algorithm specified in Section 7.2 of RFC 3841. ✨
Table of Contents 🗂️
1. Introduction ....................................................4
2. Motivations for Caller Preferences ..............................5
2.1. One-Number .................................................7
2.2. Direct-to-Voicemail ........................................7
3. Caller Preference Use Cases .....................................8
3.1. Routing of INVITE and MESSAGE to Different UA ..............8
3.1.1. Desired Behavior ....................................8
3.1.2. Solution ............................................9
3.2. Single Contact Not Matching Implicit Preferences ..........10
3.2.1. Desired Behavior ...................................10
3.2.2. Solution ...........................................10
3.3. Package-Based Routing .....................................11
3.3.1. Desired Behavior ...................................11
3.3.2. Solution ...........................................11
3.4. Package Routing II ........................................12
3.4.1. Desired Behavior ...................................12
3.4.2. Solution ...........................................13
3.5. Audio/Video vs. Audio Only ................................13
3.5.1. Desired Behavior ...................................13
3.5.2. Solution ...........................................14
3.6. Forcing Audio/Video .......................................15
3.6.1. Desired Behavior ...................................15
3.6.2. Solution ...........................................15
3.7. Third-Party Call Control: Forcing Media ...................16
3.7.1. Desired Behavior ...................................16
3.7.2. Solution ...........................................16
3.8. Maximizing Media Overlaps .................................17
3.8.1. Desired Behavior ...................................17
3.8.2. Solution ...........................................17
3.9. Multilingual Lines ........................................18
3.9.1. Desired Behavior ...................................18
3.9.2. Solution ...........................................19
3.10. I Hate Voicemail! ........................................20
3.10.1. Desired Behavior ..................................20
3.10.2. Solution ..........................................20
3.11. I Hate People! ...........................................21
3.11.1. Desired Behavior ..................................21
3.11.2. Solution ..........................................21
3.12. Prefer Voicemail .........................................22
3.12.1. Desired Behavior ..................................22
3.12.2. Solution ..........................................22
3.13. Routing to an Executive ..................................22
3.13.1. Desired Behavior ..................................22
3.13.2. Solution ..........................................22
3.14. Speak to the Executive ...................................23
3.14.1. Desired Behavior ..................................23
3.14.2. Solution ..........................................24
3.15. Mobile Phone Only ........................................24
3.15.1. Desired Behavior ..................................24
3.15.2. Solution ..........................................24
3.16. Simultaneous Languages ...................................25
3.16.1. Desired Behavior ..................................25
3.16.2. Solution ..........................................25
3.17. The Number You Have Called... ............................26
3.17.1. Desired Behavior ..................................26
3.17.2. Solution ..........................................26
3.18. The Number You Have Called, Take Two .....................27
3.18.1. Desired Behavior ..................................27
3.18.2. Solution ..........................................27
3.19. Forwarding to a Colleague ................................28
3.19.1. Desired Behavior ..................................28
3.19.2. Solution ..........................................28
4. Capability Use Cases ...........................................30
4.1. Web Redirect ..............................................30
4.2. Voicemail Icon ............................................30
5. Usage of the Feature Tags ......................................31
5.1. Traditional Cell Phone ....................................31
5.2. Traditional Work Phone ....................................32
5.3. PC Messaging Application ..................................32
5.4. Standalone Videophone .....................................33
6. Example of Implementation of Preference and Capability
Matching .......................................................33
6.1. Extracting a Feature Set from a Header ....................34
6.2. Extracting Values from a Feature Parameter ................35
6.3. Comparing Two Value-Ranges ................................36
6.4. Feature Set to Feature Set Matching .......................36
6.5. Selecting and Ordering Contacts Based on Caller
Preferences ...............................................37
6.5.1. Reject-Contact Processing ..........................37
6.5.2. Accept-Contact Processing ..........................37
7. Security Considerations ........................................38
8. Acknowledgements ...............................................38
9. Informative References .........................................381. Introduction 💖
Okay so, the Session Initiation Protocol (SIP) [1] extension for Callee Capabilities [2] is what lets a UA (User Agent) register its capabilities in a REGISTER request. 🧚 A caller can express preferences about how that request gets handled, either explicitly or implicitly. The way it works is through the Accept-Contact and Reject-Contact header fields, which are described in Caller Preferences for the Session Initiation Protocol [3]. 💅
The caller preferences extension is seriously useful for lots of applications. Ngl though, its generality makes it hard to use correctly in any one situation. 😭 So this document is basically a compendium of examples showing how to use the caller preferences extension, bestie. 🫶
NOTE: This document is intended to assist the reader in understanding RFCs 3840 and 3841. It is not intended to serve as a substitute for reading those documents. The examples presented in this document cannot be fully understood without awareness of the mechanisms defined in RFCs 3840 and 3841. 🙈
Here's the game plan. Section 2 shows off the benefits of caller preferences by describing several concrete applications the extension enables. 🌈 Section 3 is the big one: a set of detailed use cases for expressing caller preferences. Each use case presents a situation, describes how caller preferences can handle its requirements, and checks that the desired behavior happens by showing the results of the matching operation. These use cases prove that the caller preferences specification is complete and can meet a specific set of requirements. 🔥
Now here's the tea. The caller preferences specification predates the SIP change process [4], so no requirements document was ever published for it. Iykyk, right? So this document kind of "backfills" the requirements. 👑 It's not just an academic exercise though, because the use cases in here actually led to changes in the caller preferences document as it evolved. These use cases also help implementors figure out how to use caller preferences in their own applications. 🍓
Section 4 talks about applications for the callee capabilities specification. Section 5 covers the example registrations of the feature tags described in [2]. Proper usage of the caller preferences extension depends on correctly interpreting what these tags mean, so Section 5 gives more detail on the tags and includes example registrations that show typical usage. ✨
Last but not least, Section 6 outlines an implementation approach to the matching algorithm that doesn't require RFC 2533 [6] to be implemented in all its generality. 🦋
2. Motivations for Caller Preferences ✨
okay so SIP is literally all about rendezvous, which means getting users to meet up 💖 The caller and callee need to find each other so they can swap session information and actually talk. The tricky part is that a user has multiple points of attachment to the network. A called user (callee) can have a cell phone, a PDA, a work phone, a home phone, and one of several PC-based communications applications 📱 So when someone calls that user, which of these devices gets the call? 🤔
Obviously the call can ring all of them at the same time, a process known as parallel forking 🌸 But that's not always the vibe. Users may prefer that their registered devices be tried in a particular order. Like, one user might want his cell phone to ring first, and if no one answers, his work phone next. Another user might want her cell phone to ring first, then her home and work phones to ring at the same time, and then, if no one answers either of those, the call to get forwarded to voicemail 📞 These variations are all referred to as find-me/follow-me features 🎀
SIP supports find-me/follow-me features in lots of ways 💅 The most basic one is the SIP registration process. Each device where a user can be contacted registers with the network. This registration associates the device with the canonical name of the user, called the address-of-record (AOR), which is a SIP URI. Each registration can include a preference value, which shows the relative preference for receiving calls at that device compared to other devices. When someone calls the AOR, proxies compliant to RFC 3261 will try the registered devices in order of preference, unless administrative policy overrides user preferences 🌈
Preference values in SIP registrations can only do the basic find-me/follow-me stuff, though 🥺 To get more complex features, the Call Processing Language (CPL) [5] was specified. It's an XML script that gives specific call routing instructions. Users can upload these scripts to the network, which tells the servers how calls should be routed. For example, a CPL script can tell a proxy to route a call to the work phone during work hours (9 am - 5 pm) and then to the cell phone after hours, unless the call is from a family member, in which case it always goes to the cell phone 👑
It's really important to notice that both CPL scripts and preference values in registrations describe how a service works from the perspective of the called party. In other words, they describe how a call made to the called party should be routed by the network. BUT the called party isn't the only one with preferences 👀 A caller has preferences too, about how they want their call routed. For example, a caller will often want to reach a user on their cell phone. In the current telephone network, this is handled by making a user have a separate number for each device. So when a caller wants the cell phone, they dial the cell phone's number. That means users have to maintain lists of potential reach numbers and then pick the right one 😩 A way better approach is for a user to maintain a single address-of-record. When someone wants to reach them on their cell phone, they call the AOR but indicate a preference for the call to be routed to the cell phone ✨
A caller can actually have a whole range of preferences for how a call gets routed 💜 They might prefer to go right to voicemail. They might prefer never to reach voicemail. They might prefer to reach the user on a device that supports video (because they want a video conference). They might want to reach a device with an attendant who can answer if the user isn't there 🙈
The SIP caller preferences extension lets a caller express these preferences for how their calls are handled. The preferences are expressed in terms of properties of the desired device. These properties are name-value pairs that convey some kind of information about a device. One example is the property mobility, which can have the values mobile or fixed 🦋 When a caller wants to reach a cell phone, they include information in their call setup request (the INVITE method) that says the call should be routed to a device with the property mobility set to mobile. When devices register with the network, they include their properties (also known as callee capabilities) as part of the registration. That way, a proxy can match the caller's preferences against the capabilities of the various devices registered to the user and route the call appropriately 🧚
Now, this document is about a caller's preferences, but it looks at them from the perspective of a SIP User Agent representing the caller 💅 Caller preferences are represented here by syntactic elements placed in a SIP request. This document does not try to cover how a human user tells the User Agent what they want. So this document is probably going to be most useful for the developer of a User Agent 🫶
The caller preferences extension can support a wide variety of call routing applications and features. Two especially important examples are "one-number" and "direct-to-voicemail" 🌸
2.1. One-Number
In today's circuit-switched telephony networks, users have multiple devices, and each device has its own phone number 📇 A user will usually list all of these numbers on a business card: cell phone, work phone, home office phone, and so on. Other people have to store and manage all of those numbers, and it's hard to keep them complete and up-to-date. Worse, when you want to call someone, you have to pick which number to try 😵 Sometimes you want a specific device (the cell phone), and other times you just want to reach them wherever they are. In that second case, you're forced to try each number one at a time. That's inefficient, and really hard to do while driving, for example 🚗
The alternative is that a user has a single address. It's the one and only address they put on their business cards. If a caller wants to reach that user on their cell phone, they select that one address, then open a pull-down menu of device types. This menu would include home phone, work phone, and cell phone. The caller picks cell-phone, and the call is placed to the cell phone 📲 There's no need to manage or maintain more than one number for the user, because a single number will do the job 💖
On the other hand, if the caller wants to reach the user wherever they are, they call that one number without picking a preferred device. The network rings all the devices at the same time, so the user gets reached as fast as possible ⚡
This one-number service makes use of caller preferences. To express a preference for the cell phone, the caller's device would include a header in the SIP INVITE request, indicating a desire to reach a device with mobility equal to mobile 🎀
2.2. Direct-to-Voicemail
Honestly, a busy executive on the road wants to pass a message to a colleague by voice all the time 🏃♀️ For example, a boss might want to tell an employee to call a specific customer and resolve a pending issue. In that case, the user doesn't actually want to talk to the person. They just want to leave a voice message. A phone conversation can take too long, while a voice message can be quick and to the point. The voice message can also serve as a record of exactly what's wanted, whereas a fleeting conversation can be forgotten or misremembered 🧠
In today's circuit-switched telephone networks, there's often no way to go directly to someone's voicemail and leave a message 😤 Sometimes you can dial the main number for the voicemail system, enter the extension of the person you want, and leave a message by pressing a specific prompt. That's time consuming, and it requires the caller to know the main voicemail number.
Instead, an address book in a cell phone can have an option called "leave voice message", available for each entry in the address book 📱 When someone selects this option, a call goes directly to that user's voicemail, which picks up right away and prompts for a message. In fact, a rapid greeting plays, so the caller can go straight to the recording procedure 🏃
This saves the caller a ton of time, which makes it super easy to quickly leave recorded messages for a large number of people 💅
This feature is possible using the caller preferences extension 🌈 When the user selects the "leave voice message" option, the phone sends a SIP INVITE request and includes a caller preferences header field that indicates a preference for devices whose msgserver attribute has a value of true. This makes the proxy route the call directly to a registered voicemail service. Furthermore, the voicemail server sees that the caller asked to go directly to voicemail, so it can play an abbreviated greeting that's designed specifically for this case 🫶
3. Caller Preference Use Cases 🦋
Each use case is described as a situation along with a desired behavior. Then it shows how the various caller preferences headers and the proxy processing logic would lead to the right decision 💜
3.1. Routing of INVITE and MESSAGE to Different UA
3.1.1. Desired Behavior
okay so picture this 👀 Address of Record (AOR) Y has two contacts, Y1 and Y2. Y1 is a phone and supports the standard operations INVITE, ACK, OPTIONS, BYE, and CANCEL, but it does not support MESSAGE. Y2 is a pager and supports only OPTIONS and MESSAGE 📟 Caller X wants to send pages to Y. There's a lot of traffic on the network, with both calls and pages, so the goal is to avoid unnecessarily forking messages to devices that can't support them 🙅♀️ So the plan is to make sure that INVITEs to Y go only to Y1, while MESSAGEs to Y go only to Y2 🔥
3.1.2. Solution ✨
Okay bestie, so Y1 makes a registration that looks like this (just the juicy bits) 💅:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact:<sip:Y1@pc.example.com>
;methods="INVITE,ACK,OPTIONS,BYE,CANCEL"
;uri-user="<Y1>"
;uri-domain="example.com"
;audio
;schemes="sip"
;mobility="mobile"And Y2 makes its own registration, also just the highlights 🦋:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y2@pc.example.com>
;methods="OPTIONS,MESSAGE"
;uri-user="<Y2>"
;uri-domain="example.com"
;+sip.message
;schemes="sip,im"
;mobility="mobile"When a UAC (User Agent Client) sends an INVITE, it shows up at the proxy for example.com. There are no caller preferences in the request 🙈 BUT per Section 7.2.2 of [3], the proxy builds its own implicit require-flagged Accept-Contact preference, which looks like:
(& (sip.methods="INVITE"))Now the proxy runs the matching algorithm from RFC 2533 [6] on this feature set and the ones Y1 and Y2 registered. Only Y1's feature set matches. Because the Accept-Contact predicate has its require flag set, Y2 gets discarded, and the INVITE is routed to Y1. Iconic, honestly 👑
If the request is a MESSAGE, the proxy builds an implicit Accept-Contact preference with its require flag set (require-flagged) that looks like:
(& (sip.methods="MESSAGE"))This matches Y2's feature set but not Y1's. So Y1 gets discarded, and the request goes to Y2. Main character energy 💜
3.2. Single Contact Not Matching Implicit Preferences
3.2.1. Desired Behavior
AOR Y has a single contact, Y1. It's a phone, so it supports the standard operations INVITE, ACK, OPTIONS, BYE, and CANCEL, but it does not support MESSAGE 📞 A caller X sends a MESSAGE request. The desired behavior is that the request still gets routed to that one solitary contact so it can generate a 405 response. Poor phone, but we respect the process 🫶
3.2.2. Solution
The single contact Y1 generates a registration that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y1@pc.example.com>
;methods="INVITE,ACK,OPTIONS,BYE,CANCEL"
;uri-user="<Y1>"
;uri-domain="example.com"
;audio
;schemes="sip"
;mobility="fixed"
;class="personal"X sends a MESSAGE request. There are no explicit caller preferences, so this results in an implicit require-flagged Accept-Contact preference:
(& (sip.methods="MESSAGE"))Y1 doesn't match, and the Accept-Contact predicate is require-flagged, so Y1 gets discarded. BUT according to Section 7.2.4 of RFC 3841, if there are no matching targets, the original target set is used 🥹 So the request goes to the one original target, Y1, just like we wanted. Y1 then responds with a 405 💀
If there were multiple contacts and none of them matched the Accept-Contact predicate, the original target set including all of the contacts would be restored. Then all of the contacts get processed according to Section 16.6 of RFC 3261. Everyone gets a turn 🌸
3.3. Package-Based Routing
3.3.1. Desired Behavior
AOR Y has a bunch of contacts, Y1, Y2, ..., Yn, that can each support the standard operations INVITE, ACK, OPTIONS, BYE, and CANCEL. They can also support SUBSCRIBE for the "dialog" event package [7]. Y also has another contact, Yp, which is a presence agent (PA) [8]. It can accept only SUBSCRIBE requests for the "presence" event package.
The goal: SUBSCRIBE requests for presence go to Yp, while INVITEs and SUBSCRIBEs for the dialog package get forked to Y1...Yn. Sorted, bestie ✨
3.3.2. Solution
Y1..Yn generate REGISTER requests that look like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Yi@pc.example.com>
;methods="INVITE,BYE,OPTIONS,ACK,CANCEL,SUBSCRIBE"
;events="dialog"
;uri-user="<Yi>"
;uri-domain="example.com"
;audio
;schemes="sip"
;mobility="fixed"
;class="personal"And Yp generates a REGISTER request that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Yp@pc.example.com>;methods="SUBSCRIBE"
;events="presence"
;uri-user="<Yp>"
;uri-domain="example.com"
;schemes="sip,pres"
;mobility="fixed"
;class="business"A SUBSCRIBE request for presence arrives at the proxy for example.com. Since there are no explicit preferences, the proxy builds an implicit require-flagged Accept-Contact preference from the request:
(& (sip.methods="SUBSCRIBE") (sip.events="presence"))Following Section 7.2.4 of RFC 3841, this feature set only matches the one registered by Yp. Because the require flag is set, the contacts that don't match get removed from the target set. So Y1..Yn are discarded, and the request goes to the remaining contact, Yp, which represents the PA 🧚
An INVITE request without explicit preferences results in an implicit require-flagged Accept-Contact preference:
(& (sip.methods="INVITE"))This implicit Accept-Contact feature set matches Y1..Yn but does not match Yp. Using the scoring algorithm from Section 7.2.4 of RFC 3841, the score for Y1..Yn against this predicate is 1.0. As a result, the caller preference Qa for each contact is 1.0. The registrations didn't contain q-values, so the default q-value of 1.0 gets applied to each Contact URI. Since the caller and callee preferences are the same and all equal 1.0, there's no reordering of contacts. The proxy will consider Y1..Yn as equally good targets for the request, and it might fork the request to each one 🔥
A SUBSCRIBE request for the dialog event package without explicit preferences results in an implicit require-flagged Accept-Contact preference:
(& (sip.methods="SUBSCRIBE") (sip.events="dialog"))This only matches Y1..Yn, so Yp gets discarded, and the request is routed to the remaining contacts just like the INVITE was 💖
3.4. Package Routing II
3.4.1. Desired Behavior
This case is nearly identical to Section 3.3. The difference is that Y1..Yn omit the "events" feature tag from their registration. Yp registers as in Section 3.3. A SUBSCRIBE for the presence event package should still preferentially route to Yp 🌈
3.4.2. Solution
The registration from Y1..Yn looks like:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Yi@pc.example.com>
;methods="INVITE,BYE,OPTIONS,ACK,CANCEL,SUBSCRIBE"
;uri-user="<Yi>"
;uri-domain="example.com"
;audio
;schemes="sip"
;mobility="fixed"
;class="personal"When the caller sends a SUBSCRIBE for the presence event package (without explicit preferences), the proxy computes an implicit preference:
(& (sip.methods="SUBSCRIBE") (sip.events="presence"))This predicate matches Y1..Yn and Yp. However, the score for Y1..Yn against this predicate is 0.5, and the score for Yp is 1.0. That gives a caller preference Qa of 0.5 for Y1..Yn, and a caller preference Qa of 1.0 for Yp. Since the callee provided no q-values, the proxy assumes a default of 1.0. So all contacts are in the same equivalence class. They then get sorted by Qa, so Yp comes first, followed by Y1 through Yn. The proxy routes the request to Yp first, and if that fails, to Y1..Yn. Yp gets the spotlight 👑
3.5. Audio/Video vs. Audio Only
3.5.1. Desired Behavior
X sends an invitation to Y to start an audio/video call, including both m=audio and m=video lines in the SDP 🎀 AOR Y has two contacts, Y1 and Y2. Y1 is a normal audio phone, and it's where Y prefers to receive calls. It will answer an audio/video call but refuse the video. Y2 is an audio/video phone that should only be used when needed. The caller really wants the call answered by a device that supports video, but will accept an audio-only call as a second choice 🫠
3.5.2. Solution
Y1 generates a registration that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y1@pc.example.com>;q=1.0
;methods="INVITE,BYE,OPTIONS,ACK,CANCEL"
;uri-user="<Y1>"
;uri-domain="example.com"
;audio
;schemes="sip,tel"
;mobility="fixed"
;class="business"Y2 generates a registration that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y2@pc.example.com>;q=0.6
;methods="INVITE,BYE,OPTIONS,ACK,CANCEL"
;uri-user="<Y2>"
;uri-domain="example.com"
;audio
;video
;schemes="sip,tel"
;mobility="fixed"
;class="business"Notice the different q-values! That lets Y2 be picked as a device of "last resort" 🥺
To have the call preferentially routed to a device that supports video, the caller X sends an INVITE that looks like, in part:
INVITE sip:Y@example.com SIP/2.0
Accept-Contact: *
;methods="INVITE"
;videoThe proxy converts this into a feature set. That feature set matches Y2 and Y1. However, the score for Y2 is 1.0, and the score for Y1 is 0.5. The two contacts get ordered by q-value and broken into equivalence classes. There are two equivalence classes, each with one contact. So the caller preference values have no impact on the ordering. The call tries the higher-priority Y1 first, which answers the call and rejects the video stream. So the desired behavior is not achieved 😭
The desired behavior could be achieved by adding the "explicit" and "require" tags to the Accept-Contact header field in the INVITE, as is done in Section 3.6. However, doing so may result in calls failing when they could occur, just without video. As discussed in [3], both the "require" and "explicit" tags are generally used only when the request cannot be serviced in any way unless the preferences are met. That isn't the case here 🙅
3.6. Forcing Audio/Video
3.6.1. Desired Behavior
This case is similar to Section 3.5. The difference is that X requires an audio/video call and would like the call to fail if that isn't possible, rather than succeed with audio only 💅
3.6.2. Solution
The solution is similar to Section 3.5, except the Accept-Contact header field now includes the "explicit" and "require" tags. That guarantees the call is never established with any UA that hasn't explicitly indicated support for video:
INVITE sip:Y@example.com SIP/2.0
Accept-Contact: *;video;require;explicitThis arrives at the example.com proxy. This explicit feature set matches the feature sets for Y2 and Y1. However, the match for Y1 did not have a score of 1. Since the "explicit" and "require" tags are present, Y1 gets discarded. That leaves only Y2. The call gets routed to the videophone, and if the user isn't there, the audio phone never rings 🎬
Because both the "require" and "explicit" flags are present, a contact also gets discarded if it doesn't include a feature tag indicating support for video. So a UA that can do video but forgot to say so would not be reached in this case. This is why it's important for a UA to indicate all of its capabilities 🧠 Note that this only applies to a contact that indicated some capabilities but not video. Contacts that don't indicate any capabilities are "immune" from caller preferences filtering and would not be discarded ✨
3.7. Third-Party Call Control: Forcing Media ✨
3.7.1. Desired Behavior
okay so Z is a third-party call control controller (3pcc) [9] 🎀 and Z is trying to set up an audio/video call from X to Y. X has contacts X1 and X2, and Y has contacts Y1 and Y2. X1 and X2 have capabilities identical to Y1 and Y2, respectively. Z needs to send an offerless invite to X and then use the offer X proposes to send an invite to Y. When Z sends the offerless invite to X, the 3pcc controller must ensure that an audio/video contact (X2) is chosen over an audio only contact (X1) 💅
3.7.2. Solution
X1 will generate a registration that looks like this, in part: 🌸
REGISTER sip:example.com SIP/2.0
To: sip:X@example.com
Contact: <sip:X1@pc.example.com>;q=1.0
;methods="INVITE,BYE,OPTIONS,ACK,CANCEL"
;uri-user="<X1>"
;uri-domain="example.com"
;audio
;schemes="sip,tel"
;mobility="fixed"
;class="business"X2 will generate a registration that looks like this, in part: 🦋
REGISTER sip:example.com SIP/2.0
To: sip:X@example.com
Contact: <sip:X2@pc.example.com>;q=0.6
;methods="INVITE,BYE,OPTIONS,ACK,CANCEL"
;uri-user="<X2>"
;uri-domain="example.com"
;audio
;video
;schemes="sip,tel"
;mobility="fixed"
;class="business"Z would put an Accept-Contact header field in its INVITE, like this: 🧚
INVITE sip:X@example.com SIP/2.0
Accept-Contact: *;audio;video;require;explicitThis caller preference matches both X1 and X2. However, it matches X1 with a score of .5 and X2 with a score of 1. Because of the "require" and "explicit" tags, X1 gets discarded even though X prefers it 🙈 So the call is routed to X2. Iconic! 👑
The same caveats apply here as they do in Section 3.6. Generally, it is not advisable to mandate support for features (such as video) that are not strictly necessary for the request to proceed. Don't make the call pick a feature it doesn't actually need, bestie 💀
3.8. Maximizing Media Overlaps ✨
3.8.1. Desired Behavior
okay so AOR Y has two contacts: Y1, which is a regular audio phone, and Y2, which is a PC capable of supporting both audio and session-oriented IM [10] 💻 X is a PC that can handle audio, video, and session-oriented IM. X calls Y to start a voice call. However, X wants to connect to the device with the maximal overlap with its media capabilities, so the caller gets the most functionality possible 🌈
3.8.2. Solution
Y1 will generate a registration that looks like this, in part: 🍓
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y1@phone.example.com>
;methods="INVITE,BYE,OPTIONS,ACK,CANCEL"
;uri-user="<Y1>"
;uri-domain="example.com"
;audio
;schemes="sip,tel"
;mobility="fixed"
;class="business"Y2 will generate a registration that looks like this, in part: 💜
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y2@pc.example.com>
;methods="INVITE,BYE,OPTIONS,ACK,CANCEL,MESSAGE"
;uri-user="<Y2>"
;uri-domain="example.com"
;audio
;+sip.message
;schemes="sip,tel"
;mobility="fixed"
;class="business"The solution needs the caller to support caller preferences. The caller would put an Accept-Contact header field in their INVITE that lists every media type they support. In this case: ✨
INVITE sip:Y@example.com SIP/2.0
Accept-Contact: *;audio;video;+sip.messageBoth Y1 and Y2 match the predicate. Y1 matches with a score of 0.33, and Y2 matches with a score of 0.66. Since there is only one Accept-Contact predicate, the Qa for each contact is equal to the score. The registered contacts are then sorted by q-value and broken into equivalence classes. There is a single equivalence class with a q-value of 1.0. The two contacts in that class get re-ordered based on the values of Qa. Y2 has a higher Qa, so it is used first, followed by Y1. The result is that the call goes to the device with the maximum overlap in media capabilities, just like we wanted 🔥
Note that neither "require" nor "explicit" tags are used, because there is no intent to exclude contacts, only to order them. Nobody's getting kicked out of the group chat here 🫶
3.9. Multilingual Lines ✨
3.9.1. Desired Behavior
okay so AOR Y represents a shared line in an office. Several employees in the office have phones registered for Y. Some of them speak only English, some speak Spanish fluently and have some limited ability in English, and some speak both English and Spanish fluently. Calls from callers who speak only English should be parallel forked to all office workers who speak fluent English. If the call isn't picked up, then the phones of workers who speak English marginally should be rung. Calls from callers who speak only Spanish should be forked only to workers who speak Spanish 🌎
3.9.2. Solution
A user at phone Y1 who speaks English only would generate a REGISTER that looks like this, in part: 🎀
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y1@pc.example.com>;languages="en"A user at phone Y2 who speaks Spanish and a little bit of English would generate a REGISTER that looks like this, in part: 🌺
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y2-es@pc2.example.com>;languages="es"
Contact: <sip:Y2-en@pc2.example.com>;languages="en";q=0.2Y2 has registered two contacts. Both of them route to the same device (pc2.example.com), but they differ in language support and relative q-values. Multiple contacts are needed whenever a UA wants to express differing preferences for being reached for different feature collections. It's giving multi-personality energy 🦋
A user at phone Y3 who speaks English and Spanish fluently would generate a REGISTER that looks like this, in part: 🧚
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y3@pc3.example.com>;languages="es,en"Notice that only a single contact is needed, because the same q-value is applied across all feature collections. Efficient and iconic 💅
For the language-based routing to happen, the caller has to indicate its language preferences explicitly: 🫶
INVITE sip:Y@example.com SIP/2.0
Accept-Contact: *;languages="en";requireThe predicate derived from this looks like this:
(& (languages="en"))This matches the one contact for Y1, the second contact registered by Y2, and the one contact for Y3, all with a score of 1.0. The first contact registered by Y2 doesn't match, and because of the "require" flag, it's discarded. The remaining contacts are sorted by q-value and divided into equivalence classes. There are two equivalence classes. The first contains Y1 and Y3 with a q-value of 1.0, and the second contains Y2-en with a q-value of 0.2. The contacts in the first class are ordered by Qa. However, since all of them have the same Qa value (1.0), the ordering doesn't change. So Y1 and Y3 are tried first, followed by Y2-en. This is the desired behavior 🎉
An "explicit" tag is not used, because that would exclude a contact that doesn't mention language at all 🙅♀️
A caller who speaks Spanish only would specify their preference like this: 🌹
INVITE sip:Y@example.com SIP/2.0
Accept-Contact: *;languages="es";requireThis matches the first contact of Y2 phones and Y3 phones, all with a score of 1.0. The English contact of Y2, Y2-en, doesn't match and is discarded because of the "require" flag. The remaining contacts are sorted by q-value (Y3, Y2-es) and placed into a single equivalence class containing both contacts. Since the Qa for both contacts is the same (1.0), there is no reordering. The result is that the call is routed to either Y3 or Y2-es ✨
3.10. I Hate Voicemail! 🙄
3.10.1. Desired Behavior
okay so AOR Y has two contacts, a phone Y1 and a voicemail service Y2. X wants to call Y and talk in person. X does not want to be sent to voicemail under any circumstances. Absolutely not, no cap 🚫📞
3.10.2. Solution
The phone would register with a Contact that looks like this, in part: 📱
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y1@pc.example.com>
;audio
;mobility="fixed"and the voicemail server would register with a Contact that looks like this, in part: 📼
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y2@pc.example.com>
;msgserver
;automata
;attendant
;audio
;q=0.2The voicemail server registers with a lower q-value so that it only gets used after the phone itself has rung. Note that the voicemail server doesn't actually need to register. There can be a configured contact and feature set defined for it instead 🌸
A caller who wants to avoid voicemail can include an explicit preference to avoid it. A caller would do this with the Reject-Contact header field: 🙅♀️
INVITE sip:Y@example.com SIP/2.0
Reject-Contact: *;msgserverSince this feature set contains a feature tag that isn't in the registration for Y1, the feature set is discarded when examining Y1. However, the registration for Y2 contains all the feature tags listed in the feature set, so the rule is considered. There is a match, and therefore Y2 is discarded. The result is that the user is never routed to voicemail. Main character energy 👑
3.11. I Hate People! 🙈
3.11.1. Desired Behavior
The situation is similar to Section 3.10, except the caller only wants to leave a message, not actually speak to the person 💌
3.11.2. Solution
The caller would send an INVITE that looks like this, in part: 📨
INVITE sip:Y@example.com SIP/2.0
Accept-Contact: *;msgserver;require;explicitThis caller preference matches both Y1 and Y2. Y1 matches, but with a score of zero. Y2 matches with a score of 1. Since both the "require" and "explicit" flags are set, Y1 is discarded. So the call is routed to Y2, the voicemail server, just like the caller wanted 🎯
Because of the "require" and "explicit" tags, if these preferences are used with a user who doesn't have voicemail, or who fails to indicate it with a msgserver capability, the call will fail completely with a 480 Temporarily Unavailable error, rather than connect to the user. Harsh, but that's the deal 💀
3.12. Prefer Voicemail 📼
3.12.1. Desired Behavior
The situation is similar to Section 3.10. However, this time the caller prefers to leave a message. If voicemail isn't available, they're willing to talk to a person 🫠
3.12.2. Solution
It had been hoped that RFC 3841 could provide a solution for this case, but it doesn't, because doing so would require re-ordering the callee contacts, which isn't done. The caller can still get the intended effect by making two call attempts: 🔁
- First, make an attempt requiring voicemail, as described in Section 3.11.
- If that fails with a 480 error, send an invitation with no Accept-Contact or Reject-Contact headers.
3.13. Routing to an Executive 👑
3.13.1. Desired Behavior
Y is the AOR of an executive, and it has three contacts. Y1 is the phone on the executive's desk. Y2 is the phone on the desk of the executive's assistant. Y3 is the address of an auto-attendant system that can answer general questions, route calls to other parties, and so on. By default, calls to Y should be directed to Y2, and if that fails, to Y3. If Y3 doesn't answer, then Y1 should ring. The assistant gets the first shot, the robot gets the backup, and the boss is the final boss 💅✨
3.13.2. Solution
okay bestie, this one is primarily a called party feature 💅 and it's best done with a CPL (Call Processing Language) script [5] ✨. BUT you can also pull it off with caller preferences alone, as long as you set the q-values across all three devices correctly 🎀. Assuming those three devices can coordinate, here's what each one would send:
Y1 would generate a REGISTER that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y1@pc.example.com>;q=0.1Y2 would generate a REGISTER that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y2@pc2.example.com>;attendant;q=1.0Y3 would generate a REGISTER that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y3@pc3.example.com>;attendant;automata;q=0.5Now, real talk 🙈: the automated attendant would probably not use REGISTER. Since the attendant covers every employee in the company, a static contact would probably get added administratively for each user instead. The info in that static contact would still be identical to the registration above 🫶.
Next, when X calls the executive Y and expresses no preference, the proxy works out an implicit preference to support INVITE. All three contacts match that, even though none of them explicitly said they support INVITE, so nobody gets tossed out 🗑️. Each contact has its own q-value, so the caller preferences don't reorder anything. The result is that the call hits Y2 first, then Y3, then Y1, all because of the q-values 👑.
3.14. Speak to the Executive ✨
3.14.1. Desired Behavior
This case is basically the same as Section 3.13, except this time the caller, X, has a preference 🙌. X calls Y but wants to speak directly to the executive. X doesn't want the call ringing the assistant or the auto attendant (automaton) 🙅♀️.
3.14.2. Solution
X's INVITE would look like, in part:
INVITE sip:Y@example.com SIP/2.0
Reject-Contact: *;attendant
Reject-Contact: *;automataNote that the caller uses two separate Reject-Contact header field values, rather than a single one with two separate feature parameters. This distinction is a big deal 💀. If X had to use a single value with two parameters, a matching UA would need to declare that it was BOTH an attendant and an automaton. If it only declared that it was one of these, based on the matching rules in the caller preferences specification, it would not be rejected.
The above request would result in the elimination of both Y2 and Y3 as contacts 🎯. The call would then be routed to Y1, as desired.
This case shows why a CPL script, or some other programmed version of the feature, is preferable 🤌. With caller preferences, a caller can override the desired ring sequence and disturb the executive without any kind of authorization 😤. A proper version of this service would simply not permit caller preferences to force the call to go directly to the executive.
3.15. Mobile Phone Only 📱
3.15.1. Desired Behavior
The situation is similar to that in Section 3.13. However, the executive also has a mobile phone that they have registered. Caller X knows that the owner of Y is traveling, and that an assistant is covering the office phone 🧳. X wants to call Y and ring only the mobile phone.
3.15.2. Solution
The mobile phone would generate a registration that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:Y4@mobile.example.com>;mobility="mobile";q=0.1The caller would express their preference by generating an INVITE that looks like, in part:
INVITE sip:Y@example.com SIP/2.0
Accept-Contact: *;mobility="mobile";require;explicitAll four contacts match. However, Y1 through Y3 match with a score of zero. Y4 matches with a score of 1. Because of the "require" and "explicit" tags, Y1 through Y3 are discarded, and only Y4 is used, as desired 💖.
Note that this only works if the mobile phone specifies the mobility feature in its registration.
3.16. Simultaneous Languages 🌈
3.16.1. Desired Behavior
AOR Y is as in Section 3.9. Caller X, fluent in both English and Spanish, has discovered that the company's Spanish language documentation is inconsistent with the English language documentation and wants to discuss the differences between the two. So X wants to speak with one of the workers that is fluent in both English and Spanish 🇺🇸🇪🇸.
3.16.2. Solution
The caller would generate an INVITE that looks like, in part:
INVITE sip:Y@example.com SIP/2.0
Accept-Contact: *;language="en";require
Accept-Contact: *;language="es";requireThis will require a Contact URI to match both constraints. That means it needs to support English and Spanish. This will achieve the desired property ✨.
Note that there are two separate Accept-Contact header fields. If the caller had instead used this INVITE:
INVITE sip:Y@example.com SIP/2.0
Accept-Contact: *;language="en,es";requireIt would have connected them to a UA that speaks either English or Spanish, which is not what is desired here 🙅♀️.
An "explicit" option is not used, because it would bypass contacts that do not include a language tag.
3.17. The Number You Have Called... 📞
3.17.1. Desired Behavior
Consider once more the case of the executive, where the caller wishes to reach only their mobile phone (Section 3.15). However, there is a twist 👀. The callee Y has moved to new address YY, and all the configuration described for the callee now applies to YY. The old address Y remains with a pair of statically assigned contacts. One contact is YY. The other is M, referencing an automaton that generates a voice message reporting that the number has been changed. The caller is unaware of the move and calls Y, requesting to reach the mobile phone in exactly the same way they did in Section 3.15. The call should connect to the mobile 📱.
3.17.2. Solution
There would be four registrations against YY:
YY1, the executive, would generate a REGISTER that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:YY@example.com
Contact: <sip:YY1@pc.example.com>;q=0.1YY2, the attendant, would generate a REGISTER that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:YY@example.com
Contact: <sip:YY2@pc2.example.com>;attendant;q=1.0YY3, the answering service, would generate a REGISTER that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:YY@example.com
Contact: <sip:YY3@pc3.example.com>;attendant;automata;q=0.5YY4, the mobile, would generate a REGISTER that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:YY@example.com
Contact: <sip:YY4@mobile.example.com>;mobility="mobile";q=0.5Although it would be configured administratively, there are two registered contacts for Y. The first is for the forwarding:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:YY@example.com>;q=1.0and the second for the automated answering service:
REGISTER sip:example.com SIP/2.0
To: sip:Y@example.com
Contact: <sip:machine@example.com>;automata;q=0.5The caller, not knowing that Y has moved, calls Y and asks for their mobile phone:
INVITE sip:Y@example.com SIP/2.0
Accept-Contact: *;mobility="mobile";require;explicitThis reaches the example.com proxy, which finds two registrations. Only one of these (the automaton) is associated with feature parameters. The other has no feature parameters and is therefore immune to caller preferences processing. The caller preferences are applied to the automaton's contact. The feature sets match, but have a score of zero. Since the "require" and "explicit" tags are present, the contact for the automaton is dropped. The other contact, YY@example.com, is then added back in as the sole contact. The proxy therefore sends the call to sip:YY@example.com. There, there are four registrations, all of which are associated with feature parameters. The caller preferences are applied. Only YY4 matches explicitly, however. Because of the presence of the "require" and "explicit" flags, all other contacts are dropped. As such, the call is forwarded to YY4, and the mobile phone rings 📱🎉.
3.18. The Number You Have Called, Take Two 🔁
3.18.1. Desired Behavior
This use case is nearly identical to that of Section 3.17. However, this time, the caller wishes to contact the personal phone of Y. They don't feel strongly about it, and will accept other devices 🦋.
3.18.2. Solution
The INVITE generated by the caller in this case will look like:
INVITE sip:Y@example.com SIP/2.0
Accept-Contact: *;class="personal"This reaches the example.com proxy. Once more, the first registration (which forwards to the address-of-record for YY) is unaffected by the caller preferences computation. The other contact, for the automaton, is a match, but its score is zero. Its caller preference Qa equals zero. The other contact is added back in with a Qa of 1.0. The contacts are sorted based on q-value, resulting in YY (q=1.0) followed by machine (q=0.5). These are broken into equivalence classes. There are two classes, one for each contact. As a result, the caller's preferences have no impact on the ordering, and the call is routed to YY 🧩.
When the request for YY@example.com is processed, all four contacts match. However, the score for all of them is zero (none are the personal phone). As such, the contacts are ordered based on q-value. Each contact has a different q-value, so no reordering based on caller preference is possible (not that the caller preference would cause a reordering; all contacts have a Qa of 0.0). Thus, the highest q-value contact is tried, which is the executive assistant 💁♀️.
3.19. Forwarding to a Colleague 💌
3.19.1. Desired Behavior
Alice wants to forward her phone to Bob, but doesn't want folks calling her to get Bob's voicemail if he doesn't answer. She wants her callers to get her voicemail 📫💜.
3.19.2. Solution 💅
okay so Alice makes three registrations, bestie 🫶 The first one, Y1, is Alice's phone. The second is Bob's AOR. The third is a voicemail server. The three contacts have decreasing q-values, and the registration for Bob's AOR has an embedded Reject-Contact header field that rejects message servers. ngl that's such a power move 👑
REGISTER sip:example.com
To: <sip:alice@example.com>
Contact: <sip:Y1@192.0.2.150>;q=1.0
REGISTER sip:example.com
To: <sip:alice@example.com>
Contact: <sip:bob@example.com?Reject-Contact=*;msgserver>;q=0.3
REGISTER sip:example.com
To: <sip:alice@example.com>
Contact: <sip:alice-drop@msgcenter.example.com>
;msgserver;
;automata
;attendant
;q=0.1Meanwhile, Bob is registered like this 🎀
REGISTER sip:example.com
To: <sip:bob@example.com>
Contact: <sip:bob3@192.0.2.212>;q=0.8
REGISTER sip:example.com
To: <sip:bob@example.com>
Contact: <sip:bob-drop@msgcenter.example.com>
;msgserver
;automata
;attendant
;q=0.2Carol calls Alice and doesn't include any caller preference parameters, so the example.com proxy builds an implicit preference for INVITE. That preference matches all three of Alice's registered contacts with a score of zero. Since each contact has a different q-value, nothing gets reordered 🦋 So the proxy tries the highest q-value Contact first, Alice's desk phone (Y1). It cancels after a few seconds because nobody answers. Then it moves on to the next Contact, which is Bob's AOR. When it builds the request for that Contact, the proxy includes the embedded Reject-Contact header field in the INVITE. This INVITE then goes through caller preferences processing based on Bob's registered Contacts.
Bob has two registered Contacts. The second one is a message server, and it matches the Reject-Contact in the INVITE, so that contact gets discarded 🚫 The other remaining Contact, Bob's phone, gets tried. Bob isn't around, so his phone rings for a while. When that times out, the proxy figures out it can't reach Bob's AOR. So the proxy handling Alice tries the final remaining contact, which is Alice's message server 💜
4. Capability Use Cases ✨
The callee capabilities spec [2] lets the Contact header field in OPTIONS responses and dialog initiating messages carry the capabilities of the UA. These can be super useful for building new apps 🧚 Here are a few usages I'm obsessed with 🌈
4.1. Web Redirect 🌸
So a caller sends an INVITE to the called party, but the called party isn't present 🙈 The proxy representing the called party wants to redirect the caller to a web page where they can find out more about how to reach the called party. The thing is, the proxy needs to know whether the caller supports redirects to web pages. If it doesn't, the proxy would connect the user to an interactive voice response (IVR) device, which would execute an answering machine application.
The proxy could make that call if the caller included the "schemes" feature tag in the Contact header field of its INVITE:
INVITE sip:callee@example.com SIP/2.0
Contact: <sip:host22.example.com>;schemes="http,sip,sips,tel"This tells the proxy that the UAC can be redirected to an http URI. An INVITE from a normal "black phone" that lacks this capability would look like:
INVITE sip:callee@example.com SIP/2.0
Contact: <sip:host22.example.com>;schemes="sip,sips,tel"This indicates that it needs to be connected to the IVR.
4.2. Voicemail Icon 📞
On the circuit network, when a user makes a call and an answering machine picks up, the caller usually needs several seconds to figure out they're talking to an answering machine. It'd be so helpful if a phone could pop up an icon right away on call completion to show that an answering machine was reached 😭
This indication can be provided by the "msgserver" feature parameter. When the answering machine picks up, its 200 OK looks like, in part:
SIP/2.0 200 OK
Contact: <sip:server33.example.com>;msgserver;automata;attendantThis tells the caller that it's an answering machine.
5. Usage of the Feature Tags 🎀
The caller preferences extension briefly lists a set of media feature tags that a device can register and include in the Accept-Contact and Reject-Contact header fields in a request. Proper operation of caller preferences depends heavily on the caller and the callee interpreting these feature tags the same way. In this section, we go over some guidelines for using them 💖
Generally speaking, the more info a device gives when it registers, the more effective the caller preferences extension is. That's exactly why the callee capabilities extension recommends that a device register as much information as it can. I cannot stress this enough, periodt 💅
If devices explicitly registered features they don't support, such as 'video="false"', the operation of RFC 3841 would be improved. But given the open-ended nature of capabilities, it will never be possible to make sure every capability a caller cares about gets a negative value registered. Doing that would also seriously bloat registrations. So instead, it is recommended that all "unusual" capabilities be explicitly registered ✨
The subsections below show example registrations from typical devices 🦋
5.1. Traditional Cell Phone 📱
A VoIP cell phone that can make voice calls would generate a registration that looks like, in part:
REGISTER sip:example.com SIP/2.0
To: sip:user@example.com
Contact: <sip:cell-phone@example.com>
;audio
;class="business"
;duplex="full"
;+sip.extensions="100rel,path"
;mobility="mobile"
;methods="INVITE,BYE,OPTIONS,CANCEL,ACK"
;schemes="sip,sips,tel"
;uri-user="<cell-phone>"
;uri-domain="example.com"5.2. Traditional Work Phone 🏢
A traditional landline IP PBX phone would generate a registration that looks like:
REGISTER sip:example.com SIP/2.0
To: sip:user@example.com
Contact: <sip:ippbx-phone@example.com>
;audio
;class="business"
;duplex="full"
;events="dialog"
;+sip.extensions="100rel,privacy"
;mobility="fixed"
;methods="INVITE,BYE,OPTIONS,CANCEL,ACK,SUBSCRIBE"
;schemes="sip,sips,tel"
;uri-user="<ippbx-phone>"
;uri-domain="example.com"This device also supports the dialog event package and several SIP extensions that would be typical in an IP PBX phone 🍓
5.3. PC Messaging Application 💻
A PC messenger client that only does presence and IM (no voice) would generate a registration that looks like:
REGISTER sip:example.com SIP/2.0
To: sip:user@example.com
Contact: <sip:pc-msgr@example.com>
;class="personal"
;mobility="fixed"
;methods="OPTIONS,MESSAGE,NOTIFY"
;schemes="sip,sips,im,pres"
;uri-user="<pc-msgr>"
;uri-domain="example.com"5.4. Standalone Videophone 📹
A standalone IP videophone, capable of audio and video, would generate a registration that looks like, in part
REGISTER sip:example.com SIP/2.0
To: sip:user@example.com
Contact: <sip:vp@example.com>
;audio
;video
;class="business"
;duplex="full"
;mobility="fixed"
;methods="INVITE,BYE,OPTIONS,CANCEL,ACK"
;schemes="sip,sips,tel"
;uri-user="<vp>"
;uri-domain="example.com"6. Example of Implementation of Preference and Capability Matching 🧩
RFC 3841 [3] uses the definitions and feature matching algorithm from RFC 2533 [6]. That gives a precise normative spec for the algorithm. But that spec isn't ideal as an implementation guide, because it's more complex than the restricted use RFC 3841 needs. (It's mostly simpler because a particular feature tag may only appear once in each Contact, Accept-Contact, or Reject-Contact header.)
This section gives a sample approach to matching caller preferences to callee capabilities. It doesn't require the notation and techniques of RFC 2533. It is not normative, but it is believed to be consistent with that definition. It may be considered an alternative for the part of RFC 3841 that starts at Section 7.2.3 and runs to the end of page 13, in the middle of Section 7.2.4 🌈
In this section there are lots of references to syntactic elements defined by ABNF in RFC 3840, Section 9, and RFC 3841, Section 10. Here, ABNF elements are enclosed in single quotes -- for example, 'feature-param'. Such a reference identifies a sequence of octets within a SIP request that matches the corresponding ABNF element when the SIP request is parsed according to RFCs 3261, 3840, and 3841 🔥
6.1. Extracting a Feature Set from a Header
Contact header fields, Accept-Contact header fields, and Reject-Contact header fields each contain zero or more 'feature-param's. Each of those in turn may contain one or more 'tag-value's, or a 'string-value'. The first step is to pull out of each header field a more useful representation, called an FS, short for feature set 💅 (This FS representation differs from the one in RFC 2533.) This process is the same for each type of header.
An FS consists of a set of one or more feature params, denoted by FP. Each FP has a name, denoted FP.NAME, and a set of one or more value ranges, denoted by VR. Each VR consists of:
- A type (VR.TYPE): either token (TOKEN-TYPE), string (STRING-TYPE), or number-range (RANGE-TYPE)
- A negation flag (VR.NEGATION): either NEGATED, or NON-NEGATED
- The actual value, differing by type:
- For TOKEN-TYPE and STRING-TYPE, a sequence of octets (VR.OCTETS)
- For RANGE-TYPE, a pair of signed real numbers (VR.LB and VR.UB) representing the lower and upper bounds on the range, inclusive.
A single FS is created to represent the features of one header (Contact, Accept-Contact, Reject-Contact). Inside the FS, an FP is created for each 'feature-param' in the header. To create an FP, a 'feature-param' is examined as follows:
- If the
'feature-param'contains an instance of'other-tags', then FP.NAME is the value matched by'ftag-name'. - Otherwise, the
'feature-param'contains an instance of'base-tags'. If the value matched by'base-tags'is"language"or"type", then FP.NAME is just the value matched by'base-tags'. If not, then FP.NAME is the value matched by'base-tags'prefixed with"sip.". - The value of the
'feature-param', if any, is processed (according to the rules in the next section) to extract a set of one or more VRs that are associated with the FP. this is where it gets so good ✨
6.2. Extracting Values from a Feature Parameter 💅
okay so the value of a feature-param is an encoded representation (as specified in RFC 3840) of one or more value ranges of the corresponding feature 🎀 those values can be boolean, token, string, number, or numeric range, and the encoded form is what decides which type you're dealing with ✨ (these types and their representations are specific to this implementation, fyi 🦋)
(Note: numeric values can explicitly represent a range of values. the other types only represent a single value, which is a degenerate range. the term value range covers all of them 🌈)
the value of the feature-param (string-value, tag-value-list, or none) gets converted to VR form like this 💖
- if there is no value, then one new VR is created with
VR.TYPE = TOKEN-TYPE,VR.NEGATION = NON-NEGATED, andVR.OCTETSset to"true"🌸 - if the
feature-paramhas astring-value, then one new VR is created withVR.TYPE = STRING-TYPE,VR.NEGATION = NON-NEGATED, andVR.OCTETSset to the octets matchingqdtext🧚 - otherwise the
feature-paramhas atag-value-list, and a new VR gets made for eachtag-valuein that list, as follows 🫶 - if the
tag-valuebegins with"!", thenVR.NEGATION = NEGATED. otherwise,VR.NEGATION = NON-NEGATED🙈 - if the
tag-valuecontains abooleanortoken-nobang, thenVR.TYPE = TOKEN-TYPE, andVR.OCTETSis set to the octets matched by thatbooleanortoken-nobang💜 - if the
tag-valuecontains anumeric, thenVR.TYPE = RANGE-TYPEand:- if
'numeric-relation'is"<=", thenVR.UBis set to the numeric value matchingnumber.VR.LBis set to MIN-REAL (a negative number with the largest expressible magnitude) 🔥 - if
'numeric-relation'is"=", then bothVR.LBandVR.UBare set to the numeric value matchingnumber👑 - if
'numeric-relation'is">=", thenVR.LBis set to the numeric value matchingnumberplus a small epsilon.VR.UBis set to MAX-REAL (a positive number with the largest expressible magnitude) ⭐ - else the
'numeric-relation'consists of twonumbers separated by a colon. in this case,VR.LBis set to the numeric value of the smaller of the two numbers, andVR.UBis set to the numeric value of the larger one 🍓
- if
6.3. Comparing Two Value-Ranges 🦋
two VRs match if their ranges overlap 💅 the comparison is done according to type, and only comparisons between like types are defined. when two VRs of differing types get compared, they are considered not to overlap. either or both of the VRs may be NEGATED. the comparison goes like this 🌈
- if the VRs are of different types, the match is false 💀
- otherwise:
- two VRs with
VR.TYPE = RANGE-TYPEmatch ifmax(VR1.LB, VR2.LB) <= min(VR1.UB, VR2.UB)✨ - two VRs with
VR.TYPE = TOKEN-TYPEmatch if their respectiveVR.OCTETSvalues compare equal by case-insensitive comparison 🎀 - two VRs with
VR.TYPE = STRING-TYPEmatch if their respectiveVR.OCTETSvalues compare equal by case-sensitive comparison 🌸
- two VRs with
- the result (true/false) is then negated if
VR1.NEGATION = NEGATED, and negated again ifVR2.NEGATION = NEGATED🙃
6.4. Feature Set to Feature Set Matching 🧚
okay this one is a plot twist 😭 in RFC 2533, matching two feature sets is commutative (order doesn't matter), but for caller preferences matching it is not 🫶 one feature set comes from an Accept-Contact or Reject-Contact header, and the other comes from a Contact header. for this description, these get called the preferred-features (FSp) and the capability-features (FSc), respectively. the non-commutativity comes from explicit tests for whether feature param names used in preferred-features show up among capability-params 💖
a preferred-features feature set FSp can be matched to one capability-features feature set FSc, and that gives you these metrics 👑
- NPF: the number of preferred-features 💜
- NCF: the number of preferred-features for which there is a capability-feature of the same name 🌸
- NVM: the number of value matches between corresponding features of the two feature sets ✨
for a particular pair of FPp and FPc, the metrics get computed like this 🔥
- all the metrics are set to zero 🙈
- the following steps get applied for each feature param (FPp) of the FSp:
- NPF is incremented 🎀
- a corresponding FP with the same name is sought (using case-insensitive comparison) in the FSc 🍓
- if a corresponding feature param (FPc) is found:
- NCF is incremented 🌈
- every VR of FPp is matched to every VR of FPc 🦋
- if any of those matches succeed, NVM is incremented 💅
6.5. Selecting and Ordering Contacts Based on Caller Preferences 👑
6.5.1. Reject-Contact Processing 💀
the reject processing specified in Section 7.4.2 of RFC 3841 may be performed as follows 💅
- for each candidate Contact in the target set, match the feature set of each Reject-Contact to it 🌸
- if
(NVM == NPF) & (NCF == NPF), remove the contact URI from the target set 🔥
6.5.2. Accept-Contact Processing ⭐
the matching of an Accept-Contact against a Contact, and the scoring of that match afterwards, is specified in Section 7.4.2 of RFC 3841 and may be performed as follows 🫶
- match the feature set of the Accept-Contact to that of the Contact as specified in Section 6.4 🧚
- if
(NVM < NCF), then the match failed. if the Accept-Contact had its "require" flag set, then discard the corresponding contact URI from the target set 💖 - compute the score as
NVM/NPF💜 - apply the "require" and "explicit" flags as specified in the text and Figure 7 of RFC 3841 ✨
7. Security Considerations 🔥
this document provides explanation and examples of the use and implementation of RFCs 3840 and 3841 😭 the security considerations sections of those documents apply to the material presented here, so go read those too, bestie 🙏
8. Acknowledgements 🫶
the authors would like to thank Rohan Mahy for his input in this specification 💖
9. Informative References 📚
- [1] 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. 🌸
- [2] Rosenberg, J., Schulzrinne, H., and P. Kyzivat, "Indicating User Agent Capabilities in the Session Initiation Protocol (SIP)", RFC 3840, August 2004. 🎀
- [3] Rosenberg, J., Schulzrinne, H., and P. Kyzivat, "Caller Preferences for the Session Initiation Protocol (SIP)", RFC 3841, August 2004. 💜
- [4] Mankin, A., Bradner, S., Mahy, R., Willis, D., Ott, J., and B. Rosen, "Change Process for the Session Initiation Protocol (SIP)", BCP 67, RFC 3427, December 2002. 🦋
- [5] Lennox, J. and H. Schulzrinne, "Call Processing Language Framework and Requirements", RFC 2824, May 2000. 🌈
- [6] Klyne, G., "A Syntax for Describing Media Feature Sets", RFC 2533, March 1999. ✨
- [7] Rosenberg, J., Schulzrinne, H., and R. Mahy, "An INVITE-Initiated Dialog Event Package for the Session Initiation Protocol (SIP)", RFC 4235, November 2005. 🧚
- [8] Rosenberg, J., "A Presence Event Package for the Session Initiation Protocol (SIP)", RFC 3856, August 2004. 💅
- [9] Rosenberg, J., Peterson, J., Schulzrinne, H., and G. Camarillo, "Best Current Practices for Third Party Call Control (3pcc) in the Session Initiation Protocol (SIP)", BCP 85, RFC 3725, April 2004. 👑
- [10] Campbell, B., "The Message Session Relay Protocol", Work in Progress, July 2006. 🍓
Authors' Addresses 💌
the two authors, both at Cisco Systems, are listed below 🦋
Jonathan Rosenberg
Cisco Systems
600 Lanidex Plaza
Parsippany, NJ 07054
US
Phone: +1 973 952-5000
EMail: jdrosen@cisco.com
URI: http://www.jdrosen.net
Paul Kyzivat
Cisco Systems
1414 Massachusetts Avenue
Boxborough, MA 01719
US
Phone: +1 978 936-1881
EMail: pkyzivat@cisco.comFull Copyright Statement ⚖️
the legal bits are kept exactly as written, because nobody wants a rogue paraphrase in a copyright notice 🙈
Copyright (C) The Internet Society (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 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's position on patents and other rights is kept verbatim below, so read it carefully, it's giving legal 💅
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 provided by the IETF
Administrative Support Activity (IASA).and that's a wrap on RFC 4596! 🎀💖✨
📦 where this page comes from
- ietf: rfc4596 2006-07
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms