mirror of
https://github.com/moparisthebest/xeps
synced 2024-10-31 15:35:07 -04:00
29bee13867
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@320 4b5297f7-1745-476d-ba37-a9c6900126ab
1033 lines
56 KiB
XML
1033 lines
56 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>Service Discovery</title>
|
|
<abstract>This document defines an XMPP protocol extension for discovering (1) information about Jabber entities and (2) the items associated with such entities.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0030</number>
|
|
<status>Final</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
</dependencies>
|
|
<supersedes>
|
|
<spec>XEP-0011</spec>
|
|
<spec>XEP-0094</spec>
|
|
</supersedes>
|
|
<supersededby/>
|
|
<shortname>disco</shortname>
|
|
<schemaloc>
|
|
<ns>disco#info</ns>
|
|
<url>http://www.xmpp.org/schemas/disco-info.xsd</url>
|
|
</schemaloc>
|
|
<schemaloc>
|
|
<ns>disco#items</ns>
|
|
<url>http://www.xmpp.org/schemas/disco-items.xsd</url>
|
|
</schemaloc>
|
|
<registry/>
|
|
&hildjj;
|
|
&pgmillard;
|
|
&reatmon;
|
|
&stpeter;
|
|
<revision>
|
|
<version>2.2</version>
|
|
<date>2006-01-24</date>
|
|
<initials>psa</initials>
|
|
<remark>Further specified and clarified security considerations relating to server handling of requests sent to bare JIDs.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.1</version>
|
|
<date>2005-03-03</date>
|
|
<initials>psa</initials>
|
|
<remark>Added paragraph to implementation notes about server handling of requests sent to bare JIDs.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>2.0</version>
|
|
<date>2004-07-20</date>
|
|
<initials>psa</initials>
|
|
<remark>Per a vote of the Jabber Council, advanced status to Final.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.10</version>
|
|
<date>2004-06-29</date>
|
|
<initials>psa/jjh</initials>
|
|
<remark>Defined security considerations; changed extended presence example to use a fictitious protocol; further specified publish feature; defined registry submissions.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.9</version>
|
|
<date>2004-05-27</date>
|
|
<initials>psa</initials>
|
|
<remark>Clarified error conditions.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.8</version>
|
|
<date>2004-05-21</date>
|
|
<initials>psa</initials>
|
|
<remark>Moved remaining feature negotiation text to XEP-0020.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.7</version>
|
|
<date>2004-05-13</date>
|
|
<initials>psa</initials>
|
|
<remark>Added implementation note regarding flexibility of feature and item results; final editorial cleanup.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.6</version>
|
|
<date>2004-05-11</date>
|
|
<initials>psa</initials>
|
|
<remark>Corrected examples of publishing available items; further clarified nature of node hierarchies.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.5</version>
|
|
<date>2004-05-10</date>
|
|
<initials>psa</initials>
|
|
<remark>Added clarifying note about node hierarchies.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.4</version>
|
|
<date>2004-05-07</date>
|
|
<initials>psa</initials>
|
|
<remark>Clarified usage of "directory"; added section defining the relationship between an entity and its associated items.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.3</version>
|
|
<date>2004-04-23</date>
|
|
<initials>psa</initials>
|
|
<remark>Further clarified item-publication protocol; moved some feature negotiation text to XEP-0020; added information about registry of well-known service discovery nodes; added implementation notes regarding tree-walking and large result sets; incorporated additional Call for Experience suggestions.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.2</version>
|
|
<date>2004-04-20</date>
|
|
<initials>psa</initials>
|
|
<remark>Editorial cleanup; incorporated some Call for Experience suggestions.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.1</version>
|
|
<date>2004-03-15</date>
|
|
<initials>psa</initials>
|
|
<remark>Described requirements, syntax, and use cases in a more formal manner; corrected several errors in the examples and schemas; defined XMPP Registrar procedures; added a number of references; specified XMPP error handling.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>1.0</version>
|
|
<date>2003-04-21</date>
|
|
<initials>psa</initials>
|
|
<remark>Per a vote of the Jabber Council, advanced status to Draft; also added XML schemas.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.13</version>
|
|
<date>2003-02-25</date>
|
|
<initials>pgm</initials>
|
|
<remark>Added remarks about empty node attributes; described semantics regarding multiple identity elements.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.12</version>
|
|
<date>2003-02-06</date>
|
|
<initials>pgm</initials>
|
|
<remark>Added support for IQ-set; added example for disco#info to a specific node.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.11</version>
|
|
<date>2002-12-17</date>
|
|
<initials>psa</initials>
|
|
<remark>Added support for the 'node' attribute per discussion on the Standards list in order to support items that are not JID-addressable.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.10</version>
|
|
<date>2002-11-21</date>
|
|
<initials>psa</initials>
|
|
<remark>Changed <feature type='foo'/> to <feature var='foo'/> to track changes in feature negotiation (XEP-0020); added initial registry parameters.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.9</version>
|
|
<date>2002-11-07</date>
|
|
<initials>psa</initials>
|
|
<remark>Added support for empty result sets in disco#item.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.8</version>
|
|
<date>2002-11-01</date>
|
|
<initials>psa</initials>
|
|
<remark>Removed the max, start, and total attributes for item queries (this will be handled by a generic paging protocol); added "http://jabber.org/protocol/feature-neg" namespace as a feature to signal negotiability regarding one or more features.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.7</version>
|
|
<date>2002-10-28</date>
|
|
<initials>psa</initials>
|
|
<remark>Cleaned up the feature text and examples.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.6</version>
|
|
<date>2002-10-27</date>
|
|
<initials>psa</initials>
|
|
<remark>Added the 'category' attribute to the <feature/> element; added security, IANA, and XMPP Registrar considerations; added a number of examples.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.5</version>
|
|
<date>2002-10-15</date>
|
|
<initials>psa</initials>
|
|
<remark>Total overhaul and simplification.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.4</version>
|
|
<date>2002-07-16</date>
|
|
<initials>psa</initials>
|
|
<remark>Major additions and fixes, many more examples.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.3</version>
|
|
<date>2002-05-30</date>
|
|
<initials>psa</initials>
|
|
<remark>Re-organized around use cases, made some minor fixes.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.2</version>
|
|
<date>2002-05-05</date>
|
|
<initials>psa</initials>
|
|
<remark>Incorporated comments from co-authors and added notes.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1</version>
|
|
<date>2002-05-03</date>
|
|
<initials>psa</initials>
|
|
<remark>Initial draft.</remark>
|
|
</revision>
|
|
</header>
|
|
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<p>The ability to discover information about entities on the Jabber network is extremely valuable. Such information might include features offered or protocols supported by the entity, the entity's type or identity, and additional entities that are associated with the original entity in some way (often thought of as "children" of the "parent" entity). While mechanisms for doing so are not defined in &xmppcore;, several protocols have been used in the past within the Jabber community for service discovery, specifically &xep0011; and &xep0094;. However, those protocols are perceived to be inadequate for several reasons:</p>
|
|
<ol>
|
|
<li><p>Neither Jabber Browsing nor Agent Information is easily extensible. For example, the categories and subcategories listed for JID-Types in XEP-0011 are explicitly defined as the only official categories, and any additions to the list of JID-Types would require a modification to XEP-0011. While the Jabber Browsing specification does allow for the use of unofficial categories and types prefixed with the string 'x-', this introduces migration issues. This lack of flexibility violates one of the Jabber community's core &xep0134;.</p></li>
|
|
<li><p>In Agent Information, there is no way to advertise supported features. While Jabber Browsing includes such a mechanism, the only way to express the availability of a feature is to advertise a supported protocol namespace. Yet some features may not be uniquely associated with a protocol namespace, which are one implementation of features but not the only one.</p></li>
|
|
<li><p>A Jabber Browsing result returns a combination of (1) namespaces supported by a Jabber Entity, (2) items associated with a Jabber Entity, and (3) namespaces supported by the associated items. This approach mixes information levels and requires parents to know everything about child nodes, thereby introducing significant confusion.</p></li>
|
|
<li><p>In both Jabber Browsing and Agent Information, items must be addressable as JIDs; however, this may not be possible in some applications.</p></li>
|
|
</ol>
|
|
<p>This document addresses the perceived weaknesses of both the Jabber Browsing and Agent Information protocols. The result is a standards-track protocol for service discovery (often abbreviated to "disco", as is familiar in protocols such as &w3soap;).</p>
|
|
</section1>
|
|
|
|
<section1 topic='Requirements' anchor='reqs'>
|
|
<p>The authors have designed the service discovery protocol with the following requirements in mind:</p>
|
|
<ul>
|
|
<li><p>The protocol MUST support all functionality supported by the protocols it supersedes (Jabber Browsing and Agent Information).</p></li>
|
|
<li>
|
|
<p>There are three kinds of information that need to be discovered about an entity:</p>
|
|
<ol>
|
|
<li>its basic identity (type and/or category)</li>
|
|
<li>the features it offers and protocols it supports</li>
|
|
<li>any additional items associated with the entity, whether or not they are addressable as JIDs</li>
|
|
</ol>
|
|
<p>All three MUST be supported, but the first two kinds of information relate to the entity itself whereas the third kind of information relates to items associated with the entity itself; therefore two different query types are needed.</p>
|
|
</li>
|
|
<li><p>Discovering information about a child item MUST be accomplished by sending a separate discovery request to that item, not to the parent entity. (One result of this is that discovering complete information about an entire tree will require multiple request/response pairs in order to "walk the tree".)</p></li>
|
|
<li><p>The lists of identities and features MUST be flexible.</p></li>
|
|
<li><p>The protocol itself MUST be extensible.</p></li>
|
|
</ul>
|
|
</section1>
|
|
|
|
<section1 topic='Discovering Information About a Jabber Entity' anchor='info'>
|
|
<section2 topic='Basic Protocol' anchor='info-basic'>
|
|
<p>A requesting entity may want to discover information about another entity on the network. The information desired generally is of two kinds:</p>
|
|
<ol>
|
|
<li><p><strong>The target entity's identity.</strong> In disco, an entity's identity is broken down into its category (server, client, gateway, directory, etc.) and its particular type within that category (IM server, phone vs. handheld client, MSN gateway vs. AIM gateway, user directory vs. chatroom directory, etc.). This information helps requesting entities to determine the group or "bucket" of services into which the entity is most appropriately placed (e.g., perhaps the entity is shown in a GUI with an appropriate icon). An entity MAY have multiple identities. When multiple identity elements are provided, the name attributes for each identity element SHOULD have the same value.</p>
|
|
</li>
|
|
<li><p><strong>The features offered and protocols supported by the target entity.</strong> This information helps requesting entities determine what actions are possible with regard to this entity (registration, search, join, etc.), what protocols the entity supports, and specific feature types of interest, if any (e.g., for the purpose of feature negotiation).</p></li>
|
|
</ol>
|
|
<p>In order to discover such information, the requesting entity MUST send an IQ stanza of type "get", containing an empty <query/> element qualified by the 'http://jabber.org/protocol/disco#info' namespace, to the JID of the target entity (the 'to' address is REQUIRED and MUST contain a valid JID; a 'node' attribute on the &QUERY; element is OPTIONAL as described in the <link url="#info-nodes">Info Nodes</link> and <link url="#items-nodes">Items Nodes</link> section of this document):</p>
|
|
<example caption='Querying for information'><![CDATA[
|
|
<iq type='get'
|
|
from='romeo@montague.net/orchard'
|
|
to='plays.shakespeare.lit'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>The target entity then MUST either return an IQ result, or return an error (see the <link url="#errors">Error Conditions</link> section of this document). The result MUST contain a <query/> element qualified by the 'http://jabber.org/protocol/disco#info' namespace, which in turn contains one or more <identity/> elements and one or more <feature/> elements. (Note: Every entity MUST have at least one identity, and every entity MUST support at least the 'http://jabber.org/protocol/disco#info' feature; however, an entity is not required to return a result and MAY return an error, most likely &feature; or &unavailable;, although other error conditions may be appropriate.) Each <identity/> element MUST possess 'category' and 'type' attributes specifying the category and type for the entity, and MAY possess a 'name' attribute specifying a natural-language name for the entity. Each <feature/> element MUST possess a 'var' attribute whose value is a protocol namespace or other feature offered by the entity. Preferably, both the category/type values and the feature values will be registered in a public registry, as described in the <link url="#registrar">XMPP Registrar Considerations</link> section of this document.</p>
|
|
<example caption='Result-set for information request'><![CDATA[
|
|
<iq type='result'
|
|
from='plays.shakespeare.lit'
|
|
to='romeo@montague.net/orchard'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
<identity
|
|
category='conference'
|
|
type='text'
|
|
name='Play-Specific Chatrooms'/>
|
|
<identity
|
|
category='directory'
|
|
type='chatroom'
|
|
name='Play-Specific Chatrooms'/>
|
|
<feature var='http://jabber.org/protocol/disco#info'/>
|
|
<feature var='http://jabber.org/protocol/disco#items'/>
|
|
<feature var='http://jabber.org/protocol/muc'/>
|
|
<feature var='jabber:iq:register'/>
|
|
<feature var='jabber:iq:search'/>
|
|
<feature var='jabber:iq:time'/>
|
|
<feature var='jabber:iq:version'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the JID of the specified target entity does not exist, the server or other authoritative entity SHOULD return an ¬found; error, unless doing so would violate the privacy and security considerations specified in <strong>XMPP Core</strong> and &xmppim; or local privacy and security policies (see also the <link url='#security'>Security Considerations</link> of this document):</p>
|
|
<example caption='Target entity does not exist'><![CDATA[
|
|
<iq type='error'
|
|
from='plays.shakespeare.lit'
|
|
to='romeo@montague.net/orchard'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
<error code='404' type='cancel'>
|
|
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>If privacy and security considerations or policies prevent the server or other authoritative entity from returning an ¬found; error, it SHOULD return a &unavailable; error instead:</p>
|
|
<example caption='Service unavailable'><![CDATA[
|
|
<iq type='error'
|
|
from='plays.shakespeare.lit'
|
|
to='romeo@montague.net/orchard'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
<error code='503' type='cancel'>
|
|
<service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>When an entity sends a disco#info request to a bare JID (<account@domain.tld>) hosted by a server, the server itself MUST reply on behalf of the hosted account, either with an IQ-error or an IQ-result. For important rules regarding access to this functionality, see the <link url='#security'>Security Considerations</link> section of this document. In particular, in response to a disco#info request sent to a bare JID with no node, if access is not denied the server SHOULD return an IQ-result for the bare JID, in which the primary identity SHOULD have a category of "account" with an appropriate type as specified in the Service Discovery Identities registry (most likely, a type of "registered"). Note: This enables authorized or trusted entities to discover whether the account exists and its account type (e.g., in IM systems to determine the existence of an account before adding it to a contact's roster).</p>
|
|
<example caption='Requesting info from a bare JID'><![CDATA[
|
|
<iq type='get'
|
|
from='shakespeare.lit'
|
|
to='juliet@capulet.com'
|
|
id='info2'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>Here we assume that shakespeare.lit is trusted by capulet.com and that the account <juliet@capulet.com> is a registered account:</p>
|
|
<example caption='Server replies on behalf of bare JID'><![CDATA[
|
|
<iq type='result'
|
|
from='juliet@capulet.com'
|
|
to='shakespeare.lit'
|
|
id='info2'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
<identity category='account' type='registered'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>A query sent to an associated entity may result in different or more detailed information. One example is sending a query to a particular conference room rather than the parent conference service:</p>
|
|
<example caption='Querying a specific conference room'><![CDATA[
|
|
<iq type='get'
|
|
from='juliet@capulet.com/balcony'
|
|
to='balconyscene@plays.shakespeare.lit'
|
|
id='info3'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='balconyscene@plays.shakespeare.lit'
|
|
to='juliet@capulet.com/balcony'
|
|
id='info3'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
<identity
|
|
category='conference'
|
|
type='text'
|
|
name='Romeo and Juliet, Act II, Scene II'/>
|
|
<feature var='http://jabber.org/protocol/disco#info'/>
|
|
<feature var='http://jabber.org/protocol/muc'/>
|
|
<feature var='http://jabber.org/protocol/feature-neg'/>
|
|
<feature var='muc-password'/>
|
|
<feature var='muc-hidden'/>
|
|
<feature var='muc-temporary'/>
|
|
<feature var='muc-open'/>
|
|
<feature var='muc-unmoderated'/>
|
|
<feature var='muc-nonanonymous'/>
|
|
</query>
|
|
</iq>]]></example>
|
|
<p>Another example of this is sending a query to a specific connected resource for an IM user:</p>
|
|
<example caption='Querying a connected resource for further information'><![CDATA[
|
|
<iq type='get'
|
|
from='juliet@capulet.com/balcony'
|
|
to='romeo@montague.net/orchard'
|
|
id='info4'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
|
|
<iq type='result'
|
|
from='romeo@montague.net/orchard'
|
|
to='juliet@capulet.com/balcony'
|
|
id='info4'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
<identity
|
|
category='client'
|
|
type='pc'
|
|
name='Gabber'/>
|
|
<feature var='jabber:iq:time'/>
|
|
<feature var='jabber:iq:version'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='Info Nodes' anchor='info-nodes'>
|
|
<p>A disco#info query MAY also be directed to a specific node identifier associated with a JID, although the primary use of nodes is as <link url='#items-nodes'>Items Nodes</link> rather than as info nodes:</p>
|
|
<example caption='Querying a specific JID and node combination'><![CDATA[
|
|
<iq type='get'
|
|
from='romeo@montague.net/orchard'
|
|
to='mim.shakespeare.lit'
|
|
id='info3'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='http://jabber.org/protocol/commands'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='JID+node result'><![CDATA[
|
|
<iq type='result'
|
|
from='mim.shakespeare.lit'
|
|
to='romeo@montague.net/orchard'
|
|
id='info3'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='http://jabber.org/protocol/commands'>
|
|
<identity
|
|
category='automation'
|
|
type='command-list'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Discovering the Items Associated with a Jabber Entity' anchor='items'>
|
|
<section2 topic='Basic Protocol' anchor='items-basic'>
|
|
<p>In order for the requesting entity to discover the items associated with a Jabber Entity, it MUST send an IQ stanza of type "get" to the target entity, containing an empty <query/> element qualified by the 'http://jabber.org/protocol/disco#items' namespace:</p>
|
|
<example caption='Requesting all items'><![CDATA[
|
|
<iq type='get'
|
|
from='romeo@montague.net/orchard'
|
|
to='shakespeare.lit'
|
|
id='items1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>The target entity then MUST either return its list of publicly-available items, or return an error. The list of items MUST be provided in an IQ stanza of type "result", with each item specified by means of an <item/> child of a <query/> element qualified by the 'http://jabber.org/protocol/disco#items' namespace (the <item/> child MUST possess a 'jid' attribute specifying the JID of the item and MAY possess a 'name' attribute specifying a natural-language name for the item):</p>
|
|
<example caption='Result-set for all items'><![CDATA[
|
|
<iq type='result'
|
|
from='shakespeare.lit'
|
|
to='romeo@montague.net/orchard'
|
|
id='items1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'>
|
|
<item jid='people.shakespeare.lit'
|
|
name='Directory of Characters'/>
|
|
<item jid='plays.shakespeare.lit'
|
|
name='Play-Specific Chatrooms'/>
|
|
<item jid='mim.shakespeare.lit'
|
|
name='Gateway to Marlowe IM'/>
|
|
<item jid='words.shakespeare.lit'
|
|
name='Shakespearean Lexicon'/>
|
|
<item jid='globe.shakespeare.lit'
|
|
name='Calendar of Performances'/>
|
|
<item jid='headlines.shakespeare.lit'
|
|
name='Latest Shakespearean News'/>
|
|
<item jid='catalog.shakespeare.lit'
|
|
name='Buy Shakespeare Stuff!'/>
|
|
<item jid='en2fr.shakespeare.lit'
|
|
name='French Translation Service'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>The <item/> element MUST NOT contain XML character data and SHOULD be empty; while it MAY contain XML data in another namespace, such data MUST be ignored if an implementation does not understand it.</p>
|
|
<p>If there are no items associated with an entity (or if those items are not publicly available), the target entity MUST return an empty query element to the requesting entity:</p>
|
|
<example caption='Empty result set'><![CDATA[
|
|
<iq type='result'
|
|
from='shakespeare.lit'
|
|
to='romeo@montague.net/orchard'
|
|
id='items1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>As with disco#info requests, when an entity sends a disco#items request to a bare JID (<account@domain.tld>) hosted by a server, the server itself MUST reply on behalf of the hosted account. For important rules regarding access to this functionality, see the <link url='#security'>Security Considerations</link> section of this document. In particular, in response to a disco#items request sent to a bare JID with no node, if access is not denied the server SHOULD return the associated items including connected or available resources as appropriate:</p>
|
|
<example caption='Requesting items from a bare JID'><![CDATA[
|
|
<iq type='get'
|
|
from='shakespeare.lit'
|
|
to='juliet@capulet.com'
|
|
id='items2'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>Here we assume that shakespeare.lit is trusted by capulet.com and that the account <juliet@capulet.com> has two available resources:</p>
|
|
<example caption='Server replies on behalf of bare JID'><![CDATA[
|
|
<iq type='result'
|
|
from='juliet@capulet.com'
|
|
to='shakespeare.lit'
|
|
id='items2'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'>
|
|
<item jid='juliet@capulet.com/balcony'/>
|
|
<item jid='juliet@capulet.com/chamber'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='Items Nodes' anchor='items-nodes'>
|
|
<p>It is possible that an item associated with an entity will not be addressable as a JID; examples might include offline messages stored in an inbox (see &xep0013;), entries in a Jabber-enabled weblog, XML-RPC services associated with a client or component, items available in an online trading system (e.g., a catalog or auction), news postings located at an NNTP gateway, and topics hosted by a &xep0060; component. In order to handle such items, the <item/> element MAY possess an OPTIONAL 'node' attribute that supplements the REQUIRED 'jid' attribute.</p>
|
|
<p>The value of the node attribute may or may not have semantic meaning; from the perspective of Service Discovery, a node is merely something that is associated with an entity. In order to discover more about the node, the requesting entity MUST query the entity's JID while specifying the node. If the value of the 'node' attribute has semantic meaning, that meaning is provided by the using protocol or application, not by the Service Discovery protocol. A node attribute SHOULD NOT be included unless it is necessary to provide or discover information about an entity that cannot be directly addressed as a JID (i.e., if the associated item can be addressed as a JID, do not include a node). The value of the 'node' attribute MUST NOT be null.</p>
|
|
<p>In the following example, a user requests all available items from an online catalog service:</p>
|
|
<example caption='Requesting nodes'><![CDATA[
|
|
<iq type='get'
|
|
from='romeo@montague.net/orchard'
|
|
to='catalog.shakespeare.lit'
|
|
id='items2'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>If there are items associated with the target entity but they are not addressable as JIDs, the service SHOULD then return a list of nodes (where each <item/> element MUST possess a 'jid' attribute, SHOULD possess a 'node' attribute, and MAY possess a 'name' attribute):</p>
|
|
<example caption='Service returns nodes'><![CDATA[
|
|
<iq type='result'
|
|
from='catalog.shakespeare.lit'
|
|
to='romeo@montague.net/orchard'
|
|
id='items2'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'>
|
|
<item jid='catalog.shakespeare.lit'
|
|
node='books'
|
|
name='Books by and about Shakespeare'/>
|
|
<item jid='catalog.shakespeare.lit'
|
|
node='clothing'
|
|
name='Wear your literary taste with pride'/>
|
|
<item jid='catalog.shakespeare.lit'
|
|
node='music'
|
|
name='Music from the time of Shakespeare'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>There may be futher nodes associated with the "first-level" nodes returned in the above query (e.g., the nodes may be categories that have associated items). The requesting entity can query a node further by sending a request to the JID and specifying the node of interest in the query.</p>
|
|
<example caption='Requesting further nodes'><![CDATA[
|
|
<iq type='get'
|
|
from='romeo@montague.net/orchard'
|
|
to='catalog.shakespeare.lit'
|
|
id='items3'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='music'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>The service then returns the further nodes associated with the "parent" node. In the following example, the service itself enforces an alphabetically-ordered hierarchical structure on the nodes that are returned, but such a structure is a matter of implementation rather than protocol.</p>
|
|
<example caption='Service returns further nodes'><![CDATA[
|
|
<iq type='result'
|
|
from='catalog.shakespeare.lit'
|
|
to='romeo@montague.net/orchard'
|
|
id='items3'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='music'>
|
|
<item jid='catalog.shakespeare.lit'
|
|
node='music/A'/>
|
|
<item jid='catalog.shakespeare.lit'
|
|
node='music/B'/>
|
|
<item jid='catalog.shakespeare.lit'
|
|
node='music/C'/>
|
|
<item jid='catalog.shakespeare.lit'
|
|
node='music/D'/>
|
|
.
|
|
.
|
|
.
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<p>The requesting entity can then query further if desired:</p>
|
|
<example caption='Requesting even more nodes'><![CDATA[
|
|
<iq type='get'
|
|
from='romeo@montague.net/orchard'
|
|
to='catalog.shakespeare.lit'
|
|
id='items4'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='music/D'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service returns even more nodes'><![CDATA[
|
|
<iq type='result'
|
|
from='catalog.shakespeare.lit'
|
|
to='romeo@montague.net/orchard'
|
|
id='items4'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='music/D'>
|
|
<item jid='catalog.shakespeare.lit'
|
|
node='music/D/dowland-firstbooke'
|
|
name='John Dowland - First Booke of Songes or Ayres'/>
|
|
<item jid='catalog.shakespeare.lit'
|
|
node='music/D/dowland-solace'
|
|
name='John Dowland - A Pilgrimes Solace'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
<section2 topic='Node Hierarchies' anchor='items-hierarchy'>
|
|
<p>The foregoing examples show a hierarchy of nodes, in which some nodes are branches (i.e., contain further nodes) and some nodes are leaves (i.e., do not contain further nodes). The "hierarchy" category SHOULD be used to identify such nodes, where the "branch" and "leaf" types are exhaustive of the types within this category.</p>
|
|
<p>If the hierarchy category is used, every node in the hierarchy MUST be identified as either a branch or a leaf; however, since a node MAY have multiple identities, any given node MAY also possess an identity other than "hierarchy/branch" or "hierarchy/leaf".</p>
|
|
<p>Therefore, a disco#info request to the "music/D" node shown above would yield <identity category='hierarchy' type='branch'/> while a disco#info request to the "music/D/dowland-firstbooke" node would yield <identity category='hierarchy' type='leaf'/> (and each node could yield additional identities as appropriate).</p>
|
|
</section2>
|
|
<section2 topic='Relationship Between an Entity and its Items' anchor='items-relationship'>
|
|
<p>This section explains in greater detail the relationship between an entity and its associated items.</p>
|
|
<p>In general, the items returned by an entity in a disco#items result MUST be items over which the entity has some relationship of ownership -- either direct control over the item itself (e.g., <strong>Publish-Subscribe</strong> nodes owned by the entity) or at least the ability to provide or vouch for the item in a canonical way on the Jabber network (e.g., groupchat rooms directly hosted by a multi-user chat service or IRC channels to which a gateway provides access).</p>
|
|
<p>Such a relationship does not constrain the relationship between the owning entity's address and the address of the associated entity. In particular, any of the following scenarios is perfectly acceptable:</p>
|
|
<ol>
|
|
<li><p>Upon querying an entity (JID1) for items, one receives a list of items that can be addressed as JIDs; each associated item has its own JID, but no such JID equals JID1.</p></li>
|
|
<li><p>Upon querying an entity (JID1) for items, one receives a list of items that cannot be addressed as JIDs; each associated item has its own JID+node, where each JID equals JID1 and each NodeID is unique.</p></li>
|
|
<li><p>Upon querying an entity (JID1+NodeID1) for items, one receives a list of items that can be addressed as JIDs; each associated item has its own JID, but no such JID equals JID1.</p></li>
|
|
<li><p>Upon querying an entity (JID1+NodeID1) for items, one receives a list of items that cannot be addressed as JIDs; each associated item has its own JID+node, but no such JID+node equals JID1+NodeID1 and each NodeID is unique in the context of the associated JID.</p></li>
|
|
</ol>
|
|
<p>In addition, the results MAY also be mixed, so that a query to a JID or a JID+node could yield both (1) items that are addressed as JIDs and (2) items that are addressed as JID+node combinations.</p>
|
|
<p>Consider the case of an entity that owns multiple publish-subscribe nodes -- for example, a person who owns one such node for each of his music players. The following examples show what the disco#items query and result might look like (using the protocol defined in &xep0118;):</p>
|
|
<example caption='User queries entity regarding tunes'><![CDATA[
|
|
<iq from='juliet@capulet.com/chamber'
|
|
id='items4'
|
|
to='romeo@montague.net'
|
|
type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='http://jabber.org/protocol/tune'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>The queried entity now returns a list of publish-subscribe nodes over which it has control, each of which is hosted on a different pubsub service:</p>
|
|
<example caption='Entity returns multiple items'><![CDATA[
|
|
<iq from='romeo@montague.net'
|
|
id='items4'
|
|
to='juliet@capulet.com/chamber'
|
|
type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='http://jabber.org/protocol/tune'>
|
|
<item jid='pubsub.shakespeare.lit'
|
|
name='Romeo's CD player'
|
|
node='s623nms9s3bfh8js'/>
|
|
<item jid='pubsub.montague.net'
|
|
node='music/R/Romeo/iPod'/>
|
|
<item jid='tunes.characters.lit'
|
|
node='g8k4kds9sd89djf3'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
</section1>
|
|
|
|
<section1 topic='Publishing Available Items' anchor='publish'>
|
|
<p>The server handling rules defined in <strong>XMPP IM</strong> require that the server itself reply on behalf of the user if the 'to' attribute of an IQ get or set is of the form <user@host>. This functionality is currently employed so that the user can "publish" information (e.g., vCard information as specified in &xep0054;) in a way that makes it possible for other entities to retrieve that information even if the user is unavailable. The service discovery specification defined herein builds on that notion by enabling a user to publish some of its service discovery information to the server, which shall store that information in persistent storage and return that information when other entities request it from the user's "bare JID" (user@host), either alone or in combination with a particular node.</p>
|
|
<p>Implementations of service discovery that are built into instant messaging servers SHOULD allow users to publish items in this fashion, although they are not required to do so in order to conform to the service discovery specification. In order to discover whether his or her server supports this publish functionality, the user SHOULD send a disco#info request to his or her server:</p>
|
|
<example caption="User sends disco#info request to server"><![CDATA[
|
|
<iq from='kinglear@shakespeare.lit'
|
|
id='pubinfo'
|
|
to='shakespeare.lit'
|
|
type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>If the server supports service discovery publishing and the server wishes to disclose that fact to the user, it MUST include a feature of 'http://jabber.org/protocol/disco#publish' in its response.</p>
|
|
<example caption="Server responds with identity and feature information"><![CDATA[
|
|
<iq from='shakespeare.lit'
|
|
id='pubinfo'
|
|
to='kinglear@shakespeare.lit'
|
|
type='result'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
<identity category='server' type='im'/>
|
|
...
|
|
<feature var='http://jabber.org/protocol/disco#publish'/>
|
|
...
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
|
|
<p>In order to publish items, an entity uses an IQ-set transaction to its server, which is responsible for responding to requests on behalf of that entity. Each <item/> child element of the parent query MUST possess the following attributes:</p>
|
|
<ul>
|
|
<li><strong>action</strong> -- specifies the action to be taken for the item</li>
|
|
<li><strong>jid</strong> -- specifies the Jabber ID of the item "owner" or location</li>
|
|
</ul>
|
|
<p>The <item/> element MAY also possess the following attributes:</p>
|
|
<ul>
|
|
<li><strong>name</strong> -- specifies a natural-language name for the item.</li>
|
|
<li><strong>node</strong> -- specifies the particular node associated with the JID of the item "owner" or location</li>
|
|
</ul>
|
|
<p>The allowable values for the 'action' attribute are "update" and "remove"). If the action is "update", the server MUST either create a new entry (if the node and jid combination does not already exist) or overwrite an existing entry. If the action is "remove", the item MUST be removed from persistent storage.</p>
|
|
<p>The following example shows a user publishing a list of his biological children to a well-known (but fictitious) service discovery node.</p>
|
|
<example caption='Publishing items'><![CDATA[
|
|
<iq from='kinglear@shakespeare.lit'
|
|
id='publish1'
|
|
type='set'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='jabber:iq:kids'>
|
|
<item action='update'
|
|
jid='cordelia@shakespeare.lit'
|
|
name='Cordelia'/>
|
|
<item action='update'
|
|
jid='goneril@shakespeare.lit'
|
|
name='Goneril'/>
|
|
<item action='update'
|
|
jid='regan@shakespeare.lit'
|
|
name='Regan'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
|
|
<example caption="Server responds with success"><![CDATA[
|
|
<iq id='publish1'
|
|
to='kinglear@shakespeare.lit'
|
|
type='result'/>
|
|
]]></example>
|
|
|
|
<p>Subsequent queries to "jid='kinglear@shakespeare.lit'" and "node='jabber:iq:kids'" will yield the list shown above (absent the 'action' attributes).</p>
|
|
|
|
<p>If the server or service does not support persistent storage, it MUST respond to IQ-set requests with a &feature; error.</p>
|
|
|
|
<example caption='Persistent storage is not available'><![CDATA[
|
|
<iq id='publish1'
|
|
to='kinglear@shakespeare.lit'
|
|
type='error'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='jabber:iq:kids'>
|
|
<item action='update'
|
|
jid='cordelia@shakespeare.lit'
|
|
name='Cordelia'/>
|
|
<item action='update'
|
|
jid='goneril@shakespeare.lit'
|
|
name='Goneril'/>
|
|
<item action='update'
|
|
jid='regan@shakespeare.lit'
|
|
name='Regan'/>
|
|
</query>
|
|
<error code='501' type='cancel'>
|
|
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
|
|
</section1>
|
|
|
|
<section1 topic='Implementation Notes' anchor='impl'>
|
|
<p>In order to retrieve full information about an entity and its associated items, the requesting application needs to "walk the tree" of items. Naturally, this can result in a large number of requests and responses. The requesting application SHOULD NOT send follow-up requests to all items associated with an entity if the list of such items is long (e.g., more than twenty items). Entities that will routinely host a large number of items (e.g., IRC gateways or NNTP services) SHOULD structure nodes into hierarchies and/or provide more robust searching capabilities, for example via &xep0055;; they SHOULD NOT return extremely large result sets via Service Discovery.</p>
|
|
<p>This document does not require that a responding entity must return the same results in response to the same request from different requesting entities (e.g., an entity could return a different list of items or features based on the degree to which it trusts the requesting entity, or based on the known capabilities of the requesting entity). However, the responding entity SHOULD return the same <identity/> element (category+type) to all disco#info requests sent to the same JID+node combination.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Error Conditions' anchor='errors'>
|
|
<p>If a specific entity (JID or JID+node) does not support the disco namespace, refuses to return disco results to the specific requesting entity, or refuses to return disco results to any requesting entity, it SHOULD return an appropriate error message (such as &unavailable;, &forbidden;, or ¬allowed;, respectively). One example is shown below.</p>
|
|
<example caption='JID+node error'><![CDATA[
|
|
<iq type='error'
|
|
from='mim.shakespeare.lit'
|
|
to='romeo@montague.net/orchard'
|
|
id='info3'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='http://jabber.org/protocol/commands'/>
|
|
<error code='405' type='cancel'>
|
|
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>Other error conditions may be appropriate depending on the application.</p>
|
|
<p>The following table summarizes the common error conditions that can have special meaning in the context of Service Discovery (for information regarding error condition syntax and semantics, see &xep0086;).</p>
|
|
<table caption='Error Conditions'>
|
|
<tr>
|
|
<th>Condition</th>
|
|
<th>Cause</th>
|
|
</tr>
|
|
<tr>
|
|
<td>&feature;</td>
|
|
<td>The sender has attempted to publish items but the server does not support the <link url="#publish">Publishing Available Items</link> feature.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>¬found;</td>
|
|
<td>The JID or JID+NodeID of the specified target entity does not exist and that fact can be divulged in accordance with privacy and security considerations and policies.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>&unavailable;</td>
|
|
<td>The target entity does not support this protocol, or the specified target entity does not exist but that fact cannot be divulged because of pricacy and security considerations.</td>
|
|
</tr>
|
|
</table>
|
|
<p>The other error conditions specified in <strong>XMPP Core</strong> MAY be returned as well (&forbidden;, ¬allowed;, ¬authorized;, etc.), including application-specific conditions.</p>
|
|
<p>As noted above, if an entity has no associated items, it MUST return an empty &QUERY; element (rather than an error) in response to a disco#items request.</p>
|
|
</section1>
|
|
|
|
<section1 topic='Security Considerations' anchor='security'>
|
|
<p>Certain attacks may be made easier when an entity discloses (via disco#info responses) that it supports particular protocols or features; however, in general, service discovery introduces no new vulnerabilities, since a malicious entity could discover that the responding entity supports such protocols and features by sending requests specific to those protocols rather than by sending service discovery requests.</p>
|
|
<p>A responding entity is under no obligation to return the identical service discovery response when replying to service discovery requests received from different requesting entities, and MAY perform authorization checks before responding in order to determine how (or whether) to respond.</p>
|
|
<p>A server MUST carefully control access to any functionality that would enable directory harvesting attacks or that would leak information about connected or available resources; this functionality consists of the server's replies to disco#info and disco#items requests sent to bare JIDs (addresses of the form account@domain.tld) hosted on the server, since the server responds to such requests on behalf of the account. The following rules apply to the handling of service discovery requests sent to bare JIDs:</p>
|
|
<ol>
|
|
<li>
|
|
<p>In response to a disco#info request, the server MUST return a &unavailable; error if one of the following is true:</p>
|
|
<ol>
|
|
<li>The target entity does not exist (no matter if the request specifies a node or not).</li>
|
|
<li>The requesting entity is not authorized to receive presence from the target entity (i.e., via a presence subscription of type "both" or "from") or is not otherwise trusted (e.g., another server in a trusted network).</li>
|
|
</ol>
|
|
</li>
|
|
<li>
|
|
<p>In response to a disco#items request, the server MUST return an empty result set if:</p>
|
|
<ol>
|
|
<li>The target entity does not exist (no matter if the request specifies a node or not).</li>
|
|
<li>The request did not specify a node, the only items are available resources (as defined in <cite>RFC 3921</cite>), and the requesting entity is not authorized to receive presence from the target entity (i.e., via a presence subscription of type "both" or "from") or is not otherwise trusted (e.g., another server in a trusted network). <note>However, the server MAY return items other than available resources (if any).</note></li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
</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-protocol'>
|
|
<p>The ®ISTRAR; includes the 'http://jabber.org/protocol/disco#info' and 'http://jabber.org/protocol/disco#items' namespaces in its registry of protocol namespaces.</p>
|
|
</section2>
|
|
<section2 topic='Registries' anchor='registrar-reg'>
|
|
<section3 topic='Identity Categories and Types Registry' anchor='registrar-reg-identity'>
|
|
<p>The XMPP Registrar maintains a registry of values for the 'category' and 'type' attributes of the <identity/> element in the 'http://jabber.org/protocol/disco#info' namespace; see &DISCOCATEGORIES;.</p>
|
|
<section4 topic='Process' anchor='registrar-identity'>
|
|
®PROCESS;
|
|
<code><![CDATA[
|
|
<category>
|
|
<name>the name of the category (all lower-case)</name>
|
|
<desc>a natural-language description of the category</desc>
|
|
<type>
|
|
<name>the name of the specific type (all lower-case)</name>
|
|
<desc>a natural-language description of the type</desc>
|
|
<doc>the document (e.g., XEP) in which this type is specified</doc>
|
|
</type>
|
|
</category>
|
|
]]></code>
|
|
<p>The registrant may register more than one category at a time, each contained in a separate <category/> element. The registrant may also register more than one type at a time, each contained in a separate <type/> child element. Registrations of new types within an existing category must include the full XML snippet but should not include the category description (only the name).</p>
|
|
</section4>
|
|
<section4 topic='Initial Submission' anchor='registrar-reg-identity-init'>
|
|
<p>This document defines a "hierarchy" category that contains two and only two types: "branch" and "leaf"; the associated registry submission is as follows:</p>
|
|
<code><![CDATA[
|
|
<category>
|
|
<name>hierarchy</name>
|
|
<desc>
|
|
An entity that exists in the context of a
|
|
service discovery node hierarchy.
|
|
</desc>
|
|
<type>
|
|
<name>branch</name>
|
|
<desc>
|
|
A "container node" for other entities in a
|
|
service discovery node hierarchy.
|
|
</desc>
|
|
<doc>XEP-0030</doc>
|
|
</type>
|
|
<type>
|
|
<name>leaf</name>
|
|
<desc>
|
|
A "terminal node" in a service discovery
|
|
node hierarchy.
|
|
</desc>
|
|
<doc>XEP-0030</doc>
|
|
</type>
|
|
</category>
|
|
]]></code>
|
|
</section4>
|
|
</section3>
|
|
<section3 topic='Features Registry' anchor='registrar-reg-features'>
|
|
<p>The XMPP Registrar maintains a registry of features for use as values of the 'var' attribute of the <feature/> element in the 'http://jabber.org/protocol/disco#info' namespace; see &DISCOFEATURES;.</p>
|
|
<section4 topic='Process' anchor='registrar-reg-features-process'>
|
|
®PROCESS;
|
|
<code><![CDATA[
|
|
<feature var='name of feature or namespace'>
|
|
<desc>a natural-language description of the feature</desc>
|
|
<doc>the document (e.g., XEP) in which this feature is specified</doc>
|
|
</feature>]]></code>
|
|
<p>The registrant may register more than one feature at a time, each contained in a separate <feature/> element.</p>
|
|
</section4>
|
|
<section4 topic='Initial Submission' anchor='registrar-reg-features-init'>
|
|
<p>This document defines a "publish" feature that is not associated with either of the protocol namespaces listed above; the registry submission for this feature is as follows:</p>
|
|
<code><![CDATA[
|
|
<feature var='http://jabber.org/protocol/disco#publish'>
|
|
<desc>the service discovery "publish" feature</desc>
|
|
<doc>XEP-0030</doc>
|
|
</feature>
|
|
]]></code>
|
|
</section4>
|
|
</section3>
|
|
<section3 topic='Well-Known Nodes' anchor='registrar-reg-nodes'>
|
|
<p>A using protocol may specify one or more service discovery nodes that have a special and well-defined meaning in the context of that protocol. For the purpose of reserving these node names globally across all Jabber protocols, the XMPP Registrar maintains a registry of well-known service discovery nodes at &DISCONODES;.</p>
|
|
<section4 topic='Process' anchor='registrar-reg-nodes-process'>
|
|
®PROCESS;
|
|
<code><![CDATA[
|
|
<node>
|
|
<name>the name of the node</name>
|
|
<desc>a natural-language description of the node</desc>
|
|
<doc>the document (e.g., XEP) in which this node is specified</doc>
|
|
</node>
|
|
]]></code>
|
|
<p>The registrant may register more than one node at a time, each contained in a separate <node/> element.</p>
|
|
</section4>
|
|
</section3>
|
|
</section2>
|
|
<section2 topic='URI Query Types' anchor='registrar-querytypes'>
|
|
<p>As authorized by &xep0147;, the XMPP Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).</p>
|
|
<p>The "disco" querytype is defined herein for service discovery interactions, with three keys: (1) "node" (the optional node to query), (2) "request" (with values of "info" to retrieve service discovery information and "items" to retrieve service discovery items), and (3) "type" (with values of "get" for IQ-gets and "set" for IQ-sets).</p>
|
|
<example caption='Service Discovery Information Request: IRI/URI'><![CDATA[
|
|
xmpp:romeo@montague.net?disco;type=get;request=info
|
|
]]></example>
|
|
<example caption='Service Discovery Information Request: Resulting Stanza'><![CDATA[
|
|
<iq to='romeo@montague.net' type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Service Discovery Items Request: IRI/URI'><![CDATA[
|
|
xmpp:romeo@montague.net?disco;type=get;request=items
|
|
]]></example>
|
|
<example caption='Service Discovery Items Request: Resulting Stanza'><![CDATA[
|
|
<iq to='romeo@montague.net' type='get'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'/>
|
|
</iq>
|
|
]]></example>
|
|
<p>The following submission registers the "disco" querytype.</p>
|
|
<code><![CDATA[
|
|
<querytype>
|
|
<name>disco</name>
|
|
<proto>http://jabber.org/protocol/disco</proto>
|
|
<desc>enables interaction for the purpose of service discovery</desc>
|
|
<doc>XEP-0030</doc>
|
|
<keys>
|
|
<key>
|
|
<name>node</name>
|
|
<desc>the (optional) service discovery node</desc>
|
|
</key>
|
|
<key>
|
|
<name>request</name>
|
|
<desc>the service discovery request type</desc>
|
|
<values>
|
|
<value>
|
|
<name>info</name>
|
|
<desc>a service discovery information (disco#info) request</desc>
|
|
</value>
|
|
<value>
|
|
<name>items</name>
|
|
<desc>a service discovery items (disco#items) request</desc>
|
|
</value>
|
|
</values>
|
|
</key>
|
|
<key>
|
|
<name>type</name>
|
|
<desc>the IQ type</desc>
|
|
<values>
|
|
<value>
|
|
<name>get</name>
|
|
<desc>an IQ get</desc>
|
|
</value>
|
|
<value>
|
|
<name>set</name>
|
|
<desc>an IQ set (disco publish)</desc>
|
|
</value>
|
|
</values>
|
|
</key>
|
|
</keys>
|
|
</querytype>
|
|
|
|
]]></code>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='XML Schemas' anchor='schemas'>
|
|
<section2 topic='disco#info' anchor='schemas-info'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8' ?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='http://jabber.org/protocol/disco#info'
|
|
xmlns='http://jabber.org/protocol/disco#info'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
The protocol documented by this schema is defined in
|
|
XEP-0030: http://www.xmpp.org/extensions/xep-0030.html
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
|
|
<xs:element name='query'>
|
|
<xs:complexType>
|
|
<xs:sequence minOccurs='0'>
|
|
<xs:element ref='identity' maxOccurs='unbounded'/>
|
|
<xs:element ref='feature' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='node' type='xs:string' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='identity'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='category' type='xs:string' use='required'/>
|
|
<xs:attribute name='name' type='xs:string' use='optional'/>
|
|
<xs:attribute name='type' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='feature'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='var' type='xs:string' use='required'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:simpleType name='empty'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:enumeration value=''/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section2>
|
|
<section2 topic='disco#items' anchor='schemas-items'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8' ?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='http://jabber.org/protocol/disco#items'
|
|
xmlns='http://jabber.org/protocol/disco#items'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
The protocol documented by this schema is defined in
|
|
XEP-0030: http://www.xmpp.org/extensions/xep-0030.html
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
|
|
<xs:element name='query'>
|
|
<xs:complexType>
|
|
<xs:sequence minOccurs='0'>
|
|
<xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='node' type='xs:string' use='optional'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:element name='item'>
|
|
<xs:complexType>
|
|
<xs:simpleContent>
|
|
<xs:extension base='empty'>
|
|
<xs:attribute name='action' use='optional'>
|
|
<xs:simpleType>
|
|
<xs:restriction base='xs:NCName'>
|
|
<xs:enumeration value='remove'/>
|
|
<xs:enumeration value='update'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
</xs:attribute>
|
|
<xs:attribute name='jid' type='xs:string' use='required'/>
|
|
<xs:attribute name='name' type='xs:string' use='optional'/>
|
|
<xs:attribute name='node' type='xs:string' use='optional'/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
<xs:simpleType name='empty'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:enumeration value=''/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Author Note' anchor='authornote'>
|
|
<p>Peter Millard, a co-author of this specification from version 0.1 through version 2.2, died on April 26, 2006.</p>
|
|
</section1>
|
|
</xep>
|