diff options
Diffstat (limited to 'qt4/spec/Connection_Interface_Location.xml')
| -rw-r--r-- | qt4/spec/Connection_Interface_Location.xml | 464 |
1 files changed, 0 insertions, 464 deletions
diff --git a/qt4/spec/Connection_Interface_Location.xml b/qt4/spec/Connection_Interface_Location.xml deleted file mode 100644 index fe5492345..000000000 --- a/qt4/spec/Connection_Interface_Location.xml +++ /dev/null @@ -1,464 +0,0 @@ -<?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"> - <tp:added version="0.17.27">(as stable API)</tp:added> - <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> - - <p>Clients of this interface SHOULD register an interest in it by calling - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection.AddClientInterest</tp:dbus-ref> with an argument - containing the name of this interface, - before calling any Location method. If they do so, they SHOULD also call - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection.RemoveClientInterest</tp:dbus-ref> after use to allow - the CM to release resources associated with this interface.</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 - 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 accuracy key. - </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>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> - <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 - <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. - </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> - - <!-- 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 - 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>accuracy - d: horizontal position error in metres if - known - <tp:rationale> - This is from XEP-0080 - </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> - </ul> - - <p>Other well-known keys:</p> - - <ul> - <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> - 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: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> - - <method name="GetLocations" tp:name-for-bindings="Get_Locations"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>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, 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.</p> - - <tp:rationale> - <p>This method is appropriate for "lazy" location finding, for instance - displaying the location (if available) of everyone in your contact - list.</p> - </tp:rationale> - - <p>For backwards compatibility, if this method is called by a client - whose "interest count" for this interface, as defined by <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.AddClientInterest</tp:dbus-ref>, is zero, the - Connection SHOULD behave as if AddClientInterest had been called for - this interface just before that method call. Clients that do not - explicitly call AddClientInterest SHOULD NOT call <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.RemoveClientInterest</tp:dbus-ref> either.</p> - </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> - - <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"> - <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="Set_Location"> - <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> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The user's server does not support publishing their own location. - If it is possible to determine this ahead of time, the - <code>Can_Set</code> flag will not be set in - <tp:member-ref>SupportedLocationFeatures</tp:member-ref>. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> - </tp:possible-errors> - </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> - - <property name="SupportedLocationFeatures" - tp:name-for-bindings="Supported_Location_Features" - type="u" tp:type="Location_Features" access="read"> - <tp:added version="0.19.6"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Indicates the Location features supported by this connection. This - property MAY be undefined before <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection">Status</tp:dbus-ref> - becomes <code>Connected</code>, but MUST remain constant thereafter. - </tp:docstring> - </property> - - <tp:flags name="Location_Features" type="u" value-prefix="Location_Feature"> - <tp:flag suffix="Can_Set" value="1"> - <tp:docstring> - Indicates that setting your own location with - <tp:member-ref>SetLocation</tp:member-ref> is supported on this - connection. - </tp:docstring> - </tp:flag> - - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - Flags describing the Location features which may be supported on any - given connection. - </tp:docstring> - </tp:flags> - - <tp:contact-attribute name="location" - type="a{sv}" tp:type="Location"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>The same mapping that would be returned by - <tp:member-ref>GetLocations</tp:member-ref> for this contact. - Omitted from the result if the contact's location - is not known.</p> - - <p>For backwards compatibility, if contact attributes that include - this interface are requested - by a client whose "interest count" for this interface, as defined by - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Connection.AddClientInterest</tp:dbus-ref>, is zero, the - Connection SHOULD behave as if AddClientInterest was called for this - interface just before that request. Clients that do not explicitly - call AddClientInterest SHOULD NOT call <tp:dbus-ref - namespace="org.freedesktop.Telepathy" - >Connection.RemoveClientInterest</tp:dbus-ref> either.</p> - </tp:docstring> - </tp:contact-attribute> - - </interface> -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> |