TpSimpleHandler

TpSimpleHandler — a subclass of TpBaseClient implementing a simple Handler

Synopsis

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

                    TpSimpleHandler;
void                (*TpSimpleHandlerHandleChannelsImpl)
                                                        (TpSimpleHandler *handler,
                                                         TpAccount *account,
                                                         TpConnection *connection,
                                                         GList *channels,
                                                         GList *requests_satisfied,
                                                         gint64 user_action_time,
                                                         TpHandleChannelsContext *context,
                                                         gpointer user_data);
TpBaseClient *      tp_simple_handler_new               (TpDBusDaemon *dbus,
                                                         gboolean bypass_approval,
                                                         gboolean requests,
                                                         const gchar *name,
                                                         gboolean uniquify,
                                                         TpSimpleHandlerHandleChannelsImpl callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy);
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);
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);

Object Hierarchy

  GObject
   +----TpBaseClient
         +----TpSimpleHandler

Implemented Interfaces

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

Properties

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

Description

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

A typical simple handler would look liks this: 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
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.

Details

TpSimpleHandler

typedef struct _TpSimpleHandler TpSimpleHandler;

Data structure representing a simple Handler implementation.

Since 0.11.6

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.

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);

Warning

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.

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.

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.

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

Property Details

The "bypass-approval" property

  "bypass-approval"          gboolean              : Write / Construct Only

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

Default value: FALSE

Since 0.11.6

The "callback" property

  "callback"                 gpointer              : Write / Construct Only

The TpSimpleHandlerHandleChannelsImpl callback implementing the HandleChannels D-Bus method.

This property can't be NULL.

Since 0.11.6

The "destroy" property

  "destroy"                  gpointer              : Write / Construct Only

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

Since 0.11.6

The "requests" property

  "requests"                 gboolean              : Write / Construct Only

If TRUE, the Handler will implement the Requests interface

Default value: FALSE

Since 0.11.6

The "user-data" property

  "user-data"                gpointer              : Write / Construct Only

The user-data pointer passed to "callback".

Since 0.11.6

Generated by GTK-Doc V1.19