McpAccountStorage

McpAccountStorage — Account Storage object, implemented by plugins

Synopsis

#include <mission-control-plugins/account-storage.h>

#define             MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_READONLY
#define             MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_DEFAULT
#define             MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_NORMAL
#define             MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_KEYRING
                    McpAccountStorage;
                    McpAccountStorageIface;
void                mcp_account_storage_iface_set_priority
                                                        (McpAccountStorageIface *iface,
                                                         guint prio);
void                mcp_account_storage_iface_set_name  (McpAccountStorageIface *iface,
                                                         const gchar *name);
void                mcp_account_storage_iface_set_desc  (McpAccountStorageIface *iface,
                                                         const gchar *desc);
void                mcp_account_storage_iface_set_provider
                                                        (McpAccountStorageIface *iface,
                                                         const gchar *provider);
void                mcp_account_storage_iface_implement_get
                                                        (McpAccountStorageIface *iface,
                                                         gboolean (method const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *) ());
void                mcp_account_storage_iface_implement_set
                                                        (McpAccountStorageIface *iface,
                                                         gboolean (method const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *, const gchar *) ());
void                mcp_account_storage_iface_implement_delete
                                                        (McpAccountStorageIface *iface,
                                                         gboolean (method const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *) ());
void                mcp_account_storage_iface_implement_list
                                                        (McpAccountStorageIface *iface,
                                                         GList* (method const McpAccountStorage *, const McpAccountManager *) ());
void                mcp_account_storage_iface_implement_commit
                                                        (McpAccountStorageIface *iface,
                                                         gboolean (method const McpAccountStorage *, const McpAccountManager *) ());
void                mcp_account_storage_iface_implement_commit_one
                                                        (McpAccountStorageIface *iface,
                                                         gboolean (method const McpAccountStorage *, const McpAccountManager *, const gchar *) ());
void                mcp_account_storage_iface_implement_ready
                                                        (McpAccountStorageIface *iface,
                                                         void (method const McpAccountStorage *storage, const McpAccountManager *am) ());
void                mcp_account_storage_iface_implement_get_identifier
                                                        (McpAccountStorageIface *iface,
                                                         void (method const McpAccountStorage *, const gchar *, GValue *) ());
void                mcp_account_storage_iface_implement_get_additional_info
                                                        (McpAccountStorageIface *iface,
                                                         GHashTable* (method const McpAccountStorage *, const gchar *) ());
void                mcp_account_storage_iface_implement_get_restrictions
                                                        (McpAccountStorageIface *iface,
                                                         guint (method const McpAccountStorage *, const gchar *) ());
gint                mcp_account_storage_priority        (const McpAccountStorage *storage);
gboolean            mcp_account_storage_get             (const McpAccountStorage *storage,
                                                         McpAccountManager *am,
                                                         const gchar *account,
                                                         const gchar *key);
gboolean            mcp_account_storage_set             (const McpAccountStorage *storage,
                                                         const McpAccountManager *am,
                                                         const gchar *account,
                                                         const gchar *key,
                                                         const gchar *val);
gboolean            mcp_account_storage_delete          (const McpAccountStorage *storage,
                                                         const McpAccountManager *am,
                                                         const gchar *account,
                                                         const gchar *key);
void                mcp_account_storage_ready           (const McpAccountStorage *storage,
                                                         const McpAccountManager *am);
gboolean            mcp_account_storage_commit          (const McpAccountStorage *storage,
                                                         const McpAccountManager *am);
gboolean            mcp_account_storage_commit_one      (const McpAccountStorage *storage,
                                                         const McpAccountManager *am,
                                                         const gchar *account);
GList *             mcp_account_storage_list            (const McpAccountStorage *storage,
                                                         const McpAccountManager *am);
void                mcp_account_storage_get_identifier  (const McpAccountStorage *storage,
                                                         const gchar *account,
                                                         GValue *identifier);
GHashTable *        mcp_account_storage_get_additional_info
                                                        (const McpAccountStorage *storage,
                                                         const gchar *account);
guint               mcp_account_storage_get_restrictions
                                                        (const McpAccountStorage *storage,
                                                         const gchar *account);
const gchar *       mcp_account_storage_name            (const McpAccountStorage *storage);
const gchar *       mcp_account_storage_description     (const McpAccountStorage *storage);
const gchar *       mcp_account_storage_provider        (const McpAccountStorage *storage);

Object Hierarchy

  GInterface
   +----McpAccountStorage

Prerequisites

McpAccountStorage requires GObject.

Signals

  "altered"                                        : Run Last
  "altered-one"                                    : Run Last
  "created"                                        : Run Last
  "deleted"                                        : Run Last
  "toggled"                                        : Run Last

Description

Plugins may implement McpAccountStorage in order to provide account parameter storage backends to the AccountManager object.

To do so, the plugin must implement a GObject subclass that implements McpAccountStorage, then return an instance of that subclass from mcp_plugin_ref_nth_object().

The contents of the McpAccountStorage struct are not public, so to provide an implementation of the virtual methods, plugins should call mcp_account_operation_iface_implement_*() from the interface initialization function, like this:

Example 1. 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
G_DEFINE_TYPE_WITH_CODE (APlugin, a_plugin,
   G_TYPE_OBJECT,
   G_IMPLEMENT_INTERFACE (...);
   G_IMPLEMENT_INTERFACE (MCP_TYPE_ACCOUNT_STORAGE,
     account_storage_iface_init));
/* ... */
static void
account_storage_iface_init (McpAccountStorageIface *iface,
    gpointer unused G_GNUC_UNUSED)
{
  mcp_account_storage_iface_set_priority (iface, 0);
  mcp_account_storage_iface_set_name (iface, "foo")
  mcp_account_storage_iface_set_desc (iface, "The FOO storage backend");
  mcp_account_storage_iface_set_provider (iface,
    "org.freedesktop.Telepathy.MissionControl5.FooStorage");
  mcp_account_storage_iface_implement_get    (iface, _plugin_getval);
  mcp_account_storage_iface_implement_set    (iface, _plugin_setval);
  mcp_account_storage_iface_implement_delete (iface, _plugin_delete);
  mcp_account_storage_iface_implement_commit (iface, _plugin_commit);
  mcp_account_storage_iface_implement_commit_one (iface, _plugin_commit_one);
  mcp_account_storage_iface_implement_list   (iface, _plugin_list);
  mcp_account_storage_iface_implement_ready  (iface, _plugin_ready);
  mcp_account_storage_iface_implement_get_identifier (iface,
    _plugin_get_identifier);
  mcp_account_storage_iface_implement_get_additional_info (iface,
    _plugin_get_additional_info);
  mcp_account_storage_iface_implement_get_restrictions (iface,
    _plugin_get_restrictions);
/* ... */
}


A single object can implement more than one interface; It is currently unlikely that you would find it useful to implement anything other than an account storage plugin in an account storage object, though.

Details

MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_READONLY

#define MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_READONLY -1

MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_DEFAULT

#define MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_DEFAULT   0

MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_NORMAL

#define MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_NORMAL    100

MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_KEYRING

#define MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_KEYRING   10000

McpAccountStorage

typedef struct _McpAccountStorage McpAccountStorage;

McpAccountStorageIface

typedef struct _McpAccountStorageIface McpAccountStorageIface;

mcp_account_storage_iface_set_priority ()

void                mcp_account_storage_iface_set_priority
                                                        (McpAccountStorageIface *iface,
                                                         guint prio);

iface :

prio :

mcp_account_storage_iface_set_name ()

void                mcp_account_storage_iface_set_name  (McpAccountStorageIface *iface,
                                                         const gchar *name);

iface :

name :

mcp_account_storage_iface_set_desc ()

void                mcp_account_storage_iface_set_desc  (McpAccountStorageIface *iface,
                                                         const gchar *desc);

iface :

desc :

mcp_account_storage_iface_set_provider ()

void                mcp_account_storage_iface_set_provider
                                                        (McpAccountStorageIface *iface,
                                                         const gchar *provider);

iface :

provider :

mcp_account_storage_iface_implement_get ()

void                mcp_account_storage_iface_implement_get
                                                        (McpAccountStorageIface *iface,
                                                         gboolean (method const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *) ());

iface :

 @ const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *: @ const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *: @ const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *:

mcp_account_storage_iface_implement_set ()

void                mcp_account_storage_iface_implement_set
                                                        (McpAccountStorageIface *iface,
                                                         gboolean (method const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *, const gchar *) ());

iface :

 @ const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *, const gchar *: @ const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *, const gchar *: @ const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *, const gchar *:

mcp_account_storage_iface_implement_delete ()

void                mcp_account_storage_iface_implement_delete
                                                        (McpAccountStorageIface *iface,
                                                         gboolean (method const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *) ());

iface :

 @ const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *: @ const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *: @ const McpAccountStorage *, const McpAccountManager *, const gchar *, const gchar *:

mcp_account_storage_iface_implement_list ()

void                mcp_account_storage_iface_implement_list
                                                        (McpAccountStorageIface *iface,
                                                         GList* (method const McpAccountStorage *, const McpAccountManager *) ());

iface :

 @ const McpAccountStorage *, const McpAccountManager *: @ const McpAccountStorage *, const McpAccountManager *: @ const McpAccountStorage *, const McpAccountManager *:

mcp_account_storage_iface_implement_commit ()

void                mcp_account_storage_iface_implement_commit
                                                        (McpAccountStorageIface *iface,
                                                         gboolean (method const McpAccountStorage *, const McpAccountManager *) ());

iface :

 @ const McpAccountStorage *, const McpAccountManager *: @ const McpAccountStorage *, const McpAccountManager *: @ const McpAccountStorage *, const McpAccountManager *:

mcp_account_storage_iface_implement_commit_one ()

void                mcp_account_storage_iface_implement_commit_one
                                                        (McpAccountStorageIface *iface,
                                                         gboolean (method const McpAccountStorage *, const McpAccountManager *, const gchar *) ());

iface :

 @ const McpAccountStorage *, const McpAccountManager *, const gchar *: @ const McpAccountStorage *, const McpAccountManager *, const gchar *: @ const McpAccountStorage *, const McpAccountManager *, const gchar *:

mcp_account_storage_iface_implement_ready ()

void                mcp_account_storage_iface_implement_ready
                                                        (McpAccountStorageIface *iface,
                                                         void (method const McpAccountStorage *storage, const McpAccountManager *am) ());

iface :

 @ const McpAccountStorage *storage, const McpAccountManager *am: @ const McpAccountStorage *storage, const McpAccountManager *am: @ const McpAccountStorage *storage, const McpAccountManager *am:

mcp_account_storage_iface_implement_get_identifier ()

void                mcp_account_storage_iface_implement_get_identifier
                                                        (McpAccountStorageIface *iface,
                                                         void (method const McpAccountStorage *, const gchar *, GValue *) ());

iface :

 @ const McpAccountStorage *, const gchar *, GValue *: @ const McpAccountStorage *, const gchar *, GValue *: @ const McpAccountStorage *, const gchar *, GValue *:

mcp_account_storage_iface_implement_get_additional_info ()

void                mcp_account_storage_iface_implement_get_additional_info
                                                        (McpAccountStorageIface *iface,
                                                         GHashTable* (method const McpAccountStorage *, const gchar *) ());

iface :

 @ const McpAccountStorage *, const gchar *: @ const McpAccountStorage *, const gchar *: @ const McpAccountStorage *, const gchar *:

mcp_account_storage_iface_implement_get_restrictions ()

void                mcp_account_storage_iface_implement_get_restrictions
                                                        (McpAccountStorageIface *iface,
                                                         guint (method const McpAccountStorage *, const gchar *) ());

iface :

 @ const McpAccountStorage *, const gchar *: @ const McpAccountStorage *, const gchar *: @ const McpAccountStorage *, const gchar *:

mcp_account_storage_priority ()

gint                mcp_account_storage_priority        (const McpAccountStorage *storage);

storage :

 an McpAccountStorage instance

Returns :

 a gint indicating the priority of the plugin. Priorities currently run from MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_DEFAULT (the default storage plugin priority) upwards. Plugins at a higher priority then MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_KEYRING will have the opportunity to "steal" passwords from the gnome keyring: Plugins at a lower priority than this will not receive secret parameters from MC as the keyring plugin will already have claimed them. Plugins at a lower priority than the default plugin will never be asked to store any details, although they may still be asked to list them at startup time, and may asynchronously notify MC of accounts via the signals above. When loading accounts at startup, plugins are consulted in order from lowest to highest, so that higher priority plugins may overrule settings from lower priority plugins. Loading all the accounts is only done at startup, before the dbus name is claimed, and is therefore the only time plugins are allowed to indulge in blocking calls (indeed, they are expected to carry out this operation, and ONLY this operation, synchronously). When values are being set, the plugins are invoked from highest priority to lowest, with the first plugin that claims a setting being assigned ownership, and all lower priority plugins being asked to delete the setting in question.

mcp_account_storage_get ()

gboolean            mcp_account_storage_get             (const McpAccountStorage *storage,
                                                         McpAccountManager *am,
                                                         const gchar *account,
                                                         const gchar *key);

The plugin is expected to quickly and synchronously update the value associated with key using calls to am.

The plugin is not required to consult whatever long term storage it uses, and may fetch said value from its internal cache, if any.

If key is NULL the plugin should write all its settings for account into the account manager via am. The return value in this case should be TRUE if any settings were found.

storage :

 an McpAccountStorage instance

am :

 an McpAccountManager instance

account :

 the unique name of the account

key :

 the setting whose value we wish to fetch

Returns :

 a gboolean - TRUE if a value was found and FALSE otherwise

mcp_account_storage_set ()

gboolean            mcp_account_storage_set             (const McpAccountStorage *storage,
                                                         const McpAccountManager *am,
                                                         const gchar *account,
                                                         const gchar *key,
                                                         const gchar *val);

The plugin is expected to either quickly and synchronously update its internal cache of values with value, or to decline to store the setting.

The plugin is not expected to write to its long term storage at this point.

storage :

 an McpAccountStorage instance

am :

 an McpAccountManager instance

account :

 the unique name of the account

key :

 the setting whose value we wish to fetch

val :

Returns :

 a gboolean - TRUE if the setting was claimed, FALSE otherwise

mcp_account_storage_delete ()

gboolean            mcp_account_storage_delete          (const McpAccountStorage *storage,
                                                         const McpAccountManager *am,
                                                         const gchar *account,
                                                         const gchar *key);

The plugin is expected to remove the setting for key from its internal cache and to remember that its state has changed, so that it can delete said setting from its long term storage if its long term storage method makes this necessary.

If key is NULL, the plugin should forget all its settings for account (and remember to delete account from its storage later)

The plugin is not expected to update its long term storage at this point.

storage :

 an McpAccountStorage instance

am :

 an McpAccountManager instance

account :

 the unique name of the account

key :

 the setting whose value we wish to fetch

Returns :

 a gboolean - TRUE if the setting or settings are not the plugin's cache after this operation, FALSE otherwise. This is very unlikely to ever be FALSE, as a plugin is always expected to be able to manipulate its own cache.

mcp_account_storage_ready ()

void                mcp_account_storage_ready           (const McpAccountStorage *storage,
                                                         const McpAccountManager *am);

Informs the plugin that it is now permitted to create new accounts, ie it can now fire its "created", "altered", "toggled" and "deleted" signals.

storage :

 an McpAccountStorage instance

am :

mcp_account_storage_commit ()

gboolean            mcp_account_storage_commit          (const McpAccountStorage *storage,
                                                         const McpAccountManager *am);

The plugin is expected to write its cache to long term storage, deleting, adding or updating entries in said storage as needed.

This call is expected to return promptly, but the plugin is not required to have finished its commit operation when it returns, merely to have started the operation.

If the commit_one method is implemented, it will be called preferentially if only one account is to be committed. If the commit_one method is implemented but commit is not, commit_one will be called with account_name = NULL to commit all accounts.

storage :

 an McpAccountStorage instance

am :

 an McpAccountManager instance

Returns :

 a gboolean - normally TRUE, FALSE if there was a problem that was immediately obvious.

mcp_account_storage_commit_one ()

gboolean            mcp_account_storage_commit_one      (const McpAccountStorage *storage,
                                                         const McpAccountManager *am,
                                                         const gchar *account);

The same as mcp_account_storage_commit(), but only commit the given account. This is optional to implement; the default implementation is to call commit.

storage :

 an McpAccountStorage instance

am :

 an McpAccountManager instance

account :

 the unique suffix of an account's object path, or NULL if all accounts are to be committed

Returns :

 a gboolean - normally TRUE, FALSE if there was a problem that was immediately obvious.

mcp_account_storage_list ()

GList *             mcp_account_storage_list            (const McpAccountStorage *storage,
                                                         const McpAccountManager *am);

This method is called only at initialisation time, before the dbus name has been claimed, and is the only one permitted to block.

storage :

 an McpAccountStorage instance

am :

 an McpAccountManager instance

Returns :

 a GList of gchar* (the unique account names) that the plugin has settings for. The GList (and its contents) should be freed when the caller is done with them.

mcp_account_storage_get_identifier ()

void                mcp_account_storage_get_identifier  (const McpAccountStorage *storage,
                                                         const gchar *account,
                                                         GValue *identifier);

Get the storage-specific identifier for this account. The type is variant, hence the GValue.

storage :

 an McpAccountStorage instance

account :

 the unique name of the account

identifier :

 a zero-filled GValue whose type can be sent over D-Bus by dbus-glib to hold the identifier.

mcp_account_storage_get_additional_info ()

GHashTable *        mcp_account_storage_get_additional_info
                                                        (const McpAccountStorage *storage,
                                                         const gchar *account);

Return additional storage-specific information about this account, which is made available on D-Bus but not otherwise interpreted by Mission Control.

storage :

 an McpAccountStorage instance

account :

 the unique name of the account

Returns :

 a caller owned GHashTable mapping with string keys and GValue values.

mcp_account_storage_get_restrictions ()

guint               mcp_account_storage_get_restrictions
                                                        (const McpAccountStorage *storage,
                                                         const gchar *account);

storage :

 an McpAccountStorage instance

account :

 the unique name of the account

Returns :

 a bitmask of TpStorageRestrictionFlags with the restrictions to account storage.

mcp_account_storage_name ()

const gchar *       mcp_account_storage_name            (const McpAccountStorage *storage);

storage :

 an McpAccountStorage instance

Returns :

 a const gchar* : the plugin's name (for logging etc)

mcp_account_storage_description ()

const gchar *       mcp_account_storage_description     (const McpAccountStorage *storage);

storage :

 an McpAccountStorage instance

Returns :

 a const gchar* : the plugin's description (for logging etc)

mcp_account_storage_provider ()

const gchar *       mcp_account_storage_provider        (const McpAccountStorage *storage);

storage :

 an McpAccountStorage instance

Returns :

 a const gchar* : the plugin's provider, a DBus namespaced name for this plugin.

Signal Details

The "altered" signal

void                user_function                      (McpAccountStorage *account,
                                                        gchar             *arg1,
                                                        gpointer           user_data)      : Run Last

emitted if an external entity alters an account in the backend the emitting plugin handles should not be emitted if a single known property has been altered, see McpAccountStorage::altered-one instead

Should not be fired until mcp_account_storage_ready() has been called

account :

 the unique name of the created account

user_data :

 user data set when the signal handler was connected.

The "altered-one" signal

void                user_function                      (McpAccountStorage *account,
                                                        gchar             *name,
                                                        gchar             *arg2,
                                                        gpointer           user_data)      : Run Last

emitted if an external entity alters an account in the backend that the emitting plugin handles.

If many properties have changed, the plugin may choose to emit McpAccountStorage::altered _instead_, but should not emit both.

Should not be fired until mcp_account_storage_ready() has been called

account :

 the unique name of the created account

name :

 the name of the altered property (its key)

user_data :

 user data set when the signal handler was connected.

The "created" signal

void                user_function                      (McpAccountStorage *account,
                                                        gchar             *arg1,
                                                        gpointer           user_data)      : Run Last

emitted if an external entity creates an account in the backend the emitting plugin handles

Should not be fired until mcp_account_storage_ready() has been called

account :

 the unique name of the created account

user_data :

 user data set when the signal handler was connected.

The "deleted" signal

void                user_function                      (McpAccountStorage *account,
                                                        gchar             *arg1,
                                                        gpointer           user_data)      : Run Last

emitted if an external entity deletes an account in the backend the emitting plugin handles

Should not be fired until mcp_account_storage_ready() has been called

account :

 the unique name of the created account

user_data :

 user data set when the signal handler was connected.

The "toggled" signal

void                user_function                      (McpAccountStorage *account,
                                                        gchar             *enabled,
                                                        gboolean           arg2,
                                                        gpointer           user_data)      : Run Last

emitted if an external entity enables/disables an account in the backend the emitting plugin handles

Should not be fired until mcp_account_storage_ready() has been called

account :

 the unique name of the created account

enabled :

 gboolean indicating whether the account is enabled

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.15