home | help 
gensio_event(3) 	    Library Functions Manual		 gensio_event(3)

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 pa-
     rameters 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 chan-
     nel 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_NOT-
     SUP 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 verifi-
     cation  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 in-
     formation 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.   Cur-
     rently 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 sergen-
     sio_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 re-
     quest  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  re-
     ported  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 sergen-
     sio_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  opera-
     tions.   The  server  should do them, but no response is required.  You may
     notice  that  break  is  not  here,  break  is  handled  through  the  GEN-
     SIO_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)
home | help