— 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: assuan_error_t assuan_write_status (assuan_context_t ctx, const char *keyword, const char *text)

This is a convenience function for a server to send a status line. You need to pass it the keyword and the content of the status line in text.

— Function: assuan_error_t assuan_inquire (assuan_context_t ctx, const char *keyword, unsigned char **r_buffer, size_t *r_length, size_t maxlen)

A server may use this function to inquire data from a client. It sends an “INQUIRE” command back to the server and returns the response conveniently in a newly allocated buffer. You need to pass at least the server's context ctx and the keyword describing the requested data. All other parameters may be NULL or 0, although this is rarely useful.

On success the result is stored in a newly allocated buffer stored at r_buffer. The length of the data is stored at r_length. If maxlen has not been given as 0, it describes an upper size limited of the expected data. If the client returns too much data the function fails and the error code GPG_ERR_ASS_TOO_MUCH_DATA will be returned.

— Function: FILE* assuan_get_data_fp (assuan_context_t ctx)

Return a stdio stream for the Assuan context ctx. This stream may then be used for data output (assuan_write_data). The stream is valid until the end of the current handler. Calling fclose for that stream is not required. Assuan does all the buffering needed to insert the status line as well as the required line wrapping and quoting for data lines.

This function is only available on systems supporting either funopen or fopencookie. If it is not supported NULL is returned and errno is set to ENOSYS.

— Function: assuan_error_t assuan_set_okay_line (assuan_context_t ctx, const char *line)

Set the text used for the next “OK” response to line. This is sometimes useful to send additional human readable information along with the OK line. The string is automatically reset at the end of the current handler.

— Function: assuan_error_t assuan_command_parse_fd (assuan_context_t ctx, char *line, int *rfd)

This is the core of the default “INPUT” and “OUTPUT” handler. It may be used in custom commands as well to negotiate a file descriptor. If line contains FD=n, it returns n in rfd assuming a local file descriptor. If line contains just FD it returns a file descriptor at rfd; this file descriptor needs to have been sent by the client right before using assuan_sendfd.

On W32 systems the returned file descriptor is a system handle and not a libc low level I/O file descriptor. Thus applications need to use _open_osfhandle before they can pass this descriptor to standard functions like fdopen or dup.

— Function: int assuan_get_input_fd (assuan_context_t ctx)

Return the file descriptor sent by the client using the last “INPUT” command. Returns -1 if no file descriptor is available.

— Function: int assuan_get_output_fd (assuan_context_t ctx)

Return the file descriptor sent by the client using the last “OUTPUT” command. Returns -1 if no file descriptor is available.

— Function: assuan_error_t assuan_close_input_fd (assuan_context_t ctx)

Close the file descriptor set by the last “INPUT” command. This function has the advantage over a simple close that it can do some sanity checks and make sure that a following assuan_get_input_fd won't return an already closed descriptor.

— Function: assuan_error_t assuan_close_output_fd (assuan_context_t ctx)

Close the file descriptor set by the last “OUTPUT” command. This function has the advantage over a simple close that it can do some sanity checks and make sure that a following assuan_get_input_fd won't return an already closed descriptor.

— Function: int assuan_set_error (assuan_context_t ctx, int err, const char *text)

This is a helper to provide a more descriptive error text with “ERR” lines. For this to work, the text needs to be stored in the context ctx while still being in the command handler. This function is commonly called this way

            return assuan_set_error (ctx, err, "commands needs 5 arguments");
     

The value err is passed through and thus the return value of the command handler in the example. The provided text further explains that error code to humans.

— 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. Currently only one flag is defined:

ASSUAN_NO_WAITPID

When using a pipe server, by default Libassuan will wait for the forked process to die in assuan_disconnect. 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

Uses to return the state of the confidential logging mode. For changing this mode the functions assuan_begin_confidential and assuan_end_confidential should be used.

— Function: int assuan_get_flag (assuan_context_t ctx, assuan_flag_t flag)

Return the value of flag in context ctx.

— Function: const char* assuan_strerror (assuan_error_t err)

This function returns a textual representation of the given error code err. If this is an unknown value, a string with the value is returned. (Beware: it is hold in a static buffer). It is suggested that gpg-error style error numbers should be used and thus gpg_strerror be called. See function assuan_set_assuan_err_source, on how to enable these error codes.

— Function: pid_t assuan_get_pid (assuan_context_t ctx)

This function returns the pid of the connected connected peer. If that pid is not known -1 is returned. Note that it is not always possible to learn the pid of the other process. For a pipe based server the client knows it instantly and a mechanism is in place to let the server learn it. For socket based servers the pid is only available on systems providing the “SO_PEERCRED” socket option ¹.

— Function: assuan_error_t assuan_get_peercred (assuan_context_t ctx, pid_t *pid, uid_t *uid, gid_t *pid)

Return user credentials of the peer. This will work only on certain systems and only when connected over a socket. If you are not interested in some of the values, pass NULL instead of the address of an appropriate variable. pid, uid and gid are only set if the function succeeds and returns with 0.

As of now only the server is able to retrieve this information. Note, that for getting the pid of the peer assuan_get_pid is usually better suited.

— Function: int assuan_get_active_fds (assuan_context_t ctx, int what, int *fdarray, int fdarraysize)

Return all active file descriptors for the context ctx. This function can be used to select on the file descriptors and to call assuan_process_next if there is an active one. The first descriptor in the array is the one used for the command connection. Currently what needs to be 0 to return descriptors used for reading, 1 will eventually be used to return descriptors used for writing. fdarray is an array of integers provided by the caller; fdarraysize gives the size of that array.

On success the number of active descriptors are returned. These active descriptors are then stored in fdarray. On error -1 is returned; the most likely reason for this is a too small fdarray.

Note that on W32 systems the returned file descriptor is a system handle and not a libc low level I/O file descriptor.

— Function: int assuan_pending_line (assuan_context_t ctx)

A call to this function return true if a full line has been buffered and thus an entire assuan line may be read without triggering any actual I/O.

— Function: void assuan_set_io_monitor (assuan_context_t ctx, unsigned int (*monitor)(assuan_context_t ctx, int direction, const char *line, size_t linelen))

This function registers an I/O monitor for the context ctx. Such a monitor function is called right after a line has been received or just before it is send. With direction set to 1 the monitor has been called for an output operation; 0 obviosuly means it has been called for an input operation. If the monitor sets bit 0 in the return value, any active logging of the line will be suppressed. With bit 1 set, the entire line will be ignored.

— Function: void assuan_begin_confidential (assuan_context_t ctx)

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

— 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).

— Function: FILE* assuan_get_assuan_log_stream (void)

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

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