From ac1582ecc66be0ef250f5d92b115bcd97ffb4c14 Mon Sep 17 00:00:00 2001 From: Lance Stout Date: Mon, 30 Jan 2017 11:06:57 -0800 Subject: [PATCH] XEP-0234 Update to new version of XEP-0300 --- xep-0234.xml | 108 ++++++++++++++++++++++++++++----------------------- 1 file changed, 60 insertions(+), 48 deletions(-) diff --git a/xep-0234.xml b/xep-0234.xml index a4b39df5..5119f2e8 100644 --- a/xep-0234.xml +++ b/xep-0234.xml @@ -24,6 +24,18 @@ NOT_YET_ASSIGNED &stpeter; &lance; + + 0.18.0 + 2017-01-30 + ls + +
    +
  • Update dependency on XEP-0300 to require the 'urn:xmpp:hashes:2' namespace that mandates base64 encoding.
    • +
  • Clarify that a <range/> element with a limit or offset value in a 'session-accept' should be honored by the file sender.
    • +
  • Namespace version bumped to ':5'.
    • +
+ + 0.17.2 2016-07-15 @@ -300,16 +312,16 @@

A Jingle File Transfer session is described by a content type that contains one application format and one transport method. Each &CONTENT; element defines the details of a single file transfer. A Jingle negotiation MAY result in the establishment of multiple file transfers by including multiple &CONTENT; elements.

-

The application format consists of a file description contained within a &DESCRIPTION; element qualified by the "urn:xmpp:jingle:apps:file-transfer:4" namespace &VNOTE;. The file description is a <file/> element specifying metadata such as the name of the file, media type, etc., as illustrated in the following example.

+

The application format consists of a file description contained within a &DESCRIPTION; element qualified by the "urn:xmpp:jingle:apps:file-transfer:5" namespace &VNOTE;. The file description is a <file/> element specifying metadata such as the name of the file, media type, etc., as illustrated in the following example.

+ text/plain test.txt 2015-07-26T21:46:00 6144 - 552da749930852c69ae5d2141d3766b1 + w0mcJylzCn+AfvuGdqkty2+KP48= ]]>

The &DESCRIPTION; element is intended to be a child of a Jingle &CONTENT; element as specified in XEP-0166.

@@ -332,7 +344,7 @@ hash - A hash of the file content, using the <hash/> element defined in &xep0300; and qualifed by the 'urn:xmpp:hashes:1' namespace. Multiple hashes MAY be included for hash agility. + A hash of the file content, using the <hash/> element defined in &xep0300; and qualifed by the 'urn:xmpp:hashes:2' namespace. Multiple hashes MAY be included for hash agility. REQUIRED when offering a file, otherwise OPTIONAL @@ -404,7 +416,7 @@ Initiator Responder

To start a File Offer, the initiator sends a Jingle session-initiation request to a potential responder. The request specifies three things:

  1. A content 'senders' attribute with the value of 'initiator' to indicate this is a File Offer.
    2. -
  2. An application type of "urn:xmpp:jingle:apps:file-transfer:4". In particular, the <description/> element contains a <file/> elements describing the file to be sent.
    3. +
  3. An application type of "urn:xmpp:jingle:apps:file-transfer:5". In particular, the <description/> element contains a <file/> elements describing the file to be sent.
  4. An appropriate transport method.

In this example, the initiator is <romeo@montague.example>, the responder is <juliet@capulet.example>, the application type is a File Offer, and the transport method is jingle-s5b (XEP-0260).

@@ -420,7 +432,7 @@ Initiator Responder initiator='romeo@montague.example/dr4hcr0st3lup4c' sid='851ba2'> - + 1969-07-21T02:56:15Z This is a test. If this were a real file... @@ -428,8 +440,8 @@ Initiator Responder test.txt 6144 - 552da749930852c69ae5d2141d3766b1 + w0mcJylzCn+AfvuGdqkty2+KP48= ]]> -

The initiator then attempts to initiate a SOCKS5 Bytestream with the responder as described in XEP-0260 and XEP-0065. In the meantime, the responder returns a Jingle session-accept. In the session-accept message, the <file/> element MAY contain a <range/> element to indicate that the receiver also supports ranged transfers as described below under Ranged Transfers.

+

The initiator then attempts to initiate a SOCKS5 Bytestream with the responder as described in XEP-0260 and XEP-0065. In the meantime, the responder returns a Jingle session-accept. In the session-accept message, the <file/> element MAY contain a <range/> element to indicate that the receiver also supports ranged transfers as described below under Ranged Transfers. If the responder includes a <range /> element with a limit or offset, the File Sender SHOULD respect the provided range settings.

- + 1969-07-21T02:56:15Z This is a test. If this were a real file... @@ -478,8 +490,8 @@ Initiator Responder test.txt 6144 - 552da749930852c69ae5d2141d3766b1 + w0mcJylzCn+AfvuGdqkty2+KP48= -

If the File Sender has advertised the existence of a file that it hosts, such as by &xep0358;, or if a previous file transfer attempt has failed and the File Receiver would like to initiate another attempt, the File Receiver can "pull" the file from the File Sender. This is done by sending a Jingle session-initiate to the File Sender which includes a <content/> with the 'senders' attribute set to the opposite Jingle session role of the party requesting the file (see Use of Jingle Content Senders) and a <description/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:4' namespace and which includes a <file/> element with enough information included to form a "file selector" (see Section 5 of &rfc5547;) to identify the requested file.

+

If the File Sender has advertised the existence of a file that it hosts, such as by &xep0358;, or if a previous file transfer attempt has failed and the File Receiver would like to initiate another attempt, the File Receiver can "pull" the file from the File Sender. This is done by sending a Jingle session-initiate to the File Sender which includes a <content/> with the 'senders' attribute set to the opposite Jingle session role of the party requesting the file (see Use of Jingle Content Senders) and a <description/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:5' namespace and which includes a <file/> element with enough information included to form a "file selector" (see Section 5 of &rfc5547;) to identify the requested file.

- + - 552da749930852c69ae5d2141d3766b1 + w0mcJylzCn+AfvuGdqkty2+KP48= - + second-file.txt text/plain 6144 - 552da749930852c69ae5d2141d3766b1 + w0mcJylzCn+AfvuGdqkty2+KP48= - + - 552da749930852c69ae5d2141d3766b1 + w0mcJylzCn+AfvuGdqkty2+KP48= "]]> a=file-range:-<(offset + length) | *>]]>

As a full example, given the following Jingle File Transfer content description:

+ text/plain test.txt 2015-07-26T21:46:00 6144 - 552da749930852c69ae5d2141d3766b1 + w0mcJylzCn+AfvuGdqkty2+KP48= ]]> @@ -745,7 +757,7 @@ a=file-range:1024-*]]> -

Once a file has been successfully received, the recipient MAY send a Jingle session-info message indicating receipt of the complete file, which consists of a <received/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:4' namespace. The <received/> element SHOULD contain 'creator' and 'name' attributes sufficient to identify the content that was received.

+

Once a file has been successfully received, the recipient MAY send a Jingle session-info message indicating receipt of the complete file, which consists of a <received/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:5' namespace. The <received/> element SHOULD contain 'creator' and 'name' attributes sufficient to identify the content that was received.

- @@ -764,7 +776,7 @@ a=file-range:1024-*]]>

At any time during the lifetime of the file transfer session, the File Sender can communicate the checksum of the file to the File Receiver.

This can be done in the session-initiate message if the File Sender already knows the checksum, as shown above in Example 3.

-

After the session-initiate message, this can also be done by sending a session-info message containing a <checksum/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:4' namespace. The <checksum/> element SHOULD contain 'creator' and 'name' attributes sufficient to identitfy the content the checksum belongs to. Additionally, the <checksum/> element MUST contain a <file/> element which MUST contain at least one <hash/> element qualified by the 'urn:xmpp:hashes:1' namespace. Each <hash/> element contains a checksum of the file data produced in accordance with the hashing function specified by the 'algo' attribute, which MUST be one of the functions listed in the &ianahashes;.

+

After the session-initiate message, this can also be done by sending a session-info message containing a <checksum/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:5' namespace. The <checksum/> element SHOULD contain 'creator' and 'name' attributes sufficient to identitfy the content the checksum belongs to. Additionally, the <checksum/> element MUST contain a <file/> element which MUST contain at least one <hash/> element qualified by the 'urn:xmpp:hashes:2' namespace. Each <hash/> element contains a checksum of the file data produced in accordance with the hashing function specified by the 'algo' attribute, which MUST be one of the functions listed in the &ianahashes;.

- - 552da749930852c69ae5d2141d3766b1 + w0mcJylzCn+AfvuGdqkty2+KP48= @@ -792,13 +804,13 @@ a=file-range:1024-*]]> - - 4df403604e746f15062ffdbc29367886 + kHp5RSzW/h7Gm1etSf90Mr5PC/k= @@ -815,7 +827,7 @@ a=file-range:1024-*]]> initiator='romeo@montague.example/dr4hcr0st3lup4c' sid='851ba2'> - + 1969-07-21T02:56:15Z This is a test. If this were a real file... @@ -823,7 +835,7 @@ a=file-range:1024-*]]> test.txt 6144 - +

An application MAY present transport methods in any order, except that the Jingle In-Band Bytestreams Transport Method MUST be the lowest preference.

 -

Support for Jingle file transfer can be determined through discovery of the 'urn:xmpp:jingle:apps:file-transfer:4' namespace &VNOTE;, via either service discovery (XEP-0030) or entity capabilities (XEP-0115). If the initiator knows that the responder supports Jingle file transfer, it SHOULD first attempt negotiation using Jingle rather than Stream Initiation.

+

Support for Jingle file transfer can be determined through discovery of the 'urn:xmpp:jingle:apps:file-transfer:5' namespace &VNOTE;, via either service discovery (XEP-0030) or entity capabilities (XEP-0115). If the initiator knows that the responder supports Jingle file transfer, it SHOULD first attempt negotiation using Jingle rather than Stream Initiation.

 -

To advertise its support for the Jingle File Transfer, when replying to service discovery information ("disco#info") requests an entity MUST return URNs for any version of this protocol that the entity supports -- e.g., "urn:xmpp:jingle:apps:file-transfer:4" for this version &VNOTE;.

+

To advertise its support for the Jingle File Transfer, when replying to service discovery information ("disco#info") requests an entity MUST return URNs for any version of this protocol that the entity supports -- e.g., "urn:xmpp:jingle:apps:file-transfer:5" for this version &VNOTE;.

type='result'> - + @@ -947,7 +959,7 @@ a=file-range:1024-*]]>

This specification defines the following XML namespace:

    -
  • urn:xmpp:jingle:apps:file-transfer:4
    • +
  • urn:xmpp:jingle:apps:file-transfer:5

Upon advancement of this specification from a status of Experimental to a status of Draft, the ®ISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.

 @@ -968,17 +980,17 @@ a=file-range:1024-*]]> - + - + @@ -1006,7 +1018,7 @@ a=file-range:1024-*]]> - + @@ -1018,7 +1030,7 @@ a=file-range:1024-*]]> - + @@ -1032,7 +1044,7 @@ a=file-range:1024-*]]>