Copyright © 2007-2009 Collabora Limited 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. Client implementations SHOULD use StreamTube and DBusTube instead.

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.

The Tubes channel type may be requested for handles of type HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM.

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.

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.

A struct (tube ID, initiator handle, tube type, service name, parameters, state) representing a tube, as returned by ListTubes on the Tubes channel type. Represents a participant in a multi-user D-Bus tube, as returned by GetDBusNames and seen in the DBusNamesChanged signal. The handle of a participant in this D-Bus tube. That participant's unique name.

The tube is D-Bus tube as described by the org.freedesktop.Telepathy.Channel.Type.DBusTube interface.

The tube is stream tube as described by the org.freedesktop.Telepathy.Channel.Type.StreamTube interface.

The tube is waiting to be accepted/closed locally. The tube is waiting to be accepted/closed remotely. The tube is open for traffic. The supported socket address and access-control types for tubes. See GetAvailableStreamTubeTypes. List the available address types and access-control types for stream tubes.

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.

A typical value for a host without IPv6 support:

            {
              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]
            }

If stream tubes are not supported, this will be an empty dictionary.

An array of the available tube types, as defined by the Tube_Type enum. Return an array of tuples, each representing a tube, with the following members:

the tube's ID
the tube's initiator
the tube's type
the tube's service
the tube's parameters
the tube's state

Offers a D-Bus tube providing the service specified. 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. 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'. The ID of the new tube.

The contact associated with this channel doesn't have tubes capabilities. The connection manager doesn't support D-Bus tubes.

Offer a stream tube exporting the local socket specified. 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 http://www.iana.org/assignments/port-numbers or http://www.dns-sd.org/ServiceTypes.html, for instance "rsync" or "daap".

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

These should usually be the same key-value pairs specified for use in the DNS-SD TXT record for that service.

The type of the listening address of the local service, as a member of Socket_Address_Type. The listening address of the local service, as indicated by the address_type. The access control the local service applies to the local socket, specified so the connection manager can behave appropriately when it connects. A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum. The ID of the new tube.

The contact associated with this channel doesn't have tube capabilities. The connection manager doesn't support stream tubes, or does not support the given address type or access-control type.

Emitted when a tube is created. The ID of the new tube. The handle of the contact who initiated the tube. The tube type, as defined by the Tube_Type enum. A string representing the service that will be used over the tube. The new tube's properties. The new tube's state. 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. The ID of the tube to accept. The string describing the address of the private bus. The client should not attempt to connect to the address until the tube is open.

The given tube ID is invalid or does not refer to a D-Bus tube.

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. The ID of the tube to accept. The type of address the connection manager should listen on. The type of access control the connection manager should apply to the socket. A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum. 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.

The given tube ID is invalid or does not refer to a stream tube. The given address type or access-control mechanism is not supported.

Emitted when the state of a tube changes. The ID of the tube that changed state. The new state of the tube; see the Tube_State enumeration. Close a tube. The ID of the tube to close.

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. The ID of the tube that was closed. For a D-Bus tube, return a string describing the address of the private bus. The ID of the tube to get an address for. The bus address.

The tube is not a D-Bus tube. This tube is not in the "open" state.

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. The ID of the tube to get names for. An array of structures, each containing a contact handle and a D-Bus bus name.

The tube is not a multi-user D-Bus tube. This tube is not in the "open" state.

Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a participant opens or closes the tube. The ID of the tube whose names have changed. Array of handles and D-Bus names of new participants. Array of handles of former participants. For a stream tube, obtain the address of the socket used to communicate over this tube. The ID of the stream tube to get the socket for. The type of the listening address of the socket, as a member of Socket_Address_Type. The listening address of the socket, as indicated by the address_type.

The tube is not a stream tube. This tube is not in the "open" state.

Emitted on a stream tube when a participant opens a new connection to its socket. The ID of the tube The handle of the participant who opened the new connection