Deprecated

## Deprecated Deprecated — Deprecated functions |

## Synopsis

    CK_RV               p11_kit_initialize_registered       (void);
    CK_RV               p11_kit_finalize_registered         (void);
    CK_FUNCTION_LIST_PTR * p11_kit_registered_modules       (void);
    char *              p11_kit_registered_module_to_name   (CK_FUNCTION_LIST_PTR module);
    CK_FUNCTION_LIST_PTR p11_kit_registered_name_to_module  (const char *name);
    char *              p11_kit_registered_option           (CK_FUNCTION_LIST_PTR module,
                                                             const char *field);
    CK_RV               p11_kit_initialize_module           (CK_FUNCTION_LIST_PTR module);
    CK_RV               p11_kit_load_initialize_module      (const char *module_path,
                                                             CK_FUNCTION_LIST_PTR *module);
    CK_RV               p11_kit_finalize_module             (CK_FUNCTION_LIST_PTR module);
    #define             P11_KIT_DEPRECATED_FOR              (f)

## Description

These functions have been deprecated from p11-kit and are not recommended for general usage. In large part they were deprecated because they did not adequately insulate multiple callers of a PKCS#11 module from another, and could not support the 'managed' mode needed to do this.

## Details

### p11_kit_initialize_registered ()

    CK_RV               p11_kit_initialize_registered       (void);

### Warning

`p11_kit_initialize_registered` is deprecated and should not be used in newly-written code. Since: 0.19.0: Use `p11_kit_modules_load()` instead.

Initialize all the registered PKCS#11 modules.

If this is the first time this function is called multiple times consecutively within a single process, then it merely increments an initialization reference count for each of these modules.

Use `p11_kit_finalize_registered()` to finalize these registered modules once the caller is done with them.

If this function fails, then an error message will be available via the `p11_kit_message()` function.

Returns : | CKR_OK if the initialization succeeded, or an error code.

### p11_kit_finalize_registered ()

    CK_RV               p11_kit_finalize_registered         (void);

### Warning

`p11_kit_finalize_registered` is deprecated and should not be used in newly-written code. Since 0.19.0: Use `p11_kit_modules_release()` instead.

Finalize all the registered PKCS#11 modules. These should have been initialized with `p11_kit_initialize_registered()`.

If `p11_kit_initialize_registered()` has been called more than once in this process, then this function must be called the same number of times before actual finalization will occur.

If this function fails, then an error message will be available via the `p11_kit_message()` function.

Returns : | CKR_OK if the finalization succeeded, or an error code.

### p11_kit_registered_modules ()

    CK_FUNCTION_LIST_PTR * p11_kit_registered_modules       (void);

### Warning

`p11_kit_registered_modules` is deprecated and should not be used in newly-written code. Since 0.19.0: Use `p11_kit_modules_load()` instead.

Get a list of all the registered PKCS#11 modules. This list will be valid once the `p11_kit_initialize_registered()` function has been called.

The returned value is a `NULL` terminated array of `CK_FUNCTION_LIST_PTR` pointers.

The returned modules are unmanaged.

Returns : | A list of all the registered modules. Use the `free()` function to free the list.

### p11_kit_registered_module_to_name ()

    char *              p11_kit_registered_module_to_name   (CK_FUNCTION_LIST_PTR module);

### Warning

`p11_kit_registered_module_to_name` is deprecated and should not be used in newly-written code. Since 0.19.0: Use `p11_kit_module_get_name()` instead.

Get the name of a registered PKCS#11 module.

You can use `p11_kit_registered_modules()` to get a list of all the registered modules. This name is specified by the registered module configuration.

`module` : | pointer to a registered module
Returns : | A newly allocated string containing the module name, or `NULL` if no such registered module exists. Use `free()` to free this string.

### p11_kit_registered_name_to_module ()

    CK_FUNCTION_LIST_PTR p11_kit_registered_name_to_module  (const char *name);

### Warning

`p11_kit_registered_name_to_module` is deprecated and should not be used in newly-written code. Since 0.19.0: Use `p11_kit_module_for_name()` instead.

Lookup a registered PKCS#11 module by its name. This name is specified by the registered module configuration.

`name` : | name of a registered module
Returns : | a pointer to a PKCS#11 module, or `NULL` if this name was not found.

### p11_kit_registered_option ()

    char *              p11_kit_registered_option           (CK_FUNCTION_LIST_PTR module,
                                                             const char *field);

### Warning

`p11_kit_registered_option` is deprecated and should not be used in newly-written code. Since 0.19.0: Use `p11_kit_config_option()` instead.

Lookup a configured option for a registered PKCS#11 module. If a `NULL` module argument is specified, then this will lookup the configuration option in the global config file.

`module` : | a pointer to a registered module
`field` : | the name of the option to lookup.
Returns : | A newly allocated string containing the option value, or `NULL` if the registered module or the option were not found. Use `free()` to free the returned string.

### p11_kit_initialize_module ()

    CK_RV               p11_kit_initialize_module           (CK_FUNCTION_LIST_PTR module);

### Warning

`p11_kit_initialize_module` is deprecated and should not be used in newly-written code. Since 0.19.0: Use `p11_kit_module_initialize()` instead.

Initialize an arbitrary PKCS#11 module. Normally using the `p11_kit_initialize_registered()` is preferred.

Using this function to initialize modules allows coordination between multiple users of the same module in a single process. It should be called on modules that have been loaded (with `dlopen()` for example) but not yet initialized. The caller should not yet have called the module's `C_Initialize` method. This function will call `C_Initialize` as necessary.

Subsequent calls to this function for the same module will result in an initialization count being incremented for the module. It is safe (although usually unnecessary) to use this function on registered modules.

The module must be finalized with `p11_kit_finalize_module()` instead of calling its `C_Finalize` method directly.

This function does not accept a `CK_C_INITIALIZE_ARGS` argument. Custom initialization arguments cannot be supported when multiple consumers load the same module.

If this function fails, then an error message will be available via the `p11_kit_message()` function.

`module` : | loaded module to initialize.
Returns : | CKR_OK if the initialization was successful.

### p11_kit_load_initialize_module ()

    CK_RV               p11_kit_load_initialize_module      (const char *module_path,
                                                             CK_FUNCTION_LIST_PTR *module);

### Warning

`p11_kit_load_initialize_module` is deprecated and should not be used in newly-written code. Since 0.19.0: Use `p11_kit_module_load()` instead.

Load an arbitrary PKCS#11 module from a dynamic library file, and initialize it. Normally using the `p11_kit_initialize_registered()` function is preferred.

Using this function to load and initialize modules allows coordination between multiple users of the same module in a single process. The caller should not call the module's `C_Initialize` method. This function will call `C_Initialize` as necessary.

If a module has already been loaded, then use of this function is unnecesasry. Instead use the `p11_kit_initialize_module()` function to initialize it.

Subsequent calls to this function for the same module will result in an initialization count being incremented for the module. It is safe (although usually unnecessary) to use this function on registered modules.

The module must be finalized with `p11_kit_finalize_module()` instead of calling its `C_Finalize` method directly.

This function does not accept a `CK_C_INITIALIZE_ARGS` argument. Custom initialization arguments cannot be supported when multiple consumers load the same module.

If this function fails, then an error message will be available via the `p11_kit_message()` function.

`module_path` : | full file path of module library
`module` : | location to place loaded module pointer
Returns : | CKR_OK if the initialization was successful.

### p11_kit_finalize_module ()

    CK_RV               p11_kit_finalize_module             (CK_FUNCTION_LIST_PTR module);

### Warning

`p11_kit_finalize_module` is deprecated and should not be used in newly-written code. Since 0.19.0: Use `p11_kit_module_finalize()` and `p11_kit_module_release()` instead.

Finalize an arbitrary PKCS#11 module. The module must have been initialized using `p11_kit_initialize_module()`. In most cases callers will want to use `p11_kit_finalize_registered()` instead of this function.

Using this function to finalize modules allows coordination between multiple users of the same module in a single process. The caller should not call the module's `C_Finalize` method. This function will call `C_Finalize` as necessary.

If the module was initialized more than once, then this function will decrement an initialization count for the module. When the count reaches zero the module will be truly finalized. It is safe (although usually unnecessary) to use this function on registered modules if (and only if) they were initialized using `p11_kit_initialize_module()` for some reason.

If this function fails, then an error message will be available via the `p11_kit_message()` function.

`module` : | loaded module to finalize.
Returns : | CKR_OK if the finalization was successful.

### P11_KIT_DEPRECATED_FOR()

    #define P11_KIT_DEPRECATED_FOR(f) __attribute__((deprecated("Use " #f " instead")))