Requesting Channels Contact Lists
Telepathy Logo

Incoming Channels

Besides channels that you request yourself, channels can be created by a remote user (e.g. text, or file transfer channels) or by the server you are connected to (e.g. contact group channels).

The creation of channels is heralded by up to three mechanisms:

  1. Via a method call on the Client made by the Channel Dispatcher (i.e. ObserveChannels or HandleChannels).

    This is the preferred method. See Section 6.2.1 ― The HandleChannels (or ObserveChannels) Method.

  2. Via the NewChannels signal emitted by a Connection's Requests interface.

    This should be used when talking to a Connection directly. See Section 6.2.2 ― The NewChannels Signal.

  3. Via the NewChannel signal, emitted by a Connection.

    This signal has been deprecated in favour of NewChannels and should not be used unless absolutely required to talk to a legacy Connection Manager. See Section 6.2.3 ― The NewChannel Signal.

6.2.1. The HandleChannels (or ObserveChannels) Method

In many cases, your Telepathy application will implement the Handler (or Observer) Telepathy Client interface (see Section 4.1 ― Telepathy Clients) allowing the Channel Dispatcher to dispatch incoming Telepathy channels to your application.

When the Channel Dispatcher wishes to notify your client of a new channel to handle, it calls the HandleChannels method on your client. This method contains the following information:

  1. The object path to the Account associated with these channels.

  2. The object path to the Connection associated with these channels.

  3. A list of channels as a Channel_Details_List.

    This is an array of structures containing object paths for the Channels and their associated properties — a(oa{sv}). This is the same structure that is passed to NewChannels.

  4. A list of object paths to requests that are satisfied by this method call. See ...

  5. A user action time.

    This is similar to the X11 user action time and can be used by the Handler for managing things like focus stealing prevention.

  6. An a{sv} map of unstructured handler information.

The ObserveChannels method is very similar to this, but includes the path of the ChannelDispatchOperation for the dispatch in progress and does not include the user action time.

If this method call succeeds (that is, does not return an error), then the Channel Dispatcher now considers the client to be responsible for these channels. The client should keep a list of channels it is handling so that they may be returned by the HandledChannels property.

HandleChannels May Be Called on Existing Channels

The Channel Dispatcher call HandleChannels on channels that your client is already handling. The Channel Dispatcher does this when it wants your client to present the channel to the user (i.e. bring the channel to the foreground).

6.2.2. The NewChannels Signal

New channels are heralded by a Connection with the NewChannels signal, which is part of the Connection's Requests interface.

When channels are created, the NewChannels callback will pass you a list of newly created channels by their object paths along with a map of immutable properties for the channel. All channels are announced, including channels that you created. You can check the Requested property to discover if this channel is one you requested yourself (i.e. via CreateChannel).

It is possible to call CreateChannel in a fire-and-forget way (if you don't care about error conditions), or only handle the error condition in the method callback, and do all of the channel setup in the NewChannels callback, using a common codepath for channels you requested, and channels you did not (e.g. setting up a new text channel).

If required, use the Requested property to determine if you created the channel yourself.

Use the ChannelType property to decide how to handle a channel.

Example 6-9 in Section 6.3.3 ― User Defined Groups gives an example of handling the NewChannels signal.

NewChannels is also used by the Channel Dispatcher to discover new channels coming from Connections. This means that the NewChannels signal is received before the HandleChannels method.

6.2.3. The NewChannel Signal

Deprecated

The NewChannel signal has been deprecated and should only be used if compatibility is required with older Connection Managers that do not implement the Requests interface.

NewChannel, like the method call RequestChannel, is part of the old channel requesting API and should not be used in new programs unless absolutely required because a Connection Manager does not support Requests (although this is a bug in the Connection Manager).

NewChannels has several advantages over the older NewChannel:

  • Related channels (or channels created as a side-effect of another creation) can be bundled together.

    For example, creating a multi-user Tube in XMPP requires joining the corresponding multi-user chatroom, so both channels can be announced in the same signal.

  • The callback includes a map with all of the channel's immutable properties, a useful optimisation.

NewChannels is always emitted first, followed by a NewChannel signal for each of the channels.

The parameters to the NewChannel signal, and their equivalents in NewChannels is presented in Table 6-2.

Table 6-2 NewChannel Parameters to NewChannels Properties
Parameter Type NewChannels equivalent
Object_Path D-Bus Object Path (o) Channel parameter
Channel_Type String org.freedesktop.Telepathy.Channel.ChannelType property
Handle_Type uint32 org.freedesktop.Telepathy.Channel.TargetHandleType property
Handle uint32 org.freedesktop.Telepathy.Channel.TargetHandle property
Suppress_Handler Boolean -
Requesting Channels Contact Lists