moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-24 10:12:19 -05:00
Code Issues Releases Wiki Activity

0.4

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2744 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2009-02-17 22:30:57 +00:00
parent 06b80d08c2
commit 6513b38c17
1 changed files with 86 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
xep-0215.xml
View File

@ -10,7 +10,7 @@
<abstract>This document specifies an XMPP protocol extension for discovering services external to the XMPP network.</abstract> <abstract>This document specifies an XMPP protocol extension for discovering services external to the XMPP network.</abstract>
&LEGALNOTICE; &LEGALNOTICE;
<number>0215</number> <number>0215</number>
<status>Deferred</status> <status>Experimental</status>
<type>Standards Track</type> <type>Standards Track</type>
<sig>Standards</sig> <sig>Standards</sig>
<approver>Council</approver> <approver>Council</approver>
@ -19,9 +19,21 @@
</dependencies> </dependencies>
<supersedes/> <supersedes/>
<supersededby/> <supersededby/>
<shortname>NOT YET ASSIGNED</shortname> <shortname>extdisco</shortname>
&stpeter; &stpeter;
&seanegan; &seanegan;
<author>
<firstname>Marcus</firstname>
<surname>Lundblad</surname>
<email>ml@update.uu.se</email>
<jid>mlundblad@jabber.org</jid>
</author>
<revision>
<version>0.4</version>
<date>2009-02-17</date>
<initials>psa/ml</initials>
<remark><p>Revived the spec by popular demand; updated namespace to use XMPP URN; defined registry process and several initial entries.</p></remark>
</revision>
<revision> <revision>
<version>0.3</version> <version>0.3</version>
<date>2007-08-30</date> <date>2007-08-30</date>
@ -92,7 +104,7 @@
</section1> </section1>
<section1 topic='Protocol' anchor='protocol'> <section1 topic='Protocol' anchor='protocol'>
<p>In order to learn about external services known to an XMPP server or discovery service, a requesting entity (typically a client) sends an IQ-get containing an empty &lt;services/&gt; element qualified by the 'http://www.xmpp.org/extensions/xep-0215.html#ns' namespace &NSNOTE;, typically to its own server but perhaps alternatively to a dedicated discovery service.</p> <p>In order to learn about external services known to an XMPP server or discovery service, a requesting entity (typically a client) sends an IQ-get containing an empty &lt;services/&gt; element qualified by the 'urn:xmpp:extdisco:0' namespace &NSNOTE;, typically to its own server but perhaps alternatively to a dedicated discovery service.</p>
<p>The responding entity (XMPP server or discovery service) SHOULD return the list of external services it is aware of, but MAY instead return an appropriate error, such as &unavailable; if the responding entity does not support this protocol or &forbidden; if the requesting entity does not have permission to receive the list of external services. Each service is encapsulated via a &lt;service/&gt; element.</p> <p>The responding entity (XMPP server or discovery service) SHOULD return the list of external services it is aware of, but MAY instead return an appropriate error, such as &unavailable; if the responding entity does not support this protocol or &forbidden; if the requesting entity does not have permission to receive the list of external services. Each service is encapsulated via a &lt;service/&gt; element.</p>
<p>Note: The processes by which a responding entity discovers external services for "proxying" to XMPP entities are out of scope for this specification.</p> <p>Note: The processes by which a responding entity discovers external services for "proxying" to XMPP entities are out of scope for this specification.</p>
<p>The &lt;service/&gt; element MAY be empty or MAY include extended information about the service as described in the <link url='#extended'>Extended Information</link> section of this document.</p> <p>The &lt;service/&gt; element MAY be empty or MAY include extended information about the service as described in the <link url='#extended'>Extended Information</link> section of this document.</p>
@ -150,7 +162,7 @@
from='bard@shakespeare.lit/globe' from='bard@shakespeare.lit/globe'
to='shakespeare.lit' to='shakespeare.lit'
id='all1'> id='all1'>
<services xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'/> <services xmlns='urn:xmpp:extdisco:0'/>
</iq> </iq>
]]></example> ]]></example>
<example caption='XMPP Server Returns List'><![CDATA[ <example caption='XMPP Server Returns List'><![CDATA[
@ -158,18 +170,26 @@
from='shakespeare.lit' from='shakespeare.lit'
to='bard@shakespeare.lit/globe' to='bard@shakespeare.lit/globe'
id='all1'> id='all1'>
<services xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'> <services xmlns='urn:xmpp:extdisco:0'>
<service host='stun.shakespeare.lit' port='9998' transport='udp' type='stun'/>
<service host='stun.shakespeare.lit' <service host='stun.shakespeare.lit'
port='9998'
transport='udp'
type='stun'/>
<service host='relay.shakespeare.lit'
password='jj929jkj5sadjfj93v3n' password='jj929jkj5sadjfj93v3n'
port='9999' port='9999'
type='stun-relay' transport='udp'
type='turn'
username='nb78932lkjlskjfdb7g8'/> username='nb78932lkjlskjfdb7g8'/>
<service host='192.0.2.1' port='8888' transport='udp' type='stun'/> <service host='192.0.2.1'
port='8888'
transport='udp'
type='stun'/>
<service host='192.0.2.1' <service host='192.0.2.1'
port='8889' port='8889'
password='93jn3bakj9s832lrjbbz' password='93jn3bakj9s832lrjbbz'
type='stun-relay' transport='udp'
type='turn'
username='auu98sjl2wk3e9fjdsl7'/> username='auu98sjl2wk3e9fjdsl7'/>
<service host='ftp.shakespeare.lit' <service host='ftp.shakespeare.lit'
name='Shakespearean File Server' name='Shakespearean File Server'
@ -189,8 +209,7 @@
from='bard@shakespeare.lit/globe' from='bard@shakespeare.lit/globe'
to='shakespeare.lit' to='shakespeare.lit'
id='selected1'> id='selected1'>
<services xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns' <services xmlns='urn:xmpp:extdisco:0' type='turn'/>
type='stun-relay'/>
</iq> </iq>
]]></example> ]]></example>
<example caption='XMPP Server Returns List'><![CDATA[ <example caption='XMPP Server Returns List'><![CDATA[
@ -198,17 +217,19 @@
from='shakespeare.lit' from='shakespeare.lit'
to='bard@shakespeare.lit/globe' to='bard@shakespeare.lit/globe'
id='selected1'> id='selected1'>
<services xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns' <services xmlns='urn:xmpp:extdisco:0'
type='stun-relay'> type='turn'>
<service host='stun.shakespeare.lit' <service host='turn.shakespeare.lit'
password='jj929jkj5sadjfj93v3n' password='jj929jkj5sadjfj93v3n'
port='9999' port='9999'
type='stun-relay' transport='udp'
type='turn'
username='nb78932lkjlskjfdb7g8'/> username='nb78932lkjlskjfdb7g8'/>
<service host='192.0.2.1' <service host='192.0.2.1'
port='8889' port='8889'
password='93jn3bakj9s832lrjbbz' password='93jn3bakj9s832lrjbbz'
type='stun-relay' transport='udp'
type='turn'
username='auu98sjl2wk3e9fjdsl7'/> username='auu98sjl2wk3e9fjdsl7'/>
</services> </services>
</iq> </iq>
@ -219,14 +240,18 @@
from='shakespeare.lit' from='shakespeare.lit'
to='bard@shakespeare.lit/globe' to='bard@shakespeare.lit/globe'
id='push1'> id='push1'>
<services xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns' <services xmlns='urn:xmpp:extdisco:0'
type='stun-relay'> type='type'>
<server host='stun.shakespeare.lit' <server host='stun.shakespeare.lit'
port='9999' port='9999'
transport='udp'
type='turn'
username='1nas9dlm3hzl89d0b9v' username='1nas9dlm3hzl89d0b9v'
password='gh9023ljjdk109iajqn'> password='gh9023ljjdk109iajqn'>
<server host='192.0.2.2' <server host='192.0.2.2'
port='7778' port='7778'
transport='udp'
type='turn'
username='bnsv120afg48snsdozp' username='bnsv120afg48snsdozp'
password='zxp023na98dsfahn1kk'/> password='zxp023na98dsfahn1kk'/>
</services> </services>
@ -236,10 +261,10 @@
</section1> </section1>
<section1 topic='Extended Information' anchor='extended'> <section1 topic='Extended Information' anchor='extended'>
<p>If a server or service needs to include extended information, it SHOULD do so by including each bit of information as the XML character data of the &lt;value/&gt; child of a distinct &lt;field/&gt; element, with the entire set of fields contained within an &lt;x/&gt; element of type "result" qualified by the 'jabber:x:data' namespace (see &xep0004;); this &lt;x/&gt; element SHOULD be a child of the &lt;service/&gt; element qualified by the 'http://www.xmpp.org/extensions/xep-0215.html#ns' namespace &NSNOTE;. Thus the IQ result SHOULD be of the following form:</p> <p>If a server or service needs to include extended information, it SHOULD do so by including each bit of information as the XML character data of the &lt;value/&gt; child of a distinct &lt;field/&gt; element, with the entire set of fields contained within an &lt;x/&gt; element of type "result" qualified by the 'jabber:x:data' namespace (see &xep0004;); this &lt;x/&gt; element SHOULD be a child of the &lt;service/&gt; element qualified by the 'urn:xmpp:extdisco:0' namespace &NSNOTE;. Thus the IQ result SHOULD be of the following form:</p>
<code><![CDATA[ <code><![CDATA[
<iq type='result'> <iq type='result'>
<services xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns'> <services xmlns='urn:xmpp:extdisco:0'>
<service> <service>
<x type='result' xmlns='jabber:x:data'> <x type='result' xmlns='jabber:x:data'>
<field var='[var-name]' label='[optional]'> <field var='[var-name]' label='[optional]'>
@ -252,11 +277,11 @@
</iq>]]></code> </iq>]]></code>
<p>Note: A &lt;field/&gt; element MAY contain more than one &lt;value/&gt; child if appropriate.</p> <p>Note: A &lt;field/&gt; element MAY contain more than one &lt;value/&gt; child if appropriate.</p>
<p>If the data fields are to be used in the context of a protocol approved by the XMPP Standards Foundation, they SHOULD be registered in accordance with the rules defined in XEP-0068, resulting in the inclusion of a &lt;field/&gt; element whose 'var' attribute has a value of "FORM_TYPE" and whose 'type' attribute has a value of "hidden".</p> <p>If the data fields are to be used in the context of a protocol approved by the XMPP Standards Foundation, they SHOULD be registered in accordance with the rules defined in XEP-0068, resulting in the inclusion of a &lt;field/&gt; element whose 'var' attribute has a value of "FORM_TYPE" and whose 'type' attribute has a value of "hidden".</p>
<p>Note: Although &xep0128; specifies that an XMPP entity MUST NOT supply extended information about associated children communicated via the 'http://www.xmpp.org/extensions/xep-0215.html#ns' namespace, that rule does not apply to External Service Discovery since services external to the XMPP network cannot communicate via XMPP.</p> <p>Note: Although &xep0128; specifies that an XMPP entity MUST NOT supply extended information about associated children communicated via the 'urn:xmpp:extdisco:0' namespace, that rule does not apply to External Service Discovery since services external to the XMPP network cannot communicate via XMPP.</p>
</section1> </section1>
<section1 topic='Determining Support' anchor='disco'> <section1 topic='Determining Support' anchor='disco'>
<p>If an entity supports the STUN Server Discovery protocol, it MUST report that fact by including a service discovery feature of "http://www.xmpp.org/extensions/xep-0215.html#ns" &NSNOTE; in response to a &xep0030; information request:</p> <p>If an entity supports the STUN Server Discovery protocol, it MUST report that fact by including a service discovery feature of "urn:xmpp:extdisco:0" &NSNOTE; in response to a &xep0030; information request:</p>
<example caption="Service Discovery Information Request"><![CDATA[ <example caption="Service Discovery Information Request"><![CDATA[
<iq type='get' <iq type='get'
from='romeo@montague.lit/orchard' from='romeo@montague.lit/orchard'
@ -271,9 +296,7 @@
to='romeo@montague.lit/orchard' to='romeo@montague.lit/orchard'
id='disco1'> id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'> <query xmlns='http://jabber.org/protocol/disco#info'>
... <feature var='urn:xmpp:extdisco:0'/>
<feature var='http://www.xmpp.org/extensions/xep-0215.html#ns'/>
...
</query> </query>
</iq> </iq>
]]></example> ]]></example>
@ -288,11 +311,44 @@
</section1> </section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'> <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='ns'> <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>Until this specification advances to a status of Draft, its associated namespace shall be "http://www.xmpp.org/extensions/xep-0215.html#ns"; upon advancement of this specification, the XMPP Registrar shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</p> <p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:extdisco:1</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>
<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
&NSVER;
</section2> </section2>
<section2 topic='External Service Types Registry' anchor='registrar-services'> <section2 topic='External Service Types Registry' anchor='registrar-services'>
<p>The XMPP Registrar shall maintain a registry of external service types and their associated transport protocol(s). Such service types will probably be derived from the &ianaports;, defined DNS SRV record types, defined DDDS records for NAPTR, S-NAPTR, and U-NAPTR, and &ianaslp;. A future version of this specification shall define the relevant actions requested of the XMPP Registrar.</p> <p>The XMPP Registrar shall maintain a registry of external service types and their associated transport protocol(s). Such service types will probably be derived from the &ianaports;, defined DNS SRV record types, defined DDDS records for NAPTR, S-NAPTR, and U-NAPTR, and &ianaslp;.</p>
<section3 topic='Process' anchor='registrar-methods-process'>
&REGPROCESS;
<code><![CDATA[
<service>
<name>the XML character data of the service type</name>
<desc>a natural-language description of the service type</desc>
<doc>the document that best defines the service type</doc>
</service>
]]></code>
<p>The registrant may register more than one service type at a time, each contained in a separate &lt;service/&gt; element.</p>
</section3>
<section3 topic='Registration' anchor='registrar-methods-init'>
<code><![CDATA[
<service>
<name>stun</name>
<desc>a server that provides Session Traversal Utilities for NAT (STUN)</desc>
<doc>RFC 5389</doc>
</service>
<service>
<name>turn</name>
<desc>a server that provides Traversal Using Relays around NAT (TURN)</desc>
<doc>draft-ietf-behave-turn</doc>
</service>
]]></code>
</section3>
</section2> </section2>
</section1> </section1>
@ -302,8 +358,8 @@
<xs:schema <xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema' xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://www.xmpp.org/extensions/xep-0215.html#ns' targetNamespace='urn:xmpp:extdisco:0'
xmlns='http://www.xmpp.org/extensions/xep-0215.html#ns' xmlns='urn:xmpp:extdisco:0'
elementFormDefault='qualified'> elementFormDefault='qualified'>
<xs:import <xs:import