Creating a Tube

Telepathy Tubes are created by calling CreateChannel with the type of Tube, target and required properties (see Section 6.1 ― Requesting Channels). The target can either be a contact (Handle_Type_Contact) or a room (Handle_Type_Room). Example 11-1 gives some example parameter maps to create Tubes.

Don't Use Old (Deprecated) Tubes API

Telepathy originally had a different API for implementing Telepathy Tubes, org.freedesktop.Telepathy.Channel.Type.Tubes.

This API was deprecated because it had several serious design flaws and did not allow for future expansion.

Example 11-1Example Parameter Maps to Create Tubes
D-Bus, One-to-One Tube
org.freedesktop.Telepathy.Channel.ChannelType org.freedesktop.Telepathy.Channel.Type.DBusTube
org.freedesktop.Telepathy.Channel.TargetHandleType Handle_Type_Contact
org.freedesktop.Telepathy.Channel.TargetID "bob@example.com"
org.freedesktop.Telepathy.Channel.Type.DBusTube.ServiceName "com.example.ExampleService"
D-Bus, One-to-Many Tube
org.freedesktop.Telepathy.Channel.ChannelType org.freedesktop.Telepathy.Channel.Type.DBusTube
org.freedesktop.Telepathy.Channel.TargetHandleType Handle_Type_Room
org.freedesktop.Telepathy.Channel.TargetID "tubegame@conference.xmpp.example.com"
org.freedesktop.Telepathy.Channel.Type.DBusTube.ServiceName "com.example.TubeGame"
Stream, One-to-One Tube
org.freedesktop.Telepathy.Channel.ChannelType org.freedesktop.Telepathy.Channel.Type.StreamTube
org.freedesktop.Telepathy.Channel.TargetHandleType Handle_Type_Contact
org.freedesktop.Telepathy.Channel.TargetID "bob@example.com"
org.freedesktop.Telepathy.Channel.Type.StreamTube.Service "ssh"

Once the initiator has created the channel, it must be offered to the receipient/group. This is done by calling the Offer method. The parameters to this method depend on the type of Tube that is being offered. Once the Tube is offered it will be in the Remote Pending state.

Calling the Offer method requires you to be able to establish a contact's capabilities. For some protocols, e.g. XMPP, this requires being subscribed to the contact's presence.

Figure 11-1 presents an overview of setting up a Tube.

Figure 11-1Flowchart for Setting up a Tube