introduced printf() specifiers for:
[strongswan.git] / 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 #include <stdarg.h>
27
28 #include <sa/ike_sa.h>
29 #include <sa/child_sa.h>
30
31
32 /**
33 * @brief Raise a signal for an occured event.
34 *
35 * @param sig signal_t signal description
36 * @param level level for the signal
37 * @param format printf() style format string
38 * @param ... printf() style agument list
39 */
40 #define SIG(sig, level, format, ...) charon->bus->signal(charon->bus, sig, level, format, ##__VA_ARGS__)
41
42 /**
43 * @brief Set the IKE_SA the calling thread is using.
44 *
45 * @param ike_sa ike_sa to register, or NULL to unregister
46 */
47 #define SIG_SA(ike_sa) charon->bus->set_sa(charon->bus, ike_sa)
48
49 /**
50 * @brief Log a debug message via the signal bus.
51 *
52 * @param signal signal_t signal description
53 * @param format printf() style format string
54 * @param ... printf() style agument list
55 */
56 #define DBG1(sig, format, ...) charon->bus->signal(charon->bus, sig, LEV_DBG1, format, ##__VA_ARGS__)
57 #define DBG2(sig, format, ...) charon->bus->signal(charon->bus, sig, LEV_DBG2, format, ##__VA_ARGS__)
58 #define DBG3(sig, format, ...) charon->bus->signal(charon->bus, sig, LEV_DBG3, format, ##__VA_ARGS__)
59 #define DBG4(sig, format, ...) charon->bus->signal(charon->bus, sig, LEV_DBG4, format, ##__VA_ARGS__)
60
61
62 typedef enum signal_t signal_t;
63
64 enum signal_t {
65 /** an IKE_SA has been established */
66 SIG_IKE_UP,
67 /** an IKE_SA has been closed */
68 SIG_IKE_DOWN,
69 /** an IKE_SA has been rekeyed */
70 SIG_IKE_REKEY,
71 /** a CHILD_SA has been installed */
72 SIG_CHILD_UP,
73 /** a CHILD_SA has been closed */
74 SIG_CHILD_DOWN,
75 /** a CHILD_SA has been rekeyed */
76 SIG_CHILD_REKEY,
77 /** a CHILD_SA has been routed */
78 SIG_CHILD_ROUTE,
79 /** a CHILD_SA has been unrouted */
80 SIG_CHILD_UNROUTE,
81 /** a remote peer has been authenticated using RSA digital signature */
82 SIG_AUTH_RSA,
83 /** a remote peer has been authenticated using preshared keys */
84 SIG_AUTH_PSK,
85
86 /** debugging message printed from an IKE_SA */
87 SIG_DBG_IKE,
88 /** debugging message printed from a CHILD_SA */
89 SIG_DBG_CHD,
90 /** debugging message printed from job processing */
91 SIG_DBG_JOB,
92 /** debugging message printed from configuration backends */
93 SIG_DBG_CFG,
94 /** debugging message printed from kernel interface */
95 SIG_DBG_KNL,
96 /** debugging message printed from networking */
97 SIG_DBG_NET,
98 /** debugging message printed from message encoding/decoding */
99 SIG_DBG_ENC,
100
101 SIG_MAX,
102 };
103
104 typedef enum level_t level_t;
105
106 enum level_t {
107 /** Signal indicates something has failed */
108 LEV_FAILED,
109 /** Signal indicates something was successful */
110 LEV_SUCCESS,
111 /** Debug level 1, control flow messages */
112 LEV_DBG1,
113 /** Debug level 2, more detail informational messages */
114 LEV_DBG2,
115 /** Debug level 3, RAW data output */
116 LEV_DBG3,
117 /** Debug level 4, RAW data with sensitive (private) data */
118 LEV_DBG4,
119 };
120
121 typedef struct bus_listener_t bus_listener_t;
122
123 /**
124 * @brief Interface for registering at the signal bus.
125 *
126 * To receive signals from the bus, the client implementing the
127 * bus_listener_t interface registers itself at the signal bus.
128 *
129 * @ingroup bus
130 */
131 struct bus_listener_t {
132
133 /**
134 * @brief Send a signal to a bus listener.
135 *
136 * A numerical identification for the thread is included, as the
137 * associated IKE_SA, if any. Signal specifies the type of
138 * the event occured, with a verbosity level. The format string specifies
139 * an additional informational or error message with a printf() like
140 * variable argument list. This is in the va_list form, as forwarding
141 * a "..." parameters to functions is not (cleanly) possible.
142 *
143 * @param this listener
144 * @param thread ID of the thread raised this signal
145 * @param ike_sa IKE_SA associated to the event
146 * @param singal kind of the signal (up, down, rekeyed, ...)
147 * @param level level for signal
148 * @param format printf() style format string
149 * @param args vprintf() style va_list argument list
150 */
151 void (*signal) (bus_listener_t *this, int thread, ike_sa_t *ike_sa,
152 signal_t signal, level_t level, char* format, va_list args);
153 };
154
155
156 typedef struct bus_t bus_t;
157
158 /**
159 * @brief Signal bus which sends signals to registered listeners.
160 *
161 * The signal bus is not much more than a multiplexer. A listener interested
162 * in receiving event signals registers at the bus. Any signals sent to
163 * are delivered to all registered listeners.
164 *
165 *
166 * @ingroup bus
167 */
168 struct bus_t {
169
170 /**
171 * @brief Register a listener to the bus.
172 *
173 * A registered listener receives all signals which are sent to the bus.
174 *
175 * @param this bus
176 * @param listener listener to register.
177 */
178 void (*add_listener) (bus_t *this, bus_listener_t *listener);
179
180 /**
181 * @brief Set the IKE_SA the calling thread is using.
182 *
183 * To associate an received signal to an IKE_SA without passing it as
184 * parameter each time, the thread registers it's used IKE_SA each
185 * time it checked it out. Before checking it in, the thread unregisters
186 * the IKE_SA (by passing NULL). This IKE_SA is stored per-thread, so each
187 * thread has one IKE_SA registered (or not).
188 * There is a macro to simplify the call.
189 * @see SIG_SA()
190 *
191 * @param this bus
192 * @param ike_sa ike_sa to register, or NULL to unregister
193 */
194 void (*set_sa) (bus_t *this, ike_sa_t *ike_sa);
195
196 /**
197 * @brief Send a signal to the bus.
198 *
199 * A signal may belong to an IKE_SA and a CHILD_SA. If so, these
200 * are supplied to the signal function. The signal specifies the type of
201 * the event occured. The format string specifies an additional
202 * informational or error message with a printf() like variable argument
203 * list.
204 * Some useful macros may be available to shorten this call.
205 * @see SIG(), DBG1()
206 *
207 * @param this bus
208 * @param singal kind of the signal (up, down, rekeyed, ...)
209 * @param level status level of the signal to send
210 * @param format printf() style format string
211 * @param ... printf() style argument list
212 */
213 void (*signal) (bus_t *this, signal_t signal, level_t level, char* format, ...);
214
215 /**
216 * @brief Destroy the signal bus.
217 *
218 * @param this bus to destroy
219 */
220 void (*destroy) (bus_t *this);
221 };
222
223 /**
224 * @brief Create the signal bus which multiplexes signals to its listeners.
225 *
226 * @return signal bus instance
227 *
228 * @ingroup bus
229 */
230 bus_t *bus_create();
231
232 #endif /* BUS_H_ */