TpConnection: telepathy-glib API Reference Manual

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

## Functions

void | (*TpConnectionNameListCb) ()
void | tp_list_connection_names ()
TpConnection * | tp_connection_new ()
gboolean | tp_connection_run_until_ready ()
void | (*TpConnectionWhenReadyCb) ()
void | tp_connection_call_when_ready ()
gboolean | tp_connection_is_ready ()
void | tp_connection_disconnect_async ()
gboolean | tp_connection_disconnect_finish ()
TpAccount * | tp_connection_get_account ()
TpConnectionStatus | tp_connection_get_status ()
const gchar * | tp_connection_get_connection_manager_name ()
const gchar * | tp_connection_get_cm_name ()
const gchar * | tp_connection_get_protocol_name ()
TpContact * | tp_connection_get_self_contact ()
TpHandle | tp_connection_get_self_handle ()
gboolean | tp_connection_has_immortal_handles ()
void | (*TpConnectionRequestHandlesCb) ()
void | tp_connection_request_handles ()
void | (*TpConnectionHoldHandlesCb) ()
void | tp_connection_get_contact_attributes ()
void | tp_connection_get_contact_list_attributes ()
void | tp_connection_hold_handles ()
void | tp_connection_unref_handles ()
void | tp_connection_init_known_interfaces ()
gint | tp_connection_presence_type_cmp_availability ()
gboolean | tp_connection_parse_object_path ()
TpCapabilities * | tp_connection_get_capabilities ()
TpAvatarRequirements * | tp_connection_get_avatar_requirements ()
TpContactInfoFlags | tp_connection_get_contact_info_flags ()
GList * | tp_connection_get_contact_info_supported_fields ()
GList * | tp_connection_dup_contact_info_supported_fields ()
void | tp_connection_set_contact_info_async ()
gboolean | tp_connection_set_contact_info_finish ()
const gchar * | tp_connection_get_detailed_error ()
gchar * | tp_connection_dup_detailed_error_vardict ()
void | tp_connection_add_client_interest ()
void | tp_connection_add_client_interest_by_id ()
GBinding * | tp_connection_bind_connection_status_to_property ()
gboolean | tp_connection_get_balance ()
const gchar * | tp_connection_get_balance_uri ()
TpAvatarRequirements * | tp_avatar_requirements_new ()
TpAvatarRequirements * | tp_avatar_requirements_copy ()
void | tp_avatar_requirements_destroy ()
TpContactInfoFieldSpec * | tp_contact_info_field_spec_copy ()
void | tp_contact_info_field_spec_free ()
GList * | tp_contact_info_spec_list_copy ()
void | tp_contact_info_spec_list_free ()
TpContactInfoField * | tp_contact_info_field_new ()
TpContactInfoField * | tp_contact_info_field_copy ()
void | tp_contact_info_field_free ()
GList * | tp_contact_info_list_copy ()
void | tp_contact_info_list_free ()
TpContactListState | tp_connection_get_contact_list_state ()
gboolean | tp_connection_get_contact_list_persists ()
gboolean | tp_connection_get_can_change_contact_list ()
gboolean | tp_connection_get_request_uses_message ()
GPtrArray * | tp_connection_dup_contact_list ()
void | tp_connection_request_subscription_async ()
gboolean | tp_connection_request_subscription_finish ()
void | tp_connection_authorize_publication_async ()
gboolean | tp_connection_authorize_publication_finish ()
void | tp_connection_remove_contacts_async ()
gboolean | tp_connection_remove_contacts_finish ()
void | tp_connection_unsubscribe_async ()
gboolean | tp_connection_unsubscribe_finish ()
void | tp_connection_unpublish_async ()
gboolean | tp_connection_unpublish_finish ()
gboolean | tp_connection_get_disjoint_groups ()
TpContactMetadataStorageType | tp_connection_get_group_storage ()
const gchar * const * | tp_connection_get_contact_groups ()
void | tp_connection_set_group_members_async ()
gboolean | tp_connection_set_group_members_finish ()
void | tp_connection_add_to_group_async ()
gboolean | tp_connection_add_to_group_finish ()
void | tp_connection_remove_from_group_async ()
gboolean | tp_connection_remove_from_group_finish ()
void | tp_connection_remove_group_async ()
gboolean | tp_connection_remove_group_finish ()
void | tp_connection_rename_group_async ()
gboolean | tp_connection_rename_group_finish ()
void | tp_connection_block_contacts_async ()
gboolean | tp_connection_block_contacts_finish ()
void | tp_connection_unblock_contacts_async ()
gboolean | tp_connection_unblock_contacts_finish ()
gboolean | tp_connection_can_report_abusive ()
GPtrArray * | tp_connection_get_blocked_contacts ()
gboolean | tp_connection_can_set_contact_alias ()
void | (*tp_cli_connection_callback_for_connect) ()
TpProxyPendingCall * | tp_cli_connection_call_connect ()
gboolean | tp_cli_connection_run_connect ()
void | (*tp_cli_connection_callback_for_disconnect) ()
TpProxyPendingCall * | tp_cli_connection_call_disconnect ()
gboolean | tp_cli_connection_run_disconnect ()
void | (*tp_cli_connection_callback_for_get_interfaces) ()
TpProxyPendingCall * | tp_cli_connection_call_get_interfaces ()
gboolean | tp_cli_connection_run_get_interfaces ()
void | (*tp_cli_connection_callback_for_get_protocol) ()
TpProxyPendingCall * | tp_cli_connection_call_get_protocol ()
gboolean | tp_cli_connection_run_get_protocol ()
void | (*tp_cli_connection_callback_for_get_self_handle) ()
TpProxyPendingCall * | tp_cli_connection_call_get_self_handle ()
gboolean | tp_cli_connection_run_get_self_handle ()
void | (*tp_cli_connection_callback_for_get_status) ()
TpProxyPendingCall * | tp_cli_connection_call_get_status ()
gboolean | tp_cli_connection_run_get_status ()
void | (*tp_cli_connection_callback_for_hold_handles) ()
TpProxyPendingCall * | tp_cli_connection_call_hold_handles ()
gboolean | tp_cli_connection_run_hold_handles ()
void | (*tp_cli_connection_callback_for_inspect_handles) ()
TpProxyPendingCall * | tp_cli_connection_call_inspect_handles ()
gboolean | tp_cli_connection_run_inspect_handles ()
void | (*tp_cli_connection_callback_for_list_channels) ()
TpProxyPendingCall * | tp_cli_connection_call_list_channels ()
gboolean | tp_cli_connection_run_list_channels ()
void | (*tp_cli_connection_callback_for_release_handles) ()
TpProxyPendingCall * | tp_cli_connection_call_release_handles ()
gboolean | tp_cli_connection_run_release_handles ()
void | (*tp_cli_connection_callback_for_request_channel) ()
TpProxyPendingCall * | tp_cli_connection_call_request_channel ()
gboolean | tp_cli_connection_run_request_channel ()
void | (*tp_cli_connection_callback_for_request_handles) ()
TpProxyPendingCall * | tp_cli_connection_call_request_handles ()
gboolean | tp_cli_connection_run_request_handles ()
void | (*tp_cli_connection_signal_callback_new_channel) ()
TpProxySignalConnection * | tp_cli_connection_connect_to_new_channel ()
void | (*tp_cli_connection_signal_callback_self_handle_changed) ()
TpProxySignalConnection * | tp_cli_connection_connect_to_self_handle_changed ()
void | (*tp_cli_connection_signal_callback_self_contact_changed) ()
TpProxySignalConnection * | tp_cli_connection_connect_to_self_contact_changed ()
void | (*tp_cli_connection_signal_callback_status_changed) ()
TpProxySignalConnection * | tp_cli_connection_connect_to_status_changed ()
void | (*tp_cli_connection_signal_callback_connection_error) ()
TpProxySignalConnection * | tp_cli_connection_connect_to_connection_error ()
TpProxyPendingCall * | tp_cli_connection_call_add_client_interest ()
TpProxyPendingCall * | tp_cli_connection_call_remove_client_interest ()
void | (*tp_cli_connection_callback_for_add_client_interest) ()
void | (*tp_cli_connection_callback_for_remove_client_interest) ()

## Properties

gint | balance | Read
gchar * | balance-currency | Read
guint | balance-scale | Read
gchar * | balance-uri | Read
GPtrArray * | blocked-contacts | Read
gboolean | can-change-contact-list | Read
gboolean | can-report-abusive | Read
TpCapabilities * | capabilities | Read
gchar * | cm-name | Read
gchar * | connection-manager-name | Read
gboolean | connection-ready | Read
GStrv | contact-groups | Read
gboolean | contact-list-persists | Read
guint | contact-list-state | Read
gboolean | disjoint-groups | Read
guint | group-storage | Read
gchar * | protocol-name | Read
gboolean | request-uses-message | Read
TpContact * | self-contact | Read
guint | self-handle | Read
guint | status | Read
guint | status-reason | Read

## Signals

void | balance-changed | Has Details
void | blocked-contacts-changed | Run Last
void | contact-list-changed | Run Last
void | group-renamed | Run Last
void | groups-created | Run Last
void | groups-removed | Run Last

## Types and Values

struct | TpConnection
struct | TpConnectionClass
#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
#define | TP_CONNECTION_FEATURE_BALANCE
#define | TP_CONNECTION_FEATURE_CONTACT_LIST
#define | TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES
#define | TP_CONNECTION_FEATURE_CONTACT_GROUPS
#define | TP_CONNECTION_FEATURE_CONTACT_BLOCKING
#define | TP_CONNECTION_FEATURE_ALIASING
#define | TP_UNKNOWN_CONNECTION_STATUS
#define | TP_ERRORS_DISCONNECTED
#define | TP_TYPE_AVATAR_REQUIREMENTS
struct | TpAvatarRequirements
struct | TpContactInfoFieldSpec
#define | TP_TYPE_CONTACT_INFO_FIELD_SPEC
#define | TP_TYPE_CONTACT_INFO_SPEC_LIST
struct | TpContactInfoField
#define | TP_TYPE_CONTACT_INFO_FIELD
#define | TP_TYPE_CONTACT_INFO_LIST

## Object Hierarchy

        GBoxed
        ├── TpAvatarRequirements
        ├── TpContactInfoField
        ├── TpContactInfoFieldSpec
        ├── TpContactInfoList
        ╰── TpContactInfoSpecList
        GObject
        ╰── TpProxy
            ╰── TpConnection

## Includes

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

## Description

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

TpConnection objects should be obtained from a TpAccount, unless you are implementing a lower-level Telepathy component (such as the account manager service itself).

Since 0.16, TpConnection always has a non-`NULL` “factory”, and its “factory” will be propagated to its TpChannel objects (if any). Similarly, the “factory”'s features will be used for TpContact objects. If a TpConnection is created without going via the TpAccount or specifying a “factory”, the default is to use a new TpAutomaticClientFactory.

## Functions

### 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()`.

#### Parameters

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.

#### Parameters

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

### tp_connection_new ()

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

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

Use `tp_simple_client_factory_ensure_connection()` instead.

#### Parameters

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

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

`tp_connection_run_until_ready` has been deprecated since version 0.11.0 and should not be used in newly-written code.

Use `tp_proxy_prepare_async()` and re-enter the main loop yourself, 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.

[skip]

#### Parameters

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

`TpConnectionWhenReadyCb` has been deprecated since version 0.17.6 and should not be used in newly-written code.

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)

#### Parameters

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

`tp_connection_call_when_ready` has been deprecated since version 0.17.6 and should not be used in newly-written code.

Use `tp_proxy_prepare_async()`

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.

[skip]

#### Parameters

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

`tp_connection_is_ready` has been deprecated since version 0.17.6 and should not be used in newly-written code.

use `tp_proxy_is_prepared()` with `TP_CONNECTION_FEATURE_CONNECTED`

Returns the same thing as the “connection-ready” property.

[skip]

#### Parameters

self | a connection |

#### Returns

`TRUE` if introspection has completed

Since: 0.7.17

### tp_connection_disconnect_async ()

    void
    tp_connection_disconnect_async (TpConnection *self,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Disconnect the connection.

This method is intended for use by AccountManager implementations, such as Mission Control. To disconnect a connection managed by an AccountManager, either use `tp_account_request_presence_async()` or `tp_account_set_enabled_async()`, depending whether the intention is to put the account offline temporarily, or disable it longer-term.

#### Parameters

self | a TpConnection |
callback | a callback to call when the request is satisfied |
user_data | data to pass to `callback` |

Since: 0.17.5

### tp_connection_disconnect_finish ()

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

Interpret the result of `tp_connection_disconnect_async()`.

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the call was successful, otherwise `FALSE`

Since: 0.17.5

### tp_connection_get_account ()

    TpAccount *
    tp_connection_get_account (TpConnection *self);

Return the the TpAccount associated with this connection. Will return `NULL` if `self` was not acquired from a TpAccount via `tp_account_get_connection()`, or if the account object got finalized in the meantime (TpConnection does not keep a strong ref on its TpAccount).

#### Parameters

self | a connection |

#### Returns

the account associated with this connection, or `NULL`.

[transfer none]

Since: 0.15.5

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

#### Parameters

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

    const gchar *
    tp_connection_get_connection_manager_name
                                   (TpConnection *self);

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

Use `tp_connection_get_cm_name()` instead.

#### Parameters

self | a TpConnection |

#### Returns

the same as the “connection-manager-name” property

Since: 0.13.16

### tp_connection_get_cm_name ()

    const gchar *
    tp_connection_get_cm_name (TpConnection *self);

#### Parameters

self | a TpConnection |

#### Returns

the same as the “cm-name” property

Since: 0.19.3

### tp_connection_get_protocol_name ()

    const gchar *
    tp_connection_get_protocol_name (TpConnection *self);

#### Parameters

self | a TpConnection |

#### Returns

the same as the “protocol-name” property

Since: 0.13.16

### tp_connection_get_self_contact ()

    TpContact *
    tp_connection_get_self_contact (TpConnection *self);

Return a TpContact representing the local user on this connection.

The returned object is not necessarily valid after the main loop is re-entered; ref it with `g_object_ref()` if you want to keep it.

#### Parameters

self | a connection |

#### Returns

the value of the TpConnection:self-contact property, which may be `NULL`.

[transfer none]

Since: 0.13.9

### tp_connection_get_self_handle ()

    TpHandle
    tp_connection_get_self_handle (TpConnection *self);

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

Use `tp_connection_get_self_contact()` instead.

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.

#### Parameters

self | a connection |

#### Returns

the value of the TpConnection:self-handle property

Since: 0.7.26

### tp_connection_has_immortal_handles ()

    gboolean
    tp_connection_has_immortal_handles (TpConnection *self);

Return `TRUE` if this connection is known to not destroy handles (TpHandle) until it disconnects.

On such connections, if you know that a handle maps to a particular identifier now, then you can rely on that handle mapping to that identifier for the whole lifetime of the connection.

#### Parameters

self | a connection |

#### Returns

`TRUE` if handles last as long as the connection itself

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

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

See `tp_connection_request_handles()`.

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

On success, the caller has a reference to each handle in `handles` .

Since telepathy-glib version 0.13.8, the handles will remain valid until `connection` becomes invalid (signalled by “invalidated”). In earlier versions, they could be released with `tp_connection_unref_handles()`.

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

#### Parameters

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

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

If `handle_type` is TP_HANDLE_TYPE_CONTACT, use `tp_connection_dup_contact_by_id_async()` instead. For channel requests, use `tp_account_channel_request_set_target_id()` instead.

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.

#### Parameters

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

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

See `tp_connection_hold_handles()`.

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

On success, the caller has a reference to each handle in `handles` .

Since telepathy-glib version 0.13.8, the handles will remain valid until `connection` becomes invalid (signalled by “invalidated”). In earlier versions, they could be released with `tp_connection_unref_handles()`.

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

#### Parameters

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

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

Use `tp_simple_client_factory_ensure_contact()` instead.

Return (via a callback) any number of attributes of the given handles.

Since telepathy-glib version 0.13.8, the handles will remain valid until `connection` becomes invalid (signalled by “invalidated”). In earlier versions, if `hold` was `TRUE`, the callback would hold a reference to them which could be released with `tp_connection_unref_handles()`.

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.

#### Parameters

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

    void
    tp_connection_get_contact_list_attributes
                                   (TpConnection *self,
                                    gint timeout_ms,
                                    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);

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

Use `tp_connection_dup_contact_list()` instead.

Return (via a callback) the contacts on the contact list and any number of their attributes.

Since telepathy-glib version 0.13.8, the handles will remain valid until `connection` becomes invalid (signalled by “invalidated”). In earlier versions, if `hold` was `TRUE`, the callback would hold a reference to them which could be released with `tp_connection_unref_handles()`.

This is a thin wrapper around the RequestContactList D-Bus method, and should be used in preference to lower-level functions; it is similar to `tp_connection_get_contact_attributes()`.

The TpContact API provides a higher-level abstraction which should usually be used instead.

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

#### Parameters

self | a connection |
timeout_ms | the timeout in milliseconds (using a large timeout is recommended) |
interfaces | a GStrv of interfaces |
hold | if `TRUE`, the callback will hold one reference to each handle it receives |
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);

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

Holding handles is not needed with Connection Managers having immortal handles (any Connection Manager using telepathy-glib >= 0.13.8). Other Connection Managers are considered deprecated, clients wanting to still support them should continue using this deprecated function.

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.

#### Parameters

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

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

This is no-op so can be safely removed.

Do nothing. In versions of telepathy-glib prior to 0.13.8, this released a reference to the handles in `handles` .

#### Parameters

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

#### Parameters

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

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

Use `tp_connection_get_protocol_name()` and `tp_connection_get_connection_manager_name()` instead.

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

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

Since 0.19.9. New code should use `tp_connection_dup_contact_info_supported_fields()` instead.

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.

#### Parameters

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]

Since: 0.11.7

### tp_connection_dup_contact_info_supported_fields ()

    GList *
    tp_connection_dup_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 `tp_contact_info_spec_list_free()`.

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.

#### Parameters

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 full]

Since: 0.19.9

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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]

#### Returns

a D-Bus error name, or `NULL`.

[transfer none][allow-none]

Since: 0.11.4

### tp_connection_dup_detailed_error_vardict ()

    gchar *
    tp_connection_dup_detailed_error_vardict
                                   (TpConnection *self,
                                    GVariant **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` .

#### Parameters

self | a connection |
details | optionally used to return a `G_VARIANT_TYPE_VARDICT` with details of the error. | [out][allow-none][transfer full]

#### Returns

a D-Bus error name, or `NULL`.

[transfer full][allow-none]

Since: 0.19.0

### tp_connection_add_client_interest ()

    void
    tp_connection_add_client_interest (TpConnection *self,
                                       const gchar *interested_in);

Subscribe to any opt-in change notifications for `interested_in` .

For contact information, use TpContact instead, which will call this automatically.

#### Parameters

self | a connection |
interested_in | a string identifying an interface or part of an interface to which this connection will subscribe |

Since: 0.11.3

### tp_connection_add_client_interest_by_id ()

    void
    tp_connection_add_client_interest_by_id
                                   (TpConnection *self,
                                    GQuark interested_in);

Subscribe to any opt-in change notifications for `interested_in` .

Equivalent to, but a little more efficient than, calling `tp_connection_add_client_interest()` for the string value of `interested_in` .

[skip]

#### Parameters

self | a connection |
interested_in | a quark identifying an interface or part of an interface to which this connection will subscribe |

Since: 0.11.3

### tp_connection_bind_connection_status_to_property ()

    GBinding *
    tp_connection_bind_connection_status_to_property
                                   (TpConnection *self,
                                    gpointer target,
                                    const char *target_property,
                                    gboolean invert);

Binds the :status of `self` to the boolean property of another object using a GBinding such that the `target_property` will be set to `TRUE` when `self` is connected (and `invert` is `FALSE`).

`target_property` will be synchronised immediately (`G_BINDING_SYNC_CREATE`). `invert` can be interpreted as analogous to `G_BINDING_INVERT_BOOLEAN`.

For instance, this function can be used to bind the GtkWidget:sensitive property to only make a widget sensitive when the account is connected.

See `g_object_bind_property()` for more information.

#### Parameters

self | a TpConnection |
target | the target GObject |
target_property | the property on `target` to bind (must be `G_TYPE_BOOLEAN`) |
invert | `TRUE` if you wish to invert the value of `target_property` (i.e. `FALSE` if connected) |

#### Returns

the GBinding instance representing the binding between the `self` and the `target` . The binding is released whenever the GBinding reference count reaches zero.

[transfer none]

Since: 0.13.16

### tp_connection_get_balance ()

    gboolean
    tp_connection_get_balance (TpConnection *self,
                               gint *balance,
                               guint *scale,
                               const gchar **currency);

If `self` has a valid account balance, returns `TRUE` and sets the variables pointed to by `balance` , `scale` and `currency` to the appropriate fields of the Balance.AccountBalance property.

The monetary value of the balance is expressed as a fixed-point number, `balance` , with a decimal scale defined by `scale` ; for instance a `balance` of 1234 with `scale` of 2 represents a value of "12.34" in the currency represented by `currency` .

Requires `TP_CONNECTION_FEATURE_BALANCE` to be prepared.

#### Parameters

self | a TpConnection |
balance | a pointer to store the account balance (or `NULL`). | [out]
scale | a pointer to store the balance scale (or `NULL`). | [out]
currency | a pointer to store the balance currency (or `NULL`). | [out][transfer none]

#### Returns

`TRUE` if the balance is valid (and the values set), `FALSE` if the balance is invalid.

Since: 0.15.1

### tp_connection_get_balance_uri ()

    const gchar *
    tp_connection_get_balance_uri (TpConnection *self);

The value of Balance.ManageCreditURI.

Requires `TP_CONNECTION_FEATURE_BALANCE` to be prepared.

#### Parameters

self | a TpConnection |

#### Returns

the “balance-uri” property.

[transfer none]

Since: 0.15.1

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

#### Parameters

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

[skip]

#### Parameters

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.

[skip]

#### Parameters

self | a TpAvatarRequirements |

Since: 0.11.4

### tp_contact_info_field_spec_copy ()

    TpContactInfoFieldSpec *
    tp_contact_info_field_spec_copy (const TpContactInfoFieldSpec *self);

[skip]

#### Parameters

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.

[skip]

#### Parameters

self | a TpContactInfoFieldSpec |

Since: 0.11.7

### tp_contact_info_spec_list_copy ()

    GList *
    tp_contact_info_spec_list_copy (GList *list);

[skip]

#### Parameters

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.

[skip]

#### Parameters

list | a GList of TpContactInfoFieldSpec |

Since: 0.11.7

### tp_contact_info_field_new ()

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

#### Parameters

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

[skip]

#### Parameters

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.

[skip]

#### Parameters

self | a TpContactInfoField |

Since: 0.11.7

### tp_contact_info_list_copy ()

    GList *
    tp_contact_info_list_copy (GList *list);

[skip]

#### Parameters

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.

[skip]

#### Parameters

list | a GList of TpContactInfoField |

Since: 0.11.7

### tp_connection_get_contact_list_state ()

    TpContactListState
    tp_connection_get_contact_list_state (TpConnection *self);

#### Parameters

self | a TpConnection |

#### Returns

the value of “contact-list-state” property

Since: 0.15.5

### tp_connection_get_contact_list_persists ()

    gboolean
    tp_connection_get_contact_list_persists
                                   (TpConnection *self);

#### Parameters

self | a TpConnection |

#### Returns

the value of “contact-list-persists” property

Since: 0.15.5

### tp_connection_get_can_change_contact_list ()

    gboolean
    tp_connection_get_can_change_contact_list
                                   (TpConnection *self);

#### Parameters

self | a TpConnection |

#### Returns

the value of “can-change-contact-list” property

Since: 0.15.5

### tp_connection_get_request_uses_message ()

    gboolean
    tp_connection_get_request_uses_message
                                   (TpConnection *self);

#### Parameters

self | a TpConnection |

#### Returns

the value of “request-uses-message” property

Since: 0.15.5

### tp_connection_dup_contact_list ()

    GPtrArray *
    tp_connection_dup_contact_list (TpConnection *self);

Retrieves the user's contact list. In general, blocked contacts are not included in this list. The TpContact objects returned are guaranteed to have all of the features previously passed to `tp_simple_client_factory_add_contact_features()` prepared.

Before calling this method, you must first call `tp_proxy_prepare_async()` with the `TP_CONNECTION_FEATURE_CONTACT_LIST` feature, and verify that “contact-list-state” is set to `TP_CONTACT_LIST_STATE_SUCCESS`.

#### Parameters

self | a TpConnection |

#### Returns

a new GPtrArray of TpContact. Use `g_ptr_array_unref()` when done.

[transfer container][type GLib.PtrArray][element-type TelepathyGLib.Contact]

Since: 0.15.5

### tp_connection_request_subscription_async ()

    void
    tp_connection_request_subscription_async
                                   (TpConnection *self,
                                    guint n_contacts,
                                    TpContact * const *contacts,
                                    const gchar *message,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Request that the given `contacts` allow the local user to subscribe to their presence, i.e. that their “subscribe-state” property becomes `TP_SUBSCRIPTION_STATE_YES`.

For this to work properly `self` must have interface `TP_IFACE_CONNECTION_INTERFACE_CONTACT_LIST`.

#### Parameters

self | a TpConnection |
n_contacts | The number of contacts in `contacts` (must be at least 1) |
contacts | An array of TpContact objects to whom requests are to be sent. | [array length=n_contacts]
message | an optional plain-text message from the user, to send to those `contacts` with the subscription request. |
callback | a callback to call when the operation finishes |
user_data | data to pass to `callback` |

Since: 0.15.5

### tp_connection_request_subscription_finish ()

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

Finishes `tp_connection_request_subscription_async()`

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the operation was successful, otherwise `FALSE`.

Since: 0.15.5

### tp_connection_authorize_publication_async ()

    void
    tp_connection_authorize_publication_async
                                   (TpConnection *self,
                                    guint n_contacts,
                                    TpContact * const *contacts,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

For each of the given `contacts` , request that the local user's presence is sent to that contact, i.e. that their “publish-state” property becomes `TP_SUBSCRIPTION_STATE_YES`.

For this to work properly `self` must have interface `TP_IFACE_CONNECTION_INTERFACE_CONTACT_LIST`.

#### Parameters

self | a TpConnection |
n_contacts | The number of contacts in `contacts` (must be at least 1) |
contacts | An array of TpContact objects to authorize. | [array length=n_contacts]
callback | a callback to call when the operation finishes |
user_data | data to pass to `callback` |

Since: 0.15.5

### tp_connection_authorize_publication_finish ()

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

Finishes `tp_connection_authorize_publication_async()`

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the operation was successful, otherwise `FALSE`.

Since: 0.15.5

### tp_connection_remove_contacts_async ()

    void
    tp_connection_remove_contacts_async (TpConnection *self,
                                         guint n_contacts,
                                         TpContact * const *contacts,
                                         GAsyncReadyCallback callback,
                                         gpointer user_data);

Remove the given `contacts` from the contact list entirely. It is protocol-dependent whether this works, and under which circumstances.

For this to work properly `self` must have interface `TP_IFACE_CONNECTION_INTERFACE_CONTACT_LIST`.

#### Parameters

self | a TpConnection |
n_contacts | The number of contacts in `contacts` (must be at least 1) |
contacts | An array of TpContact objects to remove. | [array length=n_contacts]
callback | a callback to call when the operation finishes |
user_data | data to pass to `callback` |

Since: 0.15.5

### tp_connection_remove_contacts_finish ()

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

Finishes `tp_connection_remove_contacts_async()`

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the operation was successful, otherwise `FALSE`.

Since: 0.15.5

### tp_connection_unsubscribe_async ()

    void
    tp_connection_unsubscribe_async (TpConnection *self,
                                     guint n_contacts,
                                     TpContact * const *contacts,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Attempt to set the given `contacts` ' “subscribe-state” property to `TP_SUBSCRIPTION_STATE_NO`, i.e. stop receiving their presence.

For this to work properly `self` must have interface `TP_IFACE_CONNECTION_INTERFACE_CONTACT_LIST`.

#### Parameters

self | a TpConnection |
n_contacts | The number of contacts in `contacts` (must be at least 1) |
contacts | An array of TpContact objects to remove. | [array length=n_contacts]
callback | a callback to call when the operation finishes |
user_data | data to pass to `callback` |

Since: 0.15.5

### tp_connection_unsubscribe_finish ()

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

Finishes `tp_connection_unsubscribe_async()`

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the operation was successful, otherwise `FALSE`.

Since: 0.15.5

### tp_connection_unpublish_async ()

    void
    tp_connection_unpublish_async (TpConnection *self,
                                   guint n_contacts,
                                   TpContact * const *contacts,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Attempt to set the given `contacts` ' “publish-state” property to `TP_SUBSCRIPTION_STATE_NO`, i.e. stop sending presence to them.

For this to work properly `self` must have interface `TP_IFACE_CONNECTION_INTERFACE_CONTACT_LIST`.

#### Parameters

self | a TpConnection |
n_contacts | The number of contacts in `contacts` (must be at least 1) |
contacts | An array of TpContact objects to remove. | [array length=n_contacts]
callback | a callback to call when the operation finishes |
user_data | data to pass to `callback` |

Since: 0.15.5

### tp_connection_unpublish_finish ()

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

Finishes `tp_connection_unpublish_async()`

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the operation was successful, otherwise `FALSE`.

Since: 0.15.5

### tp_connection_get_disjoint_groups ()

    gboolean
    tp_connection_get_disjoint_groups (TpConnection *self);

#### Parameters

self | a TpConnection |

#### Returns

the value of “disjoint-groups”

Since: 0.15.5

### tp_connection_get_group_storage ()

    TpContactMetadataStorageType
    tp_connection_get_group_storage (TpConnection *self);

#### Parameters

self | a TpConnection |

#### Returns

the value of “group-storage”

Since: 0.15.5

### tp_connection_get_contact_groups ()

    const gchar * const *
    tp_connection_get_contact_groups (TpConnection *self);

#### Parameters

self | a TpConnection |

#### Returns

the value of “contact-groups”.

[array zero-terminated=1][transfer none]

Since: 0.15.5

### tp_connection_set_group_members_async ()

    void
    tp_connection_set_group_members_async (TpConnection *self,
                                           const gchar *group,
                                           guint n_contacts,
                                           TpContact * const *contacts,
                                           GAsyncReadyCallback callback,
                                           gpointer user_data);

Add the given `contacts` to the given `group` (creating it if necessary), and remove all other members.

For this to work properly `self` must have interface `TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS`.

#### Parameters

self | a TpConnection |
group | the group to alter. |
n_contacts | The number of contacts in `contacts` (must be at least 1) |
contacts | An array of TpContact objects members for the group. If this set is empty, this method MAY remove the group. | [array length=n_contacts]
callback | a callback to call when the operation finishes |
user_data | data to pass to `callback` |

Since: 0.15.5

### tp_connection_set_group_members_finish ()

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

Finishes `tp_connection_set_group_members_async()`

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the operation was successful, otherwise `FALSE`.

Since: 0.15.5

### tp_connection_add_to_group_async ()

    void
    tp_connection_add_to_group_async (TpConnection *self,
                                      const gchar *group,
                                      guint n_contacts,
                                      TpContact * const *contacts,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

Add the given `contacts` to the given `group` , creating it if necessary.

For this to work properly `self` must have interface `TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS`.

#### Parameters

self | a TpConnection |
group | the group to alter. |
n_contacts | The number of contacts in `contacts` (must be at least 1) |
contacts | An array of TpContact objects to include in the group. | [array length=n_contacts]
callback | a callback to call when the operation finishes |
user_data | data to pass to `callback` |

Since: 0.15.5

### tp_connection_add_to_group_finish ()

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

Finishes `tp_connection_add_to_group_async()`

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the operation was successful, otherwise `FALSE`.

Since: 0.15.5

### tp_connection_remove_from_group_async ()

    void
    tp_connection_remove_from_group_async (TpConnection *self,
                                           const gchar *group,
                                           guint n_contacts,
                                           TpContact * const *contacts,
                                           GAsyncReadyCallback callback,
                                           gpointer user_data);

Remove the given `contacts` from the given `group` . If there are no members left in the group afterwards, the group MAY itself be removed.

For this to work properly `self` must have interface `TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS`.

#### Parameters

self | a TpConnection |
group | the group to alter. |
n_contacts | The number of contacts in `contacts` (must be at least 1) |
contacts | An array of TpContact objects to remove from the group. | [array length=n_contacts]
callback | a callback to call when the operation finishes |
user_data | data to pass to `callback` |

Since: 0.15.5

### tp_connection_remove_from_group_finish ()

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

Finishes `tp_connection_remove_from_group_async()`

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the operation was successful, otherwise `FALSE`.

Since: 0.15.5

### tp_connection_remove_group_async ()

    void
    tp_connection_remove_group_async (TpConnection *self,
                                      const gchar *group,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

Remove all members from the given group, then remove the group itself.

For this to work properly `self` must have interface `TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS`.

#### Parameters

self | a TpConnection |
group | the group to remove. |
callback | a callback to call when the operation finishes |
user_data | data to pass to `callback` |

Since: 0.15.5

### tp_connection_remove_group_finish ()

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

Finishes `tp_connection_remove_group_async()`

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the operation was successful, otherwise `FALSE`.

Since: 0.15.5

### tp_connection_rename_group_async ()

    void
    tp_connection_rename_group_async (TpConnection *self,
                                      const gchar *old_name,
                                      const gchar *new_name,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

Rename the given `old_name` .

On protocols where groups behave like tags, this is an API short-cut for adding all of the group's members to a group with the new name, then removing the old group.

For this to work properly `self` must have interface `TP_IFACE_CONNECTION_INTERFACE_CONTACT_GROUPS`.

#### Parameters

self | a TpConnection |
old_name | the group to rename |
new_name | the new name for the group |
callback | a callback to call when the operation finishes |
user_data | data to pass to `callback` |

Since: 0.15.5

### tp_connection_rename_group_finish ()

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

Finishes `tp_connection_rename_group_async()`

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the operation was successful, otherwise `FALSE`.

Since: 0.15.5

### tp_connection_block_contacts_async ()

    void
    tp_connection_block_contacts_async (TpConnection *self,
                                        guint n_contacts,
                                        TpContact * const *contacts,
                                        gboolean report_abusive,
                                        GAsyncReadyCallback callback,
                                        gpointer user_data);

Direct the server to block `contacts` .

#### Parameters

self | a TpConnection |
n_contacts | the number of contacts in `contacts` (must be at least 1) |
contacts | An array of TpContact objects to block. | [array length=n_contacts]
report_abusive | If `TRUE`, report these contacts as abusive to the server administrators as well as blocking them. See “can-report-abusive” to discover whether reporting abuse is supported. If “can-report-abusive” is `FALSE`, this parameter will be ignored. |
callback | a callback to call when the operation finishes |
user_data | data to pass to `callback` |

Since: 0.17.0

### tp_connection_block_contacts_finish ()

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

Finishes `tp_connection_block_contacts_async()`

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the operation was successful, otherwise `FALSE`.

Since: 0.17.0

### tp_connection_unblock_contacts_async ()

    void
    tp_connection_unblock_contacts_async (TpConnection *self,
                                          guint n_contacts,
                                          TpContact * const *contacts,
                                          GAsyncReadyCallback callback,
                                          gpointer user_data);

Direct the server to unblock `contacts` .

#### Parameters

self | a TpConnection |
n_contacts | the number of contacts in `contacts` (must be at least 1) |
contacts | An array of TpContact objects to block. | [array length=n_contacts]
callback | a callback to call when the operation finishes |
user_data | data to pass to `callback` |

Since: 0.17.0

### tp_connection_unblock_contacts_finish ()

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

Finishes `tp_connection_unblock_contacts_async()`

#### Parameters

self | a TpConnection |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

`TRUE` if the operation was successful, otherwise `FALSE`.

Since: 0.17.0

### tp_connection_can_report_abusive ()

    gboolean
    tp_connection_can_report_abusive (TpConnection *self);

#### Parameters

self | a TpConnection |

#### Returns

the value of “can-report-abusive”

Since: 0.17.0

### tp_connection_get_blocked_contacts ()

    GPtrArray *
    tp_connection_get_blocked_contacts (TpConnection *self);

#### Parameters

self | a TpConnection |

#### Returns

the value of “blocked-contacts”.

[transfer none][element-type TelepathyGLib.Contact]

Since: 0.17.0

### tp_connection_can_set_contact_alias ()

    gboolean
    tp_connection_can_set_contact_alias (TpConnection *self);

Check if the user can set aliases on his contacts. TP_CONNECTION_FEATURE_ALIASING needs to be prepared for this function to return a meaningful value.

#### Parameters

self | a TpConnection |

#### Returns

`TRUE` if the aliases of contacts on `self` may be changed by the user of the service, not just by the contacts themselves; `FALSE` otherwise.

Since: 0.17.3

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

#### Parameters

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>

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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>

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

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

#### Parameters

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

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

#### Parameters

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 (TpContactHandle) |
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);

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

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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 (TpConnectionStatus) |
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.

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, which SHOULD always be the case in this version of telepathy-spec, this method does nothing and returns successfully, unless the given handle type or any of the given handles is invalid.</p> <p>In older connection managers, this method notifies 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>

#### Parameters

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 (TpHandleType) |
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);

`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>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, which SHOULD always be the case in this version of telepathy-spec, this method does nothing and returns successfully, unless the given handle type or any of the given handles is invalid.</p> <p>In older connection managers, this method notifies 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>

#### Parameters

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 (TpHandleType) |
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.

#### Parameters

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.

#### Parameters

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 (TpHandleType) |
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);

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

#### Parameters

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 (TpHandleType) |
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);

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

#### Parameters

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

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

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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.

<p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, which SHOULD always be the case in this version of telepathy-spec, this method does nothing and returns successfully, unless the given handle type or any of the given handles is invalid.</p> <p>In older connection managers, this method explicitly notifies 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 <tp:member-ref>HoldHandles</tp:member-ref> for notes.</p>

#### Parameters

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) (TpHandleType) |
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);

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

<p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, which SHOULD always be the case in this version of telepathy-spec, this method does nothing and returns successfully, unless the given handle type or any of the given handles is invalid.</p> <p>In older connection managers, this method explicitly notifies 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 <tp:member-ref>HoldHandles</tp:member-ref> for notes.</p>

#### Parameters

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) (TpHandleType) |
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);

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

#### Parameters

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

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

#### Parameters

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 (TpHandleType) |
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 (TpHandle) |
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);

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

#### Parameters

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 (TpHandleType) |
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 (TpHandle) |
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.

#### Parameters

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.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request several handles from the connection manager which represent a number of contacts, rooms or server-stored lists on the service.</p> <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, which SHOULD always be the case in this version of telepathy-spec, the handles remain valid until the connection disconnects.</p> <p>The implementation of this method in older connection managers must 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.</p>

#### Parameters

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 (TpHandleType) |
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);

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

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request several handles from the connection manager which represent a number of contacts, rooms or server-stored lists on the service.</p> <p>If <tp:member-ref>HasImmortalHandles</tp:member-ref> is true, which SHOULD always be the case in this version of telepathy-spec, the handles remain valid until the connection disconnects.</p> <p>The implementation of this method in older connection managers must 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.</p>

#### Parameters

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 (TpHandleType) |
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.

#### Parameters

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 (TpHandleType) |
arg_Handle | A handle indicating the specific contact, room or list this channel communicates with, or zero if no handle is specified (TpHandle) |
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.

#### Parameters

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.

#### Parameters

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. (TpContactHandle) |
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.

#### Parameters

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

    void
    (*tp_cli_connection_signal_callback_self_contact_changed)
                                   (TpConnection *proxy,
                                    guint arg_Self_Handle,
                                    const gchar *arg_Self_ID,
                                    gpointer user_data,
                                    GObject *weak_object);

Represents the signature of a callback for the signal SelfContactChanged.

#### Parameters

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

### tp_cli_connection_connect_to_self_contact_changed ()

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

Connect a handler to the signal SelfContactChanged.

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

#### Parameters

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.

#### Parameters

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 (TpConnectionStatus) |
arg_Reason | An integer indicating the reason for the status change, as defined by ConnectionStatusReason (TpConnectionStatusReason) |
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.

#### Parameters

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.

#### Parameters

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.Error.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>server-message (s)</dt> <dd>A human-readable message from the server explaining what happened. This may be in the user's native language, or in the server operator's native language, or even in Lojban.</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>

#### Parameters

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

    TpProxyPendingCall *
    tp_cli_connection_call_add_client_interest
                                   (TpConnection *proxy,
                                    gint timeout_ms,
                                    const gchar **in_Tokens,
                                    tp_cli_connection_callback_for_add_client_interest callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object);

Start a AddClientInterest method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Register a client's interest in notifications related to one or more interfaces.</p> <p>Groups of notifications are identified by a token which is either a D-Bus interface name, or a string that starts with a D-Bus interface name. The meaning of each token is given by that D-Bus interface, which MUST define it in its documentation.</p> <tp:rationale> <p>Initially, all interests are in entire interface, but allowing other strings allows subscription to part of an interface; for instance, an interest in ...MailNotification/count could track the number of messages without caring about their detailed content.</p> </tp:rationale> <p>For each token with which this method interacts, the Connection tracks an &quot;interest count&quot; (like a reference count) for each unique bus name that has called this method. When a client calls this method, for each token, the interest count for its unique bus name is incremented; when <tp:member-ref>RemoveClientInterest</tp:member-ref> is called, all interest counts for that unique bus name are decremented. If the unique bus name leaves the bus (for instance, if the client crashes or exits), all interest counts for that unique bus name are set to zero.</p> <p>The Connection can then use these reference counts to avoid subscribing to protocol-level notifications unless at least one client has a non-zero interest count for the relevant token.</p> <tp:rationale> <p>This method exists to reduce memory and network overhead when there is no active subscription.</p> <p>One situation where this is useful is <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">Location</tp:dbus-ref>: on XMPP, location updates are received over PEP. If the Connection advertises the <code>geoloc+notify</code> capability, it will be sent location updates for all contacts. To avoid consuming resources for this, the connection should avoid advertising that capability until a client has expressed an interest in contacts' locations.</p> <p>Another example of a protocol that benefits from this method is the Google XMPP Mail Notification extension, which can be used to implement <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">MailNotification</tp:dbus-ref>. In this protocol, the CM receives a notification that something has changed, but to get more information, the CM must request this information. Knowing that nobody is currently interested in this information, the CM can avoid generating useless network traffic. Similarly, the CM may free the list of unread messages to reduce memory overhead.</p> </tp:rationale> <p>If this method is called for an interface that might require protocol-level subscription, but the connection cannot set up that subscription yet (for instance because the <tp:member-ref>Status</tp:member-ref> is not Connected yet), the Connection MUST remember the client's interest, and attempt to subscribe to the appropriate protocol feature when this becomes possible.</p> <p>Clients MAY ignore any errors raised by this method; it is intended to be called with the reply ignored.</p> <tp:rationale> <p>The only reason it could fail is if it's unimplemented, in which case the only thing the client can usefully do is to proceed as if it had succeeded.</p> </tp:rationale>

#### Parameters

proxy | the TpProxy |
timeout_ms | the timeout in milliseconds, or -1 to use the default |
in_Tokens | Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Interfaces or parts of interfaces in which to register an interest, represented by either a <tp:type>DBus_Interface</tp:type>, or a string prefixed with a <tp:type>DBus_Interface</tp:type>.</p> <p>If the Connection does not support one of these tokens, this is not considered to be an error; the unsupported token is simply ignored.</p> |
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_call_remove_client_interest ()

    TpProxyPendingCall *
    tp_cli_connection_call_remove_client_interest
                                   (TpConnection *proxy,
                                    gint timeout_ms,
                                    const gchar **in_Tokens,
                                    tp_cli_connection_callback_for_remove_client_interest callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object);

Start a RemoveClientInterest method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Release an interest registered using <tp:member-ref>AddClientInterest</tp:member-ref>. See that method's documentation for details.</p> <p>Clients MAY ignore any errors raised by this method; it is intended to be called with the reply ignored.</p> <tp:rationale> <p>The only reasons it could fail are if it's unimplemented, or if the client's reference-counting is wrong and it has tried to remove a client interest that it did not add. In both cases, there's nothing the client could do about it.</p> </tp:rationale>

#### Parameters

proxy | the TpProxy |
timeout_ms | the timeout in milliseconds, or -1 to use the default |
in_Tokens | Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Interfaces or parts of interfaces that were previously passed to <tp:member-ref>AddClientInterest</tp:member-ref>.</p> |
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_callback_for_add_client_interest ()

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

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

#### Parameters

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

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

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

#### Parameters

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 |

## Types and Values

### struct TpConnection

    struct 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

### struct TpConnectionClass

    struct TpConnectionClass {
        TpProxyClass parent_class;
    };

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

#### Members

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
- “self-contact” is non-`NULL`
- 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. For connections associated with a TpAccount, the account manager service is responsible for doing that, but if you are constructing connections directly (e.g. if you are implementing an account manager), you must `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_dup_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_FEATURE_BALANCE

    #define             TP_CONNECTION_FEATURE_BALANCE

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

When this feature is prepared, the Balance.AccountBalance and Balance.ManageCreditURI properties of the Connection have been retrieved. In particular, the `TpConnection`:balance, `TpConnection`:balance-scale, `TpConnection`:balance-currency and `TpConnection`:balance-uri properties have been set and the TpConnection::balance-changed: will be emitted when they are changed.

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

Since: 0.15.1

### TP_CONNECTION_FEATURE_CONTACT_LIST

    #define             TP_CONNECTION_FEATURE_CONTACT_LIST

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

When this feature is prepared, the `TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES` has been prepared, so the contact list properties of the Connection has been retrieved. If “contact-list-state” is `TP_CONTACT_LIST_STATE_SUCCESS`, all TpContact objects will also be created and prepared with the desired features. See `tp_connection_dup_contact_list()` to get the list of contacts, and `tp_simple_client_factory_add_contact_features()` to define which features needs to be prepared on them.

This feature will fail to prepare when using obsolete Telepathy connection managers which do not implement the ContactList interface.

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

Since: 0.15.5

### TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES

    #define             TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES

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

When this feature is prepared, the contact list properties of the Connection has been retrieved. This feature will fail to prepare when using obsolete Telepathy connection managers which do not implement the ContactList interface.

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

Since: 0.17.0

### TP_CONNECTION_FEATURE_CONTACT_GROUPS

    #define             TP_CONNECTION_FEATURE_CONTACT_GROUPS

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

When this feature is prepared, the contact groups properties of the Connection has been retrieved.

See “contact-groups” to get the list of groups a contact is member of.

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

Since: 0.15.5

### TP_CONNECTION_FEATURE_CONTACT_BLOCKING

    #define             TP_CONNECTION_FEATURE_CONTACT_BLOCKING

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

When this feature is prepared, “blocked-contacts” will contain an up-to-date list of TpContacts the user has blocked, and “can-report-abusive” will indicate whether abusive contacts can be reported to the server administrator.

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

Since: 0.17.0

### TP_CONNECTION_FEATURE_ALIASING

    #define             TP_CONNECTION_FEATURE_ALIASING

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

This feature needs to be prepared in order to use `tp_connection_can_set_contact_alias()`.

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

Since: 0.17.3

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

    #define TP_TYPE_AVATAR_REQUIREMENTS (tp_avatar_requirements_get_type ())

The boxed type of a TpAvatarRequirements.

Since: 0.11.4

### struct TpAvatarRequirements

    struct TpAvatarRequirements {
      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;
    };

The requirements for setting an avatar on a particular protocol.

#### Members

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

### struct TpContactInfoFieldSpec

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

A struct describing a vCard field.

#### Members

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_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

### struct TpContactInfoField

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

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

#### Members

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_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

## Property Details

### The `“balance”` property

      “balance”                  gint

The Amount field of the Balance.AccountBalance property.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_BALANCE`.

See Also: `tp_connection_get_balance()`

Owner: TpConnection

Flags: Read

Default value: 0

### The `“balance-currency”` property

      “balance-currency”         gchar *

The Currency field of the Balance.AccountBalance property.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_BALANCE`.

See Also: `tp_connection_get_balance()`

Owner: TpConnection

Flags: Read

Default value: NULL

### The `“balance-scale”` property

      “balance-scale”            guint

The Scale field of the Balance.AccountBalance property.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_BALANCE`.

See Also: `tp_connection_get_balance()`

Owner: TpConnection

Flags: Read

Default value: 4294967295

### The `“balance-uri”` property

      “balance-uri”              gchar *

The Balance.ManageCreditURI property.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_BALANCE`.

Owner: TpConnection

Flags: Read

Default value: NULL

### The `“blocked-contacts”` property

      “blocked-contacts”         GPtrArray *

A GPtrArray of blocked TpContact. Changes are notified using the “blocked-contacts-changed” signal.

These TpContact objects have been prepared with the desired features. See `tp_simple_client_factory_add_contact_features()` to define which features needs to be prepared on them.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_BLOCKING`.

Owner: TpConnection

Flags: Read

Since: 0.17.0

### The `“can-change-contact-list”` property

      “can-change-contact-list”  gboolean

If true, presence subscription and publication can be changed using the RequestSubscription, AuthorizePublication and RemoveContacts methods.

Rational: link-local XMPP, presence is implicitly published to everyone in the local subnet, so the user cannot control their presence publication.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES` or `TP_CONNECTION_FEATURE_CONTACT_LIST`.

Owner: TpConnection

Flags: Read

Default value: FALSE

Since: 0.15.5

### The `“can-report-abusive”` property

      “can-report-abusive”       gboolean

If this property is `TRUE`, contacts may be reported as abusive to the server administrators by setting report_abusive to `TRUE` when calling `tp_connection_block_contacts_async()`.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_BLOCKING`.

Owner: TpConnection

Flags: Read

Default value: FALSE

Since: 0.17.0

### The `“capabilities”` property

      “capabilities”             TpCapabilities *

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

Owner: TpConnection

Flags: Read

### The `“cm-name”` property

      “cm-name”                  gchar *

This connection's connection manager name.

Owner: TpConnection

Flags: Read

Default value: NULL

Since: 0.19.3

### The `“connection-manager-name”` property

      “connection-manager-name”  gchar *

This connection's connection manager name.

`TpConnection:connection-manager-name` is deprecated and should not be used in newly-written code.

Use “cm-name” instead.

Owner: TpConnection

Flags: Read

Default value: NULL

Since: 0.13.16

### The `“connection-ready”` property

      “connection-ready”         gboolean

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.

`TpConnection:connection-ready` has been deprecated since version 0.17.6 and should not be used in newly-written code.

use `tp_proxy_is_prepared()` with `TP_CHANNEL_FEATURE_CONNECTED` for checks, or `tp_proxy_prepare_async()` for notification

Owner: TpConnection

Flags: Read

Default value: FALSE

### The `“contact-groups”` property

      “contact-groups”           GStrv

The names of all groups that currently exist. This may be a larger set than the union of all “contact-groups” properties, if the connection allows groups to be empty.

This property's value is not meaningful until the “contact-list-state” property has become `TP_CONTACT_LIST_STATE_SUCCESS`.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_GROUPS`.

Owner: TpConnection

Flags: Read

Since: 0.15.5

### The `“contact-list-persists”` property

      “contact-list-persists”    gboolean

If true, presence subscriptions (in both directions) on this connection are stored by the server or other infrastructure.

If false, presence subscriptions on this connection are not stored.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES` or `TP_CONNECTION_FEATURE_CONTACT_LIST`.

Owner: TpConnection

Flags: Read

Default value: FALSE

Since: 0.15.5

### The `“contact-list-state”` property

      “contact-list-state”       guint

The progress made in retrieving the contact list.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES` or `TP_CONNECTION_FEATURE_CONTACT_LIST`.

Owner: TpConnection

Flags: Read

Default value: 0

Since: 0.15.5

### The `“disjoint-groups”` property

      “disjoint-groups”          gboolean

True if each contact can be in at most one group; false if each contact can be in many groups.

This property cannot change after the connection has moved to the `TP_CONNECTION_STATUS_CONNECTED` state. Until then, its value is undefined, and it may change at any time, without notification.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_GROUPS`.

Owner: TpConnection

Flags: Read

Default value: FALSE

Since: 0.15.5

### The `“group-storage”` property

      “group-storage”            guint

Indicates the extent to which contacts' groups can be set and stored.

This property cannot change after the connection has moved to the `TP_CONNECTION_STATUS_CONNECTED` state. Until then, its value is undefined, and it may change at any time, without notification.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_GROUPS`.

Owner: TpConnection

Flags: Read

Default value: 0

Since: 0.15.5

### The `“protocol-name”` property

      “protocol-name”            gchar *

The connection's machine-readable protocol name, such as "jabber", "msn" or "local-xmpp". Recommended names for most protocols can be found in the Telepathy D-Bus Interface Specification.

Owner: TpConnection

Flags: Read

Default value: NULL

Since: 0.13.16

### The `“request-uses-message”` property

      “request-uses-message”     gboolean

If true, the Message parameter to RequestSubscription is likely to be significant, and user interfaces SHOULD prompt the user for a message to send with the request; a message such as "I would like to add you to my contact list", translated into the local user's language, might make a suitable default.

For this property to be valid, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_LIST_PROPERTIES` or `TP_CONNECTION_FEATURE_CONTACT_LIST`.

Owner: TpConnection

Flags: Read

Default value: FALSE

Since: 0.15.5

### The `“self-contact”` property

      “self-contact”             TpContact *

A TpContact representing the local user on this connection, or `NULL` if not yet available.

If the local user's unique identifier changes (for instance by using /nick on IRC), this property will change to a different TpContact object representing the new identifier, and “notify” will be emitted.

The TpContact object is guaranteed to have all of the features previously passed to `tp_simple_client_factory_add_contact_features()` prepared.

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

Owner: TpConnection

Flags: Read

Since: 0.13.9

### The `“self-handle”` property

      “self-handle”              guint

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.

This may change if the local user's unique identifier changes (for instance by using /nick on IRC), in which case “notify” will be emitted.

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

`TpConnection:self-handle` is deprecated and should not be used in newly-written code.

Use “self-contact” instead.

Owner: TpConnection

Flags: Read

Default value: 0

### The `“status”` property

      “status”                   guint

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.

Owner: TpConnection

Flags: Read

Default value: 4294967295

### The `“status-reason”` property

      “status-reason”            guint

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.

Owner: TpConnection

Flags: Read

Default value: 0

## Signal Details

### The `“balance-changed”` signal

    void
    user_function (TpConnection *self,
                   gint          balance,
                   guint         balance_scale,
                   gchar        *balance_currency,
                   gpointer      user_data)

Emitted when at least one of the “balance”, “balance-scale” or “balance-currency” property is changed.

For this signal to be emitted, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_BALANCE`.

#### Parameters

self | a channel |
balance | the value of the “balance” property |
balance_scale | the value of the “balance-scale” property |
balance_currency | the value of the “balance-currency” property |
user_data | user data set when the signal handler was connected. |

Flags: Has Details

Since: 0.15.1

### The `“blocked-contacts-changed”` signal

    void
    user_function (TpConnection *self,
                   GPtrArray    *added,
                   GPtrArray    *removed,
                   gpointer      user_data)

Notify of changes in “blocked-contacts”. It is guaranteed that all contacts have desired features prepared. See `tp_simple_client_factory_add_contact_features()` to define which features needs to be prepared.

This signal is also emitted for the initial set of blocked contacts once retrieved.

For this signal to be emitted, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_BLOCKING`.

#### Parameters

self | a TpConnection |
added | a GPtrArray of TpContact which have been blocked. | [type GLib.PtrArray][element-type TelepathyGLib.Contact]
removed | a GPtrArray of TpContact which are no longer blocked. | [type GLib.PtrArray][element-type TelepathyGLib.Contact]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.17.0

### The `“contact-list-changed”` signal

    void
    user_function (TpConnection *self,
                   GPtrArray    *added,
                   GPtrArray    *removed,
                   gpointer      user_data)

Notify of changes in the list of contacts as returned by `tp_connection_dup_contact_list()`. It is guaranteed that all contacts have desired features prepared. See `tp_simple_client_factory_add_contact_features()` to define which features needs to be prepared.

This signal is also emitted for the initial set of contacts once retrieved.

For this signal to be emitted, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_LIST`.

#### Parameters

self | a TpConnection |
added | a GPtrArray of TpContact added to contacts list. | [type GLib.PtrArray][element-type TelepathyGLib.Contact]
removed | a GPtrArray of TpContact removed from contacts list. | [type GLib.PtrArray][element-type TelepathyGLib.Contact]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.15.5

### The `“group-renamed”` signal

    void
    user_function (TpConnection *self,
                   gchar        *old_name,
                   gchar        *new_name,
                   gpointer      user_data)

Emitted when a group is renamed, in protocols where this can be distinguished from group creation, removal and membership changes.

Immediately after this signal is emitted, “groups-created” signal the creation of a group with the new name, and “groups-removed” signal the removal of a group with the old name. If the group was not empty, immediately after those signals are emitted, “contact-groups-changed” signal that the members of that group were removed from the old name and added to the new name.

When this signal is emitted, “contact-groups” property is already updated.

For this signal to be emited, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_GROUPS`.

#### Parameters

self | a TpConnection |
old_name | the old name of the group. |
new_name | the new name of the group. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.15.5

### The `“groups-created”` signal

    void
    user_function (TpConnection *self,
                   GStrv         added,
                   gpointer      user_data)

Emitted when new, empty groups are created. This will often be followed by “contact-groups-changed” signals that add some members. When this signal is emitted, “contact-groups” property is already updated.

For this signal to be emited, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_GROUPS`.

#### Parameters

self | a TpConnection |
added | a GStrv with the names of the new groups. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.15.5

### The `“groups-removed”` signal

    void
    user_function (TpConnection *self,
                   GStrv         added,
                   gpointer      user_data)

Emitted when one or more groups are removed. If they had members at the time that they were removed, then immediately after this signal is emitted, “contact-groups-changed” signals that their members were removed. When this signal is emitted, “contact-groups” property is already updated.

For this signal to be emited, you must first call `tp_proxy_prepare_async()` with the feature `TP_CONNECTION_FEATURE_CONTACT_GROUPS`.

#### Parameters

self | A TpConnection |
added | A GStrv with the names of the groups. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.15.5

## See Also

TpConnectionManager, TpChannel