path: root/spec/Connection_Interface_Location.xml

<?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: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 propogation 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>
    </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:enumvalue suffix="Country" value="1"/>
      <tp:enumvalue suffix="Region" value="2"/>
      <tp:enumvalue suffix="Locality" value="3"/>
      <tp:enumvalue suffix="PostalCode" value="4"/>
      <tp:enumvalue suffix="Street" value="5"/>
      <tp:enumvalue suffix="Detailed" value="6"/>
    </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</li>
            <li>lat - d: latitude in decimal degrees east, -180 to +180</li>
            <li>alt - d: altitude in metres above sea level (may be negative
              if below sea level)</li>
            <li>accuracy - 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</li>
            <li>error - d: horizontal position error in arc-minutes (1/60
              degree) if known</li>
            <li>alt-error - d: vertical position error in metres if known</li>
          </ul>

          <p>Velocities are represented by the following well-known keys:</p>

          <ul>
            <li>speed - d: speed in metres per second</li>
            <li>bearing - d: direction of movement in decimal degrees
              relative to true north [Geoclue: is this the same as your
              "direction"?]</li>
            <li>climb - d: [Geoclue: please define?]</li>
          </ul>

          <p>Other well-known keys:</p>

          <ul>
            <li>timestamp - u (Unix_Timestamp): the time that the contact was
              at this location</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:docstring>
        Return the current locations of the given contacts, if they are
        already known. This method does not make any network requests.
      </tp:docstring>

      <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
        <tp:docstring>
          The contacts whose locations should be returned.
        </tp:docstring>
      </arg>

      <arg direction="out" name="Locations" type="a{ua{sv}}"
        tp:type="Contact_Locations">
        <tp:docstring>
          The contacts' locations, if 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>

    <method name="RequestLocations">
      <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 LocationUpdate for
        them; the LocationUpdate 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="LocationUpdate">
      <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: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>

    <!-- FIXME: we may want to give this a more generic name, since it's
    basically the list of pubsub access control mechanisms, and could be
    re-used for other PEPish things -->
    <tp:enum name="Location_Access_Control_Type" type="u">
      <tp:docstring>

      </tp:docstring>

      <tp:enumvalue name="Whitelist">
        <tp:docstring>
          The associated variant is a list of contacts (signature 'au',
          Contact_Handle[]) who can see the user's location.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue name="Publish_List">
        <tp:docstring>
          All contacts in the user's 'publish' contact list can see the
          user's location. The associated variant is ignored.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue name="Group">
        <tp:docstring>
          The associated variant is a handle of type Group (signature 'u',
          Group_Handle) representing a group of contacts who can see the
          user's location.
        </tp:docstring>
      </tp:enumvalue>
      <tp:enumvalue name="Open">
        <tp:docstring>
          Anyone with access to the service can see the user's location.
        </tp:docstring>
      </tp:enumvalue>
    </tp:enum>

    <tp:struct name="Location_Access_Control">
      <tp:member name="Type" type="Location_Access_Control_Type">
        <tp:docstring>
          The type of access control to apply to the user's location.
        </tp:docstring>
      </tp:member>
      <tp:member name="Detail" type="v">
        <tp:docstring>
          Any additional information required by the Type. The required
          type and semantics are defined for each
          Location_Access_Control_Type.
        </tp:docstring>
      </tp:member>
    </tp:struct>

    <property name="LocationAccessControlTypes" type="au" access="read"
      tp:type="Location_Access_Control_Type[]">
      <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="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: -->