## TrackerPasswordProvider TrackerPasswordProvider — Password storage interface for cross platform backends |

## Synopsis

    #include <libtracker-miner/tracker-miner.h>

    #define             TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN
    #define             TRACKER_PASSWORD_PROVIDER_ERROR
    enum                TrackerPasswordProviderError;
    GQuark              tracker_password_provider_error_quark
                                                            (void);
    #define             TRACKER_PASSWORD_PROVIDER_GET_INTERFACE(o)
    typedef             TrackerPasswordProvider;
                        TrackerPasswordProviderIface;
    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

The TrackerPasswordProvider allows different backends to be written for storing sensitive information about web services which are needed to authenticate and mine data. Currently, there are two implementations. One for GNOME Keyring and one using GKeyFile (as a fallback if GNOME Keyring is installed).

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

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

### tracker_password_provider_error_quark ()

    GQuark              tracker_password_provider_error_quark
                                                            (void);

### TRACKER_PASSWORD_PROVIDER_GET_INTERFACE()

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

### TrackerPasswordProvider

    typedef struct TrackerPasswordProvider TrackerPasswordProvider;

### TrackerPasswordProviderIface

    typedef struct {
    	GTypeInterface parent_iface;

    	gboolean (* store_password)  (TrackerPasswordProvider  *provider,
    	                              const gchar              *service,
    	                              const gchar              *description,
    	                              const gchar              *username,
    	                              const gchar              *password,
    	                              GError                  **error);
    	gchar *  (* get_password)    (TrackerPasswordProvider  *provider,
    	                              const gchar              *service,
    	                              gchar                   **username,
    	                              GError                  **error);
    	gboolean (* forget_password) (TrackerPasswordProvider  *provider,
    	                              const gchar              *service,
    	                              GError                  **error);
    } TrackerPasswordProviderIface;

GTypeInterface `parent_iface`; | parent object interface
`store_password` () | save the service, username and password
`get_password` () | get a password for a given service
`forget_password` () | forget any password associated with a given service

Since 0.8

### 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`.

Since 0.8

### 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()`. [out][transfer full]

Since 0.8

### 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. [out callee-allocates][transfer full][allow-none]
Returns : | `TRUE` if the password was saved, otherwise `FALSE` is returned and `error` will be set.

Since 0.8

### 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. [out]
`error` : | return location for errors. [out callee-allocates][transfer full][allow-none]
Returns : | a newly allocated string representing a password which must be freed with `g_free()`, otherwise `NULL` is returned and `error` will be set.

Since 0.8

### 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. [out callee-allocates][transfer full][allow-none]

Since 0.8

### 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. [transfer full]

Since 0.8

### 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.

Since 0.8