Observers need to implement the Client and Client.Observer interfaces. The Client.Interfaces property should include org.freedesktop.Telepathy.Client.Observer.

The ObserverChannelFilter property must be implemented so that the Channel Dispatcher knows what types of channels your Observer is interested in.

dbus.Array([
    dbus.Dictionary({
                    }, signature='sv'),
           ], signature='a{sv}')

dbus.Array([
    dbus.Dictionary({
        'org.freedesktop.Telepathy.Channel.ChannelType':      'org.freedesktop.Telepathy.Channel.Type.Text',
	'org.freedesktop.Telepathy.Channel.TargetHandleType': HANDLE_TYPE_CONTACT,
	'org.freedesktop.Telepathy.Channel.Requested':        True,
                    }, signature='sv'),
    dbus.Dictionary({
        'org.freedesktop.Telepathy.Channel.ChannelType':      'org.freedesktop.Telepathy.Channel.Type.Text',
	'org.freedesktop.Telepathy.Channel.TargetHandleType': HANDLE_TYPE_ROOM,
	'org.freedesktop.Telepathy.Channel.Requested':        True,
                    }, signature='sv'),
           ], signature='a{sv}')

Finally the ObserveChannels method must be implemented. This method is called by the Channel Dispatcher whenever a new channel matching your filter arrives. It takes six parameters:

Approvers are very similar to Observers. Approvers need to implement the Client and Client.Approver interfaces. The Client.Interfaces property must include org.freedesktop.Telepathy.Client.Approver.

The ApproverChannelFilter property must be implemented so that the Channel Dispatcher knows what types of channels your Approver is interested in. This property has the same form as for Observers.

Finally the AddDispatchOperation method must be implemented. This method is called by the Channel Dispatcher whenever a new channel matching your filter arrives. This method has three parameters:

Each Approver should connect to the dispatch operation's Finished and ChannelLost signals. The Finished signal indicates that some Approver has handled the dispatch, and this dispatch object is no longer valid. The ChannelLost indicates that one of the original channels making up this dispatch has been closed for the reason given.

If an Approver returns from AddDispatchOperation with no error, the Channel Dispatcher will assume the Approver accepts the dispatch and is offering it to the user, and thus will wait for the Approver to handle the dispatch operation by calling Claim or HandleWith methods. If you return from this method without error, you must intend to call one of these two functions, else the channel may never be dispatched to a Handler.

To indicate you're not interested in approving a channel, return a D-Bus error from AddDispatchOperation.

Otherwise call the HandleWith or Claim method on the dispatch operation.

The HandleWith method tells the Channel Dispatcher to pass the dispatch to a Handler by calling HandleChannels on that Handler. You must either provide the name of a Handler from the list of possible Handlers provided in the PossibleHandlers property or an empty string if you wish to use the Channel Dispatcher's preferred Handler.

HandleWith may return one of several errors, for instance raising NotYours if the dispatch has already been approved; or possibly even some error returned from HandleChannels.

The Claim method tells the Channel Dispatcher that you are claiming the dispatch for yourself. Assuming the method returns without error (i.e. the dispatch wasn't already handled), the dispatch belongs to your client. The Channel Dispatcher will not call HandleChannels in this instance. Clients that claim a dispatch, but do not immediately reject it should also implement the Handler interface, specifically HandledChannels.

Handlers are the most commonly implemented class of Telepathy Client. Handlers need to implement the Client and Client.Handler interfaces. They may also optionally implement the Client.Interface.Requests interface.

The Client.Interfaces property must include org.freedesktop.Telepathy.Client.Handler and optionally org.freedesktop.Telepathy.Client.Interface.Requests.

The HandlerChannelFilter property must be implemented so that the Channel Dispatcher knows what types of channels your Handler is interested in. This property has the same form as for Observers.

The Capabilities property is the list of additional Telepathy capabilities this Handler supports. These capabilities can also be listed in the .client file.

The BypassApproval property indicates that channels in your HandlerChannelFilter. This property is normally used when a Client registers a second Client object with channels that its expecting.

The HandledChannels property is a list of D-Bus object paths for Channels this Client is handling. This property only exists to recover state in the event of a Channel Dispatcher crash, so there is no need to emit a signal when the property is updated. This property should include the channels for any temporary transient Client objects registered by the client.

The HandleChannels method must be implemented. This is the method the Channel Dispatcher will call to dispatch channels to a Handler, either because it chose a Handler or in response to an Approver calling HandleWith (this method is not called is an Approver calls Claim). The method takes six parameters:

Returning an error from HandleChannels causes the Channel Dispatcher to assume the Handler has failed or crashed, what happens in this circumstance is left up to the Channel Dispatcher.

telepathy-glib provides a class, TpBaseClient, that simplifies implementing Telepathy clients by providing the client service on the D-Bus. TpBaseClient is an abstract base class that can be inherited to create any mixture of client types. telepathy-glib also provides three basic concrete classes, one for each client type: TpSimpleObserver, TpSimpleApprover and TpSimpleHandler.

Example 4-2 provides an example of creating a TpSimpleHandler to handle file transfer channels.

/* create a new Handler */
handler = tp_simple_handler_new (dbus, FALSE, FALSE, CLIENT_NAME, FALSE,
    handle_channels, NULL, NULL);

/* add a channel filter */
tp_base_client_take_handler_filter (handler, tp_asv_new (
      /* only FT channels */
      TP_PROP_CHANNEL_CHANNEL_TYPE,
      G_TYPE_STRING,
      TP_IFACE_CHANNEL_TYPE_FILE_TRANSFER,
      /* we always need a TargetHandleType so that the Handler's
       * capabilities are exported via the Connection Manager */
      TP_PROP_CHANNEL_TARGET_HANDLE_TYPE,
      G_TYPE_UINT,
      TP_HANDLE_TYPE_CONTACT,

      NULL));

/* register the Handler on the D-Bus */
if (!tp_base_client_register (handler, &error))
  g_error ("%s", error->message);

The TpAccount, TpConnection and TpChannel objects passed to the callback are all prepared with the core feature. You must hold a reference to the object to access it outside the callback.

Each callback is passed a context object; one of TpObserveChannelsContext, TpAddDispatchOperationContext, or TpHandleChannelsContext; named after the D-Bus method that triggers the callback. Each context object provides three methods: accept, fail and delay; one of which must be called before the end of the callback.

The Accept and Fail methods are used to return from the ObserveChannels, AddDispatchOperation and HandleChannels D-Bus methods, either successfully or with an error condition.

The Delay method is used if you have further preparation to carry out before ultimately calling either Accept or Fail. This is often used for things that Observers or Approvers need to do before the Handler is given the channel, like inspecting the pending message queue. You must reference the context object to hold it outside the callback. Example 4-3 shows an example of using the delay method.

static void
observe_channels (TpSimpleObserver *observer,
    TpAccount *account,
    TpConnection *connection,
    GList *channels,
    TpChannelDispatchOperation *dispatch,
    GList *requests,
    TpObserveChannelsContext *context,
    gpointer user_data)
{
  GList *l;

  g_debug ("ObserveChannels");

  for (l = channels; l != NULL; l = l->next)
    {
      TpChannel *channel = l->data;
      TpHandleType handle_type;

      /* request the pending message queue */
      tp_cli_channel_type_text_call_list_pending_messages (channel, -1,
          FALSE,
          list_pending_messaged_cb, NULL, NULL, G_OBJECT (context));
      increment_pending (context);

      tp_channel_get_handle (channel, &handle_type);
      if (handle_type == TP_HANDLE_TYPE_ROOM)
        {
          /* prepare the group property */
          GQuark features[] = { TP_CHANNEL_FEATURE_GROUP, 0 };

          tp_proxy_prepare_async (channel, features, channel_group_prepared,
              context);
          increment_pending (context);
        }

      /* hold a reference to the channel, that we release on invalidation */
      g_object_ref (channel);
      g_signal_connect (channel, "invalidated",
          G_CALLBACK (channel_invalided), NULL);
    }

  /* hold a reference to @context */
  g_object_ref (context);
  /* delay responding to @context until our callbacks have finished */
  tp_observe_channels_context_delay (context);
}