mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-21 08:45:04 -05:00
Ensure elements specifed in text and qualified by namespace
This commit is contained in:
Steve Kille
parent
da21b29348
commit
91d80e00d8
42
xep-0369.xml
42
xep-0369.xml
@ -46,6 +46,7 @@
|
||||
Roster Update Clarifications;
|
||||
Clarify when messages are delivered to clients;
|
||||
Extend Roster Get to select format;
|
||||
Ensure that text defining attributes and elements reference the namespace;
|
||||
</p></remark>
|
||||
</revision>
|
||||
<revision>
|
||||
@ -499,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'. The nick associated with the user is mandatory and is stored in the item. 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/> sub-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.
|
||||
@ -522,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.</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/> sub-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'>
|
||||
@ -543,7 +544,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
|
||||
<section3 topic="Presence Node" anchor="presence-node">
|
||||
<p>
|
||||
The presence node contains the presence value for clients belonging to participants that choose to publish presence to the channel. A MIX channel MAY require that all participants publish presence. Each item in the presence node is identified by the full proxy JID, and contains the current presence value for that JID. The presence is encoded in the same way as data that would be sent in a presence stanza. The full proxy JID is always used in this node. In MIX it is possible to have a 'presence-less channel' by not using this node. Access Control MAY be set to enforce that for each of the full JIDs in this list, the bare JID MUST be in the participants list.
|
||||
The presence node contains the presence value for clients belonging to participants that choose to publish presence to the channel. A MIX channel MAY require that all participants publish presence. Each item in the presence node is identified by the full proxy JID, and contains the current presence value for that JID. The presence is encoded in the same way as data that would be sent in a presence stanza using a <presence/> element qualified by the 'jabber:client' namespace. The full proxy JID is always used in this node. In MIX it is possible to have a 'presence-less channel' by not using this node. Access Control MAY be set to enforce that for each of the full JIDs in this list, the bare JID MUST be in the participants list.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
@ -955,8 +956,8 @@ 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.
|
||||
This will lead 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>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.
|
||||
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>
|
||||
@ -1067,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, as shown in the following example. 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.
|
||||
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.
|
||||
</p>
|
||||
<example caption="User Modifies Subscription Request"><![CDATA[
|
||||
<iq type='set'
|
||||
@ -1179,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. This query is direct from the client to the MIX channel.</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/> 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>
|
||||
<example caption="User Requests and Recieves Preferences Template Form"><![CDATA[
|
||||
<iq type='get'
|
||||
from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||
@ -1264,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. 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/> 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>
|
||||
|
||||
|
||||
<example caption="Client Requests to Leave a Channel"><![CDATA[
|
||||
@ -1354,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. 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/> 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.
|
||||
</p>
|
||||
<example caption="User sets Nick on Channel"><![CDATA[
|
||||
<iq type='set'
|
||||
@ -1411,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. </p>
|
||||
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>
|
||||
<example caption="User Registers with Service"><![CDATA[
|
||||
<iq type='set'
|
||||
from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||
@ -1657,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. This element contains two 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 sub-elements:
|
||||
</p>
|
||||
<ol>
|
||||
<li>A <nick> element that contains the Nick of the message sender, taken from the Participants Node.</li>
|
||||
@ -1711,7 +1712,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
|
||||
<section3 topic="Retracting a Message" anchor="usecase-retract">
|
||||
<p>
|
||||
A MIX channel MAY support message retraction, where the sender of a messages or an authorized administrator deletes a message. If this is done the original message MAY be replaced by a tombstone. The protocol to request retraction does this by a message with a <retract> element as shown in the following example.
|
||||
A MIX channel MAY support message retraction, where the sender of a messages or an authorized administrator deletes a message. If this is done the original message MAY be replaced by a tombstone. The protocol to request retraction does this by adding to the message a <retract> element qualified by the 'urn:xmpp:mix:0' namespace as shown in the following example.
|
||||
</p>
|
||||
<example caption="User Retracts a Message"><![CDATA[
|
||||
<message from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||
@ -1731,7 +1732,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
</p>
|
||||
<p>
|
||||
The second approach is to leave a tombstone, which if taken MUST be done in the following manner. This is appropriate where it is desired to leave a record of the message that was redacted.
|
||||
With this approach, the original message <body> is removed and replaced with a tombstone using the <retracted> element that shows the JID of user performing the retraction and the time of the retraction.
|
||||
With this approach, the original message <body> is removed and replaced with a tombstone using the <retracted> element qualified by the 'urn:xmpp:mix:0' namespace that shows the JID of user performing the retraction and the time of the retraction.
|
||||
</p>
|
||||
<example caption="Retracted message tombstone in a MAM result"><![CDATA[
|
||||
<message id='aeb213' to='juliet@capulet.lit/UUID-e3r/9264'>
|
||||
@ -1768,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 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.
|
||||
</p>
|
||||
<example caption='Inviter Requests and Receives Invitation'><![CDATA[
|
||||
<iq from='hag66@shakespeare.lit/UUID-h5z/0253'
|
||||
@ -1796,7 +1797,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>
|
||||
The inviter can now send the invitee a message containing the invitation, as shown in the following example.
|
||||
The inviter can now send the invitee a message containing the invitation within the <message/> element, as shown in the following example.
|
||||
</p>
|
||||
<example caption='Inviter sends Invitation to Invitee'><![CDATA[
|
||||
<message from='hag66@shakespeare.lit/UUID-h5z/0253'
|
||||
@ -1811,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 is simply added to the standard channel join, 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/> 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>
|
||||
<example caption="User Joins a Channel with an Invitation"><![CDATA[
|
||||
<iq type='set'
|
||||
from='cat@shakespeare.example'
|
||||
@ -1828,7 +1829,9 @@ This approach enables flexible support of multiple clients for a MIX channel pa
|
||||
</join>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The invitee MAY send an acknowledgement back to the inviter, noting the status of the invitation. Values are:</p>
|
||||
<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.
|
||||
<value/> has the following values:</p>
|
||||
<ul>
|
||||
<li>'Joined': The invitee has joined the channel.</li>
|
||||
<li>'Declined': The invitee is not taking up the invitation.</li>
|
||||
@ -1946,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.
|
||||
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.
|
||||
</p>
|
||||
<example caption="Channel Sends Marker Message" ><![CDATA[
|
||||
<iq from='coven@mix.shakespeare.example'
|
||||
@ -2024,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). Creating and destroying a channel is done direct from a client.
|
||||
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.
|
||||
</p>
|
||||
<example caption="Creating a Channel with Default Parameters" ><![CDATA[
|
||||
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||
@ -2134,6 +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.
|
||||
A client destroys a channel using a simple set operation, as shown in the following example.
|
||||
</p>
|
||||
<example caption="Client Destroys a Channel" ><![CDATA[
|
||||
|
||||
Loading…
Reference in New Issue
Block a user