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 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. err is a standard gensio errno. 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. Return value is ignored.

  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. Return value is ignored.

  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. The return value is ignored.

  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. 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 vailing 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.

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)