moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-21 08:45:04 -05:00
Code Issues Releases Wiki Activity

initial version

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2501 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2008-11-13 20:42:02 +00:00
parent bac2314db6
commit f009ccddfe
3 changed files with 1262 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

204
xep-0253.xml Normal file
View File

@ -0,0 +1,204 @@
<?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>PubSub Chaining</title>
<abstract>This specification defines a method for chaining pubsub nodes together, resulting in lightweight repeaters for pubsub notifications.</abstract>
&LEGALNOTICE;
<number>0253</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0050</spec>
<spec>XEP-0060</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
&ralphm;
&stpeter;
<revision>
<version>0.1</version>
<date>2008-11-13</date>
<initials>psa</initials>
<remark><p>Initial published version.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2008-10-07</date>
<initials>psa</initials>
<remark><p>Added ofrom header to notifications.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2008-08-12</date>
<initials>rm/psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>To enable lightweight repeaters for &xep0060; notifications, we need the ability to subscribe one pubsub node to another pubsub node. This specification defines a method for doing so, using &xep0050;.</p>
</section1>
<section1 topic='How It Works' anchor='howitworks'>
<p>The owner of a pubsub node can subscribe that "local" node to a "remote" node using the flow described below. In these examples, the node owner is admin@consumer.tld, the local node is weatherbot@consumer.tld/Chicagoland, and the remote node has a NodeID of "OHR" at the pubsub service notify.weather.tld.</p>
<example caption='Owner requests chaining'><![CDATA[
<iq from='admin@consumer.tld/client'
id='chaining-1'
to='weatherbot@consumer.tld'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/pubsub#chaining'/>
</iq>
]]></example>
<p>Unless an error occurs, the service SHOULD return the appropriate form.</p>
<example caption='Service returns chaining form to node owner'><![CDATA[
<iq from='weatherbot@consumer.tld'
id='chaining-1'
to='admin@consumer.tld/client'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/pubsub#chaining'
sessionid='a73sjjvkla37jfea'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Chaining Request</title>
<instructions>Fill out this form to complete your request.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/pubsub#chaining</value>
</field>
<field label='The Node ID of the local pubsub node'
type='text-single'
var='local-node'>
<required/>
</field>
<field label='The Jabber ID of the remote pubsub service'
type='jid-single'
var='remote-service'>
<required/>
</field>
<field label='The NodeID of the remote pubsub node'
type='text-single'
var='remote-node'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin submits chaining form to service'><![CDATA[
<iq from='admin@consumer.tld/client'
id='chaining-2'
to='weatherbot@consumer.tld'
type='submit'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/pubsub#chaining'
sessionid='a73sjjvkla37jfea'
status='executing'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/pubsub#chaining</value>
</field>
<field var='local-node'>
<value>Chicagoland</value>
</field>
<field var='remote-service'>
<value>notify.weather.tld</value>
</field>
<field var='remote-node'>
<value>OHR</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service informs admin of completion'><![CDATA[
<iq from='weatherbot@consumer.tld'
id='chaining-2'
to='admin@consumer.tld/client'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/pubsub#chaining'
sessionid='a73sjjvkla37jfea'
status='completed'/>
</iq>
]]></example>
</section1>
<section1 topic='Notifications' anchor='notifications'>
<p>When a chained pubsub node delivers notifications to its subscribers, it SHOULD include an &xep0033; header of "ofrom" (note: this header is not yet defined in <cite>XEP-0033</cite>).</p>
<example caption='Service notifies subscribers'><![CDATA[
<message from='weatherbot@consumer.tld/bot'
to='subscriber@consumer.tld'
id='foo'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='Chicagoland'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
<example xmlns='urn:xmpp:example'>message</example>
</item>
</items>
</event>
<addresses xmlns='http://jabber.org/protocol/address'>
<address type='ofrom' jid='notify.weather.tld'/>
</addresses>
</message>
]]></example>
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>If a pubsub service supports Ad-Hoc Commands, it MUST advertise the commands it supports via &xep0030; (as described in <cite>XEP-0050: Ad-Hoc Commands</cite>); such commands exist as well-defined discovery nodes associated with the service. In particular, if a pubsub service supports chaining it MUST advertise a command of "http://jabber.org/protocol/pubsub#chaining".</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>The ability to subscribe one node to another node introduces the possibility of exposing non-public information in a public way, since the access controls for the node that originates a notification might not be known or enforced by the downstream node. Therefore, the upstream node (or its owner) is advised to make a careful access decision before allowing a downstream node (or any other entity) to subscribe.</p>
<p>Note: The upstream node can discover the identity of the downstream node by sending a service discovery information ("disco#info") request to the downstream node, and MAY cancel or decline the downstream node's subscription if it determines that the node has an identity of "pubsub/leaf" or "pubsub/collection".</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'>
<p>The &REGISTRAR; shall include the following information in its registries.</p>
<section2 topic='Protocol Namespaces' anchor='ns'>
<p>The XMPP Registrar shall include 'http://jabber.org/protocol/pubsub#chaining' in its registry of protocol namespaces (see &NAMESPACES;).</p>
</section2>
<section2 topic='Field Standardization' anchor='registrar-formtype'>
<p>&xep0068; defines a process for standardizing the fields used within &xep0004; scoped by a particular namespace (see &FORMTYPES;). The reserved fields for the 'http://jabber.org/protocol/pubsub#chaining' namespace are specified below.</p>
<code caption='Registry Submission'><![CDATA[
<form_type>
<name>http://jabber.org/protocol/pubsub#chaining</name>
<doc>XEP-xxxx</doc>
<desc>Forms used for chaining of pubsub nodes.</desc>
<field var='local-node'
type='text-single'
label='The Node ID of the local node'/>
<field var='remote-node'
type='text-single'
label='The NodeID of the remote node'/>
<field var='remote-service'
type='jid-single'
label='The Jabber ID of the remote pubsub service'/>
</form_type>
]]></code>
</section2>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Joe Hildebrand for his feedback.</p>
</section1>
</xep>

378
xep-0254.xml Normal file
View File

@ -0,0 +1,378 @@
<?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>PubSub Queueing</title>
<abstract>This specification defines an extension to XMPP publish-subscribe for queueing information at a node.</abstract>
&LEGALNOTICE;
<number>0254</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0060</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
&hildjj;
&stpeter;
<revision>
<version>0.1</version>
<date>2008-11-13</date>
<initials>psa</initials>
<remark><p>Initial published version.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2008-10-07</date>
<initials>jjh/psa</initials>
<remark><p>Added more detailed error flows; added additional implementation notes.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2008-10-07</date>
<initials>jjh/psa</initials>
<remark>
<ul>
<li>Specified that notifications are sent to only one subscriber at a time.</li>
<li>Specified that notifications include payloads.</li>
<li>Added protocol extension for unlock feature.</li>
<li>Modified namespace to incorporate namespace versioning.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2008-08-14</date>
<initials>psa/jjh</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>The &xep0060; extension to XMPP provides a comprehensive technology for alerts, notifications, data syndication, rich presence, and other real-time messaging use cases. In terms of traditional publish-subscribe systems like Java Message Service (JMS), the core XMPP PubSub specification covers the Observer design pattern only; however, traditional publish-subscribe systems often include support for a second design pattern, usually called the "point-to-point" or "queueing" pattern. <note>See for instance &lt;<link url='http://en.wikipedia.org/wiki/Java_Message_Service'>http://en.wikipedia.org/wiki/Java_Message_Service</link>&gt;.</note> This specification defines a few small extensions to XMPP PubSub that enable support for a queueing mode in XMPP. The queueing mode is an add-on feature that a service can support, and that a node owner can enable if supported by the service. The feature name is "urn:xmpp:pubsub:queueing:0".</p>
</section1>
<section1 topic='How It Works' anchor='howitworks'>
<section2 topic='Subscribing' anchor='subscribe'>
<p>If a node has enabled support for the queueing mode, in response to a subscription request without configuration options it MUST return an IQ-error containing a subscription options form; this form MUST include the "queue_requests" field (which specifies the number of parallel requests a subscriber is willing to process).</p>
<example caption='Service indicates that subscription configuration is required'><![CDATA[
<iq from='workflows.shakespeare.lit'
id='sub1'
to='workerbee237@shakespeare.lit/foo'
type='error'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe
jid='workerbee237@shakespeare.lit'
node='a290fjsl29j19kjb'/>
<options
jid='workerbee237@shakespeare.lit'
node='a290fjsl29j19kjb'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
</field>
<field type='text-single' var='pubsub#queue_requests'>
<required/>
</field>
</x>
</options>
</pubsub>
<error type='modify'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<configuration-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
</error>
</iq>
]]></example>
<p>The subscriber would then send a new subscription request, this time with options.</p>
<example caption='Subscribing with options'><![CDATA[
<iq from='workerbee237@shakespeare.lit/foo'
id='sub2'
to='workflows.shakespeare.lit'
type='set'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe
jid='workerbee237@shakespeare.lit'
node='a290fjsl29j19kjb'/>
<options
jid='workerbee237@shakespeare.lit'
node='a290fjsl29j19kjb'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
</field>
<field var='pubsub#queue_requests'>
<value>5</value>
</field>
</x>
</options>
</pubsub>
</iq>
]]></example>
<p>If the subscription request can be processed successfully, the service returns an IQ-result and includes the configuration options established during the negotiation.</p>
<example caption='Service replies with success (including configuration options)'><![CDATA[
<iq from='workflows.shakespeare.lit'
id='sub2'
to='workerbee237@shakespeare.lit/foo'
type='result'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscription
jid='workerbee237@shakespeare.lit'
node='a290fjsl29j19kjb'
subid='ba49252aaa4f5d320c24d3766f0bdcade78c78d3'
subscription='subscribed'/>
<options>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
</field>
<field var='pubsub#queue_requests'>
<value>5</value>
</field>
</x>
</options>
</pubsub>
</iq>
]]></example>
</section2>
<section2 topic='Assigning an Item' anchor='assign'>
<p>At any time, a publisher can push an item to the queue node.</p>
<example caption='Publisher publishes an item'><![CDATA[
<iq from='engine.shakespeare.lit'
id='pub1'
to='workflow.shakespeare.lit'
type='set'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='a290fjsl29j19kjb'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
<example xmlns='urn:xmpp:example'>payload</example>
</item>
</publish>
</pubsub>
</iq>
]]></example>
<p>The item is published to <em>one</em> of the subscribers.</p>
<example caption='One subscriber receives a notification'><![CDATA[
<message from='workflow.shakespeare.lit'
id='foo'
to='workerbee237@shakespeare.lit'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='a290fjsl29j19kjb'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
<example xmlns='urn:xmpp:example'>payload</example>
</item>
</items>
</event>
</message>
]]></example>
</section2>
<section2 topic='Deleting an Item from the Queue' anchor='delete'>
<p>When the subscriber that received the item has successfully processed it (whatever that means in the context of the queue), the subscriber deletes the item from the queue.</p>
<example caption='Entity deletes an item from a node'><![CDATA[
<iq from='workerbee237@shakespeare.lit/foo'
id='delete1'
to='workflows.shakespeare.lit'
type='get'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<retract node='a290fjsl29j19kjb'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
</retract>
</pubsub>
</iq>
]]></example>
<p>In the context of a queue node, the service MUST treat a delete request from a subscriber that received the item as if the sender were a publisher; i.e., it MUST delete the item from the queue and notify only this subscriber that the item has been deleted.</p>
<example caption='Subscriber receives delete notification'><![CDATA[
<message from='workflow.shakespeare.lit'
id='bar'
to='workerbee237@shakespeare.lit'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='a290fjsl29j19kjb'>
<retract id='ae890ac52d0df67ed7cfdf51b644e901'/>
</items>
</event>
</message>
]]></example>
<p>Note: The subscriber SHOULD NOT commit any pending transactions until it receives the delete notification.</p>
<p>If the item does not exist, the service MUST return an &notfound; error as described in <cite>XEP-0060</cite>.</p>
<p>If the entity that attempts to delete the item is not the subscriber that received the item, the service MUST return a &forbidden; error as described in <cite>XEP-0060</cite>.</p>
<p>If the item is locked by another subscriber, the service MUST return a &conflict; error (this flow is not defined in <cite>XEP-0060</cite>.</p>
<example caption='Item is locked by another subscriber'><![CDATA[
<iq from='workflows.shakespeare.lit'
id='delete1'
to='workerbee237@shakespeare.lit/foo'
type='get'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<retract node='a290fjsl29j19kjb'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
</retract>
</pubsub>
<error type='auth'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>If the subscriber that received the item attempts to delete the item but the item is no longer locked by the subscriber (e.g., because of a race condition or a lost notification), the service MUST return an &unexpected; error (this flow is not defined in <cite>XEP-0060</cite>.</p>
<example caption='Item is no longer locked by subscriber'><![CDATA[
<iq from='workflows.shakespeare.lit'
id='delete1'
to='workerbee237@shakespeare.lit/foo'
type='get'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<retract node='a290fjsl29j19kjb'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
</retract>
</pubsub>
<error type='wait'>
<unexpected-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section2>
<section2 topic='Unlocking an Item' anchor='unlock'>
<p>The subscriber might determine that it cannot process the item (whatever that means in the context of the queue); if so, the subscriber unlocks the item.</p>
<example caption='Entity unlocks an item'><![CDATA[
<iq from='workerbee237@shakespeare.lit/foo'
id='unlock1'
to='workflows.shakespeare.lit'
type='get'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<unlock xmlns='urn:xmpp:pubsub:queueing:0'
node='a290fjsl29j19kjb'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
</unlock>
</pubsub>
</iq>
]]></example>
<p>The service then MUST unlock the item and notify only this subscriber that the item has been unlocked.</p>
<example caption='Subscriber receives unlock notification'><![CDATA[
<message from='workflow.shakespeare.lit'
id='baz'
to='workerbee237@shakespeare.lit'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='a290fjsl29j19kjb'>
<unlock xmlns='urn:xmpp:queueing:0'
id='ae890ac52d0df67ed7cfdf51b644e901'/>
</items>
</event>
</message>
]]></example>
<p>When an item is unlocked, the service would then send a publish notification to another subscriber according to application-specific logic for determining the "next" subscriber.</p>
<p>If the item does not exist, the service MUST return an &notfound; error.</p>
<example caption='Item does not exist'><![CDATA[
<iq from='workflows.shakespeare.lit'
id='delete1'
to='workerbee237@shakespeare.lit/foo'
type='error'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<unlock xmlns='urn:xmpp:pubsub:queueing:0'
node='a290fjsl29j19kjb'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
</unlock>
</pubsub>
<error type='cancel'>
<item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>If the entity that attempts to unlock the item is not the subscriber that received the item, the service MUST return a &forbidden; error.</p>
<example caption='Requesting entity did not receive item'><![CDATA[
<iq from='workflows.shakespeare.lit'
id='delete1'
to='workerbee237@shakespeare.lit/foo'
type='error'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<unlock xmlns='urn:xmpp:pubsub:queueing:0'
node='a290fjsl29j19kjb'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
</unlock>
</pubsub>
<error type='auth'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>If the item is locked by another subscriber, the service MUST return a &conflict; error.</p>
<example caption='Item is locked by another subscriber'><![CDATA[
<iq from='workflows.shakespeare.lit'
id='delete1'
to='workerbee237@shakespeare.lit/foo'
type='error'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<unlock xmlns='urn:xmpp:pubsub:queueing:0'
node='a290fjsl29j19kjb'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
</unlock>
</pubsub>
<error type='cancel'>
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>If the subscriber that received the item attempts to unlock the item but the item is no longer locked by the subscriber (e.g., because of a race condition or a lost notification), the service MUST return an &unexpected; error.</p>
<example caption='Item is no longer locked by subscriber'><![CDATA[
<iq from='workflows.shakespeare.lit'
id='delete1'
to='workerbee237@shakespeare.lit/foo'
type='error'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<unlock xmlns='urn:xmpp:pubsub:queueing:0'
node='a290fjsl29j19kjb'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'/>
</unlock>
</pubsub>
<error type='wait'>
<unexpected-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>If a pubsub service supports the queueing mode, it MUST advertise support for the "urn:xmpp:pubsub:queueing:0" namespace in response to &xep0030; information requests.</p>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<p>If the service receives unavailable presence from a subscriber, it SHOULD unlock all outstanding queue items associated with the subscriber and unsubscribe the subscriber to prevent delivery of further publish notifications.</p>
<p>If a subscriber cannot process queue items because of an unrecoverable error (e.g., disk full), the subscriber SHOULD unsubscribe and then unlock all of its outstanding queue items.</p>
<p>If the service does not receive a delete or unlock request from a subscriber that received a queue item in a configurable amount of time, it SHOULD timeout the request, send an unlock notification to the subscriber, and send a publish notification to the "next" subscriber.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>To follow.</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-ns'>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:pubsub:queueing:0</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespaces to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>
<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
<p>If the protocol defined in this specification undergoes a major revision that is not fully backward-compatible with an older version, or that contains significant new features, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of <cite>XEP-0053</cite>.</p>
</section2>
<section2 topic='Service Discovery Features' anchor='registrar-features'>
<p>The &REGISTRAR; maintains a registry of service discovery features (see &DISCOFEATURES;), which includes a number of features that can be returned by pubsub services. The following registry submission supplements the existing list.</p>
<code><![CDATA[
<var>
<name>urn:xmpp:pubsub:queueing:0</name>
<desc>The node or service supports the queueing mode.</desc>
<doc>XEP-xxxx</doc>
</var>
]]></code>
</section2>
</section1>
</xep>

680
xep-0255.xml Normal file
View File

@ -0,0 +1,680 @@
<?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>Location Query</title>
<abstract>This specification defines an XMPP protocol extension for querying a compliant server for information about the geographical or physical location of an entity."</abstract>
&LEGALNOTICE;
<number>0255</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
<author>
<firstname>Helge</firstname>
<surname>Timenes</surname>
<email>helge@buddycloud.com</email>
<jid>helge@buddycloud.com</jid>
</author>
<author>
<firstname>Simon</firstname>
<surname>Tennant</surname>
<email>simon@buddycloud.com</email>
<jid>simon@buddycloud.com</jid>
</author>
<author>
<firstname>Ross</firstname>
<surname>Savage</surname>
<email>ross@buddycloud.com</email>
<jid>ross@buddycloud.com</jid>
</author>
<revision>
<version>0.1</version>
<date>2008-11-13</date>
<initials>psa</initials>
<remark><p>Initial published version.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2008-11-07</date>
<initials>ht</initials>
<remark><p>Removed &lt;error/&gt; child of geoloc element (arc minutes). <br/>Added &lt;accuracy/&gt; (meters). <br/>Updated notes on GPS data submitted in location query.<br/>replaced language encoding 'en-UK' with 'en-US' to avoid UK/GB confusion</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2008-11-03</date>
<initials>ht</initials>
<remark><p>Corrected XML namespace; added country code reference.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2008-10-28</date>
<initials>ht/st/rs</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>This document defines a format for querying a location server for information about an entity's geographical location. The query must contain some location characteristics that the server can process to derive this information. These can be in the form of geodetic coordinates (from GPS receivers or other positioning equipment), in which case the server will perform "reversed geocoding" to derive the information. Alternatively, the location can be characterized by a list of identifiable radio transmitters (from here on called 'beacons') observable from this location. Typical beacons include cellular telephone towers, wireless network access points and bluetooth devices. In this case the location server must match the supplied characteristics with stored knowledge about the beacons to derive the submitting entity's location. Client implementers are encouraged to supply both kinds of characteristics when available, as this can be utilized by self-learning location servers. The location information returned by the location server is structured according to &xep0080;, ensuring compatibility with systems using this standard for location information publishing.</p>
<p>The location query is designed to be used as a one-shot request or as a continuous query-result dialogue. The latter form will allow location servers to analyze changes with time, which in most cases yields improved fidelity and the possibility to derive motion state information.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>The format defined herein was designed to address the following requirements:</p>
<ul>
<li>It shall be usable on devices with no support for GPS or other geodetic positioning systems</li>
<li>It shall be usable on devices with support for GPS or other geodetic positioning systems</li>
<li>It shall be compatible with place-referencing systems</li>
<li>It shall support self-learning location servers</li>
<li>The result format shall be expressed as natural language location description</li>
<li>The result format shall be compatible with XEP-0080</li>
</ul>
</section1>
<section1 topic='How It Works' anchor='examples'>
<p>The basic principle behind this XMPP extension is as follows: An XMPP clients collects characteristics about its current location that is not directly suitable for presentation to a human user, but from which human readable location information can be derived. The client sends this information to a location server that derives this information and returns it to the querying client. Here "location server" means a XMPP server application that supports the <strong>locationquery</strong> stanza defined in this document. It can either be an integral part of the XMPP server, or run as a component on the same or a different machine from the XMPP server itself.</p>
<example caption='Entity queries server with GPS coordinates'><![CDATA[
<iq from='hamlet@shakespeare.lit/phone'
id='q01'
to='location.shakespear.lit'
type='get'
xml:lang='en-US'>
<locationquery xmlns='urn:xmpp:locationquery:0'>
<latitude>57.0501862</latitude>
<longitude>9.9188746</longitude>
<accuracy>35.6</accuracy>
</locationquery>
<iq>
]]></example>
<example caption='Server responds with location info'><![CDATA[
<iq from='location.shakespeare.lit'
id='q01'
to='hamlet@shakespeare.lit/phone'
type='result'
xml:lang='en-US'>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
<timestamp>1599-10-23T01:55:21Z</timestamp>
<latitude>57.0501862</latitude>
<longitude>9.9188746</longitude>
<accuracy>35.6</accuracy>
<street>Jomfru Ane Gade 13</street>
<locality>Aalborg</locality>
<country>Denmark</country>
<uri>http://shakespeare.lit/places/kings_head_pub_aalborg</uri>
<text>Near King's Head Pub</text>
</geoloc>
<iq>
]]></example>
<example caption='Entity queries server with cell tower and wifi access point IDs'><![CDATA[
<iq from='hamlet@shakespeare.lit/phone'
id='q02'
to='location.shakespear.lit'
type='get'
xml:lang='en-US'>
<locationquery xmlns='urn:xmpp:locationquery:0'>
<beacon>
<id>238:02:34775:50880</id>
<type>cell</id>
</beacon>
<beacon>
<id>00:0F:3D:42:92:2A</id>
<type>wifi</id>
</beacon>
<beacon>
<id>00:19:CB:45:50:4A</id>
<type>wifi</id>
</beacon>
</locationquery>
<iq>
]]></example>
<example caption='Server responds with location info'><![CDATA[
<iq from='location.shakespeare.lit'
id='q02'
to='hamlet@shakespeare.lit/phone'
type='result'
xml:lang='en-US'>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
<timestamp>1599-10-23T01:55:21Z</timestamp>
<latitude>57.050122</latitude>
<longitude>9.918833</longitude>
<locality>Aalborg</locality>
<street>Jomfru Ane Gade 13</street>
<country>Denmark</country>
<accuracy>20</accuracy>
<uri>http://shakespeare.lit/places/kings_head_pub_aalborg</uri>
<text>King's Head Pub</text>
</geoloc>
<iq>
]]></example>
<example caption='Entity queries server and specifies that results should be published'><![CDATA[
<iq from='hamlet@shakespeare.lit/phone'
id='q03'
to='location.shakespear.lit'
type='get'
xml:lang='en-US'>
<locationquery xmlns='urn:xmpp:locationquery:0'>
<timestamp>1599-10-23T01:55:21Z</timestamp>
<latitude>57.0501862</latitude>
<longitude>9.918874</longitude>
<accuracy>33.56</accuracy>
<publish>true</publish>
<beacon>
<id>238:02:34775:50880</id>
<type>cell</id>
</beacon>
<beacon>
<id>00:0F:3D:42:92:2A</id>
<type>wifi</id>
</beacon>
<beacon>
<id>00:19:CB:45:50:4A</id>
<type>wifi</id>
</beacon>
<beacon>
<id>00:18:42:E6:71:51</id>
<type>bluetooth</id>
</beacon>
</locationquery>
<iq>
]]></example>
<example caption='Server responds with empty IQ-result...'><![CDATA[
<iq from='location.shakespeare.lit'
id='q03'
to='hamlet@shakespeare.lit/phone'
type='result'
xml:lang='en-US' />
]]></example>
<example caption='...and publishes result to the entity&apos;s geoloc pubsub node...'><![CDATA[
<iq from='hamlet@shakespeare.lit/phone'
id='q03'
to='hamlet@shakespeare.lit/phone'
type='set'
xml:lang='en-US'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish'>
<node xmlns='http://jabber.org/protocol/geoloc'>
<item'>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
<timestamp>1599-10-23T01:55:21Z</timestamp>
<latitude>57.0501862</latitude>
<longitude>9.918874</longitude>
<street>Jomfru Ane Gade 13</street>
<locality>Aalborg</locality>
<country>Denmark</country>
<accuracy>20</accuracy>
<uri>http://shakespeare.lit/places/kings_head_pub_aalborg</uri>
<text>King's Head Pub</text>
</geoloc>
</item>
</node>
</publish>
</pubsub>
<iq>
]]></example>
<example caption='...which is delivered to everyone subscribing to it'><![CDATA[
<message from='hamlet@shakespeare.lit' to='hamlet@shakespeare.lit/phone'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='http://jabber.org/protocol/geoloc'>
<item id='4C940F61C13A0'>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
<timestamp>1599-10-23T01:55:21Z</timestamp>
<latitude>57.0501862</latitude>
<longitude>9.918874</longitude>
<street>Jomfru Ane Gade 13</street>
<locality>Aalborg</locality>
<country>Denmark</country>
<accuracy>20</accuracy>
<uri>http://shakespeare.lit/places/kings_head_pub_aalborg</uri>
<text>King's Head Pub</text>
</geoloc>
</item>
</items>
</event>
</message>
<message from='hamlet@shakespeare.lit' to='horatio@shakespeare.lit/pda'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='http://jabber.org/protocol/geoloc'>
<item id='4C940F61C13A0'>
<geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
<timestamp>1599-10-23T01:55:21Z</timestamp>
<latitude>57.0501862</latitude>
<longitude>9.918874</longitude>
<street>Jomfru Ane Gade 13</street>
<locality>Aalborg</locality>
<country>Denmark</country>
<accuracy>20</accuracy>
<uri>http://shakespeare.lit/places/kings_head_pub_aalborg</uri>
<text>King's Head Pub</text>
</geoloc>
</item>
</items>
</event>
</message>
]]></example>
</section1>
<section1 topic='Data Format' anchor='format'>
<p>Information about the radio beacons in the entity's surrounding, and its geodetic coordinates are provided by the entity and propagated on the network by the entity's associated application (usually a client). The information is structured by means of a &lt;locationquery/&gt; element that is qualified by the 'urn:xmpp:locationquery:0' namespace and nested with in a &lt;iq&gt; element with type set to <i>get</i>. The location result is provided by the location server and returned to the client in a &lt;iq&gt; element with type set to <i>result</i>. The location result is structured by means of a &lt;geoloc/&gt; element that is qualified by the 'http://jabber.org/protocol/geoloc' namespace (see <a href="../xep-0080.html">XEP-0080</a>).</p>
<table caption='Location Query Child Elements'>
<tr class="body">
<th>Element Name</th>
<th>Datatype</th>
<th>Definition</th>
<th>Example</th>
<th>Notes</th>
</tr>
<tr class="body">
<td>timestamp</td>
<td>xs:datetime</td>
<td>UTC timestamp specifying the moment when the reading was taken (MUST conform to the DateTime profile of &xep0082;.</td>
<td>2004-02-19T21:12Z</td>
<td>This is the only field that is required without exception.</td>
</tr>
<tr class="body">
<td>publish</td>
<td>xs:boolean</td>
<td>A flag specifying whether or not the server should publish the location result to subscribers of the submitting user's XEP-0080 compatible geoloc pub-sub node instead of returning it directly to the submitting user.</td>
<td>true</td>
<td>Optional. If present and "true", the server shall publish the entity's location details whenever it changes (suitable for periodic queries) and respond to the query with an empty &lt;iq&gt; stanza with type set to "result". If not specified or "false" the server shall return the location results to the submitting user in the form of a geoloc stanza (XEP-0080) embedded in a &lt;iq&gt; with type set to "result". Default is "false"</td>
</tr>
<tr class="body">
<td>lat</td>
<td>xs:decimal</td>
<td>Latitude in decimal degrees
North.</td>
<td>39.75</td>
<td>Required if no radio beacon data present, otherwise optional. If present, this shall also be present in the result stanza. If not present, the location server SHOULD estimate a value based on submitted beacon data and return with result stanza. The location server is free to decide if the value of this field should be piped directly through to result, or if it should be modified based on beacon data or time history information. For instance: if the entity is indoors, the GPS signal will be inaccurate and unstable over time. If wifi beacons are submitted, the location server may decide that the entity is inside a known building, and return the latitude of this instead.</td>
</tr>
<tr class="body">
<td>lon</td>
<td>xs:decimal</td>
<td>Longitude in decimal degrees
East</td>
<td>-104.99</td>
<td>See notes for <i>lat</i></td>
</tr>
<tr class="body">
<td>alt</td>
<td>xs:decimal</td>
<td>Altitude in meters above or
below sea level</td>
<td>1609</td>
<td>Optional. If present, this shall also be present in the result stanza with identical value.</td>
</tr>
<tr class="body">
<td>bearing</td>
<td>xs:decimal</td>
<td>GPS bearing (direction in which
the entity is heading to reach its next waypoint), measured in
decimal degrees relative to true north</td>
<td> </td>
<td>See notes for <i>alt</i></td>
</tr>
<tr class="body">
<td>datum</td>
<td>xs:string</td>
<td>GPS datum (See XEP-0080)</td>
<td> </td>
<td>See notes for <i>alt</i></td>
</tr>
<tr class="body">
<td>accuracy</td>
<td>xs:decimal</td>
<td>Horizontal GPS accuracy in meters</td>
<td>10</td>
<td>See notes for <i>lat</i></td>
</tr>
<tr class="body">
<td>speed</td>
<td>xs:decimal</td>
<td>The speed at which the entity is
moving, in meters per second</td>
<td>52.69</td>
<td>See notes for <i>alt</i></td>
</tr>
<tr class="body">
<td>beacons</td>
<td>locationquery:beacon</td>
<td>A list of identifiable radio transmitters observed by the entity</td>
<td> </td>
<td>Required if no <i>lat</i> and <i>lon</i> values specified, otherwise optional. See Table 2 for type definition.</td>
</tr>
</table>
<table caption='Beacon Child Elements'>
<tr class="body">
<th>Element Name</th>
<th>Datatype</th>
<th>Definition</th>
<th>Example</th>
<th>Notes</th>
</tr>
<tr class="body">
<td>id</td>
<td>xs:string</td>
<td>A world-wide unique beacon identifier. This SHALL be composed as follows: <br/><br/>For cell towers: "MCC:MNC:LAC:CID" where MCC is the mobile country code <note>Values of Mobile Country Codes (MCC) are specified by <link url="http://www.itu.int/dms_pub/itu-t/opb/sp/T-SP-E.212A-2007-PDF-E.pdf">Annex to ITU Operational Bulletin No. 897 – 1.XII.2007</link>.</note>), MNC is the network carrier code, LAC is the area code and CID is the cell ID.<br/><br/>For wireless access points and bluetooth devices: The device MAC address.</td>
<td>207:02:12643:78596</td>
<td>Required</td>
</tr>
<tr class="body">
<td>type</td>
<td>xs:string</td>
<td>Beacon type. One of "cell", "wifi", "bluetooth", "wimax", "rfid" (?), "other"</td>
<td>"cell"</td>
<td>Required.</td>
</tr>
</table>
<table caption='Location Result Child Elements (Copied from XEP-0080 with notes added)'>
<tr class="body">
<th>Element Name</th>
<th>Datatype</th>
<th>Definition</th>
<th>Example</th>
<th>Notes</th>
</tr>
<tr class="body">
<td>alt</td>
<td>xs:decimal</td>
<td>Altitude in meters above or
below sea level</td>
<td>1609</td>
<td>Piped directly through from query <i>alt</i> field if set.</td>
</tr>
<tr class="body">
<td>area</td>
<td>xs:string</td>
<td>A named area such as a campus or
neighborhood</td>
<td>Central Park</td>
<td> </td>
</tr>
<tr class="body">
<td>bearing</td>
<td>xs:decimal</td>
<td>GPS bearing (direction in which
the entity is heading to reach its next waypoint), measured in
decimal degrees relative to true north</td>
<td> </td>
<td>Piped directly through from query <i>bearing</i> field if set.</td>
</tr>
<tr class="body">
<td>building</td>
<td>xs:string</td>
<td>A specific building on a street
or in an area</td>
<td>The Empire State Building</td>
<td> </td>
</tr>
<tr class="body">
<td>country</td>
<td>xs:string</td>
<td>The nation where the user is
located</td>
<td>USA</td>
<td> </td>
</tr>
<tr class="body">
<td>datum</td>
<td>xs:string</td>
<td>GPS datum (See notes for XEP-0080)</td>
<td></td>
<td>Piped directly through from query <i>datum</i> field if set.</td>
</tr>
<tr class="body">
<td>description</td>
<td>xs:string</td>
<td>A natural-language name for or
description of the location</td>
<td>Bill's house</td>
<td>If location is mapped to a place in a place oriented service, this should hold the place description.</td>
</tr>
<tr class="body">
<td>accuracy</td>
<td>xs:decimal</td>
<td>Horizontal GPS accuracy in meters</td>
<td>10</td>
<td>Piped directly through from query <i>accuracy</i> field or estimated by location server using based on the other information in query and, if possible, differences between several queries over time.</td>
</tr>
<tr class="body">
<td>floor</td>
<td>xs:string</td>
<td>A particular floor in a building</td>
<td>102</td>
<td> </td>
</tr>
<tr class="body">
<td>lat</td>
<td>xs:decimal</td>
<td>Latitude in decimal degrees
North</td>
<td>39.75</td>
<td>Piped directly through from query <i>lat</i> field or estimated by location server based on the other information in query and, if possible, differences between several queries over time.</td>
</tr>
<tr class="body">
<td>locality</td>
<td>xs:string</td>
<td>A locality within the
administrative region, such as a town or city</td>
<td>New York City</td>
<td> </td>
</tr>
<tr class="body">
<td>lon</td>
<td>xs:decimal</td>
<td>Longitude in decimal degrees
East</td>
<td>-104.99</td>
<td>Piped directly through from query <i>lon</i> or estimated by location server based on the other information in query and, if possible, differences between several queries over time.</td>
</tr>
<tr class="body">
<td>postalcode</td>
<td>xs:string</td>
<td>A code used for postal delivery</td>
<td>10027</td>
<td> </td>
</tr>
<tr class="body">
<td>region</td>
<td>xs:string</td>
<td>An administrative region of the
nation, such as a state or province</td>
<td>New York</td>
<td> </td>
</tr>
<tr class="body">
<td>room</td>
<td>xs:string</td>
<td>A particular room in a building</td>
<td>Observatory</td>
<td> </td>
</tr>
<tr class="body">
<td>speed</td>
<td>The speed at which the entity is
moving, in meters per second</td>
<td>52.69</td>
<td>xs:decimal</td>
<td>Piped directly through from query <i>speed</i> field or estimated by location server based on the other information in query and, if possible, differences between several queries over time.</td>
</tr>
<tr class="body">
<td>street</td>
<td>xs:string</td>
<td>A thoroughfare within the
locality, or a crossing of two thoroughfares</td>
<td>34th and Broadway</td>
<td> </td>
</tr>
<tr class="body">
<td>text</td>
<td>xs:string</td>
<td>A catch-all element that
captures any other information about the location</td>
<td>Northwest corner of the lobby</td>
<td>Best practice tip: This field can be used by the server to combine several fields in a natural language style, suitable for simple one-line location presence text. Example: "Near Bob's place" (description + accuracy), "On the road in New York" (locality + speed)</td>
</tr>
<tr class="body">
<td>timestamp</td>
<td>xs:datetime</td>
<td>UTC timestamp specifying the moment when the reading was taken (MUST conform to the DateTime profile of <cite>XEP-0082</cite>)</td>
<td>2004-02-19T21:12Z</td>
<td>Piped directly through from query <i>timestamp</i> field.</td>
</tr>
<tr class="body">
<td>uri</td>
<td>A URI or URL pointing to
information about the location</td>
<td>http://beta.plazes.com/plazes/1940:jabber_inc</td>
<td>xs:anyURI</td>
<td>Only applicable to place-oriented services</td>
</tr>
</table>
<p>NOTE: The datatypes specified above are defined in &w3xmlschema2;.</p>
</section1>
<section1 topic='Recommended Transport' anchor='transport'>
<p>The location results SHOULD be distributed means of &xep0060; or the subset thereof specified in &xep0163;. This can be done automatically by requesting the "publish" location query result format, in which case the location server will publish the results on the user's behalf. Alternatively the it can be done client side as outlined in <cite>XEP-0080</cite>.</p>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<section2 topic='Server Implementation Notes' anchor='server_impl'>
<p>The does not have to determine a value for all fields of the &lt;geoloc&gt; stanza, but it SHOULD determine values for as many as possible. At the very least a value for 'country' should be set.</p>
<p>If no GPS coordinate and accuracy information is submitted in the query, and the server determines location coordinates from submitted beacon data, a value for the returned geoloc 'accuracy' field SHOULD be returned. The magnitude of this should be derived based on the ranges of the beacons used to determine the location. </p>
<p>The server should make no assumptions about how often a entity submits a query. It should support occasional manually triggered queries as well as periodic automated queries. In the latter case it should analyze changes over time, as this can greatly increase the fidelity of the result. </p>
<p>Furthermore, no assumptions should be made about the number of beacons being logged in each query. Some handset manufacturers limit the access programmers have to cell tower and access point information. Some may only offer the currently connected cell ID, such that even if the handset can "see" many cell towers, only the one to which the handset is connected at the moment can be read. In this case the cell tower readings may not be constant, even if the querying entity is not moving. Rather it may jump round-robin style to each visible cell with variable time spent on each. The location server should account for this to avoid yielding results indicating that a user is running around in cell-sized circles when he is in fact stationary. Again, analysis of variation of submitted queries over time is recommended.</p>
<p>As no guarantees can be made that a given radio beacon stays at one fixed physical location throughout it's lifetime, the server should implement means to detect this. Generally it can be assumed that cell towers seldom move (could happen when a network operator changes the way it allocates cell IDs or when a tower is physically moved to a different location). Wireless access points move a bit more frequently (for instance when their owners move, or if they are installed in moving vehicles such as busses or trains). Bluetooth devices can generally be assumed to be mobile and should, unless specific knowledge to the contrary exists, not be used to locate an entity to a specific physical location. Rather, bluetooth devices (and other mobile beacons) can be used to co-locate entities to other entities for which a physical location is known. An example: Entity A submits query with GPS coordinates and the ID of some bluetooth device. It is located based on its submitted coordinates. Entity B submits a query with the same bluetooth device ID, but no GPS coordinates. Given this, and the fact that bluetooth transmitters have a very limited range, the server can then derive that A and B are at the same physical location (it may add 10-20 m to the accuracy of the location of B to account for the bluetooth range).</p>
<p>The "radio landscape" is by no means constant. New beacons are added continuously, and old ones are phased out. A location server will have to adapt to this shifting landscape, either by means of operator-supplied databases (in case of cell towers) or by means of user generated information. This standard was written with the latter in mind, and it is recommended that location servers utilize any queries with combined GPS and radio beacon information to "learn" the approximate physical location of the provided beacons. For server implementation that rely on user generated information only, it is also recommended to supply additional means for the users to feed back location context in cases where the client does not have any GPS access, or when the server produces the wrong results. One way to do this would be to let the users define "placemarks" (a name, street, city etc) that can be associated with the beacons seen by this user at the time of definition. This is however beyond the scope of this XEP. </p>
</section2>
<section2 topic='Client Implementation Notes' anchor='client_impl'>
<p>For the reasons mentioned above, it is recommended that the client supply both GPS coordinates as well as nearby radio beacon information when possible. Also it is recommended that the client submit queries frequently enough to allow the server to analyze changes over time (or lack thereof) to obtain a better result. When possible, the client should include wifi access points in the queries, as these yield much more precise results than cell towers alone (due to the much more limited range). This must however all be weighted against the increased power consumption resulting from keeping network sockets open, scanning for access points and driving a GPS receiver.<br/><br/> For optimal results, clients SHOULD post a location query any time when the set of observed beacons change (a new beacon is seen or an old one is not seen any more)</p>
</section2>
</section1>
<section1 topic='Internationalization Considerations' anchor='i18n'>
<p>Because the character data contained in the location results is intended to be readable by humans, the location query SHOULD possess an 'xml:lang' attribute specifying the natural language of such character data &rfc4646;. If so, the server SHOULD equip the &lt;geoloc/&gt; element, of the result stanza with an identical attribute </p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>It is imperative to control access to location information, at least by default. Imagine that a stalker got unauthorized access to this information, with enough accuracy and timeliness to be able to find the target person. This scenario could lead to loss of life, so please take access control checks seriously. If an error is deliberately added to a location, the error SHOULD be the same for all receivers, to minimize the likelihood of triangulation. In the case of deliberate error, the &lt;accuracy/&gt; element SHOULD NOT be included.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with the <span class="ref" style=""><a href="http://www.iana.org/">Internet Assigned Numbers Authority (IANA)</a></span> [<a href="notes_iana">7</a>].</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:jingle:transfer:0</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespaces to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>
<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
<p>If the protocol defined in this specification undergoes a major revision that is not fully backward-compatible with an older version, or that contains significant new features, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of <cite>XEP-0053</cite>.</p>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:locationquery:0'
xmlns='urn:xmpp:locationquery:0'
elementFormDefault='qualified'>
<xs:element name='locationquery'>
<xs:complexType>
<xs:sequence minOccurs='1' maxOccurs='1'>
<xs:element name='timestamp'
minOccurs='1'
maxOccurs='1'
type='xs:datetime'/>
<xs:element name='publish'
minOccurs='0'
maxOccurs='1'
type='xs:bolean'/>
<xs:element name='lat'
minOccurs='0'
maxOccurs='1'
type='xs:decimal'/>
<xs:element name='lon'
minOccurs='0'
maxOccurs='1'
type='xs:decimal'/>
<xs:element name='alt'
minOccurs='0'
maxOccurs='1'
type='xs:decimal'/>
<xs:element name='bearing'
minOccurs='0'
maxOccurs='1'
type='xs:decimal'/>
<xs:element name='speed'
minOccurs='0'
maxOccurs='1'
type='xs:decimal'/>
<xs:element name='datum'
minOccurs='0'
maxOccurs='1'
type='xs:string'/>
<xs:element name='accuracy'
minOccurs='0'
maxOccurs='1'
type='xs:decimal'/>
<xs:element name='beacons'
minOccurs='0'
maxOccurs='unbounded'>
<xs:complexType>
<xs:sequence minOccurs='1' maxOccurs='1'>
<xs:element name='id'
minOccurs='1'
maxOccurs='1'
type='xs:string'/>
<xs:element name='type'
minOccurs='1'
maxOccurs='1'
type='xs:string'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
<p>Schema for the location results are given by <cite>XEP-0080</cite>.</p>
</section1>
</xep>