<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/2041/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/Registrar">Registrar</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~mmichelson">Mark Michelson</a>
</h4>
<br/>
<h4>Changes (12)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >h1. Endpoints <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">How does the AoR->contact URI mapping apply to configured</span> SIP <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">endpoints? SIP</span> 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: <br></td></tr>
<tr><td class="diff-unchanged" > <br># REGISTER requests from Bob would be permitted to add and remove bindings for the AoR sip:bob@example.com <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >h1. Registration data <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">What is a "registration?"</span> A registration in Asterisk SCF is a single contact URI that is bound to an AoR. We can infer from this that a single AoR may have multiple registrations associated with it, and a single REGISTER message may create multiple registrations in Asterisk SCF. <br></td></tr>
<tr><td class="diff-unchanged" > <br>The Registration 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" >{ <br> /** <br></td></tr>
<tr><td class="diff-changed-lines" >* The <span class="diff-added-words"style="background-color: #dfd;">contact</span> URI associated with this particular registration. <br></td></tr>
<tr><td class="diff-unchanged" > */ <br> string contact; <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 {{Registration}} object represents all the state data that needs to be replicated between registrars. Individual registrars will be responsible for scheduling destruction of their local registration objects based on the <span class="diff-added-words"style="background-color: #dfd;">registration's</span> expiration. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h1. Interfaces <br> <br></td></tr>
<tr><td class="diff-changed-lines" >The registrar <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">won't</span> <span class="diff-added-words"style="background-color: #dfd;">will not</span> have much in the way of public interfaces since the data it makes available is pushed out to the other SIP services. <br></td></tr>
<tr><td class="diff-unchanged" > <br>{code: language=slice} <br> <br>/** <br></td></tr>
<tr><td class="diff-changed-lines" >* The first string in the dictionary is an <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" > * The string sequence is a list of all contacts <br> * bound to the particular AoR. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > /** <br> * Alerts the listener that contacts have been added. <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"> * The AoR may itself be new or an AoR with previous <br> * bindings may have new contacts added to it. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> * The AoR may be new or it may have previous <br> * bindings. <br></td></tr>
<tr><td class="diff-unchanged" > */ <br> void contactsAdded(ContactDict contacts); <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > * 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-unchanged" > * method has been called, listeners should take <br></td></tr>
<tr><td class="diff-unchanged" > * appropriate action if the AoR has no bound contacts. <br> */ <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >A {{RegistrationListener}} 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 registration data. A {{RegistrarListener}} is always provided with a {{ContactDict}} instead of a {{RegistrationDict}} because information besides the contact in a {{Registration}} is not useful outside the registrar service. If a component wishes to get a full {{Registration}} it may use a variant of {{getRegistrations}} to do so. <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">You may notice that</span> SIP endpoints are not referenced <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">at all</span> in these interfaces. The reason is that, as of this article's creation, there is no such thing as a SIP endpoint defined in slice, much less a method of retrieving a list of SIP endpoints based on AoRs. As such, when a REGISTER is received, the registrar may use the routing service's endpoint location feature to locate an endpoint based on data in the <span class="diff-changed-words"><span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">f</span><span class="diff-added-chars"style="background-color: #dfd;">F</span>rom</span> header. <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">However, the</span> <span class="diff-added-words"style="background-color: #dfd;">The</span> registrar will not be able to find any other endpoints associated with the AoR. The responsibility for updating local endpoints falls to the {{RegistrarListeners}}. <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" >!Registration.png! <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The diagram shows that when contacts are added or removed from the registrar, the {{RegistrarListener}} is notified. Notice the third REGISTER transaction does not result in the listener being <br>notified. This is because the REGISTER in question was refreshing the expiration period for a previously-established contact. While this results in internal changes to the registrar (as well as state replication changes), {{RegistrarListeners}} do not need to be updated. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The diagram shows that when contacts are added or removed from the registrar, the {{RegistrarListener}} 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, {{RegistrarListeners}} do not need to be updated. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h1. Other ideas <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >* 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></td></tr>
<tr><td class="diff-changed-lines" >* Once SIP configuration interfaces and objects have stabilized, the section about {{RegistrarListeners}} may change. If it becomes practical, there may not be <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">any such thing as</span> a <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">need for </span>{{RegistrationListener<span class="diff-added-chars"style="background-color: #dfd;">s</span>}}</span> if the registrar is able to push configuration updates <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">for</span> <span class="diff-added-words"style="background-color: #dfd;">to</span> endpoints directly. <br></td></tr>
<tr><td class="diff-unchanged" > <br>* 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">
<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Work in progress</td></tr></table></div>
<h1><a name="Registrar-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 this mapping. The registrar populates this mapping based on incoming SIP REGISTER requests it receives.</p>
<h1><a name="Registrar-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.</p>
<h1><a name="Registrar-Registrationdata"></a>Registration data</h1>
<p>A registration in Asterisk SCF is a single contact URI that is bound to an AoR. We can infer from this that a single AoR may have multiple registrations associated with it, and a single REGISTER message may create multiple registrations in Asterisk SCF.</p>
<p>The Registration 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 Registration
{
/**
* The contact URI associated with this particular registration.
*/
string contact;
/**
* The Call-ID from the latest successful registration.
*/
string callid;
/**
* The CSeq from the latest successful registration.
*/
int cseq;
/**
* A UNIX timestamp indicating when the registration is set
* to expire
*/
int expiration;
};
sequence<Registration> RegistrationSeq;
dictionary<string, RegistrationSeq> RegistrationDict;
]]></script>
</div></div>
<p>The <tt>Registration</tt> object represents all the state data that needs to be replicated between registrars. Individual registrars will be responsible for scheduling destruction of their local registration objects based on the registration's expiration.</p>
<h1><a name="Registrar-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[
/**
* The first string in the dictionary is an AoR.
* The string sequence is a list of all contacts
* bound to the particular AoR.
*/
dictionary<string, StringSeq> ContactDict;
/**
* A RegistrarListener is updated when registration
* information changes. Typical RegistrarListeners will
* be SIP services that require up-to-date registration
* information.
*/
interface RegistrarListener
{
/**
* Alerts the listener that contacts have been added.
* The AoR may be new or it may have previous
* bindings.
*/
void contactsAdded(ContactDict contacts);
/**
* 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
* method has been called, listeners should take
* appropriate action if the AoR has no bound contacts.
*/
void contactsRemoved(ContactDict contacts);
};
interface Registrar
{
/**
* Add a new listener to the registrar.
* The return value is the map of all AoRs and their
* bindings.
*/
ContactDict addListener(RegistrarListener *listener);
/**
* Remove a listener.
*/
void removeListener(RegistrarLister *listener);
/**
* Get the mapping of all active registrations.
*/
RegistrationDict getRegistrations();
/**
* Get all registrations associated with a particular AoR
*/
RegistrationSeq getRegistrations(string aor);
};
]]></script>
</div></div>
<p>A <tt>RegistrationListener</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 registration data. A <tt>RegistrarListener</tt> is always provided with a <tt>ContactDict</tt> instead of a <tt>RegistrationDict</tt> because information besides the contact in a <tt>Registration</tt> is not useful outside the registrar service. If a component wishes to get a full <tt>Registration</tt> it may use a variant of <tt>getRegistrations</tt> to do so.</p>
<p>SIP endpoints are not referenced in these interfaces. The reason is that, as of this article's creation, there is no such thing as a SIP endpoint defined in slice, much less a method of retrieving a list of SIP endpoints based on AoRs. As such, when a REGISTER is received, the registrar may use the routing service's endpoint location feature to locate an endpoint based on data in the From header. The registrar will not be able to find any other endpoints associated with the AoR. The responsibility for updating local endpoints falls to the <tt>RegistrarListeners</tt>.</p>
<h1><a name="Registrar-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="Registrar-Otherideas"></a>Other ideas</h1>
<ul>
<li>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.</li>
</ul>
<ul>
<li>Once SIP configuration interfaces and objects have stabilized, the section about <tt>RegistrarListeners</tt> may change. If it becomes practical, there may not be a need for <tt>RegistrationListeners</tt> if the registrar is able to push configuration updates to endpoints directly.</li>
</ul>
<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/Registrar">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=12550396&revisedVersion=6&originalVersion=5">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/TOP/Registrar?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>