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

bookmarks2: Add examples of fetching/adding/removing bookmarks

Browse Source
This commit is contained in:
JC Brand 2018-03-18 17:18:32 +00:00
parent 1a7bcc5bfc
commit afc9d3a014
1 changed files with 100 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
inbox/bookmarks2.xml
View File

@ -86,20 +86,110 @@
</table>
<p>Note: The datatypes are as defined in &w3xmlschema2;.</p>
<example caption='An example of the conference element'><![CDATA[
<conference xmlns=']]>&namespace;<![CDATA['
<conference xmlns=']]>&namespace;<![CDATA['
name='Council of Oberon'
autojoin='true'>
<nick>Puck</nick>
</conference>
</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>
@ -112,6 +202,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">
@ -133,5 +226,6 @@
<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>
</section1>
</xep>