• Telepathy Developer's Manual
• Channels

Channels may be requested from the Channel Dispatcher or directly from a Connection object using the Requests interface.

Requesting a channel from the dispatcher will cause it to be handled like any other dispatched channel. This is the preferred way of requesting new channels.

Requesting a channel directly from the Connection will cause it to be ignored by the Channel Dispatcher, meaning that the requesting application must handle the channel itself.

These interfaces provides two methods: CreateChannel and EnsureChannel. Both methods take the same parameter, a dictionary containing the desired properties for the channel.

CreateChannel will attempt to create a new channel with the requested properties. Depending on the protocol, some types of channels are exclusive, and only one such channel can exist at a time (e.g. a XMPP chatroom). If a second channel is requested, the error NotAvailable is returned.

Conversely, EnsureChannel will attempt to reuse an existing channel with the same properties wherever possible, else it will create a new channel. It's possible that another client is also utilising this channel.

The properties argument for CreateChannel and EnsureChannel is a map of property names on the desired channel, and their values. In general every channel requires at least three channel properties: the type of channel we wish to create (ChannelType), the handle/id of the contact/room/list we wish to create a channel for (TargetHandle or TargetID) and the type of that handle (TargetHandleType). Specific channel types may require additional properties in order to be created, this is noted in the specification.

For example, to create a ContactList channel (this is the type of channel that is used to get a list of subscribed contacts from a service), we might provide a map like so:

More channel request examples are given in Example 6-1.

When using the Requests interface to request a channel directly from a Connection, both EnsureChannel and CreateChannel return the object path of a channel that can be access on that Connection.

Using the Channel Dispatcher, requests might take some time (e.g. if the account has to be brought online), so you are instead returned a Channel Request Object, which is discussed further in Section 6.1.1 ― Channel Request Objects.

class TextChannel (telepathy.client.Channel):
    def __init__ (self, parent, channel_path):
        self.parent = parent
        conn = parent.conn

        super (TextChannel, self).__init__ (conn.service_name, channel_path)

props = tp_asv_new (
    TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING, TP_IFACE_CHANNEL_TYPE_TEXT,
    TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, TP_TYPE_HANDLE, TP_HANDLE_TYPE_ROOM,
    TP_PROP_CHANNEL_TARGET_ID, G_TYPE_STRING, targetid,
    NULL);

request = tp_account_channel_request_new (TP_ACCOUNT (account),
    props, TP_USER_ACTION_TIME_CURRENT_TIME);

/* ensure this channel, but let the default handler handle it */
tp_account_channel_request_ensure_channel_async (request,
    NULL, NULL, _muc_channel_ready, NULL);

g_hash_table_destroy (props);
g_object_unref (request);

/* explicitly ask for the publish and subscribe contact lists
 * these will be announced by NewChannels, so we don't need
 * to handle their callbacks (this does mean we also can't
 * handle their errors) */
GHashTable *request = tp_asv_new (
        TP_PROP_CHANNEL_CHANNEL_TYPE,
        G_TYPE_STRING,
        TP_IFACE_CHANNEL_TYPE_CONTACT_LIST,

        TP_PROP_CHANNEL_TARGET_HANDLE_TYPE,
        G_TYPE_UINT,
        TP_HANDLE_TYPE_LIST,

        NULL);

/* the 'publish' list */
tp_asv_set_string (request,
        TP_PROP_CHANNEL_TARGET_ID, "publish");
tp_cli_connection_interface_requests_call_ensure_channel (
                conn, -1, request, NULL, NULL, NULL, NULL);

/* the 'subscribe' list */
tp_asv_set_string (request,
        TP_PROP_CHANNEL_TARGET_ID, "subscribe");
tp_cli_connection_interface_requests_call_ensure_channel (
                conn, -1, request, NULL, NULL, NULL, NULL);

g_hash_table_destroy (request);

const char *type = tp_asv_get_string (map,
                TP_PROP_CHANNEL_CHANNEL_TYPE);

/* if this channel is a contact list, we want to know
 * about it */
if (!strcmp (type, TP_IFACE_CHANNEL_TYPE_CONTACT_LIST))
{
        TpChannel *channel = tp_channel_new_from_properties (
                        conn, object_path, map,
                        &error);
        handle_error (error);

        tp_channel_call_when_ready (channel,
                        channel_ready, NULL);
}

        self.conn[CONNECTION].RequestChannel(CHANNEL_TYPE_ROOM_LIST,
                                             HANDLE_TYPE_NONE, 0,
                                             True,
                                             reply_handler = self.got_roomlist,
                                             error_handler = self.error)

# begin example.channel.roomlist.listrooms
def got_roomlist(self, channel_path):
    print 'Got Roomlist Channel'
    channel = telepathy.client.Channel(self.conn.service_name, channel_path)