TpConnection

## TpConnection TpConnection — proxy object for a Telepathy connection |

## Synopsis

    #include <telepathy-glib/connection.h>

    void                (*TpConnectionNameListCb)           (const gchar * const *names,
                                                             gsize n,
                                                             const gchar * const *cms,
                                                             const gchar * const *protocols,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                tp_list_connection_names            (TpDBusDaemon *bus_daemon,
                                                             TpConnectionNameListCb callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    TpConnection*       tp_connection_new                   (TpDBusDaemon *dbus,
                                                             const gchar *bus_name,
                                                             const gchar *object_path,
                                                             GError **error);
    gboolean            tp_connection_run_until_ready       (TpConnection *self,
                                                             gboolean connect,
                                                             GError **error,
                                                             GMainLoop **loop);
                        TpConnection;
                        TpConnectionClass;
    #define             TP_UNKNOWN_CONNECTION_STATUS
    #define             TP_ERRORS_DISCONNECTED

    void                (*tp_cli_connection_callback_for_connect)
                                                            (TpConnection *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_call_connect      (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_connection_callback_for_connect callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    gboolean            tp_cli_connection_run_connect       (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_disconnect)
                                                            (TpConnection *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_call_disconnect   (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_connection_callback_for_disconnect callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    gboolean            tp_cli_connection_run_disconnect    (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_get_interfaces)
                                                            (TpConnection *proxy,
                                                             const gchar **out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_call_get_interfaces
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_connection_callback_for_get_interfaces callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    gboolean            tp_cli_connection_run_get_interfaces
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             gchar ***out0,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_get_protocol)
                                                            (TpConnection *proxy,
                                                             const gchar *out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_call_get_protocol (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_connection_callback_for_get_protocol callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    gboolean            tp_cli_connection_run_get_protocol  (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             gchar **out0,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_get_self_handle)
                                                            (TpConnection *proxy,
                                                             guint out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_call_get_self_handle
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_connection_callback_for_get_self_handle callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    gboolean            tp_cli_connection_run_get_self_handle
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint *out0,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_get_status)
                                                            (TpConnection *proxy,
                                                             guint out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_call_get_status   (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_connection_callback_for_get_status callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    gboolean            tp_cli_connection_run_get_status    (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint *out0,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_hold_handles)
                                                            (TpConnection *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_call_hold_handles (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const GArray *in_handles,
                                                             tp_cli_connection_callback_for_hold_handles callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    gboolean            tp_cli_connection_run_hold_handles  (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const GArray *in_handles,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_inspect_handles)
                                                            (TpConnection *proxy,
                                                             const gchar **out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_call_inspect_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const GArray *in_handles,
                                                             tp_cli_connection_callback_for_inspect_handles callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    gboolean            tp_cli_connection_run_inspect_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const GArray *in_handles,
                                                             gchar ***out0,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_list_channels)
                                                            (TpConnection *proxy,
                                                             const GPtrArray *out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_call_list_channels
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             tp_cli_connection_callback_for_list_channels callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    gboolean            tp_cli_connection_run_list_channels (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             GPtrArray **out0,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_release_handles)
                                                            (TpConnection *proxy,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_call_release_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const GArray *in_handles,
                                                             tp_cli_connection_callback_for_release_handles callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    gboolean            tp_cli_connection_run_release_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const GArray *in_handles,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_request_channel)
                                                            (TpConnection *proxy,
                                                             const gchar *out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_call_request_channel
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_type,
                                                             guint in_handle_type,
                                                             guint in_handle,
                                                             gboolean in_suppress_handler,
                                                             tp_cli_connection_callback_for_request_channel callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    gboolean            tp_cli_connection_run_request_channel
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_type,
                                                             guint in_handle_type,
                                                             guint in_handle,
                                                             gboolean in_suppress_handler,
                                                             gchar **out0,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_request_handles)
                                                            (TpConnection *proxy,
                                                             const GArray *out0,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxyPendingCall* tp_cli_connection_call_request_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const gchar **in_names,
                                                             tp_cli_connection_callback_for_request_handles callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    gboolean            tp_cli_connection_run_request_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const gchar **in_names,
                                                             GArray **out0,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_signal_callback_new_channel)
                                                            (TpConnection *proxy,
                                                             const gchar *arg_object_path,
                                                             const gchar *arg_channel_type,
                                                             guint arg_handle_type,
                                                             guint arg_handle,
                                                             gboolean arg_suppress_handler,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxySignalConnection* tp_cli_connection_connect_to_new_channel
                                                            (TpConnection *proxy,
                                                             tp_cli_connection_signal_callback_new_channel callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);
    void                (*tp_cli_connection_signal_callback_status_changed)
                                                            (TpConnection *proxy,
                                                             guint arg_status,
                                                             guint arg_reason,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxySignalConnection* tp_cli_connection_connect_to_status_changed
                                                            (TpConnection *proxy,
                                                             tp_cli_connection_signal_callback_status_changed callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----TpProxy
             +----TpConnection

## Properties

      "connection-ready"         gboolean              : Read
      "status"                   guint                 : Read
      "status-reason"            guint                 : Read

## Description

TpConnection objects represent Telepathy instant messaging connections accessed via D-Bus.

Compared with a simple proxy for method calls, they add the following features:

* connection status tracking

* calling `GetInterfaces()` automatically

## Details

### TpConnectionNameListCb ()

    void                (*TpConnectionNameListCb)           (const gchar * const *names,
                                                             gsize n,
                                                             const gchar * const *cms,
                                                             const gchar * const *protocols,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Signature of the callback supplied to `tp_list_connection_managers()`.

`names` : | `NULL`-terminated array of connection bus names, or `NULL` on error
`n` : | number of names (not including the final `NULL`), or 0 on error
`cms` : | `NULL`-terminated array of connection manager names in the same order as `names`, or `NULL` on error
`protocols` : | `NULL`-terminated array of protocol names in the same order as `names`, or `NULL` on error
`error` : | `NULL` on success, or an error that occurred
`user_data` : | user-supplied data
`weak_object` : | user-supplied weakly referenced object

Since 0.7.1

### tp_list_connection_names ()

    void                tp_list_connection_names            (TpDBusDaemon *bus_daemon,
                                                             TpConnectionNameListCb callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

List the available (running or installed) connection managers. Call the callback when done.

`bus_daemon` : | proxy for the D-Bus daemon
`callback` : | callback to be called when listing the connections succeeds or fails; not called if the D-Bus connection fails completely or if the `weak_object` goes away
`user_data` : | user-supplied data for the callback
`destroy` : | callback to destroy the user-supplied data, called after `callback`, but also if the D-Bus connection fails or if the `weak_object` goes away
`weak_object` : | if not `NULL`, will be weakly referenced; the callback will not be called, and the call will be cancelled, if the object has vanished

Since 0.7.1

### tp_connection_new ()

    TpConnection*       tp_connection_new                   (TpDBusDaemon *dbus,
                                                             const gchar *bus_name,
                                                             const gchar *object_path,
                                                             GError **error);

`dbus` : | a D-Bus daemon; may not be `NULL`
`bus_name` : | the well-known or unique name of the connection process; if well-known, this function will make a blocking call to the bus daemon to resolve the unique name. May be `NULL` if `object_path` is not, in which case a well-known name will be derived from `object_path`.
`object_path` : | the object path of the connection process. May be `NULL` if `bus_name` is a well-known name, in which case the object path will be derived from `bus_name`.
`error` : | used to indicate the error if `NULL` is returned
Returns : | a new connection proxy, or `NULL` if unique-name resolution fails or on invalid arguments

Since 0.7.1

### tp_connection_run_until_ready ()

    gboolean            tp_connection_run_until_ready       (TpConnection *self,
                                                             gboolean connect,
                                                             GError **error,
                                                             GMainLoop **loop);

If `self` is connected and ready for use, return immediately. Otherwise, call `Connect()` (unless `connect` is `FALSE`) and re-enter the main loop until the connection becomes invalid, the connection connects successfully and is introspected, or the main loop stored via `loop` is cancelled.

`self` : | a connection
`connect` : | if `TRUE`, call `Connect()` if it appears to be necessary; if `FALSE`, rely on `Connect()` to be called by another client
`error` : | if not `NULL` and `FALSE` is returned, used to raise an error
`loop` : | if not `NULL`, a GMainLoop is placed here while it is being run (so calling code can call `g_main_loop_quit()` to abort), and `NULL` is placed here after the loop has been run
Returns : | `TRUE` if the connection is now connected and ready for use, `FALSE` if the connection has become invalid.

Since 0.7.1

### TpConnection

    typedef struct _TpConnection TpConnection;

A proxy object for a Telepathy connection.

Since 0.7.1

### TpConnectionClass

    typedef struct _TpConnectionClass TpConnectionClass;

The class of a TpConnection.

Since 0.7.1

### TP_UNKNOWN_CONNECTION_STATUS

    #define TP_UNKNOWN_CONNECTION_STATUS ((TpConnectionStatus) -1)

An invalid connection status used in TpConnection to indicate that the status has not yet been discovered.

Since 0.7.1

### TP_ERRORS_DISCONNECTED

    #define TP_ERRORS_DISCONNECTED (tp_errors_disconnected_quark ())

GError domain representing a Telepathy connection becoming disconnected. The `code` in a GError with this domain must be a member of TpConnectionStatusReason.

This macro expands to a function call returning a GQuark.

Since 0.7.1

### tp_cli_connection_callback_for_connect ()

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

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

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

Start a Connect method call.

Request that the connection be established. This will be done asynchronously and errors will be returned by emitting StatusChanged signals.

`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_run_connect ()

    gboolean            tp_cli_connection_run_connect       (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method Connect 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 connection be established. This will be done asynchronously and errors will be returned by emitting StatusChanged signals.

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`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_callback_for_disconnect ()

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

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

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

Start a Disconnect method call.

Request that the connection be closed. This closes the connection if it's not already in DISCONNECTED state, and destroys the connection object.

`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_run_disconnect ()

    gboolean            tp_cli_connection_run_disconnect    (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method Disconnect 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 connection be closed. This closes the connection if it's not already in DISCONNECTED state, and destroys the connection object.

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`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_callback_for_get_interfaces ()

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

Signature of the callback called when a GetInterfaces 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 array of D-Bus interface names
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_connection_call_get_interfaces ()

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

Start a GetInterfaces method call.

Get the optional interfaces supported by 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_run_get_interfaces ()

    gboolean            tp_cli_connection_run_get_interfaces
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             gchar ***out0,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method GetInterfaces 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 the optional interfaces supported by 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 array of D-Bus interface names
`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_callback_for_get_protocol ()

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

Signature of the callback called when a GetProtocol 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 string identifier for the protocol
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_connection_call_get_protocol ()

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

Start a GetProtocol method call.

Get the protocol this connection is using.

`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_run_get_protocol ()

    gboolean            tp_cli_connection_run_get_protocol  (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             gchar **out0,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method GetProtocol 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 the protocol this connection is using.

`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: A string identifier for the protocol
`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_callback_for_get_self_handle ()

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

Signature of the callback called when a GetSelfHandle 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 handle representing the user
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_connection_call_get_self_handle ()

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

Start a GetSelfHandle method call.

Get the handle which represents the user on this connection, which will remain valid for the lifetime of this connection, or until a change in the user's identifier is signalled by the Renamed signal on the Renaming interface (if present). This is always a CONTACT type handle.

`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_run_get_self_handle ()

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

Call the method GetSelfHandle 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 the handle which represents the user on this connection, which will remain valid for the lifetime of this connection, or until a change in the user's identifier is signalled by the Renamed signal on the Renaming interface (if present). This is always a CONTACT type handle.

`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 handle representing the user
`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_callback_for_get_status ()

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

Signature of the callback called when a GetStatus 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 representing the current status
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_connection_call_get_status ()

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

Start a GetStatus method call.

Get the current status as defined in the StatusChanged signal.

`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_run_get_status ()

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

Call the method GetStatus 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 the current status as defined in the StatusChanged signal.

`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 representing 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_callback_for_hold_handles ()

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

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

    TpProxyPendingCall* tp_cli_connection_call_hold_handles (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const GArray *in_handles,
                                                             tp_cli_connection_callback_for_hold_handles callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a HoldHandles method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Notify the connection manger that your client is holding a copy of handles which may not be in use in any existing channel or list, and were not obtained by using the RequestHandles method. For example, a handle observed in an emitted signal, or displayed somewhere in the UI that is not associated with a channel. The connection manager must not deallocate a handle where any clients have used this method to indicate it is in use until the ReleaseHandle method is called, or the clients disappear from the bus.</p> <p>Note that HoldHandles is idempotent - calling it multiple times is equivalent to calling it once. If a handle is &quot;referenced&quot; by several components which share a D-Bus unique name, the client should perform reference counting internally, and only call ReleaseHandles when none of the cooperating components need the handle any longer.</p>

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`in_handle_type` : | Used to pass an 'in' argument: The type of handle to be held
`in_handles` : | Used to pass an 'in' argument: A array of integer handles to hold
`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_run_hold_handles ()

    gboolean            tp_cli_connection_run_hold_handles  (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const GArray *in_handles,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method HoldHandles 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>Notify the connection manger that your client is holding a copy of handles which may not be in use in any existing channel or list, and were not obtained by using the RequestHandles method. For example, a handle observed in an emitted signal, or displayed somewhere in the UI that is not associated with a channel. The connection manager must not deallocate a handle where any clients have used this method to indicate it is in use until the ReleaseHandle method is called, or the clients disappear from the bus.</p> <p>Note that HoldHandles is idempotent - calling it multiple times is equivalent to calling it once. If a handle is &quot;referenced&quot; by several components which share a D-Bus unique name, the client should perform reference counting internally, and only call ReleaseHandles when none of the cooperating components need the handle any longer.</p>

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`in_handle_type` : | Used to pass an 'in' argument: The type of handle to be held
`in_handles` : | Used to pass an 'in' argument: A array of integer handles to hold
`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_callback_for_inspect_handles ()

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

Signature of the callback called when a InspectHandles 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 array of handle names in the same order as the given numbers
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_connection_call_inspect_handles ()

    TpProxyPendingCall* tp_cli_connection_call_inspect_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const GArray *in_handles,
                                                             tp_cli_connection_callback_for_inspect_handles callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a InspectHandles method call.

Return a string representation for a number of handles of a given type.

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`in_handle_type` : | Used to pass an 'in' argument: The type of handle to be inspected
`in_handles` : | Used to pass an 'in' argument: An array of integer handles of this type
`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_run_inspect_handles ()

    gboolean            tp_cli_connection_run_inspect_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const GArray *in_handles,
                                                             gchar ***out0,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method InspectHandles 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 string representation for a number of handles of a given type.

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`in_handle_type` : | Used to pass an 'in' argument: The type of handle to be inspected
`in_handles` : | Used to pass an 'in' argument: An array of integer handles of this type
`out0` : | Used to return an 'out' argument if `TRUE` is returned: An array of handle names in the same order as the given numbers
`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_callback_for_list_channels ()

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

Signature of the callback called when a ListChannels 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 array of structs representing channels.
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_connection_call_list_channels ()

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

Start a ListChannels method call.

List all the channels which currently exist 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_run_list_channels ()

    gboolean            tp_cli_connection_run_list_channels (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             GPtrArray **out0,
                                                             GError **error,
                                                             GMainLoop **loop);

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

List all the channels which currently exist 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 array of structs representing channels.
`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_callback_for_release_handles ()

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

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

    TpProxyPendingCall* tp_cli_connection_call_release_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const GArray *in_handles,
                                                             tp_cli_connection_callback_for_release_handles callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a ReleaseHandles method call.

Explicitly notify the connection manager that your client is no longer holding any references to the given handles, and that they may be deallocated if they are not held by any other clients or referenced by any existing channels. See HoldHandles for notes.

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`in_handle_type` : | Used to pass an 'in' argument: An integer handle type (as defined in RequestHandle)
`in_handles` : | Used to pass an 'in' argument: An array of integer handles being held by the client
`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_run_release_handles ()

    gboolean            tp_cli_connection_run_release_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const GArray *in_handles,
                                                             GError **error,
                                                             GMainLoop **loop);

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

Explicitly notify the connection manager that your client is no longer holding any references to the given handles, and that they may be deallocated if they are not held by any other clients or referenced by any existing channels. See HoldHandles for notes.

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`in_handle_type` : | Used to pass an 'in' argument: An integer handle type (as defined in RequestHandle)
`in_handles` : | Used to pass an 'in' argument: An array of integer handles being held by the client
`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_callback_for_request_channel ()

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

Signature of the callback called when a RequestChannel 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`: The D-Bus object path for the channel created or retrieved
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_connection_call_request_channel ()

    TpProxyPendingCall* tp_cli_connection_call_request_channel
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_type,
                                                             guint in_handle_type,
                                                             guint in_handle,
                                                             gboolean in_suppress_handler,
                                                             tp_cli_connection_callback_for_request_channel callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a RequestChannel method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request a channel satisfying the specified type and communicating with the contact, room, list etc. indicated by the given handle_type and handle. The handle_type and handle may both be zero to request the creation of a new, empty channel, which may or may not be possible, depending on the protocol and channel type.</p> <p>On success, the returned channel will always be of the requested type (i.e. implement the requested channel-type interface).</p> <p>If a new, empty channel is requested, on success the returned channel will always be an &quot;anonymous&quot; channel for which the type and handle are both zero.</p> <p>If a channel to a contact, room etc. is requested, on success, the returned channel may either be a new or existing channel to the requested entity (i.e. its `GetHandle()` returns the requested handle type and handle), or a newly created &quot;anonymous&quot; channel associated with the requested handle in some implementation-specific way.</p> <p>For example, for a contact handle, the returned channel might be &quot;anonymous&quot;, but implement the groups interface and have the requested contact already present among the members.</p> <p>If the request cannot be satisfied, an error is raised and no channel is created.</p>

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`in_type` : | Used to pass an 'in' argument: A D-Bus interface name representing base channel type
`in_handle_type` : | Used to pass an 'in' argument: An integer representing the handle type, or zero if no handle is being specified
`in_handle` : | Used to pass an 'in' argument: A nonzero integer handle representing a contact, room, list etc. according to handle_type, or zero if the handle_type is zero
`in_suppress_handler` : | Used to pass an 'in' argument: If true, the requesting client intends to take responsibility for displaying the channel to the user, so no other handler needs to be launched
`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_run_request_channel ()

    gboolean            tp_cli_connection_run_request_channel
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             const gchar *in_type,
                                                             guint in_handle_type,
                                                             guint in_handle,
                                                             gboolean in_suppress_handler,
                                                             gchar **out0,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method RequestChannel 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 a channel satisfying the specified type and communicating with the contact, room, list etc. indicated by the given handle_type and handle. The handle_type and handle may both be zero to request the creation of a new, empty channel, which may or may not be possible, depending on the protocol and channel type.</p> <p>On success, the returned channel will always be of the requested type (i.e. implement the requested channel-type interface).</p> <p>If a new, empty channel is requested, on success the returned channel will always be an &quot;anonymous&quot; channel for which the type and handle are both zero.</p> <p>If a channel to a contact, room etc. is requested, on success, the returned channel may either be a new or existing channel to the requested entity (i.e. its `GetHandle()` returns the requested handle type and handle), or a newly created &quot;anonymous&quot; channel associated with the requested handle in some implementation-specific way.</p> <p>For example, for a contact handle, the returned channel might be &quot;anonymous&quot;, but implement the groups interface and have the requested contact already present among the members.</p> <p>If the request cannot be satisfied, an error is raised and no channel is created.</p>

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`in_type` : | Used to pass an 'in' argument: A D-Bus interface name representing base channel type
`in_handle_type` : | Used to pass an 'in' argument: An integer representing the handle type, or zero if no handle is being specified
`in_handle` : | Used to pass an 'in' argument: A nonzero integer handle representing a contact, room, list etc. according to handle_type, or zero if the handle_type is zero
`in_suppress_handler` : | Used to pass an 'in' argument: If true, the requesting client intends to take responsibility for displaying the channel to the user, so no other handler needs to be launched
`out0` : | Used to return an 'out' argument if `TRUE` is returned: The D-Bus object path for the channel created or retrieved
`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_callback_for_request_handles ()

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

Signature of the callback called when a RequestHandles 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 array of integer handle numbers in the same order as the given strings
`error` : | `NULL` on success, or an error on failure
`user_data` : | user-supplied data
`weak_object` : | user-supplied object

### tp_cli_connection_call_request_handles ()

    TpProxyPendingCall* tp_cli_connection_call_request_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const gchar **in_names,
                                                             tp_cli_connection_callback_for_request_handles callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Start a RequestHandles method call.

Request several handles from the connection manager which represent a number of contacts, rooms or server-stored lists on the service. The connection manager should record that these handles are in use by the client who invokes this method, and must not deallocate the handles until the client disconnects from the bus or calls the ReleaseHandle method. Where the name refers to an entity that already has a handle in this connection manager, this handle should be returned instead. The handle number 0 must not be returned by the connection manager.

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`in_handle_type` : | Used to pass an 'in' argument: The type of handle required
`in_names` : | Used to pass an 'in' argument: An array of names of entities to request handles for
`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_run_request_handles ()

    gboolean            tp_cli_connection_run_request_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_handle_type,
                                                             const gchar **in_names,
                                                             GArray **out0,
                                                             GError **error,
                                                             GMainLoop **loop);

Call the method RequestHandles 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 several handles from the connection manager which represent a number of contacts, rooms or server-stored lists on the service. The connection manager should record that these handles are in use by the client who invokes this method, and must not deallocate the handles until the client disconnects from the bus or calls the ReleaseHandle method. Where the name refers to an entity that already has a handle in this connection manager, this handle should be returned instead. The handle number 0 must not be returned by the connection manager.

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`in_handle_type` : | Used to pass an 'in' argument: The type of handle required
`in_names` : | Used to pass an 'in' argument: An array of names of entities to request handles for
`out0` : | Used to return an 'out' argument if `TRUE` is returned: An array of integer handle numbers in the same order as the given strings
`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_signal_callback_new_channel ()

    void                (*tp_cli_connection_signal_callback_new_channel)
                                                            (TpConnection *proxy,
                                                             const gchar *arg_object_path,
                                                             const gchar *arg_channel_type,
                                                             guint arg_handle_type,
                                                             guint arg_handle,
                                                             gboolean arg_suppress_handler,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Represents the signature of a callback for the signal NewChannel.

`proxy` : | The proxy on which `tp_cli_connection_connect_to_new_channel()` was called
`arg_object_path` : | A D-Bus object path for the channel object on this service
`arg_channel_type` : | A D-Bus interface name representing the channel type
`arg_handle_type` : | An integer representing the type of handle this channel communicates with, which is zero if no handle is specified
`arg_handle` : | A handle indicating the specific contact, room or list this channel communicates with, or zero if it is an anonymous channel
`arg_suppress_handler` : | A boolean indicating that the channel was requested by a client that intends to display it to the user, so no handler needs to be launched
`user_data` : | User-supplied data
`weak_object` : | User-supplied weakly referenced object

### tp_cli_connection_connect_to_new_channel ()

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

Connect a handler to the signal NewChannel.

Emitted when a new Channel object is created, either through user request or incoming information from the service. The suppress_handler boolean indicates if the channel was requested by an existing client, or is an incoming communication and needs to have a handler launched.

`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_signal_callback_status_changed ()

    void                (*tp_cli_connection_signal_callback_status_changed)
                                                            (TpConnection *proxy,
                                                             guint arg_status,
                                                             guint arg_reason,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Represents the signature of a callback for the signal StatusChanged.

`proxy` : | The proxy on which `tp_cli_connection_connect_to_status_changed()` was called
`arg_status` : | An integer indicating the new status, as defined by ConnectionStatus
`arg_reason` : | An integer indicating the reason for the status change, as defined by ConnectionStatusReason
`user_data` : | User-supplied data
`weak_object` : | User-supplied weakly referenced object

### tp_cli_connection_connect_to_status_changed ()

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

Connect a handler to the signal StatusChanged.

Emitted when the status of the connection changes. All states and reasons have numerical values, as defined in ConnectionStatus and ConnectionStatusReason.

`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.

## Property Details

### The `"connection-ready"` property

      "connection-ready"         gboolean              : Read

Initially `FALSE`; changes to `TRUE` when the connection has gone to CONNECTED status, introspection has finished and it's ready for use.

By the time this property becomes `TRUE`, any extra interfaces will have been set up and the "interfaces" property will have been populated.

Default value: FALSE

### The `"status"` property

      "status"                   guint                 : Read

This connection's status, or TP_UNKNOWN_CONNECTION_STATUS if we don't know yet.

Default value: 4294967295

### The `"status-reason"` property

      "status-reason"            guint                 : Read

The reason why "status" changed to its current value, or TP_CONNECTION_STATUS_REASON_NONE_SPECIFIED if unknown. know yet.

Default value: 0

## See Also

TpConnectionManager, TpChannel