## ECredentials

ECredentials

## Synopsis

    struct              ECredentials;
    #define             E_CREDENTIALS_KEY_USERNAME
    #define             E_CREDENTIALS_KEY_PASSWORD
    #define             E_CREDENTIALS_KEY_AUTH_METHOD
    #define             E_CREDENTIALS_KEY_PROMPT_TITLE
    #define             E_CREDENTIALS_KEY_PROMPT_TEXT
    #define             E_CREDENTIALS_KEY_PROMPT_REASON
    #define             E_CREDENTIALS_KEY_PROMPT_KEY
    #define             E_CREDENTIALS_KEY_PROMPT_FLAGS
    enum                ECredentialsPromptFlags;
    ECredentials *      e_credentials_new                   (void);
    ECredentials *      e_credentials_new_strv              (const gchar * const *strv);
    ECredentials *      e_credentials_new_args              (const gchar *key,
                                                             ...);
    ECredentials *      e_credentials_new_clone             (const ECredentials *credentials);
    void                e_credentials_free                  (ECredentials *credentials);
    gchar **            e_credentials_to_strv               (const ECredentials *credentials);
    void                e_credentials_set                   (ECredentials *credentials,
                                                             const gchar *key,
                                                             const gchar *value);
    gchar *             e_credentials_get                   (const ECredentials *credentials,
                                                             const gchar *key);
    const gchar *       e_credentials_peek                  (ECredentials *credentials,
                                                             const gchar *key);
    gboolean            e_credentials_equal                 (const ECredentials *credentials1,
                                                             const ECredentials *credentials2);
    gboolean            e_credentials_equal_keys            (const ECredentials *credentials1,
                                                             const ECredentials *credentials2,
                                                             const gchar *key1,
                                                             ...);
    gboolean            e_credentials_has_key               (const ECredentials *credentials,
                                                             const gchar *key);
    guint               e_credentials_keys_size             (const ECredentials *credentials);
    GSList *            e_credentials_list_keys             (const ECredentials *credentials);
    void                e_credentials_clear                 (ECredentials *credentials);
    void                e_credentials_clear_peek            (ECredentials *credentials);
    void                e_credentials_util_safe_free_string (gchar *str);
    gchar *             e_credentials_util_prompt_flags_to_string
                                                            (guint prompt_flags);
    guint               e_credentials_util_string_to_prompt_flags
                                                            (const gchar *prompt_flags_string);

## Description

## Details

### struct ECredentials

    struct ECredentials {
    	ECredentialsPrivate *priv;
    };

Contains only private data that should be read and manipulated using the functions below.

Since 3.2

### E_CREDENTIALS_KEY_USERNAME

    #define E_CREDENTIALS_KEY_USERNAME "username"

FIXME Docment me.

Since 3.2

### E_CREDENTIALS_KEY_PASSWORD

    #define E_CREDENTIALS_KEY_PASSWORD "password"

FIXME Document me.

Since 3.2

### E_CREDENTIALS_KEY_AUTH_METHOD

    #define E_CREDENTIALS_KEY_AUTH_METHOD "auth-method"

FIXME Document me.

Since 3.2

### E_CREDENTIALS_KEY_PROMPT_TITLE

    #define E_CREDENTIALS_KEY_PROMPT_TITLE "prompt-title"

FIXME Document me.

Since 3.2

### E_CREDENTIALS_KEY_PROMPT_TEXT

    #define E_CREDENTIALS_KEY_PROMPT_TEXT "prompt-text"

FIXME: Document me.

Since 3.2

### E_CREDENTIALS_KEY_PROMPT_REASON

    #define E_CREDENTIALS_KEY_PROMPT_REASON "prompt-reason"

FIXME: Document me.

Since 3.2

### E_CREDENTIALS_KEY_PROMPT_KEY

    #define E_CREDENTIALS_KEY_PROMPT_KEY "prompt-key"

FIXME: Document me.

Since 3.2

### E_CREDENTIALS_KEY_PROMPT_FLAGS

    #define E_CREDENTIALS_KEY_PROMPT_FLAGS "prompt-flags"

FIXME Document me.

Since 3.2

### enum ECredentialsPromptFlags

    typedef enum {
    	E_CREDENTIALS_PROMPT_FLAG_REMEMBER_NEVER,
    	E_CREDENTIALS_PROMPT_FLAG_REMEMBER_SESSION,
    	E_CREDENTIALS_PROMPT_FLAG_REMEMBER_FOREVER,
    	E_CREDENTIALS_PROMPT_FLAG_REMEMBER_MASK = 0xf,

    	E_CREDENTIALS_PROMPT_FLAG_SECRET = 1 << 8, /* whether hide password letters in the UI */
    	E_CREDENTIALS_PROMPT_FLAG_REPROMPT = 1 << 9, /* automatically set when username and password is provided */
    	E_CREDENTIALS_PROMPT_FLAG_ONLINE = 1 << 10, /* only ask if we're online */
    	E_CREDENTIALS_PROMPT_FLAG_DISABLE_REMEMBER = 1 << 11, /* disable the 'remember password' checkbox */
    	E_CREDENTIALS_PROMPT_FLAG_PASSPHRASE = 1 << 12 /* We are asking a passphrase */
    } ECredentialsPromptFlags;

FIXME Document me.

Since 3.2

### e_credentials_new ()

    ECredentials *      e_credentials_new                   (void);

FIXME: Document me.

Since 3.2

### e_credentials_new_strv ()

    ECredentials *      e_credentials_new_strv              (const gchar * const *strv);

FIXME: Document me.

Since 3.2

### e_credentials_new_args ()

    ECredentials *      e_credentials_new_args              (const gchar *key,
                                                             ...);

FIXME: Document me.

Since 3.2

### e_credentials_new_clone ()

    ECredentials *      e_credentials_new_clone             (const ECredentials *credentials);

FIXME: Document me.

Since 3.2

### e_credentials_free ()

    void                e_credentials_free                  (ECredentials *credentials);

FIXME: Document me.

Since 3.2

### e_credentials_to_strv ()

    gchar **            e_credentials_to_strv               (const ECredentials *credentials);

Returns `NULL`-terminated array of strings with keys and encoded values; To read them back pass this pointer to `e_credentials_new()`. As it returns newly allocated string then this should be freed with `g_strfreev()` when no longer needed.

`credentials` : | an ECredentials
Returns : | a `NULL`-terminated array of key/value strings

Since 3.2

### e_credentials_set ()

    void                e_credentials_set                   (ECredentials *credentials,
                                                             const gchar *key,
                                                             const gchar *value);

Sets value for `key`, if `value` is `NULL` or an empty string then `key` is removed. The value is supposed to be in a clear form (unencoded). `key` cannot contain colon.

`credentials` : | an ECredentials
`key` : | a key string
`value` : | a value string

Since 3.2

### e_credentials_get ()

    gchar *             e_credentials_get                   (const ECredentials *credentials,
                                                             const gchar *key);

FIXME: Document me.

Since 3.2

### e_credentials_peek ()

    const gchar *       e_credentials_peek                  (ECredentials *credentials,
                                                             const gchar *key);

Peeks at the value for `key`, in a clear form. The returned value is valid until free of the `credentials` structure or until the key value is rewritten by `e_credentials_set()`.

`credentials` : | an ECredentials
`key` : | a key string
Returns : | the value for `key`

Since 3.2

### e_credentials_equal ()

    gboolean            e_credentials_equal                 (const ECredentials *credentials1,
                                                             const ECredentials *credentials2);

Returns whether two ECredential structures contain the same keys with same values.

`credentials1` : | an ECredentials
`credentials2` : | another ECredentials
Returns : | `TRUE` if they are equal, `FALSE` otherwise

Since 3.2

### e_credentials_equal_keys ()

    gboolean            e_credentials_equal_keys            (const ECredentials *credentials1,
                                                             const ECredentials *credentials2,
                                                             const gchar *key1,
                                                             ...);

Returns whether two ECredentials structures have the same keys. Key names are NULL-terminated.

`credentials1` : | an ECredentials
`credentials2` : | another ECredentials
Returns : | `TRUE` if the key sets match, `FALSE` otherwise

Since 3.2

### e_credentials_has_key ()

    gboolean            e_credentials_has_key               (const ECredentials *credentials,
                                                             const gchar *key);

Returns whether `credentials` contains `key`.

`credentials` : | an ECredentials
`key` : | a key string
Returns : | `TRUE` if `credentials` contains `key`, `FALSE` otherwise

Since 3.2

### e_credentials_keys_size ()

    guint               e_credentials_keys_size             (const ECredentials *credentials);

Returns the number of keys in `credentials`.

`credentials` : | an ECredentials
Returns : | the number of keys in `credentials`

Since 3.2

### e_credentials_list_keys ()

    GSList *            e_credentials_list_keys             (const ECredentials *credentials);

Returns a newly-allocated GSList of key names stored in `credentials`. The key names are internal credentials values and should not be modified or freed. Free the list with `g_slist_free()` when no longer needed.

`credentials` : | an ECredentials
Returns : | a newly-allocated GSList of key names

Since 3.2

### e_credentials_clear ()

    void                e_credentials_clear                 (ECredentials *credentials);

FIXME: Document me.

Since 3.2

### e_credentials_clear_peek ()

    void                e_credentials_clear_peek            (ECredentials *credentials);

FIXME: Document me.

Since 3.2

### e_credentials_util_safe_free_string ()

    void                e_credentials_util_safe_free_string (gchar *str);

FIXME Document me.

Since 3.2

### e_credentials_util_prompt_flags_to_string ()

    gchar *             e_credentials_util_prompt_flags_to_string
                                                            (guint prompt_flags);

FIXME: Document me.

Since 3.2

### e_credentials_util_string_to_prompt_flags ()

    guint               e_credentials_util_string_to_prompt_flags
                                                            (const gchar *prompt_flags_string);

FIXME: Document me.

Since 3.2