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_t assuan_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

gpg_error_t err;
assuan_log_cb_t log_cb;
void *log_cb_data;

assuan_get_log_cb (&log_cb, &log_cb_data);
err = assuan_new_ext (ctx_p, assuan_get_gpg_err_source (),
                      assuan_get_malloc_hooks (), log_cb, log_cb_data);

As you can see, this is not thread-safe. Take care not to modify the memory allocation hooks or log callback handler concurrently with assuan_new.

The function returns an error if a memory allocation error occurs, and 0 with the new context in ctx_p otherwise.

Function: gpg_error_t assuan_new_ext (assuan_context_t *ctx_p, gpg_err_source_t err_source, assuan_malloc_hooks_t malloc_hooks, assuan_log_cb_t log_cb, void *log_cb_data)

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: void assuan_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: void assuan_set_pointer (assuan_context_t ctx, 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_t ctx)

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:

static int
cmd_foo (assuan_context_t ctx, char *line)
{
  ctrl_t ctrl = assuan_get_pointer (ctx);
  ...
}

Function: void assuan_set_flag (assuan_context_t ctx, assuan_flag_t flag, int value)

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: int assuan_get_flag (assuan_context_t ctx, assuan_flag_t flag)

Return the value of flag in context ctx.

Function: void assuan_begin_confidential (assuan_context_t ctx)

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: void assuan_end_confidential (assuan_context_t ctx)

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.

void (*usleep) (assuan_context_t ctx, unsigned int usec)

This is the function called by ASSUAN to sleep for USEC microseconds.

int (*pipe) (assuan_context_t ctx, assuan_fd_t fd[2], int inherit_idx)

This is the function called by ASSUAN to create a pipe. The returned file descriptor fd[inherit_idx] must be inheritable by the child process (under Windows, this requires some extra work).

int (*close) (assuan_context_t ctx, assuan_fd_t fd)

This is the function called by ASSUAN to close a file descriptor created through the system functions.

ssize_t (*read) (assuan_context_t ctx, assuan_fd_t fd, void *buffer, size_t size)

This is the function called by ASSUAN to read data from a file descriptor. It is functionally equivalent to the system read function.

ssize_t (*write) (assuan_context_t ctx, assuan_fd_t fd, const void *buffer, size_t size)

This is the function called by ASSUAN to write data to a file descriptor. It is functionally equivalent to the system write function.

int (*recvmsg) (assuan_context_t ctx, assuan_fd_t fd, assuan_msghdr_t msg, int flags)

This is the function called by ASSUAN to receive a message from a file descriptor. It is functionally equivalent to the system recvmsg function.

int (*sendmsg) (assuan_context_t ctx, assuan_fd_t fd, const assuan_msghdr_t msg, int flags);

This is the function called by ASSUAN to send a message to a file descriptor. It is functionally equivalent to the system sendmsg function.

int (*spawn) (assuan_context_t ctx, pid_t *r_pid, const char *name, const char **argv, assuan_fd_t fd_in, assuan_fd_t fd_out, assuan_fd_t *fd_child_list, void (*atfork) (void *opaque, int reserved), void *atforkvalue, unsigned int flags)

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.

pid_t (*waitpid) (assuan_context_t ctx, pid_t pid, int action, int *status, int options)

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.

int (*socketpair) (assuan_context_t ctx, int namespace, int style, int protocol, assuan_fd_t filedes[2])

This is the function called by ASSUAN to create a socketpair. It is equivalent to socketpair.

Function: void assuan_set_system_hooks (assuan_system_hooks_t system_hooks)

Set the default system hooks to use. There is currently no way to reset to the default system hooks.

Function: void assuan_sock_set_system_hooks (assuan_system_hooks_t system_hooks)

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.

Function: void assuan_ctx_set_system_hooks (assuan_context_t ctx, assuan_system_hooks_t system_hooks)

Set the system hooks for context ctx. There is currently no way to reset to the default system hooks, create a new context for that.

The following system hook collections are defined by the library for your convenience:

ASSUAN_SYSTEM_NPTH

System hooks suitable for use with the nPth library.

ASSUAN_SYSTEM_NPTH_IMPL

The implementation of system hooks for use with the nPth library. This must be invoked once somewhere in the application, and defines the structure that is referenced by ASSUAN_SYSTEM_NPTH.

ASSUAN_SYSTEM_PTH

System hooks suitable for use with the GNU Pth library.

ASSUAN_SYSTEM_PTH_IMPL

The implementation of system hooks for use with the GNU Pth library. This must be invoked once somewhere in the application, and defines the structure that is referenced by ASSUAN_SYSTEM_PTH.