D-Bus Tubes allow you to share a private D-Bus bus between two or more clients, proxied over Telepathy. This allows clients to make method calls and emit signals using regular D-Bus semantics rather than requiring an individual RPC protocol to be developed.
For one-to-one D-Bus Tubes, the Tube behaves like a peer-to-peer D-Bus connection. The sender and destination addresses are arbitrary and the other client receives all D-Bus messages that are sent.
For multi-user D-Bus Tubes Telepathy sets up a private, peer-to-peer D-Bus "bus" brokered by the Telepathy Connection Managers. There is, however, no service through which to register or lookup service names. Requests should be made using a client's unique name (see Section 2.2 ― Using D-Bus). Instead a mapping of Telepathy contact handles to D-Bus addresses is made available via the DbusNames property.
D-Bus Tubes, especially MUC D-Bus Tubes, may prove unsuitable for high-bandwidth communication. It is not possible to detect or specify the transport mechanism for a Telepathy Tube (e.g. out-of-band socket, or in-band with the protocol), nor determine what bandwidth is available.
As it stands for multi-user Tubes in Telepathy-Gabble, D-Bus messages are transmitted between contacts inside XMPP messages relayed via the XMPP server rather than via peer-to-peer network sockets. Other types of Tubes will use a network socket (e.g. SOCKS5 bytestream) when it is available, else fall back to in-band messaging.
When creating the Tube, you must specify the property org.freedesktop.Telepathy.Channel.Type.DBusTube.ServiceName, which gives the name of the D-Bus service you intend to offer. The remote contact will not receive the channel until you call the Offer method.
The DbusTube.Offer method takes two parameters:
The parameter map allows properties to be passed that will be useful in deciding whether to accept the Tube (e.g. the name of the file to collaborate on; or specifics of the game being played), or data about how to retrieve more information once the Tube has been established. Once the Tube has been offered, this map will remain available through the Parameters property.
The access control flag should be set to Socket_Access_Control_Localhost. No other type makes sense for a D-Bus connection.
If the contact does not support Tubes, Offer will return the NotAvailable error. Otherwise the address of a private D-Bus bus will be supplied.
You must be able to retrieve a contact's capabilities (i.e. call GetContactCapabilities) in order to determine whether or not a contact supports Tubes. For some protocols (e.g. XMPP) this requires you to be subscribed to the contact's presence.
For a multi-user Tube, the room you are connecting to should already exist as a text channel. Create a text channel before offering the Tube.
The State property will change from Tube_Channel_State_Not_Offered to Tube_Channel_State_Remote_Pending, indicating that the remote contact has to accept the tube.
Offer will return the address of a private D-Bus connection. This should be stored until the channel is in the state Tube_Channel_State_Open (listen for TubeChannelStateChanged), at which point the bus is ready to be connected to.
An incoming Tube appears as an incoming channel (see Section 6.2 ― Incoming Channels). The Tube will have two immutable properties that you can inspect; ServiceName, which was passed when creating the Tube channel, and Parameters, the map of parameters passed to Offer.
The channel will be in the initial State Tube_Channel_State_Local_Pending, indicating that you have to Accept the Tube.
The DbusTube.Accept method takes one property, the access control mode. This should be set to Socket_Access_Control_Localhost. No other mode makes sense for a D-Bus connection.
Like Offer, Accept will return the address of a private D-Bus connection. This address should be stored until the channel's State changes to Tube_Channel_State_Open, as noted by the TubeChannelStateChanged property.
Connection to the private bus is done using dbus_connection_open, dbus_g_connection_open or other similar function.
There is no "bus driver" present on this bus (nothing provides org.freedesktop.DBus), so there is no way to call D-Bus methods like ListNames, RequestName, and GetNameOwner, etc.
For one-to-one channels, the Tube works like a private, peer-to-peer D-Bus connection. Any transmitted messages will arrive at the other end regardless of their source or destination addresses.
For multi-user Tubes, the property DbusNames provides the mapping of Telepathy contact handles to D-Bus unique names. The signal DBusNamesChanged will be emitted when this property changes (e.g. users enter or leave the group).