gnome-keyring Reference Manual | ||||
---|---|---|---|---|
Top | Description |
Simple Password StorageSimple Password Storage — Store and lookup passwords with a set of attributes. |
Synopsis
GnomeKeyringPasswordSchema; GnomeKeyringPasswordSchemaAttribute; extern const GnomeKeyringPasswordSchema* GNOME_KEYRING_NETWORK_PASSWORD; #define GNOME_KEYRING_DEFAULT #define GNOME_KEYRING_SESSION gpointer gnome_keyring_store_password (const GnomeKeyringPasswordSchema *schema
,const gchar *keyring
,const gchar *display_name
,const gchar *password
,GnomeKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
,...
); GnomeKeyringResult gnome_keyring_store_password_sync (const GnomeKeyringPasswordSchema *schema
,const gchar *keyring
,const gchar *display_name
,const gchar *password
,...
); gpointer gnome_keyring_find_password (const GnomeKeyringPasswordSchema *schema
,GnomeKeyringOperationGetStringCallback callback
,gpointer data
,GDestroyNotify destroy_data
,...
); GnomeKeyringResult gnome_keyring_find_password_sync (const GnomeKeyringPasswordSchema *schema
,gchar **password
,...
); gpointer gnome_keyring_delete_password (const GnomeKeyringPasswordSchema *schema
,GnomeKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
,...
); GnomeKeyringResult gnome_keyring_delete_password_sync (const GnomeKeyringPasswordSchema *schema
,...
); void gnome_keyring_free_password (gchar *password
);
Description
This is a simple API for storing passwords and retrieving passwords in the keyring.
Each password is associated with a set of attributes. Attribute values can be either strings or unsigned integers.
The names and types of allowed attributes for a given password are defined with a
schema. Certain schemas are predefined such as GNOME_KEYRING_NETWORK_PASSWORD
.
Additional schemas can be defined via the GnomeKeyringPasswordSchema
structure.
Each function accepts a variable list of attributes names and their values.
Include a NULL
to terminate the list of attributes.
Example 1. Passing attributes to the functions
1 2 3 4 5 |
res = gnome_keyring_delete_password_sync (GNOME_KEYRING_NETWORK_PASSWORD, "user", "me", // A string attribute "server, "example.gnome.org", "port", "8080", // An integer attribute NULL); |
Details
GnomeKeyringPasswordSchema
typedef struct { GnomeKeyringItemType item_type; struct { const gchar* name; GnomeKeyringAttributeType type; } attributes[32]; } GnomeKeyringPasswordSchema;
Describes a password schema. Often you'll want to use a predefined schema such
as GNOME_KEYRING_NETWORK_PASSWORD
.
The last attribute name in a schema must be NULL
.
GnomeKeyringPasswordSchema my_schema = { GNOME_KEYRING_ITEM_GENERIC_SECRET, { { "string-attr", GNOME_KEYRING_ATTRIBUTE_TYPE_STRING }, { "uint-attr", GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32 }, { NULL, 0 } } };
GnomeKeyringItemType |
The item type for this schema. |
GnomeKeyringPasswordSchemaAttribute
typedef struct { const gchar* name; GnomeKeyringAttributeType type; } GnomeKeyringPasswordSchemaAttribute;
One attribute of a GnomeKeyringPasswordSchema.
const gchar * |
the attribute name |
the attribute data type |
GNOME_KEYRING_NETWORK_PASSWORD
extern const GnomeKeyringPasswordSchema* GNOME_KEYRING_NETWORK_PASSWORD;
A predefined schema for network paswsords. It contains the following attributes:
- user: A string for the user login.
- server: The server being connected to.
- protocol: The protocol used to access the server, such as 'http' or 'smb'
- domain: A realm or domain, such as a Windows login domain.
- port: The network port to used to connect to the server.
gnome_keyring_store_password ()
gpointer gnome_keyring_store_password (const GnomeKeyringPasswordSchema *schema
,const gchar *keyring
,const gchar *display_name
,const gchar *password
,GnomeKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
,...
);
Store a password associated with a given set of attributes.
Attributes which identify this password must be passed as additional arguments. Attributes passed must be defined in the schema.
If a password exists in the keyring that already has all the same arguments, then the password will be updated.
Another more complex way to create a keyring item is using gnome_keyring_item_create()
.
|
The password schema. |
|
The keyring to store the password in. Specify NULL
for the default keyring. Use GNOME_KEYRING_SESSION to store the
password in memory only. [allow-none]
|
|
A human readable description of what the password is for. |
|
The password to store. |
|
A callback which will be called when the request completes or fails. |
|
A pointer to arbitrary data that will be passed to the
callback . [allow-none]
|
|
A function to free data when it's no longer needed. |
|
The variable argument list should contain pairs of a) The attribute name as a null
terminated string, followed by b) attribute value, either a character string,
or 32-bit unsigned int, as defined in the password schema . The list of attribtues
should be terminated with a NULL . |
Returns : |
The asynchronous request, which can be passed
to gnome_keyring_cancel_request() . [transfer none]
|
Since 2.22
gnome_keyring_store_password_sync ()
GnomeKeyringResult gnome_keyring_store_password_sync (const GnomeKeyringPasswordSchema *schema
,const gchar *keyring
,const gchar *display_name
,const gchar *password
,...
);
Store a password associated with a given set of attributes.
Attributes which identify this password must be passed as additional arguments. Attributes passed must be defined in the schema.
This function may block for an unspecified period. If your application must
remain responsive to the user, then use gnome_keyring_store_password()
.
If a password exists in the keyring that already has all the same arguments, then the password will be updated.
Another more complex way to create a keyring item is using
gnome_keyring_item_create_sync()
.
|
The password schema. |
|
The keyring to store the password in. Specify NULL
for the default keyring. Use GNOME_KEYRING_SESSION to store the
password in memory only. [allow-none]
|
|
A human readable description of what the password is for. |
|
The password to store. |
|
The variable argument list should contain pairs of a) The attribute name as a null
terminated string, followed by b) attribute value, either a character string,
or 32-bit unsigned int, as defined in the password schema . The list of attribtues
should be terminated with a NULL . |
Returns : |
GNOME_KEYRING_RESULT_OK if the operation was succcessful or
an error result otherwise. |
Since 2.22
gnome_keyring_find_password ()
gpointer gnome_keyring_find_password (const GnomeKeyringPasswordSchema *schema
,GnomeKeyringOperationGetStringCallback callback
,gpointer data
,GDestroyNotify destroy_data
,...
);
Find a password that matches a given set of attributes.
Attributes which identify this password must be passed as additional arguments. Attributes passed must be defined in the schema.
The string that is passed to callback
is automatically freed when the
function returns.
Another more complex way to find items in the keyrings is using
gnome_keyring_find_items()
.
|
The password schema. |
|
A callback which will be called when the request completes or fails. |
|
A pointer to arbitrary data that will be passed to the
callback . [allow-none]
|
|
A function to free data when it's no longer needed. |
|
The variable argument list should contain pairs of a) The attribute name as a null
terminated string, followed by b) attribute value, either a character string,
or 32-bit unsigned int, as defined in the password schema . The list of attribtues
should be terminated with a NULL . |
Returns : |
The asynchronous request, which can be passed
to gnome_keyring_cancel_request() . [transfer none]
|
Since 2.22
gnome_keyring_find_password_sync ()
GnomeKeyringResult gnome_keyring_find_password_sync (const GnomeKeyringPasswordSchema *schema
,gchar **password
,...
);
Find a password that matches a given set of attributes.
Attributes which identify this password must be passed as additional arguments. Attributes passed must be defined in the schema.
This function may block for an unspecified period. If your application must
remain responsive to the user, then use gnome_keyring_find_password()
.
Another more complex way to find items in the keyrings is using
gnome_keyring_find_items_sync()
.
|
The password schema. |
|
An address to store password that was found. The password
must be freed with gnome_keyring_free_password() . [out]
|
|
The variable argument list should contain pairs of a) The attribute name as a null
terminated string, followed by b) attribute value, either a character string,
or 32-bit unsigned int, as defined in the password schema . The list of attribtues
should be terminated with a NULL . |
Returns : |
GNOME_KEYRING_RESULT_OK if the operation was succcessful or
an error result otherwise. |
Since 2.22
gnome_keyring_delete_password ()
gpointer gnome_keyring_delete_password (const GnomeKeyringPasswordSchema *schema
,GnomeKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
,...
);
Delete a password that matches a given set of attributes.
Attributes which identify this password must be passed as additional arguments. Attributes passed must be defined in the schema.
Another more complex way to find items in the keyrings is using
gnome_keyring_item_delete()
.
|
The password schema. |
|
A callback which will be called when the request completes or fails. |
|
A pointer to arbitrary data that will be passed to the
callback . [allow-none]
|
|
A function to free data when it's no longer needed. |
|
The variable argument list should contain pairs of a) The attribute name as a null
terminated string, followed by b) attribute value, either a character string,
or 32-bit unsigned int, as defined in the password schema . The list of attribtues
should be terminated with a NULL . |
Returns : |
The asynchronous request, which can be passed
to gnome_keyring_cancel_request() . [transfer none]
|
Since 2.22
gnome_keyring_delete_password_sync ()
GnomeKeyringResult gnome_keyring_delete_password_sync (const GnomeKeyringPasswordSchema *schema
,...
);
Delete a password that matches a given set of attributes.
Attributes which identify this password must be passed as additional arguments. Attributes passed must be defined in the schema.
This function may block for an unspecified period. If your application must
remain responsive to the user, then use gnome_keyring_delete_password()
.
Another more complex way to find items in the keyrings is using
gnome_keyring_item_delete_sync()
.
|
The password schema. |
|
The variable argument list should contain pairs of a) The attribute name as a null
terminated string, followed by b) attribute value, either a character string,
or 32-bit unsigned int, as defined in the password schema . The list of attribtues
should be terminated with a NULL . |
Returns : |
GNOME_KEYRING_RESULT_OK if the operation was succcessful or
an error result otherwise. |
Since 2.22