xeps/xep-0358.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>Publishing Available Jingle Sessions</title>
  <abstract>This specification defines an XMPP protocol extension that enables an XMPP entity to advertise the fact that it is willing accept a particular Jingle session request. The protocol is used mainly to inform other entities that a particular file is available for transfer via the Jingle File Transfer protocol defined in XEP-0234.</abstract>
  &LEGALNOTICE;
  <number>0358</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0030</spec>
    <spec>XEP-0234</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>jinglepub</shortname>
  <schemaloc/>
  &fippo;
  &lance;
  &stpeter;
  <revision>
      <version>0.1</version>
      <date>2015-06-29</date>
      <initials>XEP Editor (psa)</initials>
      <remark><p>Initial published version approved by the XMPP Council.</p></remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2014-08-12</date>
    <initials>ls/psa/ph</initials>
    <remark>
      <ul>
        <li>Changed payload to use one or more Jingle &lt;description/&gt; elements (this provides support for content with multiple media types, such as audio+video).</li>
        <li>Removed 'app' attribute, since we include the application-format description as a child element.</li>
        <li>Removed 'mime-type' attribute, since it can be signalled in the application-format description if needed.</li>
        <li>Added &lt;meta/&gt; element to provide human-friendly information about the session.</li>
        <li>Incremented the protocol version number from 0 to 1.</li>
      </ul>
    </remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2014-07-30</date>
    <initials>ph/ls/psa</initials>
    <remark>First draft.</remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>This document defines a way for an entity that can initiate a Jingle session (often for the purpose of file transfer as specified in &xep0234;) to advertise that session, thus enabling a receiver to then request initiation of the session by the sender. In essence, this document defines the Jingle equivalent of &xep0137; (previously defined for &xep0095;).</p>
</section1>
<section1 topic='Use Cases' anchor='usecase'>
  <section2 topic='Publishing a Jingle Session Request' anchor='usecase.publish'>
    <p>A session owner uses the &lt;jinglepub/&gt; element to announce that it can initiate a specific Jingle session request. This element can be sent to a publish-subscribe node (see &xep0060; and &xep0163;), or sent directly to potential recipients within a &MESSAGE; stanza.</p>
    <p>The format of the &lt;jinglepub/&gt; element is as follows:</p>
    <example caption='Sample &lt;jinglepub/&gt;'><![CDATA[
  <jinglepub xmlns='urn:xmpp:jinglepub:1'
             from='sender-jid'
             id='someid'>
    [<meta/> element(s) for human-friendly information]
    [<description/> element(s) for application format(s)]
  </jinglepub>
    ]]></example>
    <p>The 'from' attribute MUST be present and MUST be the valid JID for the session owner.</p>
    <p>The 'id' attribute is an opaque identifier. This attribute MUST be present, and MUST be a valid non-empty string. It uniquely identifies the published request at the session owner's JID.</p>
    <p>The &lt;jinglepub/&gt; element MUST contain a &lt;description/&gt; element qualified by the namespace of the relevant Jingle application format (e.g., &lt;description xmlns='urn:xmpp:jingle:apps:file-transfer:4'/&gt; for file transfer).</p>
    <p>The &lt;jinglepub/&gt; element MAY contain one or more &lt;meta/&gt; elements qualified by the jingle-pub namespace; if more than one element is included, each element MUST have a different value for the 'xml:lang' attribute.</p>
    <p>The &lt;jinglepub/&gt; information is typically provided via pubsub.</p>
    <p>The following example shows a possible payload for streaming of recorded audio/video sessions, here pushed out via PEP.</p>
    <example caption='Sender advertises session via PEP'><![CDATA[
<iq from='bard@shakespeare.lit/globe' id='yhe51f39' type='set'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='scenes'>
      <jinglepub xmlns='urn:xmpp:jinglepub:1'
          from='bard@shakespeare.lit'
          id='9559976B-3FBF-4E7E-B457-2DAA225972BB'>
        <meta xml:lang='en' 
              title='Act III, Scene I of Hamlet'
              summary='High-definition audio and video recording 
                       for Act III, Scene I of Hamlet, captured 
                       last week at the Globe Theatre, London.'/>
        <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
        <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
      </jinglepub>
    </publish>
  </pubsub>
</iq>
    ]]></example>
    <example caption='Pubsub service pushes announcement to all subscribers'><![CDATA[
<message from='bard@shakespeare.lit' to='juliet@capulet.com/balcony'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='scenes'>
      <item id='current'>
        <jinglepub xmlns='urn:xmpp:jinglepub:1'
            from='bard@shakespeare.lit'
            id='9559976B-3FBF-4E7E-B457-2DAA225972BB'>
          <meta xml:lang='en' 
                title='Act III, Scene I of Hamlet'
                summary='High-definition audio and video recording 
                         for Act III, Scene I of Hamlet, captured 
                         last week at the Globe Theatre, London.'/>
          <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
          <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
        </jinglepub>
      </item>
    </items>
  </event>
</message>
    ]]></example>
    <p>The &lt;jinglepub/&gt; element MAY also be included directly within a &MESSAGE; stanza sent to another entity (or multiple entities, e.g., in &xep0045;). This can be especially useful for informing an offline entity about an available stream.</p>
    <example caption='Advertising a stream in a message stanza'><![CDATA[
<message from='romeo@montague.net/pda' to='juliet@capulet.com'>
  <jinglepub xmlns='urn:xmpp:jinglepub:1'
      id='9559976B-3FBF-4E7E-B457-2DAA225972BB'>
    <meta xml:lang='en' 
          title='Act III, Scene I of Hamlet'
          summary='High-definition audio and video recording 
                   for Act III, Scene I of Hamlet, captured 
                   last week at the Globe Theatre, London.'/>
    <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
    <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
  </jinglepub>
</message>
    ]]></example>
  </section2>
  <section2 topic='Triggering the Stream Initiation Request' anchor='usecase.trigger'>
    <p>A potential receiver requests initiation of the session by sending an IQ-get to the sender, using the &lt;start xmlns='urn:xmpp:jinglepub:1'/&gt; element. This element contains the 'id' attribute to specify which published stream to retrieve:</p>
    <example caption='Receiver requests start of session'><![CDATA[
  <iq type='get'
      id='jinglepub-request-0'
      from='juliet@capulet.com/balcony'
      to='romeo@montague.net/pda'>
    <start xmlns='urn:xmpp:jinglepub:1'
           id='9559976B-3FBF-4E7E-B457-2DAA225972BB'/>
  </iq>
    ]]></example>
    <p>If the sender accepts the request, it responds with an IQ-result containing a &lt;starting/&gt; element. This element indicates the session identifier to be used:</p>
    <example caption='Sender accepts request to start session'><![CDATA[
  <iq type='result'
      id='jinglepub-request-0'
      from='romeo@montague.net/pda'
      to='juliet@capulet.com/balcony'>
    <starting xmlns='urn:xmpp:jinglepub:1'
              sid='851ba2'/>
  </iq>
    ]]></example>
    <p>Then the sender initiates the Jingle session:</p>
    <example caption='Sender starts negotiation'><![CDATA[
<iq from='romeo@montague.lit/orchard'
    id='nzu25s8'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:1'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='851ba2'>
    <content creator='initiator' name='scene-audio'>
      <description xmlns='urn:xmpp:jingle:apps:rtp:1' media='audio'>
        <payload-type id='101' name='opus' clockrate='48000'>
          <parameter name='stereo' value='1'/>
          <parameter name='sprop-stereo' value='1'/>
        </payload-type>
        <payload-type id='97' name='speex' clockrate='8000'/>
        <payload-type id='18' name='G729'/>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'>
        <candidate component='1'
                   foundation='1'
                   generation='0'
                   id='or2ii2syr1'
                   ip='192.0.2.1'
                   network='0'
                   port='3478'
                   priority='2130706431'
                   protocol='udp'
                   type='host'/>
      </transport>
    </content>
    <content creator='initiator' name='scene-video'>
      <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>
      </description>
      <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'/>
    </content>
  </jingle>
</iq>
    ]]></example>
    <p>If the requested identifier is not valid, the sender SHOULD respond with a &notacceptable; error:</p>
    <example caption='Sender denies because of invalid id'><![CDATA[
  <iq type='error'
      id='jinglepub-set-1'
      from='romeo@montague.net/pda'
      to='juliet@capulet.com/balcony'>
    <start xmlns='urn:xmpp:jinglepub:1'>9559976B-3FBF-4E7E-B457-2DAA225972BB</start>
    <error code='405' type='modify'>
      <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    </error>
  </iq>
    ]]></example>
    <p>If the receiver does not have permission to request the data stream, the sender SHOULD respond with a &forbidden; error:</p>
    <example caption='Sender denies because receiver is forbidden'><![CDATA[
  <iq type='error'
      id='jinglepub-set-1'
      from='romeo@montague.net/pda'
      to='juliet@capulet.com/balcony'>
    <start xmlns='urn:xmpp:jinglepub:1'>9559976B-3FBF-4E7E-B457-2DAA225972BB</start>
    <error code='403' type='auth'>
      <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    </error>
  </iq>
    ]]></example>
  </section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>This document introduces no security concerns beyond those specified in <cite>XEP-0060</cite> and the relevant Jingle application format in use.</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.namespaces'>
    <p>The &REGISTRAR; will be requested to include 'urn:xmpp:jinglepub:1' in its registry of protocol namespaces.</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'
    xmlns:xml='http://www.w3.org/XML/1998/namespace'
    targetNamespace='urn:xmpp:jinglepub:1'
    xmlns='urn:xmpp:jinglepub:1'
    elementFormDefault='qualified'>

  <xs:element name='jinglepub'>
    <xs:complexType>
      <xs:sequence>
        <xs:any namespace='##other' minOccurs='1' maxOccurs='unbounded'/>
        <xs:element name='meta' type='metaElementType'/>
      </xs:sequence>
      <xs:attribute name='description' type='xs:string' use='optional'/>
      <xs:attribute name='from' type='xs:string' use='required'/>
      <xs:attribute name='id' type='xs:string' use='required'/>
      <xs:attribute name='title' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:complexType name='metaElementType'>
    <xs:simpleContent>
      <xs:extension base='empty'>
        <xs:attribute name='summary'
                      type='xs:string'
                      use='optional'/>
        <xs:attribute name='title'
                      type='xs:string'
                      use='required'/>
        <xs:attribute ref='xml:lang' use='optional'/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

  <xs:element name='start'>
    <xs:complexType>
      <xs:attribute name='id' type='xs:string' use='required'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='starting'>
    <xs:complexType>
      <xs:attribute name='sid' type='xs:string' use='required'/>
    </xs:complexType>
  </xs:element>

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