McpAccountStorage: Mission Control Plugins Reference Manual

## McpAccountStorage McpAccountStorage — Account Storage object, implemented by plugins |

## Functions

gint | mcp_account_storage_priority ()
gboolean | mcp_account_storage_get ()
gboolean | mcp_account_storage_set ()
gchar * | mcp_account_storage_create ()
gboolean | mcp_account_storage_delete ()
void | mcp_account_storage_ready ()
gboolean | mcp_account_storage_commit ()
gboolean | mcp_account_storage_commit_one ()
GList * | mcp_account_storage_list ()
void | mcp_account_storage_get_identifier ()
GHashTable * | mcp_account_storage_get_additional_info ()
guint | mcp_account_storage_get_restrictions ()
const gchar * | mcp_account_storage_name ()
const gchar * | mcp_account_storage_description ()
const gchar * | mcp_account_storage_provider ()
gboolean | mcp_account_storage_owns ()
gboolean | mcp_account_storage_set_attribute ()
gboolean | mcp_account_storage_set_parameter ()
void | mcp_account_storage_emit_created ()
void | mcp_account_storage_emit_altered ()
void | mcp_account_storage_emit_altered_one ()
void | mcp_account_storage_emit_deleted ()
void | mcp_account_storage_emit_toggled ()
void | mcp_account_storage_emit_reconnect ()

## Types and Values

#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
struct | McpAccountStorage
| McpAccountStorageIface

## Includes

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

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

Many methods take "the unique name of an account" as an argument. In this plugin, that means the unique "tail" of the account's object path, for instance "gabble/jabber/chris_40example_2ecom". The account's full object path is obtained by prepending `TP_ACCOUNT_OBJECT_PATH_BASE`.

A complete implementation of this interface with all methods would look something 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
    G_DEFINE_TYPE_WITH_CODE (FooPlugin, foo_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)
    {
      iface->priority = 0;
      iface->name = "foo";
      iface->desc = "The FOO storage backend";
      iface->provider = "org.freedesktop.Telepathy.MissionControl5.FooStorage";

      iface->get = foo_plugin_get;
      iface->set = foo_plugin_get;
      iface->delete = foo_plugin_delete;
      iface->commit = foo_plugin_commit;
      iface->commit_one = foo_plugin_commit_one;
      iface->list = foo_plugin_list;
      iface->ready = foo_plugin_ready;
      iface->get_identifier = foo_plugin_get_identifier;
      iface->get_additional_info = foo_plugin_get_additional_info;
      iface->get_restrictions = foo_plugin_get_restrictions;
      iface->create = foo_plugin_create;
      iface->owns = foo_plugin_owns;
      iface->set_attribute = foo_plugin_set_attribute;
      iface->set_parameter = foo_plugin_set_parameter;
    }

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.

## Functions

### mcp_account_storage_priority ()

    gint
    mcp_account_storage_priority (const McpAccountStorage *storage);

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

Gets the priority for this plugin.

Priorities currently run from MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_DEFAULT (the default storage plugin priority) upwards. More-positive numbers are higher priority.

Plugins at a higher priority then MCP_ACCOUNT_STORAGE_PLUGIN_PRIO_KEYRING used to have the opportunity to "steal" passwords from the gnome keyring. It is no longer significant.

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.

#### Parameters

storage | an McpAccountStorage instance |

#### Returns

the priority of this plugin

### mcp_account_storage_get ()

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

Get a value from the plugin's in-memory cache. Before emitting this signal, the plugin must call either `mcp_account_manager_set_attribute()`, `mcp_account_manager_set_parameter()`, or `mcp_account_manager_set_value()` and (if appropriate) `mcp_account_manager_parameter_make_secret()` before returning from this method call.

Note that `mcp_account_manager_set_parameter()` does not use the "param-" prefix, even if called from this function.

If `key` is `NULL` the plugin should iterate through all attributes and parameters, and push each of them into `am` , as if this method had been called once for each attribute or parameter. It must then return `TRUE` if any attributes or parameters were found, or `FALSE` if it was not responsible for `account` .

#### Parameters

storage | an McpAccountStorage instance |
am | an McpAccountManager instance |
account | the unique name of the account |
key | the setting whose value we wish to fetch: either an attribute like "DisplayName", or "param-" plus a parameter like "account" |

#### Returns

`TRUE` if `storage` is responsible for `account`

### mcp_account_storage_set ()

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

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. It can expect Mission Control to call either `mcp_account_storage_commit()` or `mcp_account_storage_commit_one()` after a short delay.

Plugins that implement `mcp_storage_set_attribute()` and `mcp_account_storage_set_parameter()` can just return `FALSE` here. There is a default implementation, which just returns `FALSE`.

#### Parameters

storage | an McpAccountStorage instance |
am | an McpAccountManager instance |
account | the unique name of the account |
key | the non-`NULL` setting whose value we wish to store: either an attribute like "DisplayName", or "param-" plus a parameter like "account" |
value | a value to associate with `key` , escaped as if for a GKeyFile |

#### Returns

`TRUE` if the attribute was claimed, `FALSE` otherwise

### mcp_account_storage_create ()

    gchar *
    mcp_account_storage_create (const McpAccountStorage *storage,
                                const McpAccountManager *am,
                                const gchar *manager,
                                const gchar *protocol,
                                GHashTable *params,
                                GError **error);

Inform the plugin that a new account is being created. `manager` , `protocol` and `params` are given to help determining the account's unique name, but does not need to be stored on the account yet, `mcp_account_storage_set()` and `mcp_account_storage_commit()` will be called later.

It is recommended to use `mcp_account_manager_get_unique_name()` to create the unique name, but it's not mandatory. One could base the unique name on an internal storage identifier, prefixed with the provider's name (e.g. goa__1234).

“created” signal should not be emitted for this account, not even when `mcp_account_storage_commit()` will be called.

#### Parameters

storage | an McpAccountStorage instance |
am | an object which can be used to call back into the account manager |
manager | the name of the manager |
protocol | the name of the protocol |
params | A gchar * / GValue * hash table of account parameters |
error | a GError to fill |

#### Returns

the newly allocated account name, which should be freed once the caller is done with it, or `NULL` if that couldn't be done.

[transfer full]

### 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 the entire account from its storage later.

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

#### Parameters

storage | an McpAccountStorage instance |
am | an McpAccountManager instance |
account | the unique name of the account |
key | the setting whose value we wish to store - either an attribute like "DisplayName", or "param-" plus a parameter like "account" - or `NULL` to delete the entire account. | [allow-none]

#### Returns

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

#### Parameters

storage | an McpAccountStorage instance |
am | an McpAccountManager instance |

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

#### Parameters

storage | an McpAccountStorage instance |
am | an McpAccountManager instance |

#### Returns

`TRUE` if the commit process was started (but not necessarily completed) successfully; `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` .

If both `mcp_account_storage_commit_one()` and `mcp_account_storage_commit()` are implemented, Mission Control will never pass `account` = `NULL` to this method.

#### Parameters

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 and `mcp_account_storage_commit()` is unimplemented. | [allow-none]

#### Returns

`TRUE` if the commit process was started (but not necessarily completed) successfully; `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);

Load details of every account stored by this plugin into an in-memory cache so that it can respond to requests promptly.

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

#### Parameters

storage | an McpAccountStorage instance |
am | an McpAccountManager instance |

#### Returns

a list of account names that the plugin has settings for. The account names should be freed with `g_free()`, and the list with `g_list_free()`, when the caller is done with them.

[element-type utf8][transfer full]

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

This method will only be called for the storage plugin that "owns" the account.

#### Parameters

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. | [out caller-allocates]

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

This method will only be called for the storage plugin that "owns" the account.

#### Parameters

storage | an McpAccountStorage instance |
account | the unique name of the account |

#### Returns

additional storage-specific information.

[transfer container][element-type utf8 GObject.Value]

### mcp_account_storage_get_restrictions ()

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

This method will only be called for the storage plugin that "owns" the account.

#### Parameters

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

#### Parameters

storage | an McpAccountStorage instance |

#### Returns

the plugin's name (for logging etc)

### mcp_account_storage_description ()

    const gchar *
    mcp_account_storage_description (const McpAccountStorage *storage);

#### Parameters

storage | an McpAccountStorage instance |

#### Returns

the plugin's description (for logging etc)

### mcp_account_storage_provider ()

    const gchar *
    mcp_account_storage_provider (const McpAccountStorage *storage);

#### Parameters

storage | an McpAccountStorage instance |

#### Returns

a D-Bus namespaced name for this plugin, or "" if none was provided in McpAccountStorageIface.provider.

### mcp_account_storage_owns ()

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

Check whether `account` is stored in `storage` . The highest-priority plugin for which this function returns `TRUE` is considered to be responsible for `account` .

There is a default implementation, which calls `mcp_account_storage_get()` for the well-known key "manager".

#### Parameters

storage | an McpAccountStorage instance |
am | an McpAccountManager instance |
account | the unique name (object-path tail) of an account |

#### Returns

`TRUE` if `account` is stored in `storage`

Since: 5.15.0

### mcp_account_storage_set_attribute ()

    gboolean
    mcp_account_storage_set_attribute (McpAccountStorage *storage,
                                       McpAccountManager *am,
                                       const gchar *account,
                                       const gchar *attribute,
                                       GVariant *value,
                                       McpAttributeFlags flags);

Store an attribute.

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

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

There is a default implementation, which just returns `FALSE`. Mission Control will call `mcp_account_storage_set()` instead, using a keyfile-escaped version of `value` .

#### Parameters

storage | an McpAccountStorage instance |
am | an McpAccountManager instance |
account | the unique name of the account |
attribute | the name of an attribute, e.g. "DisplayName" |
value | a value to associate with `attribute` |
flags | flags influencing how the attribute is to be stored |

#### Returns

`TRUE` if the attribute was claimed, `FALSE` otherwise

Since: 5.15.0

### mcp_account_storage_set_parameter ()

    gboolean
    mcp_account_storage_set_parameter (McpAccountStorage *storage,
                                       McpAccountManager *am,
                                       const gchar *account,
                                       const gchar *parameter,
                                       GVariant *value,
                                       McpParameterFlags flags);

Store a parameter.

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

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

There is a default implementation, which just returns `FALSE`. Mission Control will call `mcp_account_storage_set()` instead, using "param-" + `parameter` as key and a keyfile-escaped version of `value` as value.

#### Parameters

storage | an McpAccountStorage instance |
am | an McpAccountManager instance |
account | the unique name of the account |
parameter | the name of a parameter, e.g. "account" (note that there is no "param-" prefix here) |
value | a value to associate with `parameter` |
flags | flags influencing how the parameter is to be stored |

#### Returns

`TRUE` if the parameter was claimed, `FALSE` otherwise

Since: 5.15.0

### mcp_account_storage_emit_created ()

    void
    mcp_account_storage_emit_created (McpAccountStorage *storage,
                                      const gchar *account);

### mcp_account_storage_emit_altered ()

    void
    mcp_account_storage_emit_altered (McpAccountStorage *storage,
                                      const gchar *account);

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

Emits the “altered” signal

#### Parameters

storage | an McpAccountStorage instance |
account | the unique name of the altered account |

### mcp_account_storage_emit_altered_one ()

    void
    mcp_account_storage_emit_altered_one (McpAccountStorage *storage,
                                          const gchar *account,
                                          const gchar *key);

Emits the “altered-one” signal

#### Parameters

storage | an McpAccountStorage instance |
account | the unique name of the altered account |
key | the key of the altered property: either an attribute name like "DisplayName", or "param-" plus a parameter name like "account" |

### mcp_account_storage_emit_deleted ()

    void
    mcp_account_storage_emit_deleted (McpAccountStorage *storage,
                                      const gchar *account);

Emits the “deleted” signal

#### Parameters

storage | an McpAccountStorage instance |
account | the unique name of the deleted account |

### mcp_account_storage_emit_toggled ()

    void
    mcp_account_storage_emit_toggled (McpAccountStorage *storage,
                                      const gchar *account,
                                      gboolean enabled);

Emits ::toggled signal

#### Parameters

storage | an McpAccountStorage instance |
account | the unique name of the account |
enabled | `TRUE` if the account is now enabled |

### mcp_account_storage_emit_reconnect ()

    void
    mcp_account_storage_emit_reconnect (McpAccountStorage *storage,
                                        const gchar *account);

Emits ::reconnect signal

#### Parameters

storage | an McpAccountStorage instance |
account | the unique name of the account to reconnect |

## Types and Values

### 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

### struct McpAccountStorage

    struct McpAccountStorage {
     };
    #endif

    #define MCP_TYPE_ACCOUNT_STORAGE (mcp_account_storage_get_type ())

    #define MCP_ACCOUNT_STORAGE(o) \
      (G_TYPE_CHECK_INSTANCE_CAST ((o), MCP_TYPE_ACCOUNT_STORAGE, \
          McpAccountStorage))

    #define MCP_IS_ACCOUNT_STORAGE(o) \
      (G_TYPE_CHECK_INSTANCE_TYPE ((o), MCP_TYPE_ACCOUNT_STORAGE))

    #define MCP_ACCOUNT_STORAGE_GET_IFACE(o) \
      (G_TYPE_INSTANCE_GET_INTERFACE ((o), MCP_TYPE_ACCOUNT_STORAGE, \
                                      McpAccountStorageIface))

    GType mcp_account_storage_get_type (void);

    /* Virtual method implementation signatures */
    typedef gboolean (*McpAccountStorageGetFunc) (
        const McpAccountStorage *storage,
        const McpAccountManager *am,
        const gchar *account,
        const gchar *key);
    typedef gboolean (*McpAccountStorageSetFunc) (
        const McpAccountStorage *storage,
        const McpAccountManager *am,
        const gchar *account,
        const gchar *key,
        const gchar *val);
    typedef gchar * (*McpAccountStorageCreate) (
        const McpAccountStorage *storage,
        const McpAccountManager *am,
        const gchar *manager,
        const gchar *protocol,
        GHashTable *params,
        GError **error);
    typedef gboolean (*McpAccountStorageDeleteFunc) (
        const McpAccountStorage *storage,
        const McpAccountManager *am,
        const gchar *account,
        const gchar *key);
    typedef GList * (*McpAccountStorageListFunc) (
        const McpAccountStorage *storage,
        const McpAccountManager *am);
    typedef gboolean (*McpAccountStorageCommitFunc) (
        const McpAccountStorage *storage,
        const McpAccountManager *am);
    typedef gboolean (*McpAccountStorageCommitOneFunc) (
        const McpAccountStorage *storage,
        const McpAccountManager *am,
        const gchar *account);
    typedef void (*McpAccountStorageReadyFunc) (
        const McpAccountStorage *storage,
        const McpAccountManager *am);
    typedef void (*McpAccountStorageGetIdentifierFunc) (
        const McpAccountStorage *storage,
        const gchar *account,
        GValue *identifier);
    typedef GHashTable * (*McpAccountStorageGetAdditionalInfoFunc) (
        const McpAccountStorage *storage,
        const gchar *account);
    /* FIXME: when breaking API, make this return TpStorageRestrictionFlags */
    typedef guint (*McpAccountStorageGetRestrictionsFunc) (
        const McpAccountStorage *storage,
        const gchar *account);

    struct _McpAccountStorageIface
    {
      GTypeInterface parent;

      gint priority;
      const gchar *name;
      const gchar *desc;
      const gchar *provider;

      McpAccountStorageSetFunc set;
      McpAccountStorageGetFunc get;
      McpAccountStorageDeleteFunc delete;
      McpAccountStorageCommitFunc commit;
      McpAccountStorageListFunc list;
      McpAccountStorageReadyFunc ready;
      McpAccountStorageCommitOneFunc commit_one;
      McpAccountStorageGetIdentifierFunc get_identifier;
      McpAccountStorageGetAdditionalInfoFunc get_additional_info;
      McpAccountStorageGetRestrictionsFunc get_restrictions;
      McpAccountStorageCreate create;

      /* Since 5.15.0 */
      gboolean (*owns) (McpAccountStorage *storage,
          McpAccountManager *am,
          const gchar *account);
      gboolean (*set_attribute) (McpAccountStorage *storage,
          McpAccountManager *am,
          const gchar *account,
          const gchar *attribute,
          GVariant *val,
          McpAttributeFlags flags);
      gboolean (*set_parameter) (McpAccountStorage *storage,
          McpAccountManager *am,
          const gchar *account,
          const gchar *parameter,
          GVariant *val,
          McpParameterFlags flags);
    };

An object implementing the account storage plugin interface.

### McpAccountStorageIface

    typedef struct _McpAccountStorageIface McpAccountStorageIface;

The interface vtable for an account storage plugin.

#### Members