moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-24 02:02:16 -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'?> <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep> <xep>
<header> <header>
<title>File Transfer Thumbnails</title> <title>Jingle Content Thumbnails</title>
<abstract>This specification defines a way for a client supply a preview image for a file transfer.</abstract> <abstract>This specification defines a way for a client to supply a preview image for Jingle content.</abstract>
&LEGALNOTICE; &LEGALNOTICE;
<number>0264</number> <number>0264</number>
<status>Deferred</status> <status>Experimental</status>
<type>Standards Track</type> <type>Standards Track</type>
<sig>Standards</sig> <sig>Standards</sig>
<approver>Council</approver> <approver>Council</approver>
@ -28,6 +28,17 @@
<email>ml@update.uu.se</email> <email>ml@update.uu.se</email>
<jid>mlundblad@jabber.org</jid> <jid>mlundblad@jabber.org</jid>
</author> </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> <revision>
<version>0.3</version> <version>0.3</version>
<date>2009-04-27</date> <date>2009-04-27</date>
@ -69,43 +80,15 @@ Added missing namespace on thumnail elements.</p>
</revision> </revision>
</header> </header>
<section1 topic='Introduction' anchor='introduction'> <section1 topic='Introduction' anchor='introduction'>
<p>The current methods for file transfers include basic meta data about the <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>
file being offered (name, size, and date). There currently is no way to provide an image thumbnail for files such as photos.</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>
<section1 topic='Requirements' anchor='requirements'> <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>
<section1 topic='Use Case' anchor='usecase'> <section1 topic='Use Cases' 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> <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 SI file transfer offer'><![CDATA[ <example caption='Inclusion of a thumbnail in a Jingle 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[
<iq from='romeo@montague.lit/orchard' <iq from='romeo@montague.lit/orchard'
id='nzu25s8' id='nzu25s8'
to='juliet@capulet.lit/balcony' 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' initiator='romeo@montague.lit/orchard'
sid='851ba2'> sid='851ba2'>
<content creator='initiator' name='a-file-offer'> <content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:1'> <description xmlns='urn:xmpp:jingle:apps:file-transfer:4' senders='initiator'>
<offer> <file>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer' <media-type>image/jpeg</media>
name='image.jpg' <name>image.jpg</name>
size='3032449' <size>3032449</size>
hash='552da749930852c69ae5d2141d3766b1' <hash xmlns='urn:xmpp:hashes:1' algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
date='1969-07-21T02:56:15Z'> <desc>This is a test. If this were a real file...</desc>
<desc>This is a test. If this were a real file...</desc> <thumbnail xmlns='urn:xmpp:thumbs:1'
<thumbnail xmlns='urn:xmpp:thumbs:0' uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org'
cid='sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org' media-type='image/png'
mime-type='image/png' width='128'
width='128' height='96'/>
height='96'/> </file>
</file>
</offer>
</description> </description>
... <transport .../>
</content> </content>
</jingle> </jingle>
</iq> </iq>]]></example>
]]>
</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> <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>
<section1 topic='Security Considerations' anchor='security'> <section1 topic='Security Considerations' anchor='security'>
<p>The inclusion of an image thumbnail may leak information about a transfer <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 otherwise taking place on an e2e encrypted file transfer stream. A client MAY
wish to not include a thumbnail.</p> 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>
<section1 topic='IANA Considerations' anchor='iana'> <section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p> <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'> <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespace:</p> <p>This specification defines the following XML namespace:</p>
<ul> <ul>
<li>urn:xmpp:thumbs:0</li> <li>urn:xmpp:thumbs:1</li>
</ul> </ul>
<p>The &REGISTRAR; includes this namespace in the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p> <p>The &REGISTRAR; includes this namespace in the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2> </section2>
@ -210,8 +226,8 @@ wish to not include a thumbnail.</p>
<xs:element name='thumbnail'> <xs:element name='thumbnail'>
<xs:complexType> <xs:complexType>
<xs:attribute name='cid' type='xs:string' use='required'/> <xs:attribute name='uri' type='xs:anyURI' use='required'/>
<xs:attribute name='mime-type' type='xs:string' use='optional'/> <xs:attribute name='media-type' type='xs:string' use='optional'/>
<xs:attribute name='width' type='xs:integer' use='optional'/> <xs:attribute name='width' type='xs:integer' use='optional'/>
<xs:attribute name='height' type='xs:integer' use='optional'/> <xs:attribute name='height' type='xs:integer' use='optional'/>
</xs:complexType> </xs:complexType>