2 <node name="/Connection_Interface_Location"
3 xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
4 <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
5 <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
6 <tp:license xmlns="http://www.w3.org/1999/xhtml">
7 <p>This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Lesser General Public
9 License as published by the Free Software Foundation; either
10 version 2.1 of the License, or (at your option) any later version.</p>
12 <p>This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.</p>
17 <p>You should have received a copy of the GNU Lesser General Public
18 License along with this library; if not, write to the Free Software
19 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
21 <interface name="org.freedesktop.Telepathy.Connection.Interface.Location.DRAFT"
22 tp:causes-havoc='experimental'>
23 <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
25 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
26 <p>An interface on connections to support protocols which allow users to
27 publish their current geographical location, and subscribe to the
28 current location of their contacts.</p>
30 <p>This interface is geared strongly towards automatic propagation and
31 use of this information, so focuses on latitude, longitude and
32 altitude which can be determined by GPS, although provision is also
33 included for an optional human-readable description of locations. All
34 co-ordinate information is required to be relative to the WGS84
37 <p>The information published through this interface is intended to have
38 the same scope as presence information, so will normally be made
39 available to those individuals on the user's "publish" contact list.
40 Even so, user interfaces should not automatically publish location
41 information without the consent of the user, and it is recommended
42 that an option is made available to reduce the accuracy of the
43 reported information to allow the user to maintain their privacy.</p>
45 <p>Location information is represented using the terminology of XMPP's
46 <a href="http://www.xmpp.org/extensions/xep-0080.html">XEP-0080</a>
47 or the XEP-0080-derived
48 <a href="http://geoclue.freedesktop.org/">Geoclue</a> API where
52 <tp:enum name="Location_Accuracy_Level" type="i">
54 A location accuracy level. This should be kept in sync with
55 GeoclueAccuracyLevel in the Geoclue project.
58 <tp:enumvalue suffix="None" value="0">
60 The accuracy is unspecified.
63 <tp:enumvalue suffix="Country" value="1">
65 The location indicates the contact's country.
68 <tp:enumvalue suffix="Region" value="2">
70 The location indicates the contact's region within a country.
73 <tp:enumvalue suffix="Locality" value="3">
75 The location indicates the contact's locality within a region
76 (e.g. the correct city).
79 <tp:enumvalue suffix="Postal_Code" value="4">
81 The location indicates the correct postal code.
84 <tp:enumvalue suffix="Street" value="5">
86 The location indicates the correct street.
89 <tp:enumvalue suffix="Detailed" value="6">
91 The location's accuracy is given by the error, horizontal-error-m
92 and/or vertical-error-m keys.
97 <tp:mapping name="Location">
99 A user's location, represented as an extensible mapping.
102 <tp:member name="Key" type="s">
103 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
105 <p>Civic addresses are represented by the following well-known
106 keys (all of which have string values), which should be kept in
107 sync with those used in XEP-0080 and in the Geoclue project:</p>
110 <li>countrycode - s: an ISO-3166-1 alpha-2 (two-letter) country
111 code, e.g. "us", "gb", "fr"</li>
112 <li>country - s: a country name in unspecified locale, e.g.
114 <li>region - s: an administrative region of the nation, such as a
115 state or province</li>
116 <li>locality - s: a locality within the administrative region, such
117 as a town or city</li>
118 <li>area - s: a named area such as a campus or neighborhood</li>
119 <li>postalcode - s: a code used for postal delivery</li>
120 <li>street - s: a thoroughfare within the locality, or a crossing of
121 two thoroughfares</li>
124 <p>The following address keys are defined in XEP-0080 but not by
125 Geoclue, and are also allowed:</p>
128 <li>building - s: a specific building on a street or in an area</li>
129 <li>floor - s: a particular floor in a building</li>
130 <li>room - s: a particular room in a building</li>
131 <li>text - s: any more specific information, e.g.
132 "Northwest corner of the lobby"</li>
133 <li>description - s: A natural-language name for or description of
134 the location, e.g. "Bill's house"</li>
135 <li>uri - s: a URI representing the location or pointing to more
136 information about it</li>
139 <p>Positions are represented by the following well-known keys:</p>
142 <li>lat - d: latitude in decimal degrees north, -90 to +90,
143 relative to the WGS-84 datum
145 This is from XEP-0080; the XEP allows use of a different
146 datum, but recommends this one. We enforce sanity by requiring
147 a consistent datum: a minimal compliant implementation of this
148 specification in terms of XEP-0080 would simply ignore the
149 <lat> and <lon> elements if <datum> exists
150 and has a value other than WGS-84, while an advanced
151 implementation might correct for the different datum.
154 <li>lon - d: Longitude in decimal degrees east, -180 to +180,
155 relative to the WGS-84 datum
157 Same rationale as 'lat'
160 <li>alt - d: altitude in metres above sea level (negative
163 This is from XEP-0080
166 <li>accuracy-level - i (<tp:type>Location_Accuracy_Level</tp:type>):
167 an indication of accuracy, which SHOULD be omitted if it would be
168 Location_Accuracy_Level_None or
169 Location_Accuracy_Level_Detailed
171 This is a struct field in GeoClue; the name is new in this
172 specification, and was chosen in an attempt to avoid clashing
173 with any future XEP-0080 terminology.
176 <li>error - d: horizontal position error in arc-minutes (1/60
179 This is from XEP-0080
182 <li>vertical-error-m - d: vertical position error in metres if
185 This exists as a struct field in GeoClue; the name is new
186 in this specification.
189 <li>horizontal-error-m - d: horizontal position error in metres if
192 This exists as a struct field in GeoClue; the name is new
193 in this specification.
198 <p>Velocities are represented by the following well-known keys:</p>
201 <li>speed - d: speed in metres per second
203 This is from XEP-0080
206 <li>bearing - d: direction of movement in decimal degrees,
207 where North is 0 and East is 90
209 This is from XEP-0080, and is equivalent to the struct field
210 called "direction" in GeoClue
213 <li>climb - d: rate of change of 'alt' in metres per second
215 This is a struct field in GeoClue; the name is new to this
216 specification, but seems uncontroversial
221 <p>Other well-known keys:</p>
224 <li>timestamp - t (<tp:type>Unix_Timestamp64</tp:type>): the time
225 that the contact was at this location, in seconds since
226 1970-01-01T00:00:00Z (i.e. the beginning of 1970 in UTC)
228 XEP-0080 uses an ISO 8601 string for this, but a number of
229 seconds since the epoch is probably easier to work with.
236 <tp:member name="Value" type="v">
238 The value corresponding to the well-known key.
243 <tp:mapping name="Contact_Locations" type="a{ua{sv}}">
244 <tp:member name="Contact" type="u" tp:type="Contact_Handle">
246 <tp:member name="Location" type="a{sv}" tp:type="Location">
250 <method name="GetLocations" tp:name-for-bindings="Get_Locations">
252 Return the current locations of the given contacts, if they are
253 already known. If any of the given contacts' locations are not known,
254 request their current locations, and later emit
255 <tp:member-ref>LocationUpdated</tp:member-ref> for them; the
256 <tp:member-ref>LocationUpdated</tp:member-ref> signal for contacts
257 whose location could not be determined will have an empty Location.
260 <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
262 The contacts whose locations should be returned or signalled.
266 <arg direction="out" name="Locations" type="a{ua{sv}}"
267 tp:type="Contact_Locations">
269 The contacts' locations, if already known. Contacts whose locations
270 are not already known are omitted from the mapping; contacts known
271 to have no location information appear in the mapping with an empty
277 <signal name="LocationUpdated" tp:name-for-bindings="Location_Updated">
279 Emitted when a contact's location changes or becomes known.
282 <arg name="Contact" type="u" tp:type="Contact_Handle">
287 <arg name="Location" type="a{sv}" tp:type="Location">
289 The contact's location, or empty to indicate that nothing is known
290 about the contact's location.
295 <method name="SetLocation" tp:name-for-bindings="SetLocation">
297 Set the local user's own location.
300 <arg direction="in" name="Location" type="a{sv}">
302 The location to advertise. If the user wants to obscure their
303 exact location by reducing the precision or accuracy, clients
304 MUST do this themselves, rather than relying on the connection
305 manager to do so. Clients that interact with more than one
306 connection SHOULD advertise the same reduced-accuracy location
307 to all of them, so that contacts cannot obtain an undesirably
308 accurate location by assuming that random errors have been added
309 and averaging the locations advertised on multiple connections.
314 <property name="LocationAccessControlTypes" type="au" access="read"
315 tp:type="Rich_Presence_Access_Control_Type[]" tp:name-for-bindings="Location_Access_Control_Types">
316 <tp:docstring>The types of access control that are supported by this
317 connection.</tp:docstring>
320 <property name="LocationAccessControl" type="(uv)" access="readwrite"
321 tp:type="Rich_Presence_Access_Control" tp:name-for-bindings="Location_Access_Control">
322 <tp:docstring>The current access control mechanism and settings
323 for this connection. Before publishing location for the first time,
324 if this has not been set by a client, implementations SHOULD
325 set it to be as restrictive as possible (an empty whitelist, if
326 supported).</tp:docstring>
330 <!-- vim:set sw=2 sts=2 et ft=xml: -->