![]() |
![]() |
![]() |
mate-keyring Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
enum MateKeyringItemInfoFlags; void (*MateKeyringOperationGetItemInfoCallback) (MateKeyringResult result
,MateKeyringItemInfo *info
,gpointer data
); void (*MateKeyringOperationGetAttributesCallback) (MateKeyringResult result
,MateKeyringAttributeList *attributes
,gpointer data
); gpointer mate_keyring_item_create (const char *keyring
,MateKeyringItemType type
,const char *display_name
,MateKeyringAttributeList *attributes
,const char *secret
,gboolean update_if_exists
,MateKeyringOperationGetIntCallback callback
,gpointer data
,GDestroyNotify destroy_data
); MateKeyringResult mate_keyring_item_create_sync (const char *keyring
,MateKeyringItemType type
,const char *display_name
,MateKeyringAttributeList *attributes
,const char *secret
,gboolean update_if_exists
,guint32 *item_id
); gpointer mate_keyring_item_delete (const char *keyring
,guint32 id
,MateKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
); MateKeyringResult mate_keyring_item_delete_sync (const char *keyring
,guint32 id
); gpointer mate_keyring_item_get_info (const char *keyring
,guint32 id
,MateKeyringOperationGetItemInfoCallback callback
,gpointer data
,GDestroyNotify destroy_data
); gpointer mate_keyring_item_get_info_full (const char *keyring
,guint32 id
,guint32 flags
,MateKeyringOperationGetItemInfoCallback callback
,gpointer data
,GDestroyNotify destroy_data
); MateKeyringResult mate_keyring_item_get_info_full_sync (const char *keyring
,guint32 id
,guint32 flags
,MateKeyringItemInfo **info
); MateKeyringResult mate_keyring_item_get_info_sync (const char *keyring
,guint32 id
,MateKeyringItemInfo **info
); gpointer mate_keyring_item_set_info (const char *keyring
,guint32 id
,MateKeyringItemInfo *info
,MateKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
); MateKeyringResult mate_keyring_item_set_info_sync (const char *keyring
,guint32 id
,MateKeyringItemInfo *info
); gpointer mate_keyring_item_get_attributes (const char *keyring
,guint32 id
,MateKeyringOperationGetAttributesCallback callback
,gpointer data
,GDestroyNotify destroy_data
); MateKeyringResult mate_keyring_item_get_attributes_sync (const char *keyring
,guint32 id
,MateKeyringAttributeList **attributes
); gpointer mate_keyring_item_set_attributes (const char *keyring
,guint32 id
,MateKeyringAttributeList *attributes
,MateKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
); MateKeyringResult mate_keyring_item_set_attributes_sync (const char *keyring
,guint32 id
,MateKeyringAttributeList *attributes
); gpointer mate_keyring_item_get_acl (const char *keyring
,guint32 id
,MateKeyringOperationGetListCallback callback
,gpointer data
,GDestroyNotify destroy_data
); MateKeyringResult mate_keyring_item_get_acl_sync (const char *keyring
,guint32 id
,GList **acl
); gpointer mate_keyring_item_set_acl (const char *keyring
,guint32 id
,GList *acl
,MateKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
); MateKeyringResult mate_keyring_item_set_acl_sync (const char *keyring
,guint32 id
,GList *acl
); gpointer mate_keyring_item_grant_access_rights (const gchar *keyring
,const gchar *display_name
,const gchar *full_path
,const guint32 id
,const MateKeyringAccessType rights
,MateKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
); MateKeyringResult mate_keyring_item_grant_access_rights_sync (const char *keyring
,const char *display_name
,const char *full_path
,const guint32 id
,const MateKeyringAccessType rights
);
A keyring contains multiple items. Each item has a secret, attributes and access information associated with it.
An item is identified by an unsigned integer unique to the keyring in which it exists. An item's name is for displaying to the user. Each item has a single secret, which is a null-terminated string. This secret is stored in non-pageable memory, and encrypted on disk. All of this information is exposed via MateKeyringItemInfo pointers.
Attributes allow various other pieces of information to be associated with an item. These can also be used to search for relevant items. Attributes are accessed with MateKeyringAttribute structures and built into lists using MateKeyringAttributeList.
Each item has an access control list, which specifies the applications that can read, write or delete an item. The read access applies only to reading the secret. All applications can read other parts of the item. ACLs are accessed and changed through MateKeyringAccessControl pointers.
typedef enum { MATE_KEYRING_ITEM_INFO_BASICS = 0, MATE_KEYRING_ITEM_INFO_SECRET = 1<<0 } MateKeyringItemInfoFlags;
void (*MateKeyringOperationGetItemInfoCallback) (MateKeyringResult result
,MateKeyringItemInfo *info
,gpointer data
);
|
|
|
|
|
void (*MateKeyringOperationGetAttributesCallback) (MateKeyringResult result
,MateKeyringAttributeList *attributes
,gpointer data
);
|
|
|
|
|
gpointer mate_keyring_item_create (const char *keyring
,MateKeyringItemType type
,const char *display_name
,MateKeyringAttributeList *attributes
,const char *secret
,gboolean update_if_exists
,MateKeyringOperationGetIntCallback callback
,gpointer data
,GDestroyNotify destroy_data
);
Create a new item in a keyring.
The secret
must be a null terminated string. It should be allocated using secure
memory whenever possible. See mate_keyring_memory_strdup()
The user may have been prompted to unlock necessary keyrings. If NULL
is
specified as the keyring
and no default keyring exists, the user will be
prompted to create a new keyring.
When update_if_exists
is set to TRUE
, the user may be prompted for access
to the previously existing item.
Whether a new item is created or not, id of the item will be passed to
the callback
.
For a synchronous version of this function see mate_keyring_item_create_sync()
.
|
The name of the keyring in which to create the item, or NULL for the default keyring. |
|
The item type. |
|
The name of the item. This will be displayed to the user where necessary. |
|
A (possibly empty) list of attributes to store with the item. |
|
The password or secret of the item. |
|
If true, then another item matching the type, and attributes will be updated instead of creating a new item. |
|
A callback which will be called when the request completes or fails. |
|
A pointer to arbitrary data that will be passed to the callback .
|
|
A function to free data when it's no longer needed.
|
Returns : |
The asychronous request, which can be passed to mate_keyring_cancel_request() .
|
MateKeyringResult mate_keyring_item_create_sync (const char *keyring
,MateKeyringItemType type
,const char *display_name
,MateKeyringAttributeList *attributes
,const char *secret
,gboolean update_if_exists
,guint32 *item_id
);
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Returns : |
gpointer mate_keyring_item_delete (const char *keyring
,guint32 id
,MateKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
);
Delete an item in a keyring.
The user may be prompted if the calling application doesn't have necessary access to delete the item.
For an asynchronous version of this function see mate_keyring_delete()
.
|
The name of the keyring from which to delete the item, or NULL for the default keyring. |
|
The id of the item |
|
A callback which will be called when the request completes or fails. |
|
A pointer to arbitrary data that will be passed to the callback .
|
|
A function to free data when it's no longer needed.
|
Returns : |
The asychronous request, which can be passed to mate_keyring_cancel_request() .
|
MateKeyringResult mate_keyring_item_delete_sync (const char *keyring
,guint32 id
);
Delete an item in a keyring.
The user may be prompted if the calling application doesn't have necessary access to delete the item.
For an asynchronous version of this function see mate_keyring_item_delete()
.
|
The name of the keyring from which to delete the item, or NULL for the default keyring. |
|
The id of the item |
Returns : |
MATE_KEYRING_RESULT_OK if the operation was succcessful or
an error result otherwise.
|
gpointer mate_keyring_item_get_info (const char *keyring
,guint32 id
,MateKeyringOperationGetItemInfoCallback callback
,gpointer data
,GDestroyNotify destroy_data
);
Get information about an item and its secret.
The user may be prompted if the calling application doesn't have necessary access to read the item with its secret.
A MateKeyringItemInfo structure will be passed to the callback
. This structure
will be freed after callback
returns.
For a synchronous version of this function see mate_keyring_item_get_info_sync()
.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
A callback which will be called when the request completes or fails. |
|
A pointer to arbitrary data that will be passed to the callback .
|
|
A function to free data when it's no longer needed.
|
Returns : |
The asychronous request, which can be passed to mate_keyring_cancel_request() .
|
gpointer mate_keyring_item_get_info_full (const char *keyring
,guint32 id
,guint32 flags
,MateKeyringOperationGetItemInfoCallback callback
,gpointer data
,GDestroyNotify destroy_data
);
Get information about an item, optionally retrieving its secret.
If flags
includes MATE_KEYRING_ITEM_INFO_SECRET
then the user may be
prompted if the calling application doesn't have necessary access to read
the item with its secret.
A MateKeyringItemInfo pointer will be passed to the callback
. Certain fields
of this structure may be NULL or zero if they were not specified in flags
. This
structure will be freed after callback
returns.
For a synchronous version of this function see mate_keyring_item_get_info_full_sync()
.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
The parts of the item to retrieve. |
|
A callback which will be called when the request completes or fails. |
|
A pointer to arbitrary data that will be passed to the callback .
|
|
A function to free data when it's no longer needed.
|
Returns : |
The asychronous request, which can be passed to mate_keyring_cancel_request() .
|
MateKeyringResult mate_keyring_item_get_info_full_sync (const char *keyring
,guint32 id
,guint32 flags
,MateKeyringItemInfo **info
);
Get information about an item, optionally retrieving its secret.
If flags
includes MATE_KEYRING_ITEM_INFO_SECRET
then the user may be
prompted if the calling application doesn't have necessary access to read
the item with its secret.
A MateKeyringItemInfo structure will be returned in info
. Certain fields
of this structure may be NULL or zero if they were not specified in flags
.
This must be freed using mate_keyring_item_info_free()
.
For an asynchronous version of this function see mate_keyring_item_get_info_full()
.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
The parts of the item to retrieve. |
|
The location to return a MateKeyringItemInfo pointer. |
Returns : |
MATE_KEYRING_RESULT_OK if the operation was succcessful or
an error result otherwise.
|
MateKeyringResult mate_keyring_item_get_info_sync (const char *keyring
,guint32 id
,MateKeyringItemInfo **info
);
Get information about an item and its secret.
The user may be prompted if the calling application doesn't have necessary access to read the item with its secret.
A MateKeyringItemInfo structure will be returned in info
. This must be
freed using mate_keyring_item_info_free()
.
For an asynchronous version of this function see mate_keyring_item_get_info()
.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
The location to return a MateKeyringItemInfo pointer. |
Returns : |
MATE_KEYRING_RESULT_OK if the operation was succcessful or
an error result otherwise.
|
gpointer mate_keyring_item_set_info (const char *keyring
,guint32 id
,MateKeyringItemInfo *info
,MateKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
);
Set information on an item, like its display name, secret etc...
Only the fields in the info
pointer that are non-null or non-zero will be
set on the item.
For a synchronous version of this function see mate_keyring_item_set_info_sync()
.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
The item info to save into the item. |
|
A callback which will be called when the request completes or fails. |
|
A pointer to arbitrary data that will be passed to the callback .
|
|
A function to free data when it's no longer needed.
|
Returns : |
The asychronous request, which can be passed to mate_keyring_cancel_request() .
|
MateKeyringResult mate_keyring_item_set_info_sync (const char *keyring
,guint32 id
,MateKeyringItemInfo *info
);
Set information on an item, like its display name, secret etc...
Only the fields in the info
pointer that are non-null or non-zero will be
set on the item.
For an asynchronous version of this function see mate_keyring_item_set_info()
.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
The item info to save into the item. |
Returns : |
MATE_KEYRING_RESULT_OK if the operation was succcessful or
an error result otherwise.
|
gpointer mate_keyring_item_get_attributes (const char *keyring
,guint32 id
,MateKeyringOperationGetAttributesCallback callback
,gpointer data
,GDestroyNotify destroy_data
);
Get all the attributes for an item.
A MateKeyringAttributeList will be passed to the callback
. This list will
be freed after callback
returns.
For a synchronous version of this function see mate_keyring_item_get_attributes_sync()
.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
A callback which will be called when the request completes or fails. |
|
A pointer to arbitrary data that will be passed to the callback .
|
|
A function to free data when it's no longer needed.
|
Returns : |
The asychronous request, which can be passed to mate_keyring_cancel_request() .
|
MateKeyringResult mate_keyring_item_get_attributes_sync (const char *keyring
,guint32 id
,MateKeyringAttributeList **attributes
);
Get all attributes for an item.
A MateKeyringAttributeList will be returned in attributes
. This should be
freed using mate_keyring_attribute_list_free()
.
For an asynchronous version of this function see mate_keyring_item_get_attributes()
.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
The location to return a pointer to the attribute list. |
Returns : |
MATE_KEYRING_RESULT_OK if the operation was succcessful or
an error result otherwise.
|
gpointer mate_keyring_item_set_attributes (const char *keyring
,guint32 id
,MateKeyringAttributeList *attributes
,MateKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
);
Set all the attributes for an item. This will replace any previous attributes set on the item.
For a synchronous version of this function see mate_keyring_item_set_attributes_sync()
.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
The full list of attributes to set on the item. |
|
A callback which will be called when the request completes or fails. |
|
A pointer to arbitrary data that will be passed to the callback .
|
|
A function to free data when it's no longer needed.
|
Returns : |
The asychronous request, which can be passed to mate_keyring_cancel_request() .
|
MateKeyringResult mate_keyring_item_set_attributes_sync (const char *keyring
,guint32 id
,MateKeyringAttributeList *attributes
);
Set all the attributes for an item. This will replace any previous attributes set on the item.
For an asynchronous version of this function see mate_keyring_item_set_attributes()
.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
The full list of attributes to set on the item. |
Returns : |
MATE_KEYRING_RESULT_OK if the operation was succcessful or
an error result otherwise.
|
gpointer mate_keyring_item_get_acl (const char *keyring
,guint32 id
,MateKeyringOperationGetListCallback callback
,gpointer data
,GDestroyNotify destroy_data
);
mate_keyring_item_get_acl
is deprecated and should not be used in newly-written code. Never returns any ACL values.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
A callback which will be called when the request completes or fails. |
|
A pointer to arbitrary data that will be passed to the callback .
|
|
A function to free data when it's no longer needed.
|
Returns : |
The asychronous request, which can be passed to mate_keyring_cancel_request() .
|
MateKeyringResult mate_keyring_item_get_acl_sync (const char *keyring
,guint32 id
,GList **acl
);
mate_keyring_item_get_acl_sync
is deprecated and should not be used in newly-written code. Never returns any acls.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
The location to return a pointer to the access control list. |
Returns : |
Always MATE_KEYRING_RESULT_OK .
|
gpointer mate_keyring_item_set_acl (const char *keyring
,guint32 id
,GList *acl
,MateKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
);
mate_keyring_item_set_acl
is deprecated and should not be used in newly-written code. This function no longer has any effect.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
The access control list to set on the item. |
|
A callback which will be called when the request completes or fails. |
|
A pointer to arbitrary data that will be passed to the callback .
|
|
A function to free data when it's no longer needed.
|
Returns : |
The asychronous request, which can be passed to mate_keyring_cancel_request() .
|
MateKeyringResult mate_keyring_item_set_acl_sync (const char *keyring
,guint32 id
,GList *acl
);
mate_keyring_item_set_acl_sync
is deprecated and should not be used in newly-written code. This function no longer has any effect.
|
The name of the keyring in which the item exists, or NULL for the default keyring. |
|
The id of the item |
|
The access control list to set on the item. |
Returns : |
MATE_KEYRING_RESULT_OK if the operation was succcessful or
an error result otherwise.
|
gpointer mate_keyring_item_grant_access_rights (const gchar *keyring
,const gchar *display_name
,const gchar *full_path
,const guint32 id
,const MateKeyringAccessType rights
,MateKeyringOperationDoneCallback callback
,gpointer data
,GDestroyNotify destroy_data
);
mate_keyring_item_grant_access_rights
is deprecated and should not be used in newly-written code. This function no longer has any effect.
|
The keyring name, or NULL for the default keyring. |
|
The display name for the application, as returned by g_get_application_name() .
|
|
The full filepath to the application. |
|
The id of the item to grant access to. |
|
The type of rights to grant. |
|
Callback which is called when the operation completes |
|
Data to be passed to callback |
|
Function to be called when data is no longer needed. |
Returns : |
The asychronous request, which can be passed to mate_keyring_cancel_request() .
|
Since 2.20
MateKeyringResult mate_keyring_item_grant_access_rights_sync (const char *keyring
,const char *display_name
,const char *full_path
,const guint32 id
,const MateKeyringAccessType rights
);
mate_keyring_item_grant_access_rights_sync
is deprecated and should not be used in newly-written code. This function no longer has any effect.
Will grant the application access rights to the item, provided callee has write access to said item.
|
The keyring name, or NULL for the default keyring. |
|
The display name for the application, as returned by g_get_application_name() .
|
|
The full filepath to the application. |
|
The id of the item to grant access to. |
|
The type of rights to grant. |
Returns : |
MATE_KEYRING_RESULT_OK if the operation was succcessful or
an error result otherwise.
|