<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>File Transfer Metadata</title>
  <abstract>An extension to XEP-0096 and XEP-0234 to design a way of
  adding arbitrary data to file transfer offers.</abstract>
  &LEGALNOTICE;
  <number>xxxx</number>
  <status>ProtoXEP</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0096</spec>
    <spec>XEP-0234</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>NOT YET ASSIGNED</shortname>
 <author>
    <firstname>Jonny</firstname>
    <surname>Lamb</surname>
    <email>jonny.lamb@collabora.co.uk</email>
    <jid>jonny.lamb@collabora.co.uk</jid>
  </author>
  <revision>
    <version>0.0.1</version>
    <date>2011-11-11</date>
    <initials>jl</initials>
    <remark>Initial version.</remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>The current methods for file transfers include basic metadata
  about the file being offered such as its name, size, and date. There
  currently is no way to provide arbitrary details about the file
  being transferred. <cite>XEP-0264</cite> starts to address this
  problem, but only includes thumbnails of transfers.</p>

  <p>The design of this extension to file transfer offers is
  influenced by adding data forms to disco#info replies (as per
  &xep0115;) and by the design of &xep0264;</p>
</section1>

<section1 topic='Requirements' anchor='requirements'>
  <p>This document defines a way to include arbitrary data in a file
  transfer.</p>
</section1>

<section1 topic='Use Case' anchor='usecase'>
  <p>The arbitrary data added to the offer is incluced in &xep0004;
  which must be formatted according to &xep0128; to the root
  &lt;file&gt; element. There can be as many data forms under said
  &lt;file&gt; element as long as the FORM_TYPE field is different for
  each form.</p>
</section1>

<section1 topic='Examples' anchor='examples'>
  <example caption='Inclusion of photo EXIF data in an SI file
                    transfer offer'><![CDATA[
<iq type='set' id='offer1' to='receiver@jabber.org/resource'>
  <si xmlns='http://jabber.org/protocol/si'
      id='a0'
      mime-type='image/jpeg'
      profile='http://jabber.org/protocol/si/profile/file-transfer'>
    <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
          name='thatwildparty.jpg'
          size='3240688'>
      <x xmlns='jabber:x:data' type='result'>
        <field var='FORM_TYPE' type='hidden'>
          <value>example:dataform:exifdata</value>
        </field>
        <field var='ImageWidth'>
          <value>3872</value>
        </field>
        <field var='ImageHeight'>
          <value>2592</value>
        </field>
        <field var='Make'>
          <value>NIKON CORPORATION</value>
        </field>
        <field var='Model'>
          <value>NIKON D80</value>
        </field>
      </x>
    </file>
    ...
  </si>
</iq>]]></example>

  <example caption='Inclusion of photo EXIF data in a Jingle file
                    transfer offer'><![CDATA[
<iq from='romeo@montague.lit/orchard'
    id='nzu25s8'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='851ba2'>
    <content creator='initiator' name='a-file-offer'>
      <description xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
        <offer>
          <file>
            <date>1969-07-21T02:56:15Z</date>
            <desc>The wild party you should've been at</desc>
            <name>thatwildparty.jpg</name>
            <range/>
            <size>8492843</size>
            <hashes xmlns='urn:xmpp:hashes:0'>
              <hash algo='sha1'>552da749930852c69ae5d2141d3766b1</hash>
            </hashes>
            <x xmlns='jabber:x:data' type='result'>
              <field var='FORM_TYPE' type='hidden'>
                <value>example:dataform:exifdata</value>
              </field>
              <field var='ImageWidth'>
                <value>3872</value>
              </field>
              <field var='ImageHeight'>
                <value>2592</value>
              </field>
              <field var='Make'>
                <value>NIKON CORPORATION</value>
              </field>
              <field var='Model'>
                <value>NIKON D80</value>
              </field>
            </x>
          </file>
        </offer>
      </description>
      ...
    </content>
  </jingle>
</iq>]]></example>
</section1>

<section1 topic='Security Considerations' anchor='sec'>
  <p>This document introduces no security concerns above and beyond
  those specified in &xep0004;.</p>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;. </p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <p>This document requires no interaction with the &REGISTRAR;;
  however, specifications following the best practices defined herein
  may register FORM_TYPEs and field values with the XMPP
  Registrar.</p>
</section1>

</xep>
