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>Deferred</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>
  &fippo;
  &lance;
  &stpeter;
  <revision>
    <version>0.4</version>
    <date>2017-09-11</date>
    <initials>XEP Editor (jwi)</initials>
    <remark>Defer due to lack of activity.</remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2016-05-24</date>
    <initials>fs</initials>
    <remark><p>Add Jingle query type and XMPP registrar submission.</p></remark>
  </revision>
  <revision>
      <version>0.2</version>
      <date>2015-08-11</date>
      <initials>ls</initials>
      <remark><p>Add &lt;uri/&gt; element.</p></remark>
  </revision>
  <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 &xep0166; 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'>
    [<uri/> element for an alternate or informational URI of the content]
    [<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, called the "jinglepub 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; element MAY contain a &lt;uri/&gt; element which contains a URI for an alternative way to access the content, or other information about the content. The resource provided by the URI SHOULD be meaningful for clients that do not directly support the included Jingle content definitions, and accessing the URI MAY result in a different experience than initiating the published Jingle session. For example, the URI could be to a content landing page of an image hosting service from which an image could be viewed instead of directly downloading the image file.</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>In general, the process to trigger a stream initiation request is as follows:</p>
    <code><![CDATA[
Requester                   Publisher
    |                           |
    |   <start/>                |
    |-------------------------->|
    |   <starting/>             |
    |<--------------------------|
    |   session-initiate        |
    |<--------------------------|
    |   [further jingle         |
    |    negotiation]           |
    |<------------------------->|
    |                           |]]></code>
    <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>
  <section2 topic='Jingle Session XMPP URI/IRI Query Type' anchor='jingle-uri-query-types'>

    <p>This document defines the 'jingle' XMPP URI/IRI querytype,
    which MUST posses an 'id' key/value pair, whose value is the
    "jinglepub identifier".</p>

    <example caption='Jingle Action: IRI/URI'><![CDATA[
xmpp:files.montague.net?jingle;id=9559976B-3FBF-4E7E-B457-2DAA225972BB]]></example>

    <p>The information found in such an URI, an XMPP address and a
    "jinglepub identifier", can be used to trigger an an Jingle
    session initation request as specified in <cite>§ 2.2</cite>. This
    Jingle session can be used to transfer files (&xep0234;), audio
    and video streams (&xep0167;) and other Jingle application
    formats.</p>

  </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>
  <section2 topic='XMPP URI/IRI Querytype registration' anchor='uri-iri-registration'>
    <p>As authorized by &xep0147;, the XMPP Registrar maintains a
    registry of queries and key-value pairs for use in XMPP URIs (see
    &QUERYTYPES;).The following submission registers the 'jingle'
    querytype.</p>

    <code><![CDATA[
<querytype>
  <name>jingle</name>
  <proto>urn:xmpp:jinglepub:1</proto>
  <desc>enables retrieving Jingle sessions (file transfer, etc.)</desc>
  <doc>XEP-0358</doc>
  <keys/>
    <key>
      <name>id</name>
      <desc>The 'jinglepub' identifier</desc>
    </key>
  <keys/>
</querytype>]]></code>

  </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:all>
        <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
        <xs:element name='meta' type='metaElementType' minOccurs='0' maxOccurs='unbounded' />
        <xs:element name='uri' type='xs:anyURI' minOccurs='0' maxOccurs='1' />
      </xs:all>
      <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>