faster implementation of addr_in_subnet()
[strongswan.git] / src / charon / control / controller.h
1 /*
2 * Copyright (C) 2007 Martin Willi
3 * Hochschule fuer Technik Rapperswil
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 *
15 * $Id$
16 */
17
18 /**
19 * @defgroup controller_i controller
20 * @{ @ingroup control
21 */
22
23 #ifndef CONTROLLER_H_
24 #define CONTROLLER_H_
25
26 #include <bus/bus.h>
27
28 /**
29 * callback to log things triggered by controller.
30 *
31 * @param param echoed parameter supplied when function invoked
32 * @param signal type of signal
33 * @param level verbosity level if log
34 * @param ike_sa associated IKE_SA, if any
35 * @param format printf like format string
36 * @param args list of arguments to use for format
37 * @return FALSE to return from invoked function
38 */
39 typedef bool(*controller_cb_t)(void* param, signal_t signal, level_t level,
40 ike_sa_t* ike_sa, void *data,
41 char* format, va_list args);
42
43 /**
44 * Empty callback function for controller_t functions.
45 *
46 * If you wan't to do a syncrhonous call, but don't need a callback, pass
47 * this function to the controllers methods.
48 */
49 bool controller_cb_empty(void *param, signal_t signal, level_t level,
50 ike_sa_t *ike_sa, void *data,
51 char *format, va_list args);
52
53 typedef struct controller_t controller_t;
54
55 /**
56 * The controller provides a simple interface to run actions.
57 *
58 * The controller starts actions by creating jobs. It then tries to
59 * evaluate the result of the operation by listening on the bus.
60 *
61 * Passing NULL as callback to the managers function calls them asynchronously.
62 * If a callback is specified, they are called synchronoulsy. There is a default
63 * callback "controller_cb_empty" if you wan't to call a function
64 * synchronously, but don't need a callback.
65 */
66 struct controller_t {
67
68 /**
69 * Create an enumerator for all IKE_SAs.
70 *
71 * The enumerator blocks the IKE_SA manager until it gets destroyed. Do
72 * not call another interface/manager method while the iterator is alive.
73 *
74 * @return enumerator, locks IKE_SA manager until destroyed
75 */
76 enumerator_t* (*create_ike_sa_enumerator)(controller_t *this);
77
78 /**
79 * Initiate a CHILD_SA, and if required, an IKE_SA.
80 *
81 * The inititate() function is synchronous and thus blocks until the
82 * IKE_SA is established or failed. Because of this, the initiate() function
83 * contains a thread cancellation point.
84 *
85 * @param peer_cfg peer_cfg to use for IKE_SA setup
86 * @param child_cfg child_cfg to set up CHILD_SA from
87 * @param cb logging callback
88 * @param param parameter to include in each call of cb
89 * @return
90 * - SUCCESS, if CHILD_SA established
91 * - FAILED, if setup failed
92 * - NEED_MORE, if callback returned FALSE
93 */
94 status_t (*initiate)(controller_t *this,
95 peer_cfg_t *peer_cfg, child_cfg_t *child_cfg,
96 controller_cb_t callback, void *param);
97
98 /**
99 * Terminate an IKE_SA and all of its CHILD_SAs.
100 *
101 * The terminate() function is synchronous and thus blocks until the
102 * IKE_SA is properly deleted, or the delete timed out.
103 * The terminate() function contains a thread cancellation point.
104 *
105 * @param unique_id unique id of the IKE_SA to terminate.
106 * @param cb logging callback
107 * @param param parameter to include in each call of cb
108 * @return
109 * - SUCCESS, if CHILD_SA terminated
110 * - NOT_FOUND, if no such CHILD_SA found
111 * - NEED_MORE, if callback returned FALSE
112 */
113 status_t (*terminate_ike)(controller_t *this, u_int32_t unique_id,
114 controller_cb_t callback, void *param);
115
116 /**
117 * Terminate a CHILD_SA.
118 *
119 * @param reqid reqid of the CHILD_SA to terminate
120 * @param cb logging callback
121 * @param param parameter to include in each call of cb
122 * @return
123 * - SUCCESS, if CHILD_SA terminated
124 * - NOT_FOUND, if no such CHILD_SA found
125 * - NEED_MORE, if callback returned FALSE
126 */
127 status_t (*terminate_child)(controller_t *this, u_int32_t reqid,
128 controller_cb_t callback, void *param);
129
130 /**
131 * Route a CHILD_SA (install triggering policies).
132 *
133 * @param peer_cfg peer_cfg to use for IKE_SA setup, if triggered
134 * @param child_cfg child_cfg to route
135 * @param cb logging callback
136 * @param param parameter to include in each call of cb
137 * @return
138 * - SUCCESS, if CHILD_SA routed
139 * - FAILED, if routing failed
140 * - NEED_MORE, if callback returned FALSE
141 */
142 status_t (*route)(controller_t *this,
143 peer_cfg_t *peer_cfg, child_cfg_t *child_cfg,
144 controller_cb_t callback, void *param);
145
146 /**
147 * Unroute a routed CHILD_SA (uninstall triggering policies).
148 *
149 * Only the route is removed, not the CHILD_SAs the route triggered.
150 *
151 * @param reqid reqid of the CHILD_SA to unroute
152 * @param cb logging callback
153 * @param param parameter to include in each call of cb
154 * @return
155 * - SUCCESS, if CHILD_SA terminated
156 * - NOT_FOUND, if no such CHILD_SA routed
157 * - NEED_MORE, if callback returned FALSE
158 */
159 status_t (*unroute)(controller_t *this, u_int32_t reqid,
160 controller_cb_t callback, void *param);
161
162 /**
163 * Destroy a controller_t instance.
164 */
165 void (*destroy) (controller_t *this);
166 };
167
168
169 /**
170 * Creates a controller instance.
171 *
172 * @return controller_t object
173 */
174 controller_t *controller_create(void);
175
176 #endif /* CONTROLLER_H_ @} */