[telepathy-gabble/master] Connection_Interface_Location.xml: update to latest DRAFT
Guillaume Desmottes
guillaume.desmottes at collabora.co.uk
Thu Aug 6 07:23:32 PDT 2009
---
extensions/Connection_Interface_Location.xml | 120 +++++++++++++++++++-------
1 files changed, 90 insertions(+), 30 deletions(-)
diff --git a/extensions/Connection_Interface_Location.xml b/extensions/Connection_Interface_Location.xml
index 1e7bee4..ea9f6ad 100644
--- a/extensions/Connection_Interface_Location.xml
+++ b/extensions/Connection_Interface_Location.xml
@@ -20,6 +20,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:license>
<interface name="org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT"
tp:causes-havoc='experimental'>
+ <tp:added version="0.17.18">(as a draft)</tp:added>
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
@@ -49,6 +50,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
possible.</p>
</tp:docstring>
+ <!-- Potentially to be reinstated later:
+ http://bugs.freedesktop.org/show_bug.cgi?id=19585
<tp:enum name="Location_Accuracy_Level" type="i">
<tp:docstring>
A location accuracy level. This should be kept in sync with
@@ -88,11 +91,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</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.
+ The location's accuracy is given by the accuracy key.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
+ -->
<tp:mapping name="Location">
<tp:docstring>
@@ -136,6 +139,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
information about it</li>
</ul>
+ <p>Since the previous strings have data intended to be read by users,
+ the language used should be stated using:</p>
+
+ <ul>
+ <li>language - s: a specific language or locale of location
+ information in a format compatible to RFC 4646. Note that UTF-8
+ is the only allowed encoding, e.g. "en" or "fr-CA".</li>
+ </ul>
+
<p>Positions are represented by the following well-known keys:</p>
<ul>
@@ -163,6 +175,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
This is from XEP-0080
</tp:rationale>
</li>
+
+ <!-- Potentially to be reinstated later:
+ http://bugs.freedesktop.org/show_bug.cgi?id=19585
<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
@@ -173,24 +188,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
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
+ -->
+
+ <li>accuracy - 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.
+ This is from XEP-0080
</tp:rationale>
</li>
</ul>
@@ -210,18 +213,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
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
+ <li>timestamp - x (<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>
@@ -241,9 +238,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:mapping>
<tp:mapping name="Contact_Locations" type="a{ua{sv}}">
+ <tp:docstring>
+ A map from contacts to their locations.
+ </tp:docstring>
<tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>A contact</tp:docstring>
</tp:member>
<tp:member name="Location" type="a{sv}" tp:type="Location">
+ <tp:docstring>The contact's location, which MAY be empty to indicate
+ that the contact's location is unknown</tp:docstring>
</tp:member>
</tp:mapping>
@@ -251,10 +254,16 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<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.
+ request their current locations, but return immediately without waiting
+ for a reply; if a reply with a non-empty location is later received
+ for those contacts, the <tp:member-ref>LocationUpdated</tp:member-ref>
+ signal will be emitted for them.
+
+ <tp:rationale>
+ This method is appropriate for "lazy" location finding, for instance
+ displaying the location (if available) of everyone in your contact
+ list.
+ </tp:rationale>
</tp:docstring>
<arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
@@ -272,6 +281,51 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
Location dictionary.
</tp:docstring>
</arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RequestLocation" tp:name-for-bindings="Request_Location">
+ <tp:docstring>
+ Return the current location of the given contact. If necessary, make
+ a request to the server for up-to-date information, and wait for a
+ reply.
+
+ <tp:rationale>
+ This method is appropriate for use in a "Contact Information..."
+ dialog; it can be used to show progress information (while waiting
+ for the method to return), and can distinguish between various error
+ conditions.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact whose location should be returned.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Location" type="a{sv}" tp:type="Location">
+ <tp:docstring>
+ The contact's location. It MAY be empty, indicating that no location
+ information was found.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied">
+ <tp:docstring>
+ The requested contact does not allow the local user to see their
+ location information.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
</method>
<signal name="LocationUpdated" tp:name-for-bindings="Location_Updated">
@@ -292,7 +346,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</arg>
</signal>
- <method name="SetLocation" tp:name-for-bindings="SetLocation">
+ <method name="SetLocation" tp:name-for-bindings="Set_Location">
<tp:docstring>
Set the local user's own location.
</tp:docstring>
@@ -309,6 +363,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
and averaging the locations advertised on multiple connections.
</tp:docstring>
</arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
</method>
<property name="LocationAccessControlTypes" type="au" access="read"
--
1.5.6.5
More information about the telepathy-commits
mailing list