No Description
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

xep-0264.xml 9.9KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238
  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM 'xep.ent'>
  4. %ents;
  5. ]>
  6. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  7. <xep>
  8. <header>
  9. <title>Jingle Content Thumbnails</title>
  10. <abstract>This specification defines a way for a client to supply a preview image for Jingle content.</abstract>
  11. &LEGALNOTICE;
  12. <number>0264</number>
  13. <status>Deferred</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <approver>Council</approver>
  17. <dependencies>
  18. <spec>XMPP Core</spec>
  19. <spec>XEP-0096</spec>
  20. <spec>XEP-0231</spec>
  21. </dependencies>
  22. <supersedes/>
  23. <supersededby/>
  24. <shortname>thumbs</shortname>
  25. <author>
  26. <firstname>Marcus</firstname>
  27. <surname>Lundblad</surname>
  28. <email>ml@update.uu.se</email>
  29. <jid>mlundblad@jabber.org</jid>
  30. </author>
  31. &lance;
  32. <revision>
  33. <version>0.4</version>
  34. <date>2015-08-26</date>
  35. <initials>ljts</initials>
  36. <remark>
  37. <p>Changed format to use generic 'uri' attribute to allow for 'https:' and 'http:' URIs in addition to BoB 'cid:' URIs.</p>
  38. <p>Indicated that multiple thumbnails may be present.</p>
  39. <p>Expanded scope of use cases to be Jingle content in general, not just file transfer.</p>
  40. </remark>
  41. </revision>
  42. <revision>
  43. <version>0.3</version>
  44. <date>2009-04-27</date>
  45. <initials>ml</initials>
  46. <remark><p>Fixed typo in author's name :).</p></remark>
  47. </revision>
  48. <revision>
  49. <version>0.2</version>
  50. <date>2009-04-06</date>
  51. <initials>ml</initials>
  52. <remark><p>Add paragraph in security section about protecting against malicious thumbnail dimensions in offer. Fixed a typo.</p></remark>
  53. </revision>
  54. <revision>
  55. <version>0.1</version>
  56. <date>2009-04-02</date>
  57. <initials>psa</initials>
  58. <remark><p>Initial published version.</p></remark>
  59. </revision>
  60. <revision>
  61. <version>0.0.3</version>
  62. <date>2009-03-10</date>
  63. <initials>ml</initials>
  64. <remark><p>Split use-case section into "Introduction", "Requirements", and "Use case".</p>
  65. </remark>
  66. </revision>
  67. <revision>
  68. <version>0.0.2</version>
  69. <date>2009-02-25</date>
  70. <initials>ml</initials>
  71. <remark><p>Removed service disovery.
  72. Added missing namespace on thumnail elements.</p>
  73. </remark>
  74. </revision>
  75. <revision>
  76. <version>0.0.1</version>
  77. <date>2009-02-23</date>
  78. <initials>ml</initials>
  79. <remark><p>First draft.</p></remark>
  80. </revision>
  81. </header>
  82. <section1 topic='Introduction' anchor='introduction'>
  83. <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>
  84. <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>
  85. </section1>
  86. <section1 topic='Requirements' anchor='requirements'>
  87. <p>This documents defines a way to include a thumbnail image as an additional metadata in a Jingle content description.</p>
  88. </section1>
  89. <section1 topic='Use Cases' anchor='usecase'>
  90. <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>
  91. <example caption='Inclusion of a thumbnail in a Jingle file transfer offer'><![CDATA[
  92. <iq from='romeo@montague.lit/orchard'
  93. id='nzu25s8'
  94. to='juliet@capulet.lit/balcony'
  95. type='set'>
  96. <jingle xmlns='urn:xmpp:jingle:0'
  97. action='session-initiate'
  98. initiator='romeo@montague.lit/orchard'
  99. sid='851ba2'>
  100. <content creator='initiator' name='a-file-offer'>
  101. <description xmlns='urn:xmpp:jingle:apps:file-transfer:4' senders='initiator'>
  102. <file>
  103. <media-type>image/jpeg</media>
  104. <name>image.jpg</name>
  105. <size>3032449</size>
  106. <hash xmlns='urn:xmpp:hashes:1' algo='sha-1'>552da749930852c69ae5d2141d3766b1</hash>
  107. <desc>This is a test. If this were a real file...</desc>
  108. <thumbnail xmlns='urn:xmpp:thumbs:1'
  109. uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org'
  110. media-type='image/png'
  111. width='128'
  112. height='96'/>
  113. </file>
  114. </description>
  115. <transport .../>
  116. </content>
  117. </jingle>
  118. </iq>]]></example>
  119. <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>
  120. <example caption='Inclusion of a thumbnail in a Jingle RTP video session'><![CDATA[
  121. <iq from='romeo@montague.lit/orchard'
  122. id='ih28sx61'
  123. to='juliet@capulet.lit/balcony'
  124. type='set'>
  125. <jingle xmlns='urn:xmpp:jingle:1'
  126. action='session-initiate'
  127. initiator='romeo@montague.lit/orchard'
  128. sid='a73sjjvkla37jfea'>
  129. <content creator='initiator' name='webcam'>
  130. <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
  131. <payload-type id='98' name='theora' clockrate='90000'>
  132. <parameter name='height' value='600'/>
  133. <parameter name='width' value='800'/>
  134. <parameter name='delivery-method' value='inline'/>
  135. <parameter name='configuration' value='somebase16string'/>
  136. <parameter name='sampling' value='YCbCr-4:2:2'/>
  137. </payload-type>
  138. <payload-type id='28' name='nv' clockrate='90000'/>
  139. <payload-type id='25' name='CelB' clockrate='90000'/>
  140. <payload-type id='32' name='MPV' clockrate='90000'/>
  141. <bandwidth type='AS'>128</bandwidth>
  142. <thumbnail xmlns='urn:xmpp:thumbs:1'
  143. uri='cid:sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org'
  144. media-type='image/png'
  145. width='128'
  146. height='96'/>
  147. </description>
  148. <transport .../>
  149. </content>
  150. </jingle>
  151. </iq>]]></example>
  152. <p>Multiple &lt;thumbnail/&gt; elements MAY be included to provide thumbnails of different sizes, media types, or URIs.</p>
  153. <p>If the provided URI has the scheme 'cid', then the thumbnail data MAY be requested using &xep0231;.</p>
  154. </section1>
  155. <section1 topic='Definition of the thumbnail Element' anchor='thumbnail_element'>
  156. <p>The following attributes are defined for the &lt;thumbnail/&gt; element.</p>
  157. <table caption='Attributes of the thumbnail Element'>
  158. <tr>
  159. <th>Attribute</th>
  160. <th>Description</th>
  161. <th>Inclusion</th>
  162. </tr>
  163. <tr>
  164. <td>uri</td>
  165. <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>
  166. <td>REQUIRED</td>
  167. </tr>
  168. <tr>
  169. <td>media-type</td>
  170. <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>
  171. <td>RECOMMENDED</td>
  172. </tr>
  173. <tr>
  174. <td>width</td>
  175. <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>
  176. <td>OPTIONAL</td>
  177. </tr>
  178. <tr>
  179. <td>height</td>
  180. <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>
  181. <td>OPTIONAL</td>
  182. </tr>
  183. </table>
  184. </section1>
  185. <section1 topic='Security Considerations' anchor='security'>
  186. <p>The inclusion of an image thumbnail may leak information about a transfer
  187. otherwise taking place on an e2e encrypted file transfer stream. A client MAY
  188. wish to not include a thumbnail.</p>
  189. <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>
  190. </section1>
  191. <section1 topic='IANA Considerations' anchor='iana'>
  192. <p>This document requires no interaction with &IANA;.</p>
  193. </section1>
  194. <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  195. <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
  196. <p>This specification defines the following XML namespace:</p>
  197. <ul>
  198. <li>urn:xmpp:thumbs:1</li>
  199. </ul>
  200. <p>The &REGISTRAR; includes this namespace in the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  201. </section2>
  202. <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
  203. &NSVER;
  204. </section2>
  205. </section1>
  206. <section1 topic='XML Schema' anchor='schema'>
  207. <code><![CDATA[
  208. <?xml version='1.0' encoding='UTF-8'?>
  209. <xs:schema
  210. xmlns:xs='http://www.w3.org/2001/XMLSchema'
  211. targetNamespace='urn:xmpp:thumbs:0'
  212. xmlns='urn:xmpp:thumbs:0'
  213. elementFormDefault='qualified'>
  214. <xs:annotation>
  215. <xs:documentation>
  216. The protocol documented by this schema is defined in
  217. xxx
  218. </xs:documentation>
  219. </xs:annotation>
  220. <xs:element name='thumbnail'>
  221. <xs:complexType>
  222. <xs:attribute name='uri' type='xs:anyURI' use='required'/>
  223. <xs:attribute name='media-type' type='xs:string' use='optional'/>
  224. <xs:attribute name='width' type='xs:integer' use='optional'/>
  225. <xs:attribute name='height' type='xs:integer' use='optional'/>
  226. </xs:complexType>
  227. </xs:element>
  228. </xs:schema>
  229. ]]></code>
  230. </section1>
  231. </xep>