Provided by: libgensio-dev_2.8.2-6.1build1_amd64 
NAME
gensio_event - Event handler for events from a gensio
SYNOPSIS
#include <gensio/gensio.h>
typedef int (*gensio_event)(struct gensio *io, void *user_data,
int event, int err,
unsigned char *buf, gensiods *buflen,
const char *const *auxdata);
DESCRIPTION
When an event happens on a gensio that is reported to the user, the gensio library calls the 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:
io - The gensio the event is being reported for.
user_data
- The user_data supplied when the event handler was registered.
event - The particular event being reported.
Events follow.
GENSIO_EVENT_READ
Called when data is read from the I/O device.
If err is zero, buf points to a data buffer and buflen is the number of bytes available.
If err is set, buf and buflen are undefined and you should not use them or modify them. err is a
standard gensio errno.
If err is non-zero, you must set the number of bytes consumed in 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.
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 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.
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.
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 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.
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.
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:
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.
0 - authorization has succeeded. No more authentication is required, but the protocol may still go
through the motions of the protocol.
GE_NOTSUP
- Just continue with authentication.
Any other error will terminate the connection, these should generally be things like out of memory and
such, NOT authentication failures of any kind.
certauth only
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 GENSIO_EVENT_AUTH_BEGIN.
ssl and certauth
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:
0 on verification success.
GE_CERTNOTFOUND
if no certificate was found
GE_CERTREVOKED
if the if the certificate was revoked
GE_CERTEXPIRED
if the certificate has expired
GE_CERTINVALID
for other errors.
Any other error will terminate the connection, these should generally be things like out of memory and
such, NOT authentication failures of any kind.
auxdata[0] will be an error string (or NULL if none available). Make sure to check if auxdata is NULL
before indexing auxdata[0].
Return values are:
0 - Authentication successed (even if an error was reported).
GE_NOTSUP
- Continue with the authentication process. Password authentication may occur, for instance, if
an error was reported.
GE_AUTHREJECT
- Fail the authentication. No more authentication will occur.
ssl and certauth
GENSIO_EVENT_PASSWORD_VERIFY
A password has been received from the remote end, it is passed in buf. The callee should validate it.
If doing 2-factor auth, you should also fetch the 2-factor data with the GENSIO_CONTROL_2FA control and
handle that here, too. If this function is called, 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:
0 - The password verification succeeds.
GE_NOTSUP
- Fail the validation, but the connection shutdown will depend on the setting of allow-authfail.
GE_AUTHREJECT
- Reject the authorization for some other reason besides failing validation.
Any other error will terminate the connection, these should generally be things like out of memory and
such, NOT authentication failures of any kind.
certauth only
GENSIO_EVENT_REQUEST_PASSWORD
On the client side of an authorization, the remote end has requested that a password be sent. buf points
to a buffer of *buflen bytes to place the password in, the user should put the password there and update
*buflen to the actual length.
Return 0 for success, or any other gensio error to fail the password fetch.
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. 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. *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.
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 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:
0 - The verification succeeds.
GE_NOTSUP
- Fail the validation, but the connection shutdown will depend on the setting of allow-authfail.
GE_AUTHREJECT
- Reject the authorization for some other reason besides failing validation.
Any other error will terminate the connection, these should generally be things like out of memory and
such, NOT authentication failures of any kind.
certauth only
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 ( 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 buf parameter contains a pointer to the following structure:
struct gensio_parmlog_data {
const char *log;
va_list args;
};
which can be printed with normal vprintf() and the like.
GENSIO_EVENT_WIN_SIZE
The other end of the connection is reporting a window size change. Currently only on telnet with RFC1073
enabled.
GENSIO_EVENT_LOG
Used to report general logs in gensios while processing. Can be called any time the gensio exists.
The buf parameter contains a pointer to the following structure:
struct gensio_log_data {
const char *log;
va_list args;
};
which can be printed with normal vprintf() and the like.
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
GENSIO_EVENT_SER_DATASIZE
GENSIO_EVENT_SER_PARITY
GENSIO_EVENT_SER_STOPBITS
GENSIO_EVENT_SER_FLOWCONTROL
GENSIO_EVENT_SER_IFLOWCONTROL
GENSIO_EVENT_SER_SBREAK
GENSIO_EVENT_SER_DTR
GENSIO_EVENT_SER_RTS
For baud, databits, and stopbits, the value is an integer with the number.
Parity values can be:
GENSIO_SER_PARITY_NONE
GENSIO_SER_PARITY_ODD
GENSIO_SER_PARITY_EVEN
GENSIO_SER_PARITY_MARK
GENSIO_SER_PARITY_SPACE
Flow control values can be:
GENSIO_SER_FLOWCONTROL_NONE
GENSIO_SER_FLOWCONTROL_XON_XOFF
GENSIO_SER_FLOWCONTROL_RTS_CTS
Input flow control values can be:
GENSIO_SER_FLOWCONTROL_DCD
GENSIO_SER_FLOWCONTROL_DTR
GENSIO_SER_FLOWCONTROL_DSR
For values that are on/off (the rest), use the following:
GENSIO_SER_ON
GENSIO_SER_OFF
SIGNATURE
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.
STATE FUNCTIONS
GENSIO_EVENT_SER_MODEMSTATE_MASK
GENSIO_EVENT_SER_LINESTATE_MASK
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 sergensio_modemstate or sergensio_linestate functions.
The server need not handle all the bits requested by the user.
GENSIO_EVENT_SER_MODEMSTATE
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.
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
GENSIO_EVENT_SER_FLUSH
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.
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.
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 GENSIO_EVENT_READ and
GENSIO_EVENT_WRITE_READY which must be handled.
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) 21 Feb 2019 gensio_event(3)