mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-28 12:12:22 -05:00
more edits
This commit is contained in:
Steve Kille
parent
7f44878178
commit
7340146bc3
250
xep-0369-PAM.xml
250
xep-0369-PAM.xml
@ -198,13 +198,15 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
|||||||
from='hag66@shakespeare.example/UUID-a1j/7533'
|
from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||||
to='hag66@shakespeare.example'
|
to='hag66@shakespeare.example'
|
||||||
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||||
<join xmlns='urn:xmpp:mix:core:0'
|
<client-join xmlns='urn:xmpp:mix:core:0'>
|
||||||
channel='coven@mix.shakespeare.example'>
|
<channel='coven@mix.shakespeare.example'>
|
||||||
<subscribe node='urn:xmpp:mix:nodes:messages'/>
|
<join xmlns='urn:xmpp:mix:core:0'>
|
||||||
<subscribe node='urn:xmpp:mix:nodes:presence'/>
|
<subscribe node='urn:xmpp:mix:nodes:messages'/>
|
||||||
<subscribe node='urn:xmpp:mix:nodes:participants'/>
|
<subscribe node='urn:xmpp:mix:nodes:presence'/>
|
||||||
<subscribe node='urn:xmpp:mix:nodes:info'/>
|
<subscribe node='urn:xmpp:mix:nodes:participants'/>
|
||||||
</join>
|
<subscribe node='urn:xmpp:mix:nodes:info'/>
|
||||||
|
</join>
|
||||||
|
</client-join>
|
||||||
</iq>
|
</iq>
|
||||||
]]></example>
|
]]></example>
|
||||||
|
|
||||||
@ -230,6 +232,240 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
|||||||
</section2>
|
</section2>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<section3 topic='Joining a Channel' anchor='usecase-user-join'>
|
||||||
|
<p>A user joins a channel by sending a MIX "join" command from one of the user's clients. There is no default set of nodes, so the user MUST specify the set of nodes to be subscribed to. To achieve the equivalent service to MUC, a user would subscribe to both messages and presence nodes. A user will typically subscribe to at least the message and/or presence nodes but MAY join and not subscribe to any nodes. Note that the presence node is specified in MIX-PRESECNCE. The <join/> is a child element of <iq/> element. The <join/> element is qualified by the 'urn:xmpp:mix:core:0' namespace. The channel is specified by a 'channel' attribute in the <join/> element. The requested nodes are encoded as <subscribe/> child elements of the <join/> element.
|
||||||
|
The join leads to the server subscribing the user to each of the requested nodes associated with the channel. The MIX service will also add the user to the participant list by injecting a new item into the "urn:xmpp:mix:nodes:participants" node automatically.
|
||||||
|
|
||||||
|
</p>
|
||||||
|
<p>The default MIX model is that only channel participants are allowed to subscribe to nodes. A MIX channel MAY allow non-participant subscription. This will be handled by clients directly subscribing to the desired PubSub nodes.</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The user's server needs to make roster changes as part of the join functionality. Because of this, the join and leave operations need to operate indirectly. This is fully specified in MIX-PAM.
|
||||||
|
For this reason the initial join request is sent to the local server with the MIX channel specified as an attribute to the join. The join is sent from a client identified by a full JID to the user's bare JID.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<example caption="Client sends request to Local Server to Join a Channel"><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||||
|
to='hag66@shakespeare.example'
|
||||||
|
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||||
|
<join xmlns='urn:xmpp:mix:core:0'
|
||||||
|
channel='coven@mix.shakespeare.example'>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:messages'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:presence'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:participants'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:info'/>
|
||||||
|
</join>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The user’s server will then pass the request to the MIX channel, with the request coming from the user's bare JID.
|
||||||
|
</p>
|
||||||
|
<example caption="User's Server sends Join request to MIX Channel"><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='hag66@shakespeare.example'
|
||||||
|
to='coven@mix.shakespeare.example'
|
||||||
|
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||||
|
<join xmlns='urn:xmpp:mix:core:0'>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:messages'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:presence'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:participants'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:info'/>
|
||||||
|
</join>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The channel responds to the user's sever with an IQ-result addressed to the user's bare JID. This stanza includes the nodes to which the user has been successfully subscribed, as well as the bare JID that will be used for the user in this channel and added to the participant list. The JID returned in the join is the user's bare proxy JID. The following example shows the result of the above request when the request is completed in full. </p>
|
||||||
|
<example caption="Channel responds to User's Server"><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='coven@mix.shakespeare.example'
|
||||||
|
to='hag66@shakespeare.example'
|
||||||
|
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||||
|
<join xmlns='urn:xmpp:mix:core:0' jid='123456#coven@mix.shakespeare.example'>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:messages'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:presence'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:participants'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:info'/>
|
||||||
|
</join>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The user's server will then make roster modifications as set out in the next section.
|
||||||
|
After making these changes, the user's server will send the join response back to the client that made the join request, identified by the full JID. This is illustrated below:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<example caption="User's Server sends response to Client"><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='hag66@shakespeare.example'
|
||||||
|
to='hag66@shakespeare.example/UUID-a1j/7533'
|
||||||
|
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||||
|
<join xmlns='urn:xmpp:mix:core:0' jid='123456#coven@mix.shakespeare.example'>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:messages'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:presence'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:participants'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:info'/>
|
||||||
|
</join>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
This response informs the client that initiated the join request that the request has been completed. Note that the roster changes described in MIX-PAM will lead to roster update information being sent to all of the user's online clients, so that all of the user's clients will be updated with the new MIX channel information.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
If a user cannot be subscribed to one or more of the requested nodes (e.g., because the node does not exist), but can be subscribed to some the response simply lists the nodes successfully subscribed. If at least one node is requested and none of the nodes requested are successfully subscribed to, an error response is sent indicating the reason that the first node requested was not subscribed to. This error response will also include other nodes requested where subscription failed for the same reason. </p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The following response example shows a successful response to the initial request example where
|
||||||
|
the participant is not subscribed to all nodes associated with the channel (in this case only messages, participants, and information). This example shows the message from the MIX channel to the user's server, which will be modified and sent to the client.
|
||||||
|
</p>
|
||||||
|
<example caption="Channel Processes Join With Some Nodes Not Subscribed To"><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='hag66@shakespeare.example'
|
||||||
|
to='coven@mix.shakespeare.example'
|
||||||
|
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||||
|
<join xmlns='urn:xmpp:mix:core:0' jid='123456#coven@mix.shakespeare.example'>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:messages'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:participants'/>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:info'/>
|
||||||
|
</join>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>The channel also adds the user to the participants node and sends a notification to subscribers of the participants node. The following example shows such a notification.</p>
|
||||||
|
<example caption="Channel Distributes New Participant Information"><![CDATA[
|
||||||
|
<message from='coven@mix.shakespeare.example'
|
||||||
|
to='hecate@shakespeare.example'
|
||||||
|
id='5A9C7398-DB13-4BFA-A091-2D466C710AAF'>
|
||||||
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
||||||
|
<items node='urn:xmpp:mix:nodes:participants'>
|
||||||
|
<item id='123456#coven@mix.shakespeare.example'>
|
||||||
|
<participant xmlns='urn:xmpp:mix:core:0'>
|
||||||
|
<nick>third witch</nick>
|
||||||
|
<jid>hag66@shakespeare.example</jid>
|
||||||
|
</participant>
|
||||||
|
</item>
|
||||||
|
</items>
|
||||||
|
</event>
|
||||||
|
</message>
|
||||||
|
]]></example>
|
||||||
|
<p>The user that has been added to the channel is identified by the item id of the item added to the Participants node, which is the proxy JID of the new channel participant. Note that the <participant> element MUST NOT include a nick of the user being added. The nick MAY be set after the join.</p>
|
||||||
|
<p>
|
||||||
|
At the same time the participant MUST be added to the JID Map node, to map from proxy JID to real JID. For a JID Maybe Visible channel, the participant MUST be added to the JID Maybe Visible Map node. The value in this node MUST reflect the user's visibility preference for the channel and MUST be updated to reflect any changes to this preference.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
A user MAY subsequently modify subscription to nodes in a channel by sending a subscription modification request encoded as a <update-subscription/> child element of <iq/> element. The <update-subscription/> element is qualified by the 'urn:xmpp:mix:core:0' namespace. The requested notes are encoded as <subscribe/> child elements of the <update-subscription/> element with the node name encoded as a 'node' attribute. This modification goes directly from client to MIX channel, as this change does not impact the roster and so does not need any local action. The following example shows subscription modification.
|
||||||
|
</p>
|
||||||
|
<example caption="User Modifies Subscription Request"><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||||
|
to='coven@mix.shakespeare.example'
|
||||||
|
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||||
|
<update-subscription xmlns='urn:xmpp:mix:core:0'>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:messages'/>
|
||||||
|
</update-subscription>
|
||||||
|
</iq>
|
||||||
|
|
||||||
|
<iq type='result'
|
||||||
|
from='coven@mix.shakespeare.example'
|
||||||
|
to='hag66@shakespeare.example/UUID-a1j/7533'
|
||||||
|
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||||
|
<update-subscription xmlns='urn:xmpp:mix:core:0' jid='hag66@shakespeare.example'>
|
||||||
|
<subscribe node='urn:xmpp:mix:nodes:messages'/>
|
||||||
|
</update-subscription>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
</section3>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<section3 topic='Leaving a Channel' anchor='usecase-user-leaving'>
|
||||||
|
<p>Users generally remain in a channel for an extended period of time. In particular the user remains as a participant the channel when the user goes offline. Note that this is different to &xep0045;, where the client leaves a room when going offline. So, leaving a MIX channel is a permanent action for a user across all clients. In order to leave a channel, a user sends a MIX "leave" command to the channel. The leave command is encoded as a <leave/> child element of <iq/> element. The <leave/> element is qualified by the 'urn:xmpp:mix:core:0' namespace, with the channel specified as a 'channel" attribute. When a user leaves the channel, the user's server will remove the channel from the user's roster. Leave commands are sent indirectly through the user's server, to enable roster removal. Leaving is initiated by a client request, as shown in the following example.</p>
|
||||||
|
|
||||||
|
|
||||||
|
<example caption="Client Requests to Leave a Channel"><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||||
|
to='hag66@shakespeare.example'
|
||||||
|
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||||
|
<leave xmlns='urn:xmpp:mix:core:0'
|
||||||
|
channel='coven@mix.shakespeare.example'/>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The user's server will then generate a matching request to the MIX channel.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<example caption="User's Server sends Leave Request to a Channel"><![CDATA[
|
||||||
|
<iq type='set'
|
||||||
|
from='hag66@shakespeare.example'
|
||||||
|
to='coven@mix.shakespeare.example'
|
||||||
|
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||||
|
<leave xmlns='urn:xmpp:mix:core:0'/>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The MIX channel will then remove the user from the channel, as described below. A response is sent to the user's server.
|
||||||
|
</p>
|
||||||
|
<example caption="Channel Confirms Leave to User's Server"><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='coven@mix.shakespeare.example'
|
||||||
|
to='hag66@shakespeare.example'
|
||||||
|
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||||
|
<leave xmlns='urn:xmpp:mix:core:0'/>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
|
||||||
|
|
||||||
|
<p>
|
||||||
|
After receiving the confirmation that the user has left the MIX channel, the user's server will remove the MIX channel entry from the user's roster. The user's server will then notify the client that requested to leave.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<example caption="User's Server Confirms Leave to Client"><![CDATA[
|
||||||
|
<iq type='result'
|
||||||
|
from='hag66@shakespeare.example'
|
||||||
|
to='hag66@shakespeare.example/UUID-a1j/7533'
|
||||||
|
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||||
|
<leave xmlns='urn:xmpp:mix:core:0'/>
|
||||||
|
</iq>
|
||||||
|
]]></example>
|
||||||
|
<p>When the user leaves the channel, the MIX service is responsible for unsubscribing the user from all nodes in the channel and for removing the user from the participants and presence list. If the user has online presence when the user leaves the channel, the change of presence status caused by removing the user's entry or entries from the presence node will ensure that subscribers to the presence node are correctly updated on presence status.
|
||||||
|
|
||||||
|
|
||||||
|
Deletion from the participants and presence functions as if the item (channel participant) had been deleted using the PubSub retract mechanism with notification set to true. Notification of the deletion is sent to clients subscribed to the participants PubSub nodes, as shown in the example below.
|
||||||
|
</p>
|
||||||
|
<example caption="Reporting when User Leaves a Channel"><![CDATA[
|
||||||
|
<message from='coven@mix.shakespeare.example'
|
||||||
|
to='hecate@shakespeare.example' id='f5pp2toz'>
|
||||||
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
||||||
|
<items xmlns='urn:xmpp:mix:core:0' node='urn:xmpp:mix:nodes:participants'>
|
||||||
|
<item>
|
||||||
|
<retract id='123456#coven@mix.shakespeare.example'/>
|
||||||
|
</item>
|
||||||
|
</items>
|
||||||
|
</event>
|
||||||
|
</message>
|
||||||
|
|
||||||
|
<message from='coven@mix.shakespeare.example'
|
||||||
|
to='other-witch@shakespeare.example' id='bar'>
|
||||||
|
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
||||||
|
<items xmlns='urn:xmpp:mix:core:0' node='urn:xmpp:mix:nodes:presence' >
|
||||||
|
<item>
|
||||||
|
<retract id='123456#coven@mix.shakespeare.example/8765'/>
|
||||||
|
</item>
|
||||||
|
</items>
|
||||||
|
</event>
|
||||||
|
</message>
|
||||||
|
]]></example>
|
||||||
|
|
||||||
|
|
||||||
|
</section3>
|
||||||
|
|
||||||
<section2 topic="Roster Management" anchor="proxy-roster">
|
<section2 topic="Roster Management" anchor="proxy-roster">
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user