From 14e396ae3e86222dc98f2f85faed0c005ba27c86 Mon Sep 17 00:00:00 2001 From: Pierre-Luc Beaudoin Date: Mon, 1 Dec 2008 16:45:16 -0500 Subject: [PATCH] Get the telepathy bits generated --- extensions/Connection_Interface_Location.xml | 330 +++++++++++++++++++ extensions/Makefile.am | 1 + extensions/all.xml | 12 + extensions/misc.xml | 1 + 4 files changed, 344 insertions(+) create mode 100644 extensions/Connection_Interface_Location.xml diff --git a/extensions/Connection_Interface_Location.xml b/extensions/Connection_Interface_Location.xml new file mode 100644 index 00000000..1e7bee4e --- /dev/null +++ b/extensions/Connection_Interface_Location.xml @@ -0,0 +1,330 @@ + + + Copyright (C) 2008 Collabora Ltd. + Copyright (C) 2008 Nokia Corporation + +

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.

+ +

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.

+ +

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.

+ + + + + +

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.

+ +

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.

+ +

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.

+ +

Location information is represented using the terminology of XMPP's + XEP-0080 + or the XEP-0080-derived + Geoclue API where + possible.

+ + + + + A location accuracy level. This should be kept in sync with + GeoclueAccuracyLevel in the Geoclue project. + + + + + The accuracy is unspecified. + + + + + The location indicates the contact's country. + + + + + The location indicates the contact's region within a country. + + + + + The location indicates the contact's locality within a region + (e.g. the correct city). + + + + + The location indicates the correct postal code. + + + + + The location indicates the correct street. + + + + + The location's accuracy is given by the error, horizontal-error-m + and/or vertical-error-m keys. + + + + + + + A user's location, represented as an extensible mapping. + + + + + +

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:

+ +
    +
  • countrycode - s: an ISO-3166-1 alpha-2 (two-letter) country + code, e.g. "us", "gb", "fr"
    • +
  • country - s: a country name in unspecified locale, e.g. + "USA"
    • +
  • region - s: an administrative region of the nation, such as a + state or province
    • +
  • locality - s: a locality within the administrative region, such + as a town or city
    • +
  • area - s: a named area such as a campus or neighborhood
    • +
  • postalcode - s: a code used for postal delivery
    • +
  • street - s: a thoroughfare within the locality, or a crossing of + two thoroughfares
    • +
+ +

The following address keys are defined in XEP-0080 but not by + Geoclue, and are also allowed:

+ +
    +
  • building - s: a specific building on a street or in an area
    • +
  • floor - s: a particular floor in a building
    • +
  • room - s: a particular room in a building
    • +
  • text - s: any more specific information, e.g. + "Northwest corner of the lobby"
    • +
  • description - s: A natural-language name for or description of + the location, e.g. "Bill's house"
    • +
  • uri - s: a URI representing the location or pointing to more + information about it
    • +
+ +

Positions are represented by the following well-known keys:

+ +
    +
  • lat - d: latitude in decimal degrees north, -90 to +90, + relative to the WGS-84 datum + + 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 + <lat> and <lon> elements if <datum> exists + and has a value other than WGS-84, while an advanced + implementation might correct for the different datum. + +
    • +
  • lon - d: Longitude in decimal degrees east, -180 to +180, + relative to the WGS-84 datum + + Same rationale as 'lat' + +
    • +
  • alt - d: altitude in metres above sea level (negative + if below sea level) + + This is from XEP-0080 + +
    • +
  • accuracy-level - i (Location_Accuracy_Level): + an indication of accuracy, which SHOULD be omitted if it would be + Location_Accuracy_Level_None or + Location_Accuracy_Level_Detailed + + 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. + +
    • +
  • error - d: horizontal position error in arc-minutes (1/60 + degree) if known + + This is from XEP-0080 + +
    • +
  • vertical-error-m - d: vertical position error in metres if + known + + This exists as a struct field in GeoClue; the name is new + in this specification. + +
    • +
  • horizontal-error-m - d: horizontal position error in metres if + known + + This exists as a struct field in GeoClue; the name is new + in this specification. + +
    • +
+ +

Velocities are represented by the following well-known keys:

+ +
    +
  • speed - d: speed in metres per second + + This is from XEP-0080 + +
    • +
  • bearing - d: direction of movement in decimal degrees, + where North is 0 and East is 90 + + This is from XEP-0080, and is equivalent to the struct field + called "direction" in GeoClue + +
    • +
  • climb - d: rate of change of 'alt' in metres per second + + This is a struct field in GeoClue; the name is new to this + specification, but seems uncontroversial + +
    • +
+ +

Other well-known keys:

+ +
    +
  • timestamp - t (Unix_Timestamp64): 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) + + XEP-0080 uses an ISO 8601 string for this, but a number of + seconds since the epoch is probably easier to work with. + +
    • +
+ + + + + + The value corresponding to the well-known key. + + + + + + + + + + + + + + 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 + LocationUpdated for them; the + LocationUpdated signal for contacts + whose location could not be determined will have an empty Location. + + + + + The contacts whose locations should be returned or signalled. + + + + + + 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. + + + + + + + Emitted when a contact's location changes or becomes known. + + + + + The contact + + + + + The contact's location, or empty to indicate that nothing is known + about the contact's location. + + + + + + + Set the local user's own location. + + + + + 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. + + + + + + The types of access control that are supported by this + connection. + + + + 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). + + + + diff --git a/extensions/Makefile.am b/extensions/Makefile.am index 7591109e..3b154cdd 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 c9f4c0bd..85d9dde6 100644 --- a/extensions/all.xml +++ b/extensions/all.xml @@ -28,6 +28,18 @@ from="Telepathy specification"/> + + + + + + + diff --git a/extensions/misc.xml b/extensions/misc.xml index 5c89ff0d..a6ad1c64 100644 --- a/extensions/misc.xml +++ b/extensions/misc.xml @@ -9,5 +9,6 @@ + -- 2.39.2