Top |
Connection Presence interfaceConnection Presence interface — client-side wrappers for the Presence interface |
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.
gboolean tp_cli_connection_interface_presence_run_add_status (TpConnection *proxy
,gint timeout_ms
,const gchar *in_Status
,GHashTable *in_Parameters
,GError **error
,GMainLoop **loop
);
tp_cli_connection_interface_presence_run_add_status
is deprecated and should not be used in newly-written code.
Call the method AddStatus 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.
Request that a single presence status is published for the user, along with any desired parameters. Changes will be indicated by <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted.
proxy |
A TpConnection or subclass |
|
timeout_ms |
Timeout in milliseconds, or -1 for default |
|
in_Status |
Used to pass an 'in' argument: The string identifier of the desired status |
|
in_Parameters |
Used to pass an 'in' argument: A dictionary of optional parameter names mapped to their variant-boxed values |
|
error |
If not |
|
loop |
If not |
gboolean tp_cli_connection_interface_presence_run_clear_status (TpConnection *proxy
,gint timeout_ms
,GError **error
,GMainLoop **loop
);
tp_cli_connection_interface_presence_run_clear_status
is deprecated and should not be used in newly-written code.
Call the method ClearStatus 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.
Request that all of a user's presence statuses be removed. Be aware that this request may simply result in the statuses being replaced by a default available status. Changes will be indicated by <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted.
proxy |
A TpConnection or subclass |
|
timeout_ms |
Timeout in milliseconds, or -1 for default |
|
error |
If not |
|
loop |
If not |
gboolean tp_cli_connection_interface_presence_run_get_presence (TpConnection *proxy
,gint timeout_ms
,const GArray *in_Contacts
,GHashTable **out_Presence
,GError **error
,GMainLoop **loop
);
tp_cli_connection_interface_presence_run_get_presence
is deprecated and should not be used in newly-written code.
Call the method GetPresence 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>PresenceUpdate</tp:member-ref> for the given contacts. Data is returned in the same structure as the PresenceUpdate signal. Using this method in favour of <tp:member-ref>RequestPresence</tp:member-ref> has the advantage that it will not wake up each client connected to the PresenceUpdate signal.
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 |
|
error |
If not |
|
loop |
If not |
gboolean tp_cli_connection_interface_presence_run_get_statuses (TpConnection *proxy
,gint timeout_ms
,GHashTable **out_Available_Statuses
,GError **error
,GMainLoop **loop
);
tp_cli_connection_interface_presence_run_get_statuses
is deprecated and should not be used in newly-written code.
Call the method GetStatuses 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 a dictionary of the valid presence statuses for this connection. This is only available when online because only some statuses will be available on some servers.
proxy |
A TpConnection or subclass |
|
timeout_ms |
Timeout in milliseconds, or -1 for default |
|
out_Available_Statuses |
Used to return an 'out' argument if |
|
error |
If not |
|
loop |
If not |
gboolean tp_cli_connection_interface_presence_run_remove_status (TpConnection *proxy
,gint timeout_ms
,const gchar *in_Status
,GError **error
,GMainLoop **loop
);
tp_cli_connection_interface_presence_run_remove_status
is deprecated and should not be used in newly-written code.
Call the method RemoveStatus 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.
Request that the given presence status is no longer published for the user. Changes will be indicated by <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. As with <tp:member-ref>ClearStatus</tp:member-ref>, removing a status may actually result in it being replaced by a default available status.
proxy |
A TpConnection or subclass |
|
timeout_ms |
Timeout in milliseconds, or -1 for default |
|
in_Status |
Used to pass an 'in' argument: The string identifier of the status not to publish anymore for the user |
|
error |
If not |
|
loop |
If not |
gboolean tp_cli_connection_interface_presence_run_request_presence (TpConnection *proxy
,gint timeout_ms
,const GArray *in_Contacts
,GError **error
,GMainLoop **loop
);
tp_cli_connection_interface_presence_run_request_presence
is deprecated and should not be used in newly-written code.
Call the method RequestPresence 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.
Request the presence for contacts on this connection. A <tp:member-ref>PresenceUpdate</tp:member-ref> signal will be emitted when they are received. This is not the same as subscribing to the presence of a contact, which must be done using the 'subscription' <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>, and on some protocols presence information may not be available unless a subscription exists.
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 |
|
error |
If not |
|
loop |
If not |
gboolean tp_cli_connection_interface_presence_run_set_last_activity_time (TpConnection *proxy
,gint timeout_ms
,guint in_Time
,GError **error
,GMainLoop **loop
);
tp_cli_connection_interface_presence_run_set_last_activity_time
is deprecated and should not be used in newly-written code.
Call the method SetLastActivityTime 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.
Request that the recorded last activity time for the user be updated on the server.
proxy |
A TpConnection or subclass |
|
timeout_ms |
Timeout in milliseconds, or -1 for default |
|
in_Time |
Used to pass an 'in' argument: A UNIX timestamp of the user's last activity time (in UTC) (TpUnixTimestamp) |
|
error |
If not |
|
loop |
If not |
gboolean tp_cli_connection_interface_presence_run_set_status (TpConnection *proxy
,gint timeout_ms
,GHashTable *in_Statuses
,GError **error
,GMainLoop **loop
);
tp_cli_connection_interface_presence_run_set_status
is deprecated and should not be used in newly-written code.
Call the method SetStatus 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 user's presence be changed to the given statuses and desired parameters. Changes will be reflected by <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted.</p> <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>The same rationale as for <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence.SetPresence</tp:dbus-ref> applies.</p> </tp:rationale> <p>On certain protocols, this method may be called on a newly-created connection which is still in the DISCONNECTED state, and will sign on with the requested status. If the requested status is not available after signing on, NotAvailable will be returned and the connection will remain offline, or if the protocol does not support signing on with a certain status, Disconnected will be returned.</p>
proxy |
A TpConnection or subclass |
|
timeout_ms |
Timeout in milliseconds, or -1 for default |
|
in_Statuses |
Used to pass an 'in' argument: A dictionary mapping status identifiers to dictionaries, which map optional parameter names to their variant-boxed values |
|
error |
If not |
|
loop |
If not |
TpProxyPendingCall * tp_cli_connection_interface_presence_call_add_status (TpConnection *proxy
,gint timeout_ms
,const gchar *in_Status
,GHashTable *in_Parameters
,tp_cli_connection_interface_presence_callback_for_add_status callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
);
Start a AddStatus method call.
Request that a single presence status is published for the user, along with any desired parameters. Changes will be indicated by <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted.
proxy |
the TpProxy |
|
timeout_ms |
the timeout in milliseconds, or -1 to use the default |
|
in_Status |
Used to pass an 'in' argument: The string identifier of the desired status |
|
in_Parameters |
Used to pass an 'in' argument: A dictionary of optional parameter names mapped to their variant-boxed values |
|
callback |
called when the method call succeeds or fails;
may be |
|
user_data |
user-supplied data passed to the callback;
must be |
|
destroy |
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be |
|
weak_object |
If not |
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.
TpProxyPendingCall * tp_cli_connection_interface_presence_call_clear_status (TpConnection *proxy
,gint timeout_ms
,tp_cli_connection_interface_presence_callback_for_clear_status callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
);
Start a ClearStatus method call.
Request that all of a user's presence statuses be removed. Be aware that this request may simply result in the statuses being replaced by a default available status. Changes will be indicated by <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted.
proxy |
the TpProxy |
|
timeout_ms |
the timeout in milliseconds, or -1 to use the default |
|
callback |
called when the method call succeeds or fails;
may be |
|
user_data |
user-supplied data passed to the callback;
must be |
|
destroy |
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be |
|
weak_object |
If not |
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.
TpProxyPendingCall * tp_cli_connection_interface_presence_call_get_presence (TpConnection *proxy
,gint timeout_ms
,const GArray *in_Contacts
,tp_cli_connection_interface_presence_callback_for_get_presence callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
);
Start a GetPresence method call.
Get presence previously emitted by <tp:member-ref>PresenceUpdate</tp:member-ref> for the given contacts. Data is returned in the same structure as the PresenceUpdate signal. Using this method in favour of <tp:member-ref>RequestPresence</tp:member-ref> has the advantage that it will not wake up each client connected to the PresenceUpdate signal.
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 |
|
user_data |
user-supplied data passed to the callback;
must be |
|
destroy |
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be |
|
weak_object |
If not |
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.
TpProxyPendingCall * tp_cli_connection_interface_presence_call_get_statuses (TpConnection *proxy
,gint timeout_ms
,tp_cli_connection_interface_presence_callback_for_get_statuses callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
);
Start a GetStatuses method call.
Get a dictionary of the valid presence statuses for this connection. This is only available when online because only some statuses will be available on some servers.
proxy |
the TpProxy |
|
timeout_ms |
the timeout in milliseconds, or -1 to use the default |
|
callback |
called when the method call succeeds or fails;
may be |
|
user_data |
user-supplied data passed to the callback;
must be |
|
destroy |
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be |
|
weak_object |
If not |
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.
TpProxyPendingCall * tp_cli_connection_interface_presence_call_remove_status (TpConnection *proxy
,gint timeout_ms
,const gchar *in_Status
,tp_cli_connection_interface_presence_callback_for_remove_status callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
);
Start a RemoveStatus method call.
Request that the given presence status is no longer published for the user. Changes will be indicated by <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. As with <tp:member-ref>ClearStatus</tp:member-ref>, removing a status may actually result in it being replaced by a default available status.
proxy |
the TpProxy |
|
timeout_ms |
the timeout in milliseconds, or -1 to use the default |
|
in_Status |
Used to pass an 'in' argument: The string identifier of the status not to publish anymore for the user |
|
callback |
called when the method call succeeds or fails;
may be |
|
user_data |
user-supplied data passed to the callback;
must be |
|
destroy |
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be |
|
weak_object |
If not |
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.
TpProxyPendingCall * tp_cli_connection_interface_presence_call_request_presence (TpConnection *proxy
,gint timeout_ms
,const GArray *in_Contacts
,tp_cli_connection_interface_presence_callback_for_request_presence callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
);
Start a RequestPresence method call.
Request the presence for contacts on this connection. A <tp:member-ref>PresenceUpdate</tp:member-ref> signal will be emitted when they are received. This is not the same as subscribing to the presence of a contact, which must be done using the 'subscription' <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>, and on some protocols presence information may not be available unless a subscription exists.
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 |
|
user_data |
user-supplied data passed to the callback;
must be |
|
destroy |
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be |
|
weak_object |
If not |
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.
TpProxyPendingCall * tp_cli_connection_interface_presence_call_set_last_activity_time (TpConnection *proxy
,gint timeout_ms
,guint in_Time
,tp_cli_connection_interface_presence_callback_for_set_last_activity_time callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
);
Start a SetLastActivityTime method call.
Request that the recorded last activity time for the user be updated on the server.
proxy |
the TpProxy |
|
timeout_ms |
the timeout in milliseconds, or -1 to use the default |
|
in_Time |
Used to pass an 'in' argument: A UNIX timestamp of the user's last activity time (in UTC) (TpUnixTimestamp) |
|
callback |
called when the method call succeeds or fails;
may be |
|
user_data |
user-supplied data passed to the callback;
must be |
|
destroy |
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be |
|
weak_object |
If not |
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.
TpProxyPendingCall * tp_cli_connection_interface_presence_call_set_status (TpConnection *proxy
,gint timeout_ms
,GHashTable *in_Statuses
,tp_cli_connection_interface_presence_callback_for_set_status callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
);
Start a SetStatus method call.
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request that the user's presence be changed to the given statuses and desired parameters. Changes will be reflected by <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted.</p> <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>The same rationale as for <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence.SetPresence</tp:dbus-ref> applies.</p> </tp:rationale> <p>On certain protocols, this method may be called on a newly-created connection which is still in the DISCONNECTED state, and will sign on with the requested status. If the requested status is not available after signing on, NotAvailable will be returned and the connection will remain offline, or if the protocol does not support signing on with a certain status, Disconnected will be returned.</p>
proxy |
the TpProxy |
|
timeout_ms |
the timeout in milliseconds, or -1 to use the default |
|
in_Statuses |
Used to pass an 'in' argument: A dictionary mapping status identifiers to dictionaries, which map optional parameter names to their variant-boxed values |
|
callback |
called when the method call succeeds or fails;
may be |
|
user_data |
user-supplied data passed to the callback;
must be |
|
destroy |
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be |
|
weak_object |
If not |
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.
void (*tp_cli_connection_interface_presence_callback_for_add_status) (TpConnection *proxy
,const GError *error
,gpointer user_data
,GObject *weak_object
);
Signature of the callback called when a AddStatus method call succeeds or fails.
void (*tp_cli_connection_interface_presence_callback_for_clear_status) (TpConnection *proxy
,const GError *error
,gpointer user_data
,GObject *weak_object
);
Signature of the callback called when a ClearStatus method call succeeds or fails.
void (*tp_cli_connection_interface_presence_callback_for_get_presence) (TpConnection *proxy
,GHashTable *out_Presence
,const GError *error
,gpointer user_data
,GObject *weak_object
);
Signature of the callback called when a GetPresence method call succeeds or fails.
proxy |
the proxy on which the call was made |
|
out_Presence |
Used to return an 'out' argument if |
|
error |
|
|
user_data |
user-supplied data |
|
weak_object |
user-supplied object |
void (*tp_cli_connection_interface_presence_callback_for_get_statuses) (TpConnection *proxy
,GHashTable *out_Available_Statuses
,const GError *error
,gpointer user_data
,GObject *weak_object
);
Signature of the callback called when a GetStatuses method call succeeds or fails.
proxy |
the proxy on which the call was made |
|
out_Available_Statuses |
Used to return an 'out' argument if |
|
error |
|
|
user_data |
user-supplied data |
|
weak_object |
user-supplied object |
void (*tp_cli_connection_interface_presence_callback_for_remove_status) (TpConnection *proxy
,const GError *error
,gpointer user_data
,GObject *weak_object
);
Signature of the callback called when a RemoveStatus method call succeeds or fails.
void (*tp_cli_connection_interface_presence_callback_for_request_presence) (TpConnection *proxy
,const GError *error
,gpointer user_data
,GObject *weak_object
);
Signature of the callback called when a RequestPresence method call succeeds or fails.
void (*tp_cli_connection_interface_presence_callback_for_set_last_activity_time) (TpConnection *proxy
,const GError *error
,gpointer user_data
,GObject *weak_object
);
Signature of the callback called when a SetLastActivityTime method call succeeds or fails.
void (*tp_cli_connection_interface_presence_callback_for_set_status) (TpConnection *proxy
,const GError *error
,gpointer user_data
,GObject *weak_object
);
Signature of the callback called when a SetStatus method call succeeds or fails.
TpProxySignalConnection * tp_cli_connection_interface_presence_connect_to_presence_update (TpConnection *proxy
,tp_cli_connection_interface_presence_signal_callback_presence_update callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
,GError **error
);
Connect a handler to the signal PresenceUpdate.
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, or when the presence requested by <tp:member-ref>RequestPresence</tp:member-ref> is available.
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 |
|
weak_object |
A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected |
|
error |
If not |
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.
void (*tp_cli_connection_interface_presence_signal_callback_presence_update) (TpConnection *proxy
,GHashTable *arg_Presence
,gpointer user_data
,GObject *weak_object
);
Represents the signature of a callback for the signal PresenceUpdate.
proxy |
The proxy on which |
|
arg_Presence |
A dictionary of contact handles mapped to a struct containing a UNIX timestamp of the last activity time (in UTC), and a dictionary mapping the contact's current status identifiers to a dictionary of optional parameter names mapped to their variant-boxed values |
|
user_data |
User-supplied data |
|
weak_object |
User-supplied weakly referenced object |