2 <node name="/Channel_Type_DBus_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3 <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
4 <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Lesser General Public
8 License as published by the Free Software Foundation; either
9 version 2.1 of the License, or (at your option) any later version.
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Lesser General Public License for more details.
16 You should have received a copy of the GNU Lesser General Public
17 License along with this library; if not, write to the Free Software
18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
20 <interface name="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT"
21 tp:causes-havoc="experimental">
22 <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
23 <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT"/>
24 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
25 <p>A D-Bus tube is an ordered reliable transport, for transporting D-Bus
28 <p>For each D-Bus tube, the connection manager listens on a D-Bus
29 server address, as detailed in the D-Bus specification. On this
30 address, it emulates a bus upon which each tube participant appears
33 <p>The objects and interfaces which are expected to exist on the
34 emulated bus depend on the well-known name; typically, either the
35 participant who initiated the tube is expected to export the same
36 objects/interfaces that would be exported by a service of that name
37 on a bus, or all participants are expected to export those
38 objects/interfaces.</p>
40 <p>In a multi-user context (Handle_Type_Room) the tube behaves
41 like the D-Bus bus daemon, so participants can send each other
42 private messages, or can send broadcast messages which are
43 received by everyone in the tube (including themselves).
44 Each participant has a D-Bus unique name; connection managers
45 MUST prevent participants from sending messages with the wrong
46 sender unique name, and SHOULD attempt to avoid participants
47 receiving messages not intended for them.</p>
49 <p>In a 1-1 context (Handle_Type_Contact) the tube behaves like
50 a peer-to-peer D-Bus connection - arbitrary D-Bus messages with
51 any sender and/or destination can be sent by each participant,
52 and each participant receives all messages sent by the other
57 <method name="OfferDBusTube" tp:name-for-bindings="Offer_DBus_Tube">
59 Offers a D-Bus tube providing the service specified.
61 <arg direction="in" name="parameters" type="a{sv}"
62 tp:type="String_Variant_Map">
64 The dictionary of arbitrary
65 <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref>
66 to send with the tube offer.
69 <arg direction="out" name="address" type="s">
71 The string describing the address of the private bus. The client
72 SHOULD not attempt to connect to the address until the tube is open.
76 <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
77 <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
79 The contact associated with this channel doesn't have tubes
86 <method name="AcceptDBusTube" tp:name-for-bindings="Accept_DBus_Tube">
88 Accept a D-Bus tube that's in the "local pending" state. The
89 connection manager will attempt to open the tube. The tube remains in
90 the "local pending" state until the TubeStateChanged signal is
93 <arg direction="out" name="address" type="s">
95 The string describing the address of the private bus. The client
96 SHOULD not attempt to connect to the address until the tube is open.
101 <signal name="DBusNamesChanged" tp:name-for-bindings="DBus_Names_Changed">
103 Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a
104 participant opens or closes the tube. This provides change
105 notification for the <tp:member-ref>DBusNames</tp:member-ref> property.
107 <arg name="added" type="a{us}" tp:type="DBus_Tube_Participants">
109 Array of handles and D-Bus names of new participants.
112 <arg name="removed" type="au" tp:type="Contact_Handle[]">
114 Array of handles of former participants.
119 <property name="ServiceName" type="s" access="read"
120 tp:name-for-bindings="Service_Name">
121 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
122 <p>A string representing the service name that will be used over the
123 tube. It SHOULD be a well-known D-Bus service name, of the form
124 com.example.ServiceName.</p>
125 <p>When the tube is offered, the service name is transmitted to the
127 <p>When requesting a channel with
128 <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
129 this property MUST be included in the request.</p>
133 <property name="DBusNames" tp:name-for-bindings="DBus_Names"
134 access="read" type="a{us}" tp:type="DBus_Tube_Participants">
136 For a multi-user (i.e. Handle_Type_Room) D-Bus tube, a mapping
137 between contact handles and their unique bus names on this tube.
138 For a peer-to-peer (i.e. Handle_Type_Contact) D-Bus tube, the empty
139 dictionary. Change notification is via
140 <tp:member-ref>DBusNamesChanged</tp:member-ref>.
144 <tp:mapping name="DBus_Tube_Participants">
145 <tp:docstring>Represents the participants in a multi-user D-Bus tube, as
146 used by the <tp:member-ref>DBusNames</tp:member-ref> property and the
147 <tp:member-ref>DBusNamesChanged</tp:member-ref> signal.</tp:docstring>
148 <tp:member type="u" tp:type="Contact_Handle" name="Handle">
150 The handle of a participant in this D-Bus tube.
153 <tp:member type="s" tp:type="DBus_Unique_Name" name="Unique_Name">
155 That participant's unique name.
163 <!-- vim:set sw=2 sts=2 et ft=xml: -->