<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 (8)</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" >So let's consider a typical sequence of events: <br> <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">!InboundSubscription.png! <br> <br></td></tr>
<tr><td class="diff-changed-lines" >1. Bob sends a SIP SUBSCRIBE to Asterisk SCF for <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Alice's presence.</span> <span class="diff-added-words"style="background-color: #dfd;">a particular resource.</span> <br></td></tr>
<tr><td class="diff-unchanged" >2. Asterisk SCF's SIP subscription component receives the incoming SUBSCRIBE. <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">3. The SIP subscription component recognizes the event type and creates an appropriate SubscriptionData object. Perhaps in this case it is a SipPresenceSubscriptionData object. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">3. The SIP subscription component recognizes the event type and creates an appropriate SubscriptionData object, as well as a subclass of the InboundSubscription interface. <br></td></tr>
<tr><td class="diff-unchanged" >4. The SIP subscription component begins querying its InboundSubscriptionListeners using the InboundSubscriptionListener::requested() method. <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">5. One of the listeners recognizes that he is responsible for knowing Alice's presence and thus responds to the request with an InboundSubscriptionResponse class that indicates success. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">5. InboundSubscriptionListenerA does not support the subscription type, but InboundSubscriptionListenerB does, so it indicates a successful response. Note that in the diagram, InboundSubscriptionListenerB also functions as the InboundSubscriptionHandler. <br></td></tr>
<tr><td class="diff-unchanged" >6. The SIP subscription component sends a 200 OK to Bob. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">7. The InboundSubscriptionHandler at some point in the future determines that the resource has undergone a change and so it sends a notify() message to the InboundSubscription. <br>8. The InboundSubscription 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 terminated() message to the InboundSubscriptionHandler. <br>11. The SIP component destroys the InboundSubscription and sends a 200 OK to Bob. <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, the SIP subscription component has an InboundSubscriptionHandler proxy to send updates to if Bob decides to renew or terminate his subscription to Alice's presence. Meanwhile, the component responsible for reporting Alice's presence has an InboundSubscription proxy by which it may send state updates or terminate the subscription. This is a simple one-way subscription into Asterisk SCF. <br> <br></td></tr>
<tr><td class="diff-unchanged" >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-snipped" >...<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 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.</p>
<p>At the basis of all of this is the subscription itself. There 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 are certain attributes present in all subscription types, and they are represented in a SubscriptionData 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>Subscriptions are divided into inbound and outbound types. First, we'll inspect the InboundSubscriptionListener 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 InboundSubscriptionListener
{
InboundSubscriptionResponse requested(SubscriptionData data, InboundSubscription *sub);
};
]]></script>
</div></div>
<p>When an inbound subscription is requested, InboundSubscriptionListeners are told of the request one-by-one until one accepts the request. 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 InboundSubscriptionResponse
{
SubscriptionReason reason;
InboundSubscriptionHandler *handler;
};
enum SubscriptionReasons
{
//XXX More reasons may need to be added here.
//This is primarily for illustrative purposes.
Success,
NotPermitted,
RecipientUnknown,
NotSupported
};
class SubscriptionReason
{
SubscriptionReasons reason;
};
]]></script>
</div></div>
<p>From the InboundSubscriptionResponse class, the potential subscriber can tell if the subscription should be handled by the listener by inspecting the "reason" member of the InboundSubscriptionResponse. Specific subscription types may define subclasses of SubscriptionReason that contain type-specific reasons for failure. The InboundSubscriptionHandler proxy in the SubscriptionResponse is used to communicate further changes to the listener of the subscription. The interface is defined below:</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 InboundSubscriptionHandler
{
void renewed(SubscriptionData data);
void expired(SubscriptionData data);
void terminated(SubscriptionData data);
};
]]></script>
</div></div>
<p>Each of these methods notifies the listener of changes to the subscription state. "renewed" is mostly informational and alerts the listener that the subscriber has extended his subscription beyond the initial expiration period. "expired" indicates that the subscription has been ended due to a failure to re-subscribe in time. The "terminated" method indicates that the subscriber has ended his subscription manually. Each method takes a SubscriptionData 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 InboundSubscription, which is passed to the listener as part of InboundSubscriptionListener::requested().</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 InboundSubscription
{
void terminate();
void notify(PublishedState state);
void addHandlers(InboundSubscriptionHandlerSeq listeners);
void removeHandlers(InboundSubscriptionHandlerSeq listeners);
};
]]></script>
</div></div>
<p>The "terminate" method is a method for a handler to end a subscription. The "notify" method is used to indicate to the subscriber that the subscription state has been updated. "addHandlers" and "removeHandlers" provides methods by which more components may listen for events on an established subscription.</p>
<h1><a name="Supportforsubscriptionstoandfromexternalentities-OutboundSubscriptions"></a>Outbound Subscriptions</h1>
<p>What we have so far allows for Asterisk SCF to communicate with an outside subscriber. But what about if an Asterisk SCF component wishes to subscribe to an outside entity? First off, AsteriskSCF will require the ability to take appropriate actions, such as subscribing, as well as renewing and canceling subscriptions. In other words, the items that the subscription listener listens for need to have corresponding actions that Asterisk SCF can itself make. For this, we have OutboundSubscription.</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 OutboundSubscription
{
SubscriptionReason request(SubscriptionData data, OutboundSubscriptionHandler *handler);
void renew(SubscriptionData data);
void terminate(SubscriptionData data);
void addHandlers(OutboundSubscriptionHandlerSeq listeners);
void removeHandlers(OutboundSubscriptionHandlerSeq listeners);
};
]]></script>
</div></div>
<p>The "request" method will be used to send an outbound subscription. The "renew" method will be used to renew a previously accepted subscription. The "terminate" method is used to end a subscription.<br/>
Once a subscription is established, Asterisk SCF will need a way of knowing when changes have been made to the state of the outbound subscription. For this, we have the OutboundSubscriptionHandler 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[
interface OutboundSubscriptionHandler
{
void terminated(OutboundSubscription *sub);
void notified(OutboundSubscription *sub, PublishedState state);
};
]]></script>
</div></div>
<p>"terminated" is called if the entity to which we are subscribing terminates the subscription. "notified" is called when the entity to which we are subscribing changes its published state.</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=1293561948841" style="border: 0px solid black" /></span></p>
<p>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 subclass of the InboundSubscription interface.<br/>
4. The SIP subscription component begins querying its InboundSubscriptionListeners using the InboundSubscriptionListener::requested() method.<br/>
5. InboundSubscriptionListenerA does not support the subscription type, but InboundSubscriptionListenerB does, so it indicates a successful response. Note that in the diagram, InboundSubscriptionListenerB also functions as the InboundSubscriptionHandler.<br/>
6. The SIP subscription component sends a 200 OK to Bob.<br/>
7. The InboundSubscriptionHandler at some point in the future determines that the resource has undergone a change and so it sends a notify() message to the InboundSubscription.<br/>
8. The InboundSubscription 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 terminated() message to the InboundSubscriptionHandler.<br/>
11. The SIP component destroys the InboundSubscription and sends a 200 OK to Bob.</p>
<p>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.</p>
<p>5. One of the listeners creates an OutboundSubscription object with appropriate SubscriptionData set and calls OutboundSubscription::request().<br/>
7. The SIP subscription component sends an outbound SUBSCRIBE to the external resource that will report Alice's presence.<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 SubscriptionReason to the creator of the OutboundSubscription.<br/>
10. The handler of the inbound subscription can then respond to the inbound subscription request from step 4 with success.<br/>
11. The SIP subscription component sends a 200 OK to Bob.</p>
<p>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.</p>
<h1><a name="Supportforsubscriptionstoandfromexternalentities-LingeringQuestions%3A"></a>Lingering Questions:</h1>
<p>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)?</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=7&originalVersion=6">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>