diff options
Diffstat (limited to 'extensions')
| -rw-r--r-- | extensions/Channel_Interface_Tube.xml | 148 | ||||
| -rw-r--r-- | extensions/Channel_Type_DBus_Tube.xml | 163 | ||||
| -rw-r--r-- | extensions/Channel_Type_Stream_Tube.xml | 206 | ||||
| -rw-r--r-- | extensions/Connection_Interface_Location.xml | 330 | ||||
| -rw-r--r-- | extensions/Makefile.am | 30 | ||||
| -rw-r--r-- | extensions/all.xml | 12 | ||||
| -rw-r--r-- | extensions/misc.xml | 4 |
7 files changed, 358 insertions, 535 deletions
diff --git a/extensions/Channel_Interface_Tube.xml b/extensions/Channel_Interface_Tube.xml deleted file mode 100644 index 8e6eb6514..000000000 --- a/extensions/Channel_Interface_Tube.xml +++ /dev/null @@ -1,148 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Interface_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> - <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> - <tp:license> - 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. - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT" - tp:causes-havoc="experimental"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A <i>tube</i> is a mechanism for arbitrary data transfer between - two or more IM users, used to allow applications on the users' - systems to communicate without having to establish network - connections themselves. Currently, two types of tube exist: - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Channel.Type.DBusTube</tp:dbus-ref> and - <tp:dbus-ref namespace="org.freedesktop.Telepathy" - >Channel.Type.StreamTube</tp:dbus-ref>. This interface contains - the properties, signals and methods common to both types of tube; - you can only create channels of a specific tube type, not of this - type. A tube channel contains exactly one tube; if you need several - tubes, you have to create several tube channels.</p> - - <p>Tube channels can be requested for handles of type - HANDLE_TYPE_CONTACT (for 1-1 communication) or of type - HANDLE_TYPE_ROOM (to communicate with others in the room - simultaneously).</p> - - <p>As an exception to the usual handling of capabilities, connection managers - for protocols with capability discovery, such as XMPP, SHOULD advertise the - capability representing each Tube type that they support - (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube</tp:dbus-ref> and/or - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>) - even if no client has indicated via - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref> - that such a tube is supported.</p> - - <tp:rationale> - <p>To lower the barrier entry of new tube application, CM SHOULD accept to offer tubes of any - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Service</tp:dbus-ref> or - <tp:dbus-ref - namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">ServiceName</tp:dbus-ref> - if the contact announced to support tubes.</p> - </tp:rationale> - </tp:docstring> - - <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map" - access="read" tp:name-for-bindings="Parameters"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>Each tube has a dictionary of arbitrary parameters. Parameters are - commonly used to bootstrap legacy protocols where you can't - negotiate parameters in-band. The allowable keys, - types and values are defined by the service. Connection managers - must support the value being a string (D-Bus type 's'), array of bytes - (D-Bus type 'ay'), unsigned integer (D-Bus type 'u'), integer (D-Bus - type 'i') and boolean (D-Bus type 'b').</p> - <p>When the tube is offered, the parameters are transmitted with the - offer and appear as a property of the incoming tube for other - participants.</p> - <p>Example of valid parameters for 'smb' Server Message Block over - TCP/IP (from <a href="http://www.dns-sd.org/ServiceTypes.html">DNS - SRV (RFC 2782) Service Types - http://www.dns-sd.org/ServiceTypes.html</a>): - <code>{'u': 'username', 'p': 'password', 'path': 'path'}</code></p> - <p>When requesting a channel with - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, - this property MUST NOT be included in the request. This property is undefined until the tube is offered - (using <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">OfferStreamTube</tp:dbus-ref> - or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">OfferDBusTube</tp:dbus-ref>). - Once it has been offered, this property MUST NOT change.</p> - <p>When receiving an incoming tube, this property is immutable and so advertised in the - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref> - signal.</p> - </tp:docstring> - </property> - - <property name="State" type="u" tp:type="Tube_Channel_State" access="read" - tp:name-for-bindings="State"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>State of the tube in this channel.</p> - <p>When requesting a channel with - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, - this property MUST NOT be included in the request.</p> - </tp:docstring> - </property> - - <tp:enum name="Tube_Channel_State" type="u"> - <tp:enumvalue suffix="Local_Pending" value="0"> - <tp:docstring> - The initiator offered the tube. The tube is waiting to be - accepted/closed locally. If the client accepts the tube, the tube's - state will be Open. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Remote_Pending" value="1"> - <tp:docstring> - The tube is waiting to be accepted/closed remotely. If the - recipient accepts the tube, the tube's state will be Open. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Open" value="2"> - <tp:docstring> - The initiator offered the tube and the recipient accepted it. The - tube is open for traffic. The tube's state stays in this state until - it is closed. - </tp:docstring> - </tp:enumvalue> - <tp:enumvalue suffix="Not_Offered" value="3"> - <tp:docstring> - The tube channel has been requested but the tube is not yet offered. - The client should offer the tube to the recipient and the tube's - state will be Remote_Pending. The method to offer the tube depend on - the tube type. - </tp:docstring> - </tp:enumvalue> - </tp:enum> - - <signal name="TubeChannelStateChanged" - tp:name-for-bindings="Tube_Channel_State_Changed"> - <tp:docstring> - Emitted when the state of the tube channel changes. - </tp:docstring> - <arg name="state" type="u" tp:type="Tube_Channel_State"> - <tp:docstring> - The new state of the tube; see the Tube_Channel_State enumeration. - </tp:docstring> - </arg> - </signal> - - </interface> - -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Channel_Type_DBus_Tube.xml b/extensions/Channel_Type_DBus_Tube.xml deleted file mode 100644 index 513d77caa..000000000 --- a/extensions/Channel_Type_DBus_Tube.xml +++ /dev/null @@ -1,163 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_DBus_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> - <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> - <tp:license> - 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. - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT" - tp:causes-havoc="experimental"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A D-Bus tube is an ordered reliable transport, for transporting D-Bus - traffic.</p> - - <p>For each D-Bus tube, the connection manager listens on a D-Bus - server address, as detailed in the D-Bus specification. On this - address, it emulates a bus upon which each tube participant appears - as an endpoint.</p> - - <p>The objects and interfaces which are expected to exist on the - emulated bus depend on the well-known name; typically, either the - participant who initiated the tube is expected to export the same - objects/interfaces that would be exported by a service of that name - on a bus, or all participants are expected to export those - objects/interfaces.</p> - - <p>In a multi-user context (Handle_Type_Room) the tube behaves - like the D-Bus bus daemon, so participants can send each other - private messages, or can send broadcast messages which are - received by everyone in the tube (including themselves). - Each participant has a D-Bus unique name; connection managers - MUST prevent participants from sending messages with the wrong - sender unique name, and SHOULD attempt to avoid participants - receiving messages not intended for them.</p> - - <p>In a 1-1 context (Handle_Type_Contact) the tube behaves like - a peer-to-peer D-Bus connection - arbitrary D-Bus messages with - any sender and/or destination can be sent by each participant, - and each participant receives all messages sent by the other - participant.</p> - - </tp:docstring> - - <method name="OfferDBusTube" tp:name-for-bindings="Offer_DBus_Tube"> - <tp:docstring> - Offers a D-Bus tube providing the service specified. - </tp:docstring> - <arg direction="in" name="parameters" type="a{sv}" - tp:type="String_Variant_Map"> - <tp:docstring> - The dictionary of arbitrary - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref> - to send with the tube offer. - </tp:docstring> - </arg> - <arg direction="out" name="address" type="s"> - <tp:docstring> - The string describing the address of the private bus. The client - SHOULD not attempt to connect to the address until the tube is open. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The contact associated with this channel doesn't have tubes - capabilities. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="AcceptDBusTube" tp:name-for-bindings="Accept_DBus_Tube"> - <tp:docstring> - Accept a D-Bus tube that's in the "local pending" state. The - connection manager will attempt to open the tube. The tube remains in - the "local pending" state until the TubeStateChanged signal is - emitted. - </tp:docstring> - <arg direction="out" name="address" type="s"> - <tp:docstring> - The string describing the address of the private bus. The client - SHOULD not attempt to connect to the address until the tube is open. - </tp:docstring> - </arg> - </method> - - <signal name="DBusNamesChanged" tp:name-for-bindings="DBus_Names_Changed"> - <tp:docstring> - Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a - participant opens or closes the tube. This provides change - notification for the <tp:member-ref>DBusNames</tp:member-ref> property. - </tp:docstring> - <arg name="added" type="a{us}" tp:type="DBus_Tube_Participants"> - <tp:docstring> - Array of handles and D-Bus names of new participants. - </tp:docstring> - </arg> - <arg name="removed" type="au" tp:type="Contact_Handle[]"> - <tp:docstring> - Array of handles of former participants. - </tp:docstring> - </arg> - </signal> - - <property name="ServiceName" type="s" access="read" - tp:name-for-bindings="Service_Name"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A string representing the service name that will be used over the - tube. It SHOULD be a well-known D-Bus service name, of the form - com.example.ServiceName.</p> - <p>When the tube is offered, the service name is transmitted to the - other end.</p> - <p>When requesting a channel with - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, - this property MUST be included in the request.</p> - </tp:docstring> - </property> - - <property name="DBusNames" tp:name-for-bindings="DBus_Names" - access="read" type="a{us}" tp:type="DBus_Tube_Participants"> - <tp:docstring> - For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping - between contact handles and their unique bus names on this tube. - For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty - dictionary. Change notification is via - <tp:member-ref>DBusNamesChanged</tp:member-ref>. - </tp:docstring> - </property> - - <tp:mapping name="DBus_Tube_Participants"> - <tp:docstring>Represents the participants in a multi-user D-Bus tube, as - used by the <tp:member-ref>DBusNames</tp:member-ref> property and the - <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring> - <tp:member type="u" tp:type="Contact_Handle" name="Handle"> - <tp:docstring> - The handle of a participant in this D-Bus tube. - </tp:docstring> - </tp:member> - <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name"> - <tp:docstring> - That participant's unique name. - </tp:docstring> - </tp:member> - </tp:mapping> - - </interface> - -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Channel_Type_Stream_Tube.xml b/extensions/Channel_Type_Stream_Tube.xml deleted file mode 100644 index 060cd0bb0..000000000 --- a/extensions/Channel_Type_Stream_Tube.xml +++ /dev/null @@ -1,206 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Channel_Type_Stream_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> - <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright> - <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright> - <tp:license> - 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. - </tp:license> - <interface name="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT" - tp:causes-havoc="experimental"> - <tp:requires interface="org.freedesktop.Telepathy.Channel"/> - <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A stream tube is a transport for ordered, reliable data transfer, - similar to SOCK_STREAM sockets.</p> - - <p>When offering a stream tube, the initiating client creates a local - listening socket and offers it to the recipient client using the - <tp:member-ref>OfferStreamTube</tp:member-ref> method. When a - recipient accepts a stream tube using the - <tp:member-ref>AcceptStreamTube</tp:member-ref> method, the - recipient's connection manager creates a new local listening socket. - Each time the recipient's client connects to this socket, the - initiator's connection manager proxies this connection to the - originally offered socket.</p> - - </tp:docstring> - - <method name="OfferStreamTube" tp:name-for-bindings="Offer_Stream_Tube"> - <tp:docstring> - Offer a stream tube exporting the local socket specified. - </tp:docstring> - <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type"> - <tp:docstring> - The type of the listening address of the local service, as a member of - Socket_Address_Type. - </tp:docstring> - </arg> - <arg direction="in" name="address" type="v"> - <tp:docstring> - The listening address of the local service, as indicated by the - address_type. - </tp:docstring> - </arg> - <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> - <tp:docstring> - The access control the local service applies to the local socket, - specified so the connection manager can behave appropriately - when it connects. - </tp:docstring> - </arg> - <arg direction="in" name="access_control_param" type="v"> - <tp:docstring> - A parameter for the access control type, to be interpreted as - specified in the documentation for the Socket_Access_Control enum. - </tp:docstring> - </arg> - <arg direction="in" name="parameters" type="a{sv}" - tp:type="String_Variant_Map"> - <tp:docstring> - The dictionary of arbitrary - <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref> - to send with the tube offer. - </tp:docstring> - </arg> - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> - <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> - <tp:docstring> - The contact associated with this channel doesn't have tube - capabilities. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The connection manager doesn't support the given address type - or access-control type. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <method name="AcceptStreamTube" tp:name-for-bindings="Accept_Stream_Tube"> - <tp:docstring> - Accept a stream tube that's in the "local pending" state. The - connection manager will attempt to open the tube. The tube remains in - the "local pending" state until the TubeStateChanged signal is - emitted. - </tp:docstring> - <arg direction="in" name="address_type" type="u" tp:type="Socket_Address_Type"> - <tp:docstring> - The type of address the connection manager should listen on. - </tp:docstring> - </arg> - <arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control"> - <tp:docstring> - The type of access control the connection manager should apply to - the socket. - </tp:docstring> - </arg> - <arg direction="in" name="access_control_param" type="v"> - <tp:docstring> - A parameter for the access control type, to be interpreted as - specified in the documentation for the Socket_Access_Control enum. - </tp:docstring> - </arg> - <arg direction="out" name="address" type="v"> - <tp:docstring> - The address on which the connection manager will listen for - connections to this tube. The client should not attempt to connect - to the address until the tube is open. - </tp:docstring> - </arg> - - <tp:possible-errors> - <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> - <tp:docstring> - The access_control_param is invalid with the given access_control. - </tp:docstring> - </tp:error> - <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> - <tp:docstring> - The given address type or access-control mechanism is not supported. - </tp:docstring> - </tp:error> - </tp:possible-errors> - </method> - - <signal name="StreamTubeNewConnection" - tp:name-for-bindings="Stream_Tube_New_Connection"> - <tp:docstring> - Emitted on a stream tube when a participant opens a new connection - to its socket. - </tp:docstring> - <arg name="handle" type="u" tp:type="Contact_Handle"> - <tp:docstring> - The handle of the participant who opened the new connection - </tp:docstring> - </arg> - </signal> - - <property name="Service" type="s" access="read" - tp:name-for-bindings="Service"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p> A string representing the service name that will be used over the - tube. It should be a well-known TCP service name as defined by - <a href="http://www.iana.org/assignments/port-numbers"> - http://www.iana.org/assignments/port-numbers</a> or - <a href="http://www.dns-sd.org/ServiceTypes.html"> - http://www.dns-sd.org/ServiceTypes.html</a>, for instance - "rsync" or "daap".</p> - <p>When the tube is offered, the service name is transmitted to the - other end.</p> - <p>When requesting a channel with - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, - this property MUST be included in the request.</p> - </tp:docstring> - </property> - - <property name="SupportedSocketTypes" type="a{uau}" - tp:type="Supported_Socket_Map" access="read" - tp:name-for-bindings="Supported_Socket_Types"> - <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> - <p>A mapping from address types (members of Socket_Address_Type) to - arrays of access-control type (members of Socket_Access_Control) - that the connection manager supports for stream tubes with that - address type. For simplicity, if a CM supports offering a - particular type of tube, it is assumed to support accepting it.</p> - - <p>A typical value for a host without IPv6 support:</p> - - <pre> - { - Socket_Address_Type_IPv4: - [Socket_Access_Control_Localhost, Socket_Access_Control_Port, - Socket_Access_Control_Netmask], - Socket_Address_Type_Unix: - [Socket_Access_Control_Localhost, Socket_Access_Control_Credentials] - } - </pre> - - <p>Connection Managers MUST support at least IPv4 with the localhost - access control.</p> - - <p>When requesting a channel with - <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>, - this property MUST NOT be included in the request.</p> - - </tp:docstring> - </property> - - </interface> - -</node> -<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Connection_Interface_Location.xml b/extensions/Connection_Interface_Location.xml new file mode 100644 index 000000000..1e7bee4e0 --- /dev/null +++ b/extensions/Connection_Interface_Location.xml @@ -0,0 +1,330 @@ +<?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.DRAFT" + 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 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> + </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: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 error, horizontal-error-m + and/or vertical-error-m keys. + </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>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> + <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>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 + known + <tp:rationale> + This exists as a struct field in GeoClue; the name is new + in this specification. + </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> + <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 + 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: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:name-for-bindings="Get_Locations"> + <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. + </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="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="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> + + <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> + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> diff --git a/extensions/Makefile.am b/extensions/Makefile.am index f179ebc19..0ed6fc522 100644 --- a/extensions/Makefile.am +++ b/extensions/Makefile.am @@ -1,3 +1,5 @@ +include $(top_srcdir)/tools/shave.mk + tools_dir = $(top_srcdir)/tools AM_CPPFLAGS = $(DISABLE_DEPRECATED) @@ -13,10 +15,8 @@ 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 \ - Channel_Type_Stream_Tube.xml \ Debug.xml noinst_LTLIBRARIES = libemp-extensions.la @@ -61,45 +61,45 @@ XSLTPROCFLAGS = --nonet --novalid _gen/all.xml: all.xml $(wildcard *.xml) $(mkdir_p) _gen - $(XSLTPROC) $(XSLTPROCFLAGS) --xinclude $(tools_dir)/identity.xsl \ + $(QUIET_GEN)$(XSLTPROC) $(XSLTPROCFLAGS) --xinclude $(tools_dir)/identity.xsl \ $< > $@ extensions.html: _gen/all.xml $(tools_dir)/doc-generator.xsl - $(XSLTPROC) $(XSLTPROCFLAGS) \ + $(QUIET_GEN)$(XSLTPROC) $(XSLTPROCFLAGS) \ --param "allow-undefined-interfaces" "true()" \ $(tools_dir)/doc-generator.xsl \ $< > $@ _gen/gtypes.h _gen/gtypes-body.h: _gen/all.xml \ $(top_srcdir)/tools/glib-gtypes-generator.py - $(PYTHON) $(top_srcdir)/tools/glib-gtypes-generator.py \ + $(QUIET_GEN)$(PYTHON) $(top_srcdir)/tools/glib-gtypes-generator.py \ $< _gen/gtypes Emp _gen/signals-marshal.list: _gen/all.xml \ $(tools_dir)/glib-signals-marshal-gen.py - $(PYTHON) $(tools_dir)/glib-signals-marshal-gen.py $< > $@ + $(QUIET_GEN)$(PYTHON) $(tools_dir)/glib-signals-marshal-gen.py $< > $@ _gen/signals-marshal.h: _gen/signals-marshal.list Makefile.am - $(GLIB_GENMARSHAL) --header --prefix=_emp_ext_marshal $< > $@ + $(QUIET_GEN)$(GLIB_GENMARSHAL) --header --prefix=_emp_ext_marshal $< > $@ _gen/signals-marshal.c: _gen/signals-marshal.list Makefile.am - { echo '#include "_gen/signals-marshal.h"' && \ + $(QUIET_GEN){ echo '#include "_gen/signals-marshal.h"' && \ $(GLIB_GENMARSHAL) --body --prefix=_emp_ext_marshal $< ; } > $@ _gen/register-dbus-glib-marshallers-body.h: _gen/all.xml \ $(tools_dir)/glib-client-marshaller-gen.py - $(PYTHON) $(tools_dir)/glib-client-marshaller-gen.py $< \ + $(QUIET_GEN)$(PYTHON) $(tools_dir)/glib-client-marshaller-gen.py $< \ _emp_ext > $@ _gen/enums.h: _gen/all.xml \ $(tools_dir)/c-constants-gen.py - $(PYTHON) $(tools_dir)/c-constants-gen.py \ + $(QUIET_GEN)$(PYTHON) $(tools_dir)/c-constants-gen.py \ Emp \ $< > $@ _gen/interfaces-body.h _gen/interfaces.h: _gen/all.xml \ $(tools_dir)/glib-interfaces-gen.py - $(PYTHON) $(tools_dir)/glib-interfaces-gen.py \ + $(QUIET_GEN)$(PYTHON) $(tools_dir)/glib-interfaces-gen.py \ Emp _gen/interfaces-body.h _gen/interfaces.h $< # Generated files which must be generated per "category". Each TpProxy @@ -108,12 +108,12 @@ _gen/interfaces-body.h _gen/interfaces.h: _gen/all.xml \ _gen/misc.xml: misc.xml $(wildcard *.xml) $(mkdir_p) _gen - $(XSLTPROC) $(XSLTPROCFLAGS) --xinclude $(tools_dir)/identity.xsl \ + $(QUIET_GEN)$(XSLTPROC) $(XSLTPROCFLAGS) --xinclude $(tools_dir)/identity.xsl \ $< > $@ _gen/cli-misc-body.h _gen/cli-misc.h: _gen/misc.xml \ $(tools_dir)/glib-client-gen.py - $(PYTHON) $(tools_dir)/glib-client-gen.py \ + $(QUIET_GEN)$(PYTHON) $(tools_dir)/glib-client-gen.py \ --group=misc \ --subclass=TpProxy \ --subclass-assert=TP_IS_PROXY \ @@ -123,7 +123,7 @@ _gen/cli-misc-body.h _gen/cli-misc.h: _gen/misc.xml \ _gen/svc-misc.c _gen/svc-misc.h: _gen/misc.xml \ $(tools_dir)/glib-ginterface-gen.py - $(PYTHON) $(tools_dir)/glib-ginterface-gen.py \ + $(QUIET_GEN)$(PYTHON) $(tools_dir)/glib-ginterface-gen.py \ --filename=_gen/svc-misc \ --signal-marshal-prefix=_emp_ext \ --include='<telepathy-glib/dbus.h>' \ diff --git a/extensions/all.xml b/extensions/all.xml index c9f4c0bd7..85d9dde68 100644 --- a/extensions/all.xml +++ b/extensions/all.xml @@ -28,6 +28,18 @@ from="Telepathy specification"/> <tp:external-type name="Tube_ID" type="u" from="Telepathy specification"/> + + <!-- for localisation --> + <tp:external-type name="Rich_Presence_Access_Control_Type" type="u" + from="Telepathy specification"/> + <tp:external-type name="Rich_Presence_Access_Control" type="(uv)" + from="Telepathy specification"/> + <tp:external-type name="Unix_Timestamp64" type="t" + from="Telepathy specification"/> + <tp:external-type name="Unix_Timestamp" type="u" + from="Telepathy specification"/> + <tp:external-type name="String_String_Map" type="a{ss}" + from="Telepathy specification"/> </tp:generic-types> diff --git a/extensions/misc.xml b/extensions/misc.xml index 38e802e97..dd3125fb2 100644 --- a/extensions/misc.xml +++ b/extensions/misc.xml @@ -6,9 +6,7 @@ <xi:include href="Channel_Handler.xml"/> <xi:include href="Tube_Handler.xml"/> -<xi:include href="Channel_Interface_Tube.xml" /> -<xi:include href="Channel_Type_DBus_Tube.xml" /> -<xi:include href="Channel_Type_Stream_Tube.xml" /> +<xi:include href="Connection_Interface_Location.xml"/> <xi:include href="Debug.xml" /> </tp:spec> |