6 How to develop an Assuan client

Depending on the type of the server you want to connect you need to use different functions.

If the peer is not a simple pipe server but one using full-duplex sockets, the full-fledged variant of the above function should be used:

Function: gpg_error_t assuan_pipe_connect (assuan_context_t ctx,const char *name, const char *argv[], assuan_fd_t *fd_child_list, void (*atfork) (void *, int), void *atforkvalue, unsigned int flags)

A call to this functions forks the current process and executes the program name, passing the arguments given in the NULL-terminated list argv. A list of file descriptors not to be closed may be given using the ASSUAN_INVALID_FD terminated array fd_child_list.

If name is a null pointer, only a fork but no exec is done. Thus the child continues to run. However all file descriptors are closed and some special environment variables are set. To let the caller detect whether the child or the parent continues, the parent returns with "client" returned in argv and the child returns with "server" in argv. This feature is only available on POSIX platforms.

If atfork is not NULL, this function is called in the child right after the fork and the value atforkvalue is passed as the first argument. That function should only act if the second argument it received is 0. Such a fork callback is useful to release additional resources not to be used by the child.

flags is a bit vector and controls how the function acts:

ASSUAN_PIPE_CONNECT_FDPASSING

If cleared a simple pipe based server is expected. If set a server based on full-duplex pipes is expected. Such pipes are usually created using the socketpair function. It also enables features only available with such servers.

ASSUAN_PIPE_CONNECT_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.

If you are using a long running server listening either on a TCP or a Unix domain socket, the following function is used to connect to the server:

Function: gpg_error_t assuan_socket_connect (assuan_context_t ctx, const char *name, pid_t server_pid, unsigned int flags)

Make a connection to the Unix domain socket name using the already-initialized Assuan context at ctx. server_pid is currently not used but may become handy in the future; if you don’t know the server’s process ID (PID), pass ASSUAN_INVALID_PID. With flags set to ASSUAN_SOCKET_CONNECT_FDPASSING, sendmsg and recvmesg are used for input and output and thereby enable the use of descriptor passing.

Connecting to a TCP server is not yet implemented. Standard URL schemes are reserved for name specifying a TCP server.

Now that we have a connection to the server, all work may be conveniently done using a couple of callbacks and the transact function:

Function: gpg_error_t assuan_transact (assuan_context_t ctx, const char *command, gpg_error_t (*data_cb)(void *, const void *, size_t), void *data_cb_arg, gpg_error_t (*inquire_cb)(void*, const char *), void *inquire_cb_arg, gpg_error_t (*status_cb)(void*, const char *), void *status_cb_arg)

Here ctx is the Assuan context opened by one of the connect calls. command is the actual Assuan command string. It shall not end with a line feed and its length is limited to ASSUAN_LINELENGTH (~1000 bytes)

data_cb is called by Libassuan for data lines; data_cb_arg is passed to it along with the data and the length. [FIXME: needs more documentation].

inquire_cb is called by Libassuan when the server requests additional information from the client while processing the command. This callback shall check the provided inquiry name and send the data as requested back using the assuan_send_data. The server passed inquiry_cb_arg along with the inquiry name to the callback.

status_cb is called by Libassuan for each status line it receives from the server. status_cb_arg is passed along with the status line to the callback.

The function returns 0 success or an error value. The error value may be the one one returned by the server in error lines or one generated by the callback functions.

Libassuan supports descriptor passing on some platforms. The next two functions are used with this feature:

Function: gpg_error_t assuan_sendfd (assuan_context_t ctx, assuan_fd_t fd)

Send the descriptor fd to the peer using the context ctx. The descriptor must be sent before the command is issued that makes use of the descriptor.

Note that calling this function with a ctx of NULL and fd of ASSUAN_INVALID_FD can be used as a runtime test to check whether descriptor passing is available on the platform: 0 is returned if descriptor passing is available, otherwise an error with the error code GPG_ERR_NOT_IMPLEMENTED is returned.

Function: gpg_error_t assuan_receivefd (assuan_context_t ctx, assuan_fd_t *fd)

Receive a descriptor pending for the context ctx from the peer. The descriptor must be pending before this function is called. To accomplish this, the peer needs to use assuan_sendfd before the trigger is sent (e.g. using assuan_write_line ("INPUT FD").