src/charon/bus/bus.h

   1 /**
   2  * @file bus.h
   3  *
   4  * @brief Interface of bus_t.
   5  *
   6  */
   7
   8 /*
   9  * Copyright (C) 2006 Martin Willi
  10  * Hochschule fuer Technik Rapperswil
  11  *
  12  * This program is free software; you can redistribute it and/or modify it
  13  * under the terms of the GNU General Public License as published by the
  14  * Free Software Foundation; either version 2 of the License, or (at your
  15  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  16  *
  17  * This program is distributed in the hope that it will be useful, but
  18  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  19  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  20  * for more details.
  21  */
  22
  23 #ifndef BUS_H_
  24 #define BUS_H_
  25
  26 typedef enum signal_t signal_t;
  27 typedef enum level_t level_t;
  28 typedef struct bus_listener_t bus_listener_t;
  29 typedef struct bus_t bus_t;
  30
  31 #include <stdarg.h>
  32
  33 #include <sa/ike_sa.h>
  34 #include <sa/child_sa.h>
  35
  36
  37 /**
  38  * @brief signals emitted by the daemon.
  39  *
  40  * Signaling is for different purporses. First, it allows debugging via
  41  * "debugging signal messages", sencondly, it allows to follow certain
  42  * mechanisms currently going on in the daemon. As we are multithreaded,
  43  * and of multiple transactions are involved, it's not possible to follow
  44  * one connection setup without further infrastructure. These infrastructure
  45  * is provided by the bus and the signals the daemon emits to the bus.
  46  *
  47  * There are different scenarios to follow these signals, but all have
  48  * the same scheme. First, a START signal is emitted to indicate the daemon
  49  * has started to
  50  *
  51  * @ingroup bus
  52  */
  53 enum signal_t {
  54         /** pseudo signal, representing any other signal */
  55         SIG_ANY,
  56
  57         /** debugging message from daemon main loop */
  58         DBG_DMN,
  59         /** debugging message from IKE_SA_MANAGER */
  60         DBG_MGR,
  61         /** debugging message from an IKE_SA */
  62         DBG_IKE,
  63         /** debugging message from a CHILD_SA */
  64         DBG_CHD,
  65         /** debugging message from job processing */
  66         DBG_JOB,
  67         /** debugging message from configuration backends */
  68         DBG_CFG,
  69         /** debugging message from kernel interface */
  70         DBG_KNL,
  71         /** debugging message from networking */
  72         DBG_NET,
  73         /** debugging message from message encoding/decoding */
  74         DBG_ENC,
  75         /** debugging message from libstrongswan via logging hook */
  76         DBG_LIB,
  77
  78         /** number of debug signals */
  79         DBG_MAX,
  80
  81         /** signals for IKE_SA establishment */
  82         IKE_UP_START,
  83         IKE_UP_SUCCESS,
  84         IKE_UP_FAILED,
  85
  86         /** signals for IKE_SA delete */
  87         IKE_DOWN_START,
  88         IKE_DOWN_SUCCESS,
  89         IKE_DOWN_FAILED,
  90
  91         /** signals for IKE_SA rekeying */
  92         IKE_REKEY_START,
  93         IKE_REKEY_SUCCESS,
  94         IKE_REKEY_FAILED,
  95
  96         /** signals for CHILD_SA establishment */
  97         CHILD_UP_START,
  98         CHILD_UP_SUCCESS,
  99         CHILD_UP_FAILED,
 100
 101         /** signals for CHILD_SA delete */
 102         CHILD_DOWN_START,
 103         CHILD_DOWN_SUCCESS,
 104         CHILD_DOWN_FAILED,
 105
 106         /** signals for CHILD_SA rekeying */
 107         CHILD_REKEY_START,
 108         CHILD_REKEY_SUCCESS,
 109         CHILD_REKEY_FAILED,
 110
 111         /** signals for CHILD_SA routing */
 112         CHILD_ROUTE_START,
 113         CHILD_ROUTE_SUCCESS,
 114         CHILD_ROUTE_FAILED,
 115
 116         /** signals for CHILD_SA routing */
 117         CHILD_UNROUTE_START,
 118         CHILD_UNROUTE_SUCCESS,
 119         CHILD_UNROUTE_FAILED,
 120
 121         SIG_MAX
 122 };
 123
 124 /**
 125  * short names of signals using 3 chars
 126  */
 127 extern enum_name_t *signal_names;
 128
 129 /**
 130  * Signal levels used to control output verbosity.
 131  */
 132 enum level_t {
 133         /** numerical levels from 0 to 4 */
 134         LEVEL_0 = 0,
 135         LEVEL_1 = 1,
 136         LEVEL_2 = 2,
 137         LEVEL_3 = 3,
 138         LEVEL_4 = 4,
 139         /** absolutely silent, no signal is emitted with this level */
 140         LEVEL_SILENT = -1,
 141         /** alias for numberical levels */
 142         LEVEL_AUDIT = LEVEL_0,
 143         LEVEL_CTRL = LEVEL_1,
 144         LEVEL_CTRLMORE = LEVEL_2,
 145         LEVEL_RAW = LEVEL_3,
 146         LEVEL_PRIVATE = LEVEL_4,
 147 };
 148
 149 #ifndef DEBUG_LEVEL
 150 # define DEBUG_LEVEL 4
 151 #endif /* DEBUG_LEVEL */
 152
 153 #if DEBUG_LEVEL >= 1
 154 /**
 155  * @brief Log a debug message via the signal bus.
 156  *
 157  * @param signal        signal_t signal description
 158  * @param format        printf() style format string
 159  * @param ...           printf() style agument list
 160  */
 161 # define DBG1(sig, format, ...) charon->bus->signal(charon->bus, sig, LEVEL_1, format, ##__VA_ARGS__)
 162 #endif /* DEBUG_LEVEL */
 163 #if DEBUG_LEVEL >= 2
 164 #define DBG2(sig, format, ...) charon->bus->signal(charon->bus, sig, LEVEL_2, format, ##__VA_ARGS__)
 165 #endif /* DEBUG_LEVEL */
 166 #if DEBUG_LEVEL >= 3
 167 #define DBG3(sig, format, ...) charon->bus->signal(charon->bus, sig, LEVEL_3, format, ##__VA_ARGS__)
 168 #endif /* DEBUG_LEVEL */
 169 #if DEBUG_LEVEL >= 4
 170 #define DBG4(sig, format, ...) charon->bus->signal(charon->bus, sig, LEVEL_4, format, ##__VA_ARGS__)
 171 #endif /* DEBUG_LEVEL */
 172
 173 #ifndef DBG1
 174 # define DBG1(...) {}
 175 #endif /* DBG1 */
 176 #ifndef DBG2
 177 # define DBG2(...) {}
 178 #endif /* DBG2 */
 179 #ifndef DBG3
 180 # define DBG3(...) {}
 181 #endif /* DBG3 */
 182 #ifndef DBG4
 183 # define DBG4(...) {}
 184 #endif /* DBG4 */
 185
 186 /**
 187  * @brief Raise a signal for an occured event.
 188  *
 189  * @param sig           signal_t signal description
 190  * @param format        printf() style format string
 191  * @param ...           printf() style agument list
 192  */
 193 #define SIG(sig, format, ...) charon->bus->signal(charon->bus, sig, LEVEL_0, format, ##__VA_ARGS__)
 194
 195 /**
 196  * @brief Get the type of a signal.
 197  *
 198  * A signal may be a debugging signal with a specific context. They have
 199  * a level specific for their context > 0. All audit signals use the
 200  * type 0. This allows filtering of singals by their type.
 201  *
 202  * @param signal        signal to get the type from
 203  * @return                      type of the signal, between 0..(DBG_MAX-1)
 204  */
 205 #define SIG_TYPE(sig) (sig > DBG_MAX ? SIG_ANY : sig)
 206
 207
 208 /**
 209  * @brief Interface for registering at the signal bus.
 210  *
 211  * To receive signals from the bus, the client implementing the
 212  * bus_listener_t interface registers itself at the signal bus.
 213  *
 214  * @ingroup bus
 215  */
 216 struct bus_listener_t {
 217
 218         /**
 219          * @brief Send a signal to a bus listener.
 220          *
 221          * A numerical identification for the thread is included, as the
 222          * associated IKE_SA, if any. Signal specifies the type of
 223          * the event occured. The format string specifies
 224          * an additional informational or error message with a printf() like
 225          * variable argument list. This is in the va_list form, as forwarding
 226          * a "..." parameters to functions is not (cleanly) possible.
 227          * The implementing signal function returns TRUE to stay registered
 228          * to the bus, or FALSE to unregister itself.
 229          *
 230          * @param this          listener
 231          * @param singal        kind of the signal (up, down, rekeyed, ...)
 232          * @param level         verbosity level of the signal
 233          * @param thread        ID of the thread raised this signal
 234          * @param ike_sa        IKE_SA associated to the event
 235          * @param format        printf() style format string
 236          * @param args          vprintf() style va_list argument list
 237          " @return                      TRUE to stay registered, FALSE to unregister
 238          */
 239         bool (*signal) (bus_listener_t *this, signal_t signal, level_t level,
 240                                         int thread, ike_sa_t *ike_sa, char* format, va_list args);
 241 };
 242
 243 /**
 244  * @brief Signal bus which sends signals to registered listeners.
 245  *
 246  * The signal bus is not much more than a multiplexer. A listener interested
 247  * in receiving event signals registers at the bus. Any signals sent to
 248  * are delivered to all registered listeners.
 249  * To deliver signals to threads, the blocking listen() call may be used
 250  * to wait for a signal.
 251  *
 252  * @ingroup bus
 253  */
 254 struct bus_t {
 255
 256         /**
 257          * @brief Register a listener to the bus.
 258          *
 259          * A registered listener receives all signals which are sent to the bus.
 260          * The listener is passive; the thread which emitted the signal
 261          * processes the listener routine.
 262          *
 263          * @param this          bus
 264          * @param listener      listener to register.
 265          */
 266         void (*add_listener) (bus_t *this, bus_listener_t *listener);
 267
 268         /**
 269          * @brief Listen actively on the bus.
 270          *
 271          * As we are fully multithreaded, we must provide a mechanism
 272          * for active threads to listen to the bus. With the listen() method,
 273          * a thread waits until a signal occurs, and then processes it.
 274          * To prevent the listen() calling thread to miss signals emitted while
 275          * it processes a signal, registration is required. This is done through
 276          * the set_listen_state() method, see below.
 277          *
 278          * @param this          bus
 279          * @param level         verbosity level of the signal
 280          * @param thread        receives thread number emitted the signal
 281          * @param ike_sa        receives the IKE_SA involved in the signal, or NULL
 282          * @param format        receives the format string supplied with the signal
 283          * @param va_list       receives the variable argument list for format
 284          * @return                      the emitted signal type
 285          */
 286         signal_t (*listen) (bus_t *this, level_t* level, int *thread,
 287                                                 ike_sa_t **ike_sa, char** format, va_list* args);
 288
 289         /**
 290          * @brief Set the listening state of the calling thread.
 291          *
 292          * To prevent message loss for active listeners using listen(), threads
 293          * must register themself to the bus before starting to listen(). When
 294          * a signal occurs, the emitter waits until all threads with listen_state
 295          * TRUE are waiting in the listen() method to process the signal.
 296          * It is important that a thread with liste_state TRUE calls listen()
 297          * periodically, or sets it's listening state to FALSE; otherwise
 298          * all signal emitting threads get blocked on the bus.
 299          *
 300          * @param this          bus
 301          * @param active        TRUE to set to listening
 302          */
 303         void (*set_listen_state) (bus_t *this, bool active);
 304
 305         /**
 306          * @brief Set the IKE_SA the calling thread is using.
 307          *
 308          * To associate an received signal to an IKE_SA without passing it as
 309          * parameter each time, the thread registers it's used IKE_SA each
 310          * time it checked it out. Before checking it in, the thread unregisters
 311          * the IKE_SA (by passing NULL). This IKE_SA is stored per-thread, so each
 312          * thread has one IKE_SA registered (or not).
 313          *
 314          * @param this          bus
 315          * @param ike_sa        ike_sa to register, or NULL to unregister
 316          */
 317         void (*set_sa) (bus_t *this, ike_sa_t *ike_sa);
 318
 319         /**
 320          * @brief Send a signal to the bus.
 321          *
 322          * The signal specifies the type of the event occured. The format string
 323          * specifies an additional informational or error message with a
 324          * printf() like variable argument list.
 325          * Some useful macros are available to shorten this call.
 326          * @see SIG(), DBG1()
 327          *
 328          * @param this          bus
 329          * @param singal        kind of the signal (up, down, rekeyed, ...)
 330          * @param level         verbosity level of the signal
 331          * @param format        printf() style format string
 332          * @param ...           printf() style argument list
 333          */
 334         void (*signal) (bus_t *this, signal_t signal, level_t level, char* format, ...);
 335
 336         /**
 337          * @brief Send a signal to the bus using va_list arguments.
 338          *
 339          * Same as bus_t.signal(), but uses va_list argument list.
 340          *
 341          * @param this          bus
 342          * @param singal        kind of the signal (up, down, rekeyed, ...)
 343          * @param level         verbosity level of the signal
 344          * @param format        printf() style format string
 345          * @param args          va_list arguments
 346          */
 347         void (*vsignal) (bus_t *this, signal_t signal, level_t level, char* format, va_list args);
 348
 349         /**
 350          * @brief Destroy the signal bus.
 351          *
 352          * @param this          bus to destroy
 353          */
 354         void (*destroy) (bus_t *this);
 355 };
 356
 357 /**
 358  * @brief Create the signal bus which multiplexes signals to its listeners.
 359  *
 360  * @return              signal bus instance
 361  *
 362  * @ingroup bus
 363  */
 364 bus_t *bus_create();
 365
 366 #endif /* BUS_H_ */