<?xml version="1.0" ?>
<node name="/Channel_Type_Tubes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>
Copyright © 2007-2009 Collabora Limited
</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.Tubes">
<tp:deprecated version="0.17.25">Client implementations
SHOULD use <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube</tp:dbus-ref> and
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube</tp:dbus-ref>
instead.</tp:deprecated>
<tp:requires interface="org.freedesktop.Telepathy.Channel"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A "tube" is a mechanism for arbitrary data transfer. Two types of
data transfer are currently specified: D-Bus messages, and streams of
bytes. Each tube has a service name, which is a string specifying the
kind of communication that takes place over it, and a dictionary of
arbitrary parameters. Tube parameters are commonly used for bootstrap
information such as usernames and passwords. Each tube is identified
by a locally unique identifier.</p>
<p>The Tubes channel type may be requested for handles of type
HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM.</p>
<p>Stream tubes specify listening addresses using pairs of parameters
with signature 'u', 'v', where the integer 'u' is a member of
Socket_Address_Type and the v is dependent on the type of address.</p>
</tp:docstring>
<tp:simple-type name="Tube_ID" type="u">
<tp:docstring>An identifier for a tube. These are local to a Tubes
channel, and may not be assumed to be the same as the other
participants' idea of the tube identifier.</tp:docstring>
</tp:simple-type>
<tp:struct name="Tube_Info" array-name="Tube_Info_List">
<tp:docstring>A struct (tube ID, initiator handle, tube type,
service name, parameters, state) representing a tube, as returned
by ListTubes on the Tubes channel type.</tp:docstring>
<tp:member type="u" tp:type="Tube_ID" name="Identifier"/>
<tp:member type="u" tp:type="Contact_Handle" name="Initiator"/>
<tp:member type="u" tp:type="Tube_Type" name="Type"/>
<tp:member type="s" name="Service"/>
<tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/>
<tp:member type="u" tp:type="Tube_State" name="State"/>
</tp:struct>
<tp:struct name="DBus_Tube_Member" array-name="DBus_Tube_Member_List">
<tp:docstring>Represents a participant in a multi-user D-Bus tube, as
returned by <tp:member-ref>GetDBusNames</tp:member-ref> and seen in 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:struct>
<tp:enum name="Tube_Type" type="u" array-name="Tube_Type_List">
<tp:enumvalue suffix="DBus" value="0">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The tube is D-Bus tube as described by the
org.freedesktop.Telepathy.Channel.Type.DBusTube interface.</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Stream" value="1">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The tube is stream tube as described by the
org.freedesktop.Telepathy.Channel.Type.StreamTube interface.</p>
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<tp:enum name="Tube_State" type="u">
<tp:enumvalue suffix="Local_Pending" value="0">
<tp:docstring>
The tube is waiting to be accepted/closed locally.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Remote_Pending" value="1">
<tp:docstring>
The tube is waiting to be accepted/closed remotely.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Open" value="2">
<tp:docstring>
The tube is open for traffic.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<tp:mapping name="Supported_Socket_Map">
<tp:docstring>The supported socket address and access-control types
for tubes. See GetAvailableStreamTubeTypes.</tp:docstring>
<tp:member name="Address_Type" type="u" tp:type="Socket_Address_Type"/>
<tp:member name="Access_Control" type="au"
tp:type="Socket_Access_Control[]"/>
</tp:mapping>
<method name="GetAvailableStreamTubeTypes"
tp:name-for-bindings="Get_Available_Stream_Tube_Types">
<tp:docstring>List the available address types and access-control types
for stream tubes.</tp:docstring>
<arg direction="out" type="a{uau}" tp:type="Supported_Socket_Map"
name="Available_Stream_Tube_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>If stream tubes are not supported, this will be an empty
dictionary.</p>
</tp:docstring>
</arg>
</method>
<method name="GetAvailableTubeTypes"
tp:name-for-bindings="Get_Available_Tube_Types">
<arg direction="out" type="au" tp:type="Tube_Type[]"
name="Available_Tube_Types">
<tp:docstring>
An array of the available tube types, as defined by the Tube_Type
enum.
</tp:docstring>
</arg>
</method>
<method name="ListTubes" tp:name-for-bindings="List_Tubes">
<arg direction="out" type="a(uuusa{sv}u)" tp:type="Tube_Info[]"
name="Tubes">
<tp:docstring>
Return an array of tuples, each representing a tube, with the
following members:
<ul>
<li>the tube's ID</li>
<li>the tube's initiator</li>
<li>the tube's type</li>
<li>the tube's service</li>
<li>the tube's parameters</li>
<li>the tube's state</li>
</ul>
</tp:docstring>
</arg>
</method>
<!-- this tp:name-for-bindings is ugly, but compatible with
the code generation in telepathy-glib versions that did not use
tp:name-for-bindings -->
<method name="OfferDBusTube" tp:name-for-bindings="Offer_D_Bus_Tube">
<tp:docstring>
Offers a D-Bus tube providing the service specified.
</tp:docstring>
<arg direction="in" name="Service" type="s">
<tp:docstring>
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.
</tp:docstring>
</arg>
<arg direction="in" name="Parameters" type="a{sv}"
tp:type="String_Variant_Map">
<tp:docstring>
A dictionary of properties for the new tube; the allowable keys,
types and values are defined by the service. Connection managers
must support the value being any primitive (non-container)
D-Bus type, or a byte array 'ay'.
</tp:docstring>
</arg>
<arg direction="out" type="u" tp:type="Tube_ID" name="Tube_ID">
<tp:docstring>
The ID of the new tube.
</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: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="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="Service" type="s">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
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".
</tp:docstring>
</arg>
<arg direction="in" name="Parameters" type="a{sv}"
tp:type="String_Variant_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A dictionary of properties for the new tube; the allowable keys,
types and values are defined by the service. Connection managers
must support the value being any primitive (non-container)
D-Bus type, or a byte array 'ay'.</p>
<p>These should usually be the same key-value pairs specified for
use in the DNS-SD TXT record for that service.</p>
</tp:docstring>
</arg>
<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="out" type="u" tp:type="Tube_ID" name="Tube_ID">
<tp:docstring>
The ID of the new tube.
</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 stream tubes, or
does not support the given address type or access-control type.
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
<signal name="NewTube" tp:name-for-bindings="New_Tube">
<tp:docstring>
Emitted when a tube is created.
</tp:docstring>
<arg name="ID" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the new tube.
</tp:docstring>
</arg>
<arg name="Initiator" type="u" tp:type="Contact_Handle">
<tp:docstring>
The handle of the contact who initiated the tube.
</tp:docstring>
</arg>
<arg name="Type" type="u" tp:type="Tube_Type">
<tp:docstring>
The tube type, as defined by the Tube_Type enum.
</tp:docstring>
</arg>
<arg name="Service" type="s">
<tp:docstring>
A string representing the service that will be used over the tube.
</tp:docstring>
</arg>
<arg name="Parameters" type="a{sv}" tp:type="String_Variant_Map">
<tp:docstring>
The new tube's properties.
</tp:docstring>
</arg>
<arg name="State" type="u" tp:type="Tube_State">
<tp:docstring>
The new tube's state.
</tp:docstring>
</arg>
</signal>
<!-- this tp:name-for-bindings is ugly, but compatible with
the code generation in telepathy-glib versions that did not use
tp:name-for-bindings -->
<method name="AcceptDBusTube" tp:name-for-bindings="Accept_D_Bus_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="in" name="ID" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the tube to accept.
</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.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="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="ID" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the tube to accept.
</tp:docstring>
</arg>
<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 given tube ID is invalid or does not refer to a stream
tube.
</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="TubeStateChanged" tp:name-for-bindings="Tube_State_Changed">
<tp:docstring>
Emitted when the state of a tube changes.
</tp:docstring>
<arg name="ID" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the tube that changed state.
</tp:docstring>
</arg>
<arg name="State" type="u" tp:type="Tube_State">
<tp:docstring>
The new state of the tube; see the Tube_State enumeration.
</tp:docstring>
</arg>
</signal>
<method name="CloseTube" tp:name-for-bindings="Close_Tube">
<tp:docstring>
Close a tube.
</tp:docstring>
<arg direction="in" name="ID" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the tube to close.
</tp:docstring>
</arg>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument" />
</tp:possible-errors>
</method>
<signal name="TubeClosed" tp:name-for-bindings="Tube_Closed">
<tp:docstring>
Emitted when a tube has been closed. The ID of a closed tube is no
longer valid. The ID may later be reused for a new tube.
</tp:docstring>
<arg name="ID" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the tube that was closed.
</tp:docstring>
</arg>
</signal>
<!-- this tp:name-for-bindings is ugly, but compatible with
the code generation in telepathy-glib versions that did not use
tp:name-for-bindings -->
<method name="GetDBusTubeAddress"
tp:name-for-bindings="Get_D_Bus_Tube_Address">
<tp:docstring>
For a D-Bus tube, return a string describing the address of the
private bus.
</tp:docstring>
<arg direction="in" name="ID" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the tube to get an address for.
</tp:docstring>
</arg>
<arg direction="out" type="s" name="Address">
<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>
<!-- this tp:name-for-bindings is ugly, but compatible with
the code generation in telepathy-glib versions that did not use
tp:name-for-bindings -->
<method name="GetDBusNames" tp:name-for-bindings="Get_D_Bus_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="in" name="ID" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the tube to get names for.
</tp:docstring>
</arg>
<arg direction="out" type="a(us)" tp:type="DBus_Tube_Member[]"
name="DBus_Names">
<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>
<!-- this tp:name-for-bindings is ugly, but compatible with
the code generation in telepathy-glib versions that did not use
tp:name-for-bindings -->
<signal name="DBusNamesChanged" tp:name-for-bindings="D_Bus_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="ID" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the tube whose names have changed.
</tp:docstring>
</arg>
<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>
<method name="GetStreamTubeSocketAddress"
tp:name-for-bindings="Get_Stream_Tube_Socket_Address">
<tp:docstring>
For a stream tube, obtain the address of the socket used to
communicate over this tube.
</tp:docstring>
<arg direction="in" name="ID" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the stream tube to get the socket for.
</tp:docstring>
</arg>
<arg direction="out" name="Address_Type" type="u" tp:type="Socket_Address_Type">
<tp:docstring>
The type of the listening address of the socket, as a member of
Socket_Address_Type.
</tp:docstring>
</arg>
<arg direction="out" name="Address" type="v">
<tp:docstring>
The listening address of the socket, as indicated by the
address_type.
</tp:docstring>
</arg>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
<tp:docstring>
The tube is not a stream 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="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="ID" type="u" tp:type="Tube_ID">
<tp:docstring>
The ID of the tube
</tp:docstring>
</arg>
<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>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->