@ -571,10 +571,10 @@ A CDO client can query the server to determine the specific state of a particula
@@ -571,10 +571,10 @@ A CDO client can query the server to determine the specific state of a particula
</query>
</iq>
]]></example>
Note an event type of info. This requires all attributes for the data-sync element and items be present
<p>Note an event type of info. This requires all attributes for the data-sync element and items be present</p>
</section2>
<section2topic="Query an endpoint for a list of CDOs"anchor="cdolist">
In some cases a client may be interested in the state of all CDOs belonging to a specific endpoint - for example a chat room.
<p>In some cases a client may be interested in the state of all CDOs belonging to a specific endpoint - for example a chat room.</p>
<examplecaption="Client A constructs an IQ get and sends it to Server X wishing to obtain the current state of all CDOs belonging to the CDO users chatroom"><![CDATA[
@ -595,18 +595,17 @@ In some cases a client may be interested in the state of all CDOs belonging to a
@@ -595,18 +595,17 @@ In some cases a client may be interested in the state of all CDOs belonging to a
Note the value of the uuid for the cdo tag above uses an asterisk (*) to indicate all CDOs
<p>Note the value of the uuid for the cdo tag above uses an asterisk (*) to indicate all CDOs</p>
<p>
If desired, Client A can then query the Server for the details on the state of a specific CDO using the protocol described earlier.
</p>
</section2>
<section2topic="Create a new CDO"anchor="cdocreate">
When two endpoints (client A and client B) wish to create a new CDO. Each client and server MUST follow this algorithm:
<p>When two endpoints (client A and client B) wish to create a new CDO. Each client and server MUST follow this algorithm:</p>
<examplecaption="Client A creates a new CDO and sends it to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
@ -625,7 +624,7 @@ When two endpoints (client A and client B) wish to create a new CDO. Each client
@@ -625,7 +624,7 @@ When two endpoints (client A and client B) wish to create a new CDO. Each client
</data-sync>
</message>
]]></example>
Here client A, has created a packetID and set event=create in both <data-sync> and <item>. The version MUST be set to zero
<p>Here client A, has created a packetID and set event=create in both <data-sync> and <item>. The version MUST be set to zero</p>
<p>
Next, the message is intercepted by Server X. Server X is the IM server that both clients are connected to. When the server receives
the message, it MUST increment the version number and assign a uuid for both the <data-sync> and <item>. Once processed
@ -675,10 +674,10 @@ Server X MUST send a copy of the message back to client A as a receipt that the
@@ -675,10 +674,10 @@ Server X MUST send a copy of the message back to client A as a receipt that the
</data-sync>
</message>
]]></example>
Once this is completed, both clients have a synchronized CDO message with a uuid and a version number assigned by the server.
<p>Once this is completed, both clients have a synchronized CDO message with a uuid and a version number assigned by the server.</p>
</section2>
<section2topic="Create a new Item on an existing CDO"anchor="cdoitemcreate">
When client A wishes to create a new Item on an existing CDO, he sends the following information to client B
<p>When client A wishes to create a new Item on an existing CDO, he sends the following information to client B</p>
<examplecaption="Client A creates a new item on an existing CDO and sends it to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
@ -741,10 +740,10 @@ Next, Server X MUST send a copy of the message back to client A as a receipt tha
@@ -741,10 +740,10 @@ Next, Server X MUST send a copy of the message back to client A as a receipt tha
</data-sync>
</message>
]]></example>
Once this is completed, both clients have a synchronized CDO message with a new item. The new item has been assigned a uuid and a version number by the server.
<p>Once this is completed, both clients have a synchronized CDO message with a new item. The new item has been assigned a uuid and a version number by the server.</p>
</section2>
<section2topic="Update an Item on an existing CDO"anchor="cdoitemupdate">
When client A wishes to update an item on an existing CDO, he sends the following information to client B
<p>When client A wishes to update an item on an existing CDO, he sends the following information to client B</p>
<examplecaption="Client A updates an item on an existing CDO and sends it to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
@ -819,7 +818,7 @@ Next, Server X MUST send a copy of the message back to client A as a receipt tha
@@ -819,7 +818,7 @@ Next, Server X MUST send a copy of the message back to client A as a receipt tha
</data-sync>
</message>
]]></example>
Once this is completed, both clients have a synchronized CDO message with an updated item. The updated item has the version number incremented.
<p>Once this is completed, both clients have a synchronized CDO message with an updated item. The updated item has the version number incremented.</p>
<section3topic="Update Styles">
<p>
There are two types of behaviors associated with an item update: inclusive and exclusive. For an inclusive update, the content of the item element
@ -832,35 +831,35 @@ Once this is completed, both clients have a synchronized CDO message with an upd
@@ -832,35 +831,35 @@ Once this is completed, both clients have a synchronized CDO message with an upd
Assume that client A has created a CDO cdo_1. This CDO has an item item_1 with the attribute named attr_1 set. If A wants to update item_1 with a value
for the attribute named attr_2 without destroying the previously set value for attr_1, the following data synchronization packets are equivalent:
<section2topic="Delete an Item on an existing CDO"anchor="cdoitemdelete">
When client A wishes to delete an item on an existing CDO, he sends the following information to client B
<p>When client A wishes to delete an item on an existing CDO, he sends the following information to client B</p>
<examplecaption="Client A deletes an item on an existing CDO and sends it to client B"><![CDATA[
<message
to='joe@mitre.org/Desktop'
@ -929,7 +928,7 @@ back to client A as a receipt that the message has been processed by Server X an
@@ -929,7 +928,7 @@ back to client A as a receipt that the message has been processed by Server X an
</data-sync>
</message>
]]></example>
Once this is completed, both clients have a synchronized CDO message with a deleted item.
<p>Once this is completed, both clients have a synchronized CDO message with a deleted item.</p>
</section2>
<section2topic="Retire an existing CDO"anchor="cdoretire">
<p>
@ -990,7 +989,7 @@ message back to client A as a receipt that the message has been processed by Ser
@@ -990,7 +989,7 @@ message back to client A as a receipt that the message has been processed by Ser
</data-sync>
</message>
]]></example>
Once this is completed, both clients have retired (deleted) the CDO.
<p>Once this is completed, both clients have retired (deleted) the CDO.</p>
</section2>
</section1>
<section1topic="Errors"anchor="errors">
@ -1590,12 +1589,12 @@ containing at least one overlapping item. When this occurs, the first packet to
@@ -1590,12 +1589,12 @@ containing at least one overlapping item. When this occurs, the first packet to
reported back to the client of the second packet MAY be extended to describe the notional conflict. This additional error information is meant to facilitate
collaboration between the clients.
</p>
The additional error information provide includes:
<p>The additional error information provide includes:</p>
<ul>
<li>The resource identifier of the client originating the data sync packet with which this error conflicts.</li>
<li>The timestamp of when the originating data sync packet was executed.</li>
<li>The item element of the originating data sync packet with which this error conflicts.</li>
</ul>
<li>The resource identifier of the client originating the data sync packet with which this error conflicts.</li>
<li>The timestamp of when the originating data sync packet was executed.</li>
<li>The item element of the originating data sync packet with which this error conflicts.</li>
The metacontact storage is achieved through the use of private data storage. In order to achieve the resilience described above, the private storage of each account is used to store the metacontact membership of Jids in the roster of that account. The metacontacts are stored within private data storage of each account simply as an unordered collection of meta tags.
<p>The metacontact storage is achieved through the use of private data storage. In order to achieve the resilience described above, the private storage of each account is used to store the metacontact membership of Jids in the roster of that account. The metacontacts are stored within private data storage of each account simply as an unordered collection of meta tags.</p>
In this example, the 'jid' specifies that the roster entry 'romeo@montague.net' is a member of a metacontact. The 'tag' provides a key for a metacontact; in this example all metacontacts with a tag of 'd93nov' (across all accounts) refer to the same entity. The 'order' denotes the priority of this Jid over other Jids within the metacontact, with it being preferable to use Jids with higher priority (this is roughly analogous to the 'priority' on presence stanzas when a Jid has multiple online resources in XMPP).
<p>In this example, the 'jid' specifies that the roster entry 'romeo@montague.net' is a member of a metacontact. The 'tag' provides a key for a metacontact; in this example all metacontacts with a tag of 'd93nov' (across all accounts) refer to the same entity. The 'order' denotes the priority of this Jid over other Jids within the metacontact, with it being preferable to use Jids with higher priority (this is roughly analogous to the 'priority' on presence stanzas when a Jid has multiple online resources in XMPP).</p>
</section1>
<section1topic='Use Cases'anchor='usecases'>
<p>Below are example of setting and retrieving metacontacts for an account. When using metacontacts across multiple accounts, the steps are identical and the 'tag' attributes and used across accounts (that is: when the same tag is used for multiple contacts, all entries with the tag are merged into a single metacontact whether they reside on the same of different accounts).</p>
@ -114,7 +114,6 @@
@@ -114,7 +114,6 @@
<!--As metacontacts are especially useful when used across multiple accounts, examples are also provided for actions across two accounts.
<section2topic='Retrieving metacontact data (account 1)'anchor='dualaccount-get1'>
<section2topic='Creating a metacontact'anchor='creating'>
Creation of a metacontact is uncomplicated; the simple addition of meta tag with a common tag results in a new metacontact.
<p>Creation of a metacontact is uncomplicated; the simple addition of meta tag with a common tag results in a new metacontact.</p>
</section2>
<section2topic='Removing a metacontact'anchor='removing'>
Similarly, to remove a metacontact all that is required is to remove the meta tags which contribute to the metacontact.
<p>Similarly, to remove a metacontact all that is required is to remove the meta tags which contribute to the metacontact.</p>
</section2>
<section2topic='Uniqueness of order within a metacontact'anchor='uniqueness'>
<p>Although it is unavoidable that multiple contacts within a metacontact MAY have the same order (due to potentially unavailable information from other accounts), clients SHOULD NOT apply the same order to multiple members of the same metacontact where it is possible to avoid it. If multiple members of a metacontact have the same order, the behaviour is dependent upon the client; it MAY apply rules itself to determine which member to communicate with (based upon presence, recent activity or other methods) it MAY present the user with the option to sort the members such that the orders are again unique, or it MAY employ another appropriate action.</p>
<p>The following use cases describe tasks which are already covered by &xep0060; in a more generic context. These tasks are again being provided here in order to demonstrate the functionality provided by this protocol and convey the structure and syntax of the file listing. As a result of this close relationship, many details of PubSub are omitted here for brevity. Consult &xep0060; and &xep0248; for the full specification of node and user management commands as well as their server responses.</p>
<p>Juliet wishes to make her sonnets available for retrieval by the public. She creates a Root Pubsub Collection Node which will contain her file listing:</p>
<examplecaption='Creating a New File Listing'><code><![CDATA[<iqtype='set'
<examplecaption='Creating a New File Listing'><![CDATA[<iqtype='set'
from='juliet@capulet.com/balcony'
to='pubsub.shakespeare.lit'
id='create3'>
@ -140,11 +135,9 @@
@@ -140,11 +135,9 @@
</configure>
</pubsub>
</iq>
]]></code></example>
]]></example>
<p>Juliet also wishes to add a subsection for her sonnets about Romeo. She creates another PubSub Collection Node under the Root Node:</p>
<examplecaption='Adding a Subsection to the Listing'><code><![CDATA[<iqtype='set'
<examplecaption='Adding a Subsection to the Listing'><![CDATA[<iqtype='set'
<p>Romeo wishes to view all of Juliet's shared sonnets. To do this, Romeo subscribes to the Root Collection Node:</p>
<examplecaption='Subscription to entire File Listing'><code><![CDATA[<iqtype='set'
<examplecaption='Subscription to entire File Listing'><![CDATA[<iqtype='set'
from='romeo@montague.net/orchard'
to='pubsub.shakespeare.lit'
id='collsub2'>
@ -202,14 +192,11 @@
@@ -202,14 +192,11 @@
</options>
</pubsub>
</iq>
]]></code></example>
]]></example>
</section3>
<section3topic='Addition'anchor='list-addition'>
<p>Juliet has just finished a new sonnet and wishes to announce its availability on her File Listing. She adds the sonnet as a new PubSub Node stored in her Collection Node, then inserts a first revision of her sonnet as an Item within that Node:</p>
<examplecaption='Adding a new File'><code><![CDATA[<iqtype='set'
<examplecaption='Adding a new File'><![CDATA[<iqtype='set'
from='juliet@capulet.com/balcony'
to='pubsub.shakespeare.lit'
id='create4'>
@ -311,8 +298,7 @@
@@ -311,8 +298,7 @@
</publish>
</pubsub>
</iq>
]]></code></example>
]]></example>
<p>The Item ID is set to 1, signifying the first revision for this file. Subsequent revisions/items will have incremented ID values, like one would see in a versioning system such as CVS or SVN. Implementations MAY follow this convention, but are not required to do so. For example, a given implementation may instead mark revisions using version numbers ("Beta 1", "6.2", etc) or use other arbitrary strings. However, no two revisions of a given file may share the same ID.</p>
<p>Node IDs MAY take the form of "path/to/file.ext", rather than the randomized string "a6190c5d38e22452041d1c5798eff3f5" provided in the above use case. For example, Juliet's sonnet MAY instead use a Node ID of "juliets_sonnets/sonnet.txt", as long as this ID is unique within the PubSub server. Randomized strings are used in this document to illustrate that Node IDs SHOULD NOT be used for providing information about files.</p>
<p>Here is a listing of the possible metadata in a file revision (Item), each field is OPTIONAL:</p>
@ -326,8 +312,7 @@
@@ -326,8 +312,7 @@
<tr><th>Mirrors</th><td>A list of mirrors; their properties are defined below. If no downloads are available, MAY be left empty or removed entirely.</td></tr>
</table>
<p>Because Romeo is now subscribed, he receives notice of Juliet's addition:</p>
<examplecaption='Notification of Addition'><code><![CDATA[<message from='pubsub.shakespeare.lit' to='romeo@montague.net' id='create4'>
<examplecaption='Notification of Addition'><![CDATA[<message from='pubsub.shakespeare.lit' to='romeo@montague.net' id='create4'>
<p>The above examples give a listing of several possible file transfer protocols in example configurations. Only the sipub mirror type is REQUIRED; the other types are OPTIONAL. Here is a full listing of those protocols and their available settings:</p>
<p>Juliet has revised her sonnet and wishes to publish the new version, while still leaving the original copy available for retrieval. To do this, she inserts a new Item, representing her new revision, into the file's Node:</p>
<examplecaption='Adding a new Revision'><code><![CDATA[<iqtype='set'
<examplecaption='Adding a new Revision'><![CDATA[<iqtype='set'
<p>Juliet has uploaded a copy of her revised sonnet to a new mirror, and wishes to let her subscribers know about this secondary source. She is able to do this by modifying the revision in question to include a reference to her website, overwriting the existing mirrors in the Item with an updated list:</p>
<examplecaption='Modifying a Revision'><code><![CDATA[<iqtype='set'
<examplecaption='Modifying a Revision'><![CDATA[<iqtype='set'
from='juliet@capulet.com/balcony'
to='pubsub.shakespeare.lit'
id='publish1'>
@ -501,11 +481,10 @@
@@ -501,11 +481,10 @@
</publish>
</pubsub>
</iq>
]]></code></example>
]]></example>
<p>Juliet now wishes to allow others to contribute to her sonnet collection. She gives owner access for the entire Listing to Romeo, and publisher access to her nurse:</p>
<p>Romeo is interested in seeing what files Juliet has made available. To do this, Romeo sends a request to Juliet for repositories which she is associated with:</p>
<examplecaption='Request for File Repository listing'><code><![CDATA[<iqtype='get'
<examplecaption='Request for File Repository listing'><![CDATA[<iqtype='get'
from='romeo@montague.net/orchard'
to='juliet@capulet.com'
id='repolistreq'>
@ -549,11 +527,11 @@
@@ -549,11 +527,11 @@
<list/>
</fileshare>
</iq>
]]></code></example>
]]></example>
<p>Juliet responds with a list of PubSub nodes where she has published files or which she believes would be interesting to Romeo. If no such locations exist, Juliet SHOULD respond with an empty list.</p>
<p>After browsing Juliet's repository, Romeo has chosen to download her sonnet. The most recent revision of this file contains a listing of available mirrors, and Romeo sees that one of them is an SI stream. Romeo sends an SI request to that mirror:</p>
<examplecaption='Request that a file be sent'><code><![CDATA[<iqtype='get'
<examplecaption='Request that a file be sent'><![CDATA[<iqtype='get'
id='sipub-request-0'
from='romeo@montague.net/orchard'
to='fileserver@capulet.com'>
<startxmlns='http://jabber.org/protocol/sipub'
id='publish-sonnet2.txt'/>
</iq>
]]></code></example>
]]></example>
<p>The rest of the negotiation and file transfer occurs as described in &xep0137;.</p>
<remark><p>Addressed Last Call feedback and made editorial improvements.</p></remark>
</revision>
<revision>
<version>0.14</version>
<initials>ph</initials>
<date>2012-08-21</date>
<initials>ph</initials>
<remark><p>Updated the Security Considerations to describe the 'Unsolicited Dialback Attack' and added recommendations to avoid this attack.</p></remark>
</revision>
<revision>
<version>0.13</version>
<initials>ph/psa</initials>
<date>2012-08-08</date>
<initials>ph/psa</initials>
<remark>
<ul>
<li>Allowed same SRV target in multiplexing business</li>
<p>The following rules apply to generating and processing of the attention extension.
<ol>
<li>Before sending an attention message stanza, the client SHOULD confirm support for it in the other client as described under <linkurl='#disco'>Determining Support</link>.</li>
<li>The message stanza containing the attention extension MAY contain a body and/or other extensions, which is to be displayed along with executing the attention event.</li>
<li>In message stanzas containing either &xep0203; data, attention extensions MUST be ignored, since the attention request is an instant event which SHOULD NOT be replayed after a delay.</li>
<li>Messages containing an attention extension SHOULD use the headline message type to avoid offline storage.</li>
<li>The attention extension MUST NOT be sent in &IQ; stanzas, since use of this feature is part of a messaging conversation.</li>
</ol>
</p>
<p>The following rules apply to generating and processing of the attention extension.</p>
<ol>
<li>Before sending an attention message stanza, the client SHOULD confirm support for it in the other client as described under <linkurl='#disco'>Determining Support</link>.</li>
<li>The message stanza containing the attention extension MAY contain a body and/or other extensions, which is to be displayed along with executing the attention event.</li>
<li>In message stanzas containing either &xep0203; data, attention extensions MUST be ignored, since the attention request is an instant event which SHOULD NOT be replayed after a delay.</li>
<li>Messages containing an attention extension SHOULD use the headline message type to avoid offline storage.</li>
<li>The attention extension MUST NOT be sent in &IQ; stanzas, since use of this feature is part of a messaging conversation.</li>
<p>If an entity wishes to receive the attention extension, it MUST advertise that fact in its responses to &xep0030; information ("disco#info") requests by returning a feature of "urn:xmpp:attention:0":</p>
<p>Commands (= remote procedures) executed with Ad-Hoc Commands and IO Data SHOULD NOT keep the requester in an uncertain state. This means the responder SHOULD respond to the requester always as fast as possible. Thereby the requester acquires the sessionid. (As some remote procedures/calculations are cost-intensive and/or time-consuming the requester MUST "save" this sessionid for the case a network problem occurs.)</p>
<p>The Ad-Hoc Command logic applied for the IO Data data container should be associated with the following rules and keywords:</p>
<tableborder="1"caption='Subsequently allowed Ad-Hoc Commands are depending on the state of the service'>
<thead>
<tr>
<th>Ad-Hoc Command</th>
<th>Keyword</th>
<th>Associated Transaction Type</th>
<th>Subsequently allowed commands</th>
<th>Status description</th>
</tr>
</thead>
<tablecaption='Subsequently allowed Ad-Hoc Commands are depending on the state of the service'>
<p>Each recipient's client would then show the message with a special presentation, such as:</p>
<examplecaption="Presentation of /me Command">
<spanstyle='margin-left: 5%; font-style: italic; color: green;'>* Atlas shrugs in disgust</span>
* Atlas shrugs in disgust
</example>
<p>If the receiving client does not find a match on the string "/me " in the first four characters of the message body, it SHOULD NOT present the text in a special way. For example, the following message bodies do not match:</p>
<p>&xep0045; rooms send XMPP presence stanzas when people leave and join the room, and receiving clients typically show these presence changes as the equivalent of in-room messages, such as the following transformation of a presence stanza of type unavailable:</p>
<examplecaption="Presentation of In-Room Presence Notification">
<spanstyle='margin-left: 5%; font-style: italic; color: green;'>*** Atlas has left the room</span>
*** Atlas has left the room
</example>
<p>A sender could attempt to spoof such a leave message by sending an XMPP groupchat message stanza whose body text is "/me has left the room". Although the presentation of presence joins and leaves is determined by the receiving client and therefore such a notification cannot be universally spoofed for all receivers, a client SHOULD differentiate between presence notifications and /me commands (e.g., with different colors and different prepended characters, such as several asterisks for presence notifications and one asterisk for /me commands).</p>
<dd>A type of node that contains other nodes but no published items (<em>c.f.</em> Leaf Node).</dd>
</di>
<di>
<dt>Leaf Node</dt>
<dd>A type of node that contains published items but no other nodes (<em>c.f.</em> Collection Node).</dd>
</di>
<di>
<dt>Node Graph</dt>
<dd>The network of nodes emitting from a given node which contains all its descendants.</dd>
</di>
<di>
<dt>Root Node</dt>
<dd>An anonymous collection node used as the <em>de facto</em> beginning of a service's node graph.</dd>
</di>
<di>
<dt>Subscription Depth</dt>
<dd>How deep the collection node graph will be traversed when determining whether notifications will be sent. May be any integer, 0 or greater, or "all".</dd>
</di>
<di>
<dt>Subscription Type</dt>
<dd>The type of notification, either "nodes", "items", or "all" which the subscriber is interested in.</dd>
<section2topic='Changes to the Response Syntax'anchor='script-response'>
<p>Connection managers MUST make the following changes to convert their responses to Script Syntax:</p>
<ol>
<li><p>Certain characters within the <body/> element MUST be replaced according to the rules for escaping characters within strings defined by <cite>ECMAScript</cite>. The necessary substitutions are summarised in the table below.</p>
<tablecaption='Character Substitutions'>
<tr><th>Character</th><th>Unicode Code Point Value</th><th>Escape sequence</th></tr>
<tr><td>"</td><td>U+0022</td><td>\"</td></tr>
<tr><td>Line Feed (New Line)</td><td>U+000A</td><td>\n</td></tr>
<p>Each Unicode format-control character (i.e., the characters in category "Cf" in the Unicode Character Database, e.g., LEFT-TO-RIGHT MARK or RIGHT-TO-LEFT MARK) MUST also be substituted by its Unicode escape sequence (e.g. \u200e or \u200f).</p></li>
<li><p>The following eight characters MUST be prepended to the <body/> element: <code>_BOSH_("</code></p></li>
<li><p>The following two characters MUST be appended to the <body/> element:<code>")</code></p></li>
<li><p>If the client request does not possess a 'content' attribute, then the HTTP Content-Type header of responses MUST be either "text/javascript; charset=utf-8" or "application/x-javascript; charset=utf-8".</p></li>
<li><p>Include extra HTTP headers to prevent caching or storage by any intermediary.</p></li>
</ol>
<p>1. Certain characters within the <body/> element MUST be replaced according to the rules for escaping characters within strings defined by <cite>ECMAScript</cite>. The necessary substitutions are summarised in the table below.</p>
<tablecaption='Character Substitutions'>
<tr><th>Character</th><th>Unicode Code Point Value</th><th>Escape sequence</th></tr>
<tr><td>"</td><td>U+0022</td><td>\"</td></tr>
<tr><td>Line Feed (New Line)</td><td>U+000A</td><td>\n</td></tr>
<p>Each Unicode format-control character (i.e., the characters in category "Cf" in the Unicode Character Database, e.g., LEFT-TO-RIGHT MARK or RIGHT-TO-LEFT MARK) MUST also be substituted by its Unicode escape sequence (e.g. \u200e or \u200f).</p>
<p>2. The following eight characters MUST be prepended to the <body/> element:</p>
<code>_BOSH_("</code>
<p>3. The following two characters MUST be appended to the <body/> element:</p>
<code>")</code>
<p>4. If the client request does not possess a 'content' attribute, then the HTTP Content-Type header of responses MUST be either "text/javascript; charset=utf-8" or "application/x-javascript; charset=utf-8".</p>
<p>5. Include extra HTTP headers to prevent caching or storage by any intermediary.</p>
<p>Note: All line breaks in the bodies of the HTTP responses in the following two examples are included only to improve readability. In practice there MUST be no line breaks.</p>
<examplecaption="Session creation response in Script Syntax">
<p>Information about location references in the entity's surrounding, and, if available, the entity's own 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 <locationquery/> element that is qualified by the 'urn:xmpp:locationquery:0' namespace and nested with in a <iq> element with type set to <i>get</i>. The location result is provided by the location server and returned to the client in a <iq> element with type set to <i>result</i>. The location result is structured by means of a <geoloc/> element that is qualified by the 'http://jabber.org/protocol/geoloc' namespace (see <ahref="../xep-0080.html">XEP-0080</a>).</p>
<p>Information about location references in the entity's surrounding, and, if available, the entity's own 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 <locationquery/> element that is qualified by the 'urn:xmpp:locationquery:0' namespace and nested with in a <iq> element with type set to <em>get</em>. The location result is provided by the location server and returned to the client in a <iq> element with type set to <em>result</em>. The location result is structured by means of a <geoloc/> element that is qualified by the 'http://jabber.org/protocol/geoloc' namespace (see <linkurl="xep-0080.html">XEP-0080</link>).</p>
<tablecaption='Location Query Child Elements'>
<trclass="body">
<tr>
<th>Element Name</th>
<th>Datatype</th>
<th>Definition</th>
<th>Example</th>
<th>Notes</th>
</tr>
<trclass="body">
<tr>
<td>timestamp</td>
<td>xs:datetime</td>
<td>UTC time-stamp (MUST conform to the DateTime profile of &xep0082;). </td>
<td>2004-02-19T21:12Z</td>
<td>Optional. If individual location references contain own timing information, this time-stamp shall represent GPS time only, otherwise it shall represent all provided info in the query. If not set, the server may assume current time.</td>
</tr>
<trclass="body">
<tr>
<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 <iq> 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 <iq> with type set to "result". Default is "false"</td>
</tr>
<trclass="body">
<tr>
<td>lat</td>
<td>xs:decimal</td>
<td>Latitude in decimal degrees
@ -428,14 +427,14 @@
@@ -428,14 +427,14 @@
<td>39.75</td>
<td>Required if no location references 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 reference 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 reference data or time history information. For instance: if the entity is indoors, the GPS signal will be inaccurate and unstable over time. If wifi references are submitted, the location server may decide that the entity is inside a known building, and return the latitude of this instead.</td>
</tr>
<trclass="body">
<tr>
<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>
<td>See notes for <em>lat</em></td>
</tr>
<trclass="body">
<tr>
<td>alt</td>
<td>xs:decimal</td>
<td>Altitude in meters above or below sea level</td>
@ -443,48 +442,48 @@
@@ -443,48 +442,48 @@
<td>Optional. If present, this shall also be present in the result stanza with identical value.</td>
</tr>
<trclass="body">
<tr>
<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>
<td>See notes for <em>alt</em></td>
</tr>
<trclass="body">
<tr>
<td>datum</td>
<td>xs:string</td>
<td>GPS datum (See XEP-0080)</td>
<td></td>
<td>See notes for <i>alt</i></td>
<td>See notes for <em>alt</em></td>
</tr>
<trclass="body">
<tr>
<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>
<td>See notes for <em>lat</em></td>
</tr>
<trclass="body">
<tr>
<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>
<td>See notes for <em>alt</em></td>
</tr>
<trclass="body">
<tr>
<td>references</td>
<td>locationquery:reference</td>
<td>A list of identifiable location references 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>
<td>Required if no <em>lat</em> and <em>lon</em> values specified, otherwise optional. See Table 2 for type definition.</td>
</tr>
</table>
<tablecaption='Reference Child Elements'>
<trclass="body">
<tr>
<th>Element Name</th>
<th>Datatype</th>
<th>Definition</th>
@ -492,28 +491,28 @@
@@ -492,28 +491,28 @@
<th>Notes</th>
</tr>
<trclass="body">
<tr>
<td>id</td>
<td>xs:string</td>
<td>A world-wide unique reference 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 <linkurl="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.<br/><br/>For IP addresses: the IP address itself (either IPv4 or IPv6).</td>
<td>A world-wide unique reference identifier. This SHALL be composed as follows: For cell towers: "MCC:MNC:LAC:CID" where MCC is the mobile country code <note>Values of Mobile Country Codes (MCC) are specified by <linkurl="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.For wireless access points and Bluetooth devices: The device MAC address.For IP addresses: the IP address itself (either IPv4 or IPv6).</td>
<td>207:02:12643:78596</td>
<td>Required</td>
</tr>
<trclass="body">
<tr>
<td>type</td>
<td>xs:string</td>
<td>Reference type as maintained in the registry specified under <linkurl='#registrar-reftypes'>Reference Types Registry</link></td>
<td>"cell"</td>
<td>Required.</td>
</tr>
<trclass="body">
<tr>
<td>signalstrength</td>
<td>xs:int</td>
<td>Reference signal strength in dBM. Only appliccable to actively transmitting references (cell towers, wifi access points, Bluetooth devices)</td>
<td>-64</td>
<td>Optional.</td>
</tr>
<trclass="body">
<tr>
<td>timestamp</td>
<td>xs:datetime</td>
<td>UTC time-stamp (MUST conform to the DateTime profile of &xep0082;). </td>
@ -523,22 +522,22 @@
@@ -523,22 +522,22 @@
</table>
<tablecaption='Location Result Child Elements (Copied from XEP-0080 with notes added)'>
<trclass="body">
<tr>
<th>Element Name</th>
<th>Datatype</th>
<th>Definition</th>
<th>Example</th>
<th>Notes</th>
</tr>
<trclass="body">
<tr>
<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>
<td>Piped directly through from query <em>alt</em> field if set.</td>
</tr>
<trclass="body">
<tr>
<td>area</td>
<td>xs:string</td>
<td>A named area such as a campus or neighborhood</td>
@ -546,15 +545,15 @@
@@ -546,15 +545,15 @@
<td></td>
</tr>
<trclass="body">
<tr>
<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>
<td>Piped directly through from query <em>bearing</em> field if set.</td>
</tr>
<trclass="body">
<tr>
<td>building</td>
<td>xs:string</td>
<td>A specific building on a street or in an area</td>
@ -562,7 +561,7 @@
@@ -562,7 +561,7 @@
<td></td>
</tr>
<trclass="body">
<tr>
<td>country</td>
<td>xs:string</td>
<td>The nation where the user is located</td>
@ -570,14 +569,14 @@
@@ -570,14 +569,14 @@
<td></td>
</tr>
<trclass="body">
<tr>
<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>
<td>Piped directly through from query <em>datum</em> field if set.</td>
</tr>
<trclass="body">
<tr>
<td>description</td>
<td>xs:string</td>
<td>A natural-language name for or description of the location</td>
@ -585,15 +584,15 @@
@@ -585,15 +584,15 @@
<td>If location is mapped to a place in a place oriented service, this should hold the place description.</td>
</tr>
<trclass="body">
<tr>
<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>
<td>Piped directly through from query <em>accuracy</em> 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>
<trclass="body">
<tr>
<td>floor</td>
<td>xs:string</td>
<td>A particular floor in a building</td>
@ -601,16 +600,16 @@
@@ -601,16 +600,16 @@
<td></td>
</tr>
<trclass="body">
<tr>
<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>
<td>Piped directly through from query <em>lat</em> field or estimated by location server based on the other information in query and, if possible, differences between several queries over time.</td>
</tr>
<trclass="body">
<tr>
<td>locality</td>
<td>xs:string</td>
<td>A locality within the administrative region, such as a town or city</td>
@ -618,15 +617,15 @@
@@ -618,15 +617,15 @@
<td></td>
</tr>
<trclass="body">
<tr>
<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>
<td>Piped directly through from query <em>lon</em> or estimated by location server based on the other information in query and, if possible, differences between several queries over time.</td>
</tr>
<trclass="body">
<tr>
<td>postalcode</td>
<td>xs:string</td>
<td>A code used for postal delivery</td>
@ -634,7 +633,7 @@
@@ -634,7 +633,7 @@
<td></td>
</tr>
<trclass="body">
<tr>
<td>region</td>
<td>xs:string</td>
<td>An administrative region of the nation, such as a state or province</td>
@ -642,7 +641,7 @@
@@ -642,7 +641,7 @@
<td></td>
</tr>
<trclass="body">
<tr>
<td>room</td>
<td>xs:string</td>
<td>A particular room in a building</td>
@ -650,15 +649,15 @@
@@ -650,15 +649,15 @@
<td></td>
</tr>
<trclass="body">
<tr>
<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>
<td>Piped directly through from query <em>speed</em> field or estimated by location server based on the other information in query and, if possible, differences between several queries over time.</td>
</tr>
<trclass="body">
<tr>
<td>street</td>
<td>xs:string</td>
<td>A thoroughfare within the locality, or a crossing of two thoroughfares</td>
@ -666,7 +665,7 @@
@@ -666,7 +665,7 @@
<td></td>
</tr>
<trclass="body">
<tr>
<td>text</td>
<td>xs:string</td>
<td>A catch-all element that captures any other information about the location</td>
@ -674,15 +673,15 @@
@@ -674,15 +673,15 @@
<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>
<trclass="body">
<tr>
<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>
<td>Piped directly through from query <em>timestamp</em> field.</td>
</tr>
<trclass="body">
<tr>
<td>uri</td>
<td>A URI or URL pointing to
information about the location</td>
@ -694,7 +693,7 @@
@@ -694,7 +693,7 @@
</table>
<p>NOTE: The datatypes specified above are defined in &w3xmlschema2;.</p>
<p>For the reasons mentioned above, it is recommended that the client supply both GPS coordinates as well as nearby location references 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 location references change (e.g. a new cell tower is seen or an old one is not seen any more)</p>
<p>For the reasons mentioned above, it is recommended that the client supply both GPS coordinates as well as nearby location references 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. For optimal results, clients SHOULD post a location query any time when the set of observed location references change (e.g. a new cell tower is seen or an old one is not seen any more)</p>
<p>This document requires no interaction with the <spanclass="ref"style=""><ahref="http://www.iana.org/">Internet Assigned Numbers Authority (IANA)</a></span> [<ahref="notes_iana">7</a>].</p>
<p>This document requires no interaction with the &IANA;.</p>
Sam Whited
5 years ago