SecretValue: Libsecret Library Reference Manual

## SecretValue SecretValue — a value containing a secret |

## Functions

SecretValue * | secret_value_new ()
SecretValue * | secret_value_new_full ()
const gchar * | secret_value_get ()
const gchar * | secret_value_get_text ()
const gchar * | secret_value_get_content_type ()
SecretValue * | secret_value_ref ()
void | secret_value_unref ()
gchar * | secret_value_unref_to_password ()

## Types and Values

| SecretValue

## Object Hierarchy

        GBoxed
        ╰── SecretValue

## Includes

    #include <libsecret/secret.h>

## 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()`.

## Functions

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

value | value to unreference. | [type Secret.Value]

### secret_value_unref_to_password ()

    gchar *
    secret_value_unref_to_password (SecretValue *value,
                                    gsize *length);

Unreference a SecretValue and steal the secret data in SecretValue as nonpageable memory.

#### Parameters

value | the value |
length | the length of the secret |

#### Returns

a new password string stored in nonpageable memory which must be freed with `secret_password_free()` when done.

[transfer full]

Since: 0.19.0

## Types and Values

### SecretValue

    typedef struct _SecretValue SecretValue;

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