Connection Avatars interface

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

Synopsis

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

TpProxyPendingCall * tp_cli_connection_interface_avatars1_call_clear_avatar
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_interface_avatars1_callback_for_clear_avatar callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_interface_avatars1_call_get_known_avatar_tokens
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const GArray *in_Contacts,
                                                         tp_cli_connection_interface_avatars1_callback_for_get_known_avatar_tokens callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_interface_avatars1_call_request_avatars
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const GArray *in_Contacts,
                                                         tp_cli_connection_interface_avatars1_callback_for_request_avatars callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_connection_interface_avatars1_call_set_avatar
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const GArray *in_Avatar,
                                                         const gchar *in_MIME_Type,
                                                         tp_cli_connection_interface_avatars1_callback_for_set_avatar callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_connection_interface_avatars1_callback_for_clear_avatar)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_connection_interface_avatars1_callback_for_get_known_avatar_tokens)
                                                        (TpConnection *proxy,
                                                         GHashTable *out_Tokens,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_connection_interface_avatars1_callback_for_request_avatars)
                                                        (TpConnection *proxy,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_connection_interface_avatars1_callback_for_set_avatar)
                                                        (TpConnection *proxy,
                                                         const gchar *out_Token,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_connection_interface_avatars1_connect_to_avatar_retrieved
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_interface_avatars1_signal_callback_avatar_retrieved callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
TpProxySignalConnection * tp_cli_connection_interface_avatars1_connect_to_avatar_updated
                                                        (TpConnection *proxy,
                                                         tp_cli_connection_interface_avatars1_signal_callback_avatar_updated callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
void                (*tp_cli_connection_interface_avatars1_signal_callback_avatar_retrieved)
                                                        (TpConnection *proxy,
                                                         guint arg_Contact,
                                                         const gchar *arg_Token,
                                                         const GArray *arg_Avatar,
                                                         const gchar *arg_Type,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_connection_interface_avatars1_signal_callback_avatar_updated)
                                                        (TpConnection *proxy,
                                                         guint arg_Contact,
                                                         const gchar *arg_New_Avatar_Token,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Description

Most instant messaging protocols allow users to set an icon or avatar. This section documents the auto-generated C wrappers for the Avatar interface, used with TpConnection objects.

Details

tp_cli_connection_interface_avatars1_call_clear_avatar ()

TpProxyPendingCall * tp_cli_connection_interface_avatars1_call_clear_avatar
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         tp_cli_connection_interface_avatars1_callback_for_clear_avatar callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a ClearAvatar method call.

Remove the avatar image for this connection.

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

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

Start a GetKnownAvatarTokens method call.

Get the unique tokens for the given contacts' avatars. These tokens can be persisted across connections, and should be used by the client to check whether the avatars have been updated. For handles other than the self handle, only tokens that are already known are returned; an empty token means the given contact has no avatar. However, a CM must always have the tokens for the self handle if one is set (even if it is set to no avatar). On protocols where the avatar does not persist between connections, a CM should omit the self handle from the returned map until an avatar is explicitly set or cleared.

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 handles representing contacts

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

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

Start a RequestAvatars method call.

Request avatars for a number of contacts. The <tp:member-ref>AvatarRetrieved</tp:member-ref> signal is emitted for each avatar retrieved. If the handles are valid but retrieving an avatar fails (for any reason, including the contact not having an avatar) the AvatarRetrieved signal is not emitted for that contact.

proxy :

the TpProxy

timeout_ms :

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

in_Contacts :

Used to pass an 'in' argument: The contacts to retrieve avatars for

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

TpProxyPendingCall * tp_cli_connection_interface_avatars1_call_set_avatar
                                                        (TpConnection *proxy,
                                                         gint timeout_ms,
                                                         const GArray *in_Avatar,
                                                         const gchar *in_MIME_Type,
                                                         tp_cli_connection_interface_avatars1_callback_for_set_avatar callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a SetAvatar method call.

Set a new avatar image for this connection. The avatar image must respect the requirements obtained by the properties on this interface.

proxy :

the TpProxy

timeout_ms :

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

in_Avatar :

Used to pass an 'in' argument: An array of bytes representing the avatar image data

in_MIME_Type :

Used to pass an 'in' argument: A string representing the image MIME type

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

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

Signature of the callback called when a ClearAvatar 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_avatars1_callback_for_get_known_avatar_tokens ()

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

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

proxy :

the proxy on which the call was made

out_Tokens :

Used to return an 'out' argument if error is NULL: A dictionary of handles mapped to avatar tokens, containing only the known avatar tokens.

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_interface_avatars1_callback_for_request_avatars ()

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

Signature of the callback called when a RequestAvatars 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_avatars1_callback_for_set_avatar ()

void                (*tp_cli_connection_interface_avatars1_callback_for_set_avatar)
                                                        (TpConnection *proxy,
                                                         const gchar *out_Token,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

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

proxy :

the proxy on which the call was made

out_Token :

Used to return an 'out' argument if error is NULL: The string token of the new avatar

error :

NULL on success, or an error on failure

user_data :

user-supplied data

weak_object :

user-supplied object

tp_cli_connection_interface_avatars1_connect_to_avatar_retrieved ()

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

Connect a handler to the signal AvatarRetrieved.

Emitted when the avatar for a contact has been retrieved.

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

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

Connect a handler to the signal AvatarUpdated.

Emitted when the avatar for a contact has been updated, or first discovered on this connection. If the token differs from the token associated with the client's cached avatar for this contact, the new avatar should be requested with <tp:member-ref>RequestAvatars</tp:member-ref>.

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

void                (*tp_cli_connection_interface_avatars1_signal_callback_avatar_retrieved)
                                                        (TpConnection *proxy,
                                                         guint arg_Contact,
                                                         const gchar *arg_Token,
                                                         const GArray *arg_Avatar,
                                                         const gchar *arg_Type,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal AvatarRetrieved.

proxy :

The proxy on which tp_cli_connection_interface_avatars1_connect_to_avatar_retrieved() was called

arg_Contact :

The contact whose avatar has been retrieved (TpContactHandle)

arg_Token :

The token corresponding to the avatar

arg_Avatar :

An array of bytes containing the image data

arg_Type :

A string containing the image MIME type (eg image/jpeg), or empty if unknown

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

tp_cli_connection_interface_avatars1_signal_callback_avatar_updated ()

void                (*tp_cli_connection_interface_avatars1_signal_callback_avatar_updated)
                                                        (TpConnection *proxy,
                                                         guint arg_Contact,
                                                         const gchar *arg_New_Avatar_Token,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal AvatarUpdated.

proxy :

The proxy on which tp_cli_connection_interface_avatars1_connect_to_avatar_updated() was called

arg_Contact :

An integer handle for the contact whose avatar has changed (TpContactHandle)

arg_New_Avatar_Token :

Unique token for their new avatar

user_data :

User-supplied data

weak_object :

User-supplied weakly referenced object

See Also

TpConnection