1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
|
<?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">
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Tube"/>
<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="Offer" tp:name-for-bindings="Offer">
<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">Parameters</tp:dbus-ref>
to send with the tube offer.
</tp:docstring>
</arg>
<arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
<tp:docstring>
The access control the connection manager applies to the D-Bus socket.
</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="Accept" tp:name-for-bindings="Accept">
<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 <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Interface.Tube">TubeChannelStateChanged</tp:dbus-ref>
signal is emitted.
</tp:docstring>
<arg direction="in" name="access_control" type="u" tp:type="Socket_Access_Control">
<tp:docstring>
The access control the connection manager applies to the D-Bus socket.
</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>
</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:requestable="yep"
tp:immutable="yep">
<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
<tt>com.example.ServiceName</tt>.</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>
<property name="SupportedAccessControls" type="au"
tp:type="Socket_Access_Control[]" access="read"
tp:name-for-bindings="Supported_Access_Controls"
tp:immutable="yep">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A list of the access control types that are supported with this channel.
Note that only Socket_Access_Control_Localhost and
Socket_Access_Control_Credentials can be used with D-Bus tubes.
Using Socket_Access_Control_Credentials is recommended.</p>
<tp:rationale>
<p>Socket_Access_Control_Credentials is easy to implement for a
D-Bus tube, because typical D-Bus library implementations like
libdbus and GDBus already have to support it to be able to
connect to the system or session bus, and usually enable it
by default; so there's typically no good reason to relax
access control to Localhost.</p>
</tp:rationale>
<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: -->
|