Corrected name-space in section 10.1. Removed extra 's in example 7. Made time-stamp optional. Added optional time-stamp to beacon element. Added comment reflecting that query time-stamp applies to GPS coordinates if beacons provide own time-stamps.

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2594 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0255.xml

@@ -43,6 +43,20 @@
     <jid>ross@buddycloud.com</jid>
 
   </author>
+  <revision>
+    <version>0.3</version>
+    <date>2008-12-20</date>
+    <initials>ht</initials>
+    <remark>
+      <ul>
+        <li>Corrected name-space in section 10.1.</li>
+        <li>Removed extra 's in example 7 </li>
+        <li>Made time-stamp optional</li>
+        <li>Added optional time-stamp to beacon element</li>
+        <li>Added comment reflecting that query time-stamp applies to GPS coordinates if beacons provide own time-stamps</li>
+      </ul>
+    </remark>
+  </revision>
   <revision>
     <version>0.2</version>
     <date>2008-12-17</date>
@@ -137,7 +151,7 @@
     type='result' 
     xml:lang='en-US'>
   <geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
-    <timestamp>1599-10-23T01:55:21Z</timestamp>
+    <timestamp>1599-10-23T01:56:05Z</timestamp>
     <lat>57.0501862</lat>
     <lon>9.9188746</lon>
     <accuracy>35.6</accuracy>
@@ -180,7 +194,7 @@
     type='result' 
     xml:lang='en-US'>
   <geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
-    <timestamp>1599-10-23T01:55:21Z</timestamp>
+    <timestamp>1599-10-23T01:56:05Z</timestamp>
     <lat>57.050122</lat>
     <lon>9.918833</lon>
     <locality>Aalborg</locality>
@@ -193,7 +207,7 @@
 <iq>
   ]]></example>
 
-  <example caption='Entity queries server and specifies that results should be published'><![CDATA[
+  <example caption='Entity queries server with beacon info from multiple scans and specifies that results should be published'><![CDATA[
 <iq from='hamlet@shakespeare.lit/phone' 
     id='q03' 
     to='location.shakespear.lit' 
@@ -209,16 +223,31 @@
       <id>238:02:34775:50880</id>
       <type>cell</type>
       <signalstrength>-88</signalstrength>
+      <timestamp>1599-10-23T01:55:21Z</timestamp>
+    </beacon>
+    <beacon>
+      <id>238:02:34775:48770</id>
+      <type>cell</type>
+      <signalstrength>-76</signalstrength>
+      <timestamp>1599-10-23T01:52:34Z</timestamp>
     </beacon>
     <beacon>
       <id>00:0F:3D:42:92:2A</id>
       <type>wifi</type>
       <signalstrength>-64</signalstrength>
+      <timestamp>1599-10-23T01:55:21Z</timestamp>
+    </beacon>
+    <beacon>
+      <id>238:02:34775:50880</id>
+      <type>cell</type>
+      <signalstrength>-88</signalstrength>
+      <timestamp>1599-10-23T01:55:21Z</timestamp>
     </beacon>
     <beacon>
       <id>00:19:CB:45:50:4A</id>
       <type>wifi</type>
       <signalstrength>-82</signalstrength>
+      <timestamp>1599-10-23T01:52:24Z</timestamp>
     </beacon>
     <beacon>
       <id>00:18:42:E6:71:51</id>
@@ -243,11 +272,11 @@
     type='set' 
     xml:lang='en-US'>
   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
-    <publish'>
+    <publish>
       <node xmlns='http://jabber.org/protocol/geoloc'>
-        <item'>
+        <item>
           <geoloc xmlns='http://jabber.org/protocol/geoloc' xml:lang='en'>
-            <timestamp>1599-10-23T01:55:21Z</timestamp>
+            <timestamp>1599-10-23T01:56:05Z</timestamp>
             <lat>57.0501862</lat>
             <lon>9.918874</lon>
             <street>Jomfru Ane Gade 13</street>
@@ -270,7 +299,7 @@
     <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>
+          <timestamp>1599-10-23T01:56:05Z</timestamp>
           <lat>57.0501862</lat>
           <lon>9.918874</lon>
           <street>Jomfru Ane Gade 13</street>
@@ -290,7 +319,7 @@
     <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>
+          <timestamp>1599-10-23T01:56:05Z</timestamp>
           <lat>57.0501862</lat>
           <lon>9.918874</lon>
           <street>Jomfru Ane Gade 13</street>
@@ -323,22 +352,19 @@
       <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>UTC time-stamp (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>
+         <td>Optional. If individual beacons 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>
       <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>
@@ -347,19 +373,15 @@
       </tr>
       <tr class="body">
          <td>lon</td>
-
          <td>xs:decimal</td>
-         <td>Longitude in decimal degrees
+         <td>Longitude in decimal degrees East</td>
-         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
+         <td>Altitude in meters above or below sea level</td>
-         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>
@@ -367,9 +389,7 @@
       <tr class="body">
          <td>bearing</td>
          <td>xs:decimal</td>
-         <td>GPS bearing (direction in which
+         <td>GPS bearing (direction in which the entity is heading to reach its next waypoint), measured in decimal degrees relative to true north</td>
-         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>
 
@@ -393,17 +413,14 @@
       <tr class="body">
          <td>speed</td>
          <td>xs:decimal</td>
-         <td>The speed at which the entity is
+         <td>The speed at which the entity is moving, in meters per second</td>
-         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>
@@ -422,7 +439,6 @@
          <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>
@@ -430,7 +446,6 @@
          <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>
@@ -441,12 +456,18 @@
          <td>-64</td>
          <td>Optional.</td>
       </tr>
+      <tr class="body">
+         <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 query contains info from multiple beacon scans, specifying the timestamp for each beacon may lead to improved temporal analysis (movement state etc).</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>
@@ -454,10 +475,8 @@
       </tr>
       <tr class="body">
          <td>alt</td>
-
          <td>xs:decimal</td>
-         <td>Altitude in meters above or
+         <td>Altitude in meters above or below sea level</td>
-         below sea level</td>
          <td>1609</td>
          <td>Piped directly through from query <i>alt</i> field if set.</td>
       </tr>
@@ -465,8 +484,7 @@
       <tr class="body">
          <td>area</td>
          <td>xs:string</td>
-         <td>A named area such as a campus or
+         <td>A named area such as a campus or neighborhood</td>
-         neighborhood</td>
          <td>Central Park</td>
          <td> </td>
 
@@ -474,9 +492,7 @@
       <tr class="body">
          <td>bearing</td>
          <td>xs:decimal</td>
-         <td>GPS bearing (direction in which
+         <td>GPS bearing (direction in which the entity is heading to reach its next waypoint), measured in decimal degrees relative to true north</td>
-         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>
 
@@ -484,8 +500,7 @@
       <tr class="body">
          <td>building</td>
          <td>xs:string</td>
-         <td>A specific building on a street
+         <td>A specific building on a street or in an area</td>
-         or in an area</td>
          <td>The Empire State Building</td>
          <td> </td>
 
@@ -493,8 +508,7 @@
       <tr class="body">
          <td>country</td>
          <td>xs:string</td>
-         <td>The nation where the user is
+         <td>The nation where the user is located</td>
-         located</td>
          <td>USA</td>
          <td> </td>
 
@@ -505,13 +519,11 @@
          <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
+         <td>A natural-language name for or description of the location</td>
-         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>
 
@@ -544,8 +556,7 @@
       <tr class="body">
          <td>locality</td>
          <td>xs:string</td>
-         <td>A locality within the
+         <td>A locality within the administrative region, such as a town or city</td>
-         administrative region, such as a town or city</td>
          <td>New York City</td>
          <td> </td>
 
@@ -553,8 +564,7 @@
       <tr class="body">
          <td>lon</td>
          <td>xs:decimal</td>
-         <td>Longitude in decimal degrees
+         <td>Longitude in decimal degrees East</td>
-         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>
 
@@ -570,8 +580,7 @@
       <tr class="body">
          <td>region</td>
          <td>xs:string</td>
-         <td>An administrative region of the
+         <td>An administrative region of the nation, such as a state or province</td>
-         nation, such as a state or province</td>
          <td>New York</td>
          <td> </td>
 
@@ -586,8 +595,7 @@
       </tr>
       <tr class="body">
          <td>speed</td>
-         <td>The speed at which the entity is
+         <td>The speed at which the entity is moving, in meters per second</td>
-         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>
@@ -596,8 +604,7 @@
       <tr class="body">
          <td>street</td>
          <td>xs:string</td>
-         <td>A thoroughfare within the
+         <td>A thoroughfare within the locality, or a crossing of two thoroughfares</td>
-         locality, or a crossing of two thoroughfares</td>
          <td>34th and Broadway</td>
          <td> </td>
 
@@ -605,8 +612,7 @@
       <tr class="body">
          <td>text</td>
          <td>xs:string</td>
-         <td>A catch-all element that
+         <td>A catch-all element that captures any other information about the location</td>
-         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>
 
@@ -675,7 +681,7 @@
   <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
     <p>This specification defines the following XML namespace:</p>
     <ul>
-      <li>urn:xmpp:jingle:transfer:0</li>
+      <li>urn:xmpp:locationquery: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>