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.

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.

tp_presence_status_spec_can_set_on_self ()

gboolean            tp_presence_status_spec_can_set_on_self
                                                        (const TpPresenceStatusSpec *self);

Since 0.23.1

tp_presence_status_spec_get_name ()

const gchar *       tp_presence_status_spec_get_name    (const TpPresenceStatusSpec *self);

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.

Since 0.23.1

tp_presence_status_spec_has_message ()

gboolean            tp_presence_status_spec_has_message (const TpPresenceStatusSpec *self);

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

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.

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

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.

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.

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

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.

Since 0.14.5

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.

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.

tp_presence_status_free ()

void                tp_presence_status_free             (TpPresenceStatus *status);

Deallocate all resources associated with a presence status structure.

TpPresenceMixin

typedef struct _TpPresenceMixin 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.

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

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

tp_presence_mixin_finalize ()

void                tp_presence_mixin_finalize          (GObject *obj);

Free resources held by the presence 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.

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.

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.

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.

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.

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