mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-21 16:55:07 -05:00
Change sub-element to child element
This commit is contained in:
Steve Kille
parent
ceaf2e2a4a
commit
57d2379701
32
xep-0369.xml
32
xep-0369.xml
@ -500,7 +500,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
</section3>
|
||||
|
||||
<section3 topic="Participants Node" anchor="participants-node">
|
||||
<p>Each channel participant is represented as an item of the 'urn:xmpp:mix:nodes:participants' channel node. Each item is named by the bare proxy JID of the participant. For example '123456#coven@mix.shakespeare.example' might name the node item associated with participant 'hag66@shakespeare.example'. Information is stored in a <participant/> element qualified by the 'urn:xmpp:mix:0' namespace. The nick associated with the user is mandatory and is stored in a <nick/> sub-element of the <participant/> element. The nick for each channel participant MUST be different to the nick of other participants.
|
||||
<p>Each channel participant is represented as an item of the 'urn:xmpp:mix:nodes:participants' channel node. Each item is named by the bare proxy JID of the participant. For example '123456#coven@mix.shakespeare.example' might name the node item associated with participant 'hag66@shakespeare.example'. Information is stored in a <participant/> element qualified by the 'urn:xmpp:mix:0' namespace. The nick associated with the user is mandatory and is stored in a <nick/> child element of the <participant/> element. The nick for each channel participant MUST be different to the nick of other participants.
|
||||
</p>
|
||||
<p>
|
||||
When a user joins a channel, the user's bare JID is added to the participants node by the MIX service. When a user leaves a channel, they are removed from the participants node. The participants node MUST NOT be directly modified using pubsub.
|
||||
@ -523,7 +523,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
|
||||
<p>The JID Map node is used to associate a proxy bare JID to its corresponding real bare JID. The JID Map node MUST have one entry for each entry in the Participants node. This value is added when a user joins the channel and is removed when the user leaves the channel.
|
||||
Each item is identified by proxy bare JID, mapping to the real bare JID. This node is used to give administrator access to real JIDs and participant access to real JIDs in jid-visible channels. This node MUST NOT be modified directly using pubsub.
|
||||
In JID Visible channels, all participants MAY subscribe to this node. In JID Hidden and JID Maybe Visible channels, only administrators can subscribe. The JID Map node is a permanent node with one item per participant. Information is stored in a <participant/> element qualified by the 'urn:xmpp:mix:0' namespace. The real JID is stored in a <jid/> sub-element of the <participant/> element. </p>
|
||||
In JID Visible channels, all participants MAY subscribe to this node. In JID Hidden and JID Maybe Visible channels, only administrators can subscribe. The JID Map node is a permanent node with one item per participant. Information is stored in a <participant/> element qualified by the 'urn:xmpp:mix:0' namespace. The real JID is stored in a <jid/> child element of the <participant/> element. </p>
|
||||
<example caption="Value of JID Map Node"><![CDATA[
|
||||
<items node='urn:xmpp:mix:nodes:jidmap'>
|
||||
<item id='123456#coven@mix.shakespeare.example'>
|
||||
@ -956,7 +956,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
<section1 topic='Use Cases' anchor='usecases'>
|
||||
<section2 topic='Common User Use Cases' anchor='usecases-user'>
|
||||
<section3 topic='Joining a Channel' anchor='usecase-user-join'>
|
||||
<p>A user joins a channel by sending a MIX "join" command. 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 messages, and presence. The <join/> is a sub-element of <iq/> qualified by the 'urn:xmpp:mix:0' namespace. The channel is specified by a 'channel' attribute in the <join/> element. The requested nodes are encoded as <subscribe/> sub-elements of the <join/> element.
|
||||
<p>A user joins a channel by sending a MIX "join" command. 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 messages, and presence. The <join/> is a child element of <iq/> element. The <join/> element is qualified by the 'urn:xmpp:mix: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>
|
||||
@ -1068,7 +1068,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
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/$gt; sub-element of <iq/> qualified by the 'urn:xmpp:mix:0' namespace. The requested notes are encoded as <subscribe/> sub-elements of the <update-subscription/$gt; 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.
|
||||
A user MAY subsequently modify subscription to nodes in a channel by sending a subscription modification request encoded as a <update-subscription/$gt; child element of <iq/> element. The <update-subscription/$gt; element is qualified by the 'urn:xmpp:mix:0' namespace. The requested notes are encoded as <subscribe/> child elements of the <update-subscription/$gt; 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'
|
||||
@ -1180,7 +1180,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
</join>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The client MAY also query the channel in order to find out which user preferences are supported and the options available. This will allow users to set options not specified in the standard, by providing a form template in the result. The request is encoded as a <user-preference/> sub-element of <iq/> qualified by the 'urn:xmpp:mix:0' namespace. The result is encoded as a form sub-element in the <user-preference/> element.</p>
|
||||
<p>The client MAY also query the channel in order to find out which user preferences are supported and the options available. This will allow users to set options not specified in the standard, by providing a form template in the result. The request is encoded as a <user-preference/> child element of <iq/>. <user-preference/> is qualified by the 'urn:xmpp:mix:0' namespace. The result is encoded as a form child element in the <user-preference/> element.</p>
|
||||
<example caption="User Requests and Recieves Preferences Template Form"><![CDATA[
|
||||
<iq type='get'
|
||||
from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||
@ -1265,7 +1265,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
</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/> sub-element of <iq/> element qualified by the 'urn:xmpp:mix: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>
|
||||
<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: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[
|
||||
@ -1355,7 +1355,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
<li>The MIX service generates the nick. In this case it is RECOMMENDED that the assigned nick is a UUID following &rfc4122;.</li>
|
||||
</ol>
|
||||
<p>
|
||||
A user will typically set a nick when joining a channel and MAY update this nick from time to time. The user does this by sending a command to the channel to set the nick. This command is a <setnick/> sub-element of <iq/> element qualified by the 'urn:xmpp:mix:0' namespace. The nick is encoded as a <nick/> sub-element of the <setnick/> element. If the user wishes the channel to assign a nick (or knows that the channel will assign a nick) the nick field can be left blank, so that the user can see what is assigned in the result.
|
||||
A user will typically set a nick when joining a channel and MAY update this nick from time to time. The user does this by sending a command to the channel to set the nick. This command is a <setnick/> child element of <iq/> element. The <setnick/> element is qualified by the 'urn:xmpp:mix:0' namespace. The nick is encoded as a <nick/> child element of the <setnick/> element. If the user wishes the channel to assign a nick (or knows that the channel will assign a nick) the nick field can be left blank, so that the user can see what is assigned in the result.
|
||||
</p>
|
||||
<example caption="User sets Nick on Channel"><![CDATA[
|
||||
<iq type='set'
|
||||
@ -1412,7 +1412,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
</p>
|
||||
<p>
|
||||
To register a nick with the MIX service the user sends
|
||||
a register command to the service. This is encoded as a <register/> sub-element of an <iq/> element qualified by the urn:xmpp:mix:0' namespace. The nick is encoded in a <nick/> sub-element of the <register/> element. </p>
|
||||
a register command to the service. This is encoded as a <register/> child element of an <iq/> element. The <register/> element is qualified by the urn:xmpp:mix:0' namespace. The nick is encoded in a <nick/> child element of the <register/> element. </p>
|
||||
<example caption="User Registers with Service"><![CDATA[
|
||||
<iq type='set'
|
||||
from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||
@ -1658,7 +1658,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
</message>
|
||||
]]></example>
|
||||
<p>
|
||||
The MIX channel then adds information to the message using a <mix> element qualified by the 'urn:xmpp:mix:0' namespace. This element contains two sub-elements:
|
||||
The MIX channel then adds information to the message using a <mix> element qualified by the 'urn:xmpp:mix:0' namespace. This element contains two child elements:
|
||||
</p>
|
||||
<ol>
|
||||
<li>A <nick> element that contains the Nick of the message sender, taken from the Participants Node.</li>
|
||||
@ -1769,7 +1769,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
<li>The invitee MAY send a response to the inviter, indicating if the invitation was accepted or declined.</li>
|
||||
</ol>
|
||||
<p>
|
||||
The first step is for the inviter to request an invitation from the channel. The invitation contains inviter, invitee and a token. The channel will evaluate if the inviter has rights to issue the invitation. This will be because the inviter is a channel administrator or if the inviter is a channel participant and the channel allows invitation by participants. If the inviter has rights to make the invitation, the channel will return a token. The token is a string that the channel can subsequently use to validate an invitation. The format of the token is not specified in this standard. The encoded token MAY reflect a validity time. The invitation request is encoded as an <invite/> sub-element of an <iq/> element qualified by the 'urn:xmpp:mix:0' namespace. <invite/> contains an <invitation/> sub-element, which contain <inviter/>, <invitee/>, <channel/> and <token/> sub-elements.
|
||||
The first step is for the inviter to request an invitation from the channel. The invitation contains inviter, invitee and a token. The channel will evaluate if the inviter has rights to issue the invitation. This will be because the inviter is a channel administrator or if the inviter is a channel participant and the channel allows invitation by participants. If the inviter has rights to make the invitation, the channel will return a token. The token is a string that the channel can subsequently use to validate an invitation. The format of the token is not specified in this standard. The encoded token MAY reflect a validity time. The invitation request is encoded as an <invite/> child element of an <iq/> element. The <invite/> element is qualified by the 'urn:xmpp:mix:0' namespace. <invite/> contains an <invitation/> child element, which contain <inviter/>, <invitee/>, <channel/> and <token/> child elements.
|
||||
</p>
|
||||
<example caption='Inviter Requests and Receives Invitation'><![CDATA[
|
||||
<iq from='hag66@shakespeare.lit/UUID-h5z/0253'
|
||||
@ -1812,7 +1812,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
</invitation>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The invitation can now be used by the invitee to join a channel. The <invitation/> sub-element is simply added to the standard channel <join/> element, so that the channel can validate the invitation using the token. If the allowed node is present and the invitee is not matched against any item, the channel MUST add the invitee to the allowed node as part of the join.</p>
|
||||
<p>The invitation can now be used by the invitee to join a channel. The <invitation/> child element is simply added to the standard channel <join/> element, so that the channel can validate the invitation using the token. If the allowed node is present and the invitee is not matched against any item, the channel MUST add the invitee to the allowed node as part of the join.</p>
|
||||
<example caption="User Joins a Channel with an Invitation"><![CDATA[
|
||||
<iq type='set'
|
||||
from='cat@shakespeare.example'
|
||||
@ -1830,7 +1830,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The invitee MAY send an acknowledgement back to the inviter, noting the status of the invitation.
|
||||
This is encoded as an <invitation-ack/> sub-element of <message/> element qualified by the 'urn:xmpp:mix:0' namespace. The <invitation-ack/> has an <invitation/> sub-element that encodes the invitation being acknowledged and a <value/> sub-element to encode the acknowledgement value.
|
||||
This is encoded as an <invitation-ack/> child element of <message/> element. The <invitation-ack/> element is qualified by the 'urn:xmpp:mix:0' namespace. The <invitation-ack/> has an <invitation/> child element that encodes the invitation being acknowledged and a <value/> child element to encode the acknowledgement value.
|
||||
<value/> has the following values:</p>
|
||||
<ul>
|
||||
<li>'Joined': The invitee has joined the channel.</li>
|
||||
@ -1949,7 +1949,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
It is important that messages are all transferred from the MIX channel to the server associated with the each channel participant. Transfer between servers will typically happen quickly and &xep0198; will deal with short connection failures between servers. Longer connection failures could lead to message loss. This would lead to online users (who remain connected to their servers) missing messages, and to messages being missed out of the user archive. This section describes how MIX addresses this.
|
||||
</p>
|
||||
<p>
|
||||
When there is a long term connection failure, the MIX channel will receive an error from the XMPP server indicating that a message failed to transfer to a recipient. When this happens, the MIX channel MUST take responsibility to ensure that the message is retransmitted and delivered. When the MIX channel detects a failure it will make use of an IQ Marker message to determine when the connection to the peer server is working again. Once the channel has received a response to the marker IQ it will retransmit the pending messages. The marker is encoded as a <marker/> sub-element of an <iq/> element qualified by the 'urn:xmpp:mix:0' namespace.
|
||||
When there is a long term connection failure, the MIX channel will receive an error from the XMPP server indicating that a message failed to transfer to a recipient. When this happens, the MIX channel MUST take responsibility to ensure that the message is retransmitted and delivered. When the MIX channel detects a failure it will make use of an IQ Marker message to determine when the connection to the peer server is working again. Once the channel has received a response to the marker IQ it will retransmit the pending messages. The marker is encoded as a <marker/> child element of an <iq/> element. The <marker/> element is qualified by the 'urn:xmpp:mix:0' namespace.
|
||||
</p>
|
||||
<example caption="Channel Sends Marker Message" ><![CDATA[
|
||||
<iq from='coven@mix.shakespeare.example'
|
||||
@ -2027,7 +2027,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
</section3>
|
||||
<section3 topic='Creating a Channel' anchor='usecase-admin-create'>
|
||||
<p>
|
||||
A client creates a channel by sending a simple request to the MIX service. A channel MAY be created with default parameters, as shown in the following example. The result MUST include the name of the channel which MUST match the channel name in the request (if present). The create is encoded as a <create/> sub-element of <iq/> element qualified by the 'urn:xmpp:mix:0' namespace. The <create/> element MUST have a 'channel' attribute to specify the channel name.
|
||||
A client creates a channel by sending a simple request to the MIX service. A channel MAY be created with default parameters, as shown in the following example. The result MUST include the name of the channel which MUST match the channel name in the request (if present). The create is encoded as a <create/> child element of <iq/> element. The <create/> is qualified by the 'urn:xmpp:mix:0' namespace. The <create/> element MUST have a 'channel' attribute to specify the channel name.
|
||||
</p>
|
||||
<example caption="Creating a Channel with Default Parameters" ><![CDATA[
|
||||
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||
@ -2137,7 +2137,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
MIX channels are always explicitly destroyed by an owner of the channel or by a server operator. There is no concept of temporary channel, equivalent to &xep0045; temporary room which is automatically destroyed by the server when the users leave. However, channels MAY be configured with an explicit lifetime, after which the channel MUST be removed by the MIX service. Where a channel is created for ad hoc use, it MAY be desirable to keep the channel for history reference or for re-use by the same set of users. Note that the owner of the channel does not need to have presence registered in the channel in order to destroy it.
|
||||
</p>
|
||||
<p>
|
||||
The destroy operation is encoded as a <destroy/> sub-element of an <iq/> element qualified by the 'urn:xmpp:mix:0' namespace. The <destroy/> element MUST have a 'channel' attribute to specify the channel to be destroyed.
|
||||
The destroy operation is encoded as a <destroy/> child element of an <iq/> element. The <destroy/> element is qualified by the 'urn:xmpp:mix:0' namespace. The <destroy/> element MUST have a 'channel' attribute to specify the channel to be destroyed.
|
||||
A client destroys a channel using a simple set operation, as shown in the following example.
|
||||
</p>
|
||||
<example caption="Client Destroys a Channel" ><![CDATA[
|
||||
@ -2528,7 +2528,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
</section2>
|
||||
|
||||
<section2 topic="MIX Roster Item Capability Sharing" anchor="mix-roster-capability-sharing">
|
||||
<p>It is useful for a MIX client to know which roster members are MIX channels, as this will facilitate convenient presentation of subscribed MIX channels to the user. A MIX client MAY request that the server return this additional information. The server MUST return the additional information. The request is made by extending the standard roster get request by adding a sub-element <mix-info-request/> to the <query/> element qualified by the ‘urn:xmpp:mix:0' namespace.</p>
|
||||
<p>It is useful for a MIX client to know which roster members are MIX channels, as this will facilitate convenient presentation of subscribed MIX channels to the user. A MIX client MAY request that the server return this additional information. The server MUST return the additional information. The request is made by extending the standard roster get request by adding a child element <mix-info-request/> to the <query/> element. The <mix-info-request/> is qualified by the ‘urn:xmpp:mix:0' namespace.</p>
|
||||
<example caption="Roster Get Requesting MIX Information"><![CDATA[
|
||||
<iq from='juliet@example.com/balcony'
|
||||
id='bv1bs71f'
|
||||
|
||||
Loading…
Reference in New Issue
Block a user