telepathy-glib API Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
Synopsis
#include <telepathy-glib/telepathy-glib.h> void (*TpConnectionManagerListCb) (TpConnectionManager * const *cms
,gsize n_cms
,const GError *error
,gpointer user_data
,GObject *weak_object
); void tp_list_connection_managers_async (TpDBusDaemon *dbus_daemon
,GAsyncReadyCallback callback
,gpointer user_data
); GList * tp_list_connection_managers_finish (GAsyncResult *result
,GError **error
); void tp_list_connection_managers (TpDBusDaemon *bus_daemon
,TpConnectionManagerListCb callback
,gpointer user_data
,GDestroyNotify destroy
,GObject *weak_object
); struct TpConnectionManager; struct 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
); #define TP_CONNECTION_MANAGER_FEATURE_CORE 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; #define TP_TYPE_CM_INFO_SOURCE TpCMInfoSource tp_connection_manager_get_info_source (TpConnectionManager *self
); gboolean tp_connection_manager_activate (TpConnectionManager *self
); gboolean tp_connection_manager_is_running (TpConnectionManager *self
); GList * tp_connection_manager_dup_protocols (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
); TpProtocol * tp_connection_manager_get_protocol_object (TpConnectionManager *self
,const gchar *protocol
); struct 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
); struct TpConnectionManagerParam; const gchar * tp_connection_manager_param_get_name (const TpConnectionManagerParam *param
); const gchar * tp_connection_manager_param_get_dbus_signature (const TpConnectionManagerParam *param
); GVariantType * tp_connection_manager_param_dup_variant_type (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
); GVariant * tp_connection_manager_param_dup_default_variant (const TpConnectionManagerParam *param
); 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
); TpConnectionManagerParam * tp_connection_manager_param_copy (const TpConnectionManagerParam *in
); void tp_connection_manager_param_free (TpConnectionManagerParam *param
); TpConnectionManagerProtocol * tp_connection_manager_protocol_copy (const TpConnectionManagerProtocol *in
); void tp_connection_manager_protocol_free (TpConnectionManagerProtocol *proto
); 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
GEnum +----TpCMInfoSource
GBoxed +----TpConnectionManagerProtocol
GBoxed +----TpConnectionManagerParam
Properties
"always-introspect" gboolean : Read / Write "cm-name" gchar* : Read "connection-manager" gchar* : Read "info-source" guint : Read "manager-file" gchar* : Read / Write / Construct
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.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.
|
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]
|
|
number of connection managers in cms (not including the final
NULL ) |
|
NULL on success, or an error that occurred |
|
user-supplied data |
|
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.
|
a TpDBusDaemon, or NULL to use
tp_dbus_daemon_dup() . [allow-none]
|
|
a callback to call with a list of CMs |
|
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)
.
|
the result of tp_list_connection_managers_async()
|
|
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
);
Warning
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.
|
proxy for the D-Bus daemon |
|
callback to be called when listing the CMs
succeeds or fails; not called if the weak_object goes away |
|
user-supplied data for the callback |
|
callback to destroy the user-supplied data, called after
callback , but also if the weak_object goes away |
|
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
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_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.
|
Proxy for the D-Bus daemon |
|
The connection manager name (such as "gabble") |
|
The "manager-file"
property, which may (and generally should) be NULL . [allow-none]
|
|
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.
|
a connection manager |
Returns : |
the "cm-name" property |
Since 0.7.26
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
TpConnectionManagerWhenReadyCb ()
void (*TpConnectionManagerWhenReadyCb) (TpConnectionManager *cm
,const GError *error
,gpointer user_data
,GObject *weak_object
);
Warning
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.
|
a connection manager |
|
NULL on success, or the reason why tp_connection_manager_is_ready()
would return FALSE
|
|
the user_data passed to tp_connection_manager_call_when_ready()
|
|
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
);
Warning
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.
|
a connection manager |
|
callback to call when information has been retrieved or on error |
|
arbitrary data to pass to the callback |
|
called to destroy user_data
|
|
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
);
Warning
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.
|
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.
Since 0.11.5, there is a corresponding GEnumClass type,
TP_TYPE_CM_INFO_SOURCE
.
no information available | |
information came from a .manager file | |
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
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.
|
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.
|
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.
|
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)
.
|
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.
|
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.
|
a connection manager |
|
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
);
Warning
tp_connection_manager_get_protocol
is deprecated and should not be used in newly-written code. 0.19.1, 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.
|
a connection manager |
|
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.
|
a connection manager |
|
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
struct TpConnectionManagerProtocol
struct TpConnectionManagerProtocol { gchar *name; TpConnectionManagerParam *params; };
Warning
TpConnectionManagerProtocol
is deprecated and should not be used in newly-written code. 0.19.1, 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.
gchar * |
The name of this connection manager |
TpConnectionManagerParam * |
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
);
Warning
tp_connection_manager_protocol_can_register
is deprecated and should not be used in newly-written code. 0.19.1, use TpProtocol objects instead
Return whether a new account can be registered on this protocol, by setting
the special "register" parameter to TRUE
.
|
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
);
Warning
tp_connection_manager_protocol_dup_param_names
is deprecated and should not be used in newly-written code. 0.19.1, 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()
.
|
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
);
Warning
tp_connection_manager_protocol_has_param
is deprecated and should not be used in newly-written code. 0.19.1, use TpProtocol objects instead
|
structure representing a supported protocol |
|
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
);
Warning
tp_connection_manager_protocol_get_param
is deprecated and should not be used in newly-written code. 0.19.1, use TpProtocol objects instead
|
structure representing a supported protocol |
|
a parameter name |
Returns : |
a structure representing the parameter param , or NULL if not
supported |
Since 0.7.26
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
tp_connection_manager_param_get_name ()
const gchar * tp_connection_manager_param_get_name
(const TpConnectionManagerParam *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
);
|
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
);
|
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
);
|
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
);
|
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
);
|
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
);
|
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.
|
a parameter supported by a TpConnectionManager |
|
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
.
|
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.
|
a possible connection manager name |
|
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.
|
a possible protocol name |
|
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
);
|
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()
.
|
the TpConnectionManagerParam to free |
Since 0.11.3
tp_connection_manager_protocol_copy ()
TpConnectionManagerProtocol * tp_connection_manager_protocol_copy
(const TpConnectionManagerProtocol *in
);
Warning
tp_connection_manager_protocol_copy
is deprecated and should not be used in newly-written code. 0.19.1, use TpProtocol objects instead
|
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
);
Warning
tp_connection_manager_protocol_free
is deprecated and should not be used in newly-written code. 0.19.1, use TpProtocol objects instead
Frees proto
, which was copied with tp_connection_manager_protocol_copy()
.
|
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.
|
the proxy on which the call was made |
|
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. |
|
NULL on success, or an error on failure |
|
user-supplied data |
|
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.
|
the TpProxy |
|
the timeout in milliseconds, or -1 to use the default |
|
Used to pass an 'in' argument: The required protocol name |
|
called when the method call succeeds or fails;
may be NULL to make a "fire and forget" call with no
reply tracking |
|
user-supplied data passed to the callback;
must be NULL if callback is NULL
|
|
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be NULL if callback is NULL
|
|
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
);
Warning
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.
|
A TpConnectionManager or subclass |
|
Timeout in milliseconds, or -1 for default |
|
Used to pass an 'in' argument: The required protocol name |
|
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. |
|
If not NULL , used to return errors if FALSE
is returned |
|
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.
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.
|
the TpProxy |
|
the timeout in milliseconds, or -1 to use the default |
|
called when the method call succeeds or fails;
may be NULL to make a "fire and forget" call with no
reply tracking |
|
user-supplied data passed to the callback;
must be NULL if callback is NULL
|
|
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be NULL if callback is NULL
|
|
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
);
Warning
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.
|
A TpConnectionManager or subclass |
|
Timeout in milliseconds, or -1 for default |
|
Used to return an 'out' argument if TRUE is returned: The keys of the <tp:member-ref>Protocols</tp:member-ref> map. |
|
If not NULL , used to return errors if FALSE
is returned |
|
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.
|
the proxy on which the call was made |
|
Used to return an 'out' argument if error is NULL : A D-Bus service name where the new Connection object can be found |
|
Used to return an 'out' argument if error is NULL : The D-Bus object path to the Connection on this service |
|
NULL on success, or an error on failure |
|
user-supplied data |
|
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>
|
the TpProxy |
|
the timeout in milliseconds, or -1 to use the default |
|
Used to pass an 'in' argument: The protocol identifier |
|
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. |
|
called when the method call succeeds or fails;
may be NULL to make a "fire and forget" call with no
reply tracking |
|
user-supplied data passed to the callback;
must be NULL if callback is NULL
|
|
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be NULL if callback is NULL
|
|
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
);
Warning
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>
|
A TpConnectionManager or subclass |
|
Timeout in milliseconds, or -1 for default |
|
Used to pass an 'in' argument: The protocol identifier |
|
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. |
|
Used to return an 'out' argument if TRUE is returned: A D-Bus service name where the new Connection object can be found |
|
Used to return an 'out' argument if TRUE is returned: The D-Bus object path to the Connection on this service |
|
If not NULL , used to return errors if FALSE
is returned |
|
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.
|
The proxy on which tp_cli_connection_manager_connect_to_new_connection()
was called |
|
The D-Bus service where the connection object can be found |
|
The object path of the Connection object on this service |
|
The identifier for the protocol this connection uses |
|
User-supplied data |
|
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.
|
A TpConnectionManager or subclass |
|
Callback to be called when the signal is received |
|
User-supplied data for the callback |
|
Destructor for the user-supplied data, which
will be called when this signal is disconnected, or
before this function returns NULL
|
|
A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected |
|
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 "cm-name"
property
"cm-name" gchar* : Read
The name of the connection manager, e.g. "gabble" (read-only).
Default value: NULL
Since 0.19.3
The "connection-manager"
property
"connection-manager" gchar* : Read
Warning
TpConnectionManager:connection-manager
is deprecated and should not be used in newly-written code. Use "cm-name" instead.
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.
(Note that this is of type G_TYPE_UINT
, not TP_TYPE_CM_INFO_SOURCE
,
for historical reasons.)
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) : Has Details
Emitted when the connection manager's well-known name appears on the bus.
|
the connection manager proxy |
|
user data set when the signal handler was connected. |
The "exited"
signal
void user_function (TpConnectionManager *self,
gpointer user_data) : Has Details
Emitted when the connection manager's well-known name disappears from the bus or when activation fails.
|
the connection manager proxy |
|
user data set when the signal handler was connected. |
The "got-info"
signal
void user_function (TpConnectionManager *self,
guint source,
gpointer user_data) : Has Details
Emitted when the connection manager's capabilities have been discovered.
This signal is not very helpful. Using
tp_proxy_prepare_async()
instead is recommended.
|
the connection manager proxy |
|
a TpCMInfoSource |
|
user data set when the signal handler was connected. |