Top | ![]() |
![]() |
![]() |
![]() |
struct | TpPresenceStatusOptionalArgumentSpec |
struct | TpPresenceStatusSpec |
struct | TpPresenceStatus |
struct | TpPresenceMixin |
struct | TpPresenceMixinClass |
This mixin can be added to a TpBaseConnection subclass to implement the Presence interface.
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.
Since 0.7.13 this mixin supports the entire Presence interface. You can implement TpSvcConnectionInterfacePresence1 as follows:
use the TpContactsMixin and TpDBusPropertiesMixin;
pass tp_presence_mixin_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_PRESENCE1, tp_presence_mixin_iface_init); // ... ) |
call tp_presence_mixin_init_dbus_properties()
in the
GTypeInfo class_init function;
in the TpBaseConnectionClass.fill_contact_attributes
implementation, call tp_presence_mixin_fill_contact_attributes()
and do not chain up if it returns TRUE
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
// ... if (!tp_strdiff (dbus_interface, MY_IFACE_CONNECTION_INTERFACE_HATS)) { // ... fill in Hats attributes ... return; } if (tp_presence_mixin_fill_contact_attributes (G_OBJECT (self), dbus_interface, contact, attributes)) { return; } ((TpBaseConnectionClass *) my_connection_parent_class)-> fill_contact_attributes (self, dbus_interface, contact, attributes); |
gboolean
tp_presence_status_spec_can_set_on_self
(const TpPresenceStatusSpec *self
);
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.99.5
const gchar *
tp_presence_status_spec_get_name (const TpPresenceStatusSpec *self
);
Since 0.99.5
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.99.5
gboolean
tp_presence_status_spec_has_message (const TpPresenceStatusSpec *self
);
Since 0.99.5
TpPresenceStatusSpec * tp_presence_status_spec_new (const gchar *name
,TpConnectionPresenceType type
,gboolean can_set_on_self
,gboolean has_message
);
Since 0.99.5
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.99.5
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.99.5
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.
obj |
An instance of a TpBaseConnection subclass implementing the presence interface with this mixin |
|
which |
An index into the array of TpPresenceStatusSpec provided to
|
TpPresenceStatus * (*TpPresenceMixinGetContactStatusFunc) (GObject *obj
,TpHandle contact
);
Return the contact's status
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 |
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.
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
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.
void
tp_presence_status_free (TpPresenceStatus *status
);
Deallocate all resources associated with a presence status structure.
void tp_presence_mixin_class_init (GObjectClass *obj_cls
,glong offset
,TpPresenceMixinStatusAvailableFunc status_available
,TpPresenceMixinGetContactStatusFunc get_contact_status
,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 can be set on a particular connection. Should usually be |
|
get_contact_status |
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. |
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)); |
Since 0.99.1 obj
must be a TpBaseConnection subclass.
void
tp_presence_mixin_finalize (GObject *obj
);
Free resources held by the presence mixin.
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 |
void tp_presence_mixin_emit_one_presence_update (GObject *obj
,TpHandle handle
,const TpPresenceStatus *status
);
Emit a presence update signal for a single contact. This method is just a convenience wrapper around tp_presence_mixin_emit_presence_update.
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 TpSvcConnectionInterfacePresence1Class in an object class |
|
iface_data |
Ignored |
Since 0.7.13
void
tp_presence_mixin_init_dbus_properties
(GObjectClass *cls
);
Set up TpDBusPropertiesMixinClass to use this mixin's implementation of the Presence interface's properties.
This automatically sets up a list of the supported properties for the Presence interface.
Since 0.7.13
gboolean tp_presence_mixin_fill_contact_attributes (GObject *obj
,const gchar *dbus_interface
,TpHandle contact
,TpContactAttributeMap *attributes
);
If dbus_interface
is an interface that is relevant for this
object, fill attributes
with the attributes for contact
and return TRUE
.
obj |
an object with a TpPresenceMixin |
|
dbus_interface |
a D-Bus interface |
|
contact |
a contact |
|
attributes |
used to return attributes |
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 { 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.
const gchar * |
String identifier of the presence status |
|
TpConnectionPresenceType |
A type value, as specified by TpConnectionPresenceType |
|
gboolean |
Indicates if this status may be set on yourself |
|
const TpPresenceStatusOptionalArgumentSpec * |
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 { 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.
guint |
Index of the presence status in the provided supported presence statuses array |
|
GHashTable * |
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 { };
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 { TpPresenceMixinStatusAvailableFunc status_available; TpPresenceMixinGetContactStatusFunc get_contact_status; 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.
TpPresenceMixinStatusAvailableFunc |
The status-available function that was passed to
|
|
TpPresenceMixinGetContactStatusFunc |
The get-contact-status function that was passed to
|
|
TpPresenceMixinSetOwnStatusFunc |
The set-own-status function that was passed to
|
|
const TpPresenceStatusSpec * |
The presence statuses array that was passed to
|
|
TpPresenceMixinGetMaximumStatusMessageLengthFunc |
The callback used to discover the the limit for status messages length, if any. Since: 0.14.5 |