<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/2033/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/Support+for+subscriptions+to+and+from+external+entities">Support for subscriptions to and from external entities</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-unchanged" >h1. Concept <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Subscriptions in AsteriskSCF may come in many flavors. One obvious one would be SIP subscriptions as defined in [RFC 3265|http://www.ietf.org/rfc/rfc3265.txt]. However, subscriptions may be started via other protocols or via administration. Therefore, subscription support needs to be written in such a way that it is protocol-agnostic. While Asterisk SCF needs to be able to understand protocol-specific methods of subscribing to resources, it is not within the scope of Asterisk SCF to make decisions regarding such matters. With this in mind, the majority of session-oriented protocols that support subscriptions of some sort will make use of a listener interface in order to make it known what is happening. Listeners are alerted whenever a subscription request arrives. It is up to the listener to make the decision about how to handle such a request. If a subscription is accepted, then the listener that accepted the subscription will notify the Asterisk SCF component responsible for communicating with the subscriber his such that any further events regarding the subscription can be directed to the appropriate listener. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Subscriptions in AsteriskSCF may come in many flavors. One obvious one would be SIP subscriptions as defined in [RFC 3265|http://www.ietf.org/rfc/rfc3265.txt]. However, subscriptions may be started via other protocols or via administration. Therefore, subscription support needs to be written in such a way that it is protocol-agnostic. While Asterisk SCF needs to be able to understand protocol-specific methods of subscribing to resources, it is not within the scope of Asterisk SCF to make decisions regarding such matters. With this in mind, the majority of session-oriented protocols that support subscriptions of some sort will make use of a {{SubscriptionBroker}} in order to make it known what is happening. The {{SubscriptionBroker}} is alerted whenever a subscription request arrives. It is up to the {{SubscriptionBroker}} to make the decision about how to handle such a request. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >At the basis of all of this is the subscription itself. There <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">is no such thing as an all-encompassing subscription class since all subscriptions will have data that is specific to the subscription type. However, there</span> are certain attributes present in all subscription types, and they are represented in a {{SubscriptionData}} class. <br></td></tr>
<tr><td class="diff-unchanged" > <br>{newcode:language=slice} <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >!InboundSubscription.png! <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">1. Bob sends a SIP SUBSCRIBE to Asterisk SCF for a particular resource. <br>2. Asterisk SCF's SIP subscription component receives the incoming SUBSCRIBE. <br>3. The SIP subscription component recognizes the event type and creates an appropriate SubscriptionData object, as well as a corresponding subclass of the {{Subscriber}} interface. <br>4. The SIP subscription component queries the {{SubscriptionBroker}} to provide an appropriate {{Subscription}}. <br>5. The {{SubscriptionBroker}} finds an appropriate component to provide a {{Subscription}} and hands it off to the subscriber. <br>6. The SIP subscription component sends a 200 OK to Bob. <br>7. The {{Subscription}} at some point in the future determines that the resource has undergone a change and so it calls {{Subscriber::notify()}}. <br>8. The subscriber handles this situation by sending a SIP NOTIFY to Bob, to which Bob replies with a 200 OK. <br>9. Bob later decides that he no longer wishes to keep his subscription alive. He therefore sends a SUBSCRIBE with the Expires header set to 0. <br>10. The SIP component receives this and sends the {{Subscription::terminated()}} message. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">This is a one-legged inbound subscription scenario. Whatever resource Bob wishes to subscribe to is handled entirely by a component within Asterisk SCF. Notifications of state change originate in the {{UserComponent}} in such a situation. Another common scenario will be that Asterisk SCF sets up a bridge between two external entities. Below are two methods a user might use in order to accomplish the task. <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;">Now let's modify the situation a bit. In the new situation, Asterisk SCF does not manage Alice's presence, but it knows that it can subscribe to an external resource that is responsible for reporting Alice's presence. In such a situation, Asterisk SCF will act like a subscription "bridge" between Bob and Alice, necessitating both an inbound and outbound subscription to be used. The process starts much the same as before. Steps 1-4 are identical. We pick up with step 5. <br> <br></td></tr>
<tr><td class="diff-unchanged" >!SubscriptionBridge.png! <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">5. An OutboundSubscriptionListener asks for the SipSubscriptionService to create an OutboundSubscription and calls OutboundSubscription::request(). <br>7. The SIP subscription component sends an outbound SUBSCRIBE to the appropriate external resource. <br>8. At some point, the SIP subscription component receives a 200 OK for the outbound SUBSCRIBE. <br>9. The SIP subscription component returns a successful SubscriptionResult to the creator of the OutboundSubscription. <br>10. The InboundSubscriptionHandler can now successfully respond to the initial request() call. <br>11. The SIP subscription component sends a 200 OK to Bob. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">This is the stateless version, where the {{UserComponent}} is only involved in the setup. Once the subscription is established, The {{UserComponent}} never sees any more of the messages. The {{UserComponent}} is able to make initial decisions regarding how to route the subscription, as well as whether to permit the subscription's acceptance. <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;">At this point, Asterisk SCF serves as a subscription bridge, so to speak, between Bob and Alice. Notifications from Alice are intercepted by Asterisk SCF, and they can be sent out to Bob. If Bob, Alice, or Asterisk SCF decides to end the subscriptions, it can be done. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">!SubscriptionBridge2.png! <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;">h1. Lingering Questions: <br>1. In the above example, the SIP component has a preexisting set of InboundSubscriptionListeners to send requests to. Where does this come from? <br>2. Should there be a distinction made between InboundSubscriptionListeners that actually have the ability to make decisions based on an incoming subscription request and those that simply listen passively for events on subscriptions? My initial thought is that to the component calling the listener methods, he's not really going to care one way or the other, and so a distinction shouldn't be made. But from the viewpoint of usability and clarity, a distinction may help. <br>3. I've constructed these APIs with separate call and response methods as opposed to using two-way methods. Any reason to consider changing this? <br>4. Is having PublishedState as a member of SubscriptionData a wise choice? The main use of this as I see it, is that if a listener adds itself to a subscription late, then when given the SubscriptionData, the listener also knows the current state of the subscription. <br>5. I've put addListeners() and removeListeners() methods to InboundSubscription and OutboundSubscription, but I don't know exactly how a new listener is supposed to be able to actually add itself in the first place. How would a potential listener receive the subscription object so that it could add itself as a listener? The only thing I can think of at the moment would be that an IceStorm topic is created such that any established subscriptions would be reported to listeners of the topic, and those who receive events on the topic could then add themselves as listeners to subscriptions. Perhaps such IceStorm listening could be the solution to question 1 as well... <br>6. Are there any suggestions for cosmetic improvement (e.g. class/method name changes)? <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">This is the stateful version, where the {{UserComponent}} intercepts all messages passed during the lifetime of the subscription. The way it does this is to create a {{Subscription}} and a {{Subscriber}} that the respective SIP components communicate with. <br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<h1><a name="Supportforsubscriptionstoandfromexternalentities-Concept"></a>Concept</h1>
<p>Subscriptions in AsteriskSCF may come in many flavors. One obvious one would be SIP subscriptions as defined in <a href="http://www.ietf.org/rfc/rfc3265.txt" class="external-link" rel="nofollow">RFC 3265</a>. However, subscriptions may be started via other protocols or via administration. Therefore, subscription support needs to be written in such a way that it is protocol-agnostic. While Asterisk SCF needs to be able to understand protocol-specific methods of subscribing to resources, it is not within the scope of Asterisk SCF to make decisions regarding such matters. With this in mind, the majority of session-oriented protocols that support subscriptions of some sort will make use of a <tt>SubscriptionBroker</tt> in order to make it known what is happening. The <tt>SubscriptionBroker</tt> is alerted whenever a subscription request arrives. It is up to the <tt>SubscriptionBroker</tt> to make the decision about how to handle such a request.</p>
<p>At the basis of all of this is the subscription itself. There are certain attributes present in all subscription types, and they are represented in a <tt>SubscriptionData</tt> class.</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 SubscriptionData
{
int expiration;
string recipient;
string sender;
PublishedState state;
};
]]></script>
</div></div>
<p>Note that a subscription type is not a member of the class. This is because specific types of subscriptions should be defined as subclasses of the SubscriptionData class. The PublishedState object is a subscription package-specific set of information that describes the current state of the subscription. For a presence subscription, for instance, this would convey the current presence state, like "available" or "busy."</p>
<h1><a name="Supportforsubscriptionstoandfromexternalentities-InboundSubscriptions"></a>Inbound Subscriptions</h1>
<p>We'll examine subscriptions from two different viewpoints: inbound and outbound. First, we'll inspect the <tt>SubscriptionBroker</tt> interface. This is used by a communications protocol that has received an inbound subscription request.</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[
interface SubscriptionBroker
{
SubscriptionResponse subscribe(SubscriptionData data, Subscriber *sub);
};
]]></script>
</div></div>
<p>When an inbound subscription is requested, the SubscriptionBroker is told of the request. The SubscriptionBroker is then responsible for finding an appropriate Asterisk SCF component to be able to handle the subscription request. Once the broker has determined which, if any, component is going to handle the subscription, then the SubscriptionBroker should create a SubscriptionResponse to return to the subscriber. The SubscriptionResponse class is defined as such:</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 SubscriptionResponse
{
SubscriptionResult result;
Subscription *handler;
};
]]></script>
</div></div>
<p><tt>result</tt> can be used by the subscriber to determine if a component accepted the subscription request. If a component has not accepted the request, then <tt>result</tt> can also be used to determine why the subscription request was not accepted. The <tt>handler</tt> is a proxy that will be used by the subscriber to send any further information regarding the subscription. Here is the slice for <tt>SubscriptionResult</tt>:</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[
enum SubscriptionResultCode
{
//XXX More reasons may need to be added here.
//This is primarily for illustrative purposes.
Success,
NotPermitted,
RecipientUnknown,
NotSupported
};
class SubscriptionResult
{
SubscriptionResultCode reason;
};
]]></script>
</div></div>
<p>Specific subscription types may define subclasses of <tt>SubscriptionResult</tt> that contain type-specific reasons for failure. The <tt>Subscription</tt> class is defined as follows:</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[
interface Subscription
{
void renew(SubscriptionData data);
void expire(SubscriptionData data);
void terminate(SubscriptionData data);
};
]]></script>
</div></div>
<p>Each of these methods notifies the subscription handler of changes to the subscription state. <tt>renew</tt> is mostly informational and alerts the subscription handler that the subscriber has extended his subscription beyond the initial expiration period. <tt>expire</tt> indicates that the subscription has been ended due to a failure to re-subscribe in time. The <tt>terminated</tt> method indicates that the subscriber has ended his subscription manually. Each method takes a <tt>SubscriptionData</tt> member so that the listener can identify which subscription the method call pertains to as well as to see potential differences made to the data.</p>
<p>The listener must also be able to communicate with the subscriber. The means of doing this will be using the <tt>Subscriber</tt> interface. Recall that a proxy to a <tt>Subscriber</tt> was passed to the <tt>SubscriptionBroker</tt> in <tt>SubscriptionBroker::subscribe</tt>. </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[
interface Subscriber
{
void terminate();
void notify(PublishedState state);
};
]]></script>
</div></div>
<p>The <tt>terminate</tt> method is a method for a subscription handler to end a subscription. The <tt>notify</tt> method is used to indicate to the subscriber that the subscription state has been updated.</p>
<h1><a name="Supportforsubscriptionstoandfromexternalentities-OutboundSubscriptions"></a>Outbound Subscriptions</h1>
<p>Outbound subscriptions mostly work the same way as inbound ones, except for a few key differences. First off, the role of subscriber and subscription handler is reversed. In other words, a custom-written user component will be the subscriber and the subscription handler will be a session-oriented protocol component such as SIP. Furthermore, the method of using a <tt>SubscriptionBroker</tt> will be modified as well. For inbound subscriptions, a user-defined <tt>SubscriptionBroker</tt> is defined and called into by a subscriber in order to properly create a <tt>Subscription</tt>. For outbound scenarios, since the user component should already know which session-oriented protocol to be using based on the intended recipient of the subscription request, the user component will simply call into a <tt>SubscriptionBroker</tt> interface provided by the particular session-oriented protocol component. In this case, the <tt>SubscriptionBroker</tt> functions more like a factory.</p>
<h1><a name="Supportforsubscriptionstoandfromexternalentities-SimpleExamples"></a>Simple Examples</h1>
<p>So let's consider a typical sequence of events:</p>
<p><span class="image-wrap" style=""><img src="/wiki/download/attachments/9568785/InboundSubscription.png?version=1&modificationDate=1294178925888" style="border: 0px solid black" /></span></p>
<p>This is a one-legged inbound subscription scenario. Whatever resource Bob wishes to subscribe to is handled entirely by a component within Asterisk SCF. Notifications of state change originate in the <tt>UserComponent</tt> in such a situation. Another common scenario will be that Asterisk SCF sets up a bridge between two external entities. Below are two methods a user might use in order to accomplish the task.</p>
<p><span class="image-wrap" style=""><img src="/wiki/download/attachments/9568785/SubscriptionBridge.png?version=1&modificationDate=1294183830774" style="border: 0px solid black" /></span></p>
<p>This is the stateless version, where the <tt>UserComponent</tt> is only involved in the setup. Once the subscription is established, The <tt>UserComponent</tt> never sees any more of the messages. The <tt>UserComponent</tt> is able to make initial decisions regarding how to route the subscription, as well as whether to permit the subscription's acceptance.</p>
<p><span class="image-wrap" style=""><img src="/wiki/download/attachments/9568785/SubscriptionBridge2.png?version=1&modificationDate=1294184943271" style="border: 0px solid black" /></span></p>
<p>This is the stateful version, where the <tt>UserComponent</tt> intercepts all messages passed during the lifetime of the subscription. The way it does this is to create a <tt>Subscription</tt> and a <tt>Subscriber</tt> that the respective SIP components communicate with.</p>
</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/Support+for+subscriptions+to+and+from+external+entities">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=9568785&revisedVersion=14&originalVersion=13">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/TOP/Support+for+subscriptions+to+and+from+external+entities?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>