<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/Subscription+Support">Subscription Support</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~mmichelson">Mark Michelson</a>
</h4>
<br/>
<h4>Changes (3)</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 sender; <br> //XXX To be continued <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">}</span> <span class="diff-added-words"style="background-color: #dfd;">};</span> <br></td></tr>
<tr><td class="diff-unchanged" >{newcode} <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > void renewed(Subscription sub); <br> void terminated(Subscription sub); <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">}</span> <span class="diff-added-words"style="background-color: #dfd;">};</span> <br></td></tr>
<tr><td class="diff-unchanged" >{newcode} <br> <br>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 out parameter of the "requested" method is in case a different listener than the one that was called into is to handle the 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;"> <br>The listener must also be able to communicate with the subscriber. The means of doing this will be in a subclass of Subscription class, InboundSubscription. <br> <br>{newcode:language=slice} <br>class InboundSubscription extends Subscription <br>{ <br> void accept(); <br> void deny(SubscriptionReason reason); <br> void terminate(); <br> void notify(SubscriptionState state); <br>}; <br>{newcode} <br> <br>The "accept" and "reject" methods are used to respond to a subscription request either positively or negatively. 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. Note the introduction of two new types here. SubscriptionReason 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. SubscriptionState is an abstract class whose subclasses will pertain to specific types of subscriptions. These subclasses will likely contain methods such that state can be converted into the format that the subscriber's protocol will understand. <br> <br>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 another subclass of Subscription, OutboundSubscription. <br> <br>{newcode:language=slice} <br>class OutboundSubscription extends Subscription <br>{ <br> void request(); <br> void renew(); <br> void cancel(); <br>} <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 "cancel" method is used to end a subscription. <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><b>Under Construction</b><br />This page is a work in progress.</td></tr></table></div>
<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.</p>
<p>A typical new subscription request can be seen as such:<br/>
1. Subscription request arrives at Asterisk SCF (SIP SUBSCRIBE would be an example)<br/>
2. The component that receives the subscription request broadcasts the new subscription to listeners.<br/>
3. A listener (or more than one?) can process the details of the subscription and decide what action to take.<br/>
4. The listener (or perhaps another entity that the listener has handed responsibility to) tells the original component how to respond.</p>
<p>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 ID 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.</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 Subscription
{
int expiration;
string addressee;
string sender;
//XXX To be continued
};
]]></script>
</div></div>
<p>Note that a subscription type is not listed. This is because specific types of subscriptions should be defined as derivations of the Subscription 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 SubscriptionListener
{
bool requested(Subscription sub, out SubscriptionListener Listener);
void renewed(Subscription sub);
void terminated(Subscription sub);
};
]]></script>
</div></div>
<p>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 out parameter of the "requested" method is in case a different listener than the one that was called into is to handle the subscription. The "renewed" method is called mostly as an informational means to let the listener know that the subscriber has renewed his subscription.</p>
<p>The listener must also be able to communicate with the subscriber. The means of doing this will be in a subclass of Subscription class, InboundSubscription.</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 InboundSubscription extends Subscription
{
void accept();
void deny(SubscriptionReason reason);
void terminate();
void notify(SubscriptionState state);
};
]]></script>
</div></div>
<p>The "accept" and "reject" methods are used to respond to a subscription request either positively or negatively. 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. Note the introduction of two new types here. SubscriptionReason 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. SubscriptionState is an abstract class whose subclasses will pertain to specific types of subscriptions. These subclasses will likely contain methods such that state can be converted into the format that the subscriber's protocol will understand.</p>
<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 another subclass of Subscription, 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[]]></script>
</div></div>
<p>class OutboundSubscription extends Subscription</p>
<div class="error"><span class="error">Unknown macro: {
void request();
void renew();
void cancel();
}</span> </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 "cancel" method is used to end a subscription.</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/Subscription+Support">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=9568785&revisedVersion=2&originalVersion=1">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/TOP/Subscription+Support?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>