TpPresenceMixin: telepathy-glib API Reference Manual

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

## Functions

gboolean | tp_presence_status_spec_can_set_on_self ()
const gchar * | tp_presence_status_spec_get_name ()
TpConnectionPresenceType | tp_presence_status_spec_get_presence_type ()
gboolean | tp_presence_status_spec_has_message ()
TpPresenceStatusSpec * | tp_presence_status_spec_new ()
TpPresenceStatusSpec * | tp_presence_status_spec_copy ()
void | tp_presence_status_spec_free ()
gboolean | (*TpPresenceMixinStatusAvailableFunc) ()
GHashTable * | (*TpPresenceMixinGetContactStatusesFunc) ()
gboolean | (*TpPresenceMixinSetOwnStatusFunc) ()
guint | (*TpPresenceMixinGetMaximumStatusMessageLengthFunc) ()
TpPresenceStatus * | tp_presence_status_new ()
void | tp_presence_status_free ()
void | tp_presence_mixin_class_init ()
void | tp_presence_mixin_init ()
void | tp_presence_mixin_finalize ()
void | tp_presence_mixin_emit_presence_update ()
void | tp_presence_mixin_emit_one_presence_update ()
void | tp_presence_mixin_iface_init ()
void | tp_presence_mixin_simple_presence_iface_init ()
void | tp_presence_mixin_simple_presence_init_dbus_properties ()
void | tp_presence_mixin_simple_presence_register_with_contacts_mixin ()

## Types and Values

struct | TpPresenceStatusOptionalArgumentSpec
struct | TpPresenceStatusSpec
struct | TpPresenceStatus
struct | TpPresenceMixin
struct | TpPresenceMixinClass

## Object Hierarchy

        GBoxed
        ╰── TpPresenceStatusSpec

## Includes

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

## Description

This mixin can be added to a TpBaseConnection subclass to implement the SimplePresence and/or Presence interfaces. Implementing both interfaces (as described below) is recommended. In particular, you must implement the old-style Presence interface if compatibility with telepathy-glib versions older than 0.11.13 is required.

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.

## Implementing SimplePresence

Since 0.7.13 this mixin supports the entire SimplePresence interface. You can implement TpSvcConnectionInterfaceSimplePresence as follows:

- use the TpContactsMixin and TpDBusPropertiesMixin;

- pass `tp_presence_mixin_simple_presence_iface_init()` as an argument to `G_IMPLEMENT_INTERFACE()`, like so:

      1
      2
      3
      4
      5
      6
      7
      G_DEFINE_TYPE_WITH_CODE (MyConnection, my_connection,
          TP_TYPE_BASE_CONNECTION,
          // ...
          G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CONNECTION_INTERFACE_SIMPLE_PRESENCE,
              tp_presence_mixin_simple_presence_iface_init);
          // ...
          )

- call `tp_presence_mixin_simple_presence_init_dbus_properties()` in the GTypeInfo class_init function;

- call `tp_presence_mixin_simple_presence_register_with_contacts_mixin()` in the GObjectClass constructed function.

## Implementing old-style Presence

This mixin also supports a large subset of the deprecated Presence interface. It does not support protocols where it is possible to set multiple statuses on yourself at once (all presence statuses will have the exclusive flag set), or last-activity-time information.

To use the presence mixin as the implementation of TpSvcConnectionInterfacePresence, use `tp_presence_mixin_iface_init()` as the function you pass to `G_IMPLEMENT_INTERFACE()`, as in the following example. The presence mixin implements all of the D-Bus methods in the Presence interface.

    1
    2
    3
    4
    5
    6
    7
    G_DEFINE_TYPE_WITH_CODE (MyConnection, my_connection,
        TP_TYPE_BASE_CONNECTION,
        // ...
        G_IMPLEMENT_INTERFACE (TP_TYPE_SVC_CONNECTION_INTERFACE_PRESENCE,
            tp_presence_mixin_iface_init);
        // ...
        )

In telepathy-glib versions older than 0.11.13, every connection that used the TpPresenceMixin was required to implement TpSvcConnectionInterfacePresence; failing to do so would lead to an assertion failure. Since 0.11.13, this is no longer required.

## Functions

### tp_presence_status_spec_can_set_on_self ()

    gboolean
    tp_presence_status_spec_can_set_on_self
                                   (const TpPresenceStatusSpec *self);

#### Parameters

self | a presence status specification |

#### Returns

`TRUE` if the user can set this presence status on themselves (most statuses), or `FALSE` if they cannot directly set it on themselves (typically used for `TP_CONNECTION_PRESENCE_TYPE_OFFLINE` and `TP_CONNECTION_PRESENCE_TYPE_ERROR`)

Since: 0.23.1

### tp_presence_status_spec_get_name ()

    const gchar *
    tp_presence_status_spec_get_name (const TpPresenceStatusSpec *self);

#### Parameters

self | a presence status specification |

#### Returns

the name of this presence status, such as "available" or "out-to-lunch".

[transfer none]

Since: 0.23.1

### tp_presence_status_spec_get_presence_type ()

    TpConnectionPresenceType
    tp_presence_status_spec_get_presence_type
                                   (const TpPresenceStatusSpec *self);

Return the category into which this presence type falls. For instance, for XMPP's "" (do not disturb) status, this would return `TP_CONNECTION_PRESENCE_TYPE_BUSY`.

#### Parameters

self | a presence status specification |

#### Returns

a TpConnectionPresenceType

Since: 0.23.1

### tp_presence_status_spec_has_message ()

    gboolean
    tp_presence_status_spec_has_message (const TpPresenceStatusSpec *self);

#### Parameters

self | a presence status specification |

#### Returns

`TRUE` if this presence status is accompanied by an optional human-readable message

Since: 0.23.1

### tp_presence_status_spec_new ()

    TpPresenceStatusSpec *
    tp_presence_status_spec_new (const gchar *name,
                                 TpConnectionPresenceType type,
                                 gboolean can_set_on_self,
                                 gboolean has_message);

#### Parameters

name | the name of the new presence status |
type | the category into which this presence status falls |
can_set_on_self | `TRUE` if the user can set this presence status on themselves |
has_message | `TRUE` if this presence status is accompanied by an optional human-readable message |

#### Returns

a new TpPresenceStatusSpec.

[transfer full]

Since: 0.23.1

### tp_presence_status_spec_copy ()

    TpPresenceStatusSpec *
    tp_presence_status_spec_copy (const TpPresenceStatusSpec *self);

Copy a presence status specification.

If `self` has optional arguments other than a string named "message", they are not copied. Optional arguments with other names or types are deprecated.

#### Parameters

self | a presence status specification |

#### Returns

a new TpPresenceStatusSpec resembling `self` .

[transfer full]

Since: 0.23.1

### tp_presence_status_spec_free ()

    void
    tp_presence_status_spec_free (TpPresenceStatusSpec *self);

Free a presence status specification produced by `tp_presence_status_spec_new()` or `tp_presence_status_spec_copy()`.

#### Parameters

self | a presence status specification. | [transfer full]

Since: 0.23.1

### TpPresenceMixinStatusAvailableFunc ()

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

Signature of a callback to be used to determine if a given presence status can be set on the connection. Most users of this mixin do not need to supply an implementation of this callback: the value of TpPresenceStatusSpec.self is enough to determine whether this is a user-settable presence, so `NULL` should be passed to `tp_presence_mixin_class_init()` for this callback.

One place where this callback may be needed is on XMPP: not all server implementation support the user becoming invisible. So an XMPP implementation would implement this function, so that—once connected—the hidden status is only available if the server supports it. Before the connection is connected, this callback should return `TRUE` for every status that might possibly be supported: this allows the user to at least try to sign in as invisible.

#### Parameters

obj | An instance of a TpBaseConnection subclass implementing the presence interface with this mixin |
which | An index into the array of TpPresenceStatusSpec provided to `tp_presence_mixin_class_init()` |

#### Returns

`TRUE` if the status can be set on this connection; `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_unref. The callback is responsible for ensuring that this does any cleanup that may be necessary.

#### Parameters

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.

[transfer full]

### 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()`.

#### Parameters

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.

### TpPresenceMixinGetMaximumStatusMessageLengthFunc ()

    guint
    (*TpPresenceMixinGetMaximumStatusMessageLengthFunc)
                                   (GObject *obj);

Signature of a callback used to determine the maximum length of status messages. If this callback is provided and returns non-zero, the TpPresenceMixinSetOwnStatusFunc implementation is responsible for truncating the message to fit this limit, if necessary.

#### Parameters

obj | An object with this mixin. |

#### Returns

the maximum number of UTF-8 characters which may appear in a status message, or 0 if there is no limit.

Since: 0.14.5

### 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.

In modern Telepathy connection managers, the only optional argument should be a `G_TYPE_STRING` named "message", on statuses that have an optional human-readable message. All other optional arguments are deprecated.

[skip]

#### Parameters

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.

[skip]

#### Parameters

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

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

[skip]

#### Parameters

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 can be set on a particular connection. Should usually be `NULL`, to consider all statuses with TpPresenceStatusSpec.self set to `TRUE` to be settable. |
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));

[skip]

#### Parameters

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.

[skip]

#### Parameters

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.

[skip]

#### Parameters

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.

[skip]

#### Parameters

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.

[skip]

#### Parameters

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.

[skip]

#### Parameters

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 automatically sets up a list of the supported properties for the SimplePresence interface.

[skip]

#### Parameters

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

[skip]

#### Parameters

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

## Types and Values

### 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.

#### Members

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

### struct TpPresenceStatusSpec

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

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.

#### Members

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. In modern Telepathy connection managers, the only optional argument should be a string (type "s") named "message" on statuses that have an optional human-readable message. All other optional arguments are deprecated. |

### struct TpPresenceStatus

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

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.

In modern Telepathy connection managers, the only optional argument should be a `G_TYPE_STRING` named "message", on statuses that have an optional human-readable message. All other optional arguments are deprecated.

#### Members

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. |

### struct TpPresenceMixin

    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.

### struct TpPresenceMixinClass

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

        const TpPresenceStatusSpec *statuses;

        TpPresenceMixinGetMaximumStatusMessageLengthFunc get_maximum_status_message_length;
    };

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

If the protocol imposes a limit on the length of status messages, one should implement `get_maximum_status_message_length` . If this callback is not implemented, it is assumed that there is no limit. The callback function should be set after calling `tp_presence_mixin_class_init()`, like so:

    1
    2
    3
    4
    5
    6
    7
    TpPresenceMixinClass *mixin_class;

    tp_presence_mixin_class_init ((GObjectClass *) klass,
        G_STRUCT_OFFSET (SomeObjectClass, presence_mixin));
    mixin_class = TP_PRESENCE_MIXIN_CLASS (klass);
    mixin_class->get_maximum_status_message_length =
        some_object_get_maximum_status_message_length;

All other fields should be considered read-only.

#### Members

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()` |
TpPresenceMixinGetMaximumStatusMessageLengthFunc `get_maximum_status_message_length`; | The callback used to discover the the limit for status messages length, if any. Since: 0.14.5 |

## See Also

TpSvcConnectionInterfacePresence