4. Handler Functions

Libgcrypt makes it possible to install so called `handler functions', which get called by Libgcrypt in case of certain events.

4.1 Progress handler

It is often useful to retrieve some feedback while long running operations are performed.

Data type: gcry_handler_progress_t

Progress handler functions have to be of the type gcry_handler_progress_t, which is defined as:

void (*gcry_handler_progress_t) (void *, const char *, int, int, int)

The following function may be used to register a handler function for this purpose.

Function: void gcry_set_progress_handler (gcry_handler_progress_t cb, void *cb_data)

This function installs cb as the `Progress handler' function. cb must be defined as follows:

void my_progress_handler (void *cb_data, const char *what, int printchar, int current, int total) { /* Do something. */ }

A description of the arguments of the progress handler function follows.

cb_data

The argument provided in the call to gcry_set_progress_handler.

what

A string identifying the type of the progress output. The following values for what are defined:

need_entropy

Not enough entropy is available. total holds the number of required bytes.

primegen

Values for printchar:

\n

Prime generated.

!

Need to refresh the pool of prime numbers.

<, >

Number of bits adjusted.

^

Searching for a generator.

.

Fermat test on 10 candidates failed.

:

Restart with a new random value.

+

Rabin Miller test passed.

4.2 Allocation handler

It is possible to make Libgcrypt use special memory allocation functions instead of the built-in ones.

Memory allocation functions are of the following types:

Data type: gcry_handler_alloc_t

This type is defined as: void *(*gcry_handler_alloc_t) (size_t n).

Data type: gcry_handler_secure_check_t

This type is defined as: int *(*gcry_handler_secure_check_t) (const void *).

Data type: gcry_handler_realloc_t

This type is defined as: void *(*gcry_handler_realloc_t) (void *p, size_t n).

Data type: gcry_handler_free_t

This type is defined as: void *(*gcry_handler_free_t) (void *).

Special memory allocation functions can be installed with the following function:

Function: void gcry_set_allocation_handler (gcry_handler_alloc_t func_alloc, gcry_handler_alloc_t func_alloc_secure, gcry_handler_secure_check_t func_secure_check, gcry_handler_realloc_t func_realloc, gcry_handler_free_t func_free)

Install the provided functions and use them instead of the built-in functions for doing memory allocation.

4.3 Error handler

The following functions may be used to register handler functions that are called by Libgcrypt in case certain error conditions occur.

Data type: gcry_handler_no_mem_t

This type is defined as: void (*gcry_handler_no_mem_t) (void *, size_t, unsigned int)

Function: void gcry_set_outofcore_handler (gcry_handler_no_mem_t func_no_mem, void *cb_data)

This function registers func_no_mem as `out-of-core handler', which means that it will be called in the case of not having enough memory available.

Data type: gcry_handler_error_t

This type is defined as: void (*gcry_handler_error_t) (void *, int, const char *)

Function: void gcry_set_fatalerror_handler (gcry_handler_error_t func_error, void *cb_data)

This function registers func_error as `error handler', which means that it will be called in error conditions.

4.4 Logging handler

Data type: gcry_handler_log_t

This type is defined as: void (*gcry_handler_log_t) (void *, int, const char *, va_list)

Function: void gcry_set_log_handler (gcry_handler_log_t func_log, void *cb_data)

This function registers func_log as `logging handler', which means that it will be called in case Libgcrypt wants to log a message.