Interface Channel.Type.Tubes

Interface Index (Compact) | Summary | Description | Methods | Signals | Types

Methods

GetAvailableStreamTubeTypes () → a{uau}: Available_Stream_Tube_Types
GetAvailableTubeTypes () → au: Available_Tube_Types
ListTubes () → a(uuusa{sv}u): Tubes
OfferDBusTube (s: Service, a{sv}: Parameters) → u: Tube_ID
OfferStreamTube (s: Service, a{sv}: Parameters, u: Address_Type, v: Address, u: Access_Control, v: Access_Control_Param) → u: Tube_ID
AcceptDBusTube (u: ID) → s: Address
AcceptStreamTube (u: ID, u: Address_Type, u: Access_Control, v: Access_Control_Param) → v: Address
CloseTube (u: ID) → nothing
GetDBusTubeAddress (u: ID) → s: Address
GetDBusNames (u: ID) → a(us): DBus_Names
GetStreamTubeSocketAddress (u: ID) → u: Address_Type, v: Address

Signals

NewTube (u: ID, u: Initiator, u: Type, s: Service, a{sv}: Parameters, u: State)
TubeStateChanged (u: ID, u: State)
TubeClosed (u: ID)
DBusNamesChanged (u: ID, a(us): Added, au: Removed)
StreamTubeNewConnection (u: ID, u: Handle)

Types

Tube_ID Simple Type u
Tube_Type Enum u
Tube_State Enum u
Supported_Socket_Map Mapping a{uau}
Tube_Info Struct (uuusa{sv}u)
DBus_Tube_Member Struct (us)
Deprecated since 0.17.25. Client implementations SHOULD use StreamTube and DBusTube instead.
Objects implementing this interface must also implement:

Description

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.

Methods

(Permalink)

GetAvailableStreamTubeTypes () → a{uau}: Available_Stream_Tube_Types

Returns

  • Available_Stream_Tube_Types — a{uau} (Supported_Socket_Map)

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

List the available address types and access-control types for stream tubes.
(Permalink)

GetAvailableTubeTypes () → au: Available_Tube_Types

Returns

  • Available_Tube_Types — au (Tube_Type_List)
    • An array of the available tube types, as defined by the Tube_Type enum.
(Permalink)

ListTubes () → a(uuusa{sv}u): Tubes

Returns

  • Tubes — a(uuusa{sv}u) (Tube_Info_List)
    • 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
(Permalink)

OfferDBusTube (s: Service, a{sv}: Parameters) → u: Tube_ID

Parameters

  • Service — s
    • 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.
  • Parameters — a{sv} (String_Variant_Map)
    • 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'.

Returns

  • Tube_ID — u (Tube_ID)
    • The ID of the new tube.
Offers a D-Bus tube providing the service specified.

Possible Errors

  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Not Available
    • The contact associated with this channel doesn't have tubes capabilities.
  • Not Implemented
    • The connection manager doesn't support D-Bus tubes.
(Permalink)

OfferStreamTube (s: Service, a{sv}: Parameters, u: Address_Type, v: Address, u: Access_Control, v: Access_Control_Param) → u: Tube_ID

Parameters

  • Service — s
    • 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".
  • Parameters — a{sv} (String_Variant_Map)

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

  • Address_Type — u (Socket_Address_Type)
    • The type of the listening address of the local service, as a member of Socket_Address_Type.
  • Address — v
    • The listening address of the local service, as indicated by the address_type.
  • Access_Control — u (Socket_Access_Control)
    • The access control the local service applies to the local socket, specified so the connection manager can behave appropriately when it connects.
  • Access_Control_Param — v
    • A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.

Returns

  • Tube_ID — u (Tube_ID)
    • The ID of the new tube.
Offer a stream tube exporting the local socket specified.

Possible Errors

  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Not Available
    • The contact associated with this channel doesn't have tube capabilities.
  • Not Implemented
    • The connection manager doesn't support stream tubes, or does not support the given address type or access-control type.
(Permalink)

AcceptDBusTube (u: ID) → s: Address

Parameters

  • ID — u (Tube_ID)
    • The ID of the tube to accept.

Returns

  • Address — s
    • The string describing the address of the private bus. The client should not attempt to connect to the address until the tube is open.
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.

Possible Errors

  • Invalid Argument
    • The given tube ID is invalid or does not refer to a D-Bus tube.
(Permalink)

AcceptStreamTube (u: ID, u: Address_Type, u: Access_Control, v: Access_Control_Param) → v: Address

Parameters

  • ID — u (Tube_ID)
    • The ID of the tube to accept.
  • Address_Type — u (Socket_Address_Type)
    • The type of address the connection manager should listen on.
  • Access_Control — u (Socket_Access_Control)
    • The type of access control the connection manager should apply to the socket.
  • Access_Control_Param — v
    • A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.

Returns

  • Address — v
    • 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.
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.

Possible Errors

  • Invalid Argument
    • The given tube ID is invalid or does not refer to a stream tube.
  • Not Implemented
    • The given address type or access-control mechanism is not supported.
(Permalink)

CloseTube (u: ID) → nothing

Parameters

  • ID — u (Tube_ID)
    • The ID of the tube to close.
Close a tube.

Possible Errors

(Permalink)

GetDBusTubeAddress (u: ID) → s: Address

Parameters

  • ID — u (Tube_ID)
    • The ID of the tube to get an address for.

Returns

  • Address — s
    • The bus address.
For a D-Bus tube, return a string describing the address of the private bus.

Possible Errors

(Permalink)

GetDBusNames (u: ID) → a(us): DBus_Names

Parameters

  • ID — u (Tube_ID)
    • The ID of the tube to get names for.

Returns

  • DBus_Names — a(us) (DBus_Tube_Member_List)
    • An array of structures, each containing a contact handle and a D-Bus bus name.
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.

Possible Errors

(Permalink)

GetStreamTubeSocketAddress (u: ID) → u: Address_Type, v: Address

Parameters

  • ID — u (Tube_ID)
    • The ID of the stream tube to get the socket for.

Returns

  • Address_Type — u (Socket_Address_Type)
    • The type of the listening address of the socket, as a member of Socket_Address_Type.
  • Address — v
    • The listening address of the socket, as indicated by the address_type.
For a stream tube, obtain the address of the socket used to communicate over this tube.

Possible Errors

Signals

(Permalink)

NewTube (u: ID, u: Initiator, u: Type, s: Service, a{sv}: Parameters, u: State)

Parameters

  • ID — u (Tube_ID)
    • The ID of the new tube.
  • Initiator — u (Contact_Handle)
    • The handle of the contact who initiated the tube.
  • Type — u (Tube_Type)
    • The tube type, as defined by the Tube_Type enum.
  • Service — s
    • A string representing the service that will be used over the tube.
  • Parameters — a{sv} (String_Variant_Map)
    • The new tube's properties.
  • State — u (Tube_State)
    • The new tube's state.
Emitted when a tube is created.
(Permalink)

TubeStateChanged (u: ID, u: State)

Parameters

  • ID — u (Tube_ID)
    • The ID of the tube that changed state.
  • State — u (Tube_State)
    • The new state of the tube; see the Tube_State enumeration.
Emitted when the state of a tube changes.
(Permalink)

TubeClosed (u: ID)

Parameters

  • ID — u (Tube_ID)
    • The ID of the tube that was closed.
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.
(Permalink)

DBusNamesChanged (u: ID, a(us): Added, au: Removed)

Parameters

  • ID — u (Tube_ID)
    • The ID of the tube whose names have changed.
  • Added — a(us) (DBus_Tube_Member_List)
    • Array of handles and D-Bus names of new participants.
  • Removed — au (Contact_Handle_List)
    • Array of handles of former participants.
Emitted on a multi-user (i.e. Handle_Type_Room) D-Bus tube when a participant opens or closes the tube.
(Permalink)

StreamTubeNewConnection (u: ID, u: Handle)

Parameters

  • ID — u (Tube_ID)
    • The ID of the tube
  • Handle — u (Contact_Handle)
    • The handle of the participant who opened the new connection
Emitted on a stream tube when a participant opens a new connection to its socket.

Types

Simple Type (Permalink)

Tube_ID — u

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.
Enum (Permalink)

Tube_Type — u

  • DBus (0)

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

  • Stream (1)

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

Enum (Permalink)

Tube_State — u

  • Local_Pending (0)
    • The tube is waiting to be accepted/closed locally.
  • Remote_Pending (1)
    • The tube is waiting to be accepted/closed remotely.
  • Open (2)
    • The tube is open for traffic.
Mapping (Permalink)

Supported_Socket_Map — a{uau}

The supported socket address and access-control types for tubes. See GetAvailableStreamTubeTypes.
Struct (Permalink)

Tube_Info — (uuusa{sv}u)

A struct (tube ID, initiator handle, tube type, service name, parameters, state) representing a tube, as returned by ListTubes on the Tubes channel type.
Struct (Permalink)

DBus_Tube_Member — (us)

Represents a participant in a multi-user D-Bus tube, as returned by GetDBusNames and seen in the DBusNamesChanged signal.