e-passwords

## 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              (gint state);
    void                e_passwords_remember_password       (const gchar *component,
                                                             const gchar *key);
    void                e_passwords_add_password            (const gchar *key,
                                                             const gchar *passwd);
    gchar *             e_passwords_get_password            (const gchar *component,
                                                             const gchar *key);
    void                e_passwords_forget_password         (const gchar *component,
                                                             const gchar *key);
    void                e_passwords_forget_passwords        (void);
    void                e_passwords_clear_passwords         (const gchar *component);
    enum                EPasswordsRememberType;
    gchar *             e_passwords_ask_password            (const gchar *title,
                                                             const gchar *component_name,
                                                             const gchar *key,
                                                             const gchar *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              (gint 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.

### e_passwords_remember_password ()

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

Saves the password associated with `key` to disk.

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

### e_passwords_add_password ()

    void                e_passwords_add_password            (const gchar *key,
                                                             const gchar *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 ()

    gchar *             e_passwords_get_password            (const gchar *component,
                                                             const gchar *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 gchar *component,
                                                             const gchar *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 gchar *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 ()

    gchar *             e_passwords_ask_password            (const gchar *title,
                                                             const gchar *component_name,
                                                             const gchar *key,
                                                             const gchar *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` : |
`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.