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


[ < ] [ > ]   [ << ] [ 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: 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.


[ < ] [ > ]   [ << ] [ 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 December, 7 2007 using texi2html 1.78.