<remark>At the request of the authors, the status of this document has been changed to Retracted since it has been superseded by XEP-0095 and XEP-0096.</remark>
<p>If a receiver decides to accept an offered file they request it from the sending with an <iq/> type result. The receiver sends back the id of the file being sent, the method they wish to use, and the range they wish to download (if the sender announced support). When range support is being used the receiver MUST specify the length and MAY specify a beginning offset with the acceptance.</p>
<p>By staying in just the realm of negotiating the meta-data to a file, we allow for multiple transport layers, or streams, to be used. Some streams will need to tie the meta-data to the actual data transfer, to help accomodate this the stream may use the <file/> with an action of start and the correct id. The <file/> could be transported in the stream negotiations, or along side it. Although this spec does not mandate any specific methods to new stream authors, it does provide the syntax for the currently existing "iq:oob" system.</p>
<section2topic='"iq:oob" Relation'>
<p>For an "iq:oob" transfer to be related to it's meta-data, a <file/> is transported along side the <query/>. The id used on the <file/> is the id for the meta-data of the actual data that is being sent. The action on the <file/> is "start". An example of this can be found in the Basic Usage section.</p>
<p>The <file/> element is the "workhorse" element. This element is used to convey meta-data and report file transfer actions. This elemnt contains attributes for file meta-data and actions, and MAY contain a <desc/>, a <range/>, and zero or more <feature xmlns='jabber:iq:negotiate'/> (&xep0020;) elements.</p>
<p>The "id" attribute specifies the identifier for this particular file transfer. This attribute MUST be present at all times. There are no value requirements other than it MUST be unique between the sender and receiver.</p>
<p>The "action" attribute specifies the action to undertake with the given file. This attribute SHOULD be present in most cases. If not present, the value "offer" is implied. The value of "action" MUST be one of the following:</p>
<tablecaption='Possible "action" values'>
<tr>
<th>Value</th>
<th>Description</th>
</tr>
<tr>
<td>complete</td>
<td>The file transfer is complete.</td>
</tr>
<tr>
<td>get</td>
<td>The file transfer should start.</td>
</tr>
<tr>
<td>offer</td>
<td>The file transfer is offered (meta-data MUST be present)</td>
</tr>
<tr>
<td>start</td>
<td>The file transfer is starting.</td>
</tr>
<tr>
<td>error</td>
<td>The file transfer has failed. The outlying error tag has more
information.
</td>
</tr>
</table>
<p>The "name" attribute specifies the file name. This attribute MUST be present if the action is "offer", otherwise it SHOULD NOT be present.</p>
<p>The "size" attribute specifies the file size, in bytes. This attribute MUST be present if the action is "offer", otherwise it SHOULD NOT be present.</p>
<p>The "mime-type" attribute specifies the MIME-type for the file. This attribute SHOULD be present if the action is "offer", otherwise it SHOULD NOT be present. The value of this attribute MUST follow the specification for MIME-types from RFC-2046<note>RFC 2046: "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types" -- <linkurl='http://www.ietf.org/rfc/rfc2046.txt'>http://www.ietf.org/rfc/rfc2046.txt</link></note>.</p>
<p>The "date" attribute specifies the file date. This attribute MAY be present if the action is "offer", otherwise it SHOULD NOT be present. The value MUST follow the specification for ISO 8601 date/time formats<note>ISO 8601: "[Summary of the] International Standard Date and Time Notation" -- <linkurl='http://www.cl.cam.ac.uk/~mgk25/iso-time.html'>http://www.cl.cam.ac.uk/~mgk25/iso-time.html</link></note>.</p>
<p>The "hash" attribute specifies the hash of the file contents. This attribute MAY be present if the action is "offer", otherwise it SHOULD NOT be present. The value MUST be an SHA1 hash of the file contents.</p>
</section2>
<section2topic='<desc/> Element'>
<p>The <desc/> element contains a human-readable description of the file. This element has no attributes, and contains character data content.</p>
</section2>
<section2topic='<range/> Element'>
<p>The <range/> element describes range information for a partial transfer. This element has attributes to define the range length and range offset. This element contains no content.</p>
<p>The "length" attribute defines the range length, in bytes. This attribute MUST be present if the containing <file/> has an action value of "get", otherwise it SHOULD NOT be present. The value of this attribute MUST be an integer value and MUST be less than or equal to the (size + offset) of the file.</p>
<p>The "offset" attribute defines the range offset, in bytes. This attribute MAY be present if the containing <file/> has an action value of "get", otherwise it SHOULD NOT be present. If this attribute is not present, a value of 0 is implied. The value of this attribute MUST be an integer, MUST NOT be less than 0, and MUST be less than (size - length).</p>
</section2>
<section2topic='Error Descriptions'>
<p>
There are three main error conditions in file transfer. Following are the
conditions, error codes and descriptions:
<ul>
<li>
<em>Declining Transfer (403)</em>: During the meta-data negotiation
the receiver may decline the transfer by sending the 403 error. The
<error/> CDATA MAY contain a descriptive reason why, but is not
necessary.
</li>
<li>
<em>No Available Methods (406)</em>: When the sender presents the
available stream methods, and the receiver can not use any of them,
they send a 406 error. The <error/> CDATA is not important.
</li>
<li>
<em>Transfer Failed (500)</em>: If the file transfer fails for any
reason after negotiation, the error generator SHOULD send a 500 error
to the other party. This is the only error message that both the
sender and reciever may send. The <error/> CDATA MAY contain
information about the failure.
</li>
<li>
<em>Unable to Start Stream (502)</em>: When the receiver is unable to
start the negotiated stream method they send a 502 error to the
sender. The <error/> CDATA is not important.
</li>
</ul>
</p>
</section2>
</section1>
<section1topic='Security Considerations'>
<p>
Data integrity can be checked with the sha1 of the file that is sent. This
could be attacked via a man in the middle attack, but much more embarrasing
things could result from that than a bad file. The wire integrity is left
to the stream method.
</p>
</section1>
<section1topic='IANA Considerations'>
<p>
The mime-type attribute on <file/> is a valid MIME type as controlled
by the IANA.
</p>
</section1>
<section1topic='JANA Considerations'>
<p>
The "http://jabber.org/protocol/filexfer" is the only namespace that needs
