查看源代码

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

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

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

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

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

'''文档信息'''

系列: [[:Category:XMPP扩展|XEP]]

编号: 0096

发行者: [[XMPP标准基金会]]

状态: 草案

类型: 标准跟踪

版本: 1.1

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

批准机构: [[XMPP理事会]]

依赖于: [[RFC3920|XMPP Core]], XEP-0095

上文: 无

下文: 无

简称: si-filetransfer

名字空间的XML方案: <http://www.xmpp.org/schemas/file-transfer.xsd>

Wiki页: <http://wiki.jabber.org/index.php/File Transfer (XEP-0096)>

'''作者信息'''

'''Thomas Muldowney'''

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

:JabberID: [xmpp:temas@jabber.org temas@jabber.org]

'''Matthew Miller'''

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

:JabberID: [xmpp:linuxwolf@outer-planes.net linuxwolf@outer-planes.net]

'''Ryan Eatmon'''

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

:JabberID: [xmpp:reatmon@jabber.org reatmon@jabber.org]

'''法律通告'''

'''版权'''

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

'''权限'''

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

'''免责声明'''

注意：本协议是提供的“原样”的基础，没有担保或任何形式的条件，明示或暗示，包括，但不限于任何担保或关于名称，非侵权性，适销性或适合作某一特定目的的条件.在任何情况XMPP标准基金会或作者不对此协议承担任何责任索赔，损害赔偿，或其他责任，无论是在一项行动的合同，侵权，或否则，所产生的，运出，或在他涉嫌与规格或执行，部署或以其它方式使用本协议. ##

'''责任限制'''

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

'''知识产权的一致性'''

XMPP扩展协议完全遵守XSF的知识产权策略(可在<http://www.xmpp.org/extensions/ipr-policy.shtml>找到副本或写信给XSF, P.O. Box 1641, Denver, CO 80201 USA). 

'''讨论地点'''

首选的讨论的地方是标准讨论邮件列表: <http://mail.jabber.org/mailman/listinfo/standards>.

勘误表发送到[mailto:editor@xmpp.org editor@xmpp.org]

'''XMPP 相关信息'''

XMPP 是由XSF(XMPP标准化基金会)按互联网标准程序贡献的,和 IETF的RFC 2026兼容的规范,包括 XMPP核心(RFC 3920)和 XMPP IM(RFC 3921).在本文中定义的任何协议,都是在互联网标准程序之外开发的,是扩展XMPP，而不是改变、发展和修改 XMPP本身。

'''一致性术语'''

本文中以下关键词的含义如 RFC 2119 所述: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

==绪论==

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

==备注==

# 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>.
# The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
# The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://www.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>.

==修订历史==

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) 

结束