From c585bc0da6feb86e15147a5c80a3d449bfba6387 Mon Sep 17 00:00:00 2001 From: stpeter Date: Wed, 5 Jan 2011 11:54:19 -0700 Subject: [PATCH] 0.12 --- xep-0234.xml | 124 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 121 insertions(+), 3 deletions(-) diff --git a/xep-0234.xml b/xep-0234.xml index 0a9f884d..0dfa557b 100644 --- a/xep-0234.xml +++ b/xep-0234.xml @@ -24,6 +24,12 @@ NOT_YET_ASSIGNED &stpeter; + + 0.12 + 2011-01-05 + psa +

Clarified usage of Jingle actions as well as several ambiguous points in the text, including use of the range feature from XEP-0096.

 + 0.11 2010-02-19 @@ -152,6 +158,7 @@
  • An application type of "urn:xmpp:jingle:apps:file-transfer:1". In particular, the <description/> element contains an <offer/> or <request/> element that in turn contains a <file/> element qualified by the existing 'http://jabber.org/protocol/si/profile/file-transfer' namespace from XEP-0096.
  • An appropriate transport method. So far the suggested methods are jingle-s5b (XEP-0260) and, as a fallback, jingle-ibb (XEP-0261).
    • +

    Note: All attributes of the <file/> element are defined in XEP-0096, not in this specification.

    In this example, the initiator is <romeo@montague.lit>, the responder is <juliet@capulet.lit>, the application type is a file offer, and the transport method is jingle-s5b.

    The flow is as follows.

    This is a test. If this were a real file... + @@ -213,7 +221,8 @@ Initiator Responder ]]> -

    Note: Computing the hash of the file before sending it can slow down the process of file transfer, since the sending application needs to process the file twice. The sender might prefer to send the hash after the file transfer has begun, using a transport-info message as described under Communicating the Hash.

    +

    Note: Inclusion of the <range/> child of the <file/> element indicates that the initiatior supports ranged transfers as described below under Ranged Transfers.

    +

    Note: Computing the hash of the file before sending it can slow down the process of file transfer, since the sending application needs to process the file twice. The sender might prefer to send the hash after the file transfer has begun, using a transport-info message as described under Communicating the Hash.

    The responder immediately acknowledges receipt of the Jingle session-initiate.

    This is a test. If this were a real file... + @@ -251,6 +261,7 @@ Initiator Responder ]]> +

    Note: Inclusion of the <range/> child of the <file/> element indicates that the receiver also supports ranged transfers as described below under Ranged Transfers.

    The initiator acknowledges the Jingle session-accept.

    -

    At any time, the hosting entity can communicate the hash of the file to the receiving entity. This is done by sending a session-info message containing a <hash/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:info:1' namespace.

    +

    At any time during the lifetime of the file transfer session, the hosting entity can communicate the hash of the file to the receiving entity. This is done by sending a session-info message containing a <hash/> element qualified by the 'urn:xmpp:jingle:apps:file-transfer:info:1' namespace. The XML character data of this <hash/> element has the same meaning as the 'hash' attribute of the <file/> element qualified by the 'http://jabber.org/protocol/si/profile/file-transfer' namespace from XEP-0096; that is, it is a checksum of the file contents produced in accordance with the hashing function specified by the 'algo' attribute, which MUST be one of the functions listed in the &ianahashes;. For historical reasons and for backward-compatibility with XEP-0096, the 'algo' attribute defaults to a value of "md5".

    Note: If the requesting entity knows the hash of the file, then it can include only that metadata in its request. If not, the requesting entity needs to include enough metadata to uniquely identify the file, such as the date, name, and size. For similar considerations, see &rfc5547;.

     + +

    As in XEP-0096, a transfer can include only part of a file (e.g., to restart delivery of a truncated transfer session at a point other than the start of the file). This is done using the <range/> element from XEP-0096. The usage is illustrated in the following examples.

    +

    Let us imagine that the parties negotiate a file transfer session using, say, In-Band Bytestreams. During the transfer, the recipient goes offline unexpectedly and IBB stanzas from the sender to the recipient begin to bounce. When the recipient comes back online, the recipient could initiate a new Jingle session (to retrieve the file) and specify that it wants to receive all chunks after byte 270336 (which might be the 66th chunk of size 4096).

    + + + + + + + + + + + + + + + + + ]]> +

    Alternatively, the sender could initiate a new file transfer, indicating that it supports ranged transfers, and in the Jingle session-accept message the receiver could indicate that it wants the transfer to begin at the specified offset.

    +     + + +

    Jingle file transfer uses only a few of the actions defined in XEP-0166. Jingle usage is summarized in the following table.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ActionUse
    content-acceptUnused
    content-addUnused
    content-modifyUnused
    content-rejectUnused
    content-removeUnused
    description-infoUnused
    security-infoUnused
    session-acceptAccepting a file offer or request
    session-infoCommunication of the file hash
    session-initiateInitiating a file offer or request
    session-terminateEnding a file transfer session
    transport-acceptAccepting fallback from S5B to IBB
    transport-infoUnused
    transport-rejectRejecting fallback from S5B to IBB
    transport-replaceFallback from S5B to IBB
    +     +

    All implementations MUST support the Jingle In-Band Bytestreams Transport Method (XEP-0261) as a reliable method of last resort. An implementation SHOULD support other transport methods as well, especially the Jingle SOCKS5 Bytestreams Transport Method (XEP-0260).

    @@ -341,6 +458,7 @@ Initiator Responder     +

    For historical reasons and for backward-compatibility with XEP-0096, the hashing algorithm used in computing the file checksum defaults to MD5. It is RECOMMENDED for implementations to use stronger hashing algorithms.

    In order to secure the data stream, implementations SHOULD use encryption methods appropriate to the transport method being used. For example, end-to-end encryption can be negotiated over either SOCKS5 Bytestreams or In-Band Bytestreams as described in XEP-0260 and XEP-0261.

    Refer to XEP-0047, XEP-0065, XEP-0096, XEP-0260, and XEP-0261 for related security considerations.

     @@ -424,7 +542,7 @@ Initiator Responder -

    Thanks to Marcus Lundblad and Jiří Zárevúcky for their feedback.

    +

    Thanks to Steffen Larsen, Marcus Lundblad, Joe Maissel, Ali Sabil, Matthew Wild, and Jiří Zárevúcky for their feedback.