moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-21 15:18:51 -05:00
Code Issues Releases Wiki Activity

Update XEP-0264 to allow non-cid URIs, and expand scope

Browse Source
This commit is contained in:
Lance Stout 2015-08-26 13:28:21 -07:00
parent f1d3d763f3
commit 4d3a3baacc
1 changed files with 107 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

198
xep-0264.xml
View File

@ -6,11 +6,11 @@
<?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>
<title>Jingle Content Thumbnails</title>
<abstract>This specification defines a way for a client to supply a preview image for Jingle content.</abstract>
&LEGALNOTICE;
<number>0264</number>
<status>Deferred</status>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
@ -28,6 +28,17 @@
<email>ml@update.uu.se</email>
<jid>mlundblad@jabber.org</jid>
</author>
&lance;
<revision>
<version>0.4</version>
<date>2015-08-26</date>
<initials>ljts</initials>
<remark>
<p>Changed format to use generic 'uri' attribute to allow for 'https:' and 'http:' URIs in addition to BoB 'cid:' URIs.</p>
<p>Indicated that multiple thumbnails may be present.</p>
<p>Expanded scope of use cases to be Jingle content in general, not just file transfer.</p>
</remark>
</revision>
<revision>
<version>0.3</version>
<date>2009-04-27</date>
@ -69,43 +80,15 @@ Added missing namespace on thumnail elements.</p>
</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>
<p>When offering a Jingle session, it can be helpful to provide a small preview of the offered content to help the session responder decide whether to accept or reject the session.</p>
<p>This is particularly useful for file transfer content (especially image files), but can also be used for things such as video (e.g. using a still frame from the stream as the preview thumbnail), and even audio by using a small image of album cover art.</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>
<p>This documents defines a way to include a thumbnail image as an additional metadata in a Jingle content description.</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 shown 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 &xep0231;.</p>
<example caption='Inclusion of a thumbnail in a Jingle file transfer offer'><![CDATA[
<section1 topic='Use Cases' anchor='usecase'>
<p>When a client wishes to supply a thumbnail in a content offer, it can do so by including an extra &lt;thumbnail/&gt; element as shown in the following example:</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'
@ -115,66 +98,99 @@ file being offered (name, size, and date). There currently is no way to provide
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 xmlns='urn:xmpp:jingle:apps:file-transfer:4' senders='initiator'>
<file>
<media-type>image/jpeg</media>
<name>image.jpg</name>
<size>3032449</size>
<hash xmlns='urn:xmpp:hashes:1' algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
<desc>This is a test. If this were a real file...</desc>
<thumbnail xmlns='urn:xmpp:thumbs:1'
uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org'
media-type='image/png'
width='128'
height='96'/>
</file>
</description>
...
<transport .../>
</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>
</iq>]]></example>
</section2>
<p>Thumbnails MAY be included for Jingle content other than file transfer. For example, with Jingle RTP video a thumbnail could be included to show who is calling (either by capturing a still frame from the input stream or by using an existing profile image):</p>
<example caption='Inclusion of a thumbnail in a Jingle RTP video session'><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='ih28sx61'
to='juliet@capulet.lit/balcony'
type='set'>
<jingle xmlns='urn:xmpp:jingle:1'
action='session-initiate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='webcam'>
<description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
<payload-type id='98' name='theora' clockrate='90000'>
<parameter name='height' value='600'/>
<parameter name='width' value='800'/>
<parameter name='delivery-method' value='inline'/>
<parameter name='configuration' value='somebase16string'/>
<parameter name='sampling' value='YCbCr-4:2:2'/>
</payload-type>
<payload-type id='28' name='nv' clockrate='90000'/>
<payload-type id='25' name='CelB' clockrate='90000'/>
<payload-type id='32' name='MPV' clockrate='90000'/>
<bandwidth type='AS'>128</bandwidth>
<thumbnail xmlns='urn:xmpp:thumbs:1'
uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org'
media-type='image/png'
width='128'
height='96'/>
</description>
<transport .../>
</content>
</jingle>
</iq>]]></example>
<p>Multiple &lt;thumbnail/&gt; elements MAY be included to provide thumbnails of different sizes, media types, or URIs.</p>
<p>If the provided URI has the scheme 'cid', then the thumbnail data MAY be requested using &xep0231;.</p>
</section1>
<section1 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>uri</td>
<td>A URI where the thumbnail data can be accessed (typically by using a URI scheme of 'cid:', 'https:', or 'http:'). If the URI scheme is 'cid:' then the identifier MUST refer to a bit of binary data as described in &xep0231;</td>
<td>REQUIRED</td>
</tr>
<tr>
<td>media-type</td>
<td>The value of the 'media-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. 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 the appropriate UI, such as 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 the appropriate UI, such as a dialog window.</td>
<td>OPTIONAL</td>
</tr>
</table>
</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>
<p>A client MUST NOT rely on the values specified for the width and height of a thumbnail to allocate a bitmap data buffer for the thumbnail, to prevent possible DoS attacks. Also a client SHOULD apply implementation-specific limits on the thumbnails, if using these values to pepare a UI element for the thumbnail image, of f.ex. 128x128 pixels, values exceeding these would then be truncated and the thumbnail image scaled down when received.</p>
<p>A client MUST NOT rely on the values specified for the width and height of a thumbnail to allocate a bitmap data buffer for the thumbnail, to prevent possible DoS attacks. Also a client SHOULD apply implementation-specific limits on the thumbnails, if using these values to pepare a UI element for the thumbnail image, e.g. with dimensions of 128x128 pixels, values exceeding these would then be truncated and the thumbnail image scaled down when received.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
@ -183,7 +199,7 @@ wish to not include a thumbnail.</p>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:thumbs:0</li>
<li>urn:xmpp:thumbs:1</li>
</ul>
<p>The &REGISTRAR; includes this namespace in the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>
@ -210,8 +226,8 @@ wish to not include a thumbnail.</p>
<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='uri' type='xs:anyURI' use='required'/>
<xs:attribute name='media-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>