mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-13 21:05:09 -05:00
0d8970d298
Fix example description and attribute name of 'parameter' element as specified by XML schema
360 lines
12 KiB
XML
360 lines
12 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>Jingle RTP Header Extensions Negotiation</title>
|
|
<abstract>This specification defines an XMPP extension to negotiate
|
|
the use of the use of RTP Header Extension as defined by RFC 8285
|
|
with Jingle RTP sessions</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0294</number>
|
|
<status>Draft</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<approver>Council</approver>
|
|
<dependencies>
|
|
<spec>XEP-0167</spec>
|
|
<spec>RFC 8285</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>NOT_YET_ASSIGNED</shortname>
|
|
<schemaloc>
|
|
<url>http://xmpp.org/schemas/jingle-apps-rtp-rtp-hdrext.xsd</url>
|
|
</schemaloc>
|
|
<discuss>jingle</discuss>
|
|
<author>
|
|
<firstname>Olivier</firstname>
|
|
<surname>Crête</surname>
|
|
<email>olivier.crete@collabora.co.uk</email>
|
|
<jid>olivier.crete@collabora.co.uk</jid>
|
|
</author>
|
|
<revision>
|
|
<version>1.1.2</version>
|
|
<date>2022-08-27</date>
|
|
<initials>melvo</initials>
|
|
<remark>Fix example description and attribute name of 'parameter' element as specified by XML schema</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.1.1</version>
|
|
<date>2021-10-23</date>
|
|
<initials>egp</initials>
|
|
<remark><p>Strenghten the restriction on the 'id' attribute in the schema by making it xs:unsignedShort.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.1</version>
|
|
<date>2021-03-28</date>
|
|
<initials>ph</initials>
|
|
<remark><p>Add mapping for a=extmap-allow-mixed</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.0</version>
|
|
<date>2015-08-11</date>
|
|
<initials>XEP Editor (mam)</initials>
|
|
<remark><p>Advanced to Draft per a vote of the XMPP Council.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.2</version>
|
|
<date>2015-03-25</date>
|
|
<initials>ph</initials>
|
|
<remark><p>Added XML Schema; Updated based on last call feedback.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1</version>
|
|
<date>2011-03-24</date>
|
|
<initials>psa</initials>
|
|
<remark><p>Initial published version.</p></remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.1</version>
|
|
<date>2011-01-10</date>
|
|
<initials>oc</initials>
|
|
<remark><p>First draft.</p></remark>
|
|
</revision>
|
|
</header>
|
|
|
|
<section1 topic='Introduction' anchor='introduction'>
|
|
<p>This documents specifies how to negotiate the use of the RTP
|
|
Header Extensions as defined by &rfc8285; with Jingle RTP
|
|
sessions.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Requirements' anchor='requirements'>
|
|
<p>The Jingle extension defined herein is designed to meet the following requirements:</p>
|
|
<ol>
|
|
<li>Enable negotiations of the RTP Header extensions as defined in
|
|
<cite>RFC 8285</cite>.</li>
|
|
<li>Map these parameters to Session Description Protocol (SDP; see
|
|
&rfc4566;) to enable interoperability.</li>
|
|
</ol>
|
|
</section1>
|
|
|
|
<section1 topic='New elements' anchor='element'>
|
|
<p>This specification defines a new element, <rtp-hdrext/>,
|
|
that can be inserted in the <description/> element of a
|
|
XEP-0167 RTP session.</p>
|
|
|
|
<p>The attributes of the <rtp-hdrext/> element are:</p>
|
|
<table caption='rtp-hdrext attributes'>
|
|
<tr>
|
|
<th>Attribute</th>
|
|
<th>Description</th>
|
|
<th>Inclusion</th>
|
|
<th>Possible values</th>
|
|
</tr>
|
|
<tr>
|
|
<td>id</td>
|
|
<td>The ID of the extensions</td>
|
|
<td>REQUIRED</td>
|
|
<td>1-256, 4096-4351</td>
|
|
</tr>
|
|
<tr>
|
|
<td>uri</td>
|
|
<td>The URI that defines the extension</td>
|
|
<td>REQUIRED</td>
|
|
<td>Any valid URI</td>
|
|
</tr>
|
|
<tr>
|
|
<td>senders</td>
|
|
<td>Which party is allowed to send the negotiated RTP Header Extensions</td>
|
|
<td>OPTIONAL (defaults to "both")</td>
|
|
<td>"initiator", "responder", and "both"</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>Any type of RTP Header Extension that requires extra
|
|
parameters in the a=b form can embed <parameter/> elements to
|
|
describe it. Any other form of parameter can be stored as the 'name' attribute in a parameter element with an empty value.</p>
|
|
|
|
<p>This specification defines a new element, <extmap-allow-mixed/>,
|
|
that can be inserted in the <description/> element of a
|
|
XEP-0167 RTP session. The element has no attributes.</p>
|
|
|
|
</section1>
|
|
|
|
<section1 topic='Negotiation' anchor='negotiation'>
|
|
<p>RTP header extensions are negotiated along the codecs. They
|
|
follow the same Offer/Answer mechanism based on SDP
|
|
Offer/Answer. The initiator signals which RTP header extensions it
|
|
wants to send or receive in the the <session-initiate/> iq
|
|
stanza. If the responder does not understand the type of header
|
|
extensions, it MUST remove the element from the reply. If the
|
|
responder does not wish to provide or receive some kind of RTP
|
|
header extension, it MUST remove the relevant element from the
|
|
reply. It MUST then send the remaining elements it wants to keep
|
|
as-is without modifying them in the <session-accept/> iq
|
|
stanza.</p>
|
|
|
|
<p> It MUST NOT add any <rtp-hdrext/> element that was not
|
|
offered by the initiator. The responder MAY downgrade the senders
|
|
field from "both" to "initator" or "responder", but MUST NOT modify it
|
|
if it is "initator" or "responder".</p>
|
|
|
|
<p>The usage of the <extmap-allow-mixed/> is governed by the
|
|
SDP Offer/Answer mechanism as well.</p>
|
|
|
|
<p>Example negotiation where the initiator offers to use the
|
|
timestamp offset header extension as defined in &rfc5450; and also
|
|
the requests synchronisation metadata header extension (&rfc6051;)
|
|
with either the 56-bit or the 64-bit format.</p>
|
|
|
|
<example caption='Initiator sends description inside session-initiate'>
|
|
<![CDATA[
|
|
<description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
|
|
<rtp-hdrext xmlns='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'
|
|
uri='urn:ietf:params:rtp-hdrext:toffset'
|
|
id='1'/>
|
|
<rtp-hdrext xmlns='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'
|
|
uri='urn:ietf:params:rtp-hdrext:ntp-64'
|
|
id='4907'/>
|
|
<rtp-hdrext xmlns='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'
|
|
uri='urn:ietf:params:rtp-hdrext:ntp-56'
|
|
id='4907'/>
|
|
<payload-type id='96' name='THEORA' clockrate='90000'/>
|
|
<extmap-allow-mixed xmlns='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'/>
|
|
</description>
|
|
]]></example>
|
|
|
|
<p>Example reply where the responder accepts the timestamp offset
|
|
and the 56-bit synchronisation metadata header extensions as well as the
|
|
<extmap-allow-mixed/>.</p>
|
|
|
|
<example caption='Reponder sends description inside session-accept'><![CDATA[
|
|
<description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
|
|
<rtp-hdrext xmlns='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'
|
|
uri='urn:ietf:params:rtp-hdrext:toffset'
|
|
id='1'/>
|
|
<rtp-hdrext xmlns='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'
|
|
uri='urn:ietf:params:rtp-hdrext:ntp-56'
|
|
id='2'/>
|
|
<payload-type id='96' name='THEORA' clockrate='90000'/>
|
|
</description>
|
|
]]></example>
|
|
|
|
<p>Another reply to the same request where the responder accepts only the synchronisation data header extension with the 64-bit format.</p>
|
|
|
|
<example caption='Responder sends description inside session-accept with only the synchronisation data accepted'><![CDATA[
|
|
<description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
|
|
<rtp-hdrext xmlns='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'
|
|
uri='urn:ietf:params:rtp-hdrext:ntp-64'
|
|
id='2'/>
|
|
<payload-type id='96' name='THEORA' clockrate='90000'/>
|
|
</description>
|
|
]]></example>
|
|
</section1>
|
|
|
|
<section1 topic='Mapping to Session Description Protocol' anchor='sdp-mapping'>
|
|
<p>The <rtp-hdrext/> element maps to the "a:extmap=" SDP line
|
|
defined in <cite>RFC 8285</cite>. The ID is mapped to the 'id' attribute, the
|
|
direction to the 'senders' attribute and the URI to the 'uri'
|
|
attribute.</p>
|
|
|
|
<p>The <extmap-allow-mixed/> element maps to the "a=extmap-allow-mixed" SDP line
|
|
defined in <cite>RFC 8285</cite>. Note that a session-level line might need to be mapped
|
|
to all <description/> elements.</p>
|
|
|
|
<p>Example conversion of an incomplete SDP sample fragment taken from <cite>RFC 8285</cite> section 7 into equivalent XMPP:</p>
|
|
<example caption='SDP fragment'><![CDATA[
|
|
m=video
|
|
a=sendrecv
|
|
a=extmap:1 URI-toffset
|
|
a=extmap:2/recvonly URI-gps-string
|
|
a=extmap:3 URI-frametype
|
|
a=extmap-allow-mixed
|
|
]]></example>
|
|
<example caption='The same description in XMPP format'><![CDATA[
|
|
<description xmlns='urn:xmpp:jingle:apps:rtp:1' media='video'>
|
|
<rtp-hdrext xmlns='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'
|
|
id='1'
|
|
uri='URI-toffset'/>
|
|
<rtp-hdrext xmlns='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'
|
|
id='2'
|
|
uri='URI-gps-string'
|
|
senders='initiator'/>
|
|
<rtp-hdrext xmlns='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'
|
|
id='3'
|
|
uri='URI-frametype'/>
|
|
<extmap-allow-mixed xmlns='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'/>
|
|
</description>
|
|
]]></example>
|
|
</section1>
|
|
|
|
<section1 topic='Determining support' anchor='determining-support'>
|
|
<p>To advertise its support for Generic Header extensions in Jingle
|
|
RTP Sessions, when replying to &xep0030; information requests an
|
|
entity MUST return the following features:</p>
|
|
|
|
<ol>
|
|
<li>URNs for any version of this protocol that the entity
|
|
supports -- e.g., "urn:xmpp:jingle:apps:rtp:rtp-hdrext:0" for the
|
|
current version</li>
|
|
</ol>
|
|
|
|
<p>An example follows:</p>
|
|
|
|
<example caption="Service discovery information request"><![CDATA[
|
|
<iq from='romeo@montague.lit/orchard'
|
|
id='bh3vd715'
|
|
to='juliet@capulet.lit/balcony'
|
|
type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]></example>
|
|
|
|
<example caption="Service discovery information response"><![CDATA[
|
|
<iq from='juliet@capulet.lit/balcony'
|
|
id='bh3vd715'
|
|
to='romeo@montague.lit/orchard'
|
|
type='result'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
<feature var='urn:xmpp:jingle:1'/>
|
|
<feature var='urn:xmpp:jingle:apps:rtp:1'/>
|
|
<feature var='urn:xmpp:jingle:apps:rtp:video'/>
|
|
<feature var='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section1>
|
|
|
|
<section1 topic='IANA Considerations' anchor='iana-considerations'>
|
|
<p>This document requires no interaction with the Internet Assigned
|
|
Numbers Authority (IANA).</p>
|
|
</section1>
|
|
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
|
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
|
|
<p>This specification defines the following XML namespaces:</p>
|
|
<ul>
|
|
<li>urn:xmpp:jingle:apps:rtp:rtp-hdrext:0</li>
|
|
</ul>
|
|
<p>The ®ISTRAR; includes the foregoing namespaces in its
|
|
registry at &NAMESPACES;, as governed by &xep0053;.</p>
|
|
</section2>
|
|
<section2 topic='Namespace Versioning' anchor='registrar-versioning'>
|
|
&NSVER;
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='XML Schemas'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'
|
|
xmlns='urn:xmpp:jingle:apps:rtp:rtp-hdrext:0'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
The protocol documented by this schema is defined in
|
|
XEP-0294: http://www.xmpp.org/extensions/xep-0294.html
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
|
|
<xs:element name='rtp-hdrext'>
|
|
<xs:complexType>
|
|
<xs:sequence>
|
|
<xs:element name='parameter'
|
|
type='parameterElementType'
|
|
minOccurs='0'
|
|
maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='id' type='xs:unsignedShort' use='required'/>
|
|
<xs:attribute name='uri' type='xs:string' use='required'/>
|
|
<xs:attribute name='senders'
|
|
use='optional'
|
|
default='both'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='both'/>
|
|
<xs:enumeration value='initiator'/>
|
|
<xs:enumeration value='none'/>
|
|
<xs:enumeration value='responder'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:complexType name='parameterElementType'>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='name' type='xs:string' use='required'/>
|
|
<xs:attribute name='value' type='xs:string' use='optional'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section1>
|
|
<section1 topic='Acknowledgements' anchor='ack'>
|
|
<p>Thanks to Youness Alaoui for his feedback.</p>
|
|
</section1>
|
|
|
|
</xep>
|