.TH gensio_event 3 "21 Feb 2019"
.SH NAME
gensio_event \- Event handler for events from a gensio
.SH SYNOPSIS
.B #include <gensio/gensio.h>
.TP 20
.B typedef int (*gensio_event)(struct gensio *io, void *user_data,
.br
.B                          int event, int err,
.br
.B                          unsigned char *buf, gensiods *buflen,
.br
.B                          const char *const *auxdata);
.SH "DESCRIPTION"
When an event happens on a gensio that is reported to the user, the
gensio library calls the
.I gensio_event
type handler that was registered with the gensio.

The use of the various parameters depends on the particular event.
The parameters that don't vary are:
.TP
.B io
\- The gensio the event is being reported for.
.TP
.B user_data
\- The user_data supplied when the event handler was registered.
.TP
.B event
\- The particular event being reported.
.PP
Events follow.
.SS "GENSIO_EVENT_READ"
Called when data is read from the I/O device.

If
.B err
is zero, buf points to a data buffer and buflen is the number
of bytes available.

If
.B err
is set, buf and buflen are undefined and you should not use them or
modify them.
.B err
is a standard gensio errno.

If err is non-zero, you must set the number of bytes consumed in
.B buflen.
Note that you must
disable read if you don't consume all the bytes or in other
situations where you don't want the read handler called.
.B auxdata,
if not NULL, may contain information about the message, like if it
is out of band (oob) data.  See information on the specific gensio
for details.

Note that only one read callback is allowed to run at a time on a
gensio.

If an error is reported in
.B err,
then the gensio will be closed.  This is used to report that the other
end closed the connection (GE_REMCLOSE), or that other internal errors
occurred.

You should always return zero, it used to not matter, but it does now.
.SS "GENSIO_EVENT_WRITE_READY"
Called when data can be written to the I/O device.

Note that only one write callback is allowed to run at a time on a
gensio.

Unlike Unix-like systems, a write handler will be called (if enabled)
if the lower layer has an exception.  This is necessary because we
don't have a separate exception handler coming from the lower layer.
But this lets the write operation return a failure if something has
gone wrong.

You should always return zero, it used to not matter, but it does now.
.SS "GENSIO_EVENT_NEW_CHANNEL"
A new channel has been created by the remote end of the connection.
The new channel gensio is in buf and must be cast.  Information about
the channel will be passed in
.B auxdata,
see documentation on the particular gensio for details.  If this
returns an error (non-zero) the channel is shut down, though in the
future specific error returns may have different behavior.  You must
return GE_NOTSUP (like you should for all unhandled events) if you
don't support this event.  All other error returns besides zero and
GE_NOTSUP are reserved.

.SS "GENSIO_EVENT_SEND_BREAK"
Got a request from the other end to send a break.  Telnet client or
server.

Blocked if gensio read is disabled.
.SS "GENSIO_EVENT_AUTH_BEGIN"
Authorization has begun, the username and service is available but
nothing else.

There are a few special return values from this event:
.TP
.B GE_AUTHREJECT
\- Fail the connection, but continue to go through the motions.  This
should be called if the user was invalid or data wasn't properly
provided.
.TP
.B 0
\- authorization has succeeded.  No more authentication is required,
but the protocol may still go through the motions of the protocol.
.TP
.B GE_NOTSUP
\- Just continue with authentication.
.PP
Any other error will terminate the connection, these should
generally be things like out of memory and such,
.B NOT
authentication failures of any kind.

certauth only
.SS "GENSIO_EVENT_PRECERT_VERIFY"
The connection has received a certificate but has not verified it
yet.  This lets the user modify the certificate authority based on
certificate information.

Return values are the same as
.B GENSIO_EVENT_AUTH_BEGIN.

ssl and certauth
.SS "GENSIO_EVENT_POSTCERT_VERIFY"
The connection has received a certificate and has verified it.  The
verification may have failed.  This lets the user handle their own
verification override.  err will be one of the following:
.TP
0
on verification success.
.TP
.B GE_CERTNOTFOUND
if no certificate was found
.TP
.B GE_CERTREVOKED
if the if the certificate was revoked
.TP
.B GE_CERTEXPIRED
if the certificate has expired
.TP
.B GE_CERTINVALID
for other errors.
.PP
Any other error will terminate the connection, these should
generally be things like out of memory and such,
.B NOT
authentication failures of any kind.

.B auxdata[0]
will be an error string (or NULL if none available).  Make sure to check
if
.B auxdata
is NULL before indexing
.B auxdata[0].

Return values are:
.TP
.B 0
\- Authentication successed (even if an error was reported).
.TP
.B GE_NOTSUP
\- Continue with the authentication process.  Password
authentication may occur, for instance, if an error was reported.
.TP
.B GE_AUTHREJECT
\- Fail the authentication. No more authentication will occur.
.PP
ssl and certauth
.SS "GENSIO_EVENT_PASSWORD_VERIFY"
A password has been received from the remote end, it is passed
in
.B buf.
The callee should validate it.  If doing 2-factor auth, you should
also fetch the 2-factor data with the
.I GENSIO_CONTROL_2FA
control and handle that here, too.  If this function is called,
.I GENSIO_EVENT_2FA_VERIFY
is not called.
The length is passed in *buflen.  Note that the buf is
nil terminated one past the length.  Return values are:
.TP
.B 0
\- The password verification succeeds.
.TP
.B GE_NOTSUP
\- Fail the validation, but the connection shutdown will
depend on the setting of allow-authfail.
.TP
.B GE_AUTHREJECT
\- Reject the authorization for some other reason besides failing
validation.
.PP
Any other error will terminate the connection, these should
generally be things like out of memory and such,
.B NOT
authentication failures of any kind.

certauth only
.SS "GENSIO_EVENT_REQUEST_PASSWORD"
On the client side of an authorization, the remote end has requested
that a password be sent.
.B buf
points to a buffer of
.B *buflen
bytes to place the password in, the user should put the password there
and update
.B *buflen
to the actual length.

Return 0 for success, or any other gensio error to fail the password
fetch.
.SS "GENSIO_EVENT_REQUEST_2FA"
On the client side of an authorization, the remote end has requested
two-factor authentication data, but it has not been supplied already.
.B buf
points to a pointer to a buffer (unsigned char **) that you should
return.  It should be allocated with the zalloc function of the
os_functions in use.
.B *buflen
is where to put the size of the buffer.  This buffer will be zeroed
and freed when done.

Return 0 for success, or any other gensio error to fail the 2FA
fetch.
.SS "GENSIO_EVENT_2FA_VERIFY"
A 2-factor auth has been received from the remote end and passed as
part of the password transfer.  This is only called if the login was
validated with a certificate, this is called to handle 2-factor auth
with a certificate.  The 2fa data is passed in
.B buf.
The callee should validate it.  The length is passed in *buflen.  Note
that the buf is nil terminated one past the length.  Return values
are:
.TP
.B 0
\- The verification succeeds.
.TP
.B GE_NOTSUP
\- Fail the validation, but the connection shutdown will
depend on the setting of allow-authfail.
.TP
.B GE_AUTHREJECT
\- Reject the authorization for some other reason besides failing
validation.
.PP
Any other error will terminate the connection, these should
generally be things like out of memory and such,
.B NOT
authentication failures of any kind.

certauth only
.SS "GENSIO_EVENT_PARMLOG"
When parsing a gensio string, this will be called if the gensio
detects an error in the initial parsing or initial configuration.
This is called only during the allocation (
.B str_to_gensio()
or equivalent).  Logging this information will make it easier for users
to find out what's wrong with their gensio strings.

The
.B buf
parameter contains a pointer to the following structure:

struct gensio_parmlog_data {
.br
    const char *log;
.br
    va_list args;
.br
};

which can be printed with normal vprintf() and the like.
.SS "GENSIO_EVENT_WIN_SIZE"
The other end of the connection is reporting a window size change.
Currently only on telnet with RFC1073 enabled.
.SS "GENSIO_EVENT_LOG"
Used to report general logs in gensios while processing.  Can be
called any time the gensio exists.

The
.B buf
parameter contains a pointer to the following structure:

struct gensio_log_data {
.br
    const char *log;
.br
    va_list args;
.br
};

which can be printed with normal vprintf() and the like.

.SS "SERIAL PORT CONTROLS"
These are controls for serial port settings.  These are received on
the server side only.  It should respond by setting the value (if
possible and the value isn't zero) and responding with the current
value with sergensio_xxx().

If the server receives a zero value for any of this, it should just
report the value and not change anything.

GENSIO_EVENT_SER_BAUD
.br
GENSIO_EVENT_SER_DATASIZE
.br
GENSIO_EVENT_SER_PARITY
.br
GENSIO_EVENT_SER_STOPBITS
.br
GENSIO_EVENT_SER_FLOWCONTROL
.br
GENSIO_EVENT_SER_IFLOWCONTROL
.br
GENSIO_EVENT_SER_SBREAK
.br
GENSIO_EVENT_SER_DTR
.br
GENSIO_EVENT_SER_RTS

For baud, databits, and stopbits, the value is an integer with the
number.

Parity values can be:
.br
GENSIO_SER_PARITY_NONE
.br
GENSIO_SER_PARITY_ODD
.br
GENSIO_SER_PARITY_EVEN
.br
GENSIO_SER_PARITY_MARK
.br
GENSIO_SER_PARITY_SPACE

Flow control values can be:
.br
GENSIO_SER_FLOWCONTROL_NONE
.br
GENSIO_SER_FLOWCONTROL_XON_XOFF
.br
GENSIO_SER_FLOWCONTROL_RTS_CTS

Input flow control values can be:
.br
GENSIO_SER_FLOWCONTROL_DCD
.br
GENSIO_SER_FLOWCONTROL_DTR
.br
GENSIO_SER_FLOWCONTROL_DSR

For values that are on/off (the rest), use the following:
.br
GENSIO_SER_ON
.br
GENSIO_SER_OFF

.SS "SIGNATURE"
.B GENSIO_EVENT_SER_SIGNATURE
is received on the server side only and is a request for the
signature.  The server should respond by send the signature
with sergensio_signature().  No value is passed in this case.
.SS "STATE FUNCTIONS"
GENSIO_EVENT_SER_MODEMSTATE_MASK
.br
GENSIO_EVENT_SER_LINESTATE_MASK
.br
These are received on the server side to request updating the mask of
reported values.  The server should respond by returning the current
mask with the
.B sergensio_modemstate
or
.B sergensio_linestate
functions.  The server need not handle all the bits requested by the
user.

GENSIO_EVENT_SER_MODEMSTATE
.br
GENSIO_EVENT_SER_LINESTATE

On the client side, these are reporting current modemstate and
linestate changes as an unsigned integer.  See sergensio_modemstate(3)
and sergensio_linestate(3) for a meaning of the bits in the integer.
.SS "OTHER SERIAL PORT CONTROLS"
These are server-only, these are received requesting the various
operations.  The server should do them, but no response is required.
You may notice that break is not here, break is handled through
the GENSIO_EVENT_SEND_BREAK event.

GENSIO_EVENT_SER_FLOW_STATE
.br
GENSIO_EVENT_SER_FLUSH
.SS "SYNC"
GENSIO_EVENT_SER_SYNC is a special operation that comes in when a TCP
sync event is received.  It may be received on both sides.  A server
should send a break.  The client can do whatever it wants with the
information, that is not defined by the RFC2217 specification.
.SH "OTHER EVENTS"
sergensio gensios have a set of other events, see sergensio(5) for
details.  Other gensio that are not part of the gensio library proper
may have their own events, too.
.SH "RETURN VALUES"
See the individual events for the values you should return.  If an
event is not handled by the event handler, the handler must return
GE_NOTSUP, except in the case of
.B GENSIO_EVENT_READ
and
.B GENSIO_EVENT_WRITE_READY
which must be handled.
.SH "SEE ALSO"
gensio_set_callback(3), str_to_gensio_child(3), gensio_open_channel(3),
gensio_open_channel_s(3), gensio_acc_str_to_gensio(3), str_to_gensio(3)
sergensio(5), gensio_err(3)