XEP-0048

来自Jabber/XMPP中文翻译计划

（版本间的差异）

2011年11月30日 (三) 02:57的版本

本文的英文原文来自XEP-0048

XEP-0048: 书签

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

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

简介

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

数据格式

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

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

conference元素

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

表1: conference元素的语法

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

注意: datatypes(数据类型) 定义于 XML Schema Part 2 3 .

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

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

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

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

url元素

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

表2: url元素的语法

属性	定义	数据类型	必要性
'name' 属性	书签的一个友好名字.	string	推荐
'url' 属性	web页面的HTTP或HTTPS URL.	anyURI	必需

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

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

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

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

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

存储

建议使用发行-订阅 4 来作数据存储, 特别是通过使用位于用户的虚拟"发行-订阅"服务(见通过发行-订阅实现私有数据的持久存储的最佳实践 5 和接下来的章节)上的个人数据节点.

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

上传数据

示例3. 客户端上传数据

<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>

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

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

接收通知

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

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

<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>

接收数据

为了在不需要接收通知的情况下接收存储的数据 (比如, 初始化登录的时候), 用户的客户端发送一个 XEP-0060 定义的接收-条目请求.

示例6. 客户端请求所有条目

<iq from='juliet@capulet.lit/randomID' type='get' id='retrieve1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <items node='storage:bookmarks'/>
  </pubsub>
</iq>

示例7. 服务器返回所有条目

<iq type='result'
    to='juliet@capulet.lit/randomID'
    id='retrieve1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <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>
  </pubsub>
</iq>

安全事项

和发行-订阅的对象持久性相关的安全事项参见 XEP-0060 和 XEP-0223 .

不建议使用 <conference/> 元素的 <password/> 子元素, 因为密码可能被第三方截取到, 例如一个窃听者 (如果没有使用频道加密) 或一个服务器管理员. 无论如何, 这个元素还是可以在安全环境下使用的 (例如, 通讯不会使用未加密频道的地方以及管理员是可信任的情况下). 客户端缺省不应该存储密码并且必须允许用户禁止任何密码存储功能.

IANA事项

本文档不需要和IANA 7交互。

XMPP注册事项

不需要 XMPP Registrar 8 , 因为 'storage:bookmarks' 命名空间已经包含在协议命名空间注册项中 (见 <http://xmpp.org/registrar/namespaces.html>).

XML Schema

<?xml version='1.0' encoding='UTF-8'?>
 
<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='storage:bookmarks'
    xmlns='storage:bookmarks'
    elementFormDefault='qualified'>
 
  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0048: http://www.xmpp.org/extensions/xep-0048.html
    </xs:documentation>
  </xs:annotation>
 
  <xs:element name='storage'>
    <xs:complexType>
      <xs:choice>
        <xs:element ref='conference'/>
        <xs:element ref='url'/>
      </xs:choice>
    </xs:complexType>
  </xs:element>
 
  <xs:element name='conference'>
    <xs:complexType>
      <xs:sequence>
        <xs:element name='nick' type='xs:string' minOccurs='0'/>
        <xs:element name='password' type='xs:string' minOccurs='0'/>
      </xs:sequence>
      <xs:attribute name='autojoin' type='xs:boolean' use='optional' default='false'/>
      <xs:attribute name='jid' type='xs:string' use='required'/>
      <xs:attribute name='name' type='xs:string' use='required'/>
    </xs:complexType>
  </xs:element>
 
  <xs:element name='url'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='name' type='xs:string' use='required'/>
          <xs:attribute name='url' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>
 
  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>
 
</xs:schema>

作者备注

Peter Millard, 本协议0.1版到1.0版的共同作者, 于2006年4月26日不幸辞世.

附录

附录A:文档信息

Source Control: HTML This document in other formats: XML PDF

系列：XEP

序号：0048

发布者：XMPP标准基金会

状态：草案

类型：标准跟踪

版本：1.1

最后更新时间：2007-11-07

批准机构：XMPP理事会

依赖标准：XMPP Core, XEP-0060, XEP-0223

替代标准：无

被替代标准：无

缩略名：bookmarks

Schema: <http://www.xmpp.org/schemas/bookmarks.xsd>

原文控制： HTML

本文的其它格式： XML PDF

附录B:作者信息

Rachel Blackman

Email: rcb@ceruleanstudios.com

JabberID: sparks@jabber.org

Peter Millard

见 XEP-0048#作者备注

Peter Saint-Andre

Email: stpeter@jabber.org

JabberID: stpeter@jabber.org

URI: <https://stpeter.im/>

附录C:法律通告

版权

XMPP扩展协议的版权(1999-2008)归XMPP标准化基金会(XSF)所有.

权限

特此授权,费用全免,对任何获得本协议副本的人,对使用本协议没有限制,包括不限制在软件程序中实现本协议,不限制在网络服务中布署本协议,不限制拷贝,修改,合并,发行,翻译,分发,转授,或销售本协议的副本,被允许使用本协议做了以上工作的人士,应接受前述的版权声明和本许可通知并且必须包含在所有的副本或实质性部分的规格中.除非单独的许可，被重新分发的修改工作，不得含有关于作者，标题，编号，或出版者的规格的误导性资料，并不得宣称修改工作是由本文的作者，作者所属的任何组织或项目，或XMPP标准基金会签注。

免责声明'

## 特别注意：本协议是提供的“原样”的基础，没有担保或任何形式的条件，明示或暗示，包括，但不限于任何担保或关于名称，非侵权性，适销性或适合作某一特定目的的条件. ##

责任限制

在任何情况下以及没有任何法律规定时，不论是侵权行为（包括疏忽），合同或其它方面，除非根据适用法律的要求（如蓄意和有严重疏忽行为）或以书面形式同意，XMPP标准基金会或任何作者不对本协议所造成的损失承担责任，包括任何直接，间接，特殊，偶发，或任何从本协议出，入，连接的字符产生的或实现，布署或其他对本协议的使用导致的相应的损害赔偿（包括但不限于善意的损失，停止作业，电脑失灵或故障，或任何和所有其他商业损害或损失），即使XMPP标准基金会或作者已被告知此类损害的可能性。

知识产权的一致性

XMPP扩展协议完全遵守XSF的知识产权策略(可在<http://www.xmpp.org/extensions/ipr-policy.shtml>找到副本或写信给XMPP标准基金会, 1899 Wynkoop Street, Suite 600, Denver, CO 80202 USA).

附录D:和XMPP的关系

可扩展的消息和出席信息协议 (XMPP) 定义于 XMPP Core (RFC 3920) 和 XMPP IM (RFC 3921) 规范里，由 XMPP标准基金会贡献到由依据RFC 2026成立的互联网工程人物组管理的互联网标准流程 Internet Standards Process. 本文定义的任何协议已在互联网标准流程之外开发，并且被理解为 XMPP 的扩展而不是一个XMPP本身的演化, 开发, 或修改.

附录E:讨论地点

主要的XMPP扩展协议讨论地点是 <standards@xmpp.org> 讨论列表.

在 xmpp.org 的其它讨论列表中的讨论可能也有合适的; 所有的列表见 <http://xmpp.org/about/discuss.shtml> .

勘误表可以发送邮件到 <editor@xmpp.org>.

附录F:需求一致性

以下用于本文的需求关键字的解释见于 RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

附录G:备注

附录H:修订历史

@@ 第376行： / 第376行： @@
 {{Template:XEP附录CDEF}}
-===附录C:法律通告===
-===附录D:和XMPP的关系===
-===附录E:讨论地点===
-===附录F:需求一致性===
 ===附录G:备注===
 ===附录H:修订历史===