FIDO_DEV_SET_IO_FUNCTIONS(3)

NAME
fido_dev_set_io_functions - FIDO 2 device I/O interface

SYNOPSIS
#include <fido.h>

    typedef void *fido_dev_io_open_t(const char *);
    typedef void  fido_dev_io_close_t(void *);
    typedef int   fido_dev_io_read_t(void *, unsigned char *, size_t, int);
    typedef int   fido_dev_io_write_t(void *, const unsigned char *, size_t);
    typedef int   fido_dev_io_rx_t(struct fido_dev *, uint8_t, unsigned char *, size_t, int);
    typedef int   fido_dev_io_tx_t(struct fido_dev *, uint8_t, const unsigned char *, size_t);
    typedef struct fido_dev_io {
    	fido_dev_io_open_t  *open;
    	fido_dev_io_close_t *close;
    	fido_dev_io_read_t  *read;
    	fido_dev_io_write_t *write;
    	fido_dev_io_rx_t    *rx;
    	fido_dev_io_tx_t    *tx;
    } fido_dev_io_t;

int
fido_dev_set_io_functions(fido_dev_t *dev, const fido_dev_io_t *io);

DESCRIPTION
The fido_dev_set_io_functions interface defines the I/O and transmission handlers used to talk to dev. Its usage is optional. By default, libfido2 will use the operating system's native HID interface to talk CTAP2 to a FIDO device.

A fido_dev_io_open_t function is expected to return a non-NULL opaque pointer on success, and NULL on error. The returned opaque pointer is never dereferenced by libfido2.

A fido_dev_io_close_t function receives the opaque handle obtained from fido_dev_io_open_t. It is not expected to be idempotent.

A fido_dev_io_read_t function reads a single HID report from dev. The first parameter taken is the opaque handle obtained from fido_dev_io_open_t. The read buffer is pointed to by the second parameter, and the third parameter holds its size. The last argument passed to fido_dev_io_read_t is the number of milliseconds the caller is willing to sleep, should the call need to block. If this value holds -1, fido_dev_io_read_t may block indefinitely. The number of bytes read is returned. On error, -1 is returned.

A fido_dev_io_write_t function writes a single HID report to dev. The first parameter taken is the opaque handle returned by fido_dev_io_open_t. The write buffer is pointed to by the second parameter, and the third parameter holds its size. A fido_dev_io_write_t function may block. The number of bytes written is returned. On error, -1 is returned.

A fido_dev_io_rx_t function receives a complete CTAP2 message from dev. The first parameter taken is a pointer to dev. The second parameter holds the expected CTAP2 command byte. The read buffer is pointed to by the third parameter, and the fourth parameter holds its size. The last argument passed to fido_dev_io_rx_t is the number of milliseconds the caller is willing to sleep, should the call need to block. If this value holds -1, fido_dev_io_rx_t may block indefinitely. The number of bytes read is returned. On error, -1 is returned.

A fido_dev_io_tx_t function transmits a complete CTAP2 message to dev. The first parameter taken is a pointer to dev. The second parameter holds the CTAP2 command byte. The write buffer is pointed to by the third parameter, and the fourth parameter holds its size. A fido_dev_io_tx_t function may block. On success, 0 is returned. On error, -1 is returned.

When calling fido_dev_set_io_functions(), the open, close, read and write fields of io may not be NULL. Either rx or tx may be NULL, in which case libfido2 uses its corresponding CTAP2 HID transport method.

No references to io are held by fido_dev_set_io_functions().

RETURN VALUES
On success, fido_dev_set_io_functions() returns FIDO_OK. On error, a different error code defined in <fido/err.h> is returned.