Home | History | Annotate | Download | only in wpa_supplicant
      1 /*
      2  * Event loop
      3  * Copyright (c) 2002-2006, Jouni Malinen <j (at) 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_is_timeout_registered - Check if a timeout is already registered
    211  * @handler: Matching callback function
    212  * @eloop_data: Matching eloop_data
    213  * @user_data: Matching user_data
    214  * Returns: 1 if the timeout is registered, 0 if the timeout is not registered
    215  *
    216  * Determine if a matching <handler,eloop_data,user_data> timeout is registered
    217  * with eloop_register_timeout().
    218  */
    219 int eloop_is_timeout_registered(eloop_timeout_handler handler,
    220 				void *eloop_data, void *user_data);
    221 
    222 /**
    223  * eloop_register_signal - Register handler for signals
    224  * @sig: Signal number (e.g., SIGHUP)
    225  * @handler: Callback function to be called when the signal is received
    226  * @user_data: Callback context data (signal_ctx)
    227  * Returns: 0 on success, -1 on failure
    228  *
    229  * Register a callback function that will be called when a signal is received.
    230  * The callback function is actually called only after the system signal
    231  * handler has returned. This means that the normal limits for sighandlers
    232  * (i.e., only "safe functions" allowed) do not apply for the registered
    233  * callback.
    234  *
    235  * Signals are 'global' events and there is no local eloop_data pointer like
    236  * with other handlers. The global user_data pointer registered with
    237  * eloop_init() will be used as eloop_ctx for signal handlers.
    238  */
    239 int eloop_register_signal(int sig, eloop_signal_handler handler,
    240 			  void *user_data);
    241 
    242 /**
    243  * eloop_register_signal_terminate - Register handler for terminate signals
    244  * @handler: Callback function to be called when the signal is received
    245  * @user_data: Callback context data (signal_ctx)
    246  * Returns: 0 on success, -1 on failure
    247  *
    248  * Register a callback function that will be called when a process termination
    249  * signal is received. The callback function is actually called only after the
    250  * system signal handler has returned. This means that the normal limits for
    251  * sighandlers (i.e., only "safe functions" allowed) do not apply for the
    252  * registered callback.
    253  *
    254  * Signals are 'global' events and there is no local eloop_data pointer like
    255  * with other handlers. The global user_data pointer registered with
    256  * eloop_init() will be used as eloop_ctx for signal handlers.
    257  *
    258  * This function is a more portable version of eloop_register_signal() since
    259  * the knowledge of exact details of the signals is hidden in eloop
    260  * implementation. In case of operating systems using signal(), this function
    261  * registers handlers for SIGINT and SIGTERM.
    262  */
    263 int eloop_register_signal_terminate(eloop_signal_handler handler,
    264 				    void *user_data);
    265 
    266 /**
    267  * eloop_register_signal_reconfig - Register handler for reconfig signals
    268  * @handler: Callback function to be called when the signal is received
    269  * @user_data: Callback context data (signal_ctx)
    270  * Returns: 0 on success, -1 on failure
    271  *
    272  * Register a callback function that will be called when a reconfiguration /
    273  * hangup signal is received. The callback function is actually called only
    274  * after the system signal handler has returned. This means that the normal
    275  * limits for sighandlers (i.e., only "safe functions" allowed) do not apply
    276  * for the registered callback.
    277  *
    278  * Signals are 'global' events and there is no local eloop_data pointer like
    279  * with other handlers. The global user_data pointer registered with
    280  * eloop_init() will be used as eloop_ctx for signal handlers.
    281  *
    282  * This function is a more portable version of eloop_register_signal() since
    283  * the knowledge of exact details of the signals is hidden in eloop
    284  * implementation. In case of operating systems using signal(), this function
    285  * registers a handler for SIGHUP.
    286  */
    287 int eloop_register_signal_reconfig(eloop_signal_handler handler,
    288 				   void *user_data);
    289 
    290 /**
    291  * eloop_run - Start the event loop
    292  *
    293  * Start the event loop and continue running as long as there are any
    294  * registered event handlers. This function is run after event loop has been
    295  * initialized with event_init() and one or more events have been registered.
    296  */
    297 void eloop_run(void);
    298 
    299 /**
    300  * eloop_terminate - Terminate event loop
    301  *
    302  * Terminate event loop even if there are registered events. This can be used
    303  * to request the program to be terminated cleanly.
    304  */
    305 void eloop_terminate(void);
    306 
    307 /**
    308  * eloop_destroy - Free any resources allocated for the event loop
    309  *
    310  * After calling eloop_destroy(), other eloop_* functions must not be called
    311  * before re-running eloop_init().
    312  */
    313 void eloop_destroy(void);
    314 
    315 /**
    316  * eloop_terminated - Check whether event loop has been terminated
    317  * Returns: 1 = event loop terminate, 0 = event loop still running
    318  *
    319  * This function can be used to check whether eloop_terminate() has been called
    320  * to request termination of the event loop. This is normally used to abort
    321  * operations that may still be queued to be run when eloop_terminate() was
    322  * called.
    323  */
    324 int eloop_terminated(void);
    325 
    326 /**
    327  * eloop_wait_for_read_sock - Wait for a single reader
    328  * @sock: File descriptor number for the socket
    329  *
    330  * Do a blocking wait for a single read socket.
    331  */
    332 void eloop_wait_for_read_sock(int sock);
    333 
    334 /**
    335  * eloop_get_user_data - Get global user data
    336  * Returns: user_data pointer that was registered with eloop_init()
    337  */
    338 void * eloop_get_user_data(void);
    339 
    340 #endif /* ELOOP_H */
    341