1gensio_event(3) Library Functions Manual gensio_event(3)
2
6 gensio_event - Event handler for events from a gensio
7
9 #include <gensio/gensio.h>
10 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
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 The use of the various parameters depends on the particular event. The
22 parameters that don't vary are:
23 io - The gensio the event is being reported for.
25 user_data
27 - The user_data supplied when the event handler was registered.
28 event - The particular event being reported.
30 Events follow.
32 GENSIO_EVENT_READ
34 Called when data is read from the I/O device.
35 If err is zero, buf points to a data buffer and buflen is the number of
37 bytes available.
38 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 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 Note that only one read callback is allowed to run at a time on a gen‐
50 sio.
51 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 You should always return zero, it used to not matter, but it does now.
57 GENSIO_EVENT_WRITE_READY
59 Called when data can be written to the I/O device.
60 Note that only one write callback is allowed to run at a time on a gen‐
62 sio.
63 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 You should always return zero, it used to not matter, but it does now.
71 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 GENSIO_EVENT_SEND_BREAK
84 Got a request from the other end to send a break. Telnet client or
85 server.
86 Blocked if gensio read is disabled.
88 GENSIO_EVENT_AUTH_BEGIN
90 Authorization has begun, the username and service is available but
91 nothing else.
92 There are a few special return values from this event:
94 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 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 GE_NOTSUP
105 - Just continue with authentication.
106 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 certauth only
112 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 Return values are the same as GENSIO_EVENT_AUTH_BEGIN.
119 ssl and certauth
121 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 0 on verification success.
128 GE_CERTNOTFOUND
130 if no certificate was found
131 GE_CERTREVOKED
133 if the if the certificate was revoked
134 GE_CERTEXPIRED
136 if the certificate has expired
137 GE_CERTINVALID
139 for other errors.
140 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 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 Return values are:
149 0 - Authentication successed (even if an error was reported).
151 GE_NOTSUP
153 - Continue with the authentication process. Password authenti‐
154 cation may occur, for instance, if an error was reported.
155 GE_AUTHREJECT
157 - Fail the authentication. No more authentication will occur.
158 ssl and certauth
160 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 0 - The password verification succeeds.
170 GE_NOTSUP
172 - Fail the validation, but the connection shutdown will depend
173 on the setting of allow-authfail.
174 GE_AUTHREJECT
176 - Reject the authorization for some other reason besides failing
177 validation.
178 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 certauth only
184 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 Return 0 for success, or any other gensio error to fail the password
192 fetch.
193 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 Return 0 for success, or any other gensio error to fail the 2FA fetch.
203 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 0 - The verification succeeds.
213 GE_NOTSUP
215 - Fail the validation, but the connection shutdown will depend
216 on the setting of allow-authfail.
217 GE_AUTHREJECT
219 - Reject the authorization for some other reason besides failing
220 validation.
221 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 certauth only
227 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 The buf parameter contains a pointer to the following structure:
236 struct gensio_parmlog_data {
238 const char *log;
239 va_list args;
240 };
241 which can be printed with normal vprintf() and the like.
243 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 GENSIO_EVENT_LOG
249 Used to report general logs in gensios while processing. Can be called
250 any time the gensio exists.
251 The buf parameter contains a pointer to the following structure:
253 struct gensio_log_data {
255 const char *log;
256 va_list args;
257 };
258 which can be printed with normal vprintf() and the like.
260 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 If the server receives a zero value for any of this, it should just re‐
269 port the value and not change anything.
270 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 For baud, databits, and stopbits, the value is an integer with the num‐
282 ber.
283 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 Flow control values can be:
292 GENSIO_SER_FLOWCONTROL_NONE
293 GENSIO_SER_FLOWCONTROL_XON_XOFF
294 GENSIO_SER_FLOWCONTROL_RTS_CTS
295 Input flow control values can be:
297 GENSIO_SER_FLOWCONTROL_DCD
298 GENSIO_SER_FLOWCONTROL_DTR
299 GENSIO_SER_FLOWCONTROL_DSR
300 For values that are on/off (the rest), use the following:
302 GENSIO_SER_ON
303 GENSIO_SER_OFF
304 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 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 GENSIO_EVENT_SER_MODEMSTATE
320 GENSIO_EVENT_SER_LINESTATE
321 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 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 GENSIO_EVENT_SER_FLOW_STATE
333 GENSIO_EVENT_SER_FLUSH
334 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
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
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
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 21 Feb 2019 gensio_event(3)