SecretCollection

## SecretCollection SecretCollection — A collection of secret items |

## Synopsis

    #include <libsecret/secret.h>

                        SecretCollection;
    struct              SecretCollectionClass;
    enum                SecretCollectionFlags;
    void                secret_collection_for_alias         (SecretService *service,
                                                             const gchar *alias,
                                                             SecretCollectionFlags flags,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    SecretCollection *  secret_collection_for_alias_finish  (GAsyncResult *result,
                                                             GError **error);
    SecretCollection *  secret_collection_for_alias_sync    (SecretService *service,
                                                             const gchar *alias,
                                                             SecretCollectionFlags flags,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                secret_collection_load_items        (SecretCollection *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            secret_collection_load_items_finish (SecretCollection *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            secret_collection_load_items_sync   (SecretCollection *self,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                secret_collection_create            (SecretService *service,
                                                             const gchar *label,
                                                             const gchar *alias,
                                                             SecretCollectionCreateFlags flags,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    SecretCollection *  secret_collection_create_finish     (GAsyncResult *result,
                                                             GError **error);
    SecretCollection *  secret_collection_create_sync       (SecretService *service,
                                                             const gchar *label,
                                                             const gchar *alias,
                                                             SecretCollectionCreateFlags flags,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                secret_collection_search            (SecretCollection *self,
                                                             const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             SecretSearchFlags flags,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GList *             secret_collection_search_finish     (SecretCollection *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    GList *             secret_collection_search_sync       (SecretCollection *self,
                                                             const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             SecretSearchFlags flags,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                secret_collection_delete            (SecretCollection *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            secret_collection_delete_finish     (SecretCollection *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            secret_collection_delete_sync       (SecretCollection *self,
                                                             GCancellable *cancellable,
                                                             GError **error);
    guint64             secret_collection_get_created       (SecretCollection *self);
    SecretService *     secret_collection_get_service       (SecretCollection *self);
    SecretCollectionFlags secret_collection_get_flags       (SecretCollection *self);
    GList *             secret_collection_get_items         (SecretCollection *self);
    gchar *             secret_collection_get_label         (SecretCollection *self);
    void                secret_collection_set_label         (SecretCollection *self,
                                                             const gchar *label,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            secret_collection_set_label_finish  (SecretCollection *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            secret_collection_set_label_sync    (SecretCollection *self,
                                                             const gchar *label,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            secret_collection_get_locked        (SecretCollection *self);
    guint64             secret_collection_get_modified      (SecretCollection *self);
    void                secret_collection_refresh           (SecretCollection *self);

## Object Hierarchy

      GObject
       +----GDBusProxy
             +----SecretCollection

      GFlags
       +----SecretCollectionFlags

## Implemented Interfaces

SecretCollection implements GDBusInterface, GInitable and GAsyncInitable.

## Properties

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

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

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

## Details

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

GDBusProxyClass `parent_class`; | the parent class

### enum SecretCollectionFlags

    typedef enum {
    	SECRET_COLLECTION_NONE = 0,
    	SECRET_COLLECTION_LOAD_ITEMS = 1 << 1,
    } SecretCollectionFlags;

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

`SECRET_COLLECTION_NONE` | no flags
`SECRET_COLLECTION_LOAD_ITEMS` | items have or should be loaded

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

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

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

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

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

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

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

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

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

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_sync()` will be called to get the default SecretService proxy.

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

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

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

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

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

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

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

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

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

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

`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 SecretUnstable.Item]

### secret_collection_get_label ()

    gchar *             secret_collection_get_label         (SecretCollection *self);

Get the label of this collection.

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

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

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

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

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

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

`self` : | the collection

## Property Details

### The `"created"` property

      "created"                  guint64               : Read / Write

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

Default value: 0

### The `"flags"` property

      "flags"                    SecretCollectionFlags  : Read / Write / Construct Only

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

### The `"items"` property

      "items"                    SecretObjectList*     : Read

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

### The `"label"` property

      "label"                    gchar*                : Read / Write

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.

Default value: NULL

### The `"locked"` property

      "locked"                   gboolean              : Read

Whether the collection is locked or not.

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

Default value: TRUE

### The `"modified"` property

      "modified"                 guint64               : Read / Write

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

Default value: 0

### The `"service"` property

      "service"                  SecretService*        : Read / Write / Construct Only

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