<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 (47)</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" > string recipient; <br> string sender; <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">SubscriptionState</span> <span class="diff-added-words"style="background-color: #dfd;">PublishedState</span> state; <br></td></tr>
<tr><td class="diff-unchanged" >}; <br>{newcode} <br> <br></td></tr>
<tr><td class="diff-changed-lines" >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 <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">SubscriptionState</span> <span class="diff-added-words"style="background-color: #dfd;">PublishedState</span> 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 <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">tell of</span> <span class="diff-added-words"style="background-color: #dfd;">convey</span> the current presence state, like "available" or "busy." <br></td></tr>
<tr><td class="diff-unchanged" >h1. Inbound Subscriptions <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >interface InboundSubscriptionListener <br>{ <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"> void requested(InboundSubscription *sub); <br> void renewed(InboundSubscription *sub); <br> void terminated(InboundSubscription *sub); <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> InboundSubscriptionResponse requested(SubscriptionData data, InboundSubscription *sub); <br></td></tr>
<tr><td class="diff-unchanged" >}; <br>{newcode} <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">This is fairly straightforward. The "requested" method will be called when an entity has requested a subscription to a service and the "terminated" method will be called when an entity ends a subscription. The "renewed" method is called mostly as an informational means to let the listener know that the subscriber has renewed his subscription. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">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: <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;">The listener must also be able to communicate with the subscriber. The means of doing this will be using InboundSubscription. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{newcode:language=slice} <br>class InboundSubscriptionResponse <br>{ <br> SubscriptionReason reason; <br> InboundSubscriptionHandler *handler; <br>}; <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">enum SubscriptionReasons <br>{ <br> //XXX More reasons may need to be added here. <br> //This is primarily for illustrative purposes. <br> Success, <br> NotPermitted, <br> RecipientUnknown, <br> NotSupported <br>}; <br> <br>class SubscriptionReason <br>{ <br> SubscriptionReasons reason; <br>}; <br>{newcode} <br> <br>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: <br> <br></td></tr>
<tr><td class="diff-unchanged" >{newcode:language=slice} <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">class InboundSubscription <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">interface InboundSubscriptionHandler <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 accept(InboundSubscriptionListener *listener); <br> void deny(SubscriptionReason reason); <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> void renewed(SubscriptionData data); <br> void expired(SubscriptionData data); <br> void terminated(SubscriptionData data); <br>}; <br>{newcode} <br> <br>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. <br> <br>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(). <br> <br>{newcode:language=slice} <br>interface InboundSubscription <br>{ <br></td></tr>
<tr><td class="diff-unchanged" > void terminate(); <br></td></tr>
<tr><td class="diff-changed-lines" >void <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">notify(SubscriptionState</span> <span class="diff-added-words"style="background-color: #dfd;">notify(PublishedState</span> state); <br></td></tr>
<tr><td class="diff-changed-lines" >void <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">addListeners(InboundSubscriptionListenerSeq</span> <span class="diff-added-words"style="background-color: #dfd;">addHandlers(InboundSubscriptionHandlerSeq</span> listeners); <br></td></tr>
<tr><td class="diff-changed-lines" >void <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">removeListeners(InboundSubscriptionListenerSeq</span> <span class="diff-added-words"style="background-color: #dfd;">removeHandlers(InboundSubscriptionHandlerSeq</span> listeners); <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"> SubscriptionData data; <br></td></tr>
<tr><td class="diff-unchanged" >}; <br>{newcode} <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The "accept" and "reject" methods are used to respond to a subscription request either positively or negatively. The "accept" method has an InboundSubscriptionListener parameter that indicates the listener to which the subscriber should send any updates from the subscriber. The "terminate" method is a method for a listener to end a subscription. The "notify" method is used to indicate to the subscriber that the subscription state has been updated. "addListeners" and "removeListeners" provides methods by which more components may listen for events on the subscription. The "data" member contains the data pertaining to the subscription. Note the introduction the SubscriptionReason type. It is a means of allowing for the listener to notify the subscriber of why his request has been rejected. This can be used by SIP, as an example, to compose the appropriate 4xx or 5xx message in response to the incoming SUBSCRIBE. SubscriptionReason will be a class that will consist of an enum of common reasons a subscription is not allowed (e.g. The addressee cannot be identified, the subscriber is not allowed to subscribe to a particular resource). In addition, there may be subclasses of SubscriptionReason to account for reasons that may pertain to specific types of subscriptions. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">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. <br> <br></td></tr>
<tr><td class="diff-unchanged" >h1. Outbound Subscriptions <br></td></tr>
<tr><td class="diff-changed-lines" >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 <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">another subclass of Subscription,</span> OutboundSubscription. <br></td></tr>
<tr><td class="diff-unchanged" > <br>{newcode:language=slice} <br>class OutboundSubscription <br>{ <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"> void request(OutboundSubscriptionListener *listener); <br> void renew(); <br> void terminate(); <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> SubscriptionReason request(SubscriptionData data, OutboundSubscriptionHandler *handler); <br> void renew(SubscriptionData data); <br> void terminate(SubscriptionData data); <br></td></tr>
<tr><td class="diff-changed-lines" >void <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">addListeners(OutboundSubscriptionListenerSeq</span> <span class="diff-added-words"style="background-color: #dfd;">addHandlers(OutboundSubscriptionHandlerSeq</span> listeners); <br></td></tr>
<tr><td class="diff-changed-lines" >void <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">removeListeners(OutboundSubscriptionListenerSeq</span> <span class="diff-added-words"style="background-color: #dfd;">removeHandlers(OutboundSubscriptionHandlerSeq</span> listeners); <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"> SubscriptionData data; <br></td></tr>
<tr><td class="diff-unchanged" >}; <br>{newcode} <br> <br>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></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Once a subscription is sent out, Asterisk SCF will need a way of knowing about whether the subscription was accepted or rejected, as well as knowing when changes have been made to the state of the outbound subscription. For this, we have the OutboundSubscriptionListener class. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">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. <br></td></tr>
<tr><td class="diff-unchanged" > <br>{newcode:language=slice} <br></td></tr>
<tr><td class="diff-changed-lines" >interface <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">OutboundSubscriptionListener</span> <span class="diff-added-words"style="background-color: #dfd;">OutboundSubscriptionHandler</span> <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 accepted(OutboundSubscription *sub); <br> void denied(OutboundSubscription *sub, SubscriptionReason reason); <br></td></tr>
<tr><td class="diff-unchanged" > void terminated(OutboundSubscription *sub); <br></td></tr>
<tr><td class="diff-changed-lines" >void notified(OutboundSubscription *sub, <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">SubscriptionState</span> <span class="diff-added-words"style="background-color: #dfd;">PublishedState</span> state); <br></td></tr>
<tr><td class="diff-unchanged" >}; <br>{newcode} <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">As you can see, this is pretty much the passive version of the InboundSubscription items. "accepted" and "denied" are called in order to let Asterisk SCF know if an outbound subscription has been accepted or rejected. Rejection includes a reason why the subscription was rejected. "terminated" is called if the entity to which we are subscribing terminates the subscription. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">"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. <br></td></tr>
<tr><td class="diff-unchanged" >h1. Simple Examples <br>So let's consider a typical sequence of events: <br> <br>1. Bob sends a SIP SUBSCRIBE to Asterisk SCF for Alice's presence. <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">2. Asterisk SCF receives the incoming SUBSCRIBE. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">2. Asterisk SCF's SIP subscription component receives the incoming SUBSCRIBE. <br></td></tr>
<tr><td class="diff-unchanged" >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-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">4. The SIP subscription component places this SubscriptionData object inside an InboundSubscription object. <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-changed-words"><span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">5</span><span class="diff-added-chars"style="background-color: #dfd;">4</span>.</span> The SIP subscription component begins querying its <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">InboundSubscription listeners</span> <span class="diff-added-words"style="background-color: #dfd;">InboundSubscriptionListeners</span> using the InboundSubscriptionListener::requested() method. <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">6. One of the listeners recognizes that he is responsible for knowing Alice's presence and thus responds with the InboundSubscription::accept() method. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">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-changed-lines" ><span class="diff-changed-words"><span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">7</span><span class="diff-added-chars"style="background-color: #dfd;">6</span>.</span> The SIP subscription component sends a 200 OK to Bob. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >At this point, the SIP subscription component has <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">a listener</span> <span class="diff-added-words"style="background-color: #dfd;">an InboundSubscriptionHandler</span> 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 <span class="diff-changed-words">SCF<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;"> with no additional listeners</span>.</span> <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, a listener doesn't simply respond with success to the inbound subscription, but rather it sends an outbound subscription out and responds to the inbound subscription based on the success of the outbound one. Steps 1-5 are the same as before. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">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></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;">6. One of the listeners creates an OutboundSubscription object with appropriate data set and calls its request() method. <br>7. The SIP subscription component sends an outbound SUBSCRIBE. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">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></td></tr>
<tr><td class="diff-unchanged" >8. At some point, the SIP subscription component receives a 200 OK for the outbound SUBSCRIBE. <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">9. The SIP subscription component then uses the OutboundSubscriptionListener that was passed in the request() method to call the accepted() method. <br>10. The OutboundSubscriptionListener then calls InboundSubscription::accept(). <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">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></td></tr>
<tr><td class="diff-unchanged" >11. The SIP subscription component sends a 200 OK to Bob. <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >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></td></tr>
<tr><td class="diff-changed-lines" >4. Is having <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">SubscriptionState</span> <span class="diff-added-words"style="background-color: #dfd;">PublishedState</span> 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></td></tr>
<tr><td class="diff-unchanged" >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>
</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>1. Bob sends a SIP SUBSCRIBE to Asterisk SCF for Alice's presence.<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. Perhaps in this case it is a SipPresenceSubscriptionData object.<br/>
4. The SIP subscription component begins querying its InboundSubscriptionListeners using the InboundSubscriptionListener::requested() method.<br/>
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/>
6. The SIP subscription component sends a 200 OK to Bob.</p>
<p>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.</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=6&originalVersion=5">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>