contrib/wpa_supplicant-0.4.9/eloop.h

   1 /*
   2  * Event loop
   3  * Copyright (c) 2002-2005, Jouni Malinen <jkmaline@cc.hut.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_init() - Initialize global event loop data
  33  * @user_data: Pointer to global data passed as eloop_ctx to signal handlers
  34  *
  35  * This function must be called before any other eloop_* function. user_data
  36  * can be used to configure a global (to the process) pointer that will be
  37  * passed as eloop_ctx parameter to signal handlers.
  38  */
  39 void eloop_init(void *user_data);
  40
  41 /**
  42  * eloop_register_read_sock - Register handler for read events
  43  * @sock: File descriptor number for the socket
  44  * @handler: Callback function to be called when data is available for reading
  45  * @eloop_data: Callback context data (eloop_ctx)
  46  * @user_data: Callback context data (sock_ctx)
  47  * Returns: 0 on success, -1 on failure
  48  *
  49  * Register a read socket notifier for the given file descriptor. The handler
  50  * function will be called whenever data is available for reading from the
  51  * socket.
  52  */
  53 int eloop_register_read_sock(int sock,
  54                              void (*handler)(int sock, void *eloop_ctx,
  55                                              void *sock_ctx),
  56                              void *eloop_data, void *user_data);
  57
  58 /**
  59  * eloop_unregister_read_sock - Unregister handler for read events
  60  * @sock: File descriptor number for the socket
  61  *
  62  * Unregister a read socket notifier that was previously registered with
  63  * eloop_register_read_sock().
  64  */
  65 void eloop_unregister_read_sock(int sock);
  66
  67 /**
  68  * eloop_register_timeout - Register timeout
  69  * @secs: Number of seconds to the timeout
  70  * @usecs: Number of microseconds to the timeout
  71  * @handler: Callback function to be called when timeout occurs
  72  * @eloop_data: Callback context data (eloop_ctx)
  73  * @user_data: Callback context data (sock_ctx)
  74  * Returns: 0 on success, -1 on failure
  75  *
  76  * Register a timeout that will cause the handler function to be called after
  77  * given time.
  78  */
  79 int eloop_register_timeout(unsigned int secs, unsigned int usecs,
  80                            void (*handler)(void *eloop_ctx, void *timeout_ctx),
  81                            void *eloop_data, void *user_data);
  82
  83 /**
  84  * eloop_cancel_timeout - Cancel timeouts
  85  * @handler: Matching callback function
  86  * @eloop_data: Matching eloop_data or %ELOOP_ALL_CTX to match all
  87  * @user_data: Matching user_data or %ELOOP_ALL_CTX to match all
  88  * Returns: Number of cancelled timeouts
  89  *
  90  * Cancel matching <handler,eloop_data,user_data> timeouts registered with
  91  * eloop_register_timeout(). ELOOP_ALL_CTX can be used as a wildcard for
  92  * cancelling all timeouts regardless of eloop_data/user_data.
  93  */
  94 int eloop_cancel_timeout(void (*handler)(void *eloop_ctx, void *sock_ctx),
  95                          void *eloop_data, void *user_data);
  96
  97 /**
  98  * eloop_register_signal - Register handler for signals
  99  * @sig: Signal number (e.g., SIGHUP)
 100  * @handler: Callback function to be called when the signal is received
 101  * @user_data: Callback context data (signal_ctx)
 102  * Returns: 0 on success, -1 on failure
 103  *
 104  * Register a callback function that will be called when a signal is received.
 105  * The calback function is actually called only after the system signal handler
 106  * has returned. This means that the normal limits for sighandlers (i.e., only
 107  * "safe functions" allowed) do not apply for the registered callback.
 108  *
 109  * Signals are 'global' events and there is no local eloop_data pointer like
 110  * with other handlers. The global user_data pointer registered with
 111  * eloop_init() will be used as eloop_ctx for signal handlers.
 112  */
 113 int eloop_register_signal(int sig,
 114                           void (*handler)(int sig, void *eloop_ctx,
 115                                           void *signal_ctx),
 116                           void *user_data);
 117
 118 /**
 119  * eloop_run - Start the event loop
 120  *
 121  * Start the event loop and continue running as long as there are any
 122  * registered event handlers. This function is run after event loop has been
 123  * initialized with event_init() and one or more events have been registered.
 124  */
 125 void eloop_run(void);
 126
 127 /**
 128  * eloop_terminate - Terminate event loop
 129  *
 130  * Terminate event loop even if there are registered events. This can be used
 131  * to request the program to be terminated cleanly.
 132  */
 133 void eloop_terminate(void);
 134
 135 /**
 136  * eloop_destroy - Free any resources allocated for the event loop
 137  *
 138  * After calling eloop_destroy(), other eloop_* functions must not be called
 139  * before re-running eloop_init().
 140  */
 141 void eloop_destroy(void);
 142
 143 /**
 144  * eloop_terminated - Check whether event loop has been terminated
 145  * Returns: 1 = event loop terminate, 0 = event loop still running
 146  *
 147  * This function can be used to check whether eloop_terminate() has been called
 148  * to request termination of the event loop. This is normally used to abort
 149  * operations that may still be queued to be run when eloop_terminate() was
 150  * called.
 151  */
 152 int eloop_terminated(void);
 153
 154 #endif /* ELOOP_H */