1gensio_event(3)            Library Functions Manual            gensio_event(3)
2
3
4

NAME

6       gensio_event - Event handler for events from a gensio
7

SYNOPSIS

9       #include <gensio/gensio.h>
10
11       typedef int (*gensio_event)(struct gensio *io, void *user_data,
12                           int event, int err,
13                           unsigned char *buf, gensiods *buflen,
14                           const char *const *auxdata);
15

DESCRIPTION

17       When  an  event  happens  on a gensio that is reported to the user, the
18       gensio library calls the gensio_event type handler that was  registered
19       with the gensio.
20
21       The use of the various parameters depends on the particular event.  The
22       parameters that don't vary are:
23
24       io     - The gensio the event is being reported for.
25
26       user_data
27              - The user_data supplied when the event handler was registered.
28
29       event  - The particular event being reported.
30
31       Events follow.
32
33   GENSIO_EVENT_READ
34       Called when data is read from the I/O device.
35
36       If err is zero, buf points to a data buffer and buflen is the number of
37       bytes available.
38
39       If err is set, buf and buflen are undefined and you should not use them
40       or modify them.  err is a standard gensio errno.
41
42       If err is non-zero, you must set the number of bytes  consumed  in  bu‐
43       flen.   Note  that  you  must disable read if you don't consume all the
44       bytes or in other situations where you  don't  want  the  read  handler
45       called.   auxdata,  if not NULL, may contain information about the mes‐
46       sage, like if it is out of band (oob) data.   See  information  on  the
47       specific gensio for details.
48
49       Note  that only one read callback is allowed to run at a time on a gen‐
50       sio.
51
52       If an error is reported in err, then the gensio will be  closed.   This
53       is  used  to  report  that the other end closed the connection (GE_REM‐
54       CLOSE), or that other internal errors occurred.
55
56       You should always return zero, it used to not matter, but it does now.
57
58   GENSIO_EVENT_WRITE_READY
59       Called when data can be written to the I/O device.
60
61       Note that only one write callback is allowed to run at a time on a gen‐
62       sio.
63
64       Unlike  Unix-like  systems, a write handler will be called (if enabled)
65       if the lower layer has an exception.   This  is  necessary  because  we
66       don't  have  a  separate exception handler coming from the lower layer.
67       But this lets the write operation return a  failure  if  something  has
68       gone wrong.
69
70       You should always return zero, it used to not matter, but it does now.
71
72   GENSIO_EVENT_NEW_CHANNEL
73       A  new  channel  has  been created by the remote end of the connection.
74       The new channel gensio is in buf and must be cast.   Information  about
75       the channel will be passed in auxdata, see documentation on the partic‐
76       ular gensio for details.  If this returns an error (non-zero) the chan‐
77       nel  is shut down, though in the future specific error returns may have
78       different behavior.  You must return GE_NOTSUP (like you should for all
79       unhandled events) if you don't support this event.  All other error re‐
80       turns besides zero and GE_NOTSUP are reserved.
81
82
83   GENSIO_EVENT_SEND_BREAK
84       Got a request from the other end to send a  break.   Telnet  client  or
85       server.
86
87       Blocked if gensio read is disabled.
88
89   GENSIO_EVENT_AUTH_BEGIN
90       Authorization  has  begun,  the  username  and service is available but
91       nothing else.
92
93       There are a few special return values from this event:
94
95       GE_AUTHREJECT
96              - Fail the connection, but continue to go through  the  motions.
97              This  should  be  called  if the user was invalid or data wasn't
98              properly provided.
99
100       0      - authorization has succeeded.  No more  authentication  is  re‐
101              quired, but the protocol may still go through the motions of the
102              protocol.
103
104       GE_NOTSUP
105              - Just continue with authentication.
106
107       Any other error will terminate the connection, these  should  generally
108       be  things  like out of memory and such, NOT authentication failures of
109       any kind.
110
111       certauth only
112
113   GENSIO_EVENT_PRECERT_VERIFY
114       The connection has received a certificate but has not verified it  yet.
115       This  lets  the user modify the certificate authority based on certifi‐
116       cate information.
117
118       Return values are the same as GENSIO_EVENT_AUTH_BEGIN.
119
120       ssl and certauth
121
122   GENSIO_EVENT_POSTCERT_VERIFY
123       The connection has received a certificate and  has  verified  it.   The
124       verification may have failed.  This lets the user handle their own ver‐
125       ification override.  err will be one of the following:
126
127       0      on verification success.
128
129       GE_CERTNOTFOUND
130              if no certificate was found
131
132       GE_CERTREVOKED
133              if the if the certificate was revoked
134
135       GE_CERTEXPIRED
136              if the certificate has expired
137
138       GE_CERTINVALID
139              for other errors.
140
141       Any other error will terminate the connection, these  should  generally
142       be  things  like out of memory and such, NOT authentication failures of
143       any kind.
144
145       auxdata[0] will be an error string (or NULL if none  available).   Make
146       sure to check if auxdata is NULL before indexing auxdata[0].
147
148       Return values are:
149
150       0      - Authentication successed (even if an error was reported).
151
152       GE_NOTSUP
153              -  Continue with the authentication process.  Password authenti‐
154              cation may occur, for instance, if an error was reported.
155
156       GE_AUTHREJECT
157              - Fail the authentication. No more authentication will occur.
158
159       ssl and certauth
160
161   GENSIO_EVENT_PASSWORD_VERIFY
162       A password has been received from the remote end, it is passed in  buf.
163       The callee should validate it.  If doing 2-factor auth, you should also
164       fetch the 2-factor data with the GENSIO_CONTROL_2FA control and  handle
165       that here, too.  If this function is called, GENSIO_EVENT_2FA_VERIFY is
166       not called.  The length is passed in *buflen.  Note that the buf is nil
167       terminated one past the length.  Return values are:
168
169       0      - The password verification succeeds.
170
171       GE_NOTSUP
172              -  Fail  the validation, but the connection shutdown will depend
173              on the setting of allow-authfail.
174
175       GE_AUTHREJECT
176              - Reject the authorization for some other reason besides failing
177              validation.
178
179       Any  other  error will terminate the connection, these should generally
180       be things like out of memory and such, NOT authentication  failures  of
181       any kind.
182
183       certauth only
184
185   GENSIO_EVENT_REQUEST_PASSWORD
186       On  the  client  side of an authorization, the remote end has requested
187       that a password be sent.  buf points to a buffer of  *buflen  bytes  to
188       place  the  password in, the user should put the password there and up‐
189       date *buflen to the actual length.
190
191       Return 0 for success, or any other gensio error to  fail  the  password
192       fetch.
193
194   GENSIO_EVENT_REQUEST_2FA
195       On  the  client  side of an authorization, the remote end has requested
196       two-factor authentication data, but it has not been  supplied  already.
197       buf  points to a pointer to a buffer (unsigned char **) that you should
198       return.  It should  be  allocated  with  the  zalloc  function  of  the
199       os_functions  in  use.  *buflen is where to put the size of the buffer.
200       This buffer will be zeroed and freed when done.
201
202       Return 0 for success, or any other gensio error to fail the 2FA fetch.
203
204   GENSIO_EVENT_2FA_VERIFY
205       A 2-factor auth has been received from the remote  end  and  passed  as
206       part  of  the  password transfer.  This is only called if the login was
207       validated with a certificate, this is called to  handle  2-factor  auth
208       with  a certificate.  The 2fa data is passed in buf.  The callee should
209       validate it.  The length is passed in *buflen.  Note that  the  buf  is
210       nil terminated one past the length.  Return values are:
211
212       0      - The verification succeeds.
213
214       GE_NOTSUP
215              -  Fail  the validation, but the connection shutdown will depend
216              on the setting of allow-authfail.
217
218       GE_AUTHREJECT
219              - Reject the authorization for some other reason besides failing
220              validation.
221
222       Any  other  error will terminate the connection, these should generally
223       be things like out of memory and such, NOT authentication  failures  of
224       any kind.
225
226       certauth only
227
228   GENSIO_EVENT_PARMLOG
229       When parsing a gensio string, this will be called if the gensio detects
230       an error in the initial parsing  or  initial  configuration.   This  is
231       called  only  during  the  allocation ( str_to_gensio() or equivalent).
232       Logging this information will make it easier  for  users  to  find  out
233       what's wrong with their gensio strings.
234
235       The buf parameter contains a pointer to the following structure:
236
237       struct gensio_parmlog_data {
238           const char *log;
239           va_list args;
240       };
241
242       which can be printed with normal vprintf() and the like.
243
244   GENSIO_EVENT_WIN_SIZE
245       The  other  end  of  the  connection is reporting a window size change.
246       Currently only on telnet with RFC1073 enabled.
247
248   GENSIO_EVENT_LOG
249       Used to report general logs in gensios while processing.  Can be called
250       any time the gensio exists.
251
252       The buf parameter contains a pointer to the following structure:
253
254       struct gensio_log_data {
255           const char *log;
256           va_list args;
257       };
258
259       which can be printed with normal vprintf() and the like.
260
261
262   SERIAL PORT CONTROLS
263       These are controls for serial port settings.  These are received on the
264       server side only.  It should respond by setting the value (if  possible
265       and  the  value  isn't zero) and responding with the current value with
266       sergensio_xxx().
267
268       If the server receives a zero value for any of this, it should just re‐
269       port the value and not change anything.
270
271       GENSIO_EVENT_SER_BAUD
272       GENSIO_EVENT_SER_DATASIZE
273       GENSIO_EVENT_SER_PARITY
274       GENSIO_EVENT_SER_STOPBITS
275       GENSIO_EVENT_SER_FLOWCONTROL
276       GENSIO_EVENT_SER_IFLOWCONTROL
277       GENSIO_EVENT_SER_SBREAK
278       GENSIO_EVENT_SER_DTR
279       GENSIO_EVENT_SER_RTS
280
281       For baud, databits, and stopbits, the value is an integer with the num‐
282       ber.
283
284       Parity values can be:
285       GENSIO_SER_PARITY_NONE
286       GENSIO_SER_PARITY_ODD
287       GENSIO_SER_PARITY_EVEN
288       GENSIO_SER_PARITY_MARK
289       GENSIO_SER_PARITY_SPACE
290
291       Flow control values can be:
292       GENSIO_SER_FLOWCONTROL_NONE
293       GENSIO_SER_FLOWCONTROL_XON_XOFF
294       GENSIO_SER_FLOWCONTROL_RTS_CTS
295
296       Input flow control values can be:
297       GENSIO_SER_FLOWCONTROL_DCD
298       GENSIO_SER_FLOWCONTROL_DTR
299       GENSIO_SER_FLOWCONTROL_DSR
300
301       For values that are on/off (the rest), use the following:
302       GENSIO_SER_ON
303       GENSIO_SER_OFF
304
305
306   SIGNATURE
307       GENSIO_EVENT_SER_SIGNATURE is received on the server side only and is a
308       request  for the signature.  The server should respond by send the sig‐
309       nature with sergensio_signature().  No value is passed in this case.
310
311   STATE FUNCTIONS
312       GENSIO_EVENT_SER_MODEMSTATE_MASK
313       GENSIO_EVENT_SER_LINESTATE_MASK
314       These are received on the server side to request updating the  mask  of
315       reported  values.   The  server should respond by returning the current
316       mask with the sergensio_modemstate  or  sergensio_linestate  functions.
317       The server need not handle all the bits requested by the user.
318
319       GENSIO_EVENT_SER_MODEMSTATE
320       GENSIO_EVENT_SER_LINESTATE
321
322       On  the  client side, these are reporting current modemstate and lines‐
323       tate changes as an unsigned integer.  See  sergensio_modemstate(3)  and
324       sergensio_linestate(3) for a meaning of the bits in the integer.
325
326   OTHER SERIAL PORT CONTROLS
327       These are server-only, these are received requesting the various opera‐
328       tions.  The server should do them, but no response  is  required.   You
329       may  notice  that  break is not here, break is handled through the GEN‐
330       SIO_EVENT_SEND_BREAK event.
331
332       GENSIO_EVENT_SER_FLOW_STATE
333       GENSIO_EVENT_SER_FLUSH
334
335   SYNC
336       GENSIO_EVENT_SER_SYNC is a special operation that comes in when  a  TCP
337       sync  event  is  received.  It may be received on both sides.  A server
338       should send a break.  The client can do whatever it wants with the  in‐
339       formation, that is not defined by the RFC2217 specification.
340

OTHER EVENTS

342       sergensio  gensios have a set of other events, see sergensio(5) for de‐
343       tails.  Other gensio that are not part of the gensio library proper may
344       have their own events, too.
345

RETURN VALUES

347       See  the  individual  events  for  the values you should return.  If an
348       event is not handled by the event  handler,  the  handler  must  return
349       GE_NOTSUP,   except   in   the   case  of  GENSIO_EVENT_READ  and  GEN‐
350       SIO_EVENT_WRITE_READY which must be handled.
351

SEE ALSO

353       gensio_set_callback(3), str_to_gensio_child(3), gensio_open_channel(3),
354       gensio_open_channel_s(3), gensio_acc_str_to_gensio(3), str_to_gensio(3)
355       sergensio(5), gensio_err(3)
356
357
358
359                                  21 Feb 2019                  gensio_event(3)
Impressum