Copyright © 2008-2009 Collabora Limited Copyright © 2008-2009 Nokia Corporation 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.

A tube 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: Channel.Type.DBusTube and Channel.Type.StreamTube. 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.

Tube channels can be requested for Handle_Type Contact (for 1-1 communication) or Room (to communicate with others in the room simultaneously).

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 (Channel.Type.DBusTube and/or Channel.Type.StreamTube) even if no client has indicated via UpdateCapabilities that such a tube is supported. They SHOULD also allow clients to offer tubes with any Service or ServiceName to any contact which supports the corresponding tube capability.

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.

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 's'), array of bytes (D-Bus type 'ay'), unsigned integer (D-Bus type 'u'), integer (D-Bus type 'i') and boolean (D-Bus type 'b').

When the tube is offered, the parameters are transmitted with the offer and appear as a property of the incoming tube for other participants.

For example, a stream tube for Service "smb" (Server Message Block over TCP/IP) might use the following properties, as defined in DNS SRV (RFC 2782) Service Types:

{ 'u': 'some-username',
  'p': 'top-secret-password',
  'path': '/etc/passwd',
}

When requesting a tube with CreateChannel, this property MUST NOT be included in the request; instead, it is set when StreamTube.Offer or DBusTube.Offer (as appropriate) is called. Its value is undefined until the tube is offered; once set, its value MUST NOT change.

When receiving an incoming tube, this property is immutable and so advertised in the NewChannels signal.

State of the tube in this channel.

When requesting a tube with CreateChannel, this property MUST NOT be included in the request.

 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. The tube is waiting to be accepted/closed remotely. If the recipient accepts the tube, the tube's state will be Open. 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. 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. Emitted when the state of the tube channel changes. Valid state transitions are documented with Tube_Channel_State. The new state of the tube. A Unix socket. The address variant contains a byte-array, signature 'ay', containing the path of the socket. An abstract Unix socket. The address variant contains a byte-array, signature 'ay', containing the path of the socket including the leading null byte. 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. 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. 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. 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. This has never been implemented. If you want to share a service to your whole LAN, Telepathy is not the way to do it. 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.

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.

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.

The associated variant must be ignored.