## SecretValue SecretValue — a value containing a secret |

## Synopsis

    #include <libsecret/secret.h>

                        SecretValue;
    SecretValue *       secret_value_new                    (const gchar *secret,
                                                             gssize length,
                                                             const gchar *content_type);
    SecretValue *       secret_value_new_full               (gchar *secret,
                                                             gssize length,
                                                             const gchar *content_type,
                                                             GDestroyNotify destroy);
    const gchar *       secret_value_get                    (SecretValue *value,
                                                             gsize *length);
    const gchar *       secret_value_get_text               (SecretValue *value);
    const gchar *       secret_value_get_content_type       (SecretValue *value);
    SecretValue *       secret_value_ref                    (SecretValue *value);
    void                secret_value_unref                  (gpointer value);

## Object Hierarchy

      GBoxed
       +----SecretValue

## Description

A SecretValue contains a password or other secret value.

Use `secret_value_get()` to get the actual secret data, such as a password. The secret data is not necessarily null-terminated, unless the content type is "text/plain".

Each SecretValue has a content type. For passwords, this is "text/plain". Use `secret_value_get_content_type()` to look at the content type.

SecretValue is reference counted and immutable. The secret data is only freed when all references have been released via `secret_value_unref()`.

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

## Details

### SecretValue

    typedef struct _SecretValue SecretValue;

A secret value, like a password or other binary secret.

### secret_value_new ()

    SecretValue *       secret_value_new                    (const gchar *secret,
                                                             gssize length,
                                                             const gchar *content_type);

Create a SecretValue for the secret data passed in. The secret data is copied into non-pageable 'secure' memory.

If the length is less than zero, then `secret` is assumed to be null-terminated.

`secret` : | the secret data
`length` : | the length of the data
`content_type` : | the content type of the data
Returns : | the new SecretValue. [transfer full]

### secret_value_new_full ()

    SecretValue *       secret_value_new_full               (gchar *secret,
                                                             gssize length,
                                                             const gchar *content_type,
                                                             GDestroyNotify destroy);

Create a SecretValue for the secret data passed in. The secret data is not copied, and will later be freed with the `destroy` function.

If the length is less than zero, then `secret` is assumed to be null-terminated.

`secret` : | the secret data
`length` : | the length of the data
`content_type` : | the content type of the data
`destroy` : | function to call to free the secret data
Returns : | the new SecretValue. [transfer full]

### secret_value_get ()

    const gchar *       secret_value_get                    (SecretValue *value,
                                                             gsize *length);

Get the secret data in the SecretValue. The value is not necessarily null-terminated unless it was created with `secret_value_new()` or a null-terminated string was passed to `secret_value_new_full()`.

`value` : | the value
`length` : | the length of the secret
Returns : | the secret data. [array length=length][element-type guint8]

### secret_value_get_text ()

    const gchar *       secret_value_get_text               (SecretValue *value);

Get the secret data in the SecretValue if it contains a textual value. The content type must be `text/plain`.

`value` : | the value
Returns : | the content type. [allow-none]

### secret_value_get_content_type ()

    const gchar *       secret_value_get_content_type       (SecretValue *value);

Get the content type of the secret value, such as `text/plain`.

`value` : | the value
Returns : | the content type

### secret_value_ref ()

    SecretValue *       secret_value_ref                    (SecretValue *value);

Add another reference to the SecretValue. For each reference `secret_value_unref()` should be called to unreference the value.

`value` : | value to reference
Returns : | the value. [transfer full]

### secret_value_unref ()

    void                secret_value_unref                  (gpointer value);

Unreference a SecretValue. When the last reference is gone, then the value will be freed.

`value` : | value to unreference. [type SecretUnstable.Value][allow-none]