Signals
| TubeChannelStateChanged | (u: State) |
Properties
| Parameters | a{sv} (String_Variant_Map) | Read only | |
| State | u (Tube_Channel_State) | Read only |
Types
| Tube_Channel_State | Enum | u | |
| Socket_Address_Type | Enum | u | |
| Socket_Access_Control | Enum | u |
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.
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
TubeChannelStateChanged (u: State)
Parameters
- State — u (Tube_Channel_State)
Properties
Parameters — a{sv} (String_Variant_Map)
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 — u (Tube_Channel_State)
State of the tube in this channel.
When requesting a tube with CreateChannel, this property MUST NOT be included in the request.
Types
Tube_Channel_State — u
- Local_Pending (0)
- Remote_Pending (1)
- Open (2)
- Not_Offered (3)
Socket_Address_Type — u
- Unix (0)
- Abstract_Unix (1)
- IPv4 (2)
- IPv6 (3)
Socket_Access_Control — u
- Localhost (0)
- Port (1)
- Netmask (2)
- Credentials (3)
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.