moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-28 12:12:22 -05:00
Code Issues Releases Wiki Activity

re-organized manage subscriptions section

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1317 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2007-10-26 03:24:48 +00:00
parent c3925b609d
commit 9c31f12471
1 changed files with 133 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
xep-0060.xml
View File

@ -4112,8 +4112,9 @@ And by opposing end them?
<section2 topic='Manage Subscriptions' anchor='owner-subscriptions'> <section2 topic='Manage Subscriptions' anchor='owner-subscriptions'>
<p>A node owner may want to edit the list of subscriptions associated with a given node. Support for this feature ("pubsub#manage-subscriptions") is OPTIONAL.</p> <p>A node owner may want to edit the list of subscriptions associated with a given node. Support for this feature ("pubsub#manage-subscriptions") is OPTIONAL.</p>
<p>Note: This feature enables a node owner to set subscriptions for new entities; for nodes of type "whitelist", this enables the node owner to add subscribers.</p> <section3 topic='Retrieve Subscriptions List' anchor='owner-subscriptions-retrieve'>
<section3 topic='Request' anchor='owner-subscriptions-request'> <p>First the owner retrieves the affiliation list.</p>
<section4 topic='Request' anchor='owner-subscriptions-retrieve-request'>
<p>In order to request a list of all subscriptions, a node owner MUST send a subscriptions request, consisting of a &lt;subscriptions/&gt; element whose 'node' attribute specifies the NodeID of the relevant node.</p> <p>In order to request a list of all subscriptions, a node owner MUST send a subscriptions request, consisting of a &lt;subscriptions/&gt; element whose 'node' attribute specifies the NodeID of the relevant node.</p>
<example caption='Owner requests all subscriptions'><![CDATA[ <example caption='Owner requests all subscriptions'><![CDATA[
<iq type='get' <iq type='get'
@ -4125,8 +4126,8 @@ And by opposing end them?
</pubsub> </pubsub>
</iq> </iq>
]]></example> ]]></example>
</section3> </section4>
<section3 topic='Success Case' anchor='owner-subscriptions-success'> <section4 topic='Success Case' anchor='owner-subscriptions-retrieve-success'>
<p>If no error occurs, the service MUST return the list of subscriptions for entities whose subscription state is "subscribed" or "unconfigured" (it MUST NOT return entities whose subscription state is "none" and SHOULD NOT return entities whose subscription state is "pending"). The result MAY specify multiple &lt;subscription/&gt; elements for the same entity (JID), but each element MUST possess a distinct value of the 'subid' attribute (as shown below).</p> <p>If no error occurs, the service MUST return the list of subscriptions for entities whose subscription state is "subscribed" or "unconfigured" (it MUST NOT return entities whose subscription state is "none" and SHOULD NOT return entities whose subscription state is "pending"). The result MAY specify multiple &lt;subscription/&gt; elements for the same entity (JID), but each element MUST possess a distinct value of the 'subid' attribute (as shown below).</p>
<example caption='Service returns list of subscriptions'><![CDATA[ <example caption='Service returns list of subscriptions'><![CDATA[
<iq type='result' <iq type='result'
@ -4143,8 +4144,8 @@ And by opposing end them?
</pubsub> </pubsub>
</iq> </iq>
]]></example> ]]></example>
</section3> </section4>
<section3 topic='Error Cases' anchor='owner-subscriptions-error'> <section4 topic='Error Cases' anchor='owner-subscriptions-retrieve-error'>
<p>There are several reasons why the manage subscriptions request might fail:</p> <p>There are several reasons why the manage subscriptions request might fail:</p>
<ol> <ol>
<li>The service does not support subscription management.</li> <li>The service does not support subscription management.</li>
@ -4152,7 +4153,7 @@ And by opposing end them?
<li>The specified node does not exist.</li> <li>The specified node does not exist.</li>
</ol> </ol>
<p>These error cases are described more fully in the following sections.</p> <p>These error cases are described more fully in the following sections.</p>
<section4 topic='Subscription Management Not Supported' anchor='owner-subscriptions-error-notsupported'> <section5 topic='Subscription Management Not Supported' anchor='owner-subscriptions-retrieve-error-notsupported'>
<p>If an implementation does not support subscription management, it MUST return a &feature; error, specifying a pubsub-specific error condition of &lt;unsupported/&gt; and a feature of "manage-subscriptions".</p> <p>If an implementation does not support subscription management, it MUST return a &feature; error, specifying a pubsub-specific error condition of &lt;unsupported/&gt; and a feature of "manage-subscriptions".</p>
<example caption='Node or service does not support subscription management'><![CDATA[ <example caption='Node or service does not support subscription management'><![CDATA[
<iq type='error' <iq type='error'
@ -4168,8 +4169,8 @@ And by opposing end them?
</error> </error>
</iq> </iq>
]]></example> ]]></example>
</section4> </section5>
<section4 topic='Insufficient Privileges' anchor='owner-subscriptions-error-forbidden'> <section5 topic='Insufficient Privileges' anchor='owner-subscriptions-retrieve-error-forbidden'>
<p>If the requesting entity is not a node owner, the service MUST return a &forbidden; error.</p> <p>If the requesting entity is not a node owner, the service MUST return a &forbidden; error.</p>
<example caption='Entity is not an owner'><![CDATA[ <example caption='Entity is not an owner'><![CDATA[
<iq type='error' <iq type='error'
@ -4183,8 +4184,8 @@ And by opposing end them?
</error> </error>
</iq> </iq>
]]></example> ]]></example>
</section4> </section5>
<section4 topic='Node Does Not Exist' anchor='owner-subscriptions-error-node'> <section5 topic='Node Does Not Exist' anchor='owner-subscriptions-retrieve-error-node'>
<p>If the node does not exist, the service MUST return an &notfound; error.</p> <p>If the node does not exist, the service MUST return an &notfound; error.</p>
<example caption='Node does not exist'><![CDATA[ <example caption='Node does not exist'><![CDATA[
<iq type='error' <iq type='error'
@ -4198,9 +4199,11 @@ And by opposing end them?
</error> </error>
</iq> </iq>
]]></example> ]]></example>
</section5>
</section4> </section4>
</section3> </section3>
<section3 topic='Modifying Subscriptions' anchor='owner-subscriptions-modify'> <section3 topic='Modify Subscriptions' anchor='owner-subscriptions-modify'>
<section4 topic='Request' anchor='owner-subscriptions-modify-request'>
<p>Upon receiving the subscriptions list, the node owner MAY modify subscription states. The owner MUST send only modified subscription states (i.e., a "delta"), not the complete list. (Note: If the 'subscription' attribute is not specified in a modification request, then the value MUST NOT be changed.)</p> <p>Upon receiving the subscriptions list, the node owner MAY modify subscription states. The owner MUST send only modified subscription states (i.e., a "delta"), not the complete list. (Note: If the 'subscription' attribute is not specified in a modification request, then the value MUST NOT be changed.)</p>
<example caption='Owner modifies subscriptions'><![CDATA[ <example caption='Owner modifies subscriptions'><![CDATA[
<iq type='set' <iq type='set'
@ -4214,16 +4217,77 @@ And by opposing end them?
</pubsub> </pubsub>
</iq> </iq>
]]></example> ]]></example>
</section4>
<section4 topic='Success Case' anchor='owner-subscriptions-modify-success'>
<example caption='Service responds with success'><![CDATA[ <example caption='Service responds with success'><![CDATA[
<iq type='result' <iq type='result'
from='pubsub.shakespeare.lit' from='pubsub.shakespeare.lit'
id='subman2'/> id='subman2'/>
]]></example> ]]></example>
</section3> </section4>
<section3 topic='Deleting a Subscriber' anchor='owner-subscriptions-delete'> <section4 topic='Error Cases' anchor='owner-subscriptions-modify-error'>
<p>In order to remove an entity from the subscriptions list, the owner MUST set the value of the 'subscription' attribute to "none" and the service MUST remove that entity from the subscriptions list and not return it in response to future list requests.</p> <p>There are several reasons why the modify subscriptions request might fail:</p>
</section3> <ol>
<section3 topic='Multiple Simultaneous Modifications' anchor='owner-subscriptions-multi'> <li>The service does not support subscription management.</li>
<li>The requesting entity does not have sufficient privileges to manage subscriptions.</li>
<li>The specified node does not exist.</li>
</ol>
<p>These error cases are described more fully in the following sections.</p>
<section5 topic='Subscription Management Not Supported' anchor='owner-subscriptions-modify-error-notsupported'>
<p>If an implementation does not support subscription management, it MUST return a &feature; error, specifying a pubsub-specific error condition of &lt;unsupported/&gt; and a feature of "manage-subscriptions".</p>
<example caption='Node or service does not support subscription management'><![CDATA[
<iq type='error'
from='pubsub.shakespeare.lit'
id='subman2'>
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
<subscriptions node='princely_musings'/>
<subscription jid='bard@shakespeare.lit' subscription='subscribed'/>
</subscriptions>
</pubsub>
<error type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
feature='manage-subscriptions'/>
</error>
</iq>
]]></example>
</section5>
<section5 topic='Insufficient Privileges' anchor='owner-subscriptions-retrieve-error-forbidden'>
<p>If the requesting entity is not a node owner, the service MUST return a &forbidden; error.</p>
<example caption='Entity is not an owner'><![CDATA[
<iq type='error'
from='pubsub.shakespeare.lit'
id='subman1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
<subscriptions node='princely_musings'/>
<subscription jid='bard@shakespeare.lit' subscription='subscribed'/>
</subscriptions>
</pubsub>
<error type='auth'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section5>
<section5 topic='Node Does Not Exist' anchor='owner-subscriptions-retrieve-error-node'>
<p>If the node does not exist, the service MUST return an &notfound; error.</p>
<example caption='Node does not exist'><![CDATA[
<iq type='error'
from='pubsub.shakespeare.lit'
id='subman2'>
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
<subscriptions node='princely_musings'/>
<subscription jid='bard@shakespeare.lit' subscription='subscribed'/>
</subscriptions>
</pubsub>
<error type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section5>
</section4>
<section4 topic='Multiple Simultaneous Modifications' anchor='owner-subscriptions-multi'>
<p>The owner MAY change multiple subscriptions in a single request. If one of the entity elements specified is invalid, the service MUST return an IQ error (which SHOULD be &notacceptable;) with the invalid entries, where the subscription returned is the original, un-altered subscription.</p> <p>The owner MAY change multiple subscriptions in a single request. If one of the entity elements specified is invalid, the service MUST return an IQ error (which SHOULD be &notacceptable;) with the invalid entries, where the subscription returned is the original, un-altered subscription.</p>
<example caption='Owner sets subscription for multiple entities'><![CDATA[ <example caption='Owner sets subscription for multiple entities'><![CDATA[
<iq type='set' <iq type='set'
@ -4254,6 +4318,10 @@ And by opposing end them?
</iq> </iq>
]]></example> ]]></example>
<p>If errors occur during a modification request for multiple entities, the pubsub service MUST return any &lt;subscription/&gt; element(s) which caused the error. Returned entities which failed to be modified MUST include the existing 'subscription' attribute. Any entity elements which are not returned in an IQ error case MUST be treated as successful modifications. The owner MAY specify multiple &lt;subscription/&gt; elements for the same entity, but each element MUST possess a distinct value of the 'subid' attribute.</p> <p>If errors occur during a modification request for multiple entities, the pubsub service MUST return any &lt;subscription/&gt; element(s) which caused the error. Returned entities which failed to be modified MUST include the existing 'subscription' attribute. Any entity elements which are not returned in an IQ error case MUST be treated as successful modifications. The owner MAY specify multiple &lt;subscription/&gt; elements for the same entity, but each element MUST possess a distinct value of the 'subid' attribute.</p>
</section4>
</section3>
<section3 topic='Delete a Subscriber' anchor='owner-subscriptions-delete'>
<p>In order to remove an entity from the subscriptions list, the owner MUST set the value of the 'subscription' attribute to "none" and the service MUST remove that entity from the subscriptions list and not return it in response to future list requests.</p>
</section3> </section3>
<section3 topic='Notifying Subscribers' anchor='owner-subscriptions-notify'> <section3 topic='Notifying Subscribers' anchor='owner-subscriptions-notify'>
<p>An implementation SHOULD send notification to an entity whose subscription has changed (see the <link url='#impl-subchange'>Notification of Subscription State Changes</link> section of this document).</p> <p>An implementation SHOULD send notification to an entity whose subscription has changed (see the <link url='#impl-subchange'>Notification of Subscription State Changes</link> section of this document).</p>
@ -4267,11 +4335,11 @@ And by opposing end them?
</section3> </section3>
</section2> </section2>
<section2 topic='Manage Affiliations' anchor='owner-affilmanage'> <section2 topic='Manage Affiliations' anchor='owner-affiliations'>
<p>A node owner may want to manage the affiliations of entities associated with a given node and to set affiliations for new entities. Support for this feature ("pubsub#modify-affiliations") is OPTIONAL.</p> <p>A node owner may want to manage the affiliations of entities associated with a given node and to set affiliations for new entities. Support for this feature ("pubsub#modify-affiliations") is OPTIONAL.</p>
<section3 topic='Retrieve Affiliations List' anchor='owner-affilmanage-retrieve'> <section3 topic='Retrieve Affiliations List' anchor='owner-affiliations-retrieve'>
<p>First the owner retrieves the affiliation list.</p> <p>First the owner retrieves the affiliation list.</p>
<section4 topic='Request' anchor='owner-affilmanage-retrieve-request'> <section4 topic='Request' anchor='owner-affiliations-retrieve-request'>
<p>In order to request a list of all affiliated entities, a node owner MUST send an affiliations request, consisting of an &lt;affiliations/&gt; element whose 'node' attribute specifies the NodeID of the relevant node.</p> <p>In order to request a list of all affiliated entities, a node owner MUST send an affiliations request, consisting of an &lt;affiliations/&gt; element whose 'node' attribute specifies the NodeID of the relevant node.</p>
<example caption='Owner requests all affiliated entities'><![CDATA[ <example caption='Owner requests all affiliated entities'><![CDATA[
<iq type='get' <iq type='get'
@ -4284,7 +4352,7 @@ And by opposing end them?
</iq> </iq>
]]></example> ]]></example>
</section4> </section4>
<section4 topic='Success Case' anchor='owner-affilmanage-retrieve-success'> <section4 topic='Success Case' anchor='owner-affiliations-retrieve-success'>
<p>If no error occurs, the service MUST return the list of entities whose affiliation is "owner", "publisher", or "outcast" (it MUST NOT return entities whose affiliation is "none").</p> <p>If no error occurs, the service MUST return the list of entities whose affiliation is "owner", "publisher", or "outcast" (it MUST NOT return entities whose affiliation is "none").</p>
<example caption='Service returns list of affiliated entities'><![CDATA[ <example caption='Service returns list of affiliated entities'><![CDATA[
<iq type='result' <iq type='result'
@ -4300,7 +4368,7 @@ And by opposing end them?
</iq> </iq>
]]></example> ]]></example>
</section4> </section4>
<section4 topic='Error Cases' anchor='owner-affilmanage-retrieve-error'> <section4 topic='Error Cases' anchor='owner-affiliations-retrieve-error'>
<p>There are several reasons why the affiliated entities request might fail:</p> <p>There are several reasons why the affiliated entities request might fail:</p>
<ol> <ol>
<li>The service does not support modification of affiliations.</li> <li>The service does not support modification of affiliations.</li>
@ -4308,7 +4376,7 @@ And by opposing end them?
<li>The specified node does not exist.</li> <li>The specified node does not exist.</li>
</ol> </ol>
<p>These error cases are described more fully in the following sections.</p> <p>These error cases are described more fully in the following sections.</p>
<section5 topic='Affiliation Modification Not Supported' anchor='owner-affilmanage-retrieve-notsupported'> <section5 topic='Affiliation Modification Not Supported' anchor='owner-affiliations-retrieve-notsupported'>
<p>If an implementation does not support modification of affiliations, it MUST return a &feature; error, specifying a pubsub-specific error condition of &lt;unsupported/&gt; and a feature of "modify-affiliations".</p> <p>If an implementation does not support modification of affiliations, it MUST return a &feature; error, specifying a pubsub-specific error condition of &lt;unsupported/&gt; and a feature of "modify-affiliations".</p>
<example caption='Node or service does not support affiliation management'><![CDATA[ <example caption='Node or service does not support affiliation management'><![CDATA[
<iq type='error' <iq type='error'
@ -4325,7 +4393,7 @@ And by opposing end them?
</iq> </iq>
]]></example> ]]></example>
</section5> </section5>
<section5 topic='Insufficient Privileges' anchor='owner-affilmanage-retrieve-forbidden'> <section5 topic='Insufficient Privileges' anchor='owner-affiliations-retrieve-forbidden'>
<p>If the requesting entity is not a node owner, the service MUST return a &forbidden; error.</p> <p>If the requesting entity is not a node owner, the service MUST return a &forbidden; error.</p>
<example caption='Entity is not an owner'><![CDATA[ <example caption='Entity is not an owner'><![CDATA[
<iq type='error' <iq type='error'
@ -4340,7 +4408,7 @@ And by opposing end them?
</iq> </iq>
]]></example> ]]></example>
</section5> </section5>
<section5 topic='Node Does Not Exist' anchor='owner-affilmanage-retrieve-node'> <section5 topic='Node Does Not Exist' anchor='owner-affiliations-retrieve-node'>
<p>If the node does not exist, the service MUST return an &notfound; error.</p> <p>If the node does not exist, the service MUST return an &notfound; error.</p>
<example caption='Node does not exist'><![CDATA[ <example caption='Node does not exist'><![CDATA[
<iq type='error' <iq type='error'
@ -4357,9 +4425,9 @@ And by opposing end them?
</section5> </section5>
</section4> </section4>
</section3> </section3>
<section3 topic='Modify Affiliation' anchor='owner-affilmanage-modify'> <section3 topic='Modify Affiliation' anchor='owner-affiliations-modify'>
<p>A node owner may want to edit the affiliation of an entity associated with a given node or to set the affiliation for a new entity.</p> <p>A node owner may want to edit the affiliation of an entity associated with a given node or to set the affiliation for a new entity.</p>
<section4 topic='Request' anchor='owner-affilmanage-modify-request'> <section4 topic='Request' anchor='owner-affiliations-modify-request'>
<p>In order to modify an affiliation, a node owner MUST send an IQ set containing the modified affiliation or affiliations. The owner MUST send only modified affiliations (i.e., a "delta"), not the complete list. (Note: If the 'affiliation' attribute is not specified in a modification request, then the value MUST NOT be changed.)</p> <p>In order to modify an affiliation, a node owner MUST send an IQ set containing the modified affiliation or affiliations. The owner MUST send only modified affiliations (i.e., a "delta"), not the complete list. (Note: If the 'affiliation' attribute is not specified in a modification request, then the value MUST NOT be changed.)</p>
<example caption='Owner modifies affiliation'><![CDATA[ <example caption='Owner modifies affiliation'><![CDATA[
<iq type='set' <iq type='set'
@ -4374,7 +4442,7 @@ And by opposing end them?
</iq> </iq>
]]></example> ]]></example>
</section4> </section4>
<section4 topic='Success Case' anchor='owner-affilmanage-modify-success'> <section4 topic='Success Case' anchor='owner-affiliations-modify-success'>
<example caption='Service responds with success'><![CDATA[ <example caption='Service responds with success'><![CDATA[
<iq type='result' <iq type='result'
from='pubsub.shakespeare.lit' from='pubsub.shakespeare.lit'
@ -4390,7 +4458,7 @@ And by opposing end them?
<li>The specified node does not exist.</li> <li>The specified node does not exist.</li>
</ol> </ol>
<p>These error cases are described more fully in the following sections.</p> <p>These error cases are described more fully in the following sections.</p>
<section5 topic='Affiliation Modification Not Supported' anchor='owner-affilmanage-retrieve-notsupported'> <section5 topic='Affiliation Modification Not Supported' anchor='owner-affiliations-retrieve-notsupported'>
<p>If an implementation does not support modification of affiliations, it MUST return a &feature; error, specifying a pubsub-specific error condition of &lt;unsupported/&gt; and a feature of "modify-affiliations".</p> <p>If an implementation does not support modification of affiliations, it MUST return a &feature; error, specifying a pubsub-specific error condition of &lt;unsupported/&gt; and a feature of "modify-affiliations".</p>
<example caption='Node or service does not support affiliation management'><![CDATA[ <example caption='Node or service does not support affiliation management'><![CDATA[
<iq type='error' <iq type='error'
@ -4424,7 +4492,7 @@ And by opposing end them?
</iq> </iq>
]]></example> ]]></example>
</section5> </section5>
<section5 topic='Insufficient Privileges' anchor='owner-affilmanage-retrieve-forbidden'> <section5 topic='Insufficient Privileges' anchor='owner-affiliations-retrieve-forbidden'>
<p>If the requesting entity is not a node owner, the service MUST return a &forbidden; error.</p> <p>If the requesting entity is not a node owner, the service MUST return a &forbidden; error.</p>
<example caption='Entity is not an owner'><![CDATA[ <example caption='Entity is not an owner'><![CDATA[
<iq type='error' <iq type='error'
@ -4439,7 +4507,7 @@ And by opposing end them?
</iq> </iq>
]]></example> ]]></example>
</section5> </section5>
<section5 topic='Node Does Not Exist' anchor='owner-affilmanage-retrieve-node'> <section5 topic='Node Does Not Exist' anchor='owner-affiliations-retrieve-node'>
<p>If the node does not exist, the service MUST return an &notfound; error.</p> <p>If the node does not exist, the service MUST return an &notfound; error.</p>
<example caption='Node does not exist'><![CDATA[ <example caption='Node does not exist'><![CDATA[
<iq type='error' <iq type='error'
@ -4490,7 +4558,7 @@ And by opposing end them?
<p>The state chart at the beginning of this document is a MUST-IMPLEMENT set of rules for checking possible state transitions. Implementations MAY enforce other (more strict) rules. If errors occur during a modification request for multiple entities, the pubsub service MUST return any &lt;affiliation/&gt; element(s) which caused the error. Returned entities which failed to be modified MUST include the existing 'affiliation' attribute. Any entity elements which are not returned in an IQ error case MUST be treated as successful modifications. The owner MUST NOT specify multiple &lt;affiliation/&gt; elements for the same entity; otherwise the service MUST return a &badrequest; error.</p> <p>The state chart at the beginning of this document is a MUST-IMPLEMENT set of rules for checking possible state transitions. Implementations MAY enforce other (more strict) rules. If errors occur during a modification request for multiple entities, the pubsub service MUST return any &lt;affiliation/&gt; element(s) which caused the error. Returned entities which failed to be modified MUST include the existing 'affiliation' attribute. Any entity elements which are not returned in an IQ error case MUST be treated as successful modifications. The owner MUST NOT specify multiple &lt;affiliation/&gt; elements for the same entity; otherwise the service MUST return a &badrequest; error.</p>
</section4> </section4>
</section3> </section3>
<section3 topic='Deleting an Entity' anchor='owner-affiliations-delete'> <section3 topic='Delete an Entity' anchor='owner-affiliations-delete'>
<p>In order to remove an entity from the affiliations list, the owner MUST set the value of the 'affiliation' attribute to "none" and the service MUST remove that entity from the affiliations list and not return it in response to future list requests.</p> <p>In order to remove an entity from the affiliations list, the owner MUST set the value of the 'affiliation' attribute to "none" and the service MUST remove that entity from the affiliations list and not return it in response to future list requests.</p>
</section3> </section3>
<section3 topic='Notifying Entities' anchor='owner-affiliations-notify'> <section3 topic='Notifying Entities' anchor='owner-affiliations-notify'>