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 handles of type HANDLE_TYPE_CONTACT (for 1-1 communication) or of type HANDLE_TYPE_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 SetSelfCapabilities that such a tube is supported.

To lower the barrier entry of new tube application, CM SHOULD accept to offer tubes of any Service or ServiceName if the contact announced to support tubes.

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. 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.

Example of valid parameters for 'smb' Server Message Block over TCP/IP (from DNS SRV (RFC 2782) Service Types http://www.dns-sd.org/ServiceTypes.html): {'u': 'username', 'p': 'password', 'path': 'path'}

When requesting a channel with Connection.Interface.Requests.CreateChannel, this property MUST NOT be included in the request. This property is undefined until the tube is offered (using OfferStreamTube or OfferDBusTube). Once it has been offered, this property MUST NOT change.

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

State of the tube in this channel.

When requesting a channel with Connection.Interface.Requests.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 to offer the tube depend on the tube type. Emitted when the state of the tube channel changes. The new state of the tube; see the Tube_Channel_State enumeration.