Next: Reading and Writing, Previous: Default Log Handler, Up: Generalities [Contents][Index]
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.
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.
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.
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:
Store the arbitrary pointer value pointer into the context ctx. This is useful to provide command handlers with additional application context.
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); ... }
Set the the flag for context ctx to value. Values for flags are usually 1 or 0 but certain flags might need other values.
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.
Return the value of flag in context 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);
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);
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
.
Set the default system hooks to use. There is currently no way to reset to the default 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.
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
.
Next: Reading and Writing, Previous: Default Log Handler, Up: Generalities [Contents][Index]