xeps/xep-0221.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>Data Forms Media Element</title>
  <abstract>This specification defines an XMPP protocol extension for including media data in XEP-0004 data forms.</abstract>
  &LEGALNOTICE;
  <number>0221</number>
  <status>Proposed</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0004</spec>
  </dependencies>
  <supersedes>None</supersedes>
  <supersededby>None</supersededby>
  <shortname>NOT_YET_ASSIGNED</shortname>
  &ianpaterson;
  &stpeter;
  <revision>
    <version>0.2</version>
    <date>2008-01-30</date>
    <initials>psa</initials>
    <remark>Modified to reuse data element from XEP-0231.</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2007-07-11</date>
    <initials>psa/ip</initials>
    <remark>Initial version, split off from XEP-0158.</remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>In certain protocols that make use of &xep0004;, it can be helpful to include media data such as small images. One example of such a "using protocol" is &xep0158;. This document defines a method for including media data in a data form.</p>
</section1>

<section1 topic='Media Element' anchor='media'>
  <p>The root element for media data is &lt;media/&gt;. This element MUST be qualified by the "urn:xmpp:tmp:media-element' namespace &NSNOTE;. The &lt;media/&gt; element MUST be contained within a &lt;field/&gt; element qualified by the 'jabber:x:data' namespace.</p>
  <p>If the media is an image or video then the &lt;media/&gt; element SHOULD include 'height' and 'width' attributes specifying the recommended display size of the media in pixels.</p>
  <p>The &lt;media/&gt; element MUST contain at least one &lt;uri/&gt; element to specify the out-of-band location of the media data. <note>Constrained execution environments prevent some clients (e.g., Web clients) from rendering media unless it has been received out-of-band.</note> The &lt;uri/&gt; element MUST contain a URI that indicates the location and MUST include a 'type' atribute that specifies the MIME type (see &rfc2045;) of the media.</p>
  <p>The &lt;media/&gt; element MAY also contain one or more &lt;data/&gt; elements for distributing the media in-band. The &lt;data/&gt; element MUST be qualified by the 'urn:xmpp:tmp:data-element' as defined in &xep0231;. The <em>encoded</em> data SHOULD NOT be larger than 8 kilobytes. <note>If a stanza contains more than one &lt;data/&gt; element, the sending entity MUST take care not to trigger server-defined bandwidth limits.</note></p>
  <example caption='Audio Media Element'><![CDATA[
<media xmlns='urn:xmpp:tmp:media-element'>
  <uri type='audio/x-wav'>
    http://victim.example.com/challenges/speech.wav?F3A6292C
  </uri>
  <uri type='audio/ogg-speex'>
    http://victim.example.com/challenges/speech.ogg?F3A6292C
  </uri>
  <uri type='audio/mpeg'>
    http://victim.example.com/challenges/speech.mp3?F3A6292C
  </uri>
  <data xmlns='urn:xmpp:tmp:data-element' 
        alt='An audio file'
        type='audio/x-wav'>
    [ ... base64-encoded-audio ... ]
  </data>
</media>
  ]]></example>
  <p>The following example is provided only for the purpose of illustration; consult the specifications for using protocols to see canonical examples.</p>
  <example caption='Inclusion in Data Form'><![CDATA[
<x xmlns='jabber:x:data' type='form'>
  [ ... ]
  <field var='ocr'>
    <media xmlns='xmlns='urn:xmpp:tmp:media-element'
           height='80'
           width='290'>
      <uri type='image/jpeg'>
        http://www.victim.com/challenges/ocr.jpeg?F3A6292C
      </uri>
      <data xmlns='urn:xmpp:tmp:data-element'
            type='image/jpeg'> ** Base64 encoded image ** </data>
    </media>
  </field>
  [ ... ]
</x>
  ]]></example>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='ns'>
    <p>Until this specification advances to a status of Draft, its associated namespace shall be "urn:xmpp:tmp:media-element"; upon advancement of this specification, the &REGISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</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:tmp:media-element'
    xmlns='urn:xmpp:tmp:media-element'
    elementFormDefault='qualified'>

  <xs:import 
      namespace='urn:xmpp:tmp:data-element'/>

  <xs:element name='media'>
    <xs:complexType>
      <xs:sequence xmlns:data='urn:xmpp:tmp:data-element'>
        <xs:element ref='uri' minOccurs='1' maxOccurs='unbounded'/>
        <xs:element ref='data:data' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='height' type='xs:unsignedShort' use='optional'/>
      <xs:attribute name='width' type='xs:unsignedShort' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='uri'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute name='type' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

</xs:schema>
  ]]></code>
</section1>

</xep>