aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSjoerd Simons <sjoerd.simons@collabora.co.uk>2009-01-10 00:15:56 +0800
committerXavier Claessens <xclaesse@src.gnome.org>2009-01-10 00:15:56 +0800
commit83b767595192e0838acb3163d0d23d57a0f1ec3e (patch)
tree56601c7e6ca682520ff5bdc91573703fe06e0102
parentcec497dca69cca66c3d1a69498dd6f6e1265d673 (diff)
downloadgsoc2013-empathy-83b767595192e0838acb3163d0d23d57a0f1ec3e.tar
gsoc2013-empathy-83b767595192e0838acb3163d0d23d57a0f1ec3e.tar.gz
gsoc2013-empathy-83b767595192e0838acb3163d0d23d57a0f1ec3e.tar.bz2
gsoc2013-empathy-83b767595192e0838acb3163d0d23d57a0f1ec3e.tar.lz
gsoc2013-empathy-83b767595192e0838acb3163d0d23d57a0f1ec3e.tar.xz
gsoc2013-empathy-83b767595192e0838acb3163d0d23d57a0f1ec3e.tar.zst
gsoc2013-empathy-83b767595192e0838acb3163d0d23d57a0f1ec3e.zip
Add extension for new-style DBus tubes
Signed-off-by: Sjoerd Simons <sjoerd.simons@collabora.co.uk> svn path=/trunk/; revision=2197
-rw-r--r--extensions/Channel_Type_DBus_Tube.xml183
-rw-r--r--extensions/Makefile.am1
-rw-r--r--extensions/generic-types.xml8
-rw-r--r--extensions/misc.xml1
4 files changed, 193 insertions, 0 deletions
diff --git a/extensions/Channel_Type_DBus_Tube.xml b/extensions/Channel_Type_DBus_Tube.xml
new file mode 100644
index 000000000..a3b98d7e4
--- /dev/null
+++ b/extensions/Channel_Type_DBus_Tube.xml
@@ -0,0 +1,183 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Type_DBus_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 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>
+ <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:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The connection manager doesn't support D-Bus tubes.
+ </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>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The given tube ID is invalid or does not refer to a D-Bus
+ tube.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="GetDBusTubeAddress"
+ tp:name-for-bindings="Get_DBus_Tube_Address">
+ <tp:docstring>
+ Return a string describing the address of the private bus.
+ </tp:docstring>
+ <arg direction="out" type="s">
+ <tp:docstring>
+ The bus address.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The tube is not a D-Bus tube.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ This tube is not in the "open" state.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="GetDBusNames" tp:name-for-bindings="Get_DBus_Names">
+ <tp:docstring>
+ For a multi-user (i.e. Handle_Type_Room) D-Bus tube, obtain a mapping
+ between contact handles and their unique bus names on this tube.
+ </tp:docstring>
+ <arg direction="out" type="a(us)" tp:type="DBus_Tube_Member[]">
+ <tp:docstring>
+ An array of structures, each containing a contact handle and a D-Bus
+ bus name.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The tube is not a multi-user D-Bus tube.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ This tube is not in the "open" state.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </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.
+ </tp:docstring>
+ <arg name="added" type="a(us)" tp:type="DBus_Tube_Member[]">
+ <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>
+
+ </interface>
+
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/extensions/Makefile.am b/extensions/Makefile.am
index 974fe0b6f..408445fb8 100644
--- a/extensions/Makefile.am
+++ b/extensions/Makefile.am
@@ -15,6 +15,7 @@ EXTRA_DIST = \
Tube_Handler.xml \
Channel_Type_File_Transfer.xml \
Channel_Interface_Tube.xml \
+ Channel_Type_DBus_Tube.xml \
Channel_Type_Stream_Tube.xml
noinst_LTLIBRARIES = libemp-extensions.la
diff --git a/extensions/generic-types.xml b/extensions/generic-types.xml
index 227fde148..fe27d36c9 100644
--- a/extensions/generic-types.xml
+++ b/extensions/generic-types.xml
@@ -53,6 +53,14 @@
with dbus-glib)</tp:docstring>
</tp:simple-type>
+ <tp:struct name="DBus_Tube_Member" array-name="DBus_Tube_Member_List">
+ <tp:docstring>A struct (handle, unique name) representing a participant
+ in a D-Bus tube, as returned by GetDBusNames on the Tubes channel
+ type, and as seen in the DBusNamesChanged signal.</tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
+ <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name"/>
+ </tp:struct>
+
<tp:simple-type name="DBus_Member" type="s">
<tp:docstring>An ASCII string representing a D-Bus method, signal
or property name - a non-empty string of ASCII letters, digits and
diff --git a/extensions/misc.xml b/extensions/misc.xml
index 84dd57fc9..fc96eff89 100644
--- a/extensions/misc.xml
+++ b/extensions/misc.xml
@@ -9,6 +9,7 @@
<xi:include href="Tube_Handler.xml"/>
<xi:include href="Channel_Type_File_Transfer.xml"/>
<xi:include href="Channel_Interface_Tube.xml" />
+<xi:include href="Channel_Type_DBus_Tube.xml" />
<xi:include href="Channel_Type_Stream_Tube.xml" />
</tp:spec>