<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/2042/1/7/_/styles/combined.css?spaceKey=TOP&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/TOP/SIP+Registrar">SIP Registrar</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~kpfleming">Kevin P. Fleming</a>
</h4>
<div id="versionComment">
<b>Comment:</b>
various updates all over the place, trying to make the interfaces as logical and consistent as possible<br />
</div>
<br/>
<h4>Changes (29)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-unchanged" >h1. Registrar's Duties <br> <br></td></tr>
<tr><td class="diff-changed-lines" >The SIP registrar's job is to maintain a mapping of addresses-of-record (AoRs) to contact URIs. The registrar is responsible for letting other SIP services within a cluster know of updates to <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">this mapping.</span> <span class="diff-added-words"style="background-color: #dfd;">these mappings.</span> The registrar populates <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">this mapping based on incoming</span> <span class="diff-added-words"style="background-color: #dfd;">these mappings by processing and responding to</span> SIP REGISTER requests it receives. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h1. Endpoints <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" ># SIP Requests targeted at sip:bob@example.com would be targeted for Bob. <br> <br></td></tr>
<tr><td class="diff-changed-lines" >An endpoint may be associated with multiple AoRs and multiple endpoints may be associated with the same AoR. <span class="diff-added-words"style="background-color: #dfd;">The association between endpoints and AoRs, however, is not known to the Registrar; this association exists only in the SIP components that use the Registrar's services. As a result, decisions about whether an incoming REGISTER request should be permitted to modify the mappings or not (authorization), or even whether an incoming REGISTER request must be authenticated, will fall to components outside the Registrar. The Registrar will offer Extension Points where Hooks can be attached to implement these policies as needed.</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>h1. Registration data <br> <br></td></tr>
<tr><td class="diff-changed-lines" >A binding in <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Asterisk SCF</span> <span class="diff-added-words"style="background-color: #dfd;">the Registrar</span> is a single contact URI that is bound to an AoR. <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">A single</span> <span class="diff-added-words"style="background-color: #dfd;">An</span> AoR may have multiple bindings associated with it, and a single REGISTER message may create multiple bindings <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">in Asterisk SCF.</span> <span class="diff-added-words"style="background-color: #dfd;">for a single AoR.</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>The {{Binding}} object is defined in Slice since the registrar's state will need to be replicated. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
<tr><td class="diff-changed-lines" >The <span class="diff-changed-words">{{Binding<span class="diff-added-chars"style="background-color: #dfd;">Dict</span>}}</span> object represents all the state data that needs to be replicated between <span class="diff-changed-words">registrar<span class="diff-added-chars"style="background-color: #dfd;"> in</span>s<span class="diff-added-chars"style="background-color: #dfd;">tances</span>.</span> Individual registrars will be responsible for scheduling destruction of their local {{Bindings}} based on the binding's expiration. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The {{BindingDict}} is the set of all bindings currently known to the Registrar; the {{string}} key is the AoR, and the {{BindingSeq}} is the list of Contact URIs currently bound to that AoR. <br> <br></td></tr>
<tr><td class="diff-unchanged" >h1. Interfaces <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > <br>{code: language=slice} <br></td></tr>
<tr><td class="diff-unchanged" >struct BindingUpdate <br>{ <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > string aor; <br> /** <br></td></tr>
<tr><td class="diff-changed-lines" >* The <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">contacts from all bindings for</span> <span class="diff-added-words"style="background-color: #dfd;">Contact URIs bound to</span> this AoR <br></td></tr>
<tr><td class="diff-unchanged" > */ <br> StringSeq contacts; <br>} <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">/** <br> * A dictionary mapping <br> * AoRs to their bound contacts <br> */ <br>dictionary<string, Ice::StringSeq> ContactDict; <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">sequence<BindingUpdate> BindingUpdateSeq; <br></td></tr>
<tr><td class="diff-unchanged" > <br>/** <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{ <br> /** <br></td></tr>
<tr><td class="diff-changed-lines" >* Alerts the listener that contacts have been <span class="diff-changed-words">added<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">.</span></span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"> * The AoR may be new or it may have previous <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> * to one or more AoRs. The AoRs may be new or they <br></td></tr>
<tr><td class="diff-changed-lines" >* <span class="diff-added-words"style="background-color: #dfd;">may have already had</span> bindings. <br></td></tr>
<tr><td class="diff-unchanged" > */ <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"> void contactsAdded(BindingUpdate contacts); <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> void contactsAdded(BindingUpdateSeq updates); <br></td></tr>
<tr><td class="diff-unchanged" > /** <br> * Alerts the listener that contacts have been removed. <br> * There is no specific call for indicating that an AoR <br> * no longer has contacts associated with it. After this <br></td></tr>
<tr><td class="diff-changed-lines" >* <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">method</span> <span class="diff-added-words"style="background-color: #dfd;">operation</span> has been <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">called,</span> <span class="diff-added-words"style="background-color: #dfd;">invoked,</span> listeners should take <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"> * appropriate action if the AoR has no bound contacts. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> * appropriate action if an AoR no longer has bindings. <br></td></tr>
<tr><td class="diff-unchanged" > */ <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"> void contactsRemoved(BindingUpdate contacts); <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> void contactsRemoved(BindingUpdateSeq updates); <br></td></tr>
<tr><td class="diff-unchanged" >}; <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{ <br> /** <br></td></tr>
<tr><td class="diff-changed-lines" >* Add a new listener to the registrar. <span class="diff-added-words"style="background-color: #dfd;">The listener will</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"> * The return value is the map of all AoRs and their <br> * bindings. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> * will receive all known AoRs and their bindings through <br> * its 'contactsAdded' operation. <br></td></tr>
<tr><td class="diff-unchanged" > */ <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">ContactDict</span> <span class="diff-added-words"style="background-color: #dfd;">void</span> addListener(RegistrarListener *listener); <br></td></tr>
<tr><td class="diff-unchanged" > /** <br> * Remove a listener. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > void removeListener(RegistrarLister *listener); <br> /** <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"> * Get the mapping of all active registrations. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> * Get the mapping of all known AoRs and their bindings. <br></td></tr>
<tr><td class="diff-unchanged" > */ <br> BindingDict getAllBindings(); <br> /** <br></td></tr>
<tr><td class="diff-changed-lines" >* Get all bindings associated with a particular <span class="diff-changed-words">AoR<span class="diff-added-chars"style="background-color: #dfd;">.</span></span> <br></td></tr>
<tr><td class="diff-unchanged" > */ <br> BindingSeq getAORBindings(string aor); <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">A {{RegistrarListener}} registers itself with the {{Registrar}} in order to receive updates about the {{Registrar}}'s bindings. Most {{RegistrarListeners}} will be other SIP services that need to use the registrar's data. A {{RegistrarListener}} is always provided with a {{BindingUpdate}} instead of a {{Binding}} because information besides the contact in a {{Binding}} is not useful outside the registrar service. If a component wishes to get a full {{Binding}} it may use a variant of {{getBindings}} to do so. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">A {{RegistrarListener}} registers itself with the {{Registrar}} in order to receive updates about the {{Registrar}}'s bindings. Most {{RegistrarListeners}} will be other SIP services that need to use the registrar's data. A {{RegistrarListener}} is always provided with {{BindingUpdate}} objects instead of {{Binding}} objects because the {{Binding}} contains information that is not useful outside the registrar service. If a component wishes to get a full {{Binding}} object it may use a variant of {{getBindings}} to do so. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h1. Operation <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >h1. Other ideas <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">* The registrar specification does not currently authorize third party registrations. By this, I mean that an endpoint can only be configured to update bindings for his own AoRs, not bindings for AoRs associated with other endpoints. This could be allowed, but the configuration would become more complex for a feature that is not widely used. <br> <br>* Once SIP configuration interfaces and objects have stabilized, the section about {{RegistrarListeners}} may change. If it becomes practical, there may not be a need for {{RegistrationListeners}} if the registrar is able to push configuration updates to endpoints directly. <br> <br></td></tr>
<tr><td class="diff-unchanged" >* Providing a mechanism for default AoRs may be desirable. For instance, if there is an endpoint named "Bob" and his endpoint belongs to the domains "example1.com" and "example2.com" then it may be reasonable to automatically associate Bob with the AoRs "sip:bob@example1.com" and "sip:bob@example2.com." Implicit behavior is typically discouraged in Asterisk SCF, which is why default AoRs are not currently defined. <br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h1><a name="SIPRegistrar-Registrar%27sDuties"></a>Registrar's Duties</h1>
<p>The SIP registrar's job is to maintain a mapping of addresses-of-record (AoRs) to contact URIs. The registrar is responsible for letting other SIP services within a cluster know of updates to these mappings. The registrar populates these mappings by processing and responding to SIP REGISTER requests it receives.</p>
<h1><a name="SIPRegistrar-Endpoints"></a>Endpoints</h1>
<p>SIP endpoints will be configured to determine which AoRs they are associated with. For instance, if a SIP endpoint named "Bob" were to be configured to be associated with the AoR "sip:bob@example.com" then this would imply the following things:</p>
<ol>
<li>REGISTER requests from Bob would be permitted to add and remove bindings for the AoR sip:bob@example.com</li>
<li>SIP Requests targeted at sip:bob@example.com would be targeted for Bob.</li>
</ol>
<p>An endpoint may be associated with multiple AoRs and multiple endpoints may be associated with the same AoR. The association between endpoints and AoRs, however, is not known to the Registrar; this association exists only in the SIP components that use the Registrar's services. As a result, decisions about whether an incoming REGISTER request should be permitted to modify the mappings or not (authorization), or even whether an incoming REGISTER request must be authenticated, will fall to components outside the Registrar. The Registrar will offer Extension Points where Hooks can be attached to implement these policies as needed.</p>
<h1><a name="SIPRegistrar-Registrationdata"></a>Registration data</h1>
<p>A binding in the Registrar is a single contact URI that is bound to an AoR. An AoR may have multiple bindings associated with it, and a single REGISTER message may create multiple bindings for a single AoR.</p>
<p>The <tt>Binding</tt> object is defined in Slice since the registrar's state will need to be replicated.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="toolbar: false; theme: Confluence; brush: java; gutter: false"><![CDATA[
class Binding
{
/**
* The contact URI associated with this particular Binding.
*/
string contact;
/**
* The Call-ID from the latest successful Binding.
*/
string callid;
/**
* The CSeq from the latest successful Binding.
*/
int cseq;
/**
* A UNIX timestamp indicating when the Binding is set
* to expire
*/
int expiration;
};
sequence<Binding> BindingSeq;
dictionary<string, BindingSeq> BindingDict;
]]></script>
</div></div>
<p>The <tt>BindingDict</tt> object represents all the state data that needs to be replicated between registrar instances. Individual registrars will be responsible for scheduling destruction of their local <tt>Bindings</tt> based on the binding's expiration.</p>
<p>The <tt>BindingDict</tt> is the set of all bindings currently known to the Registrar; the <tt>string</tt> key is the AoR, and the <tt>BindingSeq</tt> is the list of Contact URIs currently bound to that AoR.</p>
<h1><a name="SIPRegistrar-Interfaces"></a>Interfaces</h1>
<p>The registrar will not have much in the way of public interfaces since the data it makes available is pushed out to the other SIP services.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="toolbar: false; theme: Confluence; brush: java; gutter: false"><![CDATA[
struct BindingUpdate
{
/**
* The AoR for which bindings have been updated
*/
string aor;
/**
* The Contact URIs bound to this AoR
*/
StringSeq contacts;
}
sequence<BindingUpdate> BindingUpdateSeq;
/**
* A RegistrarListener is updated when a binding changes.
* Typical RegistrarListeners will be SIP services that
* require up-to-date information.
*/
interface RegistrarListener
{
/**
* Alerts the listener that contacts have been added
* to one or more AoRs. The AoRs may be new or they
* may have already had bindings.
*/
void contactsAdded(BindingUpdateSeq updates);
/**
* Alerts the listener that contacts have been removed.
* There is no specific call for indicating that an AoR
* no longer has contacts associated with it. After this
* operation has been invoked, listeners should take
* appropriate action if an AoR no longer has bindings.
*/
void contactsRemoved(BindingUpdateSeq updates);
};
interface Registrar
{
/**
* Add a new listener to the registrar. The listener will
* will receive all known AoRs and their bindings through
* its 'contactsAdded' operation.
*/
void addListener(RegistrarListener *listener);
/**
* Remove a listener.
*/
void removeListener(RegistrarLister *listener);
/**
* Get the mapping of all known AoRs and their bindings.
*/
BindingDict getAllBindings();
/**
* Get all bindings associated with a particular AoR.
*/
BindingSeq getAORBindings(string aor);
};
]]></script>
</div></div>
<p>A <tt>RegistrarListener</tt> registers itself with the <tt>Registrar</tt> in order to receive updates about the <tt>Registrar</tt>'s bindings. Most <tt>RegistrarListeners</tt> will be other SIP services that need to use the registrar's data. A <tt>RegistrarListener</tt> is always provided with <tt>BindingUpdate</tt> objects instead of <tt>Binding</tt> objects because the <tt>Binding</tt> contains information that is not useful outside the registrar service. If a component wishes to get a full <tt>Binding</tt> object it may use a variant of <tt>getBindings</tt> to do so.</p>
<h1><a name="SIPRegistrar-Operation"></a>Operation</h1>
<p><span class="image-wrap" style=""><img src="/wiki/download/attachments/12550396/Registration.png?version=1&modificationDate=1299018543697" style="border: 0px solid black" /></span></p>
<p>The diagram shows that when contacts are added or removed from the registrar, the <tt>RegistrarListener</tt> is notified. The third REGISTER transaction does not notify the listener. This is because the REGISTER was refreshing the expiration period for a previously established contact. While this results in internal changes to the registrar and its replicas, <tt>RegistrarListeners</tt> do not need to be updated.</p>
<h1><a name="SIPRegistrar-Otherideas"></a>Other ideas</h1>
<ul>
<li>Providing a mechanism for default AoRs may be desirable. For instance, if there is an endpoint named "Bob" and his endpoint belongs to the domains "example1.com" and "example2.com" then it may be reasonable to automatically associate Bob with the AoRs "sip:bob@example1.com" and "sip:bob@example2.com." Implicit behavior is typically discouraged in Asterisk SCF, which is why default AoRs are not currently defined.</li>
</ul>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;">
<a href="https://wiki.asterisk.org/wiki/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/TOP/SIP+Registrar">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=12550396&revisedVersion=13&originalVersion=12">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/TOP/SIP+Registrar?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>