查看源代码

[[Category:XMPP扩展]]
[[Category:翻译中]]

'''本文的英文原文来自[http://www.xmpp.org/extensions/xep-0048.html XEP-0048]'''

'''XEP-0048: 书签'''

{|
!摘要:
|本协议定义了一个XML数据格式让XMPP客户端存储多用户聊天室和web页面的书签。聊天室书签功能还包括登录时自动加入房间的功能.
|-
!作者:
|Rachel Blackman, Peter Millard, Peter Saint-Andre
|-
!版权:
|© 1999 - 2011 XMPP标准化基金会(XSF). 参见[[XEP-0048#法律通告|法律通告]].
|-
!状态:
|草案
|-
!类型:
|标准跟踪
|-
!版本:
|1.1
|-
!最后更新日期:
|2007-11-07
|}

-----
注意: 这里定义的协议是XMPP标准化基金会的一个 '''草案标准''' .对本协议的执行是被鼓励的,也适于部署到生产系统,但是在它成为最终标准之前可能还会有一些变动.
-----

==简介==

为了让Jabber客户端易于使用, 需要一个办法把很多服务和资源 (例如会议室和web页面) 的快捷方式存储成为可以在用户的客户端显示的 "书签". 许多Jabber客户端已经同意并实现了一个方法来提供这个服务; 这个非正式的约定在本文中做了记录和扩展. 典型的, 我们引入 <storage/> 元素 (由 'storage:bookmarks' 命名空间限定) 作为一个这类数据的容器. 因为书签数据可能使用任何XML存储机制来存储, 本文推荐了一个特定的用于XMPP的方法.

==数据格式==

一个由 'storage:bookmarks' 命名空间限定的 storage 元素可以包含一组子元素, 每个子元素代表一个书签显示在客户端上. 目前, 只定义了两个子元素: <conference/> 用于 [[XEP-0045|多用户聊天]] 室 [[XEP-0048#附录G:备注|1]] 的书签 ， <url/> 用于web页面的书签.

所有子元素允许有一个 'name' 属性, 它是一个显示给客户端的友好的名字. 如果一个元素缺少 'name' 属性, 客户端应该基于可用的其他数据生成一个适当的替代品.

===conference元素===

常见的用例是多用户聊天室的书签. 一个房间使用 <conference/> 子元素来标记书签. 语法如下.

:'''表1: conference元素的语法'''

:{|border="1" cellspacing="0" 
!元素或属性 !!定义 !!数据类型 !!必要性
|-
|'autojoin' 属性 ||客户端是否应该在登录时自动加入会议室. ||boolean，缺省为false [[XEP-0048#附录G:备注|2]] ||可选
|-
|'jid' 属性 ||聊天室的JabberID. ||	string ||必需
|-
|'name' 属性 ||书签的一个友好名字. ||string ||推荐
|-
|<nick/> 元素 ||用户在这个聊天室中的首选昵称. ||string ||可选
|-
|<password/>元素 ||未加密的字符串，用来加入一个密码保护的房间. 处于安全性的原因, 不推荐使用这个元素. ||string ||不推荐
|}

注意: datatypes(数据类型) 定义于 [http://www.w3.org/TR/xmlschema-2/ XML Schema Part 2] [[XEP-0048#附录G:备注|3]] .

'''示例1. 一个conference元素的例子'''

<source lang="xml">
    <storage xmlns='storage:bookmarks'>
      <conference name='Council of Oberon' 
                  autojoin='true'
                  jid='council@conference.underhill.org'>
        <nick>Puck</nick>
      </conference>
    </storage>
</source>

:这个书签将显示为 'Council of Oberon' 并且, 如果激活它, 将尝试以昵称 'Puck' 加入会议室 'council@conference.underhill.org' .

:注意: 一个书签组可以包含不限数量的会议室.

===url元素===

<url/>元素设计用于标记web页面, 例如, HTTP 或 HTTPS URLs. 语法如下.

:'''表2: url元素的语法'''

:{|border="1" cellspacing="0" 
!属性 !!定义 !!数据类型 !!必要性
|-
|'name' 属性 ||书签的一个友好名字. ||string ||推荐
|-
|'url' 属性 ||web页面的HTTP或HTTPS URL. ||anyURI ||必需
|}

当用户选择一个URL书签, 该客户端应该启动一个适当的浏览器或直接把URL装载到客户端 (如果那个客户端是一个web客户端或包含web浏览功能).

'''示例2. 一个url元素的例子'''

<source lang="xml">
    <storage xmlns='storage:bookmarks'>
      <url name='Complete Works of Shakespeare'
           url='http://the-tech.mit.edu/Shakespeare/'/>
    </storage>
</source>

这个书签将在客户端显示为 'Complete Works of Shakespeare' 并且当它被选中的时候会把用户带到 <http://the-tech.mit.edu/Shakespeare/> .

注意: 一个书签组可以包含任意数量的URLs.

==存储==

建议使用 [[XEP-0060|发行-订阅]] [[XEP-0048#附录G:备注|4]] 来作数据存储, 特别是通过使用位于用户的虚拟"发行-订阅"服务(见 [[XEP-0223|通过发行-订阅实现私有数据的持久存储的最佳实践]] [[XEP-0048#附录G:备注|5]] 和接下来的章节)上的个人数据节点.

注意: 过去, [[XEP-0049|私有XML存储]]  [[XEP-0048#附录G:备注|6]] 是推荐的方法 (参见本协议的归档版本 <http://www.xmpp.org/extensions/attic/xep-0048-1.0.html>). 另外, 也可以使用其他方法, 例如 HTTP 或 WebDAV.

===上传数据===

'''示例3. 客户端上传数据'''

<source lang="xml">
<iq from='juliet@capulet.lit/balcony' type='set' id='pip1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='storage:bookmarks'>
      <item id='current'>
        <storage xmlns='storage:bookmarks'>
          <conference name='The Play&apos;s the Thing' 
                      autojoin='true'
                      jid='theplay@conference.shakespeare.lit'>
            <nick>JC</nick>
          </conference>
        </storage>
      </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>
</source>

'''示例4. 服务器承认成功存储'''

<source lang="xml">
<iq to='juliet@capulet.lit/balcony' type='result' id='pip1'/>
</source>

===接收通知===

存储的数据自动推送到该用户的所有已连接资源.

'''示例5. 发行者接收事件通知'''

<source lang="xml">
<message from='juliet@capulet.lit'
         to='juliet@capulet.lit/balcony'
         type='headline'
         id='rnfoo1'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='storage:bookmarks'>
      <item id='current'>
        <storage xmlns='storage:bookmarks'>
          <conference name='The Play&apos;s the Thing' 
                      autojoin='true'
                      jid='theplay@conference.shakespeare.lit'>
            <nick>JC</nick>
          </conference>
        </storage>
      </item>
    </items>
  </event>
</message>

<message from='juliet@capulet.lit'
         to='juliet@capulet.lit/chamber'
         type='headline'
         id='rnfoo2'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='storage:bookmarks'>
      <item id='current'>
        <storage xmlns='storage:bookmarks'>
        <note jid='hamlet@shakespeare.lit'
              cdate='2004-09-24T15:23:21Z'
              mdate='2004-09-24T15:23:21Z'>Seems to be a good writer</note>
        <note jid='juliet@capulet.com'
              cdate='2004-09-27T17:23:14Z'
              mdate='2004-09-28T12:43:12Z'>Oh my sweetest love ...</note>
        </storage>
      </item>
    </items>
  </event>
</message>
</source>

===接收数据===

==安全事项==
==IANA事项==
==XMPP注册事项==
==XML Schema==
==作者备注==