SecretItem

## SecretItem SecretItem — A secret item |

## Synopsis

    #include <libsecret/secret.h>

                        SecretItem;
    struct              SecretItemClass;
    enum                SecretItemFlags;
    enum                SecretItemCreateFlags;
    void                secret_item_create                  (SecretCollection *collection,
                                                             const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             const gchar *label,
                                                             SecretValue *value,
                                                             SecretItemCreateFlags flags,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    SecretItem *        secret_item_create_finish           (GAsyncResult *result,
                                                             GError **error);
    SecretItem *        secret_item_create_sync             (SecretCollection *collection,
                                                             const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             const gchar *label,
                                                             SecretValue *value,
                                                             SecretItemCreateFlags flags,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                secret_item_delete                  (SecretItem *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            secret_item_delete_finish           (SecretItem *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            secret_item_delete_sync             (SecretItem *self,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gchar *             secret_item_get_schema_name         (SecretItem *self);
    GHashTable *        secret_item_get_attributes          (SecretItem *self);
    void                secret_item_set_attributes          (SecretItem *self,
                                                             const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            secret_item_set_attributes_finish   (SecretItem *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            secret_item_set_attributes_sync     (SecretItem *self,
                                                             const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GError **error);
    guint64             secret_item_get_created             (SecretItem *self);
    gchar *             secret_item_get_label               (SecretItem *self);
    void                secret_item_set_label               (SecretItem *self,
                                                             const gchar *label,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            secret_item_set_label_finish        (SecretItem *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            secret_item_set_label_sync          (SecretItem *self,
                                                             const gchar *label,
                                                             GCancellable *cancellable,
                                                             GError **error);
    SecretItemFlags     secret_item_get_flags               (SecretItem *self);
    gboolean            secret_item_get_locked              (SecretItem *self);
    guint64             secret_item_get_modified            (SecretItem *self);
    SecretService *     secret_item_get_service             (SecretItem *self);
    SecretValue *       secret_item_get_secret              (SecretItem *self);
    void                secret_item_load_secret             (SecretItem *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            secret_item_load_secret_finish      (SecretItem *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            secret_item_load_secret_sync        (SecretItem *self,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                secret_item_load_secrets            (GList *items,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            secret_item_load_secrets_finish     (GAsyncResult *result,
                                                             GError **error);
    gboolean            secret_item_load_secrets_sync       (GList *items,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                secret_item_set_secret              (SecretItem *self,
                                                             SecretValue *value,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            secret_item_set_secret_finish       (SecretItem *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            secret_item_set_secret_sync         (SecretItem *self,
                                                             SecretValue *value,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                secret_item_refresh                 (SecretItem *self);

## Object Hierarchy

      GObject
       +----GDBusProxy
             +----SecretItem

      GFlags
       +----SecretItemFlags

## Implemented Interfaces

SecretItem implements GDBusInterface, GInitable and GAsyncInitable.

## Properties

      "attributes"               GHashTable*           : Read / Write
      "created"                  guint64               : Read / Write
      "flags"                    SecretItemFlags       : Read / Write / Construct Only
      "label"                    gchar*                : Read / Write
      "locked"                   gboolean              : Read
      "modified"                 guint64               : Read / Write
      "service"                  SecretService*        : Read / Write / Construct Only

## Description

SecretItem represents a secret item stored in the Secret Service.

Each item has a value, represented by a SecretValue, which can be retrieved by `secret_item_get_secret()` or set by `secret_item_set_secret()`. The item is only available when the item is not locked.

Items can be locked or unlocked using the `secret_service_lock()` or `secret_service_unlock()` functions. The Secret Service may not be able to unlock individual items, and may unlock an entire collection when a single item is unlocked.

Each item has a set of attributes, which are used to locate the item later. These are not stored or transferred in a secure manner. Each attribute has a string name and a string value. Use `secret_service_search()` to search for items based on their attributes, and `secret_item_set_attributes()` to change the attributes associated with an item.

Items can be created with `secret_item_create()` or `secret_service_store()`.

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

## Details

### SecretItem

    typedef struct _SecretItem SecretItem;

A proxy object representing a secret item in the Secret Service.

### struct SecretItemClass

    struct SecretItemClass {
    	GDBusProxyClass parent_class;
    };

The class for SecretItem.

GDBusProxyClass `parent_class`; | the parent class

### enum SecretItemFlags

    typedef enum {
    	SECRET_ITEM_NONE,
    	SECRET_ITEM_LOAD_SECRET = 1 << 1
    } SecretItemFlags;

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

`SECRET_ITEM_NONE` | no flags
`SECRET_ITEM_LOAD_SECRET` | a secret has been (or should be) loaded for SecretItem

### enum SecretItemCreateFlags

    typedef enum {
    	SECRET_ITEM_CREATE_NONE = 0,
    	SECRET_ITEM_CREATE_REPLACE = 1 << 1
    } SecretItemCreateFlags;

Flags for `secret_item_create()`.

`SECRET_ITEM_CREATE_NONE` | no flags
`SECRET_ITEM_CREATE_REPLACE` | replace an item with the same attributes.

### secret_item_create ()

    void                secret_item_create                  (SecretCollection *collection,
                                                             const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             const gchar *label,
                                                             SecretValue *value,
                                                             SecretItemCreateFlags flags,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Create a new item in the secret service.

If the `flags` contains `SECRET_ITEM_CREATE_REPLACE`, then the secret service will search for an item matching the `attributes`, and update that item instead of creating a new one.

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.

`collection` : | a secret collection to create this item in
`schema` : | the schema for the attributes. [allow-none]
`attributes` : | attributes for the new item. [element-type utf8 utf8]
`label` : | label for the new item
`value` : | secret value for the new item
`flags` : | flags for the creation of the new item
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to pass to the callback

### secret_item_create_finish ()

    SecretItem *        secret_item_create_finish           (GAsyncResult *result,
                                                             GError **error);

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

`result` : | the asynchronous result passed to the callback
`error` : | location to place an error on failure
Returns : | the new item, which should be unreferenced with `g_object_unref()`. [transfer full]

### secret_item_create_sync ()

    SecretItem *        secret_item_create_sync             (SecretCollection *collection,
                                                             const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             const gchar *label,
                                                             SecretValue *value,
                                                             SecretItemCreateFlags flags,
                                                             GCancellable *cancellable,
                                                             GError **error);

Create a new item in the secret service.

If the `flags` contains `SECRET_ITEM_CREATE_REPLACE`, then the secret service will search for an item matching the `attributes`, and update that item instead of creating a new one.

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.

`collection` : | a secret collection to create this item in
`schema` : | the schema for the attributes. [allow-none]
`attributes` : | attributes for the new item. [element-type utf8 utf8]
`label` : | label for the new item
`value` : | secret value for the new item
`flags` : | flags for the creation of the new item
`cancellable` : | optional cancellation object
`error` : | location to place an error on failure
Returns : | the new item, which should be unreferenced with `g_object_unref()`. [transfer full]

### secret_item_delete ()

    void                secret_item_delete                  (SecretItem *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Delete this item.

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` : | an item
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to pass to the callback

### secret_item_delete_finish ()

    gboolean            secret_item_delete_finish           (SecretItem *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Complete asynchronous operation to delete the secret item.

`self` : | an item
`result` : | asynchronous result passed to the callback
`error` : | location to place an error on failure
Returns : | whether the item was successfully deleted or not

### secret_item_delete_sync ()

    gboolean            secret_item_delete_sync             (SecretItem *self,
                                                             GCancellable *cancellable,
                                                             GError **error);

Delete this secret item.

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` : | an item
`cancellable` : | optional cancellation object
`error` : | location to place an error on failure
Returns : | whether the item was successfully deleted or not

### secret_item_get_schema_name ()

    gchar *             secret_item_get_schema_name         (SecretItem *self);

Gets the name of the schema that this item was stored with. This is also available at the `xdg:schema` attribute.

`self` : | an item
Returns : | the schema name. [transfer full]

### secret_item_get_attributes ()

    GHashTable *        secret_item_get_attributes          (SecretItem *self);

Set the attributes of this item.

The `attributes` are a mapping of string keys to string values. Attributes are used to search for items. Attributes are not stored or transferred securely by the secret service.

Do not modify the attributes returned by this method. Use `secret_item_set_attributes()` instead.

`self` : | an item
Returns : | a new reference to the attributes, which should not be modified, and released with `g_hash_table_unref()`. [transfer full][element-type utf8 utf8]

### secret_item_set_attributes ()

    void                secret_item_set_attributes          (SecretItem *self,
                                                             const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Set the attributes of this item.

The `attributes` are a mapping of string keys to string values. Attributes are used to search for items. Attributes are not stored or transferred securely by the secret service.

This function returns immediately and completes asynchronously.

`self` : | an item
`schema` : | the schema for the attributes. [allow-none]
`attributes` : | a new set of attributes. [element-type utf8 utf8]
`cancellable` : | optional cancellation object
`callback` : | called when the asynchronous operation completes
`user_data` : | data to pass to the callback

### secret_item_set_attributes_finish ()

    gboolean            secret_item_set_attributes_finish   (SecretItem *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Complete operation to set the attributes of this item.

`self` : | an item
`result` : | asynchronous result passed to the callback
`error` : | location to place error on failure
Returns : | whether the change was successful or not

### secret_item_set_attributes_sync ()

    gboolean            secret_item_set_attributes_sync     (SecretItem *self,
                                                             const SecretSchema *schema,
                                                             GHashTable *attributes,
                                                             GCancellable *cancellable,
                                                             GError **error);

Set the attributes of this item.

The `attributes` are a mapping of string keys to string values. Attributes are used to search for items. Attributes are not stored or transferred securely by the secret service.

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

`self` : | an item
`schema` : | the schema for the attributes. [allow-none]
`attributes` : | a new set of attributes. [element-type utf8 utf8]
`cancellable` : | optional cancellation object
`error` : | location to place error on failure
Returns : | whether the change was successful or not

### secret_item_get_created ()

    guint64             secret_item_get_created             (SecretItem *self);

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

`self` : | an item
Returns : | the created date and time

### secret_item_get_label ()

    gchar *             secret_item_get_label               (SecretItem *self);

Get the label of this item.

`self` : | an item
Returns : | the label, which should be freed with `g_free()`. [transfer full]

### secret_item_set_label ()

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

Set the label of this item.

This function returns immediately and completes asynchronously.

`self` : | an item
`label` : | a new label
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to pass to the callback

### secret_item_set_label_finish ()

    gboolean            secret_item_set_label_finish        (SecretItem *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Complete asynchronous operation to set the label of this collection.

`self` : | an item
`result` : | asynchronous result passed to callback
`error` : | location to place error on failure
Returns : | whether the change was successful or not

### secret_item_set_label_sync ()

    gboolean            secret_item_set_label_sync          (SecretItem *self,
                                                             const gchar *label,
                                                             GCancellable *cancellable,
                                                             GError **error);

Set the label of this item.

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

`self` : | an item
`label` : | a new label
`cancellable` : | optional cancellation object
`error` : | location to place error on failure
Returns : | whether the change was successful or not

### secret_item_get_flags ()

    SecretItemFlags     secret_item_get_flags               (SecretItem *self);

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

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

`self` : | the secret item proxy
Returns : | the flags for features initialized

### secret_item_get_locked ()

    gboolean            secret_item_get_locked              (SecretItem *self);

Get whether the item is locked or not.

Depending on the secret service an item may not be able to be locked independently from the collection that it is in.

`self` : | an item
Returns : | whether the item is locked or not

### secret_item_get_modified ()

    guint64             secret_item_get_modified            (SecretItem *self);

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

`self` : | an item
Returns : | the modified date and time

### secret_item_get_service ()

    SecretService *     secret_item_get_service             (SecretItem *self);

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

`self` : | an item
Returns : | the Secret Service object. [transfer none]

### secret_item_get_secret ()

    SecretValue *       secret_item_get_secret              (SecretItem *self);

Get the secret value of this item. If this item is locked or the secret has not yet been loaded then this will return `NULL`.

To load the secret call the `secret_item_load_secret()` method.

`self` : | an item
Returns : | the secret value which should be released with `secret_value_unref()`, or `NULL`. [transfer full][allow-none]

### secret_item_load_secret ()

    void                secret_item_load_secret             (SecretItem *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Load the secret value of this item.

Each item has a single secret which might be a password or some other secret binary value.

This function will fail if the secret item is locked.

This function returns immediately and completes asynchronously.

`self` : | an item proxy
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to pass to the callback

### secret_item_load_secret_finish ()

    gboolean            secret_item_load_secret_finish      (SecretItem *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Complete asynchronous operation to load the secret value of this item.

The newly loaded secret value can be accessed by calling `secret_item_get_secret()`.

`self` : | an item proxy
`result` : | asynchronous result passed to callback
`error` : | location to place error on failure
Returns : | whether the secret item succesfully loaded or not

### secret_item_load_secret_sync ()

    gboolean            secret_item_load_secret_sync        (SecretItem *self,
                                                             GCancellable *cancellable,
                                                             GError **error);

Load the secret value of this item.

Each item has a single secret which might be a password or some other secret binary value.

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

`self` : | an item
`cancellable` : | optional cancellation object
`error` : | location to place error on failure
Returns : | whether the secret item succesfully loaded or not

### secret_item_load_secrets ()

    void                secret_item_load_secrets            (GList *items,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Load the secret values for an secret items stored in the service.

The `items` must all have the same SecretItem::service property.

This function returns immediately and completes asynchronously.

`items` : | the items to retrieve secrets for. [element-type SecretUnstable.Item]
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to pass to the callback

### secret_item_load_secrets_finish ()

    gboolean            secret_item_load_secrets_finish     (GAsyncResult *result,
                                                             GError **error);

Complete asynchronous operation to load the secret values for secret items stored in the service.

Items that are locked will not have their secrets loaded.

`result` : | asynchronous result passed to callback
`error` : | location to place an error on failure
Returns : | whether the operation succeded or not

### secret_item_load_secrets_sync ()

    gboolean            secret_item_load_secrets_sync       (GList *items,
                                                             GCancellable *cancellable,
                                                             GError **error);

Load the secret values for an secret items stored in the service.

The `items` must all have the same SecretItem::service property.

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

Items that are locked will not have their secrets loaded.

`items` : | the items to retrieve secrets for. [element-type SecretUnstable.Item]
`cancellable` : | optional cancellation object
`error` : | location to place an error on failure
Returns : | whether the operation succeded or not

### secret_item_set_secret ()

    void                secret_item_set_secret              (SecretItem *self,
                                                             SecretValue *value,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Set the secret value of this item.

Each item has a single secret which might be a password or some other secret binary value.

This function returns immediately and completes asynchronously.

`self` : | an item
`value` : | a new secret value
`cancellable` : | optional cancellation object
`callback` : | called when the operation completes
`user_data` : | data to pass to the callback

### secret_item_set_secret_finish ()

    gboolean            secret_item_set_secret_finish       (SecretItem *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Complete asynchronous operation to set the secret value of this item.

`self` : | an item
`result` : | asynchronous result passed to callback
`error` : | location to place error on failure
Returns : | whether the change was successful or not

### secret_item_set_secret_sync ()

    gboolean            secret_item_set_secret_sync         (SecretItem *self,
                                                             SecretValue *value,
                                                             GCancellable *cancellable,
                                                             GError **error);

Set the secret value of this item.

Each item has a single secret which might be a password or some other secret binary value.

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

`self` : | an item
`value` : | a new secret value
`cancellable` : | optional cancellation object
`error` : | location to place error on failure
Returns : | whether the change was successful or not

### secret_item_refresh ()

    void                secret_item_refresh                 (SecretItem *self);

Refresh the properties on this item. 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 `"attributes"` property

      "attributes"               GHashTable*           : Read / Write

The attributes set on this item. Attributes are used to locate an item. They are not guaranteed to be stored or transferred securely.

Type: GLib.HashTable(utf8,utf8) Transfer: full

### The `"created"` property

      "created"                  guint64               : Read / Write

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

Default value: 0

### The `"flags"` property

      "flags"                    SecretItemFlags       : Read / Write / Construct Only

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

### The `"label"` property

      "label"                    gchar*                : Read / Write

The human readable label for the item.

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

Default value: NULL

### The `"locked"` property

      "locked"                   gboolean              : Read

Whether the item is locked or not. An item may not be independently lockable separate from other items in its collection.

To lock or unlock a item 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 item was last modified.

Default value: 0

### The `"service"` property

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

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