|
|
|
libmcclient Reference Manual | |
|---|---|---|---|---|
McAccountManager;
McAccountManagerClass;
McAccountManager* mc_account_manager_new (TpDBusDaemon *dbus);
void (*McAccountManagerWhenReadyCb) (McAccountManager *manager,
const GError *error,
gpointer user_data);
void mc_account_manager_call_when_ready (McAccountManager *manager,
McAccountManagerWhenReadyCb callback,
gpointer user_data);
void (*McAccountManagerWhenReadyObjectCb)
(McAccountManager *manager,
const GError *error,
gpointer user_data,
GObject *weak_object);
void mc_account_manager_call_when_iface_ready
(McAccountManager *manager,
GQuark interface,
McAccountManagerWhenReadyObjectCb callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object);
void mc_account_manager_call_when_ready_with_accounts
(McAccountManager *manager,
McAccountManagerWhenReadyObjectCb callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object,
...);
McAccount* mc_account_manager_get_account (McAccountManager *manager,
const gchar *account_name);
gboolean (*McAccountFilterFunc) (McAccount *account,
gpointer user_data);
GList* mc_account_manager_list_accounts (McAccountManager *manager,
McAccountFilterFunc filter,
gpointer user_data);
void (*mc_cli_account_manager_signal_callback_account_removed)
(TpProxy *proxy,
const gchar *arg_Account,
gpointer user_data,
GObject *weak_object);
TpProxySignalConnection* mc_cli_account_manager_connect_to_account_removed
(gpointer proxy,
mc_cli_account_manager_signal_callback_account_removed callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object,
GError **error);
void (*mc_cli_account_manager_signal_callback_account_validity_changed)
(TpProxy *proxy,
const gchar *arg_Account,
gboolean arg_Valid,
gpointer user_data,
GObject *weak_object);
TpProxySignalConnection* mc_cli_account_manager_connect_to_account_validity_changed
(gpointer proxy,
mc_cli_account_manager_signal_callback_account_validity_changed callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object,
GError **error);
void (*mc_cli_account_manager_callback_for_create_account)
(TpProxy *proxy,
const gchar *out_Account,
const GError *error,
gpointer user_data,
GObject *weak_object);
TpProxyPendingCall* mc_cli_account_manager_call_create_account
(gpointer proxy,
gint timeout_ms,
const gchar *in_Connection_Manager,
const gchar *in_Protocol,
const gchar *in_Display_Name,
GHashTable *in_Parameters,
GHashTable *in_Properties,
mc_cli_account_manager_callback_for_create_account callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object);
void (*mc_cli_account_manager_interface_creation_callback_for_create_account)
(TpProxy *proxy,
const gchar *out_Account,
const GError *error,
gpointer user_data,
GObject *weak_object);
TpProxyPendingCall* mc_cli_account_manager_interface_creation_call_create_account
(gpointer proxy,
gint timeout_ms,
const gchar *in_Connection_Manager,
const gchar *in_Protocol,
const gchar *in_Display_Name,
GHashTable *in_Parameters,
GHashTable *in_Properties,
mc_cli_account_manager_interface_creation_callback_for_create_account callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object);
void (*mc_cli_account_manager_interface_query_callback_for_find_accounts)
(TpProxy *proxy,
const GPtrArray *out_accounts,
const GError *error,
gpointer user_data,
GObject *weak_object);
TpProxyPendingCall* mc_cli_account_manager_interface_query_call_find_accounts
(gpointer proxy,
gint timeout_ms,
GHashTable *in_params,
mc_cli_account_manager_interface_query_callback_for_find_accounts callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object);
This module provides a client-side proxy object for the Telepathy AccountManager D-Bus API.
typedef struct _McAccountManager McAccountManager;
A proxy object for the Telepathy AccountManager D-Bus API. This is a subclass of TpProxy.
typedef struct _McAccountManagerClass McAccountManagerClass;
The class of a McAccountManager.
McAccountManager* mc_account_manager_new (TpDBusDaemon *dbus);
Creates a proxy for the DBus AccountManager Telepathy object.
dbus : |
a D-Bus daemon; may not be NULL
|
| Returns : | a new McAccountManager object. |
void (*McAccountManagerWhenReadyCb) (McAccountManager *manager, const GError *error, gpointer user_data);
manager : |
the McAccountManager. |
error : |
NULL if the interface is ready for use, or the error with which it
was invalidated if it is now invalid.
|
user_data : |
the user data that was passed to
mc_account_manager_call_when_ready().
|
void mc_account_manager_call_when_ready (McAccountManager *manager, McAccountManagerWhenReadyCb callback, gpointer user_data);
Start retrieving and monitoring the properties of the base interface of
manager. If they have already been retrieved, call callback immediately,
then return. Otherwise, callback will be called when the properties are
ready.
manager : |
the McAccountManager. |
callback : |
called when the interface becomes ready or invalidated, whichever happens first. |
user_data : |
user data to be passed to callback.
|
void (*McAccountManagerWhenReadyObjectCb)
(McAccountManager *manager,
const GError *error,
gpointer user_data,
GObject *weak_object);
manager : |
the McAccountManager. |
error : |
NULL if the interface is ready for use, or the error with which it
was invalidated if it is now invalid.
|
user_data : |
the user data that was passed to
mc_account_call_when_iface_ready() or mc_account_call_when_all_ready().
|
weak_object : |
the GObject that was passed to
mc_account_call_when_iface_ready() or mc_account_call_when_all_ready().
|
void mc_account_manager_call_when_iface_ready
(McAccountManager *manager,
GQuark interface,
McAccountManagerWhenReadyObjectCb callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object);
Start retrieving and monitoring the properties of the interface interface
of account. If they have already been retrieved, call callback
immediately, then return. Otherwise, callback will be called when the
properties are ready.
manager : |
the McAccountManager. |
interface : |
a GQuark representing the interface to process. |
callback : |
called when the interface becomes ready or invalidated, whichever happens first. |
user_data : |
user data to be passed to callback.
|
destroy : |
called with the user_data as argument, after the call has succeeded, failed or been cancelled. |
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
|
void mc_account_manager_call_when_ready_with_accounts
(McAccountManager *manager,
McAccountManagerWhenReadyObjectCb callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object,
...);
This is a convenience function that waits for the account manager to be ready, after which it requests the desired interfaces out of all accounts and returns only once they are all ready. After this function has been called, all new accounts that should appear will have their desired interfaces retrieved, and the "account-ready" signal will be emitted.
manager : |
the McAccountManager. |
callback : |
called when the account manager and all the accounts are ready, or some error occurs. |
user_data : |
user data to be passed to callback.
|
destroy : |
called with the user_data as argument, after the call has succeeded, failed or been cancelled. |
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
|
... : |
a list of GQuark types representing the account interfaces to
process, followed by 0.
|
McAccount* mc_account_manager_get_account (McAccountManager *manager, const gchar *account_name);
Get the McAccount for the account whose name is account_name. It looks up
the accounts from an internal cache, and if the McAccount is not found
there it is created, provided that the account_name refers to a proper
account.
manager : |
the McAccountManager. |
account_name : |
the name of a McAccount, or an object path. |
| Returns : | a McAccount, not referenced. NULL if account_name does not match
any account.
|
gboolean (*McAccountFilterFunc) (McAccount *account, gpointer user_data);
account : |
a McAccount. |
user_data : |
the user data that was passed to
mc_account_manager_list_accounts().
|
| Returns : | TRUE if account must be listed, FALSE otherwise.
|
GList* mc_account_manager_list_accounts (McAccountManager *manager, McAccountFilterFunc filter, gpointer user_data);
List all accounts known by the manager. For this function to be really
useful, you first need to have waited for
mc_account_manager_call_when_ready_with_accounts() to succeed, or it will
only return those accounts for which mc_account_manager_get_account() has
been called.
manager : |
the McAccountManager. |
filter : |
a function for filtering accounts, or NULL.
|
user_data : |
user data to be supplied to the filtering callback. |
| Returns : | a GList of McAccount objects; to be free'd with g_list_free().
|
void (*mc_cli_account_manager_signal_callback_account_removed)
(TpProxy *proxy,
const gchar *arg_Account,
gpointer user_data,
GObject *weak_object);
Represents the signature of a callback for the signal AccountRemoved.
proxy : |
The proxy on which mc_cli_account_manager_connect_to_account_removed()
was called
|
arg_Account : |
An Account, which must not be used any more. |
user_data : |
User-supplied data |
weak_object : |
User-supplied weakly referenced object |
TpProxySignalConnection* mc_cli_account_manager_connect_to_account_removed
(gpointer proxy,
mc_cli_account_manager_signal_callback_account_removed callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object,
GError **error);
Connect a handler to the signal AccountRemoved.
The given account has been removed. <tp:rationale> This is effectively change notification for the valid and invalid accounts lists. On emission of this signal, the Account indicated will no longer be present in either of the lists. </tp:rationale>
proxy : |
A TpProxy 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.
|
void (*mc_cli_account_manager_signal_callback_account_validity_changed)
(TpProxy *proxy,
const gchar *arg_Account,
gboolean arg_Valid,
gpointer user_data,
GObject *weak_object);
Represents the signature of a callback for the signal AccountValidityChanged.
proxy : |
The proxy on which mc_cli_account_manager_connect_to_account_validity_changed()
was called
|
arg_Account : |
An Account. |
arg_Valid : |
True if the account is now valid. |
user_data : |
User-supplied data |
weak_object : |
User-supplied weakly referenced object |
TpProxySignalConnection* mc_cli_account_manager_connect_to_account_validity_changed
(gpointer proxy,
mc_cli_account_manager_signal_callback_account_validity_changed callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object,
GError **error);
Connect a handler to the signal AccountValidityChanged.
The validity of the given account has changed. New accounts are also indicated by this signal, as an account validity change (usually to True) on an account that did not previously exist. <tp:rationale> This is effectively change notification for the valid and invalid accounts lists. </tp:rationale>
proxy : |
A TpProxy 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.
|
void (*mc_cli_account_manager_callback_for_create_account)
(TpProxy *proxy,
const gchar *out_Account,
const GError *error,
gpointer user_data,
GObject *weak_object);
Signature of the callback called when a CreateAccount method call succeeds or fails.
proxy : |
the proxy on which the call was made |
out_Account : |
Used to return an 'out' argument if error is NULL: The new <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.
|
error : |
NULL on success, or an error on failure
|
user_data : |
user-supplied data |
weak_object : |
user-supplied object |
TpProxyPendingCall* mc_cli_account_manager_call_create_account
(gpointer proxy,
gint timeout_ms,
const gchar *in_Connection_Manager,
const gchar *in_Protocol,
const gchar *in_Display_Name,
GHashTable *in_Parameters,
GHashTable *in_Properties,
mc_cli_account_manager_callback_for_create_account callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object);
Start a CreateAccount method call.
Request the creation of a new <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>. The account manager SHOULD NOT allow invalid accounts to be created.
proxy : |
the TpProxy |
timeout_ms : |
the timeout in milliseconds, or -1 to use the default |
in_Connection_Manager : |
Used to pass an 'in' argument: The name of the connection manager, e.g. "salut". |
in_Protocol : |
Used to pass an 'in' argument: The protocol, e.g. "local-xmpp". |
in_Display_Name : |
Used to pass an 'in' argument: The initial value of the new account's <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref> property. The account manager SHOULD modify this to make it unique if an Account already exists with the same display name, for instance by appending a number or the 'account' parameter. Account manager implementations SHOULD accept an empty string, but account editing user interfaces should avoid passing an empty string for this parameter. <tp:rationale> <p>The account creation UI may ask the user for a name for the new account. If the author of the UI chooses not to do this, the account creation UI is better able to suggest a default display name because it has protocol-specific knowledge which the account manager does not.</p> <p>The account manager always knows the complete list of accounts so it can easily tell whether it should append something to the display name to avoid presenting two identically-named accounts to the user.</p> </tp:rationale> |
in_Parameters : |
Used to pass an 'in' argument: Initial parameter values, as would be passed to <tp:dbus-ref namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>. |
in_Properties : |
Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The values of any other properties to be set immediately on the new Account.</p> <p>Only the properties mentioned in <tp:member-ref>SupportedAccountProperties</tp:member-ref> are acceptable here. In particular, the <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref> and <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref> properties are never allowed here, since they are set using the other arguments to this method.</p> <p>Account manager implementations SHOULD support creating accounts with an empty value for this argument.</p> |
callback : |
called when the method call succeeds or fails;
may be NULL to make a "fire and forget" call with no
reply tracking
|
user_data : |
user-supplied data passed to the callback;
must be NULL if callback is NULL
|
destroy : |
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be NULL if callback is NULL
|
weak_object : |
If not NULL, a GObject which will be
weakly referenced; if it is destroyed, this call
will automatically be cancelled. Must be NULL if
callback is NULL
|
| Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid. |
void (*mc_cli_account_manager_interface_creation_callback_for_create_account)
(TpProxy *proxy,
const gchar *out_Account,
const GError *error,
gpointer user_data,
GObject *weak_object);
Signature of the callback called when a CreateAccount method call succeeds or fails.
proxy : |
the proxy on which the call was made |
out_Account : |
Used to return an 'out' argument if error is NULL: The new account.
|
error : |
NULL on success, or an error on failure
|
user_data : |
user-supplied data |
weak_object : |
user-supplied object |
TpProxyPendingCall* mc_cli_account_manager_interface_creation_call_create_account
(gpointer proxy,
gint timeout_ms,
const gchar *in_Connection_Manager,
const gchar *in_Protocol,
const gchar *in_Display_Name,
GHashTable *in_Parameters,
GHashTable *in_Properties,
mc_cli_account_manager_interface_creation_callback_for_create_account callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object);
Start a CreateAccount method call.
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request the creation of a new account, and sets the given properties on it.</p> <tp:rationale> <p>Besides for optimization reasons, it makes sense for some properties to be set as soon as the account is created (one being the "Profile" property in the Compat interface).</p> </tp:rationale>
proxy : |
the TpProxy |
timeout_ms : |
the timeout in milliseconds, or -1 to use the default |
in_Connection_Manager : |
Used to pass an 'in' argument: The name of the connection manager, e.g. "salut". |
in_Protocol : |
Used to pass an 'in' argument: The protocol, e.g. "local-xmpp". |
in_Display_Name : |
Used to pass an 'in' argument: The initial value of the new account's DisplayName property. The account manager MAY modify this to make it unique, for instance by appending a number or the 'account' parameter. |
in_Parameters : |
Used to pass an 'in' argument: Initial parameter values, as would be passed to RequestConnection. |
in_Properties : |
Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The properties to be set, whose key must be in the form <code>Interface.PropertyName</code>.</p> |
callback : |
called when the method call succeeds or fails;
may be NULL to make a "fire and forget" call with no
reply tracking
|
user_data : |
user-supplied data passed to the callback;
must be NULL if callback is NULL
|
destroy : |
called with the user_data as argument, after the
call has succeeded, failed or been cancelled;
must be NULL if callback is NULL
|
weak_object : |
If not NULL, a GObject which will be
weakly referenced; if it is destroyed, this call
will automatically be cancelled. Must be NULL if
callback is NULL
|
| Returns : | a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid. |
void (*mc_cli_account_manager_interface_query_callback_for_find_accounts)
(TpProxy *proxy,
const GPtrArray *out_accounts,
const GError *error,
gpointer user_data,
GObject *weak_object);
Signature of the callback called when a FindAccounts method call succeeds or fails.
proxy : |
the proxy on which the call was made |
out_accounts : |
Used to return an 'out' argument if error is NULL: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> The array of account objects.
|
error : |
NULL on success, or an error on failure
|
user_data : |
user-supplied data |
weak_object : |
user-supplied object |
TpProxyPendingCall* mc_cli_account_manager_interface_query_call_find_accounts
(gpointer proxy,
gint timeout_ms,
GHashTable *in_params,
mc_cli_account_manager_interface_query_callback_for_find_accounts callback,
gpointer user_data,
GDestroyNotify destroy,
GObject *weak_object);
Start a FindAccounts method call.
<tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Find all accounts which match the search query.</p> <p>An empty parameter should return all accounts</p>
proxy : |
the TpProxy |
timeout_ms : |
the timeout in milliseconds, or -1 to use the default |
in_params : |
Used to pass an 'in' argument: <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>The search query data. The keys can be any Connection Manager parameter (in which case they must be prepended with the string "param-"), any readable Account property (in the form <code>Interface.PropertyName</code>) or any of these special keys:</p> <ul> <li>s: Manager</li> <li>s: Protocol</li> <li>u: RequestedPresence</li> <li>s: RequestedStatus</li> <li>u: CurrentPresence</li> <li>s: CurrentStatus</li> </ul> |
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. |
"account-created" signalvoid user_function (McAccountManager *account_manager, gchar *object_path, gboolean valid, gpointer user_data) : Run Last
Emitted when a new account is created.
This signal will be emitted only once
mc_account_manager_call_when_ready() has been successfully invoked.
account_manager : |
the McAccountManager. |
object_path : |
the path to the DBus Account object. |
valid : |
TRUE if this is a valid account.
|
user_data : |
user data set when the signal handler was connected. |
"account-ready" signalvoid user_function (McAccountManager *account_manager, McAccount *account, gpointer user_data) : Run Last
Emitted when a new account has appeared on the D-Bus and all the
requested interfaces (see
mc_account_manager_call_when_ready_with_accounts()) have become ready.
Clients should connect to this signal only after
mc_account_manager_call_when_ready_with_accounts() has called the
callback function.
In the unlikely case that this signal is emitted several times for the same account, clients should ignore all but the first emission.
account_manager : |
the McAccountManager. |
account : |
the McAccount that became ready. |
user_data : |
user data set when the signal handler was connected. |