Libsecret Library Reference Manual: SecretCollection

SecretCollection

SecretCollection — A collection of secret items

Functions

void	secret_collection_for_alias ()
SecretCollection *	secret_collection_for_alias_finish ()
SecretCollection *	secret_collection_for_alias_sync ()
void	secret_collection_load_items ()
gboolean	secret_collection_load_items_finish ()
gboolean	secret_collection_load_items_sync ()
void	secret_collection_create ()
SecretCollection *	secret_collection_create_finish ()
SecretCollection *	secret_collection_create_sync ()
void	secret_collection_search ()
GList *	secret_collection_search_finish ()
GList *	secret_collection_search_sync ()
void	secret_collection_delete ()
gboolean	secret_collection_delete_finish ()
gboolean	secret_collection_delete_sync ()
guint64	secret_collection_get_created ()
SecretService *	secret_collection_get_service ()
SecretCollectionFlags	secret_collection_get_flags ()
GList *	secret_collection_get_items ()
gchar *	secret_collection_get_label ()
void	secret_collection_set_label ()
gboolean	secret_collection_set_label_finish ()
gboolean	secret_collection_set_label_sync ()
gboolean	secret_collection_get_locked ()
guint64	secret_collection_get_modified ()
void	secret_collection_refresh ()

Properties

guint64	created	Read / Write
SecretCollectionFlags	flags	Read / Write / Construct Only
SecretObjectList *	items	Read
gchar *	label	Read / Write
gboolean	locked	Read
guint64	modified	Read / Write
SecretService *	service	Read / Write / Construct Only

Types and Values

	SecretCollection
struct	SecretCollectionClass
enum	SecretCollectionFlags

Object Hierarchy

    GFlags
    ╰── SecretCollectionFlags
    GObject
    ╰── GDBusProxy
        ╰── SecretCollection

Implemented Interfaces

SecretCollection implements GDBusInterface, GInitable and GAsyncInitable.

Includes

#include <libsecret/secret.h>

Description

SecretCollection represents a collection of secret items stored in the Secret Service.

A collection can be in a locked or unlocked state. Use secret_service_lock() or secret_service_unlock() to lock or unlock the collection.

Use the SecretCollection::items property or secret_collection_get_items() to lookup the items in the collection. There may not be any items exposed when the collection is locked.

Functions

secret_collection_for_alias ()

void
secret_collection_for_alias (SecretService *service,
                             const gchar *alias,
                             SecretCollectionFlags flags,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Lookup which collection is assigned 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.

Parameters

service	a secret service object.	[allow-none]
alias	the alias to lookup
flags	options for the collection initialization
cancellable	optional cancellation object.	[allow-none]
callback	called when the operation completes
user_data	data to pass to the callback

secret_collection_for_alias_finish ()

SecretCollection *
secret_collection_for_alias_finish (GAsyncResult *result,
                                    GError **error);

Finish an asynchronous operation to lookup which collection is assigned to an alias.

Parameters

result	asynchronous result passed to callback
error	location to place error on failure

Returns

the collection, or NULL if none assigned to the alias.

[transfer full]

secret_collection_for_alias_sync ()

SecretCollection *
secret_collection_for_alias_sync (SecretService *service,
                                  const gchar *alias,
                                  SecretCollectionFlags flags,
                                  GCancellable *cancellable,
                                  GError **error);

Lookup which collection is assigned 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.

Parameters

service	a secret service object.	[allow-none]
alias	the alias to lookup
flags	options for the collection initialization
cancellable	optional cancellation object.	[allow-none]
error	location to place error on failure

Returns

the collection, or NULL if none assigned to the alias.

[transfer full]

secret_collection_load_items ()

void
secret_collection_load_items (SecretCollection *self,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

Ensure that the SecretCollection proxy has loaded all the items present in the Secret Service. This affects the result of secret_collection_get_items().

For collections returned from secret_service_get_collections() the items will have already been loaded.

This method will return immediately and complete asynchronously.

Parameters

self	the secret collection
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to be passed to the callback

secret_collection_load_items_finish ()

gboolean
secret_collection_load_items_finish (SecretCollection *self,
                                     GAsyncResult *result,
                                     GError **error);

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

Parameters

self	the secret collection
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_collection_load_items_sync ()

gboolean
secret_collection_load_items_sync (SecretCollection *self,
                                   GCancellable *cancellable,
                                   GError **error);

Ensure that the SecretCollection proxy has loaded all the items present in the Secret Service. This affects the result of secret_collection_get_items().

For collections returned from secret_service_get_collections() the items will have already been loaded.

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

Parameters

self	the secret collection
cancellable	optional cancellation object
error	location to place an error on failure

Returns

whether the load was successful or not

secret_collection_create ()

void
secret_collection_create (SecretService *service,
                          const gchar *label,
                          const gchar *alias,
                          SecretCollectionCreateFlags flags,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Create a new collection in the secret service.

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 are required.

An alias is a well-known tag for a collection, such as 'default' (ie: the default collection to store items in). This allows other applications to easily identify and share a collection. If you specify an alias , and a collection with that alias already exists, then a new collection will not be created. The previous one will be returned instead.

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

Parameters

service	a secret service object.	[allow-none]
label	label for the new collection
alias	alias to assign to the collection.	[allow-none]
flags	currently unused
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to pass to the callback

secret_collection_create_finish ()

SecretCollection *
secret_collection_create_finish (GAsyncResult *result,
                                 GError **error);

Finish operation to create a new collection in the secret service.

Parameters

result	the asynchronous result passed to the callback
error	location to place an error on failure

Returns

the new collection, which should be unreferenced with g_object_unref().

[transfer full]

secret_collection_create_sync ()

SecretCollection *
secret_collection_create_sync (SecretService *service,
                               const gchar *label,
                               const gchar *alias,
                               SecretCollectionCreateFlags flags,
                               GCancellable *cancellable,
                               GError **error);

Create a new collection in the secret service.

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 are required.

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

Parameters

service	a secret service object.	[allow-none]
label	label for the new collection
alias	alias to assign to the collection.	[allow-none]
flags	currently unused
cancellable	optional cancellation object
error	location to place an error on failure

Returns

the new collection, which should be unreferenced with g_object_unref().

[transfer full]

secret_collection_search ()

void
secret_collection_search (SecretCollection *self,
                          const SecretSchema *schema,
                          GHashTable *attributes,
                          SecretSearchFlags flags,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Search for items matching the attributes in the collection . The attributes should be a table of string keys and string values.

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.

Parameters

self	a secret collection
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_collection_search_finish ()

GList *
secret_collection_search_finish (SecretCollection *self,
                                 GAsyncResult *result,
                                 GError **error);

Complete asynchronous operation to search for items in a collection.

Parameters

self	the secret collection
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 Secret.Item]

secret_collection_search_sync ()

GList *
secret_collection_search_sync (SecretCollection *self,
                               const SecretSchema *schema,
                               GHashTable *attributes,
                               SecretSearchFlags flags,
                               GCancellable *cancellable,
                               GError **error);

Search for items matching the attributes in the collection . The attributes should be a table of string keys and string values.

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 may block indefinetely. Use the asynchronous version in user interface threads.

Parameters

self	a secret collection
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 Secret.Item]

secret_collection_delete ()

void
secret_collection_delete (SecretCollection *self,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Delete this collection.

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.

Parameters

self	a collection
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to pass to the callback

secret_collection_delete_finish ()

gboolean
secret_collection_delete_finish (SecretCollection *self,
                                 GAsyncResult *result,
                                 GError **error);

Complete operation to delete this collection.

Parameters

self	a collection
result	asynchronous result passed to the callback
error	location to place an error on failure

Returns

whether the collection was successfully deleted or not

secret_collection_delete_sync ()

gboolean
secret_collection_delete_sync (SecretCollection *self,
                               GCancellable *cancellable,
                               GError **error);

Delete this collection.

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.

Parameters

self	a collection
cancellable	optional cancellation object
error	location to place an error on failure

Returns

whether the collection was successfully deleted or not

secret_collection_get_created ()

guint64
secret_collection_get_created (SecretCollection *self);

Get the created date and time of the collection. The return value is the number of seconds since the unix epoch, January 1st 1970.

Parameters

self

a collection

Returns

the created date and time

secret_collection_get_service ()

SecretService *
secret_collection_get_service (SecretCollection *self);

Get the Secret Service object that this collection was created with.

Parameters

self

a collection

Returns

the Secret Service object.

[transfer none]

secret_collection_get_flags ()

SecretCollectionFlags
secret_collection_get_flags (SecretCollection *self);

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

Use secret_collection_load_items() to initialize further features and change the flags.

Parameters

self

the secret collection proxy

Returns

the flags for features initialized

secret_collection_get_items ()

GList *
secret_collection_get_items (SecretCollection *self);

Get the list of items in this collection.

Parameters

self

a collection

Returns

a list of items, when done, the list should be freed with g_list_free, and each item should be released with g_object_unref().

[transfer full][element-type Secret.Item]

secret_collection_get_label ()

gchar *
secret_collection_get_label (SecretCollection *self);

Get the label of this collection.

Parameters

self

a collection

Returns

the label, which should be freed with g_free().

[transfer full]

secret_collection_set_label ()

void
secret_collection_set_label (SecretCollection *self,
                             const gchar *label,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Set the label of this collection.

This function returns immediately and completes asynchronously.

Parameters

self	a collection
label	a new label
cancellable	optional cancellation object
callback	called when the operation completes
user_data	data to pass to the callback

secret_collection_set_label_finish ()

gboolean
secret_collection_set_label_finish (SecretCollection *self,
                                    GAsyncResult *result,
                                    GError **error);

Complete asynchronous operation to set the label of this collection.

Parameters

self	a collection
result	asynchronous result passed to callback
error	location to place error on failure

Returns

whether the change was successful or not

secret_collection_set_label_sync ()

gboolean
secret_collection_set_label_sync (SecretCollection *self,
                                  const gchar *label,
                                  GCancellable *cancellable,
                                  GError **error);

Set the label of this collection.

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

Parameters

self	a collection
label	a new label
cancellable	optional cancellation object
error	location to place error on failure

Returns

whether the change was successful or not

secret_collection_get_locked ()

gboolean
secret_collection_get_locked (SecretCollection *self);

Get whether the collection is locked or not.

Use secret_service_lock() or secret_service_unlock() to lock or unlock the collection.

Parameters

self

a collection

Returns

whether the collection is locked or not

secret_collection_get_modified ()

guint64
secret_collection_get_modified (SecretCollection *self);

Get the modified date and time of the collection. The return value is the number of seconds since the unix epoch, January 1st 1970.

Parameters

self

a collection

Returns

the modified date and time

secret_collection_refresh ()

void
secret_collection_refresh (SecretCollection *self);

Refresh the properties on this collection. This fires off a request to refresh, and the properties will be updated later.

Calling this method is not normally necessary, as the secret service will notify the client when properties change.

Parameters

self

the collection

Types and Values

SecretCollection

typedef struct _SecretCollection SecretCollection;

A proxy object representing a collection of secrets in the Secret Service.

struct SecretCollectionClass

struct SecretCollectionClass {
	GDBusProxyClass parent_class;
};

The class for SecretCollection.

Members

GDBusProxyClass parent_class;

the parent class

enum SecretCollectionFlags

Flags which determine which parts of the SecretCollection proxy are initialized.

Members

SECRET_COLLECTION_NONE	no flags
SECRET_COLLECTION_LOAD_ITEMS	items have or should be loaded

Property Details

The `“created”` property

  “created”                  guint64

The date and time (in seconds since the UNIX epoch) that this collection was created.

Flags: Read / Write

Default value: 0

The `“flags”` property

  “flags”                    SecretCollectionFlags

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

Flags: Read / Write / Construct Only

The `“items”` property

  “items”                    SecretObjectList *

A list of SecretItem objects representing the items that are in this collection. This list will be empty if the collection is locked.

Flags: Read

The `“label”` property

  “label”                    gchar *

The human readable label for the collection.

Setting this property will result in the label of the collection being set asynchronously. To properly track the changing of the label use the secret_collection_set_label() function.

Flags: Read / Write

Default value: NULL

The `“locked”` property

  “locked”                   gboolean

Whether the collection is locked or not.

To lock or unlock a collection use the secret_service_lock() or secret_service_unlock() functions.

Flags: Read

Default value: TRUE

The `“modified”` property

  “modified”                 guint64

The date and time (in seconds since the UNIX epoch) that this collection was last modified.

Flags: Read / Write

Default value: 0

The `“service”` property

  “service”                  SecretService *

The SecretService object that this collection is associated with and uses to interact with the actual D-Bus Secret Service.

Flags: Read / Write / Construct Only