## TpSimpleObserver

TpSimpleObserver — a subclass of TpBaseClient implementing a simple Observer

## Functions

void | ( *TpSimpleObserverObserveChannelsImpl ) ()
TpBaseClient * | tp_simple_observer_new ()
TpBaseClient * | tp_simple_observer_new_with_am ()
TpBaseClient * | tp_simple_observer_new_with_factory ()

## Properties

gpointer | callback | Write / Construct Only
gpointer | destroy | Write / Construct Only
gboolean | recover | Write / Construct Only
gpointer | user-data | Write / Construct Only

## Types and Values

struct | TpSimpleObserver

## Object Hierarchy

        GObject
        ╰── TpBaseClient
            ╰── TpSimpleObserver

## Implemented Interfaces

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

## Includes

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

## Description

This class makes it easier to write TpSvcClient implementing the TpSvcClientObserver interface.

A typical simple observer 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

    static void
    my_observe_channels (TpSimpleObserver *observer,
       TpAccount *account,
       TpConnection *connection,
       GList *channels,
       TpChannelDispatchOperation *dispatch_operation,
       GList *requests,
       TpObserveChannelsContext *context,
       gpointer user_data)
    {
     /<!-- -->* do something useful with the channels here *<!-- -->/

     tp_observe_channels_context_accept (context);
    }

    factory = tp_automatic_client_factory_new (dbus);
    client = tp_simple_observer_new_with_factory (factory, TRUE, "MyObserver",
        FALSE, my_observe_channels, user_data);
    g_object_unref (factory);

    tp_base_client_take_observer_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/media-observer.c for a complete example.

## Functions

### TpSimpleObserverObserveChannelsImpl ()

    void
    (*TpSimpleObserverObserveChannelsImpl)
                                   (TpSimpleObserver *observer,
                                    TpAccount *account,
                                    TpConnection *connection,
                                    GList *channels,
                                    TpChannelDispatchOperation *dispatch_operation,
                                    GList *requests,
                                    TpObserveChannelsContext *context,
                                    gpointer user_data);

Signature of the implementation of the ObserveChannels method.

This function must call either `tp_observe_channels_context_accept()`, `tp_observe_channels_context_delay()` or `tp_observe_channels_context_fail()` on `context` before it returns.

#### Parameters

observer | a TpSimpleObserver 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]
dispatch_operation | a TpChannelDispatchOperation or `NULL`; the dispatch_operation is not guaranteed to be prepared. | [allow-none]
requests | a GList of TpChannelRequest, all having their object-path defined but are not guaranteed to be prepared. | [element-type TelepathyGLib.ChannelRequest]
context | a TpObserveChannelsContext representing the context of this D-Bus call |
user_data | arbitrary user-supplied data passed to `tp_simple_observer_new()` |

Since 0.11.5

### tp_simple_observer_new ()

    TpBaseClient *
    tp_simple_observer_new (TpDBusDaemon *dbus,
                            gboolean recover,
                            const gchar *name,
                            gboolean uniquify,
                            TpSimpleObserverObserveChannelsImpl callback,
                            gpointer user_data,
                            GDestroyNotify destroy);

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

New code should use `tp_simple_observer_new_with_am()` instead.

Convenient function to create a new TpSimpleObserver instance.

If `dbus` is not the result of `tp_dbus_daemon_dup()`, you should call `tp_simple_observer_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` |
recover | the value of the Observer.Recover D-Bus property |
name | the name of the Observer (see “name”: for details) |
uniquify | the value of the “uniquify-name”: property |
callback | the function called when ObserveChannels is called |
user_data | arbitrary user-supplied data passed to `callback` |
destroy | called with the user_data as argument, when the TpSimpleObserver is destroyed |

#### Returns

a new TpSimpleObserver.

[type TelepathyGLib.SimpleObserver]

Since 0.11.5

### tp_simple_observer_new_with_am ()

    TpBaseClient *
    tp_simple_observer_new_with_am (TpAccountManager *account_manager,
                                    gboolean recover,
                                    const gchar *name,
                                    gboolean uniquify,
                                    TpSimpleObserverObserveChannelsImpl callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy);

Convenient function to create a new TpSimpleObserver 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` |
recover | the value of the Observer.Recover D-Bus property |
name | the name of the Observer (see “name”: for details) |
uniquify | the value of the “uniquify-name”: property |
callback | the function called when ObserveChannels is called |
user_data | arbitrary user-supplied data passed to `callback` |
destroy | called with the user_data as argument, when the TpSimpleObserver is destroyed |

#### Returns

a new TpSimpleObserver.

[type TelepathyGLib.SimpleObserver]

Since 0.11.14

### tp_simple_observer_new_with_factory ()

    TpBaseClient *
    tp_simple_observer_new_with_factory (TpSimpleClientFactory *factory,
                                         gboolean recover,
                                         const gchar *name,
                                         gboolean uniquify,
                                         TpSimpleObserverObserveChannelsImpl callback,
                                         gpointer user_data,
                                         GDestroyNotify destroy);

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

#### Parameters

factory | a TpSimpleClientFactory, which may not be `NULL` |
recover | the value of the Observer.Recover D-Bus property |
name | the name of the Observer (see “name”: for details) |
uniquify | the value of the “uniquify-name”: property |
callback | the function called when ObserveChannels is called |
user_data | arbitrary user-supplied data passed to `callback` |
destroy | called with the user_data as argument, when the TpSimpleObserver is destroyed |

#### Returns

a new TpSimpleObserver.

[type TelepathyGLib.SimpleObserver]

Since 0.15.5

## Types and Values

### struct TpSimpleObserver

    struct TpSimpleObserver;

Data structure representing a simple Observer implementation.

Since 0.11.5

## Property Details

### The `“callback”` property

      “callback”                 gpointer

The TpSimpleObserverObserveChannelsImpl callback implementing the ObserveChannels D-Bus method.

This property can't be `NULL`.

Flags: Write / Construct Only

Since 0.11.5

### The `“destroy”` property

      “destroy”                  gpointer

The GDestroyNotify function called to free the user-data pointer when the TpSimpleObserver is destroyed.

Flags: Write / Construct Only

Since 0.11.5

### The `“recover”` property

      “recover”                  gboolean

The value of the Observer.Recover D-Bus property.

Flags: Write / Construct Only

Default value: FALSE

Since 0.11.5

### The `“user-data”` property

      “user-data”                gpointer

The user-data pointer passed to the callback implementing the ObserveChannels D-Bus method.

Flags: Write / Construct Only

Since 0.11.5