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.