TpPresenceMixin

## TpPresenceMixin TpPresenceMixin — a mixin implementation of the Presence connection interface |

## Synopsis

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

    struct              TpPresenceStatusOptionalArgumentSpec;
                        TpPresenceStatusSpec;
    gboolean            (*TpPresenceMixinStatusAvailableFunc)
                                                            (GObject *obj,
                                                             guint which);
    GHashTable *        (*TpPresenceMixinGetContactStatusesFunc)
                                                            (GObject *obj,
                                                             const GArray *contacts,
                                                             GError **error);
    gboolean            (*TpPresenceMixinSetOwnStatusFunc)  (GObject *obj,
                                                             const TpPresenceStatus *status,
                                                             GError **error);
                        TpPresenceStatus;
    TpPresenceStatus *  tp_presence_status_new              (guint which,
                                                             GHashTable *optional_arguments);
    void                tp_presence_status_free             (TpPresenceStatus *status);
                        TpPresenceMixin;
                        TpPresenceMixinClass;
    void                tp_presence_mixin_class_init        (GObjectClass *obj_cls,
                                                             glong offset,
                                                             TpPresenceMixinStatusAvailableFunc status_available,
                                                             TpPresenceMixinGetContactStatusesFunc get_contact_statuses,
                                                             TpPresenceMixinSetOwnStatusFunc set_own_status,
                                                             const TpPresenceStatusSpec *statuses);
    void                tp_presence_mixin_init              (GObject *obj,
                                                             glong offset);
    void                tp_presence_mixin_finalize          (GObject *obj);
    void                tp_presence_mixin_emit_presence_update
                                                            (GObject *obj,
                                                             GHashTable *contact_presences);
    void                tp_presence_mixin_emit_one_presence_update
                                                            (GObject *obj,
                                                             TpHandle handle,
                                                             const TpPresenceStatus *status);
    void                tp_presence_mixin_iface_init        (gpointer g_iface,
                                                             gpointer iface_data);
    void                tp_presence_mixin_simple_presence_iface_init
                                                            (gpointer g_iface,
                                                             gpointer iface_data);
    void                tp_presence_mixin_simple_presence_init_dbus_properties
                                                            (GObjectClass *cls);
    void                tp_presence_mixin_simple_presence_register_with_contacts_mixin
                                                            (GObject *obj);

## Description

This mixin can be added to a TpBaseConnection subclass to implement the presence interface in a general way. It does not support protocols where it is possible to set multiple statuses on yourself at once, however. Hence all presence statuses will have the exclusive flag set.

There are plans to deprecate the notion of last activity time in the D-Bus presence interface, so TpPresenceStatus doesn't include it at all. Consequently, the last activity time field in presence data presented over D-Bus will always be zero and the SetLastActivityTime method doesn't actually do anything.

To use the presence mixin, include a TpPresenceMixinClass somewhere in your class structure and a TpPresenceMixin somewhere in your instance structure, and call `tp_presence_mixin_class_init()` from your class_init function, `tp_presence_mixin_init()` from your init function or constructor, and `tp_presence_mixin_finalize()` from your dispose or finalize function.

To use the presence mixin as the implementation of TpSvcConnectionInterfacePresence, in the function you pass to G_IMPLEMENT_INTERFACE, you should call tp_presence_mixin_iface_init. TpPresenceMixin implements all of the D-Bus methods in the Presence interface.

Since 0.7.13 you can also implement TpSvcConnectionInterfaceSimplePresence by using this mixin, in this case you should pass tp_presence_mixin_iface_init as an argument to G_IMPLEMENT_INTERFACE. Note that this can cause the status_available callback to be called while disconnected. Also to fully implement this interface some dbus properties need to be supported. To do that using this mixin the instance needs to use the dbus properties mixin and call tp_presence_mixin_simple_presence_init_dbus_properties in the class init function

## Details

### struct TpPresenceStatusOptionalArgumentSpec

    struct TpPresenceStatusOptionalArgumentSpec {
        const gchar *name;
        const gchar *dtype;
    };

Structure specifying a supported optional argument for a presence status.

In addition to the fields documented here, there are two gpointer fields which must currently be `NULL`. A meaning may be defined for these in a future version of telepathy-glib.

const gchar *`name`; | Name of the argument as passed over D-Bus
const gchar *`dtype`; | D-Bus type signature of the argument

### TpPresenceStatusSpec

    typedef struct {
        const gchar *name;
        TpConnectionPresenceType presence_type;
        gboolean self;
        const TpPresenceStatusOptionalArgumentSpec *optional_arguments;
    } TpPresenceStatusSpec;

Structure specifying a supported presence status.

In addition to the fields documented here, there are two gpointer fields which must currently be `NULL`. A meaning may be defined for these in a future version of telepathy-glib.

const gchar *`name`; | String identifier of the presence status
TpConnectionPresenceType `presence_type`; | A type value, as specified by TpConnectionPresenceType
gboolean `self`; | Indicates if this status may be set on yourself
const TpPresenceStatusOptionalArgumentSpec *`optional_arguments`; | An array of TpPresenceStatusOptionalArgumentSpec structures representing the optional arguments for this status, terminated by a NULL name. If there are no optional arguments for a status, this can be NULL.

### TpPresenceMixinStatusAvailableFunc ()

    gboolean            (*TpPresenceMixinStatusAvailableFunc)
                                                            (GObject *obj,
                                                             guint which);

Signature of the callback used to determine if a given status is currently available to be set on the connection.

When implementing the org.freedesktop.Telepathy.Connection.Interface.SimplePresence interface this can be called while DISCONNECTED to determine which statuses can be set in that state.

`obj` : | An object implementing the presence interface with this mixin
`which` : | The index of the presence status in the provided supported presence statuses array
Returns : | `TRUE` if the status is available, `FALSE` if not.

### TpPresenceMixinGetContactStatusesFunc ()

    GHashTable *        (*TpPresenceMixinGetContactStatusesFunc)
                                                            (GObject *obj,
                                                             const GArray *contacts,
                                                             GError **error);

Signature of the callback used to get the stored presence status of contacts. The returned hash table should have contact handles mapped to their respective presence statuses in TpPresenceStatus structs.

The returned hash table will be freed with g_hash_table_destroy. The callback is responsible for ensuring that this does any cleanup that may be necessary.

`obj` : | An object with this mixin.
`contacts` : | An array of TpHandle for the contacts to get presence status for
`error` : | Used to return a Telepathy D-Bus error if `NULL` is returned
Returns : | The contact presence on success, `NULL` with error set on error

### TpPresenceMixinSetOwnStatusFunc ()

    gboolean            (*TpPresenceMixinSetOwnStatusFunc)  (GObject *obj,
                                                             const TpPresenceStatus *status,
                                                             GError **error);

Signature of the callback used to commit changes to the user's own presence status in SetStatuses. It is also used in ClearStatus and RemoveStatus to reset the user's own status back to the "default" one with a `NULL` status argument.

The optional_arguments hash table in `status`, if not NULL, will have been filtered so it only contains recognised parameters, so the callback need not (and cannot) check for unrecognised parameters. However, the types of the parameters are not currently checked, so the callback is responsible for doing so.

The callback is responsible for emitting PresenceUpdate, if appropriate, by calling `tp_presence_mixin_emit_presence_update()`.

`obj` : | An object with this mixin.
`status` : | The status to set, or NULL for whatever the protocol defines as a "default" status
`error` : | Used to return a Telepathy D-Bus error if `FALSE` is returned
Returns : | `TRUE` if the operation was successful, `FALSE` if not.

### TpPresenceStatus

    typedef struct {
        guint index;
        GHashTable *optional_arguments;
    } TpPresenceStatus;

Structure representing a presence status.

In addition to the fields documented here, there are two gpointer fields which must currently be `NULL`. A meaning may be defined for these in a future version of telepathy-glib.

guint `index`; | Index of the presence status in the provided supported presence statuses array
GHashTable *`optional_arguments`; | A GHashTable mapping of string identifiers to GValues of the optional status arguments, if any. If there are no optional arguments, this pointer may be NULL.

### tp_presence_status_new ()

    TpPresenceStatus *  tp_presence_status_new              (guint which,
                                                             GHashTable *optional_arguments);

Construct a presence status structure. You should free the returned structure with tp_presence_status_free.

`which` : | Index of the presence status in the provided supported presence statuses array
`optional_arguments` : | Optional arguments for the presence statuses. Can be NULL if there are no optional arguments. The presence status object makes a copy of the hashtable, so you should free the original.
Returns : | A pointer to the newly allocated presence status structure.

### tp_presence_status_free ()

    void                tp_presence_status_free             (TpPresenceStatus *status);

Deallocate all resources associated with a presence status structure.

`status` : | A pointer to the presence status structure to free.

### TpPresenceMixin

    typedef struct {
    } TpPresenceMixin;

Structure to be included in the instance structure of objects that use this mixin. Initialize it with `tp_presence_mixin_init()`.

There are no public fields.

### TpPresenceMixinClass

    typedef struct {
        TpPresenceMixinStatusAvailableFunc status_available;
        TpPresenceMixinGetContactStatusesFunc get_contact_statuses;
        TpPresenceMixinSetOwnStatusFunc set_own_status;

        const TpPresenceStatusSpec *statuses;
    } TpPresenceMixinClass;

Structure to be included in the class structure of objects that use this mixin. Initialize it with `tp_presence_mixin_class_init()`.

All fields should be considered read-only.

TpPresenceMixinStatusAvailableFunc `status_available`; | The status-available function that was passed to `tp_presence_mixin_class_init()`
TpPresenceMixinGetContactStatusesFunc `get_contact_statuses`; | The get-contact-statuses function that was passed to `tp_presence_mixin_class_init()`
TpPresenceMixinSetOwnStatusFunc `set_own_status`; | The set-own-status function that was passed to `tp_presence_mixin_class_init()`
const TpPresenceStatusSpec *`statuses`; | The presence statuses array that was passed to `tp_presence_mixin_class_init()`

### tp_presence_mixin_class_init ()

    void                tp_presence_mixin_class_init        (GObjectClass *obj_cls,
                                                             glong offset,
                                                             TpPresenceMixinStatusAvailableFunc status_available,
                                                             TpPresenceMixinGetContactStatusesFunc get_contact_statuses,
                                                             TpPresenceMixinSetOwnStatusFunc set_own_status,
                                                             const TpPresenceStatusSpec *statuses);

Initialize the presence mixin. Should be called from the implementation's class_init function like so:

    1
    2
    3
    tp_presence_mixin_class_init ((GObjectClass *) klass,
                                  G_STRUCT_OFFSET (SomeObjectClass,
                                                   presence_mixin));

`obj_cls` : | The class of the implementation that uses this mixin
`offset` : | The byte offset of the TpPresenceMixinClass within the class structure
`status_available` : | A callback to be used to determine if a given presence status is available to be set on the connection. If NULL, all statuses are always considered available.
`get_contact_statuses` : | A callback to be used get the current presence status for contacts. This is used in implementations of various D-Bus methods and hence must be provided.
`set_own_status` : | A callback to be used to commit changes to the user's own presence status to the server. This is used in implementations of various D-Bus methods and hence must be provided.
`statuses` : | An array of TpPresenceStatusSpec structures representing all presence statuses supported by the protocol, terminated by a NULL name.

### tp_presence_mixin_init ()

    void                tp_presence_mixin_init              (GObject *obj,
                                                             glong offset);

Initialize the presence mixin. Should be called from the implementation's instance init function like so:

    1
    2
    tp_presence_mixin_init ((GObject *) self,
                            G_STRUCT_OFFSET (SomeObject, presence_mixin));

`obj` : | An instance of the implementation that uses this mixin
`offset` : | The byte offset of the TpPresenceMixin within the object structure

### tp_presence_mixin_finalize ()

    void                tp_presence_mixin_finalize          (GObject *obj);

Free resources held by the presence mixin.

`obj` : | An object with this mixin.

### tp_presence_mixin_emit_presence_update ()

    void                tp_presence_mixin_emit_presence_update
                                                            (GObject *obj,
                                                             GHashTable *contact_presences);

Emit the PresenceUpdate signal for multiple contacts. For emitting PresenceUpdate for a single contact, there is a convenience wrapper called tp_presence_mixin_emit_one_presence_update.

`obj` : | A connection object with this mixin
`contact_presences` : | A mapping of contact handles to TpPresenceStatus structures with the presence data to emit

### tp_presence_mixin_emit_one_presence_update ()

    void                tp_presence_mixin_emit_one_presence_update
                                                            (GObject *obj,
                                                             TpHandle handle,
                                                             const TpPresenceStatus *status);

Emit the PresenceUpdate signal for a single contact. This method is just a convenience wrapper around tp_presence_mixin_emit_presence_update.

`obj` : | A connection object with this mixin
`handle` : | The handle of the contact to emit the signal for
`status` : | The new status to emit

### tp_presence_mixin_iface_init ()

    void                tp_presence_mixin_iface_init        (gpointer g_iface,
                                                             gpointer iface_data);

Fill in the vtable entries needed to implement the presence interface using this mixin. This function should usually be called via G_IMPLEMENT_INTERFACE.

`g_iface` : | A pointer to the TpSvcConnectionInterfacePresenceClass in an object class
`iface_data` : | Ignored

### tp_presence_mixin_simple_presence_iface_init ()

    void                tp_presence_mixin_simple_presence_iface_init
                                                            (gpointer g_iface,
                                                             gpointer iface_data);

Fill in the vtable entries needed to implement the simple presence interface using this mixin. This function should usually be called via G_IMPLEMENT_INTERFACE.

`g_iface` : | A pointer to the TpSvcConnectionInterfaceSimplePresenceClass in an object class
`iface_data` : | Ignored

Since 0.7.13

### tp_presence_mixin_simple_presence_init_dbus_properties ()

    void                tp_presence_mixin_simple_presence_init_dbus_properties
                                                            (GObjectClass *cls);

Set up TpDBusPropertiesMixinClass to use this mixin's implementation of the SimplePresence interface's properties.

This uses `tp_presence_mixin_get_simple_dbus_property()` as the property getter and sets up a list of the supported properties for it.

`cls` : | The class of an object with this mixin

Since 0.7.13

### tp_presence_mixin_simple_presence_register_with_contacts_mixin ()

    void                tp_presence_mixin_simple_presence_register_with_contacts_mixin
                                                            (GObject *obj);

Register the SimplePresence interface with the Contacts interface to make it inspectable. The Contacts mixin should be initialized before this function is called

`obj` : | An instance that of the implementation that uses both the Contacts mixin and this mixin

## See Also

TpSvcConnectionInterfacePresence