moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-21 08:45:04 -05:00
Code Issues Releases Wiki Activity

Clarify Direct PubSub acces to each node type

Browse Source
This commit is contained in:
Steve Kille 2016-12-05 08:55:24 +00:00 committed by Kevin Smith
parent 337e41f925
commit 76df73939f
1 changed files with 44 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
xep-0369.xml
View File

@ -263,22 +263,23 @@
</p>
</section2>
<section2 topic="Standard Nodes" anchor="concepts-nodes">
<p>MIX defines a number standard nodes are as follows (although note that not every channel will necessarily use each node):</p>
<p>MIX defines a number standard nodes are as follows. Note that all nodes are optional and that not every channel will necessarily use each node:</p>
<table caption="Standard MIX Nodes">
<tr><th>Name</th><th>Node</th><th>Description</th></tr>
<tr><td>Messages</td><td>'urn:xmpp:mix:nodes:messages'</td><td>For publishing messages. Each item of this node will contain a message sent to the channel.</td></tr>
<tr><td>Subject</td><td>'urn:xmpp:mix:nodes:subject'</td><td>For publishing the subject of the channels</td></tr>
<tr><td>Participants</td><td>'urn:xmpp:mix:nodes:participants'</td><td>For publishing the list of participants (identified by anonymized bare proxy JID), and identifying the nick. This is a list of users who would receive messages (by subscription to the messages node) and/or would receive presence (by subscription to the presence node).</td></tr>
<tr><td>JID Map</td><td>'urn:xmpp:mix:nodes:jidmap'</td><td>For publishing a list of anonymized bare JIDs from the participants node with a 1:1 mapping to the corresponding real JIDs.</td></tr>
<tr><td>Presence</td><td>'urn:xmpp:mix:nodes:presence'</td><td>For publishing information about the availability status of online participants, which may include multiple clients for a single participant.</td></tr>
<tr><td>Messages</td><td>'urn:xmpp:mix:nodes:messages'</td><td>For distributing messages to the channel. Each item of this node will contain a message sent to the channel.</td></tr>
<tr><td>Participants</td><td>'urn:xmpp:mix:nodes:participants'</td><td>For storing the list of participants and the associated nick. Channel participants are added when they join the channel and removed when they leave </td></tr>
<tr><td>JID Map</td><td>'urn:xmpp:mix:nodes:jidmap'</td><td>For storing a list of anonymized bare JIDs from the participants node with a 1:1 mapping to the corresponding real JIDs.</td></tr>
<tr><td>Presence</td><td>'urn:xmpp:mix:nodes:presence'</td><td>For storing information about the availability status of online participants, which may include multiple clients for a single participant.</td></tr>
<tr><td>Information</td><td>'urn:xmpp:mix:nodes:info'</td><td>For storing general channel information, such as description. </td></tr>
<tr><td>Subject</td><td>'urn:xmpp:mix:nodes:subject'</td><td>For storing and sharing the current subject of a channel</td></tr>
<tr><td>Allowed</td><td>'urn:xmpp:mix:nodes:allowed'</td><td>For storing JIDs that are allowed to be channel participants.</td></tr>
<tr><td>Banned</td><td>'urn:xmpp:mix:nodes:banned'</td><td>For storing JIDs that are not allowed to be channel participants. </td></tr>
<tr><td>Configuration</td><td>'urn:xmpp:mix:nodes:config'</td><td>For storing channel configuration. This information will generally be restricted to the channel owners.</td></tr>
<tr><td>Configuration</td><td>'urn:xmpp:mix:nodes:config'</td><td>For storing channel configuration. </td></tr>
</table>
<p>
All of the standard nodes are optional. A channel providing a service similar to MUC will typically use all of the standard nodes.
MIX provides mechanisms to allow users to conveniently subscribe to a chosen set of nodes and to unsubscribe to all nodes with a single operation.
All of the standard nodes are optional. A channel providing a service similar to MUC will typically use all of the standard nodes, but other channels may use combinations of these nodes.
MIX provides mechanisms to allow users to conveniently subscribe to a chosen set of nodes and to unsubscribe to all nodes with a single operation. Some nodes are accessed and managed with PubSub, whereas other nodes define MIX specific mechanisms for their use.
</p>
<p>
MIX also makes use of two nodes for support of Avatars. These nodes and their use is defined in &xep0084;. These nodes may be created as part of a MIX channel, where it is desired to publish an avatar associated with the channel.
@ -308,27 +309,18 @@
</p>
</section3>
<section3 topic="Messages Node" anchor="messages-node">
<p>Items in this node will contain a message identified by a unique ID. A MIX implementation SHOULD NOT make messages available for retrieval from this node using pubsub. The recommended approach is that zero history is held in the messages node, and that this node is used for publication only. The recommended approach to retrieve message history is MAM. Users subscribe to this node to receive messages.</p>
<p>Items in this node will contain a message identified by a unique ID. A MIX implementation SHOULD NOT make messages available for retrieval from this node using pubsub and MUST NOT allow direct pubsub publishing to this node. Messages are published by sending messages to the channel. Zero history is held in the messages node. Message history is retrieved by use of MAM. Users subscribe to this node to indicate that messages from the channel are to be sent to them.</p>
<p>Private Messages are not stored in the messages node.</p>
</section3>
<section3 topic="Subject Node" anchor="subject-node">
<p>The subject node publishes the current subject of channel. Subject history is stored in MAM. A single item is stored in this node at a time which MUST contain a "text" element and MAY contain additional text elements. Where multiple text elements are provided, each MUST posses an xml:lang attribute that describes the natural language of the subject. The following example shows the format of a item in the subject node.</p>
<example caption="Subject Node">
<![CDATA[<items node='urn:xmpp:mix:nodes:subject'>
<item>
<text xml:lang="en">How to use Toads</text>
<text xml:lang="de">Wie benutzt man Kröten</text>
</item>
</items>]]></example>
<p>
When a user subscribes to the Subject Node, this will cause the channel to send Subject messages to the user through the MIX Proxy. This is done on initial user subscription and on subject change. Clients MAY directly read the channel subject from the Subject Node using PubSub.
</p>
</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 'coven+123456@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 'coven+123456@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>
<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.
This node MAY be subscribed to for jid-visible channels that permit subscription to this node - this will allow users to see changes to the channel participants.
</p>
<p>If the Participants Node is not used, information on channel participants is not shared.</p>
<p>The participants node is optional. If the Participants Node is not used, information on channel participants is not shared. If there is no participants node, the access control value 'participants' MUST NOT be used.</p>
<example caption="Value of Participants Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:participants'>
<item id='coven+123456@mix.shakespeare.example'>
@ -340,8 +332,8 @@
</section3>
<section3 topic="JID Map Node" anchor="jid-map-node">
<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.
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.
<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 channels, only administrators can subscribe. </p>
<example caption="Value of JID Map Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:jidmap'>
@ -358,7 +350,7 @@
</p>
<p>
This node may be subscribed to by users and this subscription MUST use the users bare JID. So presence of online clients is sent to the MIX Proxy for each user subscribed to this node. Presence is always sent using standard presence protocol.
This node may be subscribed to by users and this subscription MUST use the users bare JID. So presence of online clients is sent to the MIX Proxy for each user subscribed to this node. Presence is always sent using standard presence protocol and NOT using pubsub protocol. Clients MUST NOT directly access the presence node using pubsub.
</p>
<example caption="Value of Presence Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:presence'>
@ -374,7 +366,7 @@
<section3 topic="Information Node" anchor="info-node">
<p>The Information node holds information about the channel. The information node contains a single item with the current information. Information node history is held in MAM.
The information node is named by the date/time at which the item was created. Users MAY subscribe to this node to receive information updates. The Information node item may contain the following attributes, each of which is optional:
The information node is named by the date/time at which the item was created. The information node is accessed and managed using standard pubsub. Users MAY subscribe to this node to receive information updates. The Information node item may contain the following attributes, each of which is optional:
</p>
<table caption="Information Node Attributes">
<tr><th>Name</th><th>Description</th><th>Field Type</th><th>Values</th><th>Default</th></tr>
@ -406,9 +398,29 @@
</items>
]]></example>
</section3>
<section3 topic="Subject Node" anchor="subject-node">
<p>The subject node publishes the current subject of channel. Subject history is stored in MAM. A single item is stored in this node at a time which MUST contain a "text" element and MAY contain additional text elements. Where multiple text elements are provided, each MUST posses an xml:lang attribute that describes the natural language of the subject. </p>
<p>
Setting and sharing subject uses a message with subject element, in a manner compatible with &xep0045;. Clients MAY also write or access this node using pubsub. Writes to this node will lead to update of subject by sending messages. Setting the subject is controlled by configuration; in some channels it may be set by all users and in others restricted to administrators.
The following example shows the format of a item in the subject node.
</p>
<example caption="Subject Node">
<![CDATA[<items node='urn:xmpp:mix:nodes:subject'>
<item>
<text xml:lang="en">How to use Toads</text>
<text xml:lang="de">Wie benutzt man Kröten</text>
</item>
</items>]]></example>
<p>
When a user subscribes to the Subject Node, this will cause the channel to send Subject messages to the user through the MIX Proxy. This is done on initial user subscription and on subject change. Clients MAY directly read the channel subject from the Subject Node using PubSub.
</p>
</section3>
<section3 topic="Allowed" anchor="allowed-node">
<p>
This node represents a list of JIDs that are allowed to become participants. If the allowed node is not present, all JIDs are allowed. The allowed list is always considered in conjunction with the banned list, stored in the banned node. Only Administrators and Owners have write permission to the allowed node and are also the only roles that are allows to subscribe to this node. Each item contains a real bare JID. The following example shows how the allowed list can specify single JIDs and domains.
This node represents a list of JIDs that are allowed to become participants. If the allowed node is not present, all JIDs are allowed. This node is accessed and managed using standard pubsub. The allowed list is always considered in conjunction with the banned list, stored in the banned node. Only Administrators and Owners have write permission to the allowed node and are also the only roles that are allows to subscribe to this node. Each item contains a real bare JID. The following example shows how the allowed list can specify single JIDs and domains.
</p>
<example caption="Allowed Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:allowed'>
@ -419,7 +431,7 @@
</section3>
<section3 topic="Banned" anchor="banned-node">
<p>
This node represents a list of JIDs that are explicitly not allowed to become participants. The values in this list take priority over values in the allowed node. Only Administrators and Owners have write permission to the allowed node and are also the only roles that are allows to subscribe to this node. Each item contains a real bare JID.
This node represents a list of JIDs that are explicitly not allowed to become participants. The values in this list take priority over values in the allowed node. This node is accessed and managed using standard pubsub Only Administrators and Owners have write permission to the allowed node and are also the only roles that are allows to subscribe to this node. Each item contains a real bare JID.
</p>
<example caption="Banned Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:banned'>
@ -430,7 +442,7 @@
</section3>
<section3 topic="Configuration Node" anchor="config-node">
<p>
The Configuration node holds the configuration of the channel as a single item, named by the date-time of the last update to the configuration. A single item is stored in the node, with previous configuration history accessed by MAM. Users MAY subscribe to the configuration node to get notification of configuration change. The configuration node is optional for a MIX channel. For example, configuration choices could be fixed and not exposed. A subset of the defined configuration options may be used and additional non-standard configuration options may be added. If configuration options to control functionality of the nature described here are provided, the options defined in this standard MUST be used. The following configuration attributes are defined:
The Configuration node holds the configuration of the channel as a single item, named by the date-time of the last update to the configuration. A single item is stored in the node, with previous configuration history accessed by MAM. Users with read access to the configuration node MAY subscribe to the configuration node to get notification of configuration change. This node is accessed and managed using standard pubsub. The configuration node is optional for a MIX channel. For example, configuration choices could be fixed and not exposed. A subset of the defined configuration options may be used and additional non-standard configuration options may be added. If configuration options to control functionality of the nature described here are provided, the options defined in this standard MUST be used. The following configuration attributes are defined:
</p>
<table caption="Configuration Node Attributes">
<tr><th>Name</th><th>Description</th><th>Field Type</th><th>Values</th><th>Default</th></tr>