## e-passwords

e-passwords

## Synopsis

    void                e_passwords_init                    (void);
    void                e_passwords_shutdown                (void);
    void                e_passwords_cancel                  (void);
    void                e_passwords_set_online              (int state);
    void                e_passwords_remember_password       (const char *component,
                                                             const char *key);
    void                e_passwords_add_password            (const char *key,
                                                             const char *passwd);
    char*               e_passwords_get_password            (const char *component,
                                                             const char *key);
    void                e_passwords_forget_password         (const char *component,
                                                             const char *key);
    void                e_passwords_forget_passwords        (void);
    void                e_passwords_clear_passwords         (const char *component);
    enum                EPasswordsRememberType;
    char*               e_passwords_ask_password            (const char *title,
                                                             const char *component_name,
                                                             const char *key,
                                                             const char *prompt,
                                                             EPasswordsRememberType remember_type,
                                                             gboolean *remember,
                                                             GtkWindow *parent);

## Description

## Details

### e_passwords_init ()

    void                e_passwords_init                    (void);

Initializes the e_passwords routines. Must be called before any other e_passwords_* function.

### e_passwords_shutdown ()

    void                e_passwords_shutdown                (void);

Cleanup routine to call before exiting.

### e_passwords_cancel ()

    void                e_passwords_cancel                  (void);

Cancel any outstanding password operations and close any dialogues currently being shown.

### e_passwords_set_online ()

    void                e_passwords_set_online              (int state);

Set the offline-state of the application. This is a work-around for having the backends fully offline aware, and returns a cancellation response instead of prompting for passwords.

FIXME: This is not a permanent api, review post 2.0.

`state` : |

### e_passwords_remember_password ()

    void                e_passwords_remember_password       (const char *component,
                                                             const char *key);

Saves the password associated with `key` to disk.

`component` : |
`key` : | the key

### e_passwords_add_password ()

    void                e_passwords_add_password            (const char *key,
                                                             const char *passwd);

This stores the `key`/`passwd` pair in the current session's password hash.

`key` : | a key
`passwd` : | the password for `key`

### e_passwords_get_password ()

    char*               e_passwords_get_password            (const char *component,
                                                             const char *key);

`component` : |
`key` : | the key
Returns : | the password associated with `key`, or `NULL`. Caller must free the returned password.

### e_passwords_forget_password ()

    void                e_passwords_forget_password         (const char *component,
                                                             const char *key);

Forgets the password associated with `key`, in memory and on disk.

`component` : |
`key` : | the key

### e_passwords_forget_passwords ()

    void                e_passwords_forget_passwords        (void);

Forgets all cached passwords, in memory and on disk.

### e_passwords_clear_passwords ()

    void                e_passwords_clear_passwords         (const char *component);

Forgets all disk cached passwords for the component.

`component` : |

### enum EPasswordsRememberType

    typedef enum {
    	E_PASSWORDS_REMEMBER_NEVER,
    	E_PASSWORDS_REMEMBER_SESSION,
    	E_PASSWORDS_REMEMBER_FOREVER,
    	E_PASSWORDS_REMEMBER_MASK = 0xf,

    	/* option bits */
    	E_PASSWORDS_SECRET = 1<<8,
    	E_PASSWORDS_REPROMPT = 1<<9,
    	E_PASSWORDS_ONLINE = 1<<10, /* only ask if we're online */
    	E_PASSWORDS_DISABLE_REMEMBER = 1<<11, /* disable the 'remember password' checkbox */
    	E_PASSWORDS_PASSPHRASE = 1<<12, /* We are asking a passphrase */
    } EPasswordsRememberType;

### e_passwords_ask_password ()

    char*               e_passwords_ask_password            (const char *title,
                                                             const char *component_name,
                                                             const char *key,
                                                             const char *prompt,
                                                             EPasswordsRememberType remember_type,
                                                             gboolean *remember,
                                                             GtkWindow *parent);

Asks the user for a password.

`title` : | title for the password dialog
`component_name` : | the name of the component for which we're storing the password (e.g. Mail, Addressbook, etc.)
`key` : | key to store the password under
`prompt` : | prompt string
`remember_type` : | whether or not to offer to remember the password, and for how long.
`remember` : | on input, the default state of the remember checkbox. on output, the state of the checkbox when the dialog was closed.
`parent` : | parent window of the dialog, or `NULL`
Returns : | the password, which the caller must free, or `NULL` if the user cancelled the operation. *`remember` will be set if the return value is non-`NULL` and `remember_type` is not E_PASSWORDS_DO_NOT_REMEMBER.