mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-24 10:12:19 -05:00
289 lines
13 KiB
XML
289 lines
13 KiB
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>xxxx</number>
|
|
<status>ProtoXEP</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.0.2</version>
|
|
<date>2014-08-12</date>
|
|
<initials>ls/psa/ph</initials>
|
|
<remark>
|
|
<ul>
|
|
<li>Changed payload to use one or more Jingle <description/> 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 <meta/> 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 <jinglepub/> 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 <jinglepub/> element is as follows:</p>
|
|
<example caption='Sample <jinglepub/>'><![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 <jinglepub/> element MUST contain a <description/> element qualified by the namespace of the relevant Jingle application format (e.g., <description xmlns='urn:xmpp:jingle:apps:file-transfer:4'/> for file transfer).</p>
|
|
<p>The <jinglepub/> element MAY contain one or more <meta/> 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 <jinglepub/> 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 <jinglepub/> 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 <start xmlns='urn:xmpp:jinglepub:1'/> 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 <starting/> 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 ¬acceptable; 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 ®ISTRAR; 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>
|