## GckModule lists

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

## Functions

GList * | gck_modules_initialize_registered ()
void | gck_modules_initialize_registered_async ()
GList * | gck_modules_initialize_registered_finish ()
GckEnumerator * | gck_modules_enumerate_objects ()
GckEnumerator * | gck_modules_enumerate_uri ()
GList * | gck_modules_get_slots ()
GckObject * | gck_modules_object_for_uri ()
GList * | gck_modules_objects_for_uri ()
GckSlot * | gck_modules_token_for_uri ()
GList * | gck_modules_tokens_for_uri ()

## Description

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

## Functions

### gck_modules_initialize_registered ()

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

Load and initialize all the registered modules.

#### Parameters

cancellable | optional cancellation object. | [nullable]
error | location to place an error on failure. | [out][optional]

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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][nullable]

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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]