TpSimpleHandler

## TpSimpleHandler TpSimpleHandler — a subclass of TpBaseClient implementing a simple Handler |

## Synopsis

    #include <telepathy-glib/simple-handler.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