Move changes to bookmarks2 to actual XEP

This commit is contained in:
Jonas Wielicki 2018-03-28 18:11:34 +02:00
vecāks 0f06172140
revīzija a5d9506e68
2 mainīti faili ar 120 papildinājumiem un 114 dzēšanām

Parādīt failu

@ -83,113 +83,29 @@
<td>string</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>&lt;password/&gt; element</td>
<td>Unencrypted string for the password needed to enter a password-protected room. For security reasons, use of this element is NOT RECOMMENDED.</td>
<td>string</td>
<td>NOT RECOMMENDED</td>
</tr>
</table>
<p>Note: The datatypes are as defined in &w3xmlschema2;.</p>
<example caption='An example of the conference element'><![CDATA[
<conference xmlns=']]>&namespace;<![CDATA['
name='Council of Oberon'
autojoin='true'>
<nick>Puck</nick>
</conference>
<conference xmlns=']]>&namespace;<![CDATA['
name='Council of Oberon'
autojoin='true'>
<nick>Puck</nick>
</conference>
]]></example>
<p>This bookmark would be displayed as 'Council of Oberon' and, if activated, would attempt to join the conference room 'council@conference.underhill.org' with nickname 'Puck'.</p>
<p>Note that a bookmark item MUST contain only one conference room.</p>
<p>Note also that a conference element has no truly mandatory attributes or child elements, though a name SHOULD be given. Thus the following is legal:</p>
<example caption='Minimalist conference element'><![CDATA[
<conference xmlns=']]>&namespace;<![CDATA['/>
<conference xmlns=']]>&namespace;<![CDATA['/>
]]></example>
</section1>
<section1 topic='Examples' anchor='examples'>
<section2 topic='Retrieving all bookmarks' anchor='retrieving-bookmarks'>
<example caption='Client retrieves all bookmarks'><![CDATA[
<iq from='juliet@capulet.lit/balcony' type='get' id='retrieve1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:bookmarks:0'/>
</pubsub>
</iq>
]]></example>
<example caption='Server returns the bookmarks'><![CDATA[
<iq type='result'
to='juliet@capulet.lit/balcony'
id='retrieve1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:bookmarks:0'>
<item id='theplay@conference.shakespeare.lit'>
<conference name='The Play&apos;s the Thing'
autojoin='true'>
<nick>JC</nick>
</conference>
</item>
<item id='orchard@conference.shakespeare.lit'>
<conference name='The Orchard'
autojoin='true'>
<nick>JC</nick>
</conference>
</item>
</items>
</pubsub>
</iq>
]]></example>
</section2>
<section2 topic='Adding a bookmark' anchor='adding-a-bookmark'>
<p>Adding a bookmark means publishing a new item, with the bookmark JID as id, to the '&namespace;' node.</p>
<example caption='Client adds a new bookmark'><![CDATA[
<iq from='juliet@capulet.lit/balcony' type='set' id='pip1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:bookmarks:0'>
<item id='theplay@conference.shakespeare.lit'>
<conference name='The Play&apos;s the Thing'
autojoin='true'>
<nick>JC</nick>
</conference>
</item>
</publish>
<publish-options>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#publish-options</value>
</field>
<field var='pubsub#persist_items'>
<value>true</value>
</field>
<field var='pubsub#access_model'>
<value>whitelist</value>
</field>
</x>
</publish-options>
</pubsub>
</iq>
]]></example>
<example caption='Server acknowledges successful storage'><![CDATA[
<iq to='juliet@capulet.lit/balcony' type='result' id='pip1'/>
]]></example>
</section2>
<section2 topic='Removing a bookmark' anchor='removing-a-bookmark'>
<p>Removing a bookmark means retracting an existing item, identified by the bookmark's JID, form the '&namespace;' node.</p>
<p>This implies that server support for the "delete-items" pubsub feature is REQUIRED.</p>
<example caption='Client removes a new bookmark'><![CDATA[
<iq from='juliet@capulet.lit/balcony' type='set' id='remove-bookmark1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<retract node='urn:xmpp:bookmarks:0'>
<item id='theplay@conference.shakespeare.lit'/>
</retract>
</pubsub>
</iq>
]]></example>
<example caption='Server acknowledges successful retraction'><![CDATA[
<iq to='juliet@capulet.lit/balcony' type='result' id='remove-bookmark1'/>
]]></example>
</section2>
</section1>
<section1 topic="Bookmark Notifications">
<p>When a client is sent an event from the Pubsub service for the '&namespace;' node, it MUST check the 'autojoin' attribute if present, and join the room immediately if the attribute is both present and true.</p>
</section1>
@ -202,9 +118,6 @@
<li>The storage MUST be &xep0223;</li>
</ul>
</section2>
<section2 topic='Storage' anchor='storage'>
<p>&xep0060; is used for data storage, specifically through the use of private, personal pubsub nodes (described in &xep0223;) hosted at the user's virtual pubsub service (see &xep0163;).</p>
</section2>
<section2 topic="Compatibility">
<p>A server MAY choose to unify the bookmarks from both &xep0049; based and the current &xep0048;.</p>
<section3 topic="Publishing via this specification">
@ -225,7 +138,6 @@
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>Security considerations related to object persistence via publish-subscribe are described in <cite>XEP-0060</cite> and <cite>XEP-0223</cite>.</p>
<p>The client needs to make sure that the server actually supports the "http://jabber.org/protocol/pubsub#publish-options" feature, before relying on it. If it's not supported, the client should configure the '&namespace;' node first (see <cite>xep-0060</cite>), before adding any bookmarks.</p>
<p>The password child element of conference is well known to provide only very weak levels of security; storing it in bookmarks lowers this security still further.</p>
</section1>
</xep>

Parādīt failu

@ -33,6 +33,12 @@
<email>jc@opkode.com</email>
<jid>jc@opkode.com</jid>
</author>
<revision>
<version>0.2.0</version>
<date>2018-03-28</date>
<initials>jcb</initials>
<remark>Remove password element, add examples, update security considerations.</remark>
</revision>
<revision>
<version>0.1.0</version>
<date>2018-03-28</date>
@ -89,29 +95,113 @@
<td>string</td>
<td>OPTIONAL</td>
</tr>
<tr>
<td>&lt;password/&gt; element</td>
<td>Unencrypted string for the password needed to enter a password-protected room. For security reasons, use of this element is NOT RECOMMENDED.</td>
<td>string</td>
<td>NOT RECOMMENDED</td>
</tr>
</table>
<p>Note: The datatypes are as defined in &w3xmlschema2;.</p>
<example caption='An example of the conference element'><![CDATA[
<conference xmlns=']]>&namespace;<![CDATA['
name='Council of Oberon'
autojoin='true'>
<nick>Puck</nick>
</conference>
<conference xmlns=']]>&namespace;<![CDATA['
name='Council of Oberon'
autojoin='true'>
<nick>Puck</nick>
</conference>
]]></example>
<p>This bookmark would be displayed as 'Council of Oberon' and, if activated, would attempt to join the conference room 'council@conference.underhill.org' with nickname 'Puck'.</p>
<p>Note that a bookmark item MUST contain only one conference room.</p>
<p>Note also that a conference element has no truly mandatory attributes or child elements, though a name SHOULD be given. Thus the following is legal:</p>
<example caption='Minimalist conference element'><![CDATA[
<conference xmlns=']]>&namespace;<![CDATA['/>
<conference xmlns=']]>&namespace;<![CDATA['/>
]]></example>
</section1>
<section1 topic='Examples' anchor='examples'>
<section2 topic='Retrieving all bookmarks' anchor='retrieving-bookmarks'>
<example caption='Client retrieves all bookmarks'><![CDATA[
<iq from='juliet@capulet.lit/balcony' type='get' id='retrieve1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:bookmarks:0'/>
</pubsub>
</iq>
]]></example>
<example caption='Server returns the bookmarks'><![CDATA[
<iq type='result'
to='juliet@capulet.lit/balcony'
id='retrieve1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:bookmarks:0'>
<item id='theplay@conference.shakespeare.lit'>
<conference name='The Play&apos;s the Thing'
autojoin='true'>
<nick>JC</nick>
</conference>
</item>
<item id='orchard@conference.shakespeare.lit'>
<conference name='The Orchard'
autojoin='true'>
<nick>JC</nick>
</conference>
</item>
</items>
</pubsub>
</iq>
]]></example>
</section2>
<section2 topic='Adding a bookmark' anchor='adding-a-bookmark'>
<p>Adding a bookmark means publishing a new item, with the bookmark JID as id, to the '&namespace;' node.</p>
<example caption='Client adds a new bookmark'><![CDATA[
<iq from='juliet@capulet.lit/balcony' type='set' id='pip1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:bookmarks:0'>
<item id='theplay@conference.shakespeare.lit'>
<conference name='The Play&apos;s the Thing'
autojoin='true'>
<nick>JC</nick>
</conference>
</item>
</publish>
<publish-options>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#publish-options</value>
</field>
<field var='pubsub#persist_items'>
<value>true</value>
</field>
<field var='pubsub#access_model'>
<value>whitelist</value>
</field>
</x>
</publish-options>
</pubsub>
</iq>
]]></example>
<example caption='Server acknowledges successful storage'><![CDATA[
<iq to='juliet@capulet.lit/balcony' type='result' id='pip1'/>
]]></example>
</section2>
<section2 topic='Removing a bookmark' anchor='removing-a-bookmark'>
<p>Removing a bookmark means retracting an existing item, identified by the bookmark's JID, form the '&namespace;' node.</p>
<p>This implies that server support for the "delete-items" pubsub feature is REQUIRED.</p>
<example caption='Client removes a new bookmark'><![CDATA[
<iq from='juliet@capulet.lit/balcony' type='set' id='remove-bookmark1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<retract node='urn:xmpp:bookmarks:0'>
<item id='theplay@conference.shakespeare.lit'/>
</retract>
</pubsub>
</iq>
]]></example>
<example caption='Server acknowledges successful retraction'><![CDATA[
<iq to='juliet@capulet.lit/balcony' type='result' id='remove-bookmark1'/>
]]></example>
</section2>
</section1>
<section1 topic="Bookmark Notifications">
<p>When a client is sent an event from the Pubsub service for the '&namespace;' node, it MUST check the 'autojoin' attribute if present, and join the room immediately if the attribute is both present and true.</p>
</section1>
@ -124,6 +214,9 @@
<li>The storage MUST be &xep0223;</li>
</ul>
</section2>
<section2 topic='Storage' anchor='storage'>
<p>&xep0060; is used for data storage, specifically through the use of private, personal pubsub nodes (described in &xep0223;) hosted at the user's virtual pubsub service (see &xep0163;).</p>
</section2>
<section2 topic="Compatibility">
<p>A server MAY choose to unify the bookmarks from both &xep0049; based and the current &xep0048;.</p>
<section3 topic="Publishing via this specification">
@ -144,6 +237,7 @@
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>The password child element of conference is well known to provide only very weak levels of security; storing it in bookmarks lowers this security still further.</p>
<p>Security considerations related to object persistence via publish-subscribe are described in <cite>XEP-0060</cite> and <cite>XEP-0223</cite>.</p>
<p>The client needs to make sure that the server actually supports the "http://jabber.org/protocol/pubsub#publish-options" feature, before relying on it. If it's not supported, the client should configure the '&namespace;' node first (see <cite>xep-0060</cite>), before adding any bookmarks.</p>
</section1>
</xep>