## 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;
                        TpConnectionClass;
    TpConnection *      tp_connection_new                   (TpDBusDaemon *dbus,
                                                             const gchar *bus_name,
                                                             const gchar *object_path,
                                                             GError **error);
    #define             TP_CONNECTION_FEATURE_CORE
    #define             TP_CONNECTION_FEATURE_CONNECTED
    #define             TP_CONNECTION_FEATURE_CAPABILITIES
    #define             TP_CONNECTION_FEATURE_AVATAR_REQUIREMENTS
    #define             TP_CONNECTION_FEATURE_CONTACT_INFO
    gboolean            tp_connection_run_until_ready       (TpConnection *self,
                                                             gboolean connect,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*TpConnectionWhenReadyCb)          (TpConnection *connection,
                                                             const GError *error,
                                                             gpointer user_data);
    void                tp_connection_call_when_ready       (TpConnection *self,
                                                             TpConnectionWhenReadyCb callback,
                                                             gpointer user_data);
    gboolean            tp_connection_is_ready              (TpConnection *self);
    TpConnectionStatus  tp_connection_get_status            (TpConnection *self,
                                                             TpConnectionStatusReason *reason);
    TpHandle            tp_connection_get_self_handle       (TpConnection *self);
    void                (*TpConnectionRequestHandlesCb)     (TpConnection *connection,
                                                             TpHandleType handle_type,
                                                             guint n_handles,
                                                             const TpHandle *handles,
                                                             const gchar * const *ids,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                tp_connection_request_handles       (TpConnection *self,
                                                             gint timeout_ms,
                                                             TpHandleType handle_type,
                                                             const gchar * const *ids,
                                                             TpConnectionRequestHandlesCb callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    void                (*TpConnectionHoldHandlesCb)        (TpConnection *connection,
                                                             TpHandleType handle_type,
                                                             guint n_handles,
                                                             const TpHandle *handles,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    void                tp_connection_get_contact_attributes
                                                            (TpConnection *self,
                                                             gint timeout_ms,
                                                             guint n_handles,
                                                             const TpHandle *handles,
                                                             const gchar * const *interfaces,
                                                             gboolean hold,
                                                             tp_cli_connection_interface_contacts_callback_for_get_contact_attributes callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    void                tp_connection_hold_handles          (TpConnection *self,
                                                             gint timeout_ms,
                                                             TpHandleType handle_type,
                                                             guint n_handles,
                                                             const TpHandle *handles,
                                                             TpConnectionHoldHandlesCb callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);
    void                tp_connection_unref_handles         (TpConnection *self,
                                                             TpHandleType handle_type,
                                                             guint n_handles,
                                                             const TpHandle *handles);
    void                tp_connection_init_known_interfaces (void);
    gint                tp_connection_presence_type_cmp_availability
                                                            (TpConnectionPresenceType p1,
                                                             TpConnectionPresenceType p2);
    gboolean            tp_connection_parse_object_path     (TpConnection *self,
                                                             gchar **protocol,
                                                             gchar **cm_name);
    TpCapabilities *    tp_connection_get_capabilities      (TpConnection *self);
    TpAvatarRequirements * tp_connection_get_avatar_requirements
                                                            (TpConnection *self);
    TpContactInfoFlags  tp_connection_get_contact_info_flags
                                                            (TpConnection *self);
    GList *             tp_connection_get_contact_info_supported_fields
                                                            (TpConnection *self);
    void                tp_connection_set_contact_info_async
                                                            (TpConnection *self,
                                                             GList *info,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_connection_set_contact_info_finish
                                                            (TpConnection *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    #define             TP_UNKNOWN_CONNECTION_STATUS
    #define             TP_ERRORS_DISCONNECTED
    const gchar *       tp_connection_get_detailed_error    (TpConnection *self,
                                                             const GHashTable **details);

    #define             TP_TYPE_AVATAR_REQUIREMENTS
                        TpAvatarRequirements;
    TpAvatarRequirements * tp_avatar_requirements_new       (GStrv supported_mime_types,
                                                             guint minimum_width,
                                                             guint minimum_height,
                                                             guint recommended_width,
                                                             guint recommended_height,
                                                             guint maximum_width,
                                                             guint maximum_height,
                                                             guint maximum_bytes);
    TpAvatarRequirements * tp_avatar_requirements_copy      (const TpAvatarRequirements *self);
    void                tp_avatar_requirements_destroy      (TpAvatarRequirements *self);

                        TpContactInfoFieldSpec;
    #define             TP_TYPE_CONTACT_INFO_FIELD_SPEC
    TpContactInfoFieldSpec * tp_contact_info_field_spec_copy
                                                            (const TpContactInfoFieldSpec *self);
    void                tp_contact_info_field_spec_free     (TpContactInfoFieldSpec *self);
    #define             TP_TYPE_CONTACT_INFO_SPEC_LIST
    GList *             tp_contact_info_spec_list_copy      (GList *list);
    void                tp_contact_info_spec_list_free      (GList *list);
                        TpContactInfoField;
    #define             TP_TYPE_CONTACT_INFO_FIELD
    TpContactInfoField * tp_contact_info_field_new          (const gchar *field_name,
                                                             GStrv parameters,
                                                             GStrv field_value);
    TpContactInfoField * tp_contact_info_field_copy         (const TpContactInfoField *self);
    void                tp_contact_info_field_free          (TpContactInfoField *self);
    #define             TP_TYPE_CONTACT_INFO_LIST
    GList *             tp_contact_info_list_copy           (GList *list);
    void                tp_contact_info_list_free           (GList *list);

    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 **out_Interfaces,
                                                             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 ***out_Interfaces,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_get_protocol)
                                                            (TpConnection *proxy,
                                                             const gchar *out_Protocol,
                                                             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 **out_Protocol,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_get_self_handle)
                                                            (TpConnection *proxy,
                                                             guint out_Self_Handle,
                                                             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 *out_Self_Handle,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_get_status)
                                                            (TpConnection *proxy,
                                                             guint out_Status,
                                                             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 *out_Status,
                                                             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 **out_Identifiers,
                                                             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 ***out_Identifiers,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_list_channels)
                                                            (TpConnection *proxy,
                                                             const GPtrArray *out_Channel_Info,
                                                             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 **out_Channel_Info,
                                                             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 *out_Object_Path,
                                                             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 **out_Object_Path,
                                                             GError **error,
                                                             GMainLoop **loop);
    void                (*tp_cli_connection_callback_for_request_handles)
                                                            (TpConnection *proxy,
                                                             const GArray *out_Handles,
                                                             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_Identifiers,
                                                             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_Identifiers,
                                                             GArray **out_Handles,
                                                             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_self_handle_changed)
                                                            (TpConnection *proxy,
                                                             guint arg_Self_Handle,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxySignalConnection * tp_cli_connection_connect_to_self_handle_changed
                                                            (TpConnection *proxy,
                                                             tp_cli_connection_signal_callback_self_handle_changed 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);
    void                (*tp_cli_connection_signal_callback_connection_error)
                                                            (TpConnection *proxy,
                                                             const gchar *arg_Error,
                                                             GHashTable *arg_Details,
                                                             gpointer user_data,
                                                             GObject *weak_object);
    TpProxySignalConnection * tp_cli_connection_connect_to_connection_error
                                                            (TpConnection *proxy,
                                                             tp_cli_connection_signal_callback_connection_error callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object,
                                                             GError **error);

## Object Hierarchy

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

## Properties

      "capabilities"             TpCapabilities*       : Read
      "connection-ready"         gboolean              : Read
      "self-handle"              guint                 : 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_names()`.

`names` : | `NULL`-terminated array of `n` connection bus names, or `NULL` on error. [array zero-terminated=1]
`n` : | number of names (not including the final `NULL`), or 0 on error
`cms` : | `NULL`-terminated array of `n` connection manager names (e.g. "gabble") in the same order as `names`, or `NULL` on error. [array zero-terminated=1]
`protocols` : | `NULL`-terminated array of `n` protocol names as defined in the Telepathy spec (e.g. "jabber") in the same order as `names`, or `NULL` on error. [array zero-terminated=1]
`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 bus names of all the connections that currently exist, together with the connection manager name and the protocol name for each connection. Call the callback when done.

The bus names passed to the callback can be used to construct TpConnection objects for any connections that are of interest.

`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 if the object has vanished. [allow-none]

Since 0.7.1

### TpConnection

    typedef struct _TpConnection TpConnection;

A proxy object for a Telepathy connection. There are no interesting public struct fields.

(Changed in 0.7.12: the layout of the structure is visible, allowing subclassing.)

Since 0.7.1

### TpConnectionClass

    typedef struct {
        TpProxyClass parent_class;
    } TpConnectionClass;

The class of a TpConnection. In addition to `parent_class` there are four pointers reserved for possible future use.

(Changed in 0.7.12: the layout of the structure is visible, allowing subclassing.)

TpProxyClass `parent_class`; | the parent class

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`. [allow-none]
`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`. [allow-none]
`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_FEATURE_CORE

    #define             TP_CONNECTION_FEATURE_CORE

Expands to a call to a function that returns a quark for the "core" feature on a TpConnection.

When this feature is prepared, the basic properties of the Connection have been retrieved and are available for use, and change-notification has been set up for those that can change.

Specifically, this implies that:

- "status" has a value other than `TP_UNKNOWN_CONNECTION_STATUS`, and "status-reason" is the reason for changing to that status
- interfaces that are always available have been added to the "interfaces" (although the set of interfaces is not guaranteed to be complete until "status" becomes `TP_CONNECTION_STATUS_CONNECTED`))

### prepared does not imply connected

Unlike the older "connection-ready" mechanism, this feature does not imply that the connection has successfully connected. It only implies that an initial status (disconnected, connecting or connected) has been discovered. `TP_CONNECTION_FEATURE_CONNECTED` is the closest equivalent of "connection-ready".

One can ask for a feature to be prepared using the `tp_proxy_prepare_async()` function, and waiting for it to callback.

Since 0.11.3

### TP_CONNECTION_FEATURE_CONNECTED

    #define             TP_CONNECTION_FEATURE_CONNECTED

Expands to a call to a function that returns a GQuark representing the "connected" feature.

When this feature is prepared, it means that the connection has become connected to the appropriate real-time communications service, and all information requested via other features has been updated accordingly. In particular, the following aspects of `TP_CONNECTION_FEATURE_CORE` will be up to date:

- "status" is `TP_CONNECTION_STATUS_CONNECTED`
- "self-handle" is valid and non-zero
- all interfaces have been added to the set of "interfaces", and that set will not change again

### Someone still has to call `Connect()`

Requesting this feature via `tp_proxy_prepare_async()` means that you want to wait for the connection to connect, but it doesn't actually start the process of connecting: to do that, call `tp_cli_connection_call_connect()` separately.

One can ask for a feature to be prepared using the `tp_proxy_prepare_async()` function, and waiting for it to callback.

Since 0.11.3

### TP_CONNECTION_FEATURE_CAPABILITIES

    #define             TP_CONNECTION_FEATURE_CAPABILITIES

Expands to a call to a function that returns a GQuark representing the "capabilities" feature.

When this feature is prepared, the Requests.RequestableChannelClasses property of the Connection has been retrieved. In particular, the `TpConnection`:capabilities property has been set.

One can ask for a feature to be prepared using the `tp_proxy_prepare_async()` function, and waiting for it to callback.

Since 0.11.3

### TP_CONNECTION_FEATURE_AVATAR_REQUIREMENTS

    #define             TP_CONNECTION_FEATURE_AVATAR_REQUIREMENTS

Expands to a call to a function that returns a GQuark representing the "avatar-requirements" feature.

When this feature is prepared, the avatar requirements of the Connection has been retrieved. Use `tp_connection_get_avatar_requirements()` to get them once prepared.

One can ask for a feature to be prepared using the `tp_proxy_prepare_async()` function, and waiting for it to callback.

Since 0.11.4

### TP_CONNECTION_FEATURE_CONTACT_INFO

    #define             TP_CONNECTION_FEATURE_CONTACT_INFO

Expands to a call to a function that returns a GQuark representing the "contact-info" feature.

When this feature is prepared, the ContactInfoFlags and SupportedFields of the Connection has been retrieved. Use `tp_connection_get_contact_info_flags()` and `tp_connection_get_contact_info_supported_fields()` to get them once prepared.

One can ask for a feature to be prepared using the `tp_proxy_prepare_async()` function, and waiting for it to callback.

Since 0.11.7

### tp_connection_run_until_ready ()

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

### Warning

`tp_connection_run_until_ready` has been deprecated since version 0.11.0 and should not be used in newly-written code. Use tp_connection_call_when_ready, or restructure your program in such a way as to avoid re-entering the main 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

### TpConnectionWhenReadyCb ()

    void                (*TpConnectionWhenReadyCb)          (TpConnection *connection,
                                                             const GError *error,
                                                             gpointer user_data);

Signature of a callback passed to `tp_connection_call_when_ready()`, which will be called exactly once, when the connection becomes ready or invalid (whichever happens first)

`connection` : | the connection (which may be in the middle of being disposed, if error is non-`NULL`, error->domain is TP_DBUS_ERRORS and error->code is TP_DBUS_ERROR_PROXY_UNREFERENCED)
`error` : | `NULL` if the connection is ready for use, or the error with which it was invalidated if it is now invalid
`user_data` : | whatever was passed to `tp_connection_call_when_ready()`

### tp_connection_call_when_ready ()

    void                tp_connection_call_when_ready       (TpConnection *self,
                                                             TpConnectionWhenReadyCb callback,
                                                             gpointer user_data);

If `self` is ready for use or has been invalidated, call `callback` immediately, then return. Otherwise, arrange for `callback` to be called when `self` either becomes ready for use or becomes invalid.

Note that if the connection is not in state CONNECTED, the callback will not be called until the connection either goes to state CONNECTED or is invalidated (e.g. by going to state DISCONNECTED or by becoming unreferenced). In particular, this method does not call `Connect()`. Call `tp_cli_connection_call_connect()` too, if you want to do that.

`self` : | a connection
`callback` : | called when the connection becomes ready or invalidated, whichever happens first
`user_data` : | arbitrary user-supplied data passed to the callback

Since 0.7.7

### tp_connection_is_ready ()

    gboolean            tp_connection_is_ready              (TpConnection *self);

Returns the same thing as the "connection-ready" property.

`self` : | a connection
Returns : | `TRUE` if introspection has completed

Since 0.7.17

### tp_connection_get_status ()

    TpConnectionStatus  tp_connection_get_status            (TpConnection *self,
                                                             TpConnectionStatusReason *reason);

If `reason` is not `NULL` it is set to the reason why "status" changed to its current value, or `TP_CONNECTION_STATUS_REASON_NONE_SPECIFIED` if unknown.

`self` : | a connection
`reason` : | a TpConnectionStatusReason, or `NULL`. [out]
Returns : | This connection's status, or `TP_UNKNOWN_CONNECTION_STATUS` if we don't know yet.

Since 0.7.14

### tp_connection_get_self_handle ()

    TpHandle            tp_connection_get_self_handle       (TpConnection *self);

Return the `TP_HANDLE_TYPE_CONTACT` handle of the local user on this connection, or 0 if the self-handle is not known yet or the connection has become invalid (the TpProxy::invalidated signal).

The returned handle is not necessarily valid forever (the notify::self-handle signal will be emitted if it changes, which can happen on protocols such as IRC). Construct a TpContact object if you want to track the local user's identifier in the protocol, or other information like their presence status, over time.

`self` : | a connection
Returns : | the value of the TpConnection:self-handle property

Since 0.7.26

### TpConnectionRequestHandlesCb ()

    void                (*TpConnectionRequestHandlesCb)     (TpConnection *connection,
                                                             TpHandleType handle_type,
                                                             guint n_handles,
                                                             const TpHandle *handles,
                                                             const gchar * const *ids,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Signature of the callback called when `tp_connection_request_handles()` succeeds or fails.

On success, the caller has one reference to each handle in `handles`, which may be released later with `tp_connection_unref_handles()`. If not released, the handles will remain valid until `connection` becomes invalid (signalled by TpProxy::invalidated).

For convenience, the handle type and IDs requested by the caller are passed through to this callback, so the caller does not have to include them in `user_data`.

`connection` : | the connection
`handle_type` : | the handle type that was passed to `tp_connection_request_handles()`
`n_handles` : | the number of IDs that were passed to `tp_connection_request_handles()` on success, or 0 on failure
`handles` : | the `n_handles` handles corresponding to `ids`, in the same order, or `NULL` on failure. [element-type uint][array length=n_handles]
`ids` : | a copy of the array of `n_handles` IDs that was passed to `tp_connection_request_handles()` on success, or `NULL` on failure. [element-type utf8][array length=n_handles]
`error` : | `NULL` on success, or an error on failure
`user_data` : | the same arbitrary pointer that was passed to `tp_connection_request_handles()`
`weak_object` : | the same object that was passed to `tp_connection_request_handles()`

### tp_connection_request_handles ()

    void                tp_connection_request_handles       (TpConnection *self,
                                                             gint timeout_ms,
                                                             TpHandleType handle_type,
                                                             const gchar * const *ids,
                                                             TpConnectionRequestHandlesCb callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Request the handles corresponding to the given identifiers, and if they are valid, hold (ensure a reference to) the corresponding handles.

If they are valid, the callback will later be called with the given handles; if not all of them are valid, the callback will be called with an error.

`self` : | a connection
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`handle_type` : | the handle type
`ids` : | an array of string identifiers for which handles are required, terminated by `NULL` (must not be `NULL` or empty). [array zero-terminated=1]
`callback` : | called on success or failure (unless `weak_object` has become unreferenced)
`user_data` : | arbitrary user-supplied data
`destroy` : | called to destroy `user_data` after calling `callback`, or when `weak_object` becomes unreferenced (whichever occurs sooner)
`weak_object` : | if not `NULL`, an object to be weakly referenced: if it is destroyed, `callback` will not be called

### TpConnectionHoldHandlesCb ()

    void                (*TpConnectionHoldHandlesCb)        (TpConnection *connection,
                                                             TpHandleType handle_type,
                                                             guint n_handles,
                                                             const TpHandle *handles,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Signature of the callback called when `tp_connection_hold_handles()` succeeds or fails.

On success, the caller has one reference to each handle in `handles`, which may be released later with `tp_connection_unref_handles()`. If not released, the handles will remain valid until `connection` becomes invalid (signalled by "invalidated").

For convenience, the handle type and handles requested by the caller are passed through to this callback on success, so the caller does not have to include them in `user_data`.

`connection` : | the connection
`handle_type` : | the handle type that was passed to `tp_connection_hold_handles()`
`n_handles` : | the number of handles that were passed to `tp_connection_hold_handles()` on success, or 0 on failure
`handles` : | a copy of the array of `n_handles` handles that was passed to `tp_connection_hold_handles()` on success, or `NULL` on failure
`error` : | `NULL` on success, or an error on failure
`user_data` : | the same arbitrary pointer that was passed to `tp_connection_hold_handles()`
`weak_object` : | the same object that was passed to `tp_connection_hold_handles()`

### tp_connection_get_contact_attributes ()

    void                tp_connection_get_contact_attributes
                                                            (TpConnection *self,
                                                             gint timeout_ms,
                                                             guint n_handles,
                                                             const TpHandle *handles,
                                                             const gchar * const *interfaces,
                                                             gboolean hold,
                                                             tp_cli_connection_interface_contacts_callback_for_get_contact_attributes callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Return (via a callback) any number of attributes of the given handles, and if they are valid and `hold` is TRUE, hold a reference to them.

This is a thin wrapper around the GetContactAttributes D-Bus method, and should be used in preference to `tp_cli_connection_interface_contacts_call_get_contact_attributes()`; mixing this function, `tp_connection_hold_handles()`, `tp_connection_unref_handles()`, and TpContact with direct use of the RequestHandles, HoldHandles and GetContactAttributes D-Bus methods is unwise, as TpConnection and TpContact perform client-side reference counting of handles. The TpContact API provides a higher-level abstraction which should usually be used instead.

`callback` will later be called with the attributes of those of the given handles that were valid. Invalid handles are simply omitted from the parameter to the callback.

If `hold` is `TRUE`, the `callback` is given one reference to each handle that appears as a key in the callback's `attributes` parameter.

`self` : | a connection
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`n_handles` : | the number of handles in `handles` (must be at least 1)
`handles` : | an array of handles. [array length=n_handles]
`interfaces` : | a GStrv of interfaces
`hold` : | if `TRUE`, the callback will hold one reference to each valid handle
`callback` : | called on success or failure (unless `weak_object` has become unreferenced). [type GObject.Callback]
`user_data` : | arbitrary user-supplied data
`destroy` : | called to destroy `user_data` after calling `callback`, or when `weak_object` becomes unreferenced (whichever occurs sooner)
`weak_object` : | if not `NULL`, an object to be weakly referenced: if it is destroyed, `callback` will not be called

### tp_connection_hold_handles ()

    void                tp_connection_hold_handles          (TpConnection *self,
                                                             gint timeout_ms,
                                                             TpHandleType handle_type,
                                                             guint n_handles,
                                                             const TpHandle *handles,
                                                             TpConnectionHoldHandlesCb callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy,
                                                             GObject *weak_object);

Hold (ensure a reference to) the given handles, if they are valid.

If they are valid, the callback will later be called with the given handles; if not all of them are valid, the callback will be called with an error.

This function, along with `tp_connection_unref_handles()`, `tp_connection_get_contact_attributes()` and TpContact, keeps a client-side reference count of handles; you should not use the RequestHandles, HoldHandles and GetContactAttributes D-Bus methods directly as well as these functions.

`self` : | a connection
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`handle_type` : | the handle type
`n_handles` : | the number of handles in `handles` (must be at least 1)
`handles` : | an array of handles. [array length=n_handles]
`callback` : | called on success or failure (unless `weak_object` has become unreferenced)
`user_data` : | arbitrary user-supplied data
`destroy` : | called to destroy `user_data` after calling `callback`, or when `weak_object` becomes unreferenced (whichever occurs sooner)
`weak_object` : | if not `NULL`, an object to be weakly referenced: if it is destroyed, `callback` will not be called

### tp_connection_unref_handles ()

    void                tp_connection_unref_handles         (TpConnection *self,
                                                             TpHandleType handle_type,
                                                             guint n_handles,
                                                             const TpHandle *handles);

Release the reference to the handles in `handles` that was obtained by calling `tp_connection_hold_handles()` or `tp_connection_request_handles()`.

This function might release any references held by calling `tp_cli_connection_call_request_handles()`, `tp_cli_connection_run_request_handles()`, `tp_cli_connection_call_hold_handles()`, `tp_cli_connection_run_hold_handles()`, `tp_cli_connection_interface_contacts_call_get_contact_attributes()` or `tp_cli_connection_interface_contacts_run_get_contact_attributes()` directly. Those functions should be avoided in favour of using TpContact, `tp_connection_hold_handles()`, `tp_connection_request_handles()` and `tp_connection_get_contact_attributes()`, which along with this function perform client-side reference counting of handles.

If `self` has already become invalid, this function does nothing.

`self` : | a connection
`handle_type` : | a handle type
`n_handles` : | the number of handles in `handles`
`handles` : | an array of `n_handles` handles. [array length=n_handles]

### tp_connection_init_known_interfaces ()

    void                tp_connection_init_known_interfaces (void);

Ensure that the known interfaces for TpConnection have been set up. This is done automatically when necessary, but for correct overriding of library interfaces by local extensions, you should call this function before calling `tp_proxy_or_subclass_hook_on_interface_add()` with first argument `TP_TYPE_CONNECTION`.

Since 0.7.6

### tp_connection_presence_type_cmp_availability ()

    gint                tp_connection_presence_type_cmp_availability
                                                            (TpConnectionPresenceType p1,
                                                             TpConnectionPresenceType p2);

Compares `p1` and `p2` like `strcmp()`. `p1` > `p2` means `p1` is more available than `p2`.

The order used is: available > busy > away > xa > hidden > offline > error > unknown > unset

`p1` : | a TpConnectionPresenceType
`p2` : | a TpConnectionPresenceType
Returns : | -1, 0 or 1, if `p1` is <, == or > than `p2`.

Since 0.7.16

### tp_connection_parse_object_path ()

    gboolean            tp_connection_parse_object_path     (TpConnection *self,
                                                             gchar **protocol,
                                                             gchar **cm_name);

If the object path of `connection` is in the correct form, set `protocol` and `cm_name`, return TRUE. Otherwise leave them unchanged and return FALSE.

`self` : | a connection
`protocol` : | If not NULL, used to return the protocol of the connection. [out][transfer full]
`cm_name` : | If not NULL, used to return the connection manager name of the connection. [out][transfer full]
Returns : | TRUE if the object path was correctly parsed, FALSE otherwise.

Since 0.7.27

### tp_connection_get_capabilities ()

    TpCapabilities *    tp_connection_get_capabilities      (TpConnection *self);

`self` : | a connection
Returns : | the same TpCapabilities as the "capabilities" property. [transfer none]

Since 0.11.3

### tp_connection_get_avatar_requirements ()

    TpAvatarRequirements * tp_connection_get_avatar_requirements
                                                            (TpConnection *self);

To wait for valid avatar requirements, call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_AVATAR_REQUIREMENTS`.

This property cannot change after `self` goes to the Connected state.

`self` : | a connection
Returns : | a TpAvatarRequirements struct, or `NULL` if the feature is not yet prepared or the connection doesn't have the necessary properties. [transfer none]

Since 0.11.4

### tp_connection_get_contact_info_flags ()

    TpContactInfoFlags  tp_connection_get_contact_info_flags
                                                            (TpConnection *self);

Returns the flags describing how contact info (vCards) behaves on this connection

To wait for valid contact info flags, call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_INFO`.

This property cannot change after `self` goes to the Connected state.

`self` : | a connection
Returns : | a set of TpContactInfoFlags

Since 0.11.7

### tp_connection_get_contact_info_supported_fields ()

    GList *             tp_connection_get_contact_info_supported_fields
                                                            (TpConnection *self);

Returns a newly allocated GList of supported contact info fields for this connection. The list must be freed with `g_list_free()` after used.

Note that the TpContactInfoFieldSpecs in the returned GList are not dupped before returning from this function. One could copy every item in the list using `tp_contact_info_field_spec_copy()`.

To wait for valid supported fields, call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_INFO`.

This property cannot change after `self` goes to the Connected state.

`self` : | a connection
Returns : | a GList of TpContactInfoFieldSpec struct, or `NULL` if the feature is not yet prepared or the connection doesn't have the necessary properties. [element-type TelepathyGLib.ContactInfoFieldSpec][transfer container TelepathyGLib.ContactInfoFieldSpec]

Since 0.11.7

### tp_connection_set_contact_info_async ()

    void                tp_connection_set_contact_info_async
                                                            (TpConnection *self,
                                                             GList *info,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Requests an asynchronous set of the contact info of `self`. When the operation is finished, `callback` will be called. You can then call `tp_connection_set_contact_info_finish()` to get the result of the operation.

This method should not be expected to succeed if the result of `tp_connection_get_contact_info_flags()` does not include `TP_CONTACT_INFO_FLAG_CAN_SET`.

`self` : | a TpConnection
`info` : | a GList of TpContactInfoField. [element-type TelepathyGLib.ContactInfoField]
`callback` : | a callback to call when the request is satisfied
`user_data` : | data to pass to `callback`

Since 0.11.7

### tp_connection_set_contact_info_finish ()

    gboolean            tp_connection_set_contact_info_finish
                                                            (TpConnection *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an async set of `self` info.

`self` : | a TpConnection
`result` : | a GAsyncResult
`error` : | a GError to be filled
Returns : | `TRUE` if the request call was successful, otherwise `FALSE`

Since 0.11.7

### 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.24, this error domain is only used if a connection manager emits a TpConnectionStatusReason not known to telepathy-glib.

Since 0.7.1

### tp_connection_get_detailed_error ()

    const gchar *       tp_connection_get_detailed_error    (TpConnection *self,
                                                             const GHashTable **details);

If the connection has disconnected, return the D-Bus error name with which it disconnected (in particular, this is `TP_ERROR_STR_CANCELLED` if it was disconnected by a user request).

Otherwise, return `NULL`, without altering `details`.

`self` : | a connection
`details` : | optionally used to return a map from string to GValue, which must not be modified or destroyed by the caller. [out][allow-none][element-type utf8 GObject.Value][transfer none utf8 GObject.Value]
Returns : | a D-Bus error name, or `NULL`. [transfer none][allow-none]

Since 0.11.4

### TP_TYPE_AVATAR_REQUIREMENTS

    #define TP_TYPE_AVATAR_REQUIREMENTS (tp_avatar_requirements_get_type ())

The boxed type of a TpAvatarRequirements.

Since 0.11.4

### TpAvatarRequirements

    typedef struct {
      GStrv supported_mime_types;
      guint minimum_width;
      guint minimum_height;
      guint recommended_width;
      guint recommended_height;
      guint maximum_width;
      guint maximum_height;
      guint maximum_bytes;
    } TpAvatarRequirements;

The requirements for setting an avatar on a particular protocol.

GStrv `supported_mime_types`; | An array of supported MIME types (e.g. "image/jpeg") Clients MAY assume that the first type in this array is preferred
guint `minimum_width`; | The minimum width in pixels of an avatar, which MAY be 0
guint `minimum_height`; | The minimum height in pixels of an avatar, which MAY be 0
guint `recommended_width`; | The recommended width in pixels of an avatar, or 0 if there is no preferred width.
guint `recommended_height`; | The recommended height in pixels of an avatar, or 0 if there is no preferred height
guint `maximum_width`; | The maximum width in pixels of an avatar on this protocol, or 0 if there is no limit.
guint `maximum_height`; | The maximum height in pixels of an avatar, or 0 if there is no limit.
guint `maximum_bytes`; | he maximum size in bytes of an avatar, or 0 if there is no limit.

Since 0.11.4

### tp_avatar_requirements_new ()

    TpAvatarRequirements * tp_avatar_requirements_new       (GStrv supported_mime_types,
                                                             guint minimum_width,
                                                             guint minimum_height,
                                                             guint recommended_width,
                                                             guint recommended_height,
                                                             guint maximum_width,
                                                             guint maximum_height,
                                                             guint maximum_bytes);

`supported_mime_types` : | An array of supported MIME types (e.g. "image/jpeg") Clients MAY assume that the first type in this array is preferred
`minimum_width` : | The minimum width in pixels of an avatar, which MAY be 0
`minimum_height` : | The minimum height in pixels of an avatar, which MAY be 0
`recommended_width` : | The recommended width in pixels of an avatar, or 0 if there is no preferred width.
`recommended_height` : | The recommended height in pixels of an avatar, or 0 if there is no preferred height
`maximum_width` : | The maximum width in pixels of an avatar on this protocol, or 0 if there is no limit.
`maximum_height` : | The maximum height in pixels of an avatar, or 0 if there is no limit.
`maximum_bytes` : | he maximum size in bytes of an avatar, or 0 if there is no limit.
Returns : | a newly allocated TpAvatarRequirements, free it with `tp_avatar_requirements_destroy()`

Since 0.11.4

### tp_avatar_requirements_copy ()

    TpAvatarRequirements * tp_avatar_requirements_copy      (const TpAvatarRequirements *self);

`self` : | a TpAvatarRequirements
Returns : | a newly allocated TpAvatarRequirements, free it with `tp_avatar_requirements_destroy()`

Since 0.11.4

### tp_avatar_requirements_destroy ()

    void                tp_avatar_requirements_destroy      (TpAvatarRequirements *self);

Free all memory used by the TpAvatarRequirements.

`self` : | a TpAvatarRequirements

Since 0.11.4

### TpContactInfoFieldSpec

    typedef struct {
      gchar *name;
      GStrv parameters;
      TpContactInfoFieldFlags flags;
      guint max;
    } TpContactInfoFieldSpec;

A struct describing a vCard field.

gchar *`name`; | The name of the field; this is the lowercased name of a vCard field. For example, a field representing a contact's address would be named "adr".
GStrv `parameters`; | The set of vCard type parameters which may be set on this field. If this list is empty and the TP_CONTACT_INFO_FIELD_FLAG_PARAMETERS_EXACT flag is not set, any vCard type parameters may be used. The type parameter names, and any values that are case-insensitive in vCard, MUST be in lower case. For example, a contact's preferred home address would have parameters 'type=home' and 'type=pref'.
TpContactInfoFieldFlags `flags`; | Flags describing the behaviour of this field.
guint `max`; | Maximum number of instances of this field which may be set. G_MAXUINT32 is used to indicate that there is no limit.

Since 0.11.7

### TP_TYPE_CONTACT_INFO_FIELD_SPEC

    #define TP_TYPE_CONTACT_INFO_FIELD_SPEC (tp_contact_info_field_spec_get_type ())

The boxed type of a TpContactInfoFieldSpec.

Since 0.11.7

### tp_contact_info_field_spec_copy ()

    TpContactInfoFieldSpec * tp_contact_info_field_spec_copy
                                                            (const TpContactInfoFieldSpec *self);

`self` : | a TpContactInfoFieldSpec
Returns : | a newly allocated TpContactInfoFieldSpec, free it with `tp_contact_info_field_spec_free()`

Since 0.11.7

### tp_contact_info_field_spec_free ()

    void                tp_contact_info_field_spec_free     (TpContactInfoFieldSpec *self);

Free all memory used by the TpContactInfoFieldSpec.

`self` : | a TpContactInfoFieldSpec

Since 0.11.7

### TP_TYPE_CONTACT_INFO_SPEC_LIST

    #define TP_TYPE_CONTACT_INFO_SPEC_LIST (tp_contact_info_spec_list_get_type ())

The boxed type of a GList of TpContactInfoFieldSpec.

Since 0.11.7

### tp_contact_info_spec_list_copy ()

    GList *             tp_contact_info_spec_list_copy      (GList *list);

`list` : | a GList of TpContactInfoFieldSpec
Returns : | a new GList of newly allocated TpContactInfoFieldSpec, free it with `tp_contact_info_spec_list_free()`

Since 0.11.7

### tp_contact_info_spec_list_free ()

    void                tp_contact_info_spec_list_free      (GList *list);

Free all memory used by the GList and its elements.

`list` : | a GList of TpContactInfoFieldSpec

Since 0.11.7

### TpContactInfoField

    typedef struct {
      gchar *field_name;
      GStrv parameters;
      GStrv field_value;
    } TpContactInfoField;

A structure representing an information about a contact. Similar to a vCard field.

gchar *`field_name`; | The name of the field; this is the lowercased name of a vCard field. For example, a field representing a contact's address would be named "adr".
GStrv `parameters`; | A list of vCard type parameters applicable to this field, with their values. The type parameter names, and any values that are case-insensitive in vCard, MUST be in lower case. For example, a contact's preferred home address would have parameters 'type=home' and 'type=pref'.
GStrv `field_value`; | For unstructured vCard fields (such as 'fn', a formatted name field), a single-element array containing the field's value. For structured fields (such as 'adr', an address field), an array corresponding to the semicolon-separated elements of the field (with empty strings for empty elements).

Since 0.11.7

### TP_TYPE_CONTACT_INFO_FIELD

    #define TP_TYPE_CONTACT_INFO_FIELD (tp_contact_info_field_get_type ())

The boxed type of a TpContactInfoField.

Since 0.11.7

### tp_contact_info_field_new ()

    TpContactInfoField * tp_contact_info_field_new          (const gchar *field_name,
                                                             GStrv parameters,
                                                             GStrv field_value);

`field_name` : | The name of the field; this is the lowercased name of a vCard field. For example, a field representing a contact's address would be named "adr".
`parameters` : | A list of vCard type parameters applicable to this field, with their values. The type parameter names, and any values that are case-insensitive in vCard, MUST be in lower case. For example, a contact's preferred home address would have parameters 'type=home' and 'type=pref'.
`field_value` : | For unstructured vCard fields (such as 'fn', a formatted name field), a single-element array containing the field's value. For structured fields (such as 'adr', an address field), an array corresponding to the semicolon-separated elements of the field (with empty strings for empty elements).
Returns : | a newly allocated TpContactInfoField, free it with `tp_contact_info_field_free()`

Since 0.11.7

### tp_contact_info_field_copy ()

    TpContactInfoField * tp_contact_info_field_copy         (const TpContactInfoField *self);

`self` : | a TpContactInfoField
Returns : | a newly allocated TpContactInfoField, free it with `tp_contact_info_field_free()`

Since 0.11.7

### tp_contact_info_field_free ()

    void                tp_contact_info_field_free          (TpContactInfoField *self);

Free all memory used by the TpContactInfoField.

`self` : | a TpContactInfoField

Since 0.11.7

### TP_TYPE_CONTACT_INFO_LIST

    #define TP_TYPE_CONTACT_INFO_LIST (tp_contact_info_list_get_type ())

The boxed type of a GList of TpContactInfoField.

Since 0.11.7

### tp_contact_info_list_copy ()

    GList *             tp_contact_info_list_copy           (GList *list);

`list` : | a GList of TpContactInfoField
Returns : | a new GList of newly allocated TpContactInfoField, free it with `tp_contact_info_list_free()`

Since 0.11.7

### tp_contact_info_list_free ()

    void                tp_contact_info_list_free           (GList *list);

Free all memory used by the GList and its elements.

`list` : | a GList of TpContactInfoField

Since 0.11.7

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

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request that the connection be established. This will be done asynchronously and errors will be returned by emitting <tp:member-ref>StatusChanged</tp:member-ref> signals.</p> <p>Calling this method on a Connection that is already connecting or connected is allowed, and has no effect.</p>

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`callback` : | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_run_connect ()

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

### Warning

`tp_cli_connection_run_connect` is deprecated and should not be used in newly-written code.

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.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request that the connection be established. This will be done asynchronously and errors will be returned by emitting <tp:member-ref>StatusChanged</tp:member-ref> signals.</p> <p>Calling this method on a Connection that is already connecting or connected is allowed, and has no effect.</p>

`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; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_run_disconnect ()

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

### Warning

`tp_cli_connection_run_disconnect` is deprecated and should not be used in newly-written code.

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 **out_Interfaces,
                                                             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
`out_Interfaces` : | Used to return an 'out' argument if `error` is `NULL`: The value of the <tp:member-ref>Interfaces</tp:member-ref> property
`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.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Returns the set of optional interfaces supported by this connection. See <tp:member-ref>Interfaces</tp:member-ref> for more details.</p>

`proxy` : | the TpProxy
`timeout_ms` : | the timeout in milliseconds, or -1 to use the default
`callback` : | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_run_get_interfaces ()

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

### Warning

`tp_cli_connection_run_get_interfaces` is deprecated and should not be used in newly-written code.

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.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Returns the set of optional interfaces supported by this connection. See <tp:member-ref>Interfaces</tp:member-ref> for more details.</p>

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`out_Interfaces` : | Used to return an 'out' argument if `TRUE` is returned: The value of the <tp:member-ref>Interfaces</tp:member-ref> property
`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 *out_Protocol,
                                                             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
`out_Protocol` : | 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; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_run_get_protocol ()

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

### Warning

`tp_cli_connection_run_get_protocol` is deprecated and should not be used in newly-written code.

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
`out_Protocol` : | 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 out_Self_Handle,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

### Warning

`tp_cli_connection_callback_for_get_self_handle` is deprecated and should not be used in newly-written code. Use GetAll to get the SelfHandle property (and all other Connection properties) instead.

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

`proxy` : | the proxy on which the call was made
`out_Self_Handle` : | Used to return an 'out' argument if `error` is `NULL`: The value of the <tp:member-ref>SelfHandle</tp:member-ref> property
`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);

### Warning

`tp_cli_connection_call_get_self_handle` is deprecated and should not be used in newly-written code. Use GetAll to get the SelfHandle property (and all other Connection properties) instead.

Start a GetSelfHandle method call.

Returns the value of the SelfHandle property. Change notification is via the SelfHandleChanged 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; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_run_get_self_handle ()

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

### Warning

`tp_cli_connection_run_get_self_handle` is deprecated and should not be used in newly-written code. Use GetAll to get the SelfHandle property (and all other Connection properties) instead.

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.

Returns the value of the SelfHandle property. Change notification is via the SelfHandleChanged signal.

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`out_Self_Handle` : | Used to return an 'out' argument if `TRUE` is returned: The value of the <tp:member-ref>SelfHandle</tp:member-ref> property
`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 out_Status,
                                                             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
`out_Status` : | Used to return an 'out' argument if `error` is `NULL`: The value of the <tp:member-ref>Status</tp:member-ref> property
`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 <tp:member-ref>StatusChanged</tp:member-ref> 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; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_run_get_status ()

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

### Warning

`tp_cli_connection_run_get_status` is deprecated and should not be used in newly-written code.

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 <tp:member-ref>StatusChanged</tp:member-ref> signal.

`proxy` : | A TpConnection or subclass
`timeout_ms` : | Timeout in milliseconds, or -1 for default
`out_Status` : | Used to return an 'out' argument if `TRUE` is returned: The value of the <tp:member-ref>Status</tp:member-ref> property
`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 <tp:member-ref>RequestHandles</tp:member-ref> 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 <tp:member-ref>ReleaseHandles</tp:member-ref> 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; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_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);

### Warning

`tp_cli_connection_run_hold_handles` is deprecated and should not be used in newly-written code.

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 <tp:member-ref>RequestHandles</tp:member-ref> 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 <tp:member-ref>ReleaseHandles</tp:member-ref> 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 **out_Identifiers,
                                                             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
`out_Identifiers` : | Used to return an 'out' argument if `error` is `NULL`: An array of identifiers corresponding to the given handles, in the same order.
`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; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_run_inspect_handles ()

    gboolean            tp_cli_connection_run_inspect_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_Handle_Type,
                                                             const GArray *in_Handles,
                                                             gchar ***out_Identifiers,
                                                             GError **error,
                                                             GMainLoop **loop);

### Warning

`tp_cli_connection_run_inspect_handles` is deprecated and should not be used in newly-written code.

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
`out_Identifiers` : | Used to return an 'out' argument if `TRUE` is returned: An array of identifiers corresponding to the given handles, in the same order.
`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 *out_Channel_Info,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

### Warning

`tp_cli_connection_callback_for_list_channels` is deprecated and should not be used in newly-written code. Use the Requests.Channels property instead.

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

`proxy` : | the proxy on which the call was made
`out_Channel_Info` : | 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);

### Warning

`tp_cli_connection_call_list_channels` is deprecated and should not be used in newly-written code. Use the Requests.Channels property instead.

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; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_run_list_channels ()

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

### Warning

`tp_cli_connection_run_list_channels` is deprecated and should not be used in newly-written code. Use the Requests.Channels property instead.

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
`out_Channel_Info` : | 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; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_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);

### Warning

`tp_cli_connection_run_release_handles` is deprecated and should not be used in newly-written code.

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 *out_Object_Path,
                                                             const GError *error,
                                                             gpointer user_data,
                                                             GObject *weak_object);

### Warning

`tp_cli_connection_callback_for_request_channel` is deprecated and should not be used in newly-written code. Use Requests.CreateChannel or Requests.EnsureChannel instead. Connection managers MAY implement RequestChannel by raising NotImplemented, or implement fewer types of channel via this API.

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

`proxy` : | the proxy on which the call was made
`out_Object_Path` : | 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);

### Warning

`tp_cli_connection_call_request_channel` is deprecated and should not be used in newly-written code. Use Requests.CreateChannel or Requests.EnsureChannel instead. Connection managers MAY implement RequestChannel by raising NotImplemented, or implement fewer types of channel via this API.

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 <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> properties are 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 Handle_Type_None if no handle is 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 Handle_Type_None
`in_Suppress_Handler` : | Used to pass an 'in' argument: <p>Clients SHOULD always set this to true.</p> <tp:rationale> <p>The historical meaning was that clients that did not intend to take responsibility for displaying the channel to the user could set this to FALSE, in which case the channel dispatcher would launch an appropriate channel handler.</p> <p>However, clients whose functionality relies on having a working channel dispatcher should obtain that functionality by calling methods on the channel dispatcher, so that they will get an appropriate error if the channel dispatcher is missing or not working.</p> <p>The channel dispatcher itself should set this to true too, so that it will ignore the <tp:member-ref>NewChannel</tp:member-ref> signal that results from the creation of the channel. It can then dispatch the channel returned from this method to an appropriate handler.</p> <p>So, there is no sensible use-case for setting this to false, and setting it to false can result in unhandled channels (in the case where clients assume that a channel dispatcher is present, but it isn't).</p> </tp:rationale>
`callback` : | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_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 **out_Object_Path,
                                                             GError **error,
                                                             GMainLoop **loop);

### Warning

`tp_cli_connection_run_request_channel` is deprecated and should not be used in newly-written code. Use Requests.CreateChannel or Requests.EnsureChannel instead. Connection managers MAY implement RequestChannel by raising NotImplemented, or implement fewer types of channel via this API.

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 <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref> and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref> properties are 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 Handle_Type_None if no handle is 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 Handle_Type_None
`in_Suppress_Handler` : | Used to pass an 'in' argument: <p>Clients SHOULD always set this to true.</p> <tp:rationale> <p>The historical meaning was that clients that did not intend to take responsibility for displaying the channel to the user could set this to FALSE, in which case the channel dispatcher would launch an appropriate channel handler.</p> <p>However, clients whose functionality relies on having a working channel dispatcher should obtain that functionality by calling methods on the channel dispatcher, so that they will get an appropriate error if the channel dispatcher is missing or not working.</p> <p>The channel dispatcher itself should set this to true too, so that it will ignore the <tp:member-ref>NewChannel</tp:member-ref> signal that results from the creation of the channel. It can then dispatch the channel returned from this method to an appropriate handler.</p> <p>So, there is no sensible use-case for setting this to false, and setting it to false can result in unhandled channels (in the case where clients assume that a channel dispatcher is present, but it isn't).</p> </tp:rationale>
`out_Object_Path` : | 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 *out_Handles,
                                                             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
`out_Handles` : | Used to return an 'out' argument if `error` is `NULL`: An array of integer handle numbers in the same order as the given identifiers.
`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_Identifiers,
                                                             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 <tp:member-ref>ReleaseHandles</tp:member-ref> method. Where the identifier 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_Identifiers` : | Used to pass an 'in' argument: An array of identifiers of entities to request handles for
`callback` : | called when the method call succeeds or fails; may be `NULL` to make a "fire and forget" call with no reply tracking
`user_data` : | user-supplied data passed to the callback; must be `NULL` if `callback` is `NULL`
`destroy` : | called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be `NULL` if `callback` is `NULL`
`weak_object` : | If not `NULL`, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be `NULL` if `callback` is `NULL`
Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

### tp_cli_connection_run_request_handles ()

    gboolean            tp_cli_connection_run_request_handles
                                                            (TpConnection *proxy,
                                                             gint timeout_ms,
                                                             guint in_Handle_Type,
                                                             const gchar **in_Identifiers,
                                                             GArray **out_Handles,
                                                             GError **error,
                                                             GMainLoop **loop);

### Warning

`tp_cli_connection_run_request_handles` is deprecated and should not be used in newly-written code.

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 <tp:member-ref>ReleaseHandles</tp:member-ref> method. Where the identifier 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_Identifiers` : | Used to pass an 'in' argument: An array of identifiers of entities to request handles for
`out_Handles` : | Used to return an 'out' argument if `TRUE` is returned: An array of integer handle numbers in the same order as the given identifiers.
`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, or Handle_Type_None if no handle is specified
`arg_Handle` : | A handle indicating the specific contact, room or list this channel communicates with, or zero if no handle is specified
`arg_Suppress_Handler` : | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>If true, the channel was requested by a client that intends to present it to the user itself (i.e. it passed suppress_handler=TRUE to the <tp:member-ref>RequestChannel</tp:member-ref> method), so no other handler should be launched. Clients MAY assume that channels where this is true were created by a user request.</p> <p>If false, either the channel was created due to incoming information from the service, or the channel was requested by a local client that does not intend to handle the channel itself (this usage is deprecated).</p> <p>Clients MUST NOT assume that only incoming channels will have this flag set to false.</p>
`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.

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

    void                (*tp_cli_connection_signal_callback_self_handle_changed)
                                                            (TpConnection *proxy,
                                                             guint arg_Self_Handle,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Represents the signature of a callback for the signal SelfHandleChanged.

`proxy` : | The proxy on which `tp_cli_connection_connect_to_self_handle_changed()` was called
`arg_Self_Handle` : | The new value of the SelfHandle property.
`user_data` : | User-supplied data
`weak_object` : | User-supplied weakly referenced object

### tp_cli_connection_connect_to_self_handle_changed ()

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

Connect a handler to the signal SelfHandleChanged.

Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property changes. If the connection is not yet in the CONNECTED state, this signal is not guaranteed to be emitted.

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

### tp_cli_connection_signal_callback_connection_error ()

    void                (*tp_cli_connection_signal_callback_connection_error)
                                                            (TpConnection *proxy,
                                                             const gchar *arg_Error,
                                                             GHashTable *arg_Details,
                                                             gpointer user_data,
                                                             GObject *weak_object);

Represents the signature of a callback for the signal ConnectionError.

`proxy` : | The proxy on which `tp_cli_connection_connect_to_connection_error()` was called
`arg_Error` : | The name of a D-Bus error describing the error that occurred, which may correspond to a <tp:type>Connection_Status_Reason</tp:type>, or may be a more specific Telepathy error (such as <code>org.freedesktop.Telepathy.Errors.ConnectionRefused</code> for Connection_Status_Reason_Network_Error) or a protocol-specific or connection-manager-specific error in a suitable namespace. <tp:rationale> For instance, a SIP connection manager could signal &quot;402 Payment Required&quot; as an error in a connection-manager-specific namespace, or a link-local XMPP implementation that used Avahi could provide the error given to it by the avahi-daemon. </tp:rationale>
`arg_Details` : | <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Additional information about the error, which may include the following well-known keys:</p> <dl> <dt>debug-message (s)</dt> <dd>Debugging information on the change, corresponding to the message part of a D-Bus error message, which SHOULD NOT be displayed to users under normal circumstances</dd> <dt>user-requested (b), expected-hostname (s), certificate-hostname (s)</dt> <dd>The same details defined in <tp:type>TLS_Certificate_Rejection</tp:type>.</dd> </dl>
`user_data` : | User-supplied data
`weak_object` : | User-supplied weakly referenced object

### tp_cli_connection_connect_to_connection_error ()

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

Connect a handler to the signal ConnectionError.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Emitted when an error occurs that renders this connection unusable. </p> <p>Whenever this signal is emitted, it MUST immediately be followed by a <tp:member-ref>StatusChanged</tp:member-ref> signal with status Connection_Status_Disconnected and an appropriate reason code.</p> <p>Connection managers SHOULD emit this signal on disconnection, but need not do so. Clients MUST support connection managers that emit StatusChanged(Disconnected, ...) without first emitting ConnectionError.</p> <tp:rationale> <p>This signal provides additional information about the reason for disconnection. The reason for connection is always straightforward - it was requested - so it does not need further explanation. However, on errors, it can be useful to provide additional information.</p> <p>The <tp:type>Connection_Status_Reason</tp:type> is not given here, since it will be signalled in <tp:member-ref>StatusChanged</tp:member-ref>. A reasonable client implementation would be to store the information given by this signal until StatusChanged is received, at which point the information given by this signal can be used to supplement the StatusChanged signal.</p> </tp:rationale>

`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 `"capabilities"` property

      "capabilities"             TpCapabilities*       : Read

The `TpCapabilities` object representing the capabilities of this connection, or NULL if we don't know yet.

To wait for valid capability information, call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CAPABILITIES`.

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

This is similar to `TP_CONNECTION_FEATURE_CONNECTED`, except that once it has changed to `TRUE`, it remains `TRUE` even if the connection has been invalidated.

Default value: FALSE

### The `"self-handle"` property

      "self-handle"              guint                 : Read

The `TP_HANDLE_TYPE_CONTACT` handle of the local user on this connection, or 0 if we don't know yet or if the connection has become invalid.

To wait for a valid self-handle (and other properties), call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONNECTED`.

Default value: 0

### The `"status"` property

      "status"                   guint                 : Read

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

To wait for a valid status (and other properties), call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CORE`.

Since version 0.11.3, the change to status `TP_CONNECTION_STATUS_CONNECTED` is delayed slightly, until introspection of the connection has finished.

Default value: 4294967295

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

      "status-reason"            guint                 : Read

To wait for a valid status (and other properties), call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CORE`.

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