e-credentials: Evolution-Data-Server Reference Manual

## e-credentials e-credentials |

## Functions

ECredentials * | e_credentials_new ()
ECredentials * | e_credentials_new_strv ()
ECredentials * | e_credentials_new_args ()
ECredentials * | e_credentials_new_clone ()
void | e_credentials_free ()
gchar ** | e_credentials_to_strv ()
void | e_credentials_set ()
gchar * | e_credentials_get ()
const gchar * | e_credentials_peek ()
gboolean | e_credentials_equal ()
gboolean | e_credentials_equal_keys ()
gboolean | e_credentials_has_key ()
guint | e_credentials_keys_size ()
GSList * | e_credentials_list_keys ()
void | e_credentials_clear ()
void | e_credentials_clear_peek ()
void | e_credentials_util_safe_free_string ()
gchar * | e_credentials_util_prompt_flags_to_string ()
guint | e_credentials_util_string_to_prompt_flags ()

## Types and Values

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
#define | E_CREDENTIALS_KEY_FOREIGN_REQUEST
enum | ECredentialsPromptFlags
| ECredentialsPrivate

## Description

## Functions

### e_credentials_new ()

    ECredentials *
    e_credentials_new (void);

`e_credentials_new` is deprecated and should not be used in newly-written code.

#### Returns

a new empty ECredentials. Free with `e_credentials_free()` when done with it.

[transfer full]

Since: 3.2

### e_credentials_new_strv ()

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

`e_credentials_new_strv` is deprecated and should not be used in newly-written code.

Creates a new ECredentials with prefilled key/value-s from `strv` . It expects the `strv` as a NULL-terminated list of strings "key:encoded_value". The same can be returned from `e_credentials_to_strv()`.

#### Parameters

strv | an array of key/value-s to prefill |

#### Returns

a new ECredentials. Free with `e_credentials_free()` when done with it.

[transfer full]

Since: 3.2

### e_credentials_new_args ()

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

`e_credentials_new_args` is deprecated and should not be used in newly-written code.

Creates a new ECredentials with prefilled keys. The arguments is a NULL-terminated list of string pairs <key, value>; value is in a clear form.

#### Parameters

key | the first key name |
... | value, followed by key,value pairs, terminated with `NULL` |

#### Returns

a new ECredentials. Free with `e_credentials_free()` when done with it.

[transfer full]

Since: 3.2

### e_credentials_new_clone ()

    ECredentials *
    e_credentials_new_clone (const ECredentials *credentials);

`e_credentials_new_clone` is deprecated and should not be used in newly-written code.

#### Parameters

credentials | an ECredentials |

#### Returns

Creates a clone (copy) of the given `credentials` . Free with `e_credentials_free()` when done with it.

[transfer full]

Since: 3.2

### e_credentials_free ()

    void
    e_credentials_free (ECredentials *credentials);

`e_credentials_free` is deprecated and should not be used in newly-written code.

Frees the `credentials` . Any peek-ed values are invalidated by this call.

#### Parameters

credentials | an ECredentials |

Since: 3.2

### e_credentials_to_strv ()

    gchar **
    e_credentials_to_strv (const ECredentials *credentials);

`e_credentials_to_strv` is deprecated and should not be used in newly-written code.

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.

#### Parameters

credentials | an ECredentials |

#### Returns

a NULL-terminated array of key/value strings.

[transfer full]

Since: 3.2

### e_credentials_set ()

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

`e_credentials_set` is deprecated and should not be used in newly-written code.

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.

#### Parameters

credentials | an ECredentials |
key | a key string |
value | a value string. | [nullable]

Since: 3.2

### e_credentials_get ()

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

`e_credentials_get` is deprecated and should not be used in newly-written code.

#### Parameters

credentials | an ECredentials |
key | a key name |

#### Returns

A copy of the key's value, or `NULL`, if no such key is stored in the `credentuals` . Free returned string with `e_credentials_util_safe_free_string()`, when done with it.

[transfer full][nullable]

Since: 3.2

### e_credentials_peek ()

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

`e_credentials_peek` is deprecated and should not be used in newly-written code.

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

#### Parameters

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);

`e_credentials_equal` is deprecated and should not be used in newly-written code.

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

#### Parameters

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,
                              ...);

`e_credentials_equal_keys` is deprecated and should not be used in newly-written code.

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

#### Parameters

credentials1 | an ECredentials |
credentials2 | another ECredentials |
key1 | the first key name |
... | other key names, terminated with `NULL` |

#### 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);

`e_credentials_has_key` is deprecated and should not be used in newly-written code.

Returns whether `credentials` contains `key` .

#### Parameters

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);

`e_credentials_keys_size` is deprecated and should not be used in newly-written code.

Returns the number of keys in `credentials` .

#### Parameters

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);

`e_credentials_list_keys` is deprecated and should not be used in newly-written code.

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.

#### Parameters

credentials | an ECredentials |

#### Returns

a newly-allocated GSList of key names.

[transfer container][element-type utf8]

Since: 3.2

### e_credentials_clear ()

    void
    e_credentials_clear (ECredentials *credentials);

`e_credentials_clear` is deprecated and should not be used in newly-written code.

Clears all the stored keys (and their peek-ed values).

#### Parameters

credentials | an ECredentials |

Since: 3.2

### e_credentials_clear_peek ()

    void
    e_credentials_clear_peek (ECredentials *credentials);

`e_credentials_clear_peek` is deprecated and should not be used in newly-written code.

Clears cache of peek-ed values.

#### Parameters

credentials | an ECredentials |

Since: 3.2

### e_credentials_util_safe_free_string ()

    void
    e_credentials_util_safe_free_string (gchar *str);

`e_credentials_util_safe_free_string` is deprecated and should not be used in newly-written code.

Frees a nul-terminated string safely, which means it overwrites the content first and only then calls `g_free()` on it. If `str` is `NULL`, then does nothing.

#### Parameters

str | a string to safely free. | [nullable]

Since: 3.2

### e_credentials_util_prompt_flags_to_string ()

    gchar *
    e_credentials_util_prompt_flags_to_string
                                   (guint prompt_flags);

`e_credentials_util_prompt_flags_to_string` is deprecated and should not be used in newly-written code.

Converts bit-or of # to a string representation. Use `e_credentials_util_string_to_prompt_flags()` to convert the string back to the numeric representation.

#### Parameters

prompt_flags | bit-or of ECredentialsPromptFlags |

#### Returns

text representation of the `prompt_flags` .

[transfer full]

Since: 3.2

### e_credentials_util_string_to_prompt_flags ()

    guint
    e_credentials_util_string_to_prompt_flags
                                   (const gchar *prompt_flags_string);

`e_credentials_util_string_to_prompt_flags` is deprecated and should not be used in newly-written code.

Converts ECredentialsPromptFlags represented as string back to the numeric representation. This is a reverse function of `e_credentials_util_prompt_flags_to_string()`.

#### Parameters

prompt_flags_string | flags encoded as string |

#### Returns

decoded bit-or of ECredentialsPromptFlags

Since: 3.2

## Types and Values

### struct ECredentials

    struct ECredentials {
    };

`ECredentials` is deprecated and should not be used in newly-written code.

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"

`E_CREDENTIALS_KEY_USERNAME` is deprecated and should not be used in newly-written code.

FIXME Docment me.

Since: 3.2

### E_CREDENTIALS_KEY_PASSWORD

    #define E_CREDENTIALS_KEY_PASSWORD "password"

`E_CREDENTIALS_KEY_PASSWORD` is deprecated and should not be used in newly-written code.

FIXME Document me.

Since: 3.2

### E_CREDENTIALS_KEY_AUTH_METHOD

    #define E_CREDENTIALS_KEY_AUTH_METHOD "auth-method"

`E_CREDENTIALS_KEY_AUTH_METHOD` is deprecated and should not be used in newly-written code.

FIXME Document me.

Since: 3.2

### E_CREDENTIALS_KEY_PROMPT_TITLE

    #define E_CREDENTIALS_KEY_PROMPT_TITLE "prompt-title"

`E_CREDENTIALS_KEY_PROMPT_TITLE` is deprecated and should not be used in newly-written code.

FIXME Document me.

Since: 3.2

### E_CREDENTIALS_KEY_PROMPT_TEXT

    #define E_CREDENTIALS_KEY_PROMPT_TEXT "prompt-text"

`E_CREDENTIALS_KEY_PROMPT_TEXT` is deprecated and should not be used in newly-written code.

FIXME: Document me.

Since: 3.2

### E_CREDENTIALS_KEY_PROMPT_REASON

    #define E_CREDENTIALS_KEY_PROMPT_REASON "prompt-reason"

`E_CREDENTIALS_KEY_PROMPT_REASON` is deprecated and should not be used in newly-written code.

FIXME: Document me.

Since: 3.2

### E_CREDENTIALS_KEY_PROMPT_KEY

    #define E_CREDENTIALS_KEY_PROMPT_KEY "prompt-key"

`E_CREDENTIALS_KEY_PROMPT_KEY` is deprecated and should not be used in newly-written code.

FIXME: Document me.

Since: 3.2

### E_CREDENTIALS_KEY_PROMPT_FLAGS

    #define E_CREDENTIALS_KEY_PROMPT_FLAGS "prompt-flags"

`E_CREDENTIALS_KEY_PROMPT_FLAGS` is deprecated and should not be used in newly-written code.

FIXME Document me.

Since: 3.2

### E_CREDENTIALS_KEY_FOREIGN_REQUEST

    #define E_CREDENTIALS_KEY_FOREIGN_REQUEST "foreign-request"

`E_CREDENTIALS_KEY_FOREIGN_REQUEST` is deprecated and should not be used in newly-written code.

Set to "1" when the ECredentials is used to authenticate other than current EClient.

Since: 3.4

### enum ECredentialsPromptFlags

`ECredentialsPromptFlags` is deprecated and should not be used in newly-written code.

Flags for a credentials prompt.

#### Members

E_CREDENTIALS_PROMPT_FLAG_REMEMBER_NEVER | never remember the credentials |
E_CREDENTIALS_PROMPT_FLAG_REMEMBER_SESSION | remember the credentials only for the current session |
E_CREDENTIALS_PROMPT_FLAG_REMEMBER_FOREVER | remember the credentials forever |
E_CREDENTIALS_PROMPT_FLAG_REMEMBER_MASK | a bit-mask of the 'remember' flags |
E_CREDENTIALS_PROMPT_FLAG_SECRET | whether hide password letters in the UI |
E_CREDENTIALS_PROMPT_FLAG_REPROMPT | whether this is a re-prompt |
E_CREDENTIALS_PROMPT_FLAG_ONLINE | only ask if we're online |
E_CREDENTIALS_PROMPT_FLAG_DISABLE_REMEMBER | disable the 'remember password' checkbox |
E_CREDENTIALS_PROMPT_FLAG_PASSPHRASE | we are asking a passphrase |

Since: 3.2

### ECredentialsPrivate

    typedef struct _ECredentialsPrivate ECredentialsPrivate;

`ECredentialsPrivate` is deprecated and should not be used in newly-written code.