Provided by: libgensio-dev_2.8.2-6.1build1_amd64 bug

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)