Connection SimplePresence interface

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

Synopsis

#include <telepathy-glib/connection.h>

gboolean            tp_cli_connection_interface_simple_presence_run_get_presences
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const GArray *in_Contacts,
                                                         GHashTable **out_Presence,
                                                         GError **error,
                                                         GMainLoop **loop);
gboolean            tp_cli_connection_interface_simple_presence_run_set_presence
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Status,
                                                         const gchar *in_Status_Message,
                                                         GError **error,
                                                         GMainLoop **loop);
TpProxyPendingCall * tp_cli_connection_interface_simple_presence_call_get_presences
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const GArray *in_Contacts,
                                                         tp_cli_connection_interface_simple_presence_callback_for_get_presences callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_interface_simple_presence_call_set_presence
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Status,
                                                         const gchar *in_Status_Message,
                                                         tp_cli_connection_interface_simple_presence_callback_for_set_presence callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_connection_interface_simple_presence_callback_for_get_presences)
                                                        (TpConnection *proxy,
                                                         GHashTable *out_Presence,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_connection_interface_simple_presence_callback_for_set_presence)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_connection_interface_simple_presence_connect_to_presences_changed
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_interface_simple_presence_signal_callback_presences_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_connection_interface_simple_presence_signal_callback_presences_changed)
                                                        (TpConnection *proxy,
                                                         GHashTable *arg_Presence,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Description

Most instant messaging protocols allow users to advertise their presence status. In Telepathy, this is represented by the SimplePresence 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 SimplePresence interface, used with TpConnection objects.

Details

tp_cli_connection_interface_simple_presence_run_get_presences ()

gboolean            tp_cli_connection_interface_simple_presence_run_get_presences
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const GArray *in_Contacts,
                                                         GHashTable **out_Presence,
                                                         GError **error,
                                                         GMainLoop **loop);

Call the method GetPresences and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Get presence previously emitted by <tp:member-ref>PresencesChanged</tp:member-ref> for the given contacts. Data is returned in the same structure as the PresencesChanged signal; no additional network requests are made.

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for default

in_Contacts :

Used to pass an 'in' argument: An array of the contacts whose presence should be obtained.

out_Presence :

Used to return an 'out' argument if TRUE is returned: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Presence information in the same format as for the <tp:member-ref>PresencesChanged</tp:member-ref> signal. The returned mapping MUST include an entry for each contact in the method's argument.</p> <p>The definition of the connection presence types Unknown and Offline means that if a connection manager will return Unknown for contacts not on the subscribe list, it MUST delay the reply to this method call until it has found out which contacts are, in fact, on the subscribe list.</p>

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_interface_simple_presence_run_set_presence ()

gboolean            tp_cli_connection_interface_simple_presence_run_set_presence
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Status,
                                                         const gchar *in_Status_Message,
                                                         GError **error,
                                                         GMainLoop **loop);

Call the method SetPresence and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>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.</p> <p>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.</p> <p>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.</p>

proxy :

A TpConnection or subclass

timeout_ms :

Timeout in milliseconds, or -1 for 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 &quot;Busy&quot; 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="org.freedesktop.Telepathy.Connection">Disconnect</tp:dbus-ref> instead. The &quot;error&quot; and &quot;unknown&quot; statuses make no sense.</p> </tp:rationale>

in_Status_Message :

Used to pass an 'in' argument: The status message associated with the current status.

error :

If not NULL, used to return errors if FALSE is returned

loop :

If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

TRUE on success, FALSE and sets error on error

tp_cli_connection_interface_simple_presence_call_get_presences ()

TpProxyPendingCall * tp_cli_connection_interface_simple_presence_call_get_presences
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const GArray *in_Contacts,
                                                         tp_cli_connection_interface_simple_presence_callback_for_get_presences callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a GetPresences method call.

Get presence previously emitted by <tp:member-ref>PresencesChanged</tp:member-ref> for the given contacts. Data is returned in the same structure as the PresencesChanged signal; no additional network requests are made.

proxy :

the TpProxy

timeout_ms :

the timeout in milliseconds, or -1 to use the default

in_Contacts :

Used to pass an 'in' argument: An array of the contacts whose presence should be obtained.

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

TpProxyPendingCall * tp_cli_connection_interface_simple_presence_call_set_presence
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Status,
                                                         const gchar *in_Status_Message,
                                                         tp_cli_connection_interface_simple_presence_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"> <p>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.</p> <p>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.</p> <p>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.</p>

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 &quot;Busy&quot; 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="org.freedesktop.Telepathy.Connection">Disconnect</tp:dbus-ref> instead. The &quot;error&quot; and &quot;unknown&quot; 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_simple_presence_callback_for_get_presences ()

void                (*tp_cli_connection_interface_simple_presence_callback_for_get_presences)
                                                        (TpConnection *proxy,
                                                         GHashTable *out_Presence,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

proxy :

the proxy on which the call was made

out_Presence :

Used to return an 'out' argument if error is NULL: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Presence information in the same format as for the <tp:member-ref>PresencesChanged</tp:member-ref> signal. The returned mapping MUST include an entry for each contact in the method's argument.</p> <p>The definition of the connection presence types Unknown and Offline means that if a connection manager will return Unknown for contacts not on the subscribe list, it MUST delay the reply to this method call until it has found out which contacts are, in fact, on the subscribe list.</p>

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_interface_simple_presence_callback_for_set_presence ()

void                (*tp_cli_connection_interface_simple_presence_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.

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

TpProxySignalConnection * tp_cli_connection_interface_simple_presence_connect_to_presences_changed
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_interface_simple_presence_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.

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

void                (*tp_cli_connection_interface_simple_presence_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.

proxy :

The proxy on which tp_cli_connection_interface_simple_presence_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

See Also

TpConnection