Search Functionality
3
GNOME-KEYRING Library

# Search Functionality

Find Keyring Items

## Synopsis

                        GnomeKeyringFound;
    void                gnome_keyring_found_free            (GnomeKeyringFound *found);
    void                gnome_keyring_found_list_free       (GList *found_list);
    gpointer            gnome_keyring_find_items            (GnomeKeyringItemType type,
                                                             GnomeKeyringAttributeList *attributes,
                                                             GnomeKeyringOperationGetListCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);
    gpointer            gnome_keyring_find_itemsv           (GnomeKeyringItemType type,
                                                             GnomeKeyringOperationGetListCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data,
                                                             ...);
    GnomeKeyringResult  gnome_keyring_find_items_sync       (GnomeKeyringItemType type,
                                                             GnomeKeyringAttributeList *attributes,
                                                             GList **found);
    GnomeKeyringResult  gnome_keyring_find_itemsv_sync      (GnomeKeyringItemType type,
                                                             GList **found,
                                                             ...);

## Description

A find operation searches through all keyrings for items that match the attributes. The user may have been prompted to unlock necessary keyrings, and user will have been prompted for access to the items if needed.

A find operation may return multiple or zero results.

## Details

### GnomeKeyringFound

    typedef struct {
    	char *keyring;
    	guint item_id;
    	GnomeKeyringAttributeList *attributes;
    	char *secret;
    } GnomeKeyringFound;

### gnome_keyring_found_free ()

    void                gnome_keyring_found_free            (GnomeKeyringFound *found);

Free the memory used by a GnomeKeyringFound item.

You usually want to use `gnome_keyring_found_list_free()` on the list of results.

`found` :

  a GnomeKeyringFound

### gnome_keyring_found_list_free ()

    void                gnome_keyring_found_list_free       (GList *found_list);

Free the memory used by the GnomeKeyringFound items in `found_list`.

`found_list` :

  a GList of GnomeKeyringFound

### gnome_keyring_find_items ()

    gpointer            gnome_keyring_find_items            (GnomeKeyringItemType type,
                                                             GnomeKeyringAttributeList *attributes,
                                                             GnomeKeyringOperationGetListCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data);

Searches through all keyrings for items that match the `attributes`. The matches are for exact equality.

A `GList` of GnomeKeyringFound structures are passed to the `callback`. The list and structures are freed after the callback returns.

The user may have been prompted to unlock necessary keyrings, and user will have been prompted for access to the items if needed.

For a synchronous version of this function see `gnome_keyring_find_items_sync()`.

`type` :

  The type of items to find.

`attributes` :

  A list of attributes to search for. This cannot be an empty list.

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

### gnome_keyring_find_itemsv ()

    gpointer            gnome_keyring_find_itemsv           (GnomeKeyringItemType type,
                                                             GnomeKeyringOperationGetListCallback callback,
                                                             gpointer data,
                                                             GDestroyNotify destroy_data,
                                                             ...);

Searches through all keyrings for items that match the specified attributes. The matches are for exact equality.

The variable argument list should contain a) The attribute name as a null terminated string, followed by b) The attribute type, either `GNOME_KEYRING_ATTRIBUTE_TYPE_STRING` or `GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32` and then the c) attribute value, either a character string, or 32-bit unsigned int. The list should be terminated with a NULL.

A `GList` of GnomeKeyringFound structures are passed to the `callback`. The list and structures are freed after the callback returns.

The user may have been prompted to unlock necessary keyrings, and user will have been prompted for access to the items if needed.

For a synchronous version of this function see `gnome_keyring_find_itemsv_sync()`.

`type` :

  The type of items to find.

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

### gnome_keyring_find_items_sync ()

    GnomeKeyringResult  gnome_keyring_find_items_sync       (GnomeKeyringItemType type,
                                                             GnomeKeyringAttributeList *attributes,
                                                             GList **found);

Searches through all keyrings for items that match the `attributes` and `type`. The matches are for exact equality.

A `GList` of GnomeKeyringFound structures is returned in `found`. The list may have zero items if nothing matched the criteria. The list should be freed using `gnome_keyring_found_list_free()`.

The user may have been prompted to unlock necessary keyrings, and user will have been prompted for access to the items if needed.

For an asynchronous version of this function see `gnome_keyring_find_items()`.

`type` :

  The type of items to find.

`attributes` :

  A list of attributes to search for. This cannot be an empty list.

`found` :

  The location to return a list of GnomeKeyringFound pointers.

Returns :

  `GNOME_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.

### gnome_keyring_find_itemsv_sync ()

    GnomeKeyringResult  gnome_keyring_find_itemsv_sync      (GnomeKeyringItemType type,
                                                             GList **found,
                                                             ...);

Searches through all keyrings for items that match the `attributes` and `type`. The matches are for exact equality.

The variable argument list should contain a) The attribute name as a null terminated string, followed by b) The attribute type, either `GNOME_KEYRING_ATTRIBUTE_TYPE_STRING` or `GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32` and then the c) attribute value, either a character string, or 32-bit unsigned int. The list should be terminated with a NULL.

A `GList` of GnomeKeyringFound structures is returned in `found`. The list may have zero items if nothing matched the criteria. The list should be freed using `gnome_keyring_found_list_free()`.

The user may have been prompted to unlock necessary keyrings, and user will have been prompted for access to the items if needed.

For an asynchronous version of this function see `gnome_keyring_find_items()`.

`type` :

  The type of items to find.

`found` :

  The location to return a list of GnomeKeyringFound pointers.

`...` :

Returns :

  `GNOME_KEYRING_RESULT_OK` if the operation was succcessful or an error result otherwise.