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.