3.1 Server responses

OK [<arbitrary debugging information>]

Request was successful.

ERR errorcode [<human readable error description>]

Request could not be fulfilled. The possible error codes are defined by libgpg-error.

S keyword <status information depending on keyword>

Informational output by the server, which is still processing the request. A client may not send such lines to the server while processing an Inquiry command. keyword shall start with a letter or an underscore.

# <string>

Comment line issued only for debugging purposes. Totally ignored.

D <raw data>

Raw data returned to client. There must be exactly one space after the ’D’. The values for ’%’, CR and LF must be percent escaped; these are encoded as %25, %0D and %0A, respectively. Only uppercase letters should be used in the hexadecimal representation. Other characters may be percent escaped for easier debugging. All Data lines are considered one data stream up to the OK or ERR response. Status and Inquiry Responses may be mixed with the Data lines.

INQUIRE keyword <parameters>

The server needs further information from the client. The client should respond with data (using the “D” command and terminated by “END”). Alternatively, the client may cancel the current operation by responding with “CAN”.

Consider the following examples (lines prefixed with S indicate text that the server sends; lines prefixed with C indicate text that the client sends):

S: INQUIRE foo
C: D foo bar
C: D bar baz
C: END
[Server continues normal work]

This implements a callback to the client:

S: INQUIRE foo
C: END
[Server continues]

and:

S: INQUIRE foo
C: CAN
[Server terminates the operaion and in most cases returns an ERR to the client.]

But, CAN may also mean “I have no data for you, try to get it from elsewhere.”

Note: lines longer than 1000 bytes should be treated as a communication error. (The rationale for having a line length limit is to allow for easier multiplexing of several channels.)

3.2 Client requests

The server waits for client requests after sending an Okay or Error. The client should not issue a request in other cases.

command <parameters>

command is a one word string without preceding white space. Parameters are command specific, CR, LF and the percent signs should be percent escaped as described above. To send a backslash as the last character it should also be percent escaped. Percent escaping is allowed anywhere in the parameters but not in the command. The line ends with a CR, LF pair or just a LF.

Not yet implemented feature: If there is a need for a parameter list longer than the line length limit (1000 characters including command and CR, LF), the last character of the line (right before the CR/LF or LF) must be a unescaped (i.e., literal) backslash. The following line is then expected to be a continuation of the line with the backslash replaced by a blank and the line ending removed.

D <raw data>

Sends raw data to the server. There must be exactly one space after the ’D’. The values for ’%’, CR and LF must be percent escaped. These are encoded as %25, %0D and %0A, respectively. Only uppercase letters should be used in the hexadecimal representation. Other characters may be percent escaped for easier debugging. All Data lines are considered one data stream up to the OK or ERR response. Status and Inquiry Responses may be mixed with the Data lines.

END

Lines beginning with a # or empty lines are ignored. This is useful to comment test scripts.

Although the commands are application specific, some of them are used by all protocols and partly supported by the Assuan library:

BYE

Close the connection. The server will respond with OK.

RESET

Reset the connection but not any existing authentication. The server should release all resources associated with the connection.

END

Used by a client to mark the end of raw data. The server may send END to indicate a partial end of data.

HELP

Lists all commands that the server understands as comment lines on the status channel.

QUIT

Reserved for future extensions.

OPTION

Set options for the connection. The syntax of such a line is

  OPTION name [ [=] value ]

Leading and trailing spaces around name and value are allowed but should be ignored. For compatibility reasons, name may be prefixed with two dashes. The use of the equal sign is optional but suggested if value is given.

CANCEL

This command is reserved for future extensions.

AUTH

This command is reserved for future extensions. Not yet specified as we don’t implement it in the first phase. See Werner’s mail to gpa-dev on 2001-10-25 about the rationale for measurements against local attacks.

NOP

No operation. Returns OK without any action.

3.3 Error codes

Libassuan is used with gpg-error style error codes. It is recommended to set the error source to a different value from the default GPG_ERR_SOURCE_UNKNOWN by calling function assuan_set_gpg_err_source early.

4.1 Header

All interfaces (data types and functions) of libassuan are defined in the header file assuan.h. You must include this in all source files using the library, either directly or through some other header file, like this:

#include <assuan.h>

The namespace of libassuan is assuan_* for function and type names and ASSUAN* for other symbols. In addition the same name prefixes with one prepended underscore are reserved for internal use and should never be used by an application.

Because libassuan makes use of the GPG Error library, using libassuan will also use the GPG_ERR_* namespace directly, and the gpg_err* and gpg_str* namespaces indirectly.

4.2 Building sources

If you want to compile a source file including the assuan.h header file, you must make sure that the compiler can find it in the directory hierarchy. This is accomplished by adding the path to the directory in which the header file is located to the compilers include file search path (via the -I option).

However, the path to the include file is determined at the time the source is configured. To solve this problem, libassuan ships with a small helper program libassuan-config that knows the path to the include file and other configuration options. The options that need to be added to the compiler invocation at compile time are output by the --cflags option to libassuan-config. The following example shows how it can be used at the command line:

gcc -c foo.c $(libassuan-config --cflags)

Adding the output of ‘libassuan-config --cflags’ to the compiler’s command line will ensure that the compiler can find the assuan.h header file.

A similar problem occurs when linking the program with the library. Again, the compiler/linker has to find the library files. For this to work, the path to the library files has to be added to the library search path (via the -L option). For this, the option --libs to libassuan-config can be used. For convenience, this option also outputs all other options that are required to link the program with the libassuan libraries (in particular, the -lassuan option). The example shows how to link foo.o with the libassuan library to a program foo.

gcc -o foo foo.o $(libassuan-config --libs)

You can also combine both examples to a single command by specifying both options to libassuan-config:

gcc -o foo foo.c $(libassuan-config --cflags --libs)

4.3 Building sources using Automake

It is much easier if you use GNU Automake instead of writing your own Makefiles. If you do that you do not have to worry about finding and invoking the libassuan-config script at all. libassuan provides an Automake macro that does all the work for you.

Macro: AM_PATH_LIBASSUAN ([minimum-version], [action-if-found], [action-if-not-found]) ¶

Check whether libassuan (at least version minimum-version, if given) exists on the host system. If it is found, execute action-if-found, otherwise do action-if-not-found, if given.

Additionally, the function defines LIBASSUAN_CFLAGS to the flags needed for compilation of the program to find the assuan.h header file, and LIBASSUAN_LIBS to the linker flags needed to link the program to the libassuan library.

You can use the defined Autoconf variables like this in your Makefile.am:

AM_CPPFLAGS = $(LIBASSUAN_CFLAGS)
LDADD = $(LIBASSUAN_LIBS)

4.4 Multi Threading

The libassuan library is designed so that it can be used in a threaded application, if some rules are followed.

• Run the initialization functions before you actually start to use threads. Specifically, the functions assuan_set_gpg_err_source, assuan_set_malloc_hooks and assuan_set_log_cb should not be called concurrently with assuan_new. Use assuan_new_ext instead or ensure proper serialization.
• Only one thread at a time may access an libassuan context.
• If you use the default log handler, use assuan_set_assuan_log_stream to setup a default log stream.
• If you have callback functions shared by multiple functions, the callback function must be reentrant for that purpose. libassuan does not serialize invocation of callback functions across contexts.

5.1 Data Types used by the library

ASSUAN uses a so-called context to store a connection’s state. The following data type is used for that:

Data type: assuan_context_t ¶

The assuan_context_t type is a pointer to an object maintained internally by the library. Contexts are allocated with assuan_new or assuan_new_ext and released with assuan_release. Other functions take this data type to access the state created by these functions.

Data type: assuan_fd_t ¶

The assuan_fd_t is a file descriptor (in Unix) or a system handle (in Windows). The special value ASSUAN_INVALID_FD is used to specify invalid Assuan file descriptors.

Function: assuan_fd_t assuan_fdopen (int fd) ¶

Create an assuan file descriptor from a POSIX (libc) file descriptor fd. On Unix, this is equivalent to dup, while on Windows this will retrieve the underlying system handle with _get_osfhandle and duplicate that.

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.

5.3 Default Log Handler

The default log handler can be configured by the following functions:

Function: void assuan_set_assuan_log_prefix (const char *text) ¶

Set the prefix to be used at the start of a line emitted by assuan on the log stream to text. The default is the empty string.

Function: const char * assuan_get_assuan_log_prefix (void) ¶

Return the prefix to be used at the start of a line emitted by assuan on the log stream. The default implementation returns the empty string.

Function: void assuan_set_assuan_log_stream (FILE *fp) ¶

This sets the default log stream to which libassuan should log messages not associated with a specific context to fp. The default is to log to stderr. This default value is also changed by using assuan_set_log_stream (to set a logging stream for a specific context) unless this function has been used. Obviously this is not thread-safe and thus it is highly recommended to use this function to setup a proper default.

Function: FILE * assuan_get_assuan_log_stream (void) ¶

Return the stream which is currently being using for global logging.

The log stream used by the default log handler can also be set on a per context basis.

Function: void assuan_set_log_stream (assuan_context_t ctx, FILE *fp) ¶

Enable debugging for the context ctx and write all debugging output to the stdio stream fp. If the default log stream (used for non-context specific events) has not yet been set, a call to this functions implicitly sets this stream also to fp.

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.

5.5 How to communicate with the peer

What would be an IPC library without the ability to read and write data? Not very useful. Libassuan has high level functions to take care of of the more boring stuff, but eventually data needs to be written and read.

The basic read and write functions are:

Function: gpg_error_t assuan_read_line (assuan_context_t ctx, char **line, size_t *linelen) ¶

Read the next line written by the peer to the control channel and store a pointer to the buffer holding that line at the address line. The valid length of the lines is stored at the address of linelen. This buffer is valid until the next read operation on the same context ctx. You may modify the context of this buffer. The buffer is invalid (i.e. must not be used) if an error is returned. This function returns 0 on success or an error value.

Function: gpg_error_t assuan_write_line (assuan_context_t ctx, const char *line) ¶

Write the string line to the other end on the control channel. This string needs to be a proper formatted Assuan protocol line and should not include a linefeed. Sending linefeed or Nul characters is not possible and not allowed by the assuan protocol. This function shall not be used for sending data (D) lines. This function returns 0 on success or an error value.

To actually send bulk data lines a specialized function is available:

Function: gpg_error_t assuan_send_data (assuan_context_t ctx, const void *buffer, size_t length) ¶

This function is used by a server or a client to send length bytes of bulk data in buffer to the other end on the control channel. The data will be escaped as required by the Assuan protocol and may get buffered until a line is full. To flush any pending data, buffer may be passed as NULL and length be 0.

When used by a client, this flush operation does also send the END command to terminate the response on an INQUIRE request. Note that the function assuan_transact takes care of sending this END itself.

This function returns 0 on success or an error value.

The input and output of data can be controlled at a higher level using an I/O monitor.

Data type: unsigned int (*assuan_io_monitor_t) (assuan_context_t ctx, void *hook_value, int inout, const char *line, size_t linelen) ¶

The monitor function is called right after a line has been received, if inout is ASSUAN_IO_FROM_PEER, or just before it is send, if inout is ASSUAN_IO_TO_PEER. The hook_value is provided by the user when registering the I/O monitor function with a context using assuan_set_io_monitor. The callback function should return the bitwise OR of some (or none) of the following flags:

ASSUAN_IO_MONITOR_NOLOG

Active logging of this line is suppressed. This can reduce debug output in the case of a frequent message.

ASSUAN_IO_MONITOR_IGNORE

The whole output line is discarded.

Function: void assuan_set_io_monitor (assuan_context_t ctx, assuan_io_monitor_t io_monitor, void *hook_data) ¶

This function registers an I/O monitor io_monitor for the context ctx with the hook value hook_data.

8.1 External I/O event loops in the client.

The reference implementation for using external I/O event loops in the client is the GPGME library, which exports its own external I/O event loop mechanism and utilizes the Assuan library transparently for the user. The following steps document how GPGME achieves this.

1. Before connecting, set up pipes for bulk data transfer (using the INPUT/OUTPUT commands, for example). These are passed to the server either by inheritance (using a pipe server) or by FD passing (using a socket server).
2. Then you need to connect to the server. GPGME uses a pipe server, so it just spawns a server process, which is a non-blocking operation. FIXME: Currently, using a client with external event loop over a socket connection is not supported. It is easy to support (we just need a variation of assuan_socket_connect which takes an already connected socket FD and turns it into an Assuan context), so if you need this let us know.
3. After connecting, get the inbound status FD with assuan_get_active_fds (the first one returned is the status FD). This FD can be duplicated if it is convenient (GPGME does this to be able to close this FD and associated callback handlers without disrupting Assuan’s internals).
4. Then register the Assuan inbound status FD and all bulk data FDs with the I/O event mechanism. In general, this requires setting up callback handlers for these FDs and registering them with the main event loop.
5. When bulk data FDs become ready, you can simply perform the corresponding read or write operations. When the inbound status FD becomes ready, you can receive the next server line with assuan_read_line().
6. You should close and unregister the bulk data FDs when you wrote all data (for outbound FDs) or receive an EOF (for inbound FDs). When you receive an ERR from the server, or an OK for the final operation, you can unregister the inbound status FD and call assuan_release.
7. As noted above, all send operations on the outbound status FD are done immediate with blocking. In GPGME, this has never caused any problems.
8. The INQUIRE function can be handled in two ways: If the requested data is immediately available, the client can just send the data blockingly. If the requested data needs to be fetched from a blocking source, a callback handler can be registered for the FD with the main event loop. GPGME does not support the INQUIRE function, so we do not have any practical experience with this.

Currently, the client can not cancel a pending operation gracefully. It can, however, disconnect from the server at any time. It is the responsibility of the server to periodically send status messages to the client to probe if the connection remains alive.

8.2 External I/O event loops in the server.

Currently, no Assuan server exists which uses external I/O event loops. However, the following guidelines should lead to a usable implementation:

1. For socket servers: You can not use assuan_accept, so you should just implement the bind/connect/listen/accept stage yourself. You can register the listen FD with your main event loop, accept the connection when it becomes ready, and finally call assuan_init_socket_server with the final argument being ASSUAN_SOCKET_SERVER_ACCEPTED to create an Assuan context for this connection. This way you can also handle multiple connections in parallel. The reference implementation for this approach is DirMngr.

   For pipe servers: assuan_init_pipe_server creates an Assuan context valid for the pipe FDs.

2. Once you have a context for a single connection, you can get the inbound status FD with assuan_get_active_fds (the first one returned is the status FD). This FD can be duplicated if it is convenient. Every time the inbound status FD is readable, you should invoke the function assuan_process_next (see below) to process the next incoming message. assuan_process_next processes as many status lines as can be received by a single read operation. When it returns, the inbound status FD may still be readable, but Assuan does not check this.

   The function assuan_process_next returns 0 if it can not make progress reliably, and it returns true in done if the client closed the connection. See below for more information on this function.

3. The command will be dispatched by assuan_process_next just as with assuan_process, however, you will want to implement the command handlers in such a way that they do not block. For example, the command handler may just register the bulk data FDs with the main event loop and return.

   When the command is finished, irregardless if this happens directly in the command handler or later, you must call assuan_process_done with an appropriate error value (or 0 for success) to return an appropriate status line to the client. You can do this at the end of the command handler, for example by ending it with return assuan_process_done (error_code);. Another possibility is to invoke assuan_process_done from the place in the code which closes the last active bulk FD registered with the main event loop for this operation.

It is not possible to use assuan_inquire in a command handler, as this function blocks on receiving the inquired data from the client. Instead, the asynchronous version assuan_inquire_ext needs to be used (see below), which invokes a callback when the client provided the inquired data. A typical usage would be for the command handler to register a continuation with assuan_inquire_ext and return 0. Eventually, the continuation would be invoked by assuan_process_next when the client data arrived. The continuation could complete the command and eventually call assuan_process_done.

Cancellation is supported by returning an appropriate error value to the client with assuan_process_done. For long running operations, the server should send progress status messages to the client in regular intervals to notice when the client disconnects.

Function: gpg_error_t assuan_process_next (assuan_context_t ctx, int *done) ¶

This is the same as assuan_process but the caller has to provide the outer loop. He should loop as long as the return code is zero and done is false.

Function: gpg_error_t assuan_process_done (assuan_context_t ctx, gpg_error_t rc) ¶

Finish a pending command and return the error code rc to the client.

Function: gpg_error_t assuan_inquire_ext (assuan_context_t ctx, const char *keyword, size_t maxlen, gpg_error_t (*cb) (void *cb_data, gpg_error_t rc, unsigned char *buffer, size_t buffer_len), void *cb_data) ¶

This is similar to assuan_inquire but the caller has to provide the outer loop (using assuan_process_next). The caller should specify a continuation with cb, which receives cb_data as its first argument, and the error value as well as the inquired data as its remaining arguments.