GckModule lists

## GckModule lists GckModule lists — Dealing with lists of PKCS#11 modules. |

## Synopsis

    GList *             gck_modules_initialize_registered   (GCancellable *cancellable,
                                                             GError **error);
    void                gck_modules_initialize_registered_async
                                                            (GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GList *             gck_modules_initialize_registered_finish
                                                            (GAsyncResult *result,
                                                             GError **error);
    GckEnumerator *     gck_modules_enumerate_objects       (GList *modules,
                                                             GckAttributes *attrs,
                                                             GckSessionOptions session_options);
    GckEnumerator *     gck_modules_enumerate_uri           (GList *modules,
                                                             const gchar *uri,
                                                             GckSessionOptions session_options,
                                                             GError **error);
    GList *             gck_modules_get_slots               (GList *modules,
                                                             gboolean token_present);
    GckObject *         gck_modules_object_for_uri          (GList *modules,
                                                             const gchar *uri,
                                                             GckSessionOptions session_options,
                                                             GError **error);
    GList *             gck_modules_objects_for_uri         (GList *modules,
                                                             const gchar *uri,
                                                             GckSessionOptions session_options,
                                                             GError **error);
    GckSlot *           gck_modules_token_for_uri           (GList *modules,
                                                             const gchar *uri,
                                                             GError **error);
    GList *             gck_modules_tokens_for_uri          (GList *modules,
                                                             const gchar *uri,
                                                             GError **error);

## Description

These functions are useful for dealing with lists of modules, and performing operations on all of them.

## Details

### gck_modules_initialize_registered ()

    GList *             gck_modules_initialize_registered   (GCancellable *cancellable,
                                                             GError **error);

Load and initialize all the registered modules.

`cancellable` : | optional cancellation object. [allow-none]
`error` : | location to place an error on failure. [allow-none]
Returns : | A newly allocated list of GckModule objects, which should be released with `gck_list_unref_free()`. [transfer full][element-type Gck.Module]

### gck_modules_initialize_registered_async ()

    void                gck_modules_initialize_registered_async
                                                            (GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Load and initialize all the registered modules asynchronously.

`cancellable` : | optional cancellation object
`callback` : | a callback which will be called when the operation completes
`user_data` : | data to pass to the callback

### gck_modules_initialize_registered_finish ()

    GList *             gck_modules_initialize_registered_finish
                                                            (GAsyncResult *result,
                                                             GError **error);

Finishes the asynchronous operation to initialize the registered PKCS#11 modules.

`result` : | the asynchronous result
`error` : | location to place an error on failure
Returns : | a list of newly initialized GckModule objects. [transfer full][element-type Gck.Module]

### gck_modules_enumerate_objects ()

    GckEnumerator *     gck_modules_enumerate_objects       (GList *modules,
                                                             GckAttributes *attrs,
                                                             GckSessionOptions session_options);

Setup an enumerator for listing matching objects on the modules.

This call will not block but will return an enumerator immediately.

If the `attrs` GckAttributes is floating, it is consumed.

`modules` : | The modules. [element-type Gck.Module]
`attrs` : | attributes that the objects must have, or empty for all objects
`session_options` : | Options from GckSessionOptions
Returns : | A new enumerator, which should be released with `g_object_unref()`. [transfer full]

### gck_modules_enumerate_uri ()

    GckEnumerator *     gck_modules_enumerate_uri           (GList *modules,
                                                             const gchar *uri,
                                                             GckSessionOptions session_options,
                                                             GError **error);

Enumerate objects that match a URI.

This call will not block. Use the GckEnumerator functions in order to get at the actual objects that match.

`modules` : | The modules. [element-type Gck.Module]
`uri` : | The URI that the enumerator will match
`session_options` : | Options from GckSessionOptions
`error` : | A location to raise an error on failure.
Returns : | A new GckEnumerator, or `NULL` if an error occurs. [transfer full]

### gck_modules_get_slots ()

    GList *             gck_modules_get_slots               (GList *modules,
                                                             gboolean token_present);

Get a list of slots for across all of the modules.

`modules` : | The modules. [element-type Gck.Module]
`token_present` : | Whether to only list slots with token present
Returns : | A list of GckSlot objects, which should be freed with `gck_list_unref_free()`. [transfer full][element-type Gck.Slot]

### gck_modules_object_for_uri ()

    GckObject *         gck_modules_object_for_uri          (GList *modules,
                                                             const gchar *uri,
                                                             GckSessionOptions session_options,
                                                             GError **error);

Find an object that matches a URI.

This call can block. Use `gck_modules_enumerate_uri()` for a non-blocking version.

`modules` : | The modules. [element-type Gck.Module]
`uri` : | The URI the objects must match
`session_options` : | Options from GckSessionOptions
`error` : | A location to raise an error on failure.
Returns : | A new GckObject which should be released with `g_object_unref()`, or `NULL` if no matching object was found. [transfer full][allow-none]

### gck_modules_objects_for_uri ()

    GList *             gck_modules_objects_for_uri         (GList *modules,
                                                             const gchar *uri,
                                                             GckSessionOptions session_options,
                                                             GError **error);

Find objects that match a URI.

This call can block. Use `gck_modules_enumerate_uri()` for a non-blocking version.

`modules` : | The modules. [element-type Gck.Module]
`uri` : | The URI the objects must match
`session_options` : | Options from GckSessionOptions
`error` : | A location to raise an error on failure.
Returns : | A list of GckObject which should be released with `gck_list_unref_free()`, or `NULL` if no matching object was found. [transfer full][element-type Gck.Object]

### gck_modules_token_for_uri ()

    GckSlot *           gck_modules_token_for_uri           (GList *modules,
                                                             const gchar *uri,
                                                             GError **error);

Lookup a token that matches the URI.

`modules` : | The modules. [element-type Gck.Module]
`uri` : | The URI that the token must match
`error` : | A location to raise an error on failure
Returns : | A newly allocated GckSlot or `NULL` if no such token was found. [transfer full]

### gck_modules_tokens_for_uri ()

    GList *             gck_modules_tokens_for_uri          (GList *modules,
                                                             const gchar *uri,
                                                             GError **error);

Lookup a token that matches the URI.

`modules` : | The modules. [element-type Gck.Module]
`uri` : | The URI that the token must match
`error` : | A location to raise an error on failure
Returns : | A list of newly allocated GckSlot objects. Use `gck_list_unref_free()` to release the list once you're done with it. [transfer full][element-type Gck.Slot]