xeps/inbox/thumbs.xml

<?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 Thumbnails</title>
  <abstract>This specification defines a way for a client supply a preview image for a file transfer.</abstract>
  <legal>
    <copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2009 by the XMPP Standards Foundation (XSF).</copyright>
    <permissions>Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the &quot;Specification&quot;), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.</permissions>
    <warranty>## NOTE WELL: This Specification is provided on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##</warranty>
    <liability>In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.</liability>
    <conformance>This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at &lt;<link url='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>&gt; or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).</conformance>
  </legal>
  <number>xxxx</number>
  <status>ProtoXEP</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0001</spec>
    <spec>XEP-0096</spec>
    <spec>XEP-0231</spec>
    <spec>XEP-0234</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>thumbs</shortname>
  <author>
    <firstname>Marcus</firstname>
    <surname>Ludblad</surname>
    <email>ml@update.uu.se</email>
    <jid>mlundblad@jabber.org</jid>
  </author>
  <revision>
    <version>0.0.3</version>
    <date>2009-03-10</date>
    <initials>ml</initials>
    <remark><p>Split use-case section into "Introduction", "Requirements", and "Use case".</p>
    </remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2009-02-25</date>
    <initials>ml</initials>
    <remark><p>Removed service disovery.
Added missing namespace on thumnail elements.</p>
    </remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2009-02-23</date>
    <initials>ml</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='introduction'>
  <p>The current methods for file transfers include basic meta data about the
file being offered (name, size, and date). There currently is no way to provide an image thumbnail for files such as photos.</p>
</section1>
<section1 topic='Requirements' anchor='requirements'>
  <p>This documents defines a way to include a thumbnail image as an additional metadata in a file transfer.</p>
</section1>
<section1 topic='Use Case' anchor='usecase'>
  <p>When a client wishes to supply a thumbnail in a transfer offer, it can do so by including an extra <![CDATA[<thumbnail/>]]> element as show in the following exaples.</p>
  <example caption='Inclusion of a thumbnail in 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='image.jpg'
          size='3032449'>
      <thumbnail xmlns='urn:xmpp:thumbs:0'
		 cid='sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org'
		 mime-type='image/png'
		 width='128'
		 height='96'/>
    </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>
    ]]>
</example>
  <p>The receiver MAY now request the data using the protocol defined in XEP-0231.</p>
<example caption='Inclusion of a thumbnail 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:0'
          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:1'>
        <offer>
          <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
                name='image.jpg'
                size='3032449'
                hash='552da749930852c69ae5d2141d3766b1'
                date='1969-07-21T02:56:15Z'>
            <desc>This is a test. If this were a real file...</desc>
	    <thumbnail xmlns='urn:xmpp:thumbs:0'
		       cid='sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org'
		       mime-type='image/png'
		       width='128'
		       height='96'/>
          </file>
        </offer>
      </description>
      ...
    </content>
  </jingle>
</iq>
]]>
</example>
  <section2 topic='Definition of the thumbnail Element'
	    anchor='thumbnail_element'>
    <p>The following attributes are defined for the &lt;thumbnail/&gt; element.</p>
    <table caption='Attributes of the thumbnail Element'>
      <tr>
        <th>Attribute</th>
        <th>Description</th>
        <th>Inclusion</th>
      </tr>
      <tr>
        <td>cid</td>
        <td>A Content-ID that can be mapped to a cid: URL as specified in &rfc2111;. The 'cid' value SHOULD be of the form algo+hash@bob.xmpp.org, where the "algo" is the hashing algorithm used (e.g., "sha1" for the SHA-1 algorithm as specified in &rfc3174;) and the "hash" is the hex output of the algorithm applied to the binary data itself.</td>
        <td>REQUIRED</td>
      </tr>
      <tr>
        <td>mime-type</td>
        <td>The value of the 'mime-type' attribute MUST match the syntax specified in &rfc2045;. That is, the value MUST include a top-level media type, the "/" character, and a subtype; in addition, it MAY include one or more optional parameters (e.g., the "audio/ogg" MIME type in the example shown below includes a "codecs" parameter as specified in &rfc4281;). The "type/subtype" string SHOULD be registered in the &ianamedia;, but MAY be an unregistered or yet-to-be-registered value.</td>
        <td>RECOMMENDED</td>
      </tr>
      <tr>
	<td>width</td>
	<td>The intended display width of the thumbnail image. Used as a hint for the receiving client to prepare i.e. a dialog window.</td>
	<td>OPTIONAL</td>
      </tr>
      <tr>
	<td>height</td>
	<td>The intended display height of the thumbnail image. Used as a hint for the receiving client to prepare i.e. a dialog window.</td>
	<td>OPTIONAL</td>
      </tr>
    </table>

  </section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>The inclusion of an image thumbnail may leak information about a transfer
otherwise taking place on an e2e encrypted file transfer stream. A client MAY
wish to not include a thumbnail.</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'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:thumbs:0</li>
    </ul>
    <p>The &REGISTRAR; includes this namespace in the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    <p>If the protocol defined in this specification undergoes a major revision that is not fully backward-compatible with an older version, or that contains significant new features, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of <cite>XEP-0053</cite>.</p>
  </section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:thumbs:0'
    xmlns='urn:xmpp:thumbs:0'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      xxx
    </xs:documentation>
  </xs:annotation>

  <xs:element name='thumbnail'>
    <xs:complexType>
      <xs:attribute name='cid' type='xs:string' use='required'/>
      <xs:attribute name='mime-type' type='xs:string' use='optional'/>
      <xs:attribute name='width' type='xs:integer' use='optional'/>
      <xs:attribute name='height' type='xs:integer' use='optional'/>
    </xs:complexType>
  </xs:element>
</xs:schema>
  ]]></code>
</section1>
</xep>