Get the telepathy bits generated

4 files changed, 344 insertions, 0 deletions

diff --git a/extensions/Connection_Interface_Location.xml b/extensions/Connection_Interface_Location.xml
new file mode 100644
index 000000000..1e7bee4e0
--- /dev/null
+++ b/extensions/Connection_Interface_Location.xml
@@ -0,0 +1,330 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Location"
+  xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+  <tp:license xmlns="http://www.w3.org/1999/xhtml">
+    <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+  </tp:license>
+  <interface name="org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT"
+    tp:causes-havoc='experimental'>
+    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>An interface on connections to support protocols which allow users to
+        publish their current geographical location, and subscribe to the
+        current location of their contacts.</p>
+
+      <p>This interface is geared strongly towards automatic propagation and
+        use of this information, so focuses on latitude, longitude and
+        altitude which can be determined by GPS, although provision is also
+        included for an optional human-readable description of locations. All
+        co-ordinate information is required to be relative to the WGS84
+        datum.</p>
+
+      <p>The information published through this interface is intended to have
+        the same scope as presence information, so will normally be made
+        available to those individuals on the user's "publish" contact list.
+        Even so, user interfaces should not automatically publish location
+        information without the consent of the user, and it is recommended
+        that an option is made available to reduce the accuracy of the
+        reported information to allow the user to maintain their privacy.</p>
+
+      <p>Location information is represented using the terminology of XMPP's
+        <a href="http://www.xmpp.org/extensions/xep-0080.html">XEP-0080</a>
+        or the XEP-0080-derived
+        <a href="http://geoclue.freedesktop.org/">Geoclue</a> API where
+        possible.</p>
+    </tp:docstring>
+
+    <tp:enum name="Location_Accuracy_Level" type="i">
+      <tp:docstring>
+        A location accuracy level. This should be kept in sync with
+        GeoclueAccuracyLevel in the Geoclue project.
+      </tp:docstring>
+
+      <tp:enumvalue suffix="None" value="0">
+        <tp:docstring>
+          The accuracy is unspecified.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Country" value="1">
+        <tp:docstring>
+          The location indicates the contact's country.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Region" value="2">
+        <tp:docstring>
+          The location indicates the contact's region within a country.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Locality" value="3">
+        <tp:docstring>
+          The location indicates the contact's locality within a region
+          (e.g. the correct city).
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Postal_Code" value="4">
+        <tp:docstring>
+          The location indicates the correct postal code.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Street" value="5">
+        <tp:docstring>
+          The location indicates the correct street.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Detailed" value="6">
+        <tp:docstring>
+          The location's accuracy is given by the error, horizontal-error-m
+          and/or vertical-error-m keys.
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <tp:mapping name="Location">
+      <tp:docstring>
+        A user's location, represented as an extensible mapping.
+      </tp:docstring>
+
+      <tp:member name="Key" type="s">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+
+          <p>Civic addresses are represented by the following well-known
+            keys (all of which have string values), which should be kept in
+            sync with those used in XEP-0080 and in the Geoclue project:</p>
+
+          <ul>
+            <li>countrycode - s: an ISO-3166-1 alpha-2 (two-letter) country
+              code, e.g. "us", "gb", "fr"</li>
+            <li>country - s: a country name in unspecified locale, e.g.
+              "USA"</li>
+            <li>region - s: an administrative region of the nation, such as a
+              state or province</li>
+            <li>locality - s: a locality within the administrative region, such
+              as a town or city</li>
+            <li>area - s: a named area such as a campus or neighborhood</li>
+            <li>postalcode - s: a code used for postal delivery</li>
+            <li>street - s: a thoroughfare within the locality, or a crossing of
+              two thoroughfares</li>
+          </ul>
+
+          <p>The following address keys are defined in XEP-0080 but not by
+            Geoclue, and are also allowed:</p>
+
+          <ul>
+            <li>building - s: a specific building on a street or in an area</li>
+            <li>floor - s: a particular floor in a building</li>
+            <li>room - s: a particular room in a building</li>
+            <li>text - s: any more specific information, e.g.
+              "Northwest corner of the lobby"</li>
+            <li>description - s: A natural-language name for or description of
+              the location, e.g. "Bill's house"</li>
+            <li>uri - s: a URI representing the location or pointing to more
+              information about it</li>
+          </ul>
+
+          <p>Positions are represented by the following well-known keys:</p>
+
+          <ul>
+            <li>lat - d: latitude in decimal degrees north, -90 to +90,
+              relative to the WGS-84 datum
+              <tp:rationale>
+                This is from XEP-0080; the XEP allows use of a different
+                datum, but recommends this one. We enforce sanity by requiring
+                a consistent datum: a minimal compliant implementation of this
+                specification in terms of XEP-0080 would simply ignore the
+                &lt;lat&gt; and &lt;lon&gt; elements if &lt;datum&gt; exists
+                and has a value other than WGS-84, while an advanced
+                implementation might correct for the different datum.
+              </tp:rationale>
+            </li>
+            <li>lon - d: Longitude in decimal degrees east, -180 to +180,
+              relative to the WGS-84 datum
+              <tp:rationale>
+                Same rationale as 'lat'
+              </tp:rationale>
+            </li>
+            <li>alt - d: altitude in metres above sea level (negative
+              if below sea level)
+              <tp:rationale>
+                This is from XEP-0080
+              </tp:rationale>
+            </li>
+            <li>accuracy-level - i (<tp:type>Location_Accuracy_Level</tp:type>):
+              an indication of accuracy, which SHOULD be omitted if it would be
+              Location_Accuracy_Level_None or
+              Location_Accuracy_Level_Detailed
+              <tp:rationale>
+                This is a struct field in GeoClue; the name is new in this
+                specification, and was chosen in an attempt to avoid clashing
+                with any future XEP-0080 terminology.
+              </tp:rationale>
+            </li>
+            <li>error - d: horizontal position error in arc-minutes (1/60
+              degree) if known
+              <tp:rationale>
+                This is from XEP-0080
+              </tp:rationale>
+            </li>
+            <li>vertical-error-m - d: vertical position error in metres if
+              known
+              <tp:rationale>
+                This exists as a struct field in GeoClue; the name is new
+                in this specification.
+              </tp:rationale>
+            </li>
+            <li>horizontal-error-m - d: horizontal position error in metres if
+              known
+              <tp:rationale>
+                This exists as a struct field in GeoClue; the name is new
+                in this specification.
+              </tp:rationale>
+            </li>
+          </ul>
+
+          <p>Velocities are represented by the following well-known keys:</p>
+
+          <ul>
+            <li>speed - d: speed in metres per second
+              <tp:rationale>
+                This is from XEP-0080
+              </tp:rationale>
+            </li>
+            <li>bearing - d: direction of movement in decimal degrees,
+              where North is 0 and East is 90
+              <tp:rationale>
+                This is from XEP-0080, and is equivalent to the struct field
+                called "direction" in GeoClue
+              </tp:rationale>
+            </li>
+            <li>climb - d: rate of change of 'alt' in metres per second
+              <tp:rationale>
+                This is a struct field in GeoClue; the name is new to this
+                specification, but seems uncontroversial
+              </tp:rationale>
+            </li>
+          </ul>
+
+          <p>Other well-known keys:</p>
+
+          <ul>
+            <li>timestamp - t (<tp:type>Unix_Timestamp64</tp:type>): the time
+              that the contact was at this location, in seconds since
+              1970-01-01T00:00:00Z (i.e. the beginning of 1970 in UTC)
+              <tp:rationale>
+                XEP-0080 uses an ISO 8601 string for this, but a number of
+                seconds since the epoch is probably easier to work with.
+              </tp:rationale>
+            </li>
+          </ul>
+        </tp:docstring>
+      </tp:member>
+
+      <tp:member name="Value" type="v">
+        <tp:docstring>
+          The value corresponding to the well-known key.
+        </tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
+    <tp:mapping name="Contact_Locations" type="a{ua{sv}}">
+      <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+      </tp:member>
+      <tp:member name="Location" type="a{sv}" tp:type="Location">
+      </tp:member>
+    </tp:mapping>
+
+    <method name="GetLocations" tp:name-for-bindings="Get_Locations">
+      <tp:docstring>
+        Return the current locations of the given contacts, if they are
+        already known. If any of the given contacts' locations are not known,
+        request their current locations, and later emit
+        <tp:member-ref>LocationUpdated</tp:member-ref> for them; the
+        <tp:member-ref>LocationUpdated</tp:member-ref> signal for contacts
+        whose location could not be determined will have an empty Location.
+      </tp:docstring>
+
+      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+        <tp:docstring>
+          The contacts whose locations should be returned or signalled.
+        </tp:docstring>
+      </arg>
+
+      <arg direction="out" name="Locations" type="a{ua{sv}}"
+        tp:type="Contact_Locations">
+        <tp:docstring>
+          The contacts' locations, if already known. Contacts whose locations
+          are not already known are omitted from the mapping; contacts known
+          to have no location information appear in the mapping with an empty
+          Location dictionary.
+        </tp:docstring>
+      </arg>
+    </method>
+
+    <signal name="LocationUpdated" tp:name-for-bindings="Location_Updated">
+      <tp:docstring>
+        Emitted when a contact's location changes or becomes known.
+      </tp:docstring>
+
+      <arg name="Contact" type="u" tp:type="Contact_Handle">
+        <tp:docstring>
+          The contact
+        </tp:docstring>
+      </arg>
+      <arg name="Location" type="a{sv}" tp:type="Location">
+        <tp:docstring>
+          The contact's location, or empty to indicate that nothing is known
+          about the contact's location.
+        </tp:docstring>
+      </arg>
+    </signal>
+
+    <method name="SetLocation" tp:name-for-bindings="SetLocation">
+      <tp:docstring>
+        Set the local user's own location.
+      </tp:docstring>
+
+      <arg direction="in" name="Location" type="a{sv}">
+        <tp:docstring>
+          The location to advertise. If the user wants to obscure their
+          exact location by reducing the precision or accuracy, clients
+          MUST do this themselves, rather than relying on the connection
+          manager to do so. Clients that interact with more than one
+          connection SHOULD advertise the same reduced-accuracy location
+          to all of them, so that contacts cannot obtain an undesirably
+          accurate location by assuming that random errors have been added
+          and averaging the locations advertised on multiple connections.
+        </tp:docstring>
+      </arg>
+    </method>
+
+    <property name="LocationAccessControlTypes" type="au" access="read"
+      tp:type="Rich_Presence_Access_Control_Type[]" tp:name-for-bindings="Location_Access_Control_Types">
+      <tp:docstring>The types of access control that are supported by this
+        connection.</tp:docstring>
+    </property>
+
+    <property name="LocationAccessControl" type="(uv)" access="readwrite"
+      tp:type="Rich_Presence_Access_Control" tp:name-for-bindings="Location_Access_Control">
+      <tp:docstring>The current access control mechanism and settings
+        for this connection. Before publishing location for the first time,
+        if this has not been set by a client, implementations SHOULD
+        set it to be as restrictive as possible (an empty whitelist, if
+        supported).</tp:docstring>
+    </property>
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Makefile.am b/extensions/Makefile.am
index 7591109e8..3b154cdd9 100644
--- a/extensions/Makefile.am
+++ b/extensions/Makefile.am
@@ -15,6 +15,7 @@ EXTRA_DIST = \
     generic-types.xml \
     misc.xml \
     Channel_Handler.xml \
+    Connection_Interface_Location.xml \
     Tube_Handler.xml \
     Channel_Interface_Tube.xml \
     Channel_Type_DBus_Tube.xml \
diff --git a/extensions/all.xml b/extensions/all.xml
index c9f4c0bd7..85d9dde68 100644
--- a/extensions/all.xml
+++ b/extensions/all.xml
@@ -28,6 +28,18 @@
     from="Telepathy specification"/>
   <tp:external-type name="Tube_ID" type="u"
     from="Telepathy specification"/>
+
+  <!-- for localisation -->
+  <tp:external-type name="Rich_Presence_Access_Control_Type" type="u"
+    from="Telepathy specification"/>
+  <tp:external-type name="Rich_Presence_Access_Control" type="(uv)"
+    from="Telepathy specification"/>
+  <tp:external-type name="Unix_Timestamp64" type="t"
+    from="Telepathy specification"/>
+  <tp:external-type name="Unix_Timestamp" type="u"
+    from="Telepathy specification"/>
+  <tp:external-type name="String_String_Map" type="a{ss}"
+    from="Telepathy specification"/>
 </tp:generic-types>
 
 
diff --git a/extensions/misc.xml b/extensions/misc.xml
index 5c89ff0d8..a6ad1c648 100644
--- a/extensions/misc.xml
+++ b/extensions/misc.xml
@@ -9,5 +9,6 @@
 <xi:include href="Channel_Interface_Tube.xml" />
 <xi:include href="Channel_Type_DBus_Tube.xml" />
 <xi:include href="Channel_Type_Stream_Tube.xml" />
+<xi:include href="Connection_Interface_Location.xml"/>
 
 </tp:spec>