telepathy-glib API Reference Manual: Connection Presence interface

Connection Presence interface

Connection Presence interface — client-side wrappers for the Presence interface

Functions

TpProxyPendingCall *	tp_cli_connection_interface_presence1_call_set_presence ()
void	(*tp_cli_connection_interface_presence1_callback_for_set_presence) ()
TpProxySignalConnection *	tp_cli_connection_interface_presence1_connect_to_presences_changed ()
void	(*tp_cli_connection_interface_presence1_signal_callback_presences_changed) ()

Object Hierarchy

Includes

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

Description

Most instant messaging protocols allow users to advertise their presence status. In Telepathy, this is represented by the Presence interface, which lets applications advertise the presence status of the local user, and query the presence status of their contacts.

This section documents the auto-generated C wrappers for the Presence interface, used with TpConnection objects.

Functions

tp_cli_connection_interface_presence1_call_set_presence ()

TpProxyPendingCall *
tp_cli_connection_interface_presence1_call_set_presence
                               (TpConnection *proxy,
                                gint timeout_ms,
                                const gchar *in_Status,
                                const gchar *in_Status_Message,
                                tp_cli_connection_interface_presence1_callback_for_set_presence callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object);

Start a SetPresence method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> Request that the presence status and status message are published for the connection. Changes will be indicated by <tp:member-ref>PresencesChanged</tp:member-ref> signals being emitted. This method may be called on a newly-created connection while it is still in the DISCONNECTED state, to request that when the connection connects, it will do so with the selected status. In DISCONNECTED state the <tp:member-ref>Statuses</tp:member-ref> property will indicate which statuses are allowed to be set while DISCONNECTED (none, if the Connection Manager doesn't allow this). This value MUST NOT be cached, as the set of allowed presences might change upon connecting.

Parameters

proxy	the TpProxy
timeout_ms	the timeout in milliseconds, or -1 to use the default
in_Status	Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The string identifier of the desired status. Possible status identifiers are defined in the <tp:member-ref>Statuses</tp:member-ref> property.</p> <p>Clients MUST NOT set a status whose string value they do not recognise, even if its presence type in Statuses matches what the user requested.</p> <tp:rationale> <p>Suppose a protocol has statuses that include 'phone' (of type BUSY) and 'in-a-meeting' (of type BUSY), but there is no generic 'busy' status.</p> <p>If the user requests "Busy" status from a menu, a client author might be tempted to pick an arbitrary status that has type BUSY. However, on this protocol, neither of the choices would be appropriate, and incorrect information about the user would be conveyed.</p> </tp:rationale> <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type> is Offline, Error or Unknown MUST NOT be passed to this function. Connection managers SHOULD reject these statuses.</p> <tp:rationale> <p>To go offline, call <tp:dbus-ref namespace="im.telepathy.v1.Connection">Disconnect</tp:dbus-ref> instead. The "error" and "unknown" statuses make no sense.</p> </tp:rationale>
in_Status_Message	Used to pass an 'in' argument: The status message associated with the current status.
callback	called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
user_data	user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
destroy	called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
weak_object	If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`

Returns

a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_connection_interface_presence1_callback_for_set_presence ()

void
(*tp_cli_connection_interface_presence1_callback_for_set_presence)
                               (TpConnection *proxy,
                                const GError *error,
                                gpointer user_data,
                                GObject *weak_object);

Signature of the callback called when a SetPresence method call succeeds or fails.

Parameters

proxy	the proxy on which the call was made
error	`NULL` on success, or an error on failure
user_data	user-supplied data
weak_object	user-supplied object

tp_cli_connection_interface_presence1_connect_to_presences_changed ()

TpProxySignalConnection *
tp_cli_connection_interface_presence1_connect_to_presences_changed
                               (TpConnection *proxy,
                                tp_cli_connection_interface_presence1_signal_callback_presences_changed callback,
                                gpointer user_data,
                                GDestroyNotify destroy,
                                GObject *weak_object,
                                GError **error);

Connect a handler to the signal PresencesChanged.

This signal should be emitted when your own presence has been changed, or the presence of the member of any of the connection's channels has been changed.

Parameters

proxy	A TpConnection or subclass
callback	Callback to be called when the signal is received
user_data	User-supplied data for the callback
destroy	Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns `NULL`
weak_object	A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
error	If not `NULL`, used to raise an error if `NULL` is returned

Returns

a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_connection_interface_presence1_signal_callback_presences_changed ()

void
(*tp_cli_connection_interface_presence1_signal_callback_presences_changed)
                               (TpConnection *proxy,
                                GHashTable *arg_Presence,
                                gpointer user_data,
                                GObject *weak_object);

Represents the signature of a callback for the signal PresencesChanged.

Parameters

proxy	The proxy on which `tp_cli_connection_interface_presence1_connect_to_presences_changed()` was called
arg_Presence	A dictionary of contact handles mapped to the status, presence type and status message.
user_data	User-supplied data
weak_object	User-supplied weakly referenced object

Connection Presence interface

Functions

Object Hierarchy

Includes

Description

Functions

tp_cli_connection_interface_presence1_call_set_presence ()

Parameters

Returns

tp_cli_connection_interface_presence1_callback_for_set_presence ()

Parameters

tp_cli_connection_interface_presence1_connect_to_presences_changed ()

Parameters

Returns

tp_cli_connection_interface_presence1_signal_callback_presences_changed ()

Parameters

Types and Values

See Also