## TrackerPasswordProvider

TrackerPasswordProvider

## Synopsis

    #define             TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN
    #define             TRACKER_PASSWORD_PROVIDER_ERROR
    #define             TRACKER_PASSWORD_PROVIDER_GET_INTERFACE(o)
    typedef             TrackerPasswordProvider;
    enum                TrackerPasswordProviderError;
    typedef             TrackerPasswordProviderIface;
    GQuark              tracker_password_provider_error_quark
                                                            (void);
    TrackerPasswordProvider * tracker_password_provider_get (void);
    gchar *             tracker_password_provider_get_name  (TrackerPasswordProvider *provider);
    gboolean            tracker_password_provider_store_password
                                                            (TrackerPasswordProvider *provider,
                                                             const gchar *service,
                                                             const gchar *description,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             GError **error);
    gchar *             tracker_password_provider_get_password
                                                            (TrackerPasswordProvider *provider,
                                                             const gchar *service,
                                                             gchar **username,
                                                             GError **error);
    void                tracker_password_provider_forget_password
                                                            (TrackerPasswordProvider *provider,
                                                             const gchar *service,
                                                             GError **error);
    gchar *             tracker_password_provider_lock_password
                                                            (const gchar *password);
    gboolean            tracker_password_provider_unlock_password
                                                            (gchar *password);

## Description

## Details

### TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN

    #define TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN  "TrackerPasswordProvider"

### TRACKER_PASSWORD_PROVIDER_ERROR

    #define TRACKER_PASSWORD_PROVIDER_ERROR         tracker_password_provider_error_quark()

### TRACKER_PASSWORD_PROVIDER_GET_INTERFACE()

    #define TRACKER_PASSWORD_PROVIDER_GET_INTERFACE(o) (G_TYPE_INSTANCE_GET_INTERFACE ((o),  TRACKER_TYPE_PASSWORD_PROVIDER, TrackerPasswordProviderIface))

`o` : |

### TrackerPasswordProvider

    typedef struct TrackerPasswordProvider TrackerPasswordProvider;

### enum TrackerPasswordProviderError

    typedef enum {
    	TRACKER_PASSWORD_PROVIDER_ERROR_SERVICE,
    	TRACKER_PASSWORD_PROVIDER_ERROR_NOTFOUND
    } TrackerPasswordProviderError;

The following errors are possible during any of the performed actions with a password provider.

`TRACKER_PASSWORD_PROVIDER_ERROR_SERVICE` | An internal error occurred which meant the operation failed.
`TRACKER_PASSWORD_PROVIDER_ERROR_NOTFOUND` | No password provider was found to store/retrieve the remote service's authentication credentials

Since 0.8

### TrackerPasswordProviderIface

    typedef struct TrackerPasswordProviderIface TrackerPasswordProviderIface;

Since 0.8.

### tracker_password_provider_error_quark ()

    GQuark              tracker_password_provider_error_quark
                                                            (void);

Returns : | the GQuark used to identify password provider errors in GError structures.

### tracker_password_provider_get ()

    TrackerPasswordProvider * tracker_password_provider_get (void);

This function MUST be defined by the implementation of TrackerPasswordProvider.

For example, tracker-password-provider-gnome.c should include this function for a GNOME Keyring implementation.

Only one implementation can exist at once.

Returns : | a `TrackerPasswordProvider`.

### tracker_password_provider_get_name ()

    gchar *             tracker_password_provider_get_name  (TrackerPasswordProvider *provider);

At the moment there are only two providers, "GNOME Keyring" and "GKeyFile". Either of these is what will be returned unless new providers are written.

`provider` : | a TrackerPasswordProvider
Returns : | a newly allocated string representing the "name" which must be freed with `g_free()`.

### tracker_password_provider_store_password ()

    gboolean            tracker_password_provider_store_password
                                                            (TrackerPasswordProvider *provider,
                                                             const gchar *service,
                                                             const gchar *description,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             GError **error);

This function calls the password provider's "store_password" implementation with `service`, `description`, `username` and `password`.

`provider` : | a TrackerPasswordProvider
`service` : | the name of the remote service associated with `username` and `password`
`description` : | the description for `service`
`username` : | the username to store
`password` : | the password to store
`error` : | return location for errors
Returns : | `TRUE` if the password was saved, otherwise `FALSE` is returned and `error` will be set.

### tracker_password_provider_get_password ()

    gchar *             tracker_password_provider_get_password
                                                            (TrackerPasswordProvider *provider,
                                                             const gchar *service,
                                                             gchar **username,
                                                             GError **error);

This function calls the password provider's "get_password" implementation with `service` and `username`.

`provider` : | a TrackerPasswordProvider
`service` : | the name of the remote service associated with `username`
`username` : | the username associated with the password we are returning
`error` : | return location for errors
Returns : | a newly allocated string representing a password which must be freed with `g_free()`, otherwise `NULL` is returned and `error` will be set.

### tracker_password_provider_forget_password ()

    void                tracker_password_provider_forget_password
                                                            (TrackerPasswordProvider *provider,
                                                             const gchar *service,
                                                             GError **error);

This function calls the password provider's "forget_password" implementation with `service`.

On failure `error` will be set.

`provider` : | a TrackerPasswordProvider
`service` : | the name of the remote service associated with `username`
`error` : | return location for errors

### tracker_password_provider_lock_password ()

    gchar *             tracker_password_provider_lock_password
                                                            (const gchar *password);

This function calls `mlock()` to secure a memory region newly allocated and `password` is copied using `memcpy()` into the new address.

Password can not be `NULL` or an empty string ("").

`password` : | a string pointer
Returns : | a newly allocated string which MUST be freed with `tracker_password_provider_unlock_password()`. On failure `NULL` is returned.

### tracker_password_provider_unlock_password ()

    gboolean            tracker_password_provider_unlock_password
                                                            (gchar *password);

This function calls `munlock()` on `password` which should be a secured memory region. The `password` is zeroed first with `bzero()` and once unlocked it is freed with `g_free()`.

The `password` can not be `NULL` or an empty string (""). In addition, `password` MUST be a string created with `tracker_password_provider_lock_password()`.

`password` : | a string pointer
Returns : | `TRUE` if `munlock()` succeeded, otherwise `FALSE` is returned.