## Keyring Items

Keyring Items — Keyring items each hold a secret and a number of attributes.

## Synopsis

    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);

## Description

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.

## Details

### enum MateKeyringItemInfoFlags

    typedef enum {
    	MATE_KEYRING_ITEM_INFO_BASICS = 0,
    	MATE_KEYRING_ITEM_INFO_SECRET = 1<<0
    } MateKeyringItemInfoFlags;

### MateKeyringOperationGetItemInfoCallback ()

    void                (*MateKeyringOperationGetItemInfoCallback)
                                                            (MateKeyringResult result,
                                                             MateKeyringItemInfo *info,
                                                             gpointer data);

`result` : |
`info` : |
`data` : |

### MateKeyringOperationGetAttributesCallback ()

    void                (*MateKeyringOperationGetAttributesCallback)
                                                            (MateKeyringResult result,
                                                             MateKeyringAttributeList *attributes,
                                                             gpointer data);

`result` : |
`attributes` : |
`data` : |

### mate_keyring_item_create ()

    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()`.

`keyring` : | The name of the keyring in which to create the item, or NULL for the default keyring.
`type` : | The item type.
`display_name` : | The name of the item. This will be displayed to the user where necessary.
`attributes` : | A (possibly empty) list of attributes to store with the item.
`secret` : | The password or secret of the item.
`update_if_exists` : | If true, then another item matching the type, and attributes will be updated instead of creating a new item.
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asychronous request, which can be passed to `mate_keyring_cancel_request()`.

### mate_keyring_item_create_sync ()

    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);

`keyring` : |
`type` : |
`display_name` : |
`attributes` : |
`secret` : |
`update_if_exists` : |
`item_id` : |
Returns : |

### mate_keyring_item_delete ()

    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()`.

`keyring` : | The name of the keyring from which to delete the item, or NULL for the default keyring.
`id` : | The id of the item
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asychronous request, which can be passed to `mate_keyring_cancel_request()`.

### mate_keyring_item_delete_sync ()

    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()`.

`keyring` : | The name of the keyring from which to delete the item, or NULL for the default keyring.
`id` : | The id of the item
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_item_get_info ()

    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()`.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asychronous request, which can be passed to `mate_keyring_cancel_request()`.

### mate_keyring_item_get_info_full ()

    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()`.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`flags` : | The parts of the item to retrieve.
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asychronous request, which can be passed to `mate_keyring_cancel_request()`.

### mate_keyring_item_get_info_full_sync ()

    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()`.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`flags` : | The parts of the item to retrieve.
`info` : | The location to return a MateKeyringItemInfo pointer.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_item_get_info_sync ()

    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()`.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`info` : | The location to return a MateKeyringItemInfo pointer.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_item_set_info ()

    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()`.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`info` : | The item info to save into the item.
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asychronous request, which can be passed to `mate_keyring_cancel_request()`.

### mate_keyring_item_set_info_sync ()

    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()`.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`info` : | The item info to save into the item.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_item_get_attributes ()

    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()`.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asychronous request, which can be passed to `mate_keyring_cancel_request()`.

### mate_keyring_item_get_attributes_sync ()

    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()`.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`attributes` : | 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.

### mate_keyring_item_set_attributes ()

    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()`.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`attributes` : | The full list of attributes to set on the item.
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asychronous request, which can be passed to `mate_keyring_cancel_request()`.

### mate_keyring_item_set_attributes_sync ()

    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()`.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`attributes` : | 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.

### mate_keyring_item_get_acl ()

    gpointer            mate_keyring_item_get_acl          (const char *keyring,
                                                             guint32 id,
                                                             MateKeyringOperationGetListCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

### Warning

`mate_keyring_item_get_acl` is deprecated and should not be used in newly-written code. Never returns any ACL values.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asychronous request, which can be passed to `mate_keyring_cancel_request()`.

### mate_keyring_item_get_acl_sync ()

    MateKeyringResult  mate_keyring_item_get_acl_sync     (const char *keyring,
                                                             guint32 id,
                                                             GList **acl);

### Warning

`mate_keyring_item_get_acl_sync` is deprecated and should not be used in newly-written code. Never returns any acls.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`acl` : | The location to return a pointer to the access control list.
Returns : | Always `MATE_KEYRING_RESULT_OK`.

### mate_keyring_item_set_acl ()

    gpointer            mate_keyring_item_set_acl          (const char *keyring,
                                                             guint32 id,
                                                             GList *acl,
                                                             MateKeyringOperationDoneCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

### Warning

`mate_keyring_item_set_acl` is deprecated and should not be used in newly-written code. This function no longer has any effect.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`acl` : | The access control list to set on the item.
`callback` : | A callback which will be called when the request completes or fails.
`data` : | A pointer to arbitrary data that will be passed to the `callback`.
`destroy_data` : | A function to free `data` when it's no longer needed.
Returns : | The asychronous request, which can be passed to `mate_keyring_cancel_request()`.

### mate_keyring_item_set_acl_sync ()

    MateKeyringResult  mate_keyring_item_set_acl_sync     (const char *keyring,
                                                             guint32 id,
                                                             GList *acl);

### Warning

`mate_keyring_item_set_acl_sync` is deprecated and should not be used in newly-written code. This function no longer has any effect.

`keyring` : | The name of the keyring in which the item exists, or NULL for the default keyring.
`id` : | The id of the item
`acl` : | The access control list to set on the item.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### mate_keyring_item_grant_access_rights ()

    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);

### Warning

`mate_keyring_item_grant_access_rights` is deprecated and should not be used in newly-written code. This function no longer has any effect.

`keyring` : | The keyring name, or NULL for the default keyring.
`display_name` : | The display name for the application, as returned by `g_get_application_name()`.
`full_path` : | The full filepath to the application.
`id` : | The id of the item to grant access to.
`rights` : | The type of rights to grant.
`callback` : | Callback which is called when the operation completes
`data` : | Data to be passed to callback
`destroy_data` : | 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

### mate_keyring_item_grant_access_rights_sync ()

    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);

### Warning

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

`keyring` : | The keyring name, or NULL for the default keyring.
`display_name` : | The display name for the application, as returned by `g_get_application_name()`.
`full_path` : | The full filepath to the application.
`id` : | The id of the item to grant access to.
`rights` : | The type of rights to grant.
Returns : | `MATE_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.