## GckModule

GckModule — A loaded and initialized PKCS#11 module.

## Synopsis

    struct              GckModule;
    GckModule *         gck_module_initialize               (const gchar *path,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gck_module_initialize_async         (const gchar *path,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GckModule *         gck_module_initialize_finish        (GAsyncResult *result,
                                                             GError **error);
    GckModule *         gck_module_new                      (CK_FUNCTION_LIST_PTR funcs);
    gboolean            gck_module_equal                    (gconstpointer module1,
                                                             gconstpointer module2);
    guint               gck_module_hash                     (gconstpointer module);
    gboolean            gck_module_match                    (GckModule *self,
                                                             GckUriData *uri);
    const gchar *       gck_module_get_path                 (GckModule *self);
    CK_FUNCTION_LIST_PTR gck_module_get_functions           (GckModule *self);
    GckModuleInfo *     gck_module_get_info                 (GckModule *self);
    GList *             gck_module_get_slots                (GckModule *self,
                                                             gboolean token_present);
    struct              GckModuleInfo;
    GckModuleInfo *     gck_module_info_copy                (GckModuleInfo *module_info);
    void                gck_module_info_free                (GckModuleInfo *module_info);

## Object Hierarchy

      GObject
       +----GckModule

      GBoxed
       +----GckModuleInfo

## Properties

      "functions"                gpointer              : Read / Write / Construct Only
      "path"                     gchar*                : Read / Write / Construct Only

## Signals

      "authenticate-object"                            : Run Last
      "authenticate-slot"                              : Run Last

## Description

A GckModule object holds a loaded PKCS#11 module. A PKCS#11 module is a shared library.

You can load and initialize a PKCS#11 module with the `gck_module_initialize()` call. If you already have a loaded and initialized module that you'd like to use with the various gck functions, then you can use `gck_module_new()`.

## Details

### struct GckModule

    struct GckModule;

Holds a loaded and initialized PKCS#11 module.

### gck_module_initialize ()

    GckModule *         gck_module_initialize               (const gchar *path,
                                                             GCancellable *cancellable,
                                                             GError **error);

Load and initialize a PKCS#11 module represented by a GckModule object.

`path` : | The file system path to the PKCS#11 module to load.
`cancellable` : | optional cancellation object. [allow-none]
`error` : | A location to store an error resulting from a failed load.
Returns : | The loaded PKCS#11 module or `NULL` if failed. [transfer full]

### gck_module_initialize_async ()

    void                gck_module_initialize_async         (const gchar *path,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously load and initialize a PKCS#11 module represented by a GckModule object.

`path` : | the file system path to the PKCS#11 module to load
`cancellable` : | optional cancellation object. [allow-none]
`callback` : | a callback which will be called when the operation completes
`user_data` : | data to pass to the callback

### gck_module_initialize_finish ()

    GckModule *         gck_module_initialize_finish        (GAsyncResult *result,
                                                             GError **error);

Finishes the asynchronous initialize operation.

`result` : | the asynchronous result
`error` : | location to place an error on failure
Returns : | The initialized module, or NULL. [transfer full][allow-none]

### gck_module_new ()

    GckModule *         gck_module_new                      (CK_FUNCTION_LIST_PTR funcs);

Create a GckModule representing a PKCS#11 module. It is assumed that this the module is already initialized. In addition it will not be finalized when complete.

`funcs` : | Initialized PKCS#11 function list pointer
Returns : | The new PKCS#11 module.

### gck_module_equal ()

    gboolean            gck_module_equal                    (gconstpointer module1,
                                                             gconstpointer module2);

Checks equality of two modules. Two GckModule objects can point to the same underlying PKCS#11 module.

`module1` : | a pointer to the first GckModule. [type Gck.Module]
`module2` : | a pointer to the second GckModule. [type Gck.Module]
Returns : | TRUE if module1 and module2 are equal. FALSE if either is not a GckModule.

### gck_module_hash ()

    guint               gck_module_hash                     (gconstpointer module);

Create a hash value for the GckModule.

This function is intended for easily hashing a GckModule to add to a GHashTable or similar data structure.

`module` : | a pointer to a GckModule. [type Gck.Module]
Returns : | An integer that can be used as a hash value, or 0 if invalid.

### gck_module_match ()

    gboolean            gck_module_match                    (GckModule *self,
                                                             GckUriData *uri);

Check whether the PKCS#11 URI matches the module

`self` : | the module to match
`uri` : | the uri to match against the module
Returns : | whether the URI matches or not

### gck_module_get_path ()

    const gchar *       gck_module_get_path                 (GckModule *self);

Get the file path of this module. This may not be an absolute path, and usually reflects the path passed to `gck_module_initialize()`.

`self` : | The module for which to get the path.
Returns : | The path, do not modify or free this value.

### gck_module_get_functions ()

    CK_FUNCTION_LIST_PTR gck_module_get_functions           (GckModule *self);

Get the PKCS#11 function list for the module.

`self` : | The module for which to get the function list.
Returns : | The function list, do not modify this structure.

### gck_module_get_info ()

    GckModuleInfo *     gck_module_get_info                 (GckModule *self);

Get the info about a PKCS#11 module.

`self` : | The module to get info for.
Returns : | the module info; release this with `gck_module_info_free()`. [transfer full]

### gck_module_get_slots ()

    GList *             gck_module_get_slots                (GckModule *self,
                                                             gboolean token_present);

Get the GckSlot objects for a given module.

`self` : | The module for which to get the slots.
`token_present` : | Whether to limit only to slots with a token present.
Returns : | The possibly empty list of slots. Release this with `gck_list_unref_free()`. [element-type Gck.Slot][transfer full]

### struct GckModuleInfo

    struct GckModuleInfo {
    	guint8 pkcs11_version_major;
    	guint8 pkcs11_version_minor;

    	gchar *manufacturer_id;
    	gulong flags;

    	gchar *library_description;
    	guint8 library_version_major;
    	guint8 library_version_minor;
    };

Holds information about the PKCS#11 module.

This structure corresponds to CK_MODULE_INFO in the PKCS#11 standard. The strings are NULL terminated for easier use.

Use `gck_module_info_free()` to release this structure when done with it.

guint8 `pkcs11_version_major`; | The major version of the module.
guint8 `pkcs11_version_minor`; | The minor version of the module.
gchar *`manufacturer_id`; | The module manufacturer.
gulong `flags`; | The module PKCS#11 flags.
gchar *`library_description`; | The module description.
guint8 `library_version_major`; | The major version of the library.
guint8 `library_version_minor`; | The minor version of the library.

### gck_module_info_copy ()

    GckModuleInfo *     gck_module_info_copy                (GckModuleInfo *module_info);

Make a copy of the module info.

`module_info` : | a module info
Returns : | a newly allocated copy module info. [transfer full]

### gck_module_info_free ()

    void                gck_module_info_free                (GckModuleInfo *module_info);

Free a GckModuleInfo structure.

`module_info` : | The module info to free, or NULL.

## Property Details

### The `"functions"` property

      "functions"                gpointer              : Read / Write / Construct Only

The raw PKCS#11 function list for the module.

This points to a CK_FUNCTION_LIST structure.

### The `"path"` property

      "path"                     gchar*                : Read / Write / Construct Only

The PKCS#11 module file path.

This may be set to NULL if this object was created from an already initialized module via the `gck_module_new()` function.

Default value: NULL

## Signal Details

### The `"authenticate-object"` signal

    gboolean            user_function                      (GckModule *module,
                                                            GckObject *object,
                                                            gchar     *label,
                                                            gpointer   password,
                                                            gpointer   user_data)      : Run Last

### Warning

`GckModule::authenticate-object` is deprecated and should not be used in newly-written code. Since 3.4

Use `gck_slot_set_interaction()` instead of connecting to this signal.

`module` : | The module.
`object` : | The object to be authenticated.
`label` : | A displayable label which describes the object.
`password` : | A gchar** where a password should be returned.
`user_data` : | user data set when the signal handler was connected.

### The `"authenticate-slot"` signal

    gboolean            user_function                      (GckModule *module,
                                                            GckSlot   *slot,
                                                            gchar     *string,
                                                            gpointer   password,
                                                            gpointer   user_data)      : Run Last

### Warning

`GckModule::authenticate-slot` is deprecated and should not be used in newly-written code. Since 3.4

Use `gck_slot_set_interaction()` instead of connecting to this signal.

`module` : | The module
`slot` : | The slot to be authenticated.
`string` : | A displayable label which describes the object.
`password` : | A gchar** where a password should be returned.
`user_data` : | user data set when the signal handler was connected.