Connection Aliasing interface

## Connection Aliasing interface Connection Aliasing interface — client-side wrappers for the Aliasing interface |

## Synopsis

    #include <telepathy-glib/connection.h>

    gboolean            tp_cli_connection_interface_aliasing_run_get_alias_flags
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint *out0,
                                                             GError **error,
                                                             GMainLoop **loop);
    gboolean            tp_cli_connection_interface_aliasing_run_request_aliases
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const GArray *in_contacts,
                                                             gchar ***out0,
                                                             GError **error,
                                                             GMainLoop **loop);
    gboolean            tp_cli_connection_interface_aliasing_run_set_aliases
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             GHashTable *in_aliases,
                                                             GError **error,
                                                             GMainLoop **loop);
    TpProxyPendingCall* tp_cli_connection_interface_aliasing_call_get_alias_flags
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_connection_interface_aliasing_callback_for_get_alias_flags callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_interface_aliasing_call_request_aliases
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const GArray *in_contacts,
                                                             tp_cli_connection_interface_aliasing_callback_for_request_aliases callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_interface_aliasing_call_set_aliases
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             GHashTable *in_aliases,
                                                             tp_cli_connection_interface_aliasing_callback_for_set_aliases callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    void                (*tp_cli_connection_interface_aliasing_callback_for_get_alias_flags)
                                                            (TpConnection *proxy,
                                                             guint out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                (*tp_cli_connection_interface_aliasing_callback_for_request_aliases)
                                                            (TpConnection *proxy,
                                                             const gchar **out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                (*tp_cli_connection_interface_aliasing_callback_for_set_aliases)
                                                            (TpConnection *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxySignalConnection* tp_cli_connection_interface_aliasing_connect_to_aliases_changed
                                                            (TpConnection *proxy,
                                                             tp_cli_connection_interface_aliasing_signal_callback_aliases_changed callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);
    void                (*tp_cli_connection_interface_aliasing_signal_callback_aliases_changed)
                                                            (TpConnection *proxy,
                                                             const GPtrArray *arg_aliases,
                                                             gpointer user_data,
                                                             GObject *weak_object);

## Description

Most instant messaging protocols allow users to set a nickname or alias. This section documents the auto-generated C wrappers for the Aliasing interface, used with TpConnection objects.

## Details

### tp_cli_connection_interface_aliasing_run_get_alias_flags ()

    gboolean            tp_cli_connection_interface_aliasing_run_get_alias_flags
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint *out0,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method GetAliasFlags 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.

Return a bitwise OR of flags detailing the behaviour of aliases on this connection.

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`out0` : | Used to return an 'out' argument if `TRUE` is returned: An integer with a bitwise OR of flags from ConnectionAliasFlags
`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_aliasing_run_request_aliases ()

    gboolean            tp_cli_connection_interface_aliasing_run_request_aliases
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const GArray *in_contacts,
                                                             gchar ***out0,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method RequestAliases 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 value of several contacts' aliases at once.

`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 handles representing contacts
`out0` : | Used to return an 'out' argument if `TRUE` is returned: A list of aliases in the same order as the contact handles
`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_aliasing_run_set_aliases ()

    gboolean            tp_cli_connection_interface_aliasing_run_set_aliases
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             GHashTable *in_aliases,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method SetAliases 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 alias of the given contact be changed. Success will be indicated by emitting an AliasUpdate signal. On connections where the CONNECTION_ALIAS_FLAG_USER_SET flag is not set, this method will only ever succeed if the contact is the user's own handle (as returned by GetSelfHandle on the Connection interface).

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`in_aliases` : | Used to pass an 'in' argument: A dictionary mapping integer handles of contacts to strings of the new alias to set.
`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_aliasing_call_get_alias_flags ()

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

Start a GetAliasFlags method call.

Return a bitwise OR of flags detailing the behaviour of aliases on 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
`user_data` : | user-supplied data passed to the callback
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
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_aliasing_call_request_aliases ()

    TpProxyPendingCall* tp_cli_connection_interface_aliasing_call_request_aliases
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const GArray *in_contacts,
                                                             tp_cli_connection_interface_aliasing_callback_for_request_aliases callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a RequestAliases method call.

Request the value of several contacts' aliases at once.

`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
`user_data` : | user-supplied data passed to the callback
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
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_aliasing_call_set_aliases ()

    TpProxyPendingCall* tp_cli_connection_interface_aliasing_call_set_aliases
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             GHashTable *in_aliases,
                                                             tp_cli_connection_interface_aliasing_callback_for_set_aliases callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a SetAliases method call.

Request that the alias of the given contact be changed. Success will be indicated by emitting an AliasUpdate signal. On connections where the CONNECTION_ALIAS_FLAG_USER_SET flag is not set, this method will only ever succeed if the contact is the user's own handle (as returned by GetSelfHandle on the Connection interface).

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`in_aliases` : | Used to pass an 'in' argument: A dictionary mapping integer handles of contacts to strings of the new alias to set.
`callback` : | called when the method call succeeds or fails
`user_data` : | user-supplied data passed to the callback
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled
`weak_object` : | A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected
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_aliasing_callback_for_get_alias_flags ()

    void                (*tp_cli_connection_interface_aliasing_callback_for_get_alias_flags)
                                                            (TpConnection *proxy,
                                                             guint out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

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

`proxy` : | the proxy on which the call was made
`out0` : | Used to return an 'out' argument if `error` is `NULL`: An integer with a bitwise OR of flags from ConnectionAliasFlags
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_connection_interface_aliasing_callback_for_request_aliases ()

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

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

`proxy` : | the proxy on which the call was made
`out0` : | Used to return an 'out' argument if `error` is `NULL`: A list of aliases in the same order as the contact handles
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_connection_interface_aliasing_callback_for_set_aliases ()

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

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

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

Connect a handler to the signal AliasesChanged.

Signal emitted when a contact's alias (or that of the user) is 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_aliasing_signal_callback_aliases_changed ()

    void                (*tp_cli_connection_interface_aliasing_signal_callback_aliases_changed)
                                                            (TpConnection *proxy,
                                                             const GPtrArray *arg_aliases,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Represents the signature of a callback for the signal AliasesChanged.

`proxy` : | The proxy on which `tp_cli_connection_interface_aliasing_connect_to_aliases_changed()` was called
`arg_aliases` : | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array containing structs of: <ul> <li>the handle representing the contact</li> <li>the new alias</li> </ul>
`user_data` : | User-supplied data
`weak_object` : | User-supplied weakly referenced object

## See Also

TpConnection