5.2 Initializing the library

Libassuan makes use of Libgpg-error and assumes that Libgpg-error has been initialized. In general gpgrt_check_version should be called to guarantee this; the Libgpg-error manual for details.

Libassuan itself requires no initialization. There are however some initialization hooks provided which are often useful. These should be called as early as possible and in a multi-threaded application before a second thread is created.

These functions initialize default values that are used at context creation with assuan_new. As there can only be one default, all values can also be set directly with assuan_new_ext or with context-specific functions after context creation.

If your application uses its own memory allocation functions or wrappers it is good idea to tell libassuan about it so it can make use of the same functions or wrappers:

Data type: struct assuan_malloc_hooks

This structure is used to store the memory allocation callback interface functions. It has the following members, whose semantics are identical to the corresponding system functions:

void *(*malloc) (size_t cnt)

This is the function called by ASSUAN to allocate memory for a context.

void *(*realloc) (void *ptr, size_t cnt)

This is the function called by ASSUAN to reallocate memory for a context.

void (*free) (void *ptr)

This is the function called by ASSUAN to release memory for a context.

Data type: assuan_malloc_hooks_t

This is a pointer to a struct assuan_malloc_hooks.

Function: void assuan_set_malloc_hooks (assuan_malloc_hooks_t malloc_hooks)

This function sets the default allocation hooks for new contexts allocated with assuan_new. You need to provide all three functions. Those functions need to behave exactly as their standard counterparts malloc, realloc and free. If you write your own functions, please take care to set errno whenever an error has occurred.

Function: assuan_malloc_hooks_t assuan_get_malloc_hooks ()

This function gets the default allocation hooks for new contexts allocated with assuan_new. The result structure is statically allocated and should not be modified.

The ASSUAN library uses libgpg-error error values, which consist and error code and an error source. The default source used by contexts allocated with assuan_new can be set with the following function.

Function: void assuan_set_gpg_err_source (gpg_err_source_t err_source)

This function sets the default error source for errors generated by contexts allocated with assuan_new.

One way to call this function is

assuan_set_gpg_err_source (GPG_ERR_SOURCE_DEFAULT);

Function: gpg_err_source_t assuan_get_gpg_err_source (void)

This function gets the default error source for errors generated by contexts allocated with assuan_new.

To integrate assuan logging and diagnostics into your own logging system, you may use the following two functions:

Data type: int (*assuan_log_cb_t) (assuan_context_t ctx, void *hook_value, unsigned int cat, const char *msg)

The user-provided callback function takes a context ctx, for which the message msg was generated, and a hook value hook_value that was supplied when the log handler was registered for the context with assuan_set_log_cb, and a category cat. The category is one of:

ASSUAN_LOG_INIT

ASSUAN_LOG_CTX

ASSUAN_LOG_ENGINE

ASSUAN_LOG_DATA

RFU

ASSUAN_LOG_SYSIO

Log lowlevel I/O data.

ASSUAN_LOG_CONTROL

Log the control channel.

The user may then, depending on the category, write the message to a log file or treat it in some other way.

If msg is a null pointer, then no message should be logged, but the function should return 1 if it is interested in log messages with the category cat. If it is not interested, 0 should be returned. This allows libassuan to suppress the generation of expensive debug output.

Function: void assuan_set_log_cb (assuan_log_cb_t log_cb, void *log_cb_data)

This function sets the default logging handler for log messages generated by contexts allocated with assuan_new.

Function: void assuan_get_log_cb (assuan_log_cb_t *log_cb, void **log_cb_data)

This function gets the default logging handler for log messages generated by contexts allocated with assuan_new.

You do not need to set a log handler, as ASSUAN provides a configurable default log handler that should be suitable for most purposes. Logging can be disabled completely by setting the log handler to a null pointer.