#ifndef  LIBTIO_IO_SERIAL_H
# define LIBTIO_IO_SERIAL_H 20190429
# include "../cdefs.h"

TIO_BEGIN_NAMESPACE

/* A serial stream is for a serial (e.g. RS-232) connexion between the
 * current machine and another one. Using such a stream, you can read,
 * write and define the connexion attributes.
 *
 * The connexion attributes define how the two parts communicate with
 * each other. */

TIO_STRUCT(tio_serial_attrs, tio_serial_attrs_t)

/* Among the attributes of such a stream, you can define:
 * - the connexion speed, in bauds;
 * - various flags;
 * - various characters that will impact the communication. */

# define TIO_SERIAL_ATTRS_NCCS 2

struct tio_serial_attrs {
	unsigned int  tio_serial_attrs_flags;
	unsigned long tio_serial_attrs_speed;
	unsigned char tio_serial_attrs_cc[TIO_SERIAL_ATTRS_NCCS];
};

/* Here are the different speeds you can set, in bauds: */

# define TIO_B110         110
# define TIO_B300         300
# define TIO_B600         600
# define TIO_B1200       1200
# define TIO_B2400       2400
# define TIO_B4800       4800
# define TIO_B9600       9600
# define TIO_B14400     14400
# define TIO_B19200     19200
# define TIO_B38400     38400
# define TIO_B57600     57600
# define TIO_B115200   115200
# define TIO_B128000   128000
# define TIO_B256000   256000

/* Use `tio_make_serial_speed()` and `tio_make_serial_speed_in_bauds()` to
 * make the conversion, it will make your life easier.
 *
 * Here are the control characters you can define:
 * `TIO_XON`: the XON character to re-enable transmission (software control);
 * `TIO_XOFF`: the XOFF charater to disable transmission (software control). */

# define TIO_XON  0
# define TIO_XOFF 1

/* Among the flags, you can find various things. First of all, the stop bits
 * settings (1 or 2):
 * `TIO_STOONE`: 1 stop bit;
 * `TIO_STOTWO`: 2 stop bits.
 *
 * For example, to set some stop bits settings:
 * `flags = (flags & ~TIO_STOMASK) | TIO_STOTWO;` */

# define TIO_STOMASK      0x0001
# define TIO_STOONE       0x0000
# define TIO_STOTWO       0x0001

/* Then the parity settings:
 * `TIO_PARDIS`: disable parity checking;
 * `TIO_PARENB`: enable parity checking;
 * `TIO_PAREVEN`: even parity (when enabled);
 * `TIO_PARODD`: odd parity (when enabled).
 *
 * For example, to set some parity settings:
 * `flags = (flags & ~TIO_PARMASK) | TIO_PARENB | TIO_PAREVEN;` */

# define TIO_PARMASK      0x0006
# define TIO_PARDIS       0x0000
# define TIO_PARENB       0x0002
# define TIO_PAREVEN      0x0000
# define TIO_PARODD       0x0004

/* The DTR/RTS settings.
 * `TIO_DTRDIS`: disable DTR.
 * `TIO_DTRENB`: enable DTR.
 * `TIO_DTRHAND`: enable DTR and handshake.
 * `TIO_RTSDIS`: disable RTS.
 * `TIO_RTSENB`: enable RTS.
 * `TIO_RTSHAND`: enable RTS and handshake.
 *
 * For example, to set some DTR/RTS settings:
 * `flags = (flags & ~TIO_DTRRTSMASK) | TIO_DTRHAND | TIO_RTSDIS;`
 *
 * Notice that not all platforms implement this. Streams just do as they
 * can. */

# define TIO_DTRMASK      0x0018
# define TIO_RTSMASK      0x0060
# define TIO_DTRRTSMASK   0x0078
# define TIO_RTSDTRMASK   0x0078

# define TIO_DTRDIS       0x0000
# define TIO_DTRENB       0x0008
# define TIO_DTRHAND      0x0018
# define TIO_DTRNOHAND    0x0000

# define TIO_RTSDIS       0x0000
# define TIO_RTSENB       0x0020
# define TIO_RTSHAND      0x0060
# define TIO_RTSNOHAND    0x0000

/* The XON/XOFF software control settings.
 *
 * XOFF disables the transmission temporarily, usually because the device at
 * the other end can't manage so much data at once, whereas XON re-enables the
 * transmission, probably because the device at the other end has finished
 * processing the data you sent it and is ready to process some more.
 *
 * XON/XOFF software flow control can be enabled on input (XIN) and
 * output (XOFF). The XON and XOFF characters are common to both
 * the input and the output.
 *
 * `TIO_XINDIS`:  disable input XON/XOFF.
 * `TIO_XINENB`:  enable  input XON/XOFF.
 * `TIO_XOUTDIS`: disable output XON/XOFF.
 * `TIO_XOUTENB`: enable  output XON/XOFF.
 *
 * For example, to set some XON/XOFF settings:
 * `flags = (flags & ~TIO_XONXOFFMASK) | TIO_XONENB | TIO_XOFFDIS;` */

# define TIO_XINMASK     0x0080
# define TIO_XOUTMASK    0x0100
# define TIO_XINOUTMASK  0x0180
# define TIO_XOUTINMASK  0x0180

# define TIO_XINDIS      0x0000
# define TIO_XINENB      0x0080

# define TIO_XOUTDIS     0x0000
# define TIO_XOUTENB     0x0100

/* When setting the attributes, sometimes you only want to set some of
 * the attributes, here are flags to control what you set.
 *
 * `TIO_SERIALFLAG_SPEED`: set the speed.
 * `TIO_SERIALFLAG_XIN`: set the XON/XOFF input settings and characters.
 * `TIO_SERIALFLAG_XOUT`: set the XON/XOFF output settings and characters.
 * `TIO_SERIALFLAG_STOP`: set the stop bits.
 * `TIO_SERIALFLAG_PARITY`: set the parity.
 * `TIO_SERIALFLAG_DTR`: set the DTR mode.
 * `TIO_SERIALFLAG_RTS`: set the RTS mode.
 *
 * `TIO_SERIALFLAG_ALL`: everything. */

# define TIO_SERIALFLAG_SPEED     1
# define TIO_SERIALFLAG_XIN       2
# define TIO_SERIALFLAG_XOUT      4
# define TIO_SERIALFLAG_STOP      8
# define TIO_SERIALFLAG_PARITY   16
# define TIO_SERIALFLAG_DTR      32
# define TIO_SERIALFLAG_RTS      64

# define TIO_SERIALFLAG_XINOUT    6
# define TIO_SERIALFLAG_XOUTIN    6
# define TIO_SERIALFLAG_DTRRTS   96
# define TIO_SERIALFLAG_RTSDTR   96
# define TIO_SERIALFLAG_ALL     127

/* ---
 * Utilities.
 * --- */

TIO_BEGIN_DECLS

/* Manage the attributes. */

TIO_EXTERN(int) tio_make_serial_attrs
	OF((tio_serial_attrs_t *tio__attrs, char const *tio__raw,
		unsigned long tio__flags));

TIO_EXTERN(int) tio_make_serial_speed
	OF((unsigned long *tio__speed, unsigned long tio__bauds));
TIO_EXTERN(int) tio_make_serial_speed_in_bauds
	OF((unsigned long *tio__bauds, unsigned long tio__speed));

/* List the available serial ports.
 * The iterator yields strings (`char const *`) representing the path. */

TIO_EXTERN(int) tio_list_serial_ports
	OF((tio_iter_t **tio__iterp));

# define tio_next_serial_port(ITER, PTRP) \
	(tio_next((ITER), (void **)(char const **)(PTRP)))

TIO_END_DECLS
TIO_END_NAMESPACE

#endif /* LIBTIO_IO_SERIAL_H */