TpConnectionManager: telepathy-glib API Reference Manual

## TpConnectionManager TpConnectionManager — proxy object for a Telepathy connection manager |

## Functions

void | (*TpConnectionManagerListCb) ()
void | tp_list_connection_managers_async ()
GList * | tp_list_connection_managers_finish ()
void | tp_list_connection_managers ()
TpConnectionManager * | tp_connection_manager_new ()
const gchar * | tp_connection_manager_get_name ()
void | (*TpConnectionManagerWhenReadyCb) ()
void | tp_connection_manager_call_when_ready ()
gboolean | tp_connection_manager_is_ready ()
TpCMInfoSource | tp_connection_manager_get_info_source ()
gboolean | tp_connection_manager_activate ()
gboolean | tp_connection_manager_is_running ()
GList * | tp_connection_manager_dup_protocols ()
gchar ** | tp_connection_manager_dup_protocol_names ()
gboolean | tp_connection_manager_has_protocol ()
const TpConnectionManagerProtocol * | tp_connection_manager_get_protocol ()
TpProtocol * | tp_connection_manager_get_protocol_object ()
gboolean | tp_connection_manager_protocol_can_register ()
gchar ** | tp_connection_manager_protocol_dup_param_names ()
gboolean | tp_connection_manager_protocol_has_param ()
const TpConnectionManagerParam * | tp_connection_manager_protocol_get_param ()
const gchar * | tp_connection_manager_param_get_name ()
const gchar * | tp_connection_manager_param_get_dbus_signature ()
GVariantType * | tp_connection_manager_param_dup_variant_type ()
gboolean | tp_connection_manager_param_is_required ()
gboolean | tp_connection_manager_param_is_required_for_registration ()
gboolean | tp_connection_manager_param_is_secret ()
gboolean | tp_connection_manager_param_is_dbus_property ()
gboolean | tp_connection_manager_param_get_default ()
GVariant * | tp_connection_manager_param_dup_default_variant ()
gboolean | tp_connection_manager_check_valid_name ()
gboolean | tp_connection_manager_check_valid_protocol_name ()
void | tp_connection_manager_init_known_interfaces ()
TpConnectionManagerParam * | tp_connection_manager_param_copy ()
void | tp_connection_manager_param_free ()
TpConnectionManagerProtocol * | tp_connection_manager_protocol_copy ()
void | tp_connection_manager_protocol_free ()
void | (*tp_cli_connection_manager_callback_for_get_parameters) ()
TpProxyPendingCall * | tp_cli_connection_manager_call_get_parameters ()
gboolean | tp_cli_connection_manager_run_get_parameters ()
void | (*tp_cli_connection_manager_callback_for_list_protocols) ()
TpProxyPendingCall * | tp_cli_connection_manager_call_list_protocols ()
gboolean | tp_cli_connection_manager_run_list_protocols ()
void | (*tp_cli_connection_manager_callback_for_request_connection) ()
TpProxyPendingCall * | tp_cli_connection_manager_call_request_connection ()
gboolean | tp_cli_connection_manager_run_request_connection ()
void | (*tp_cli_connection_manager_signal_callback_new_connection) ()
TpProxySignalConnection * | tp_cli_connection_manager_connect_to_new_connection ()

## Properties

gboolean | always-introspect | Read / Write
gchar * | cm-name | Read
gchar * | connection-manager | Read
guint | info-source | Read
gchar * | manager-file | Read / Write / Construct

## Signals

void | activated | Has Details
void | exited | Has Details
void | got-info | Has Details

## Types and Values

struct | TpConnectionManager
struct | TpConnectionManagerClass
#define | TP_CONNECTION_MANAGER_FEATURE_CORE
enum | TpCMInfoSource
#define | TP_TYPE_CM_INFO_SOURCE
struct | TpConnectionManagerProtocol
struct | TpConnectionManagerParam

## Object Hierarchy

        GBoxed
        ├── TpConnectionManagerParam
        ╰── TpConnectionManagerProtocol
        GEnum
        ╰── TpCMInfoSource
        GObject
        ╰── TpProxy
            ╰── TpConnectionManager

## Includes

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

## Description

TpConnectionManager objects represent Telepathy connection managers. They can be used to open connections.

## Functions

### TpConnectionManagerListCb ()

    void
    (*TpConnectionManagerListCb) (TpConnectionManager * const *cms,
                                  gsize n_cms,
                                  const GError *error,
                                  gpointer user_data,
                                  GObject *weak_object);

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

Since 0.11.3, `tp_list_connection_managers()` will wait for `TP_CONNECTION_MANAGER_FEATURE_CORE` to be prepared on each connection manager passed to `callback` , unless an error occurred while launching that connection manager.

#### Parameters

cms | `NULL`-terminated array of TpConnectionManager (the objects will be unreferenced and the array will be freed after the callback returns, so the callback must reference any CMs it stores a pointer to), or `NULL` on error. | [array zero-terminated=1]
n_cms | number of connection managers in `cms` (not including the final `NULL`) |
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_managers_async ()

    void
    tp_list_connection_managers_async (TpDBusDaemon *dbus_daemon,
                                       GAsyncReadyCallback callback,
                                       gpointer user_data);

List the available (running or installed) connection managers, asynchronously, and wait for their `TP_CONNECTION_MANAGER_FEATURE_CORE` feature to be ready.

#### Parameters

dbus_daemon | a TpDBusDaemon, or `NULL` to use `tp_dbus_daemon_dup()`. | [allow-none]
callback | a callback to call with a list of CMs |
user_data | data to pass to `callback` |

Since: 0.17.6

### tp_list_connection_managers_finish ()

    GList *
    tp_list_connection_managers_finish (GAsyncResult *result,
                                        GError **error);

Finish listing the available connection managers.

Free the list after use, for instance with `g_list_free_full (list, g_object_unref)`.

#### Parameters

result | the result of `tp_list_connection_managers_async()` |
error | used to raise an error if the operation failed |

#### Returns

a newly allocated list of references to TpConnectionManager objects.

[transfer full][element-type TelepathyGLib.ConnectionManager]

Since: 0.17.6

### tp_list_connection_managers ()

    void
    tp_list_connection_managers (TpDBusDaemon *bus_daemon,
                                 TpConnectionManagerListCb callback,
                                 gpointer user_data,
                                 GDestroyNotify destroy,
                                 GObject *weak_object);

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

since 0.19.1, use `tp_list_connection_managers_async()`

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

Since 0.7.26, this function will wait for each TpConnectionManager to be ready, so all connection managers passed to `callback` will have their `TP_CONNECTION_MANAGER_FEATURE_CORE` feature prepared, unless an error occurred while launching that connection manager.

#### Parameters

bus_daemon | proxy for the D-Bus daemon |
callback | callback to be called when listing the CMs succeeds or fails; not called 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 `weak_object` goes away |
weak_object | if not `NULL`, will be weakly referenced; the callback will not be called, and the call will be cancelled, if the object has vanished. | [allow-none]

Since: 0.7.1

### tp_connection_manager_new ()

    TpConnectionManager *
    tp_connection_manager_new (TpDBusDaemon *dbus,
                               const gchar *name,
                               const gchar *manager_filename,
                               GError **error);

Convenience function to create a new connection manager proxy. If its protocol and parameter information are required, you should call `tp_proxy_prepare_async()` on the result.

#### Parameters

dbus | Proxy for the D-Bus daemon |
name | The connection manager name (such as "gabble") |
manager_filename | The “manager-file” property, which may (and generally should) be `NULL`. | [allow-none]
error | used to return an error if `NULL` is returned |

#### Returns

a new reference to a connection manager proxy, or `NULL` if `error` is set.

### tp_connection_manager_get_name ()

    const gchar *
    tp_connection_manager_get_name (TpConnectionManager *self);

Return the internal name of this connection manager in the Telepathy D-Bus API, e.g. "gabble" or "haze". This is often the name of the binary without the "telepathy-" prefix.

The returned string is valid as long as `self` is. Copy it with `g_strdup()` if a longer lifetime is required.

#### Parameters

self | a connection manager |

#### Returns

the “cm-name” property

Since: 0.7.26

### TpConnectionManagerWhenReadyCb ()

    void
    (*TpConnectionManagerWhenReadyCb) (TpConnectionManager *cm,
                                       const GError *error,
                                       gpointer user_data,
                                       GObject *weak_object);

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

since 0.17.6, use `tp_proxy_prepare_async()` instead

Called as the result of `tp_connection_manager_call_when_ready()`. If the connection manager's protocol and parameter information could be retrieved, `error` is `NULL` and `cm` is considered to be ready. Otherwise, `error` is non-`NULL` and `cm` is not ready.

#### Parameters

cm | a connection manager |
error | `NULL` on success, or the reason why `tp_connection_manager_is_ready()` would return `FALSE` |
user_data | the `user_data` passed to `tp_connection_manager_call_when_ready()` |
weak_object | the `weak_object` passed to `tp_connection_manager_call_when_ready()` |

### tp_connection_manager_call_when_ready ()

    void
    tp_connection_manager_call_when_ready (TpConnectionManager *self,
                                           TpConnectionManagerWhenReadyCb callback,
                                           gpointer user_data,
                                           GDestroyNotify destroy,
                                           GObject *weak_object);

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

since 0.17.6, use `tp_proxy_prepare_async()` instead

Call the `callback` from the main loop when information about `cm` 's supported protocols and parameters has been retrieved.

[skip]

#### Parameters

self | a connection manager |
callback | callback to call when information has been retrieved or on error |
user_data | arbitrary data to pass to the callback |
destroy | called to destroy `user_data` |
weak_object | object to reference weakly; if it is destroyed, `callback` will not be called, but `destroy` will still be called |

Since: 0.7.26

### tp_connection_manager_is_ready ()

    gboolean
    tp_connection_manager_is_ready (TpConnectionManager *self);

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

since 0.17.6, use `tp_proxy_is_prepared()` with `TP_CONNECTION_MANAGER_FEATURE_CORE` instead

If protocol and parameter information has been obtained from the connection manager or the cache in the .manager file, return `TRUE`. Otherwise, return `FALSE`.

This may change from `FALSE` to `TRUE` at any time that the main loop is running; the “notify” signal is emitted for the “info-source” property.

[skip]

#### Parameters

self | a connection manager |

#### Returns

`TRUE`, unless the “info-source” property is `TP_CM_INFO_SOURCE_NONE`

Since: 0.7.26

### tp_connection_manager_get_info_source ()

    TpCMInfoSource
    tp_connection_manager_get_info_source (TpConnectionManager *self);

If protocol and parameter information has been obtained from the connection manager, return `TP_CM_INFO_SOURCE_LIVE`; if it has been obtained from the cache in the .manager file, return `TP_CM_INFO_SOURCE_FILE`. If this information has not yet been obtained, or obtaining it failed, return `TP_CM_INFO_SOURCE_NONE`.

This may increase at any time that the main loop is running; the “notify” signal is emitted.

#### Parameters

self | a connection manager |

#### Returns

the value of the “info-source” property

Since: 0.7.26

### tp_connection_manager_activate ()

    gboolean
    tp_connection_manager_activate (TpConnectionManager *self);

Attempt to run and introspect the connection manager, asynchronously. Since 0.7.26 this function is not generally very useful, since the connection manager will now be activated automatically if necessary.

If the CM was already running, do nothing and return `FALSE`.

On success, emit “activated” when the CM appears on the bus, and “got-info” when its capabilities have been (re-)discovered.

On failure, emit “exited” without first emitting activated.

[skip]

#### Parameters

self | a connection manager proxy |

#### Returns

`TRUE` if activation was needed and is now in progress, `FALSE` if the connection manager was already running and no additional signals will be emitted.

Since: 0.7.1

### tp_connection_manager_is_running ()

    gboolean
    tp_connection_manager_is_running (TpConnectionManager *self);

Return `TRUE` if this connection manager currently appears to be running. This may change at any time that the main loop is running; the “activated” and “exited” signals are emitted.

#### Parameters

self | a connection manager |

#### Returns

whether the connection manager is currently running

Since: 0.7.26

### tp_connection_manager_dup_protocols ()

    GList *
    tp_connection_manager_dup_protocols (TpConnectionManager *self);

Return objects representing all protocols supported by this connection manager.

If this function is called before the connection manager information has been obtained, the result is always `NULL`. Use `tp_proxy_prepare_async()` to wait for this.

The caller must free the list, for instance with `g_list_free_full (l, g_object_unref)`.

#### Parameters

self | a connection manager |

#### Returns

a list of TpProtocol objects representing the protocols supported by `self` , owned by the caller.

[transfer full][element-type TelepathyGLib.Protocol]

Since: 0.17.6

### tp_connection_manager_dup_protocol_names ()

    gchar **
    tp_connection_manager_dup_protocol_names
                                   (TpConnectionManager *self);

Returns a list of protocol names supported by this connection manager. These are the internal protocol names used by the Telepathy specification (e.g. "jabber" and "msn"), rather than user-visible names in any particular locale.

If this function is called before the connection manager information has been obtained, the result is always `NULL`. Use `tp_proxy_prepare_async()` to wait for this.

The result is copied and must be freed by the caller, but it is not necessarily still true after the main loop is re-entered.

#### Parameters

self | a connection manager |

#### Returns

a GStrv of protocol names.

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

Since: 0.7.26

### tp_connection_manager_has_protocol ()

    gboolean
    tp_connection_manager_has_protocol (TpConnectionManager *self,
                                        const gchar *protocol);

Return whether `protocol` is supported by this connection manager.

If this function is called before the connection manager information has been obtained, the result is always `FALSE`. Use `tp_proxy_prepare_async()` to wait for this.

#### Parameters

self | a connection manager |
protocol | the name of a protocol as defined in the Telepathy D-Bus API, e.g. "jabber" or "msn" |

#### Returns

`TRUE` if this connection manager supports `protocol`

Since: 0.7.26

### tp_connection_manager_get_protocol ()

    const TpConnectionManagerProtocol *
    tp_connection_manager_get_protocol (TpConnectionManager *self,
                                        const gchar *protocol);

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

, use `tp_connection_manager_get_protocol_object()`

Returns a structure representing a protocol, or `NULL` if this connection manager does not support the specified protocol.

Since 0.11.11, you can get a GObject version with more functionality by calling `tp_connection_manager_get_protocol_object()`.

If this function is called before the connection manager information has been obtained, the result is always `NULL`. Use `tp_proxy_prepare_async()` to wait for this.

The result is not necessarily valid after the main loop is re-entered. Since 0.11.3, it can be copied with `tp_connection_manager_protocol_copy()` if a permanently-valid copy is needed.

#### Parameters

self | a connection manager |
protocol | the name of a protocol as defined in the Telepathy D-Bus API, e.g. "jabber" or "msn" |

#### Returns

a structure representing the protocol.

[transfer none]

Since: 0.7.26

### tp_connection_manager_get_protocol_object ()

    TpProtocol *
    tp_connection_manager_get_protocol_object
                                   (TpConnectionManager *self,
                                    const gchar *protocol);

Returns an object representing a protocol, or `NULL` if this connection manager does not support the specified protocol.

If this function is called before the connection manager information has been obtained, the result is always `NULL`. Use `tp_proxy_prepare_async()` to wait for this.

The result should be referenced with `g_object_ref()` if it will be kept.

#### Parameters

self | a connection manager |
protocol | the name of a protocol as defined in the Telepathy D-Bus API, e.g. "jabber" or "msn" |

#### Returns

an object representing the protocol, or `NULL`.

[transfer none]

Since: 0.11.11

### tp_connection_manager_protocol_can_register ()

    gboolean
    tp_connection_manager_protocol_can_register
                                   (const TpConnectionManagerProtocol *protocol);

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

, use TpProtocol objects instead

Return whether a new account can be registered on this protocol, by setting the special "register" parameter to `TRUE`.

#### Parameters

protocol | structure representing a supported protocol |

#### Returns

`TRUE` if `protocol` supports the parameter "register"

Since: 0.7.26

### tp_connection_manager_protocol_dup_param_names ()

    gchar **
    tp_connection_manager_protocol_dup_param_names
                                   (const TpConnectionManagerProtocol *protocol);

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

, use TpProtocol objects instead

Returns a list of parameter names supported by this connection manager for this protocol.

The result is copied and must be freed by the caller with `g_strfreev()`.

#### Parameters

protocol | a protocol supported by a TpConnectionManager |

#### Returns

a GStrv of protocol names.

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

Since: 0.7.26

### tp_connection_manager_protocol_has_param ()

    gboolean
    tp_connection_manager_protocol_has_param
                                   (const TpConnectionManagerProtocol *protocol,
                                    const gchar *param);

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

, use TpProtocol objects instead

#### Parameters

protocol | structure representing a supported protocol |
param | a parameter name |

#### Returns

`TRUE` if `protocol` supports the parameter `param` .

Since: 0.7.26

### tp_connection_manager_protocol_get_param ()

    const TpConnectionManagerParam *
    tp_connection_manager_protocol_get_param
                                   (const TpConnectionManagerProtocol *protocol,
                                    const gchar *param);

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

, use TpProtocol objects instead

#### Parameters

protocol | structure representing a supported protocol |
param | a parameter name |

#### Returns

a structure representing the parameter `param` , or `NULL` if not supported

Since: 0.7.26

### tp_connection_manager_param_get_name ()

    const gchar *
    tp_connection_manager_param_get_name (const TpConnectionManagerParam *param);

#### Parameters

param | a parameter supported by a TpConnectionManager |

#### Returns

the name of the parameter

Since: 0.7.26

### tp_connection_manager_param_get_dbus_signature ()

    const gchar *
    tp_connection_manager_param_get_dbus_signature
                                   (const TpConnectionManagerParam *param);

#### Parameters

param | a parameter supported by a TpConnectionManager |

#### Returns

the D-Bus signature of the parameter

Since: 0.7.26

### tp_connection_manager_param_dup_variant_type ()

    GVariantType *
    tp_connection_manager_param_dup_variant_type
                                   (const TpConnectionManagerParam *param);

#### Parameters

param | a parameter supported by a TpConnectionManager |

#### Returns

the GVariantType of the parameter.

[transfer full]

Since: 0.23.1

### tp_connection_manager_param_is_required ()

    gboolean
    tp_connection_manager_param_is_required
                                   (const TpConnectionManagerParam *param);

#### Parameters

param | a parameter supported by a TpConnectionManager |

#### Returns

`TRUE` if the parameter is normally required

Since: 0.7.26

### tp_connection_manager_param_is_required_for_registration ()

    gboolean
    tp_connection_manager_param_is_required_for_registration
                                   (const TpConnectionManagerParam *param);

#### Parameters

param | a parameter supported by a TpConnectionManager |

#### Returns

`TRUE` if the parameter is required when registering a new account (by setting the special "register" parameter to `TRUE`)

Since: 0.7.26

### tp_connection_manager_param_is_secret ()

    gboolean
    tp_connection_manager_param_is_secret (const TpConnectionManagerParam *param);

#### Parameters

param | a parameter supported by a TpConnectionManager |

#### Returns

`TRUE` if the parameter's value is a password or other secret

Since: 0.7.26

### tp_connection_manager_param_is_dbus_property ()

    gboolean
    tp_connection_manager_param_is_dbus_property
                                   (const TpConnectionManagerParam *param);

#### Parameters

param | a parameter supported by a TpConnectionManager |

#### Returns

`TRUE` if the parameter represents a D-Bus property of the same name

Since: 0.7.26

### tp_connection_manager_param_get_default ()

    gboolean
    tp_connection_manager_param_get_default
                                   (const TpConnectionManagerParam *param,
                                    GValue *value);

Get the default value for this parameter, if there is one. If `FALSE` is returned, `value` is left uninitialized.

#### Parameters

param | a parameter supported by a TpConnectionManager |
value | pointer to an unset (all zeroes) GValue into which the default's type and value are written |

#### Returns

`TRUE` if there is a default value

Since: 0.7.26

### tp_connection_manager_param_dup_default_variant ()

    GVariant *
    tp_connection_manager_param_dup_default_variant
                                   (const TpConnectionManagerParam *param);

Get the default value for this parameter.

Use `g_variant_get_type()` to check that the type is what you expect. For instance, a string parameter should have type `G_VARIANT_TYPE_STRING`.

#### Parameters

param | a parameter supported by a TpConnectionManager |

#### Returns

the default value, or `NULL` if there is no default

Since: 0.19.0

### tp_connection_manager_check_valid_name ()

    gboolean
    tp_connection_manager_check_valid_name
                                   (const gchar *name,
                                    GError **error);

Check that the given string is a valid connection manager name, i.e. that it consists entirely of ASCII letters, digits and underscores, and starts with a letter.

#### Parameters

name | a possible connection manager name |
error | used to raise `TP_ERROR_INVALID_ARGUMENT` if `FALSE` is returned |

#### Returns

`TRUE` if `name` is valid

Since: 0.7.1

### tp_connection_manager_check_valid_protocol_name ()

    gboolean
    tp_connection_manager_check_valid_protocol_name
                                   (const gchar *name,
                                    GError **error);

Check that the given string is a valid protocol name, i.e. that it consists entirely of ASCII letters, digits and hyphen/minus, and starts with a letter.

#### Parameters

name | a possible protocol name |
error | used to raise `TP_ERROR_INVALID_ARGUMENT` if `FALSE` is returned |

#### Returns

`TRUE` if `name` is valid

Since: 0.7.1

### tp_connection_manager_init_known_interfaces ()

    void
    tp_connection_manager_init_known_interfaces
                                   (void);

Ensure that the known interfaces for TpConnectionManager 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_MANAGER`.

Since: 0.7.32

### tp_connection_manager_param_copy ()

    TpConnectionManagerParam *
    tp_connection_manager_param_copy (const TpConnectionManagerParam *in);

#### Parameters

in | the TpConnectionManagerParam to copy |

#### Returns

a newly (slice) allocated TpConnectionManagerParam, free with `tp_connection_manager_param_free()`

Since: 0.11.3

### tp_connection_manager_param_free ()

    void
    tp_connection_manager_param_free (TpConnectionManagerParam *param);

Frees `param` , which was copied with `tp_connection_manager_param_copy()`.

#### Parameters

param | the TpConnectionManagerParam to free |

Since: 0.11.3

### tp_connection_manager_protocol_copy ()

    TpConnectionManagerProtocol *
    tp_connection_manager_protocol_copy (const TpConnectionManagerProtocol *in);

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

, use TpProtocol objects instead

#### Parameters

in | the TpConnectionManagerProtocol to copy |

#### Returns

a newly (slice) allocated TpConnectionManagerProtocol, free with `tp_connection_manager_protocol_free()`

Since: 0.11.3

### tp_connection_manager_protocol_free ()

    void
    tp_connection_manager_protocol_free (TpConnectionManagerProtocol *proto);

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

, use TpProtocol objects instead

Frees `proto` , which was copied with `tp_connection_manager_protocol_copy()`.

#### Parameters

proto | the TpConnectionManagerProtocol to free |

Since: 0.11.3

### tp_cli_connection_manager_callback_for_get_parameters ()

    void
    (*tp_cli_connection_manager_callback_for_get_parameters)
                                   (TpConnectionManager *proxy,
                                    const GPtrArray *out_Parameters,
                                    const GError *error,
                                    gpointer user_data,
                                    GObject *weak_object);

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

#### Parameters

proxy | the proxy on which the call was made |
out_Parameters | Used to return an 'out' argument if `error` is `NULL`: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structs representing possible parameters. |
error | `NULL` on success, or an error on failure |
user_data | user-supplied data |
weak_object | user-supplied object |

### tp_cli_connection_manager_call_get_parameters ()

    TpProxyPendingCall *
    tp_cli_connection_manager_call_get_parameters
                                   (TpConnectionManager *proxy,
                                    gint timeout_ms,
                                    const gchar *in_Protocol,
                                    tp_cli_connection_manager_callback_for_get_parameters callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object);

Start a GetParameters method call.

Get a list of the parameters which may be specified in the <tp:dbus-ref namespace="ofdT.Account">Parameters</tp:dbus-ref> of an <tp:dbus-ref namespace="ofdT">Account</tp:dbus-ref> (or, for specialised applications which do not use the account manager, passed to <tp:member-ref>RequestConnection</tp:member-ref>). Some parameters are mandatory, and some parameters only make sense when registering new accounts with the server; see the <tp:type>Param_Spec</tp:type> documentation for more details.

#### Parameters

proxy | the TpProxy |
timeout_ms | the timeout in milliseconds, or -1 to use the default |
in_Protocol | Used to pass an 'in' argument: The required protocol name |
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_manager_run_get_parameters ()

    gboolean
    tp_cli_connection_manager_run_get_parameters
                                   (TpConnectionManager *proxy,
                                    gint timeout_ms,
                                    const gchar *in_Protocol,
                                    GPtrArray **out_Parameters,
                                    GError **error,
                                    GMainLoop **loop);

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

Call the method GetParameters 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 a list of the parameters which may be specified in the <tp:dbus-ref namespace="ofdT.Account">Parameters</tp:dbus-ref> of an <tp:dbus-ref namespace="ofdT">Account</tp:dbus-ref> (or, for specialised applications which do not use the account manager, passed to <tp:member-ref>RequestConnection</tp:member-ref>). Some parameters are mandatory, and some parameters only make sense when registering new accounts with the server; see the <tp:type>Param_Spec</tp:type> documentation for more details.

#### Parameters

proxy | A TpConnectionManager or subclass |
timeout_ms | Timeout in milliseconds, or -1 for default |
in_Protocol | Used to pass an 'in' argument: The required protocol name |
out_Parameters | Used to return an 'out' argument if `TRUE` is returned: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> An array of structs representing possible parameters. |
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_manager_callback_for_list_protocols ()

    void
    (*tp_cli_connection_manager_callback_for_list_protocols)
                                   (TpConnectionManager *proxy,
                                    const gchar **out_Protocols,
                                    const GError *error,
                                    gpointer user_data,
                                    GObject *weak_object);

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

#### Parameters

proxy | the proxy on which the call was made |
out_Protocols | Used to return an 'out' argument if `error` is `NULL`: The keys of the <tp:member-ref>Protocols</tp:member-ref> map. |
error | `NULL` on success, or an error on failure |
user_data | user-supplied data |
weak_object | user-supplied object |

### tp_cli_connection_manager_call_list_protocols ()

    TpProxyPendingCall *
    tp_cli_connection_manager_call_list_protocols
                                   (TpConnectionManager *proxy,
                                    gint timeout_ms,
                                    tp_cli_connection_manager_callback_for_list_protocols callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object);

Start a ListProtocols method call.

Get a list of protocol identifiers that are implemented by this connection manager.

#### 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_manager_run_list_protocols ()

    gboolean
    tp_cli_connection_manager_run_list_protocols
                                   (TpConnectionManager *proxy,
                                    gint timeout_ms,
                                    gchar ***out_Protocols,
                                    GError **error,
                                    GMainLoop **loop);

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

Call the method ListProtocols 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 a list of protocol identifiers that are implemented by this connection manager.

#### Parameters

proxy | A TpConnectionManager or subclass |
timeout_ms | Timeout in milliseconds, or -1 for default |
out_Protocols | Used to return an 'out' argument if `TRUE` is returned: The keys of the <tp:member-ref>Protocols</tp:member-ref> map. |
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_manager_callback_for_request_connection ()

    void
    (*tp_cli_connection_manager_callback_for_request_connection)
                                   (TpConnectionManager *proxy,
                                    const gchar *out_Bus_Name,
                                    const gchar *out_Object_Path,
                                    const GError *error,
                                    gpointer user_data,
                                    GObject *weak_object);

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

#### Parameters

proxy | the proxy on which the call was made |
out_Bus_Name | Used to return an 'out' argument if `error` is `NULL`: A D-Bus service name where the new Connection object can be found |
out_Object_Path | Used to return an 'out' argument if `error` is `NULL`: The D-Bus object path to the Connection on this service |
error | `NULL` on success, or an error on failure |
user_data | user-supplied data |
weak_object | user-supplied object |

### tp_cli_connection_manager_call_request_connection ()

    TpProxyPendingCall *
    tp_cli_connection_manager_call_request_connection
                                   (TpConnectionManager *proxy,
                                    gint timeout_ms,
                                    const gchar *in_Protocol,
                                    GHashTable *in_Parameters,
                                    tp_cli_connection_manager_callback_for_request_connection callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object);

Start a RequestConnection method call.

<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request a <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> object representing a given account on a given protocol with the given parameters. The method returns the bus name and the object path where the new Connection object can be found, which should have the status of Connection_Status_Disconnected, to allow signal handlers to be attached before connecting is started with the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">Connect</tp:dbus-ref> method.</p> <p><strong>Most applications should not use this method</strong>: they should instead use the the <tp:dbus-ref namespace="ofdT.Account">Connection</tp:dbus-ref> property on an <tp:dbus-ref namespace="ofdT">Account</tp:dbus-ref> object obtained from the <tp:dbus-ref namespace="ofdT">AccountManager</tp:dbus-ref>. This method is used internally by the account manager to create connections when needed.</p> <p>The parameters which must and may be provided in the parameters dictionary can be discovered with the <tp:member-ref>GetParameters</tp:member-ref> method. These parameters, their types, and their default values may be cached in files so that all available connection managers do not need to be started to discover which protocols are available.</p> <p>To request values for these parameters from the user, a client must have prior knowledge of the meaning of the parameter names, so the well-known names and types defined by the <tp:type>Connection_Parameter_Name</tp:type> type should be used where appropriate.</p> <p>Connection manager authors SHOULD avoid introducing parameters whose default values would not be serializable in a <code>.manager</code> file.</p> <tp:rationale> <p>The same serialization format is used in Mission Control to store accounts.</p> </tp:rationale> <p>Every successful RequestConnection call will cause the emission of a <tp:member-ref>NewConnection</tp:member-ref> signal for the same newly created connection. The requester can use the returned object path and service name independently of the emission of that signal. In that case this signal emission is most useful for, e.g. other processes that are monitoring the creation of new connections.</p>

#### Parameters

proxy | the TpProxy |
timeout_ms | the timeout in milliseconds, or -1 to use the default |
in_Protocol | Used to pass an 'in' argument: The protocol identifier |
in_Parameters | Used to pass an 'in' argument: A dictionary mapping parameter names to values of the appropriate type, as indicated by <tp:member-ref>GetParameters</tp:member-ref> and the well-known list of names and value types documented on the <tp:type>Connection_Parameter_Name</tp:type> 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_manager_run_request_connection ()

    gboolean
    tp_cli_connection_manager_run_request_connection
                                   (TpConnectionManager *proxy,
                                    gint timeout_ms,
                                    const gchar *in_Protocol,
                                    GHashTable *in_Parameters,
                                    gchar **out_Bus_Name,
                                    gchar **out_Object_Path,
                                    GError **error,
                                    GMainLoop **loop);

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

Call the method RequestConnection 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 <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> object representing a given account on a given protocol with the given parameters. The method returns the bus name and the object path where the new Connection object can be found, which should have the status of Connection_Status_Disconnected, to allow signal handlers to be attached before connecting is started with the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">Connect</tp:dbus-ref> method.</p> <p><strong>Most applications should not use this method</strong>: they should instead use the the <tp:dbus-ref namespace="ofdT.Account">Connection</tp:dbus-ref> property on an <tp:dbus-ref namespace="ofdT">Account</tp:dbus-ref> object obtained from the <tp:dbus-ref namespace="ofdT">AccountManager</tp:dbus-ref>. This method is used internally by the account manager to create connections when needed.</p> <p>The parameters which must and may be provided in the parameters dictionary can be discovered with the <tp:member-ref>GetParameters</tp:member-ref> method. These parameters, their types, and their default values may be cached in files so that all available connection managers do not need to be started to discover which protocols are available.</p> <p>To request values for these parameters from the user, a client must have prior knowledge of the meaning of the parameter names, so the well-known names and types defined by the <tp:type>Connection_Parameter_Name</tp:type> type should be used where appropriate.</p> <p>Connection manager authors SHOULD avoid introducing parameters whose default values would not be serializable in a <code>.manager</code> file.</p> <tp:rationale> <p>The same serialization format is used in Mission Control to store accounts.</p> </tp:rationale> <p>Every successful RequestConnection call will cause the emission of a <tp:member-ref>NewConnection</tp:member-ref> signal for the same newly created connection. The requester can use the returned object path and service name independently of the emission of that signal. In that case this signal emission is most useful for, e.g. other processes that are monitoring the creation of new connections.</p>

#### Parameters

proxy | A TpConnectionManager or subclass |
timeout_ms | Timeout in milliseconds, or -1 for default |
in_Protocol | Used to pass an 'in' argument: The protocol identifier |
in_Parameters | Used to pass an 'in' argument: A dictionary mapping parameter names to values of the appropriate type, as indicated by <tp:member-ref>GetParameters</tp:member-ref> and the well-known list of names and value types documented on the <tp:type>Connection_Parameter_Name</tp:type> type. |
out_Bus_Name | Used to return an 'out' argument if `TRUE` is returned: A D-Bus service name where the new Connection object can be found |
out_Object_Path | Used to return an 'out' argument if `TRUE` is returned: The D-Bus object path to the Connection on this service |
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_manager_signal_callback_new_connection ()

    void
    (*tp_cli_connection_manager_signal_callback_new_connection)
                                   (TpConnectionManager *proxy,
                                    const gchar *arg_Bus_Name,
                                    const gchar *arg_Object_Path,
                                    const gchar *arg_Protocol,
                                    gpointer user_data,
                                    GObject *weak_object);

Represents the signature of a callback for the signal NewConnection.

#### Parameters

proxy | The proxy on which `tp_cli_connection_manager_connect_to_new_connection()` was called |
arg_Bus_Name | The D-Bus service where the connection object can be found |
arg_Object_Path | The object path of the Connection object on this service |
arg_Protocol | The identifier for the protocol this connection uses |
user_data | User-supplied data |
weak_object | User-supplied weakly referenced object |

### tp_cli_connection_manager_connect_to_new_connection ()

    TpProxySignalConnection *
    tp_cli_connection_manager_connect_to_new_connection
                                   (TpConnectionManager *proxy,
                                    tp_cli_connection_manager_signal_callback_new_connection callback,
                                    gpointer user_data,
                                    GDestroyNotify destroy,
                                    GObject *weak_object,
                                    GError **error);

Connect a handler to the signal NewConnection.

Emitted when a new <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> object is created.

#### Parameters

proxy | A TpConnectionManager 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.

## Types and Values

### struct TpConnectionManager

    struct TpConnectionManager;

A proxy object for a Telepathy connection manager.

This might represent a connection manager which is currently running (in which case it can be introspected) or not (in which case its capabilities can be read from .manager files in the filesystem). Accordingly, this object never emits “invalidated” unless all references to it are discarded.

Various fields and methods on this object do not work until `TP_CONNECTION_MANAGER_FEATURE_CORE` is prepared. Use `tp_proxy_prepare_async()` to wait for this to happen.

Since 0.19.1, accessing the fields of this struct is deprecated, and they are no longer documented here. Use the accessors `tp_connection_manager_get_name()`, `tp_connection_manager_is_running()`, `tp_connection_manager_dup_protocols()`, `tp_connection_manager_get_info_source()` and the “always-introspect” property instead.

Since: 0.7.1

### struct TpConnectionManagerClass

    struct TpConnectionManagerClass {
    };

The class of a TpConnectionManager.

Since: 0.7.1

### TP_CONNECTION_MANAGER_FEATURE_CORE

    #define             TP_CONNECTION_MANAGER_FEATURE_CORE

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

After this feature is prepared, basic information about the connection manager's protocols (`tp_connection_manager_dup_protocols()`), and their available parameters, will have been retrieved, either by activating the connection manager over D-Bus or by reading the .manager file in which that information is cached.

Since 0.11.11, this feature also finds any extra interfaces that this connection manager has, and adds them to “interfaces” (where they can be queried with `tp_proxy_has_interface()`).

(These are the same guarantees offered by the older `tp_connection_manager_call_when_ready()` mechanism.)

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

### enum TpCMInfoSource

Describes possible sources of information on connection managers' supported protocols.

Since 0.11.5, there is a corresponding GEnumClass type, `TP_TYPE_CM_INFO_SOURCE`.

#### Members

TP_CM_INFO_SOURCE_NONE | no information available |
TP_CM_INFO_SOURCE_FILE | information came from a .manager file |
TP_CM_INFO_SOURCE_LIVE | information came from the connection manager |

Since: 0.7.1

### TP_TYPE_CM_INFO_SOURCE

    #define TP_TYPE_CM_INFO_SOURCE (tp_cm_info_source_get_type ())

The GEnumClass type of a TpCMInfoSource.

Since: 0.11.5

### struct TpConnectionManagerProtocol

    struct TpConnectionManagerProtocol {
      gchar *name;
      TpConnectionManagerParam *params;
    };

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

, use TpProtocol objects instead

Structure representing a protocol supported by a connection manager. Note that the size of this structure may change, so its size must not be relied on.

#### Members

gchar *`name`; | The name of this connection manager |
TpConnectionManagerParam *`params`; | Array of TpConnectionManagerParam structures, terminated by a structure whose `name` is `NULL` |

Since: 0.7.1

### struct TpConnectionManagerParam

    struct TpConnectionManagerParam {
    };

Structure representing a connection manager parameter.

Since 0.19.1, accessing the fields of this struct is deprecated, and they are no longer documented here. Use the accessors `tp_connection_manager_param_get_name()`, `tp_connection_manager_param_get_dbus_signature()`, `tp_connection_manager_param_is_required()`, `tp_connection_manager_param_is_required_for_registration()`, `tp_connection_manager_param_is_secret()`, `tp_connection_manager_param_is_dbus_property()`, `tp_connection_manager_param_get_default()`, `tp_connection_manager_param_dup_default_variant()` instead.

Since: 0.7.1

## Property Details

### The `“always-introspect”` property

      “always-introspect”        gboolean

If `TRUE`, always introspect the connection manager as it comes online, even if we already have its info from a .manager file. Default `FALSE`.

Owner: TpConnectionManager

Flags: Read / Write

Default value: FALSE

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

      “cm-name”                  gchar *

The name of the connection manager, e.g. "gabble" (read-only).

Owner: TpConnectionManager

Flags: Read

Default value: NULL

Since: 0.19.3

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

      “connection-manager”       gchar *

The name of the connection manager, e.g. "gabble" (read-only).

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

Use “cm-name” instead.

Owner: TpConnectionManager

Flags: Read

Default value: NULL

### The `“info-source”` property

      “info-source”              guint

Where we got the current information on supported protocols (a TpCMInfoSource).

Since 0.7.26, the “notify” signal is emitted for this property.

(Note that this is of type `G_TYPE_UINT`, not `TP_TYPE_CM_INFO_SOURCE`, for historical reasons.)

Owner: TpConnectionManager

Flags: Read

Allowed values: <= 2

Default value: 0

### The `“manager-file”` property

      “manager-file”             gchar *

The absolute path of the .manager file. If set to `NULL` (the default), the XDG data directories will be searched for a .manager file of the correct name.

If set to the empty string, no .manager file will be read.

Owner: TpConnectionManager

Flags: Read / Write / Construct

Default value: NULL

## Signal Details

### The `“activated”` signal

    void
    user_function (TpConnectionManager *self,
                   gpointer             user_data)

Emitted when the connection manager's well-known name appears on the bus.

#### Parameters

self | the connection manager proxy |
user_data | user data set when the signal handler was connected. |

Flags: Has Details

### The `“exited”` signal

    void
    user_function (TpConnectionManager *self,
                   gpointer             user_data)

Emitted when the connection manager's well-known name disappears from the bus or when activation fails.

#### Parameters

self | the connection manager proxy |
user_data | user data set when the signal handler was connected. |

Flags: Has Details

### The `“got-info”` signal

    void
    user_function (TpConnectionManager *self,
                   guint                source,
                   gpointer             user_data)

Emitted when the connection manager's capabilities have been discovered.

This signal is not very helpful. Using `tp_proxy_prepare_async()` instead is recommended.

#### Parameters

self | the connection manager proxy |
source | a TpCMInfoSource |
user_data | user data set when the signal handler was connected. |

Flags: Has Details

## See Also

TpConnection