## GTlsPassword

GTlsPassword — TLS Passwords for prompting

## Synopsis

    #include <gio/gio.h>

                        GTlsPassword;
    struct              GTlsPasswordClass;
    enum                GTlsPasswordFlags;
    GTlsPassword *      g_tls_password_new                  (GTlsPasswordFlags flags,
                                                             const gchar *description);
    const guchar *      g_tls_password_get_value            (GTlsPassword *password,
                                                             gsize *length);
    void                g_tls_password_set_value            (GTlsPassword *password,
                                                             const guchar *value,
                                                             gssize length);
    void                g_tls_password_set_value_full       (GTlsPassword *password,
                                                             guchar *value,
                                                             gssize length,
                                                             GDestroyNotify destroy);
    const gchar *       g_tls_password_get_description      (GTlsPassword *password);
    void                g_tls_password_set_description      (GTlsPassword *password,
                                                             const gchar *description);
    GTlsPasswordFlags   g_tls_password_get_flags            (GTlsPassword *password);
    void                g_tls_password_set_flags            (GTlsPassword *password,
                                                             GTlsPasswordFlags flags);
    const gchar *       g_tls_password_get_warning          (GTlsPassword *password);
    void                g_tls_password_set_warning          (GTlsPassword *password,
                                                             const gchar *warning);

## Object Hierarchy

      GObject
       +----GTlsPassword

      GFlags
       +----GTlsPasswordFlags

## Properties

      "description"              gchar*                : Read / Write
      "flags"                    GTlsPasswordFlags     : Read / Write
      "warning"                  gchar*                : Read / Write

## Description

Holds a password used in TLS.

## Details

### GTlsPassword

    typedef struct _GTlsPassword GTlsPassword;

An abstract interface representing a password used in TLS. Often used in user interaction such as unlocking a key storage token.

Since 2.30

### struct GTlsPasswordClass

    struct GTlsPasswordClass {
      GObjectClass parent_class;

      /* methods */

      const guchar *    ( *get_value)            (GTlsPassword  *password,
                                                  gsize         *length);

      void              ( *set_value)            (GTlsPassword  *password,
                                                  guchar        *value,
                                                  gssize         length,
                                                  GDestroyNotify destroy);

      const gchar*      ( *get_default_warning)  (GTlsPassword  *password);
    };

### enum GTlsPasswordFlags

    typedef enum {
      G_TLS_PASSWORD_NONE = 0,
      G_TLS_PASSWORD_RETRY = 1 << 1,
      G_TLS_PASSWORD_MANY_TRIES = 1 << 2,
      G_TLS_PASSWORD_FINAL_TRY = 1 << 3
    } GTlsPasswordFlags;

Various flags for the password.

`G_TLS_PASSWORD_NONE` | No flags
`G_TLS_PASSWORD_RETRY` | The password was wrong, and the user should retry.
`G_TLS_PASSWORD_MANY_TRIES` | Hint to the user that the password has been wrong many times, and the user may not have many chances left.
`G_TLS_PASSWORD_FINAL_TRY` | Hint to the user that this is the last try to get this password right.

Since 2.30

### g_tls_password_new ()

    GTlsPassword *      g_tls_password_new                  (GTlsPasswordFlags flags,
                                                             const gchar *description);

Create a new GTlsPassword object.

`flags` : | the password flags
`description` : | description of what the password is for
Returns : | The newly allocated password object. [transfer full]

### g_tls_password_get_value ()

    const guchar *      g_tls_password_get_value            (GTlsPassword *password,
                                                             gsize *length);

Get the password value. If `length` is not `NULL` then it will be filled in with the length of the password value. (Note that the password value is not nul-terminated, so you can only pass `NULL` for `length` in contexts where you know the password will have a certain fixed length.)

`password` : | a GTlsPassword object
`length` : | location to place the length of the password. [allow-none]
Returns : | The password value (owned by the password object).

Since 2.30

### g_tls_password_set_value ()

    void                g_tls_password_set_value            (GTlsPassword *password,
                                                             const guchar *value,
                                                             gssize length);

Set the value for this password. The `value` will be copied by the password object.

Specify the `length`, for a non-nul-terminated password. Pass -1 as `length` if using a nul-terminated password, and `length` will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.)

`password` : | a GTlsPassword object
`value` : | the new password value
`length` : | the length of the password, or -1

Since 2.30

### g_tls_password_set_value_full ()

    void                g_tls_password_set_value_full       (GTlsPassword *password,
                                                             guchar *value,
                                                             gssize length,
                                                             GDestroyNotify destroy);

Provide the value for this password.

The `value` will be owned by the password object, and later freed using the `destroy` function callback.

Specify the `length`, for a non-nul-terminated password. Pass -1 as `length` if using a nul-terminated password, and `length` will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.)

Virtual: set_value

`password` : | a GTlsPassword object
`value` : | the value for the password
`length` : | the length of the password, or -1
`destroy` : | a function to use to free the password. [allow-none]

Since 2.30

### g_tls_password_get_description ()

    const gchar *       g_tls_password_get_description      (GTlsPassword *password);

Get a description string about what the password will be used for.

`password` : | a GTlsPassword object
Returns : | The description of the password.

Since 2.30

### g_tls_password_set_description ()

    void                g_tls_password_set_description      (GTlsPassword *password,
                                                             const gchar *description);

Set a description string about what the password will be used for.

`password` : | a GTlsPassword object
`description` : | The description of the password

Since 2.30

### g_tls_password_get_flags ()

    GTlsPasswordFlags   g_tls_password_get_flags            (GTlsPassword *password);

Get flags about the password.

`password` : | a GTlsPassword object
Returns : | The flags about the password.

Since 2.30

### g_tls_password_set_flags ()

    void                g_tls_password_set_flags            (GTlsPassword *password,
                                                             GTlsPasswordFlags flags);

Set flags about the password.

`password` : | a GTlsPassword object
`flags` : | The flags about the password

Since 2.30

### g_tls_password_get_warning ()

    const gchar *       g_tls_password_get_warning          (GTlsPassword *password);

Get a user readable translated warning. Usually this warning is a representation of the password flags returned from `g_tls_password_get_flags()`.

`password` : | a GTlsPassword object
Returns : | The warning.

Since 2.30

### g_tls_password_set_warning ()

    void                g_tls_password_set_warning          (GTlsPassword *password,
                                                             const gchar *warning);

Set a user readable translated warning. Usually this warning is a representation of the password flags returned from `g_tls_password_get_flags()`.

`password` : | a GTlsPassword object
`warning` : | The user readable warning

Since 2.30

## Property Details

### The `"description"` property

      "description"              gchar*                : Read / Write

Description of what the password is for.

Default value: ""

### The `"flags"` property

      "flags"                    GTlsPasswordFlags     : Read / Write

Flags about the password.

### The `"warning"` property

      "warning"                  gchar*                : Read / Write

Warning about the password.

Default value: ""