Disconnect hostapd from building in base
[dragonfly.git] / contrib / hostapd / src / utils / eloop.h
CommitLineData
ebfa2275
SZ
1/*
2 * Event loop
3 * Copyright (c) 2002-2006, Jouni Malinen <j@w1.fi>
4 *
4781064b
JM
5 * This software may be distributed under the terms of the BSD license.
6 * See README for more details.
ebfa2275
SZ
7 *
8 * This file defines an event loop interface that supports processing events
9 * from registered timeouts (i.e., do something after N seconds), sockets
10 * (e.g., a new packet available for reading), and signals. eloop.c is an
11 * implementation of this interface using select() and sockets. This is
12 * suitable for most UNIX/POSIX systems. When porting to other operating
13 * systems, it may be necessary to replace that implementation with OS specific
14 * mechanisms.
15 */
16
17#ifndef ELOOP_H
18#define ELOOP_H
19
20/**
21 * ELOOP_ALL_CTX - eloop_cancel_timeout() magic number to match all timeouts
22 */
23#define ELOOP_ALL_CTX (void *) -1
24
25/**
26 * eloop_event_type - eloop socket event type for eloop_register_sock()
27 * @EVENT_TYPE_READ: Socket has data available for reading
28 * @EVENT_TYPE_WRITE: Socket has room for new data to be written
29 * @EVENT_TYPE_EXCEPTION: An exception has been reported
30 */
31typedef enum {
32 EVENT_TYPE_READ = 0,
33 EVENT_TYPE_WRITE,
34 EVENT_TYPE_EXCEPTION
35} eloop_event_type;
36
37/**
38 * eloop_sock_handler - eloop socket event callback type
39 * @sock: File descriptor number for the socket
40 * @eloop_ctx: Registered callback context data (eloop_data)
41 * @sock_ctx: Registered callback context data (user_data)
42 */
43typedef void (*eloop_sock_handler)(int sock, void *eloop_ctx, void *sock_ctx);
44
45/**
46 * eloop_event_handler - eloop generic event callback type
47 * @eloop_ctx: Registered callback context data (eloop_data)
48 * @sock_ctx: Registered callback context data (user_data)
49 */
50typedef void (*eloop_event_handler)(void *eloop_data, void *user_ctx);
51
52/**
53 * eloop_timeout_handler - eloop timeout event callback type
54 * @eloop_ctx: Registered callback context data (eloop_data)
55 * @sock_ctx: Registered callback context data (user_data)
56 */
57typedef void (*eloop_timeout_handler)(void *eloop_data, void *user_ctx);
58
59/**
60 * eloop_signal_handler - eloop signal event callback type
61 * @sig: Signal number
ebfa2275
SZ
62 * @signal_ctx: Registered callback context data (user_data from
63 * eloop_register_signal(), eloop_register_signal_terminate(), or
64 * eloop_register_signal_reconfig() call)
65 */
4781064b 66typedef void (*eloop_signal_handler)(int sig, void *signal_ctx);
ebfa2275
SZ
67
68/**
69 * eloop_init() - Initialize global event loop data
ebfa2275
SZ
70 * Returns: 0 on success, -1 on failure
71 *
4781064b 72 * This function must be called before any other eloop_* function.
ebfa2275 73 */
4781064b 74int eloop_init(void);
ebfa2275
SZ
75
76/**
77 * eloop_register_read_sock - Register handler for read events
78 * @sock: File descriptor number for the socket
79 * @handler: Callback function to be called when data is available for reading
80 * @eloop_data: Callback context data (eloop_ctx)
81 * @user_data: Callback context data (sock_ctx)
82 * Returns: 0 on success, -1 on failure
83 *
84 * Register a read socket notifier for the given file descriptor. The handler
85 * function will be called whenever data is available for reading from the
86 * socket. The handler function is responsible for clearing the event after
87 * having processed it in order to avoid eloop from calling the handler again
88 * for the same event.
89 */
90int eloop_register_read_sock(int sock, eloop_sock_handler handler,
91 void *eloop_data, void *user_data);
92
93/**
94 * eloop_unregister_read_sock - Unregister handler for read events
95 * @sock: File descriptor number for the socket
96 *
97 * Unregister a read socket notifier that was previously registered with
98 * eloop_register_read_sock().
99 */
100void eloop_unregister_read_sock(int sock);
101
102/**
103 * eloop_register_sock - Register handler for socket events
104 * @sock: File descriptor number for the socket
105 * @type: Type of event to wait for
106 * @handler: Callback function to be called when the event is triggered
107 * @eloop_data: Callback context data (eloop_ctx)
108 * @user_data: Callback context data (sock_ctx)
109 * Returns: 0 on success, -1 on failure
110 *
111 * Register an event notifier for the given socket's file descriptor. The
112 * handler function will be called whenever the that event is triggered for the
113 * socket. The handler function is responsible for clearing the event after
114 * having processed it in order to avoid eloop from calling the handler again
115 * for the same event.
116 */
117int eloop_register_sock(int sock, eloop_event_type type,
118 eloop_sock_handler handler,
119 void *eloop_data, void *user_data);
120
121/**
122 * eloop_unregister_sock - Unregister handler for socket events
123 * @sock: File descriptor number for the socket
124 * @type: Type of event for which sock was registered
125 *
126 * Unregister a socket event notifier that was previously registered with
127 * eloop_register_sock().
128 */
129void eloop_unregister_sock(int sock, eloop_event_type type);
130
131/**
132 * eloop_register_event - Register handler for generic events
133 * @event: Event to wait (eloop implementation specific)
134 * @event_size: Size of event data
135 * @handler: Callback function to be called when event is triggered
136 * @eloop_data: Callback context data (eloop_data)
137 * @user_data: Callback context data (user_data)
138 * Returns: 0 on success, -1 on failure
139 *
140 * Register an event handler for the given event. This function is used to
4781064b 141 * register eloop implementation specific events which are mainly targeted for
ebfa2275
SZ
142 * operating system specific code (driver interface and l2_packet) since the
143 * portable code will not be able to use such an OS-specific call. The handler
144 * function will be called whenever the event is triggered. The handler
145 * function is responsible for clearing the event after having processed it in
146 * order to avoid eloop from calling the handler again for the same event.
147 *
148 * In case of Windows implementation (eloop_win.c), event pointer is of HANDLE
149 * type, i.e., void*. The callers are likely to have 'HANDLE h' type variable,
150 * and they would call this function with eloop_register_event(h, sizeof(h),
151 * ...).
152 */
153int eloop_register_event(void *event, size_t event_size,
154 eloop_event_handler handler,
155 void *eloop_data, void *user_data);
156
157/**
158 * eloop_unregister_event - Unregister handler for a generic event
159 * @event: Event to cancel (eloop implementation specific)
160 * @event_size: Size of event data
161 *
162 * Unregister a generic event notifier that was previously registered with
163 * eloop_register_event().
164 */
165void eloop_unregister_event(void *event, size_t event_size);
166
167/**
168 * eloop_register_timeout - Register timeout
169 * @secs: Number of seconds to the timeout
170 * @usecs: Number of microseconds to the timeout
171 * @handler: Callback function to be called when timeout occurs
172 * @eloop_data: Callback context data (eloop_ctx)
173 * @user_data: Callback context data (sock_ctx)
174 * Returns: 0 on success, -1 on failure
175 *
176 * Register a timeout that will cause the handler function to be called after
177 * given time.
178 */
179int eloop_register_timeout(unsigned int secs, unsigned int usecs,
180 eloop_timeout_handler handler,
181 void *eloop_data, void *user_data);
182
183/**
184 * eloop_cancel_timeout - Cancel timeouts
185 * @handler: Matching callback function
186 * @eloop_data: Matching eloop_data or %ELOOP_ALL_CTX to match all
187 * @user_data: Matching user_data or %ELOOP_ALL_CTX to match all
188 * Returns: Number of cancelled timeouts
189 *
190 * Cancel matching <handler,eloop_data,user_data> timeouts registered with
191 * eloop_register_timeout(). ELOOP_ALL_CTX can be used as a wildcard for
192 * cancelling all timeouts regardless of eloop_data/user_data.
193 */
194int eloop_cancel_timeout(eloop_timeout_handler handler,
195 void *eloop_data, void *user_data);
196
4781064b
JM
197/**
198 * eloop_cancel_timeout_one - Cancel a single timeout
199 * @handler: Matching callback function
200 * @eloop_data: Matching eloop_data
201 * @user_data: Matching user_data
202 * @remaining: Time left on the cancelled timer
203 * Returns: Number of cancelled timeouts
204 *
205 * Cancel matching <handler,eloop_data,user_data> timeout registered with
206 * eloop_register_timeout() and return the remaining time left.
207 */
208int eloop_cancel_timeout_one(eloop_timeout_handler handler,
209 void *eloop_data, void *user_data,
210 struct os_reltime *remaining);
211
a875087d
JL
212/**
213 * eloop_is_timeout_registered - Check if a timeout is already registered
214 * @handler: Matching callback function
215 * @eloop_data: Matching eloop_data
216 * @user_data: Matching user_data
217 * Returns: 1 if the timeout is registered, 0 if the timeout is not registered
218 *
219 * Determine if a matching <handler,eloop_data,user_data> timeout is registered
220 * with eloop_register_timeout().
221 */
222int eloop_is_timeout_registered(eloop_timeout_handler handler,
223 void *eloop_data, void *user_data);
224
4781064b
JM
225/**
226 * eloop_deplete_timeout - Deplete a timeout that is already registered
227 * @req_secs: Requested number of seconds to the timeout
228 * @req_usecs: Requested number of microseconds to the timeout
229 * @handler: Matching callback function
230 * @eloop_data: Matching eloop_data
231 * @user_data: Matching user_data
232 * Returns: 1 if the timeout is depleted, 0 if no change is made, -1 if no
233 * timeout matched
234 *
235 * Find a registered matching <handler,eloop_data,user_data> timeout. If found,
236 * deplete the timeout if remaining time is more than the requested time.
237 */
238int eloop_deplete_timeout(unsigned int req_secs, unsigned int req_usecs,
239 eloop_timeout_handler handler, void *eloop_data,
240 void *user_data);
241
242/**
243 * eloop_replenish_timeout - Replenish a timeout that is already registered
244 * @req_secs: Requested number of seconds to the timeout
245 * @req_usecs: Requested number of microseconds to the timeout
246 * @handler: Matching callback function
247 * @eloop_data: Matching eloop_data
248 * @user_data: Matching user_data
249 * Returns: 1 if the timeout is replenished, 0 if no change is made, -1 if no
250 * timeout matched
251 *
252 * Find a registered matching <handler,eloop_data,user_data> timeout. If found,
253 * replenish the timeout if remaining time is less than the requested time.
254 */
255int eloop_replenish_timeout(unsigned int req_secs, unsigned int req_usecs,
256 eloop_timeout_handler handler, void *eloop_data,
257 void *user_data);
258
ebfa2275
SZ
259/**
260 * eloop_register_signal - Register handler for signals
261 * @sig: Signal number (e.g., SIGHUP)
262 * @handler: Callback function to be called when the signal is received
263 * @user_data: Callback context data (signal_ctx)
264 * Returns: 0 on success, -1 on failure
265 *
266 * Register a callback function that will be called when a signal is received.
267 * The callback function is actually called only after the system signal
268 * handler has returned. This means that the normal limits for sighandlers
269 * (i.e., only "safe functions" allowed) do not apply for the registered
270 * callback.
ebfa2275
SZ
271 */
272int eloop_register_signal(int sig, eloop_signal_handler handler,
273 void *user_data);
274
275/**
276 * eloop_register_signal_terminate - Register handler for terminate signals
277 * @handler: Callback function to be called when the signal is received
278 * @user_data: Callback context data (signal_ctx)
279 * Returns: 0 on success, -1 on failure
280 *
281 * Register a callback function that will be called when a process termination
282 * signal is received. The callback function is actually called only after the
283 * system signal handler has returned. This means that the normal limits for
284 * sighandlers (i.e., only "safe functions" allowed) do not apply for the
285 * registered callback.
286 *
ebfa2275
SZ
287 * This function is a more portable version of eloop_register_signal() since
288 * the knowledge of exact details of the signals is hidden in eloop
289 * implementation. In case of operating systems using signal(), this function
290 * registers handlers for SIGINT and SIGTERM.
291 */
292int eloop_register_signal_terminate(eloop_signal_handler handler,
293 void *user_data);
294
295/**
296 * eloop_register_signal_reconfig - Register handler for reconfig signals
297 * @handler: Callback function to be called when the signal is received
298 * @user_data: Callback context data (signal_ctx)
299 * Returns: 0 on success, -1 on failure
300 *
301 * Register a callback function that will be called when a reconfiguration /
302 * hangup signal is received. The callback function is actually called only
303 * after the system signal handler has returned. This means that the normal
304 * limits for sighandlers (i.e., only "safe functions" allowed) do not apply
305 * for the registered callback.
306 *
ebfa2275
SZ
307 * This function is a more portable version of eloop_register_signal() since
308 * the knowledge of exact details of the signals is hidden in eloop
309 * implementation. In case of operating systems using signal(), this function
310 * registers a handler for SIGHUP.
311 */
312int eloop_register_signal_reconfig(eloop_signal_handler handler,
313 void *user_data);
314
315/**
316 * eloop_run - Start the event loop
317 *
318 * Start the event loop and continue running as long as there are any
319 * registered event handlers. This function is run after event loop has been
320 * initialized with event_init() and one or more events have been registered.
321 */
322void eloop_run(void);
323
324/**
325 * eloop_terminate - Terminate event loop
326 *
327 * Terminate event loop even if there are registered events. This can be used
328 * to request the program to be terminated cleanly.
329 */
330void eloop_terminate(void);
331
332/**
333 * eloop_destroy - Free any resources allocated for the event loop
334 *
335 * After calling eloop_destroy(), other eloop_* functions must not be called
336 * before re-running eloop_init().
337 */
338void eloop_destroy(void);
339
340/**
341 * eloop_terminated - Check whether event loop has been terminated
342 * Returns: 1 = event loop terminate, 0 = event loop still running
343 *
344 * This function can be used to check whether eloop_terminate() has been called
345 * to request termination of the event loop. This is normally used to abort
346 * operations that may still be queued to be run when eloop_terminate() was
347 * called.
348 */
349int eloop_terminated(void);
350
351/**
352 * eloop_wait_for_read_sock - Wait for a single reader
353 * @sock: File descriptor number for the socket
354 *
355 * Do a blocking wait for a single read socket.
356 */
357void eloop_wait_for_read_sock(int sock);
358
ebfa2275 359#endif /* ELOOP_H */