XEP-0096

来自Jabber/XMPP中文翻译计划

跳转到：导航, 搜索

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

XEP-0096: 文件传输

摘要: 本文定义了一个XMPP流初始化扩展的外壳,用于两个实体之间的文件传输. 该协议提供了一个模块化框架使能交换被传输文件的信息以及参数的协商(例如使用的通道).

作者: Thomas Muldowney, Matthew Miller, Ryan Eatmon

状态: 草案

类型: 标准跟踪

版本: 1.1

最后更新日期: 2004-04-13

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

绪论

在Jabber社区，传统的文件传输的方法是Out-of-Band Data带外传输协议。该协议有一些缺点：

它是不可靠的
当有一方在防火墙后面的话，该协议无效
对要交换的文件有元数据的限制。

本文档定义了一个流启动的流程用于解决带外传输的问题，并提供了一种健壮的、可靠的通过Jabber网络文件传输的算法。

要求

允许无缝文件传输，包括必要的回滚机制。

保证一方或者双方都在防火墙之后时，文件传输还能进行。

定义一个完整的文件传输的元数据，如下：

description
size
name
date
hash

可选的，支持文件传输的范围。

协议

文件传输情形属于 http://jabber.org/protocol/si/profile/file-transfer 命名空间。该情形很简单：由可能的描述可选择的传输范围的子元素组成的根元素组成。

根元素<file>有4个属性。这些属性只有在流初始化的情况下使用：

size - 发送文件的大小，按字节计算

name - 发送者想要发送的文件名

date - 文件的最后修改日期。日期格式使用XMPP Date and Time Profiles指定的格式。

hash - 文件内容的MD5

文件大小和文件名属性必须(MUST)在传输情形中出现，其他属性可以(MAY)出现。

根元素还有2个可能的子元素：<desc> 和 <range>，他们都是可选的(OPTIONAL)。

<desc>是发送者提供的对于文件描述，接收者可以更加明确被发送的是什么。它不能(MUST NOT)在结果中发送。

当提供了<range>元素时，它不应该包含属性。这表示发送者能按照范围发送。当发送流初始化的结果中包含了<range>元素时，是用以下属性：

offset - 指定了位置，按字节计算，开始文件传输的起点。如果没有指定，默认值为0。

length - 指定了从偏移量开始的要接收的字节数。默认值是从偏移量开始到文件末尾的字节数。

<range>元素中的2个元素都是可选的(OPTIONAL)。发送无属性的元素等同于没有<range>元素。当在流初始化的结果中没有<range>元素时，发送者必须(MUST)从偏移量为0处发送完整的文件。更通常的情况是，从偏移量位置开始根据指定长度通过字节流发送。

强制实现的技术

为了能够允许无缝实时进行文件传输以及适当的回滚机制，为了更好的处理这些情况，对于这些情况的具体实现必须(MUST)支持SOCKS5 Bytestreams [4] 和In-Band Bytestreams [5]。相关的命名空间也要包含于"stream-method"的可选值中，如下例子中所示：

此外，具体的实现也可以(MAY)支持其他机制。

例子

例子1. 在流初始化中，简单的使用示例

<iq type='set' id='offer1' to='receiver@jabber.org/resource'>
  <si xmlns='http://jabber.org/protocol/si' 
      id='a0'
      mime-type='text/plain'
      profile='http://jabber.org/protocol/si/profile/file-transfer'>
    <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
          name='test.txt'
          size='1022'/>
    <feature xmlns='http://jabber.org/protocol/feature-neg'>
      <x xmlns='jabber:x:data' type='form'>
        <field var='stream-method' type='list-single'>
          <option><value>http://jabber.org/protocol/bytestreams</value></option>
          <option><value>http://jabber.org/protocol/ibb</value></option>
        </field>
      </x>
    </feature>
  </si>
</iq>

例子2. 在流初始化结果中，简单的使用示例

<iq type='result' to='sender@jabber.org/resource' id='offer1'>
  <si xmlns='http://jabber.org/protocol/si'>
    <feature xmlns='http://jabber.org/protocol/feature-neg'>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='stream-method'>
          <value>http://jabber.org/protocol/bytestreams</value>
        </field>
      </x>
    </feature>
  </si>
</iq>

例子3. 在流初始化中，完整的使用示例

<iq type='set' id='offer1' to='receiver@jabber.org/resource'>
  <si xmlns='http://jabber.org/protocol/si' 
      id='a0'
      mime-type='text/plain'
      profile='http://jabber.org/protocol/si/profile/file-transfer'>
    <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
          name='test.txt'
          size='1022'
          hash='552da749930852c69ae5d2141d3766b1'
          date='1969-07-21T02:56:15Z'>
      <desc>This is a test. If this were a real file...</desc>
    </file>
    <feature xmlns='http://jabber.org/protocol/feature-neg'>
      <x xmlns='jabber:x:data' type='form'>
        <field var='stream-method' type='list-single'>
          <option><value>http://jabber.org/protocol/bytestreams</value></option>
          <option><value>http://jabber.org/protocol/ibb</value></option>
        </field>
      </x>
    </feature>
  </si>
</iq>

例子4. 在流初始化结果中，完整的使用示例

<iq type='result' to='sender@jabber.org/resource' id='offer1'>
  <si xmlns='http://jabber.org/protocol/si'>
    <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'/>
    <feature xmlns='http://jabber.org/protocol/feature-neg'>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='stream-method'>
          <value>http://jabber.org/protocol/bytestreams</value>
        </field>
      </x>
    </feature>
  </si>
</iq>

从文件的起点处接收256个字节

例子 5.

<range length='256'/>

从文件偏移量为128个字节处开始接收256个字节

例子 6.

<range offset='128' length='256'/>

从文件偏移量为128个字节处开始接收剩下的文件

例子 7.

<range offset='128'/>

以下的范围等同于没有发送范围请求，整个文件将被发送。

例子 8.

<range/>

IANA事项

本文不需要与Internet Assigned Numbers Authority (IANA) [6]交互。

XMPP注册事项

流初始化情况

本文档描述的情形包含于由XMPP Registrar维护的流初始化情形注册(参考<http://www.xmpp.org/registrar/si-profiles.html>)。注册请求如下：

<profile>
  <name>http://jabber.org/protocol/si/profile/file-transfer</name>
  <doc>XEP-0096</doc>
  <desc>A profile for file transfer between any two entities.</desc>
</profile>

URI查询类型

XMPP注册维护了XMPP URIs的查询和键-值对应的使用，并且被XMPP URI Query Components所验证(参考<http://www.xmpp.org/registrar/querytypes.html>)。

就如下描述的，文件传输的注册类型是"sendfile"和"recvfile"。注意"sendfile"意味着另一个实体将发送一个文件给控制着IRI/URI的XMPP实体，"recvfile"意味着另一个实体将会从控制着IRI/URI的XMPP实体那里接收文件。

发送文件

为了允许另一个实体发送文件，IRI/URI就遵循如下：

例子9. 发送文件：IRI/URI

xmpp:romeo@montague.net/orchard?sendfile

具体的应用程序应该(SHOULD)提供一个界面，允许用户提供关于要发送的文件的信息(比如，为了选择一个文件，“浏览”用户计算机的文件系统)。结果，应用程序应该(SHOULD)发送一个发布流初始化请求的信息给在IRI/URI封装的XMPP地址。

例子 10. 发送文件：结果节点

<message from='juliet@capulet.com/balcony' to='romeo@montague.net'>
  <sipub xmlns='http://jabber.org/protocol/si-pub'
      id='publish-0123'
      mime-type='text/plain'
      profile='http://jabber.org/protocol/si/profile/file-transfer'>
    <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
          name='missive.txt'
          size='1024'
          date='2005-11-29T11:21Z'/>
  </sipub>
</message>

以下提交注册"sendfile"类型。

<querytype>
  <name>sendfile</name>
  <proto>http://jabber.org/protocol/si/profile/file-transfer</proto>
  <desc>enables initiation of an inbound file transfer to XMPP entity</desc>
  <doc>XEP-0096</doc>
</querytype>

接收文件

允许另一个实体接收文件，IRI/URI如下：

例子11. 接收文件: IRI/URI

xmpp:romeo@montague.net/orchard?recvfile;sid=pub234;mime-type=text%2Fplain;name=reply.txt;size=2048

该IRI/URI等同于以下XML节点：

例子12. 接收文件：等同的节点

<message from='romeo@montague.net' to='juliet@capulet.com/balcony'>
  <sipub xmlns='http://jabber.org/protocol/si-pub'
      id='pub234'
      mime-type='text/plain'
      profile='http://jabber.org/protocol/si/profile/file-transfer'>
    <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
          name='reply.txt'
          size='2048'/>
  </sipub>
</message>

根据XEP-0137，应用程序应该(SHOULD)通过发送如下表单初始化文件传输：

例子13. 接收文件：结果节点

<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard'>
  <start xmlns='http://jabber.org/protocol/si-pub' id='pub234'/>
</iq>

注意：开始流的请求要发送给在XMPP IRI/URI中定义的实体的全JID。因此，IRI/URI应该(SHOULD)包含全JID。如果没有如此，接收者必须(MUST)通过出席信息或者服务发现来查找全JID。如果接收者不能查找到发送者的全JID(比如，在最后一次出现时，通过发送订阅出席请求并从发送者的资源接收到出席信息)，那么它应该(SHOULD)取消文件传输。

以下的提交注册了"recvfile"查询类型。

<querytype>
  <name>recvfile</name>
  <proto>http://jabber.org/protocol/si/profile/file-transfer</proto>
  <desc>enables initiation of an outbound file transfer from XMPP entity</desc>
  <doc>XEP-0096</doc>
  <keys>
    <key>
      <name>mime-type</name>
      <desc>the MIME type of the file being offered</desc>
    </key>
    <key>
      <name>name</name>
      <desc>the name of the file being offered</desc>
    </key>
    <key>
      <name>sid</name>
      <desc>the session ID associated with the file being offered</desc>
    </key>
    <key>
      <name>size</name>
      <desc>the size in bytes of the file being offered</desc>
    </key>
  </keys>
</querytype>

XML Schema

<?xml version='1.0' encoding='UTF-8'?>
 
<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/si/profile/file-transfer'
    xmlns='http://jabber.org/protocol/si/profile/file-transfer'
    elementFormDefault='qualified'>
 
  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0096: http://www.xmpp.org/extensions/xep-0096.html
    </xs:documentation>
  </xs:annotation>
 
  <xs:element name='file'>
    <xs:complexType>
      <xs:sequence minOccurs='0'>
        <xs:element name='desc' type='xs:string'/>
        <xs:element ref='range'/>
      </xs:sequence>
      <xs:attribute name='date' type='xs:dateTime' use='optional'/>
      <xs:attribute name='hash' type='xs:string' use='optional'/>
      <xs:attribute name='name' type='xs:string' use='required'/>
      <xs:attribute name='size' type='xs:integer' use='required'/>
    </xs:complexType>
  </xs:element>
 
  <xs:element name='range'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='length' type='xs:integer' use='optional'/>
          <xs:attribute name='offset' type='xs:integer' use='optional'/>
        </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>

附录

附录A:文档信息

系列：XEP

序号：0096

发布者：XMPP标准基金会

状态：草案

类型：标准跟踪

版本：1.1

最后更新：2004-04-13

批准机构：XMPP理事会

依赖标准：XMPP Core, XEP-0095

替代标准：无

被替代标准：无

缩略名：si-filetransfer

XML架构(Schema): <http://www.xmpp.org/schemas/file-transfer.xsd>

原文控制： HTML RSS

本文的其它格式： XML PDF

附录B:作者信息

Thomas Muldowney

Email: temas@jabber.org

JabberID: temas@jabber.org

Matthew Miller

Email: linuxwolf@outer-planes.net

JabberID: linuxwolf@outer-planes.net

Ryan Eatmon

Email: reatmon@jabber.org

JabberID: reatmon@jabber.org

附录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:备注

XEP-0066: Out of Band Data <http://www.xmpp.org/extensions/xep-0066.html>.
XEP-0095: Stream Initiation <http://www.xmpp.org/extensions/xep-0095.html>.
XEP-0082: XMPP Date and Time Profiles <http://www.xmpp.org/extensions/xep-0082.html>.
XEP-0065: SOCKS5 Bytestreams <http://www.xmpp.org/extensions/xep-0065.html>.
XEP-0047: In-Band Bytestreams <http://www.xmpp.org/extensions/xep-0047.html>.
互联网编号分配机构(IANA) 是用于互联网协议的唯一性参数值分配的核心协调者, 例如号码和URI计划. 更多信息, 见 <http://www.iana.org/>.
XMPP登记员XMPP Registrar 维护着一个保留的协议名字空间以及用于由XMPP标准基金会批准的XMPP扩展协议的上下文参数的注册项的列表. 更多信息, 见 <http://xmpp.org/registrar/>.
XEP-0147: XMPP URI Query Components <http://www.xmpp.org/extensions/xep-0147.html>.
XEP-0137: Publishing Stream Initiation Requests <http://www.xmpp.org/extensions/xep-0137.html>.

附录H:修订历史

注意: 本协议的旧版本可能在 http://xmpp.org/extensions/attic/ 还可用

Version 1.1 (2004-04-13)

More fully defined the XMPP Registrar considerations. (psa)

Version 1.1 (2003-12-30)

Improved explanatory text; fixed several errors in the schema. (psa)

Version 1.0 (2003-10-17)

Per a vote of the Jabber Council, advanced status to Draft. (psa)

Version 0.7 (2003-10-07)

Added IBB as a MUST requirement. (tjm)

Version 0.6 (2003-08-18)

Cleaned up some namespace inconsistencies, added the <desc> element for file descriptions. (tjm)

Version 0.5 (2003-07-15)

Stream ids not needed on return results. Moved s5b, ibb, and url-data to the actual namespaces of the stream protocols. (rwe)

Version 0.4 (2003-06-30)

Fixed various typos and inconsistencies (lw)

Version 0.3 (2003-06-30)

Added XML Schema (lw)

Version 0.2 (2003-06-24)

Clarified many examples, added linuxwolf as an author (again, my bad, should have been there), clarified the allowed streams and how data is sent over it. (tjm)

Version 0.1 (2003-06-10)

Initial version. (tjm)

结束