5.4 How to work with contexts

Some operations work globally on the library, but most operate in a
context, which saves state across operations. To allow the use of
libassuan in mixed environments, such as in a library using
GPGME and an application using GPGME, the context is very extensive
and covers utilitary information like memory allocation callbacks as
well as specific information associated with client/server operations.

Function: gpg_error_tassuan_new(assuan_context_t *ctx_p)

The function assuan_new creates a new context, using the global
default memory allocation, log handler and libgpg-error source.
It is equivalent to

The function assuan_new_ext creates a new context using the
supplied libgpg-error error source err_source, the memory
allocation hooks malloc_hooks and the log handler log_cb
with the user data log_cb_data.

After the context has been used, it can be destroyed again.

Function: voidassuan_release(assuan_context_t ctx)

The function assuan_release destroys the context CTX and
releases all associated resources.

Other properties of the context beside the memory allocation handler,
the log handler, and the libgpg-error source can be set after
context creation. Here are some of them:

Function: voidassuan_set_pointer(assuan_context_tctx, void *pointer)

Store the arbitrary pointer value pointer into the context
ctx. This is useful to provide command handlers with additional
application context.

Function: void*assuan_get_pointer(assuan_context_tctx)

This returns the pointer for context ctx which has been set using
the above function. A common way to use it is by setting the pointer
before starting the processing loop and to retrieve it right at the
start of a command handler:

Set the the flag for context ctx to value. Values for
flags are usually 1 or 0 but certain flags might need other values.

Data type: assuan_flag_t

The flags are all named and collected in an enum for better readability.
Available flags are:

ASSUAN_NO_WAITPID

When using a pipe server, by default Libassuan will wait for the forked
process to die in assuan_release. In certain cases this is
not desirable. By setting this flag, a call to waitpid will be
suppressed and the caller is responsible to cleanup the child process.

ASSUAN_CONFIDENTIAL

Use to return the state of the confidential logging mode.

ASSUAN_NO_FIXSIGNALS

Do not modify signal handler for SIGPIPE.

ASSUAN_CONVEY_COMMENTS

If enabled comment lines are passed to the status callback of the
assuan_transact.

ASSUAN_FORCE_CLOSE

Setting this flag forces the next command to assume that the
connection has been closed. This breaks the command processing loop
and may be used as an implicit BYE command. value is ignored
and thus it is not possible to clear this flag.

Function: intassuan_get_flag(assuan_context_tctx, assuan_flag_tflag)

Return the value of flag in context ctx.

Function: voidassuan_begin_confidential(assuan_context_tctx)

Put the logging feature into confidential mode. This is to avoid
logging of sensitive data.

This is identical to:

assuan_set_flag (ctx, ASSUAN_CONFIDENTIAL, 1);

Function: voidassuan_end_confidential(assuan_context_tctx)

Get the logging feature out of confidential mode. All data will be
logged again (if logging is enabled).

This is identical to:

assuan_set_flag (ctx, ASSUAN_CONFIDENTIAL, 0);

Data type: struct assuan_system_hooks

This structure is used to store the system callback interface
functions. It has the following members, whose semantics are similar
to the corresponding system functions, but not exactly equivalent.

int version

The user should set this to ASSUAN_SYSTEM_HOOKS_VERSION. This
indicates to the library which members of this structure are present
in case of future extensions. The user should initialize the whole
structure with zero bytes.

This is the function called by ASSUAN to spawn a child process.
The stdin and stdout file descriptors are provided in
fd_in and fd_out respectively, but can be set to
ASSUAN_INVALID_FD, in which case they are set to
/dev/null. On systems which use fork and exec,
the atfork function should be called with atforkvalue
and 0 for flags in the child process right after fork
returns. fd_child_list is a ASSUAN_INVALID_FD
terminated array (or NULL) and specifies file descriptors to be
inherited by the child process.

A special situation occurs if name is a null pointer, in which
case the process should just fork but not call exec. In this
case, *argv should be set to "client" in the parent
process and "server" in the child process.

Flags is the bit-wise OR of some (or none) of the following flags:

ASSUAN_SPAWN_DETACHED

If set and there is a need to start the server it will be started as a
background process. This flag is useful under W32 systems, so that no
new console is created and pops up a console window when starting the
server. On W32CE systems this flag is ignored.

This is the function called by ASSUAN to wait for the spawned
child process pid to exit, or, if action is 1, to just
release all resources associated with pid (required on Windows
platforms). If action is 0, this is equivalent to waitpid.

The socket subsystem uses an internal context which uses the default
system hooks. This function allows to change these system hooks. The
function is not thread-safe and only useful if a certain order of
assuan and assuan socket initializations are required.