TpSimpleHandler: telepathy-glib API Reference Manual

TpSimpleHandler

TpSimpleHandler — a subclass of TpBaseClient implementing a simple Handler

Functions

void	(*TpSimpleHandlerHandleChannelsImpl) ()
TpBaseClient *	tp_simple_handler_new ()
TpBaseClient *	tp_simple_handler_new_with_am ()
TpBaseClient *	tp_simple_handler_new_with_factory ()

Properties

gboolean	bypass-approval	Write / Construct Only
gpointer	callback	Write / Construct Only
gpointer	destroy	Write / Construct Only
gboolean	requests	Write / Construct Only
gpointer	user-data	Write / Construct Only

Types and Values

struct

TpSimpleHandler

Object Hierarchy

    GObject
    ╰── TpBaseClient
        ╰── TpSimpleHandler

Implemented Interfaces

TpSimpleHandler implements TpSvcDBusProperties, TpSvcClient, TpSvcClientObserver, TpSvcClientApprover, TpSvcClientHandler and TpSvcClientInterfaceRequests.

Includes

#include <telepathy-glib/telepathy-glib.h>

Description

This class makes it easier to construct a TpSvcClient implementing the TpSvcClientHandler interface.

A typical simple handler would look liks this:

static void
my_handle_channels (TpSimpleHandler *handler,
   TpAccount *account,
   TpConnection *connection,
   GList *channels,
   GList *requests_satisfied,
   gint64 user_action_time,
   GList *requests,
   TpHandleChannelsContext *context,
   gpointer user_data)
{
 /<!-- -->* start handling the channels here *<!-- -->/

 tp_handle_channels_context_accept (context);
}

factory = tp_automatic_client_factory_new (dbus);
client = tp_simple_handler_new_with_factory (factory, FALSE, FALSE,
    "MyHandler", FALSE, my_handle_channels, user_data);
g_object_unref (factory);

tp_base_client_take_handler_filter (client, tp_asv_new (
     TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING, TP_IFACE_CHANNEL_TYPE_TEXT,
     TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, G_TYPE_UINT, TP_HANDLE_TYPE_CONTACT,
     NULL));

tp_base_client_register (client, NULL);

See examples/client/text-handler.c for a complete example.

Functions

TpSimpleHandlerHandleChannelsImpl ()

void
(*TpSimpleHandlerHandleChannelsImpl) (TpSimpleHandler *handler,
                                      TpAccount *account,
                                      TpConnection *connection,
                                      GList *channels,
                                      GList *requests_satisfied,
                                      gint64 user_action_time,
                                      TpHandleChannelsContext *context,
                                      gpointer user_data);

Signature of the implementation of the HandleChannels method.

This function must call either tp_handle_channels_context_accept(), tp_handle_channels_context_delay() or tp_handle_channels_context_fail() on context before it returns.

Parameters

handler	a TpSimpleHandler instance
account	a TpAccount having `TP_ACCOUNT_FEATURE_CORE` prepared if possible
connection	a TpConnection having `TP_CONNECTION_FEATURE_CORE` prepared if possible
channels	a GList of TpChannel, all having `TP_CHANNEL_FEATURE_CORE` prepared if possible.	[element-type TelepathyGLib.Channel]
requests_satisfied	a GList of TpChannelRequest having their object-path defined but are not guaranteed to be prepared.	[element-type TelepathyGLib.ChannelRequest]
user_action_time	the time at which user action occurred, or one of the special values `TP_USER_ACTION_TIME_NOT_USER_ACTION` or `TP_USER_ACTION_TIME_CURRENT_TIME` (see “user-action-time” for details)
context	a TpHandleChannelsContext representing the context of this D-Bus call
user_data	arbitrary user-supplied data passed to `tp_simple_handler_new()`

Since: 0.11.6

tp_simple_handler_new ()

TpBaseClient *
tp_simple_handler_new (TpDBusDaemon *dbus,
                       gboolean bypass_approval,
                       gboolean requests,
                       const gchar *name,
                       gboolean uniquify,
                       TpSimpleHandlerHandleChannelsImpl callback,
                       gpointer user_data,
                       GDestroyNotify destroy);

tp_simple_handler_new is deprecated and should not be used in newly-written code.

New code should use tp_simple_handler_new_with_am() instead.

Convenient function to create a new TpSimpleHandler instance.

If dbus is not the result of tp_dbus_daemon_dup(), you should call tp_simple_handler_new_with_am() instead, so that TpAccount, TpConnection and TpContact instances can be shared between modules.

Parameters

dbus	a TpDBusDaemon object, may not be `NULL`
bypass_approval	the value of the Handler.BypassApproval D-Bus property (see `tp_base_client_set_handler_bypass_approval()` for details)
requests	whether this handler should implement Requests (see `tp_base_client_set_handler_request_notification()` for details)
name	the name of the Handler (see “name” for details)
uniquify	the value of the “uniquify-name” property
callback	the function called when HandleChannels is called
user_data	arbitrary user-supplied data passed to `callback`
destroy	called with `user_data` as its argument when the TpSimpleHandler is destroyed

Returns

a new TpSimpleHandler.

[type TelepathyGLib.SimpleHandler]

Since: 0.11.6

tp_simple_handler_new_with_am ()

TpBaseClient *
tp_simple_handler_new_with_am (TpAccountManager *account_manager,
                               gboolean bypass_approval,
                               gboolean requests,
                               const gchar *name,
                               gboolean uniquify,
                               TpSimpleHandlerHandleChannelsImpl callback,
                               gpointer user_data,
                               GDestroyNotify destroy);

Convenient function to create a new TpSimpleHandler instance with a specified TpAccountManager.

It is not necessary to prepare any features on account_manager before calling this function.

Parameters

account_manager	an account manager, which may not be `NULL`
bypass_approval	the value of the Handler.BypassApproval D-Bus property (see `tp_base_client_set_handler_bypass_approval()` for details)
requests	whether this handler should implement Requests (see `tp_base_client_set_handler_request_notification()` for details)
name	the name of the Handler (see “name” for details)
uniquify	the value of the “uniquify-name” property
callback	the function called when HandleChannels is called
user_data	arbitrary user-supplied data passed to `callback`
destroy	called with `user_data` as its argument when the TpSimpleHandler is destroyed

Returns

a new TpSimpleHandler.

[type TelepathyGLib.SimpleHandler]

Since: 0.11.14

tp_simple_handler_new_with_factory ()

TpBaseClient *
tp_simple_handler_new_with_factory (TpSimpleClientFactory *factory,
                                    gboolean bypass_approval,
                                    gboolean requests,
                                    const gchar *name,
                                    gboolean uniquify,
                                    TpSimpleHandlerHandleChannelsImpl callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy);

Convenient function to create a new TpSimpleHandler instance with a specified TpSimpleClientFactory.

Parameters

factory	a TpSimpleClientFactory, which may not be `NULL`
bypass_approval	the value of the Handler.BypassApproval D-Bus property (see `tp_base_client_set_handler_bypass_approval()` for details)
requests	whether this handler should implement Requests (see `tp_base_client_set_handler_request_notification()` for details)
name	the name of the Handler (see “name” for details)
uniquify	the value of the “uniquify-name” property
callback	the function called when HandleChannels is called
user_data	arbitrary user-supplied data passed to `callback`
destroy	called with `user_data` as its argument when the TpSimpleHandler is destroyed

Returns

a new TpSimpleHandler.

[type TelepathyGLib.SimpleHandler]

Since: 0.15.5

Types and Values

struct TpSimpleHandler

struct TpSimpleHandler;

Data structure representing a simple Handler implementation.

Since: 0.11.6

Property Details

The `“bypass-approval”` property

  “bypass-approval”          gboolean

The value of the Handler.BypassApproval D-Bus property.

Owner: TpSimpleHandler

Flags: Write / Construct Only

Default value: FALSE

Since: 0.11.6

The `“callback”` property

  “callback”                 gpointer

The TpSimpleHandlerHandleChannelsImpl callback implementing the HandleChannels D-Bus method.

This property can't be NULL.

Owner: TpSimpleHandler

Flags: Write / Construct Only

Since: 0.11.6

The `“destroy”` property

  “destroy”                  gpointer

The GDestroyNotify function called to free “user-data” when the TpSimpleHandler is destroyed.

Owner: TpSimpleHandler

Flags: Write / Construct Only

Since: 0.11.6

The `“requests”` property

  “requests”                 gboolean

If TRUE, the Handler will implement the Requests interface

Owner: TpSimpleHandler

Flags: Write / Construct Only

Default value: FALSE

Since: 0.11.6

The `“user-data”` property

  “user-data”                gpointer

The user-data pointer passed to “callback”.

Owner: TpSimpleHandler

Flags: Write / Construct Only

Since: 0.11.6