[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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  Using a progress handler function.
4.2 Allocation handler  Using special memory allocation functions.
4.3 Error handler  Using error handler functions.
4.4 Logging handler  Using a special logging function.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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: void *(*gcry_handler_secure_check_t) (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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by root on April, 16 2004 using texi2html