Interface Channel.Interface.Tube

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

Signals

TubeChannelStateChanged (u: State)

Properties

Parameters a{sv} ( String_Variant_Map) Read only Sometimes immutable
State u ( Tube_Channel_State) Read only

Types

Tube_Channel_State Enum u
Socket_Address_Type Enum u
Socket_Access_Control Enum u
Objects implementing this interface must also implement:

Description

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.

Rationale:

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.

Signals

(Permalink)

TubeChannelStateChanged (u: State)

Parameters

Emitted when the state of the tube channel changes. Valid state transitions are documented with Tube_Channel_State.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

Parameters — a{sv} (String_Variant_Map)

Read only
Depending on the protocol, this property may be immutable which means that it can never change once the channel has been created. Immutable properties SHOULD appear in the channel detail list of NewChannel signals.

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.

(Permalink)

State — u (Tube_Channel_State)

Read only

State of the tube in this channel.

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

Types

Enum (Permalink)

Tube_Channel_State — u

  • Local_Pending (0)
    • 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.
  • Remote_Pending (1)
    • The tube is waiting to be accepted/closed remotely. If the recipient accepts the tube, the tube's state will be Open.
  • Open (2)
    • 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.
  • Not_Offered (3)
    • 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.
Enum (Permalink)

Socket_Address_Type — u

  • Unix (0)
    • A Unix socket. The address variant contains a byte-array, signature 'ay', containing the path of the socket.
  • Abstract_Unix (1)
    • An abstract Unix socket. The address variant contains a byte-array, signature 'ay', containing the path of the socket including the leading null byte.
  • IPv4 (2)
    • 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.
  • IPv6 (3)
    • 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.
Enum (Permalink)

Socket_Access_Control — u

  • Localhost (0)

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

    For a D-Bus tube, this means that the "same user" access control typically provided by default in D-Bus implementations SHOULD be disabled. If the socket is only available to local users (e.g. a Unix socket, an IPv4 socket bound to 127.0.0.1, or an IPv6 socket bound to ::1), the ANONYMOUS authentication mechanism MAY be enabled.

  • Port (1)
    • May only be used on IP sockets, and only for Stream tubes. 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.
  • Netmask (2)
    • Deprecated since 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.
    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.
  • Credentials (3)

    • The high-level meaning of this access control type is that only the same user (e.g. same numeric Unix uid) is allowed to interact with the tube. Exactly how this is achieved varies by channel type.

    For StreamTube channels, this access control type 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, without any attached credentials. (This mechanism is very similar to the first byte of a D-Bus connection, except that in D-Bus the byte is always zero, whereas in Tubes it can be nonzero.)

    For DBusTube channels, this access control type may be used on any type of socket, and there is no extra byte added by Telepathy at the beginning of the stream: all bytes in the stream are part of the D-Bus tube connection. The connecting process should prove its identity via any of the SASL authentication mechanisms usually used for D-Bus (in typical D-Bus implementations this involves either sending and receiving credentials as above, or demonstrating the ability to write to a file in the user's home directory).

    In either case, 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.

    In either tube type, the associated variant must be ignored.