TpConnectionManager

TpConnectionManager — proxy object for a Telepathy connection manager

Synopsis

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

void                (*TpConnectionManagerListCb)        (TpConnectionManager * const *cms,
                                                         gsize n_cms,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                tp_list_connection_managers         (TpDBusDaemon *bus_daemon,
                                                         TpConnectionManagerListCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
                    TpConnectionManager;
                    TpConnectionManagerClass;
TpConnectionManager * tp_connection_manager_new         (TpDBusDaemon *dbus,
                                                         const gchar *name,
                                                         const gchar *manager_filename,
                                                         GError **error);
const gchar *       tp_connection_manager_get_name      (TpConnectionManager *self);
void                (*TpConnectionManagerWhenReadyCb)   (TpConnectionManager *cm,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                tp_connection_manager_call_when_ready
                                                        (TpConnectionManager *self,
                                                         TpConnectionManagerWhenReadyCb callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
gboolean            tp_connection_manager_is_ready      (TpConnectionManager *self);
enum                TpCMInfoSource;
TpCMInfoSource      tp_connection_manager_get_info_source
                                                        (TpConnectionManager *self);
gboolean            tp_connection_manager_activate      (TpConnectionManager *self);
gboolean            tp_connection_manager_is_running    (TpConnectionManager *self);
gchar **            tp_connection_manager_dup_protocol_names
                                                        (TpConnectionManager *self);
gboolean            tp_connection_manager_has_protocol  (TpConnectionManager *self,
                                                         const gchar *protocol);
const TpConnectionManagerProtocol * tp_connection_manager_get_protocol
                                                        (TpConnectionManager *self,
                                                         const gchar *protocol);
                    TpConnectionManagerProtocol;
gboolean            tp_connection_manager_protocol_can_register
                                                        (const TpConnectionManagerProtocol *protocol);
gchar **            tp_connection_manager_protocol_dup_param_names
                                                        (const TpConnectionManagerProtocol *protocol);
gboolean            tp_connection_manager_protocol_has_param
                                                        (const TpConnectionManagerProtocol *protocol,
                                                         const gchar *param);
const TpConnectionManagerParam * tp_connection_manager_protocol_get_param
                                                        (const TpConnectionManagerProtocol *protocol,
                                                         const gchar *param);
                    TpConnectionManagerParam;
const gchar *       tp_connection_manager_param_get_name
                                                        (const TpConnectionManagerParam *param);
const gchar *       tp_connection_manager_param_get_dbus_signature
                                                        (const TpConnectionManagerParam *param);
gboolean            tp_connection_manager_param_is_required
                                                        (const TpConnectionManagerParam *param);
gboolean            tp_connection_manager_param_is_required_for_registration
                                                        (const TpConnectionManagerParam *param);
gboolean            tp_connection_manager_param_is_secret
                                                        (const TpConnectionManagerParam *param);
gboolean            tp_connection_manager_param_is_dbus_property
                                                        (const TpConnectionManagerParam *param);
gboolean            tp_connection_manager_param_get_default
                                                        (const TpConnectionManagerParam *param,
                                                         GValue *value);
gboolean            tp_connection_manager_check_valid_name
                                                        (const gchar *name,
                                                         GError **error);
gboolean            tp_connection_manager_check_valid_protocol_name
                                                        (const gchar *name,
                                                         GError **error);
void                tp_connection_manager_init_known_interfaces
                                                        (void);


void                (*tp_cli_connection_manager_callback_for_get_parameters)
                                                        (TpConnectionManager *proxy,
                                                         const GPtrArray *out_Parameters,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
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);
gboolean            tp_cli_connection_manager_run_get_parameters
                                                        (TpConnectionManager *proxy,
                                                         gint timeout_ms,
                                                         const gchar *in_Protocol,
                                                         GPtrArray **out_Parameters,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_connection_manager_callback_for_list_protocols)
                                                        (TpConnectionManager *proxy,
                                                         const gchar **out_Protocols,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
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);
gboolean            tp_cli_connection_manager_run_list_protocols
                                                        (TpConnectionManager *proxy,
                                                         gint timeout_ms,
                                                         gchar ***out_Protocols,
                                                         GError **error,
                                                         GMainLoop **loop);
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);
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);
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);
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);
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);

Object Hierarchy

  GObject
   +----TpProxy
         +----TpConnectionManager

Properties

  "always-introspect"        gboolean              : Read / Write
  "connection-manager"       gchar*                : Read
  "info-source"              guint                 : Read
  "manager-file"             gchar*                : Read / Write / Construct

Signals

  "activated"                                      : Run Last / Has Details
  "exited"                                         : Run Last / Has Details
  "got-info"                                       : Run Last / Has Details

Description

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

Details

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.7.26, tp_list_connection_managers() will wait for each TpConnectionManager to become ready, so all connection managers passed to callback will be ready (tp_connection_manager_is_ready() will return TRUE) unless an error occurred while launching that connection manager.

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

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

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

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 be ready (tp_connection_manager_is_ready() will return TRUE) unless an error occurred while launching that connection manager.

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

Since 0.7.1


TpConnectionManager

typedef struct {
    TpProxy parent;

    const gchar *name;
    const TpConnectionManagerProtocol * const *protocols;

    /* These are really booleans, but gboolean is signed. Thanks, GLib */
    unsigned int running:1;
    unsigned int always_introspect:1;
    /* TpCMInfoSource, but can't rely on enums being unsigned */
    unsigned int info_source:2;
    guint reserved_flags:28;

    TpConnectionManagerPrivate *priv;
} 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_is_ready() returns TRUE. Use tp_connection_manager_call_when_ready() to wait for this to happen.

TpProxy parent;

The parent class instance

const gchar *name;

The identifier of the connection manager (e.g. "gabble"). Should be considered read-only

const TpConnectionManagerProtocol * const  *protocols;

If info_source > TP_CM_INFO_SOURCE_NONE, a NULL-terminated array of pointers to TpConnectionManagerProtocol structures; otherwise NULL. Should be considered read-only

unsigned int running :1;

TRUE if the CM is currently known to be running. Should be considered read-only

unsigned int always_introspect :1;

TRUE if the CM will be introspected automatically. Should be considered read-only: use the "always-introspect" property if you want to change it

unsigned int info_source :2;

The source of protocols, or TP_CM_INFO_SOURCE_NONE if no info has been discovered yet

guint reserved_flags :28;

Reserved for future use

TpConnectionManagerPrivate *priv;

Pointer to opaque private data

Since 0.7.1


TpConnectionManagerClass

typedef struct {
} TpConnectionManagerClass;

The class of a TpConnectionManager.

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_connection_manager_call_when_ready() on the result.

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.

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.

self :

a connection manager

Returns :

the "connection-manager" property

Since 0.7.26


TpConnectionManagerWhenReadyCb ()

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

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.

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

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

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

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.

self :

a connection manager

Returns :

TRUE, unless the "info-source" property is TP_CM_INFO_SOURCE_NONE

Since 0.7.26


enum TpCMInfoSource

typedef enum
{
  TP_CM_INFO_SOURCE_NONE,
  TP_CM_INFO_SOURCE_FILE,
  TP_CM_INFO_SOURCE_LIVE
} TpCMInfoSource;

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

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

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.

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.

self :

a connection manager

Returns :

whether the connection manager is currently running

Since 0.7.26


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

self :

a connection manager

Returns :

a GStrv of protocol names

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_connection_manager_call_when_ready() to wait for this.

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

Returns a structure 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_connection_manager_call_when_ready() to wait for this.

The result is not necessarily valid after the main loop is re-entered.

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

Since 0.7.26


TpConnectionManagerProtocol

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

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.

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


tp_connection_manager_protocol_can_register ()

gboolean            tp_connection_manager_protocol_can_register
                                                        (const TpConnectionManagerProtocol *protocol);

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

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

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

protocol :

a protocol supported by a TpConnectionManager

Returns :

a GStrv of protocol names

Since 0.7.26


tp_connection_manager_protocol_has_param ()

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

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

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


TpConnectionManagerParam

typedef struct {
  gchar *name;
  gchar *dbus_signature;
  GValue default_value;
  guint flags;

  gpointer priv;
} TpConnectionManagerParam;

Structure representing a connection manager parameter.

gchar *name;

The name of this parameter

gchar *dbus_signature;

This parameter's D-Bus signature

GValue default_value;

This parameter's default value, or an arbitrary value of an appropriate type if TP_CONN_MGR_PARAM_FLAG_HAS_DEFAULT is not set on this parameter, or an unset GValue if the signature is not recognised by telepathy-glib

guint flags;

This parameter's flags (a combination of TpConnMgrParamFlags)

gpointer priv;

Pointer to opaque private data

Since 0.7.1


tp_connection_manager_param_get_name ()

const gchar *       tp_connection_manager_param_get_name
                                                        (const TpConnectionManagerParam *param);

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

param :

a parameter supported by a TpConnectionManager

Returns :

the D-Bus signature of the parameter

Since 0.7.26


tp_connection_manager_param_is_required ()

gboolean            tp_connection_manager_param_is_required
                                                        (const TpConnectionManagerParam *param);

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

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

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

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.

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

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.

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

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 must or may be provided to the <tp:member-ref>RequestConnection</tp:member-ref> method when connecting to the given protocol, or registering (the boolean &quot;register&quot; parameter is available, and set to true).

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

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 must or may be provided to the <tp:member-ref>RequestConnection</tp:member-ref> method when connecting to the given protocol, or registering (the boolean &quot;register&quot; parameter is available, and set to true).

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.

proxy :

the proxy on which the call was made

out_Protocols :

Used to return an 'out' argument if error is NULL: A array of string protocol identifiers supported by this manager

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.

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

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.

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: A array of string protocol identifiers supported by this manager

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.

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>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 following well-known names and types should be used where appropriate:</p> <dl> <dt>account (s)</dt> <dd>The identifier for the user's account on the server</dd> <dt>server (s)</dt> <dd>A fully qualified domain name or numeric IPv4 or IPv6 address. Using the fully-qualified domain name form is recommended whenever possible. If this parameter is specified and the account for that protocol also specifies a server, this parameter should override that in the user id.</dd> <dt>port (q)</dt> <dd>A TCP or UDP port number. If this parameter is specified and the account for that protocol also specifies a port, this parameter should override that in the account.</dd> <dt>password (s)</dt> <dd>A password associated with the account.</dd> <dt>require-encryption (b)</dt> <dd>Require encryption for this connection. A connection should fail to connect if require-encryption is set and an encrypted connection is not possible.</dd> <dt>register (b)</dt> <dd>This account should be created on the server if it does not already exist.</dd> <dt>ident (s)</dt> <dd>The local username to report to the server if necessary, such as in IRC.</dd> <dt>fullname (s)</dt> <dd>The user's full name if the service requires this when authenticating or registering.</dd> <dt>stun-server (s)</dt> <dd>The IP address or FQDN of a STUN server to use for NAT traversal, without any &quot;:port&quot; suffix.</dd> <dt>stun-port (q)</dt> <dd>The UDP port number on the stun-server to use for STUN. Only significant if the stun-server is also supplied.</dd> <dt>keepalive-interval (u)</dt> <dd>The time in seconds between pings sent to the server to ensure that the connection is still alive, or <tt>0</tt> to disable such pings.</dd> </dl> <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>

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 above well-known list.

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

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>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 following well-known names and types should be used where appropriate:</p> <dl> <dt>account (s)</dt> <dd>The identifier for the user's account on the server</dd> <dt>server (s)</dt> <dd>A fully qualified domain name or numeric IPv4 or IPv6 address. Using the fully-qualified domain name form is recommended whenever possible. If this parameter is specified and the account for that protocol also specifies a server, this parameter should override that in the user id.</dd> <dt>port (q)</dt> <dd>A TCP or UDP port number. If this parameter is specified and the account for that protocol also specifies a port, this parameter should override that in the account.</dd> <dt>password (s)</dt> <dd>A password associated with the account.</dd> <dt>require-encryption (b)</dt> <dd>Require encryption for this connection. A connection should fail to connect if require-encryption is set and an encrypted connection is not possible.</dd> <dt>register (b)</dt> <dd>This account should be created on the server if it does not already exist.</dd> <dt>ident (s)</dt> <dd>The local username to report to the server if necessary, such as in IRC.</dd> <dt>fullname (s)</dt> <dd>The user's full name if the service requires this when authenticating or registering.</dd> <dt>stun-server (s)</dt> <dd>The IP address or FQDN of a STUN server to use for NAT traversal, without any &quot;:port&quot; suffix.</dd> <dt>stun-port (q)</dt> <dd>The UDP port number on the stun-server to use for STUN. Only significant if the stun-server is also supplied.</dd> <dt>keepalive-interval (u)</dt> <dd>The time in seconds between pings sent to the server to ensure that the connection is still alive, or <tt>0</tt> to disable such pings.</dd> </dl> <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>

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 above well-known list.

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.

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.

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.

Property Details

The "always-introspect" property

  "always-introspect"        gboolean              : Read / Write

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

Default value: FALSE


The "connection-manager" property

  "connection-manager"       gchar*                : Read

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

Default value: NULL


The "info-source" property

  "info-source"              guint                 : Read

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

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

Allowed values: <= 2

Default value: 0


The "manager-file" property

  "manager-file"             gchar*                : Read / Write / Construct

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.

Default value: NULL

Signal Details

The "activated" signal

void                user_function                      (TpConnectionManager *self,
                                                        gpointer             user_data)      : Run Last / Has Details

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

self :

the connection manager proxy

user_data :

user data set when the signal handler was connected.

The "exited" signal

void                user_function                      (TpConnectionManager *self,
                                                        gpointer             user_data)      : Run Last / Has Details

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

self :

the connection manager proxy

user_data :

user data set when the signal handler was connected.

The "got-info" signal

void                user_function                      (TpConnectionManager *self,
                                                        guint                source,
                                                        gpointer             user_data)      : Run Last / Has Details

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

This signal is not very helpful. Since 0.7.26, using tp_connection_manager_call_when_ready() instead is recommended.

self :

the connection manager proxy

source :

a TpCMInfoSource

user_data :

user data set when the signal handler was connected.

See Also

TpConnection