## Search Functionality

Search Functionality — Find Keyring Items

## Functions

GnomeKeyringFound * | gnome_keyring_found_copy ()
void | gnome_keyring_found_free ()
void | gnome_keyring_found_list_free ()
gpointer | gnome_keyring_find_items ()
gpointer | gnome_keyring_find_itemsv ()
GnomeKeyringResult | gnome_keyring_find_items_sync ()
GnomeKeyringResult | gnome_keyring_find_itemsv_sync ()

## Types and Values

| GnomeKeyringFound

## Description

All of these APIs are deprecated. Use libsecret instead.

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.

## Functions

### gnome_keyring_found_copy ()

    GnomeKeyringFound *
    gnome_keyring_found_copy (GnomeKeyringFound *found);

`gnome_keyring_found_copy` is deprecated and should not be used in newly-written code.

Not needed when using libsecret.

Copy a GnomeKeyringFound item.

#### Parameters

found | a GnomeKeyringFound |

#### Returns

The new GnomeKeyringFound.

[transfer full]

### gnome_keyring_found_free ()

    void
    gnome_keyring_found_free (GnomeKeyringFound *found);

`gnome_keyring_found_free` is deprecated and should not be used in newly-written code.

Deprecated: Not needed when using libsecret.

Free the memory used by a GnomeKeyringFound item.

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

#### Parameters

found | a GnomeKeyringFound |

### gnome_keyring_found_list_free ()

    void
    gnome_keyring_found_list_free (GList *found_list);

`gnome_keyring_found_list_free` is deprecated and should not be used in newly-written code.

Not needed when using libsecret.

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

#### Parameters

found_list | a GList of GnomeKeyringFound. | [element-type GnomeKeyringFound]

### gnome_keyring_find_items ()

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

`gnome_keyring_find_items` is deprecated and should not be used in newly-written code.

Use `secret_password_lookup()` or `secret_service_search()` instead.

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

#### Parameters

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` . | [allow-none]
destroy_data | A function to free `data` when it's no longer needed. |

#### Returns

The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`.

[transfer none]

### gnome_keyring_find_itemsv ()

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

`gnome_keyring_find_itemsv` is deprecated and should not be used in newly-written code.

Use `secret_password_lookup()` or `secret_service_search()` instead.

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

#### Parameters

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` . | [allow-none]
destroy_data | A function to free `data` when it's no longer needed. |
... | Attribute name, followed by the attribute type, and string or 32-bit unsigned int value. Terminated with `NULL`. |

#### Returns

The asynchronous request, which can be passed to `gnome_keyring_cancel_request()`.

[transfer none]

### gnome_keyring_find_items_sync ()

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

`gnome_keyring_find_items_sync` is deprecated and should not be used in newly-written code.

Use `secret_password_lookup_sync()` or `secret_service_search_sync()` instead.

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

#### Parameters

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. | [out][element-type GnomeKeyringFound]

#### 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,
                                    ...);

`gnome_keyring_find_itemsv_sync` is deprecated and should not be used in newly-written code.

Use `secret_password_lookup_sync()` or `secret_service_search_sync()` instead.

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

#### Parameters

type | The type of items to find. |
found | The location to return a list of GnomeKeyringFound pointers. | [out][element-type GnomeKeyringFound]
... | Attribute name, followed by the attribute type, and string or 32-bit unsigned int value. Terminated with `NULL`. |

#### Returns

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

## Types and Values

### GnomeKeyringFound

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

`GnomeKeyringFound` is deprecated and should not be used in newly-written code.

Not used with libsecret.

A found structure returned by a found operation. Use `gnome_keyring_found_list_free()` to free a list of these structures.

#### Members

char *`keyring`; | The keyring the item was found in. |
guint `item_id`; | The identifier for the item. |
GnomeKeyringAttributeList *`attributes`; | The item's attributes. |
char *`secret`; | The item's secret. |