SecretService

SecretService — the Secret Service

Synopsis

#include <libsecret/secret.h>

struct              SecretService;
struct              SecretServiceClass;
enum                SecretServiceFlags;
void                secret_service_get                  (SecretServiceFlags flags,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
SecretService *     secret_service_get_sync             (SecretServiceFlags flags,
                                                         GCancellable *cancellable,
                                                         GError **error);
SecretService *     secret_service_get_finish           (GAsyncResult *result,
                                                         GError **error);
void                secret_service_disconnect           (void);
void                secret_service_new                  (GType service_gtype,
                                                         const gchar *service_bus_name,
                                                         SecretServiceFlags flags,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
SecretService *     secret_service_new_finish           (GAsyncResult *result,
                                                         GError **error);
SecretService *     secret_service_new_sync             (GType service_gtype,
                                                         const gchar *service_bus_name,
                                                         SecretServiceFlags flags,
                                                         GCancellable *cancellable,
                                                         GError **error);
GList *             secret_service_get_collections      (SecretService *self);
SecretServiceFlags  secret_service_get_flags            (SecretService *self);
const gchar *       secret_service_get_session_algorithms
                                                        (SecretService *self);
void                secret_service_ensure_session       (SecretService *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            secret_service_ensure_session_finish
                                                        (SecretService *self,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            secret_service_ensure_session_sync  (SecretService *self,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                secret_service_load_collections     (SecretService *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            secret_service_load_collections_finish
                                                        (SecretService *self,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            secret_service_load_collections_sync
                                                        (SecretService *self,
                                                         GCancellable *cancellable,
                                                         GError **error);
enum                SecretSearchFlags;
void                secret_service_search               (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         SecretSearchFlags flags,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GList *             secret_service_search_finish        (SecretService *service,
                                                         GAsyncResult *result,
                                                         GError **error);
GList *             secret_service_search_sync          (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         SecretSearchFlags flags,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                secret_service_lock                 (SecretService *service,
                                                         GList *objects,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gint                secret_service_lock_finish          (SecretService *service,
                                                         GAsyncResult *result,
                                                         GList **locked,
                                                         GError **error);
gint                secret_service_lock_sync            (SecretService *service,
                                                         GList *objects,
                                                         GCancellable *cancellable,
                                                         GList **locked,
                                                         GError **error);
void                secret_service_unlock               (SecretService *service,
                                                         GList *objects,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gint                secret_service_unlock_finish        (SecretService *service,
                                                         GAsyncResult *result,
                                                         GList **unlocked,
                                                         GError **error);
gint                secret_service_unlock_sync          (SecretService *service,
                                                         GList *objects,
                                                         GCancellable *cancellable,
                                                         GList **unlocked,
                                                         GError **error);
void                secret_service_store                (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         const gchar *collection,
                                                         const gchar *label,
                                                         SecretValue *value,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            secret_service_store_finish         (SecretService *service,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            secret_service_store_sync           (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         const gchar *collection,
                                                         const gchar *label,
                                                         SecretValue *value,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                secret_service_lookup               (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
SecretValue *       secret_service_lookup_finish        (SecretService *service,
                                                         GAsyncResult *result,
                                                         GError **error);
SecretValue *       secret_service_lookup_sync          (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                secret_service_clear                (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            secret_service_clear_finish         (SecretService *service,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            secret_service_clear_sync           (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                secret_service_prompt               (SecretService *self,
                                                         SecretPrompt *prompt,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GVariant *          secret_service_prompt_finish        (SecretService *self,
                                                         GAsyncResult *result,
                                                         const GVariantType *return_type,
                                                         GError **error);
GVariant *          secret_service_prompt_sync          (SecretService *self,
                                                         SecretPrompt *prompt,
                                                         GCancellable *cancellable,
                                                         const GVariantType *return_type,
                                                         GError **error);
void                secret_service_set_alias            (SecretService *service,
                                                         const gchar *alias,
                                                         SecretCollection *collection,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            secret_service_set_alias_finish     (SecretService *service,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            secret_service_set_alias_sync       (SecretService *service,
                                                         const gchar *alias,
                                                         SecretCollection *collection,
                                                         GCancellable *cancellable,
                                                         GError **error);

Object Hierarchy

  GObject
   +----GDBusProxy
         +----SecretService
  GFlags
   +----SecretServiceFlags

Implemented Interfaces

SecretService implements GDBusInterface, GInitable and GAsyncInitable.

Properties

  "collections"              SecretObjectList*     : Read
  "flags"                    SecretServiceFlags    : Read / Write / Construct Only

Description

A SecretService object represents the Secret Service implementation which runs as a D-Bus service.

Normally a single SecretService object can be shared between multiple callers. The secret_service_get() method is used to access this SecretService object. If a new independent SecretService object is required, use secret_service_new().

In order to securely transfer secrets to the Sercret Service, an session is established. This session can be established while initializing a SecretService object by passing the SECRET_SERVICE_OPEN_SESSION flag to the secret_service_get() or secret_service_new() functions. In order to establish a session on an already existing SecretService, use the secret_service_ensure_session() function.

To search for items, use the secret_service_search() method.

Multiple collections can exist in the Secret Service, each of which contains secret items. In order to instantiate SecretCollection objects which represent those collections while initializing a SecretService then pass the SECRET_SERVICE_LOAD_COLLECTIONS flag to the secret_service_get() or secret_service_new() functions. In order to establish a session on an already existing SecretService, use the secret_service_load_collections() function. To access the list of collections use secret_service_get_collections().

Certain actions on the Secret Service require user prompting to complete, such as creating a collection, or unlocking a collection. When such a prompt is necessary, then a SecretPrompt object is created by this library, and passed to the secret_service_prompt() method. In this way it is handled automatically.

In order to customize prompt handling, override the prompt_async and prompt_finish virtual methods of the SecretService class.

These functions have an unstable API and may change across versions. Use libsecret-unstable package to access them.

Details

struct SecretService

struct SecretService;

A proxy object representing the Secret Service.


struct SecretServiceClass

struct SecretServiceClass {
	GDBusProxyClass parent_class;

	GType collection_gtype;
	GType item_gtype;

	GVariant *  (* prompt_sync)      (SecretService *self,
	                                  SecretPrompt *prompt,
	                                  GCancellable *cancellable,
	                                  const GVariantType *return_type,
	                                  GError **error);

	void        (* prompt_async)     (SecretService *self,
	                                  SecretPrompt *prompt,
	                                  GCancellable *cancellable,
	                                  GAsyncReadyCallback callback,
	                                  gpointer user_data);

	GVariant *  (* prompt_finish)    (SecretService *self,
	                                  GAsyncResult *result,
	                                  const GVariantType *return_type,
	                                  GError **error);
};

The class for SecretService.

GDBusProxyClass parent_class;

the parent class

GType collection_gtype;

the GType of the SecretCollection objects instantiated by the SecretService proxy

GType item_gtype;

the GType of the SecretItem objects instantiated by the SecretService proxy

prompt_sync ()

called to perform synchronous prompting when necessary

prompt_async ()

called to perform asynchronous prompting when necessary

prompt_finish ()

called to complete an asynchronous prompt operation

enum SecretServiceFlags

typedef enum {
	SECRET_SERVICE_NONE = 0,
	SECRET_SERVICE_OPEN_SESSION = 1 << 1,
	SECRET_SERVICE_LOAD_COLLECTIONS = 1 << 2,
} SecretServiceFlags;

Flags which determine which parts of the SecretService proxy are initialized during a secret_service_get() or secret_service_new() operation.

SECRET_SERVICE_NONE

no flags for initializing the SecretService

SECRET_SERVICE_OPEN_SESSION

establish a session for transfer of secrets while initializing the SecretService

SECRET_SERVICE_LOAD_COLLECTIONS

load collections while initializing the SecretService

secret_service_get ()

void                secret_service_get                  (SecretServiceFlags flags,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Get a SecretService proxy for the Secret Service. If such a proxy object already exists, then the same proxy is returned.

If flags contains any flags of which parts of the secret service to ensure are initialized, then those will be initialized before completing.

This method will return immediately and complete asynchronously.

flags :

flags for which service functionality to ensure is initialized

cancellable :

optional cancellation object

callback :

called when the operation completes

user_data :

data to be passed to the callback

secret_service_get_sync ()

SecretService *     secret_service_get_sync             (SecretServiceFlags flags,
                                                         GCancellable *cancellable,
                                                         GError **error);

Get a SecretService proxy for the Secret Service. If such a proxy object already exists, then the same proxy is returned.

If flags contains any flags of which parts of the secret service to ensure are initialized, then those will be initialized before returning.

This method may block indefinitely and should not be used in user interface threads.

flags :

flags for which service functionality to ensure is initialized

cancellable :

optional cancellation object

error :

location to place an error on failure

Returns :

a new reference to a SecretService proxy, which should be released with g_object_unref(). [transfer full]

secret_service_get_finish ()

SecretService *     secret_service_get_finish           (GAsyncResult *result,
                                                         GError **error);

Complete an asynchronous operation to get a SecretService proxy for the Secret Service.

result :

the asynchronous result passed to the callback

error :

location to place an error on failure

Returns :

a new reference to a SecretService proxy, which should be released with g_object_unref(). [transfer full]

secret_service_disconnect ()

void                secret_service_disconnect           (void);

Disconnect the default SecretService proxy returned by secret_service_get() and secret_service_get_sync().

It is not necessary to call this function, but you may choose to do so at program exit. It is useful for testing that memory is not leaked.

This function is safe to call at any time. But if other objects in this library are still referenced, then this will not result in all memory being freed.


secret_service_new ()

void                secret_service_new                  (GType service_gtype,
                                                         const gchar *service_bus_name,
                                                         SecretServiceFlags flags,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Create a new SecretService proxy for the Secret Service.

This function is rarely used, see secret_service_get() instead.

The service_gtype argument should be set to SECRET_TYPE_SERVICE or a the type of a derived class.

If flags contains any flags of which parts of the secret service to ensure are initialized, then those will be initialized before returning.

If service_bus_name is NULL then the default is used.

This method will return immediately and complete asynchronously.

service_gtype :

the GType of the new secret service

service_bus_name :

the D-Bus service name of the secret service. [allow-none]

flags :

flags for which service functionality to ensure is initialized

cancellable :

optional cancellation object

callback :

called when the operation completes

user_data :

data to be passed to the callback

secret_service_new_finish ()

SecretService *     secret_service_new_finish           (GAsyncResult *result,
                                                         GError **error);

Complete an asynchronous operation to create a new SecretService proxy for the Secret Service.

result :

the asynchronous result passed to the callback

error :

location to place an error on failure

Returns :

a new reference to a SecretService proxy, which should be released with g_object_unref(). [transfer full]

secret_service_new_sync ()

SecretService *     secret_service_new_sync             (GType service_gtype,
                                                         const gchar *service_bus_name,
                                                         SecretServiceFlags flags,
                                                         GCancellable *cancellable,
                                                         GError **error);

Create a new SecretService proxy for the Secret Service.

This function is rarely used, see secret_service_get_sync() instead.

The service_gtype argument should be set to SECRET_TYPE_SERVICE or a the type of a derived class.

If flags contains any flags of which parts of the secret service to ensure are initialized, then those will be initialized before returning.

If service_bus_name is NULL then the default is used.

This method may block indefinitely and should not be used in user interface threads.

service_gtype :

the GType of the new secret service

service_bus_name :

the D-Bus service name of the secret service. [allow-none]

flags :

flags for which service functionality to ensure is initialized

cancellable :

optional cancellation object

error :

location to place an error on failure

Returns :

a new reference to a SecretService proxy, which should be released with g_object_unref(). [transfer full]

secret_service_get_collections ()

GList *             secret_service_get_collections      (SecretService *self);

Get a list of SecretCollection objects representing all the collections in the secret service.

If the SECRET_SERVICE_LOAD_COLLECTIONS flag was not specified when initializing SecretService proxy object, then this method will return NULL. Use secret_service_load_collections() to load the collections.

self :

the secret service proxy

Returns :

a list of the collections in the secret service. [transfer full][element-type SecretUnstable.Collection][allow-none]

secret_service_get_flags ()

SecretServiceFlags  secret_service_get_flags            (SecretService *self);

Get the flags representing what features of the SecretService proxy have been initialized.

Use secret_service_ensure_session() or secret_service_load_collections() to initialize further features and change the flags.

self :

the secret service proxy

Returns :

the flags for features initialized

secret_service_get_session_algorithms ()

const gchar *       secret_service_get_session_algorithms
                                                        (SecretService *self);

Get the set of algorithms being used to transfer secrets between this secret service proxy and the Secret Service itself.

This will be NULL if no session has been established. Use secret_service_ensure_session() to establish a session.

self :

the secret service proxy

Returns :

a string representing the algorithms for transferring secrets. [allow-none]

secret_service_ensure_session ()

void                secret_service_ensure_session       (SecretService *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Ensure that the SecretService proxy has established a session with the Secret Service. This session is used to transfer secrets.

It is not normally necessary to call this method, as the session is established as necessary. You can also pass the SECRET_SERVICE_OPEN_SESSION to secret_service_get() in order to ensure that a session has been established by the time you get the SecretService proxy.

This method will return immediately and complete asynchronously.

self :

the secret service

cancellable :

optional cancellation object

callback :

called when the operation completes

user_data :

data to be passed to the callback

secret_service_ensure_session_finish ()

gboolean            secret_service_ensure_session_finish
                                                        (SecretService *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finish an asynchronous operation to ensure that the SecretService proxy has established a session with the Secret Service.

self :

the secret service

result :

the asynchronous result passed to the callback

error :

location to place an error on failure

Returns :

whether a session is established or not

secret_service_ensure_session_sync ()

gboolean            secret_service_ensure_session_sync  (SecretService *self,
                                                         GCancellable *cancellable,
                                                         GError **error);

Ensure that the SecretService proxy has established a session with the Secret Service. This session is used to transfer secrets.

It is not normally necessary to call this method, as the session is established as necessary. You can also pass the SECRET_SERVICE_OPEN_SESSION to secret_service_get_sync() in order to ensure that a session has been established by the time you get the SecretService proxy.

This method may block indefinitely and should not be used in user interface threads.

self :

the secret service

cancellable :

optional cancellation object

error :

location to place an error on failure

Returns :

whether a session is established or not

secret_service_load_collections ()

void                secret_service_load_collections     (SecretService *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Ensure that the SecretService proxy has loaded all the collections present in the Secret Service. This affects the result of secret_service_get_collections().

You can also pass the SECRET_SERVICE_LOAD_COLLECTIONS to secret_service_get_sync() in order to ensure that the collections have been loaded by the time you get the SecretService proxy.

This method will return immediately and complete asynchronously.

self :

the secret service

cancellable :

optional cancellation object

callback :

called when the operation completes

user_data :

data to be passed to the callback

secret_service_load_collections_finish ()

gboolean            secret_service_load_collections_finish
                                                        (SecretService *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Complete an asynchronous operation to ensure that the SecretService proxy has loaded all the collections present in the Secret Service.

self :

the secret service

result :

the asynchronous result passed to the callback

error :

location to place an error on failure

Returns :

whether the load was successful or not

secret_service_load_collections_sync ()

gboolean            secret_service_load_collections_sync
                                                        (SecretService *self,
                                                         GCancellable *cancellable,
                                                         GError **error);

Ensure that the SecretService proxy has loaded all the collections present in the Secret Service. This affects the result of secret_service_get_collections().

You can also pass the SECRET_SERVICE_LOAD_COLLECTIONS to secret_service_get_sync() in order to ensure that the collections have been loaded by the time you get the SecretService proxy.

This method may block indefinitely and should not be used in user interface threads.

self :

the secret service

cancellable :

optional cancellation object

error :

location to place an error on failure

Returns :

whether the load was successful or not

enum SecretSearchFlags

typedef enum {
	SECRET_SEARCH_NONE = 0,
	SECRET_SEARCH_ALL = 1 << 1,
	SECRET_SEARCH_UNLOCK = 1 << 2,
	SECRET_SEARCH_LOAD_SECRETS = 1 << 3,
} SecretSearchFlags;

Various flags to be used with secret_service_search() and secret_service_search_sync().

SECRET_SEARCH_NONE

no flags

SECRET_SEARCH_ALL

all the items matching the search will be returned, instead of just the first one

SECRET_SEARCH_UNLOCK

unlock locked items while searching

SECRET_SEARCH_LOAD_SECRETS

while searching load secrets for items that are not locked

secret_service_search ()

void                secret_service_search               (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         SecretSearchFlags flags,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Search for items matching the attributes. All collections are searched. The attributes should be a table of string keys and string values.

If service is NULL, then secret_service_get() will be called to get the default SecretService proxy.

If SECRET_SEARCH_ALL is set in flags, then all the items matching the search will be returned. Otherwise only the first item will be returned. This is almost always the unlocked item that was most recently stored.

If SECRET_SEARCH_UNLOCK is set in flags, then items will be unlocked if necessary. In either case, locked and unlocked items will match the search and be returned. If the unlock fails, the search does not fail.

If SECRET_SEARCH_LOAD_SECRETS is set in flags, then the items will have their secret values loaded and available via secret_item_get_secret().

This function returns immediately and completes asynchronously.

service :

the secret service. [allow-none]

schema :

the schema for the attributes. [allow-none]

attributes :

search for items matching these attributes. [element-type utf8 utf8]

flags :

search option flags

cancellable :

optional cancellation object

callback :

called when the operation completes

user_data :

data to pass to the callback

secret_service_search_finish ()

GList *             secret_service_search_finish        (SecretService *service,
                                                         GAsyncResult *result,
                                                         GError **error);

Complete asynchronous operation to search for items.

service :

the secret service. [allow-none]

result :

asynchronous result passed to callback

error :

location to place error on failure

Returns :

a list of items that matched the search. [transfer full][element-type SecretUnstable.Item]

secret_service_search_sync ()

GList *             secret_service_search_sync          (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         SecretSearchFlags flags,
                                                         GCancellable *cancellable,
                                                         GError **error);

Search for items matching the attributes. All collections are searched. The attributes should be a table of string keys and string values.

If service is NULL, then secret_service_get_sync() will be called to get the default SecretService proxy.

If SECRET_SEARCH_ALL is set in flags, then all the items matching the search will be returned. Otherwise only the first item will be returned. This is almost always the unlocked item that was most recently stored.

If SECRET_SEARCH_UNLOCK is set in flags, then items will be unlocked if necessary. In either case, locked and unlocked items will match the search and be returned. If the unlock fails, the search does not fail.

If SECRET_SEARCH_LOAD_SECRETS is set in flags, then the items' secret values will be loaded for any unlocked items. Loaded item secret values are available via secret_item_get_secret(). If the load of a secret values fail, then the

This function may block indefinetely. Use the asynchronous version in user interface threads.

service :

the secret service. [allow-none]

schema :

the schema for the attributes. [allow-none]

attributes :

search for items matching these attributes. [element-type utf8 utf8]

flags :

search option flags

cancellable :

optional cancellation object

error :

location to place error on failure

Returns :

a list of items that matched the search. [transfer full][element-type SecretUnstable.Item]

secret_service_lock ()

void                secret_service_lock                 (SecretService *service,
                                                         GList *objects,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Lock items or collections in the secret service.

The secret service may not be able to lock items individually, and may lock an entire collection instead.

If service is NULL, then secret_service_get() will be called to get the default SecretService proxy.

This method returns immediately and completes asynchronously. The secret service may prompt the user. secret_service_prompt() will be used to handle any prompts that show up.

service :

the secret service. [allow-none]

objects :

the items or collections to lock. [element-type GLib.DBusProxy]

cancellable :

optional cancellation object

callback :

called when the operation completes

user_data :

data to pass to the callback

secret_service_lock_finish ()

gint                secret_service_lock_finish          (SecretService *service,
                                                         GAsyncResult *result,
                                                         GList **locked,
                                                         GError **error);

Complete asynchronous operation to lock items or collections in the secret service.

The secret service may not be able to lock items individually, and may lock an entire collection instead.

service :

the secret service. [allow-none]

result :

asynchronous result passed to the callback

locked :

location to place list of items or collections that were locked. [out][element-type GLib.DBusProxy][transfer full][allow-none]

error :

location to place an error on failure

Returns :

the number of items or collections that were locked

secret_service_lock_sync ()

gint                secret_service_lock_sync            (SecretService *service,
                                                         GList *objects,
                                                         GCancellable *cancellable,
                                                         GList **locked,
                                                         GError **error);

Lock items or collections in the secret service.

The secret service may not be able to lock items individually, and may lock an entire collection instead.

If service is NULL, then secret_service_get_sync() will be called to get the default SecretService proxy.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. secret_service_prompt() will be used to handle any prompts that show up.

service :

the secret service. [allow-none]

objects :

the items or collections to lock. [element-type GLib.DBusProxy]

cancellable :

optional cancellation object

locked :

location to place list of items or collections that were locked. [out][element-type GLib.DBusProxy][transfer full][allow-none]

error :

location to place an error on failure

Returns :

the number of items or collections that were locked

secret_service_unlock ()

void                secret_service_unlock               (SecretService *service,
                                                         GList *objects,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Unlock items or collections in the secret service.

The secret service may not be able to unlock items individually, and may unlock an entire collection instead.

If service is NULL, then secret_service_get() will be called to get the default SecretService proxy.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. secret_service_prompt() will be used to handle any prompts that show up.

service :

the secret service. [allow-none]

objects :

the items or collections to unlock. [element-type GLib.DBusProxy]

cancellable :

optional cancellation object

callback :

called when the operation completes

user_data :

data to pass to the callback

secret_service_unlock_finish ()

gint                secret_service_unlock_finish        (SecretService *service,
                                                         GAsyncResult *result,
                                                         GList **unlocked,
                                                         GError **error);

Complete asynchronous operation to unlock items or collections in the secret service.

The secret service may not be able to unlock items individually, and may unlock an entire collection instead.

service :

the secret service. [allow-none]

result :

asynchronous result passed to the callback

unlocked :

location to place list of items or collections that were unlocked. [out][element-type GLib.DBusProxy][transfer full][allow-none]

error :

location to place an error on failure

Returns :

the number of items or collections that were unlocked

secret_service_unlock_sync ()

gint                secret_service_unlock_sync          (SecretService *service,
                                                         GList *objects,
                                                         GCancellable *cancellable,
                                                         GList **unlocked,
                                                         GError **error);

Unlock items or collections in the secret service.

The secret service may not be able to unlock items individually, and may unlock an entire collection instead.

If service is NULL, then secret_service_get_sync() will be called to get the default SecretService proxy.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. secret_service_prompt() will be used to handle any prompts that show up.

service :

the secret service. [allow-none]

objects :

the items or collections to unlock. [element-type GLib.DBusProxy]

cancellable :

optional cancellation object

unlocked :

location to place list of items or collections that were unlocked. [out][element-type GLib.DBusProxy][transfer full][allow-none]

error :

location to place an error on failure

Returns :

the number of items or collections that were unlocked

secret_service_store ()

void                secret_service_store                (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         const gchar *collection,
                                                         const gchar *label,
                                                         SecretValue *value,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Store a secret value in the secret service.

The attributes should be a set of key and value string pairs.

If the attributes match a secret item already stored in the collection, then the item will be updated with these new values.

If service is NULL, then secret_service_get() will be called to get the default SecretService proxy.

If collection is not specified, then the default collection will be used. Use SECRET_COLLECTION_SESSION to store the password in the session collection, which doesn't get stored across login sessions.

This method will return immediately and complete asynchronously.

service :

the secret service. [allow-none]

schema :

the schema to use to check attributes. [allow-none]

attributes :

the attribute keys and values. [element-type utf8 utf8]

collection :

a collection alias, or D-Bus object path of the collection where to store the secret. [allow-none]

label :

label for the secret

value :

the secret value

cancellable :

optional cancellation object

callback :

called when the operation completes

user_data :

data to be passed to the callback

secret_service_store_finish ()

gboolean            secret_service_store_finish         (SecretService *service,
                                                         GAsyncResult *result,
                                                         GError **error);

Finish asynchronous operation to store a secret value in the secret service.

service :

the secret service. [allow-none]

result :

the asynchronous result passed to the callback

error :

location to place an error on failure

Returns :

whether the storage was successful or not

secret_service_store_sync ()

gboolean            secret_service_store_sync           (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         const gchar *collection,
                                                         const gchar *label,
                                                         SecretValue *value,
                                                         GCancellable *cancellable,
                                                         GError **error);

Store a secret value in the secret service.

The attributes should be a set of key and value string pairs.

If the attributes match a secret item already stored in the collection, then the item will be updated with these new values.

If collection is NULL, then the default collection will be used. Use SECRET_COLLECTION_SESSION to store the password in the session collection, which doesn't get stored across login sessions.

If service is NULL, then secret_service_get_sync() will be called to get the default SecretService proxy.

This method may block indefinitely and should not be used in user interface threads.

service :

the secret service. [allow-none]

schema :

the schema for the attributes. [allow-none]

attributes :

the attribute keys and values. [element-type utf8 utf8]

collection :

a collection alias, or D-Bus object path of the collection where to store the secret. [allow-none]

label :

label for the secret

value :

the secret value

cancellable :

optional cancellation object

error :

location to place an error on failure

Returns :

whether the storage was successful or not

secret_service_lookup ()

void                secret_service_lookup               (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Lookup a secret value in the secret service.

The attributes should be a set of key and value string pairs.

If service is NULL, then secret_service_get() will be called to get the default SecretService proxy.

This method will return immediately and complete asynchronously.

service :

the secret service. [allow-none]

schema :

the schema for the attributes. [allow-none]

attributes :

the attribute keys and values. [element-type utf8 utf8]

cancellable :

optional cancellation object

callback :

called when the operation completes

user_data :

data to be passed to the callback

secret_service_lookup_finish ()

SecretValue *       secret_service_lookup_finish        (SecretService *service,
                                                         GAsyncResult *result,
                                                         GError **error);

Finish asynchronous operation to lookup a secret value in the secret service.

If no secret is found then NULL is returned.

service :

the secret service. [allow-none]

result :

the asynchronous result passed to the callback

error :

location to place an error on failure

Returns :

a newly allocated SecretValue, which should be released with secret_value_unref(), or NULL if no secret found. [transfer full]

secret_service_lookup_sync ()

SecretValue *       secret_service_lookup_sync          (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         GCancellable *cancellable,
                                                         GError **error);

Lookup a secret value in the secret service.

The attributes should be a set of key and value string pairs.

If service is NULL, then secret_service_get_sync() will be called to get the default SecretService proxy.

This method may block indefinitely and should not be used in user interface threads.

service :

the secret service. [allow-none]

schema :

the schema for the attributes. [allow-none]

attributes :

the attribute keys and values. [element-type utf8 utf8]

cancellable :

optional cancellation object

error :

location to place an error on failure

Returns :

a newly allocated SecretValue, which should be released with secret_value_unref(), or NULL if no secret found. [transfer full]

secret_service_clear ()

void                secret_service_clear                (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Remove unlocked items which match the attributes from the secret service.

The attributes should be a set of key and value string pairs.

If service is NULL, then secret_service_get() will be called to get the default SecretService proxy.

This method will return immediately and complete asynchronously.

service :

the secret service. [allow-none]

schema :

the schema for the attributes. [allow-none]

attributes :

the attribute keys and values. [element-type utf8 utf8]

cancellable :

optional cancellation object

callback :

called when the operation completes

user_data :

data to be passed to the callback

secret_service_clear_finish ()

gboolean            secret_service_clear_finish         (SecretService *service,
                                                         GAsyncResult *result,
                                                         GError **error);

Finish asynchronous operation to remove items from the secret service.

service :

the secret service. [allow-none]

result :

the asynchronous result passed to the callback

error :

location to place an error on failure

Returns :

whether the removal was successful or not

secret_service_clear_sync ()

gboolean            secret_service_clear_sync           (SecretService *service,
                                                         const SecretSchema *schema,
                                                         GHashTable *attributes,
                                                         GCancellable *cancellable,
                                                         GError **error);

Remove unlocked items which match the attributes from the secret service.

The attributes should be a set of key and value string pairs.

If service is NULL, then secret_service_get_sync() will be called to get the default SecretService proxy.

This method may block indefinitely and should not be used in user interface threads.

service :

the secret service. [allow-none]

schema :

the schema for the attributes. [allow-none]

attributes :

the attribute keys and values. [element-type utf8 utf8]

cancellable :

optional cancellation object

error :

location to place an error on failure

Returns :

whether the removal was successful or not

secret_service_prompt ()

void                secret_service_prompt               (SecretService *self,
                                                         SecretPrompt *prompt,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Perform prompting for a SecretPrompt.

This function is called by other parts of this library to handle prompts for the various actions that can require prompting.

Override the SecretServiceClass prompt_async virtual method to change the behavior of the propmting. The default behavior is to simply run secret_prompt_perform() on the prompt.

self :

the secret service

prompt :

the prompt

cancellable :

optional cancellation object

callback :

called when the operation completes

user_data :

data to be passed to the callback

secret_service_prompt_finish ()

GVariant *          secret_service_prompt_finish        (SecretService *self,
                                                         GAsyncResult *result,
                                                         const GVariantType *return_type,
                                                         GError **error);

Complete asynchronous operation to perform prompting for a SecretPrompt.

Returns a variant result if the prompt was completed and not dismissed. The type of result depends on the action the prompt is completing, and is defined in the Secret Service DBus API specification.

self :

the secret service

result :

the asynchronous result passed to the callback

return_type :

the variant type of the prompt result

error :

location to place an error on failure

Returns :

NULL if the prompt was dismissed or an error occurred, a variant result if the prompt was successful. [transfer full]

secret_service_prompt_sync ()

GVariant *          secret_service_prompt_sync          (SecretService *self,
                                                         SecretPrompt *prompt,
                                                         GCancellable *cancellable,
                                                         const GVariantType *return_type,
                                                         GError **error);

Perform prompting for a SecretPrompt.

Runs a prompt and performs the prompting. Returns a variant result if the prompt was completed and not dismissed. The type of result depends on the action the prompt is completing, and is defined in the Secret Service DBus API specification.

This function is called by other parts of this library to handle prompts for the various actions that can require prompting.

Override the SecretServiceClass prompt_sync virtual method to change the behavior of the propmting. The default behavior is to simply run secret_prompt_perform_sync() on the prompt.

self :

the secret service

prompt :

the prompt

cancellable :

optional cancellation object

return_type :

the variant type of the prompt result

error :

location to place an error on failure

Returns :

NULL if the prompt was dismissed or an error occurred, a variant result if the prompt was successful. [transfer full]

secret_service_set_alias ()

void                secret_service_set_alias            (SecretService *service,
                                                         const gchar *alias,
                                                         SecretCollection *collection,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Assign a collection to this alias. Aliases help determine well known collections, such as 'default'.

If service is NULL, then secret_service_get() will be called to get the default SecretService proxy.

This method will return immediately and complete asynchronously.

service :

a secret service object. [allow-none]

alias :

the alias to assign the collection to

collection :

the collection to assign to the alias. [allow-none]

cancellable :

optional cancellation object. [allow-none]

callback :

called when the operation completes

user_data :

data to pass to the callback

secret_service_set_alias_finish ()

gboolean            secret_service_set_alias_finish     (SecretService *service,
                                                         GAsyncResult *result,
                                                         GError **error);

Finish an asynchronous operation to assign a collection to an alias.

service :

a secret service object. [allow-none]

result :

asynchronous result passed to callback

error :

location to place error on failure

Returns :

TRUE if successful

secret_service_set_alias_sync ()

gboolean            secret_service_set_alias_sync       (SecretService *service,
                                                         const gchar *alias,
                                                         SecretCollection *collection,
                                                         GCancellable *cancellable,
                                                         GError **error);

Assign a collection to this alias. Aliases help determine well known collections, such as 'default'.

If service is NULL, then secret_service_get_sync() will be called to get the default SecretService proxy.

This method may block and should not be used in user interface threads.

service :

a secret service object. [allow-none]

alias :

the alias to assign the collection to

collection :

the collection to assign to the alias. [allow-none]

cancellable :

optional cancellation object. [allow-none]

error :

location to place error on failure

Returns :

TRUE if successful

Property Details

The "collections" property

  "collections"              SecretObjectList*     : Read

A list of SecretCollection objects representing the collections in the Secret Service. This list may be NULL if the collections have not been loaded.

To load the collections, specify the SECRET_SERVICE_LOAD_COLLECTIONS initialization flag when calling the secret_service_get() or secret_service_new() functions. Or call the secret_service_load_collections() method.


The "flags" property

  "flags"                    SecretServiceFlags    : Read / Write / Construct Only

A set of flags describing which parts of the secret service have been initialized.