查看源代码

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

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

'''XEP-0096: 文件传输'''

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

作者: Thomas Muldowney, Matthew Miller, Ryan Eatmon

版权: © 1999 - 2010 XMPP标准化基金会(XSF). 参见[[XEP-0096#附录C:法律通告|法律通告]].

状态: 草案

类型: 标准跟踪

版本: 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. 在流初始化中，简单的使用示例'''

<source lang="xml">
<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>
</source>

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

<source lang="xml">
<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>
</source>
 
'''例子3. 在流初始化中，完整的使用示例'''    

<source lang="xml">
<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>
</source>
 
'''例子4. 在流初始化结果中，完整的使用示例'''    

<source lang="xml">
<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>
</source>

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

'''例子 5.'''   

<source lang="xml">
<range length='256'/>
</source>

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

'''例子 6.'''

<source lang="xml">
<range offset='128' length='256'/>
</source>

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

'''例子 7.'''   

<source lang="xml">
<range offset='128'/>
</source>

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

'''例子 8.'''   

<source lang="xml">
<range/>
</source>

==IANA事项==

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

==XMPP注册事项==

===流初始化情况===

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

<source lang="xml">
<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>
</source>

===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. 发送文件：结果节点'''

<source lang="xml">
<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>
</source>

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

<source lang="xml">
<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>
</source>

====接收文件====

允许另一个实体接收文件，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. 接收文件：等同的节点'''

<source lang="xml">
<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>
</source>

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

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

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

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

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

<source lang="xml">
<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>
</source>

==XML Schema==

<source lang="xml">
<?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>
</source>

==附录==
===附录A:文档信息===

系列：[http://xmpp.org/extensions/ XEP]

序号：0096

发布者：[http://xmpp.org/xsf/ XMPP标准基金会]

状态：[http://xmpp.org/extensions/xep-0001.html#states-Draft 草案]

类型：[http://www.xmpp.org/extensions/xep-0001.html#types-Standards%20Track 标准跟踪]

版本：1.1

最后更新：2004-04-13

批准机构：[http://xmpp.org/council/ XMPP理事会]

依赖标准：XMPP Core, XEP-0095

替代标准：无

被替代标准：无

缩略名：si-filetransfer

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

原文控制： [http://svn.xmpp.org:18080/browse/XMPP/trunk/extensions/xep-0096.xml HTML] [http://svn.xmpp.org:18080//changelog/~rss/XMPP/trunk/extensions/xep-0096.xml/rss.xml RSS]

本文的其它格式： [http://xmpp.org/extensions/xep-0096.xml XML] [http://xmpp.org/extensions/xep-0096.pdf PDF]

===附录B:作者信息===

'''Thomas Muldowney'''

:Email: [mailto:temas@jabber.org temas@jabber.org]

:JabberID: temas@jabber.org

'''Matthew Miller'''

:Email: [mailto:linuxwolf@outer-planes.net linuxwolf@outer-planes.net]

:JabberID: linuxwolf@outer-planes.net

'''Ryan Eatmon'''

:Email: [mailto:reatmon@jabber.org reatmon@jabber.org]

:JabberID: reatmon@jabber.org

{{Template:XEP附录CDEF}}

===附录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) 

----

结束