<?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">
<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 <tp:type>Handle_Type</tp:type>
Contact (for 1-1 communication) or 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">UpdateCapabilities</tp:dbus-ref>
that such a tube is supported. They SHOULD also allow clients to offer tubes with any
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref> or
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube">ServiceName</tp:dbus-ref>
to any contact which supports the corresponding tube capability.</p>
<tp:rationale>
<p>This lowers the barrier to entry for those writing new tube
applications, and preserves interoperability with older versions of
the Telepathy stack which did not support rich capabilities.</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, but connection managers
must support the value being a string (D-Bus type <tt>'s'</tt>),
array of bytes (D-Bus type <tt>'ay'</tt>), unsigned integer (D-Bus
type <tt>'u'</tt>), integer (D-Bus type <tt>'i'</tt>) and boolean
(D-Bus type <tt>'b'</tt>).</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>For example, a stream tube for <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube">Service</tp:dbus-ref>
<tt>"smb"</tt> (<cite>Server Message Block over TCP/IP</cite>) might
use the following properties, as defined in <a
href="http://www.dns-sd.org/ServiceTypes.html">DNS SRV (RFC 2782)
Service Types</a>:</p>
<pre>
{ 'u': 'some-username',
'p': 'top-secret-password',
'path': '/etc/passwd',
}</pre>
<p>When requesting a tube with
<tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>,
this property MUST NOT be included in the request; instead, it is set
when <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type">StreamTube.Offer</tp:dbus-ref>
or <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Channel.Type">DBusTube.Offer</tp:dbus-ref>
(as appropriate) is called. Its value is undefined until the tube is
offered; once set, its value 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 tube 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 used to offer the tube
depends 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. Valid state
transitions are documented with <tp:type>Tube_Channel_State</tp:type>.
</tp:docstring>
<arg name="State" type="u" tp:type="Tube_Channel_State">
<tp:docstring>
The new state of the tube.
</tp:docstring>
</arg>
</signal>
<tp:enum name="Socket_Address_Type" type="u">
<tp:enumvalue suffix="Unix" value="0">
<tp:docstring>
A Unix socket. The address variant contains a byte-array, signature 'ay',
containing the path of the socket.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Abstract_Unix" value="1">
<tp:docstring>
An abstract Unix socket. The address variant contains a byte-array,
signature 'ay', containing the path of the socket including the
leading null byte.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="IPv4" value="2">
<tp:docstring>
An IPv4 socket. The address variant contains a Socket_Address_IPv4,
i.e. a structure with signature (sq)
in which the string is an IPv4 dotted-quad address literal
(and must not be a DNS name), while the 16-bit unsigned integer is
the port number.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="IPv6" value="3">
<tp:docstring>
An IPv6 socket. The address variant contains a Socket_Address_IPv6,
i.e. a structure with signature (sq)
in which the string is an IPv6 address literal as specified in
RFC2373 (and must not be a DNS name), while the 16-bit unsigned
integer is the port number.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<tp:enum name="Socket_Access_Control" type="u"
array-name="Socket_Access_Control_List">
<tp:enumvalue suffix="Localhost" value="0">
<tp:docstring>
The IP or Unix socket can be accessed by any local user (e.g.
a Unix socket that accepts all local connections, or an IP socket
listening on 127.0.0.1 (or ::1) or rejecting connections not from
that address). The associated variant must be ignored.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Port" value="1">
<tp:docstring>
May only be used on IP sockets. The associated variant must contain
a struct Socket_Address_IPv4 (or Socket_Address_IPv6)
containing the string form of an IP address of the appropriate
version, and a port number. The socket can only be accessed if the
connecting process has that address and port number; all other
connections will be rejected.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Netmask" value="2">
<tp:deprecated version="0.17.25">This has never been implemented.
If you want to share a service to your whole LAN, Telepathy is
not the way to do it.</tp:deprecated>
<tp:docstring>
May only be used on IP sockets. The associated variant must contain
a struct Socket_Netmask_IPv4 (or Socket_Netmask_IPv6) with
signature (sy), containing the string form of an
IP address of the appropriate version, and a prefix length "n".
The socket can only be accessed if the first n bits of the
connecting address match the first n bits of the given address.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Credentials" value="3">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>May only be used on UNIX sockets.
The connecting process must send a byte when
it first connects, which is not considered to be part of the data
stream. If the operating system uses sendmsg() with SCM_CREDS or
SCM_CREDENTIALS to pass credentials over sockets, the connecting
process must do so if possible; if not, it must still send the
byte.</p>
<p>The listening process will disconnect the connection unless it
can determine by OS-specific means that the connecting process
has the same user ID as the listening process.</p>
<p>The associated variant must be ignored.</p>
</tp:docstring>
</tp:enumvalue>
</tp:enum>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->