contrib/wpa_supplicant-0.5.8/eloop.h

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