.\" Copyright (c) 2018 Yubico AB. All rights reserved.
.\" Use of this source code is governed by a BSD-style
.\" license that can be found in the LICENSE file.
.\"
.Dd $Mdocdate: May 25 2018 $
.Dt FIDO_DEV_SET_IO_FUNCTIONS 3
.Os
.Sh NAME
.Nm fido_dev_set_io_functions ,
.Nm fido_dev_set_sigmask
.Nd FIDO 2 device I/O interface
.Sh SYNOPSIS
.In fido.h
.Bd -literal
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 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_t;

#ifdef _WIN32
typedef int fido_sigset_t;
#else
typedef sigset_t fido_sigset_t;
#endif
.Ed
.Ft int
.Fn fido_dev_set_io_functions "fido_dev_t *dev" "const fido_dev_io_t *io"
.Ft int
.Fn fido_dev_set_sigmask "fido_dev_t *dev" "const fido_sigset_t *sigmask"
.Sh DESCRIPTION
The
.Fn fido_dev_set_io_functions
function sets the I/O handlers used by
.Em libfido2
to talk to
.Fa dev .
By default, these handlers are set to the operating system's native HID or NFC
interfaces.
They are defined as follows:
.Bl -tag -width Ds
.It Vt fido_dev_open_t
Receives a
.Vt const char *
holding a path and opens the corresponding device, returning a
non-NULL opaque pointer on success and NULL on error.
.It Vt fido_dev_close_t
Receives the opaque pointer returned by
.Vt fido_dev_open_t
and closes the device.
.It Vt fido_dev_read_t
Reads a single transmission unit (HID report, APDU) from a device.
The first parameter is the opaque pointer returned by
.Vt fido_dev_open_t .
The second parameter is the read buffer, and the third parameter
is the read buffer size.
The fourth parameter is the number of milliseconds the caller is
willing to sleep, should the call need to block.
If this value holds -1,
.Vt fido_dev_read_t
may block indefinitely.
On success, the number of bytes read is returned.
On error, -1 is returned.
.It Vt fido_dev_write_t
Writes a single transmission unit (HID report, APDU) to
.Fa dev .
The first parameter is the opaque pointer returned by
.Vt fido_dev_open_t .
The second parameter is the write buffer, and the third parameter
is the number of bytes to be written.
A
.Vt fido_dev_write_t
may block.
On success, the number of bytes written is returned.
On error, -1 is returned.
.El
.Pp
When calling
.Fn fido_dev_set_io_functions ,
the
.Fa open ,
.Fa close ,
.Fa read ,
and
.Fa write
fields of
.Fa io
may not be NULL.
.Pp
No references to
.Fa io
are held by
.Fn fido_dev_set_io_functions .
.Pp
The
.Fn fido_dev_set_sigmask
function may be used to specify a non-NULL signal mask
.Fa sigmask
to be used while
.Em libfido2's
default I/O handlers wait on
.Fa dev .
On UNIX-like operating systems,
.Vt fido_sigset_t
is defined as
.Vt sigset_t .
On Windows,
.Vt fido_sigset_t
is defined as
.Vt int
and
.Fn fido_dev_set_sigmask
is a no-op.
.Pp
No references to
.Fa sigmask
are held by
.Fn fido_dev_set_sigmask .
.Sh RETURN VALUES
On success,
.Fn fido_dev_set_io_functions
and
.Fn fido_dev_set_sigmask
return
.Dv FIDO_OK .
On error, a different error code defined in
.In fido/err.h
is returned.