daemon: Flush shunts before unloading plugins
[strongswan.git] / src / libcharon / 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
16 /**
17 * @defgroup controller_i controller
18 * @{ @ingroup control
19 */
20
21 #ifndef CONTROLLER_H_
22 #define CONTROLLER_H_
23
24 #include <bus/bus.h>
25
26 /**
27 * Callback to log things triggered by controller.
28 *
29 * @param param parameter supplied when controller method was called
30 * @param group debugging group
31 * @param level verbosity level
32 * @param ike_sa associated IKE_SA, if any
33 * @param message log message
34 * @return FALSE to return from called controller method
35 */
36 typedef bool (*controller_cb_t)(void* param, debug_t group, level_t level,
37 ike_sa_t* ike_sa, const char *message);
38
39 /**
40 * Empty callback function for controller_t methods.
41 *
42 * If you want to do a synchronous call, but don't need a callback, pass
43 * this function to the controller methods.
44 */
45 bool controller_cb_empty(void *param, debug_t group, level_t level,
46 ike_sa_t *ike_sa, const char *message);
47
48 typedef struct controller_t controller_t;
49
50 /**
51 * The controller provides a simple interface to run actions.
52 *
53 * The controller starts actions by creating jobs. It then tries to
54 * evaluate the result of the operation by listening on the bus.
55 *
56 * Passing NULL as callback to the managers function calls them asynchronously.
57 * If a callback is specified, they are called synchronously. There is a default
58 * callback "controller_cb_empty" if you want to call a function
59 * synchronously, but don't need a callback.
60 */
61 struct controller_t {
62
63 /**
64 * Create an enumerator for all IKE_SAs.
65 *
66 * The enumerator blocks the IKE_SA manager until it gets destroyed. Do
67 * not call another interface/manager method while the enumerator is alive.
68 *
69 * @param wait TRUE to wait for checked out SAs, FALSE to skip
70 * @return enumerator, locks IKE_SA manager until destroyed
71 */
72 enumerator_t* (*create_ike_sa_enumerator)(controller_t *this, bool wait);
73
74 /**
75 * Initiate a CHILD_SA, and if required, an IKE_SA.
76 *
77 * If a callback is provided the function is synchronous and thus blocks
78 * until the IKE_SA is established or failed.
79 *
80 * @param peer_cfg peer_cfg to use for IKE_SA setup
81 * @param child_cfg child_cfg to set up CHILD_SA from
82 * @param cb logging callback
83 * @param param parameter to include in each call of cb
84 * @param timeout timeout in ms to wait for callbacks, 0 to disable
85 * @return
86 * - SUCCESS, if CHILD_SA established
87 * - FAILED, if setup failed
88 * - NEED_MORE, if callback returned FALSE
89 * - OUT_OF_RES if timed out
90 */
91 status_t (*initiate)(controller_t *this,
92 peer_cfg_t *peer_cfg, child_cfg_t *child_cfg,
93 controller_cb_t callback, void *param, u_int timeout);
94
95 /**
96 * Terminate an IKE_SA and all of its CHILD_SAs.
97 *
98 * If a callback is provided the function is synchronous and thus blocks
99 * until the IKE_SA is properly deleted, or the call timed out.
100 *
101 * @param unique_id unique id of the IKE_SA to terminate.
102 * @param cb logging callback
103 * @param param parameter to include in each call of cb
104 * @param timeout timeout in ms to wait for callbacks, 0 to disable
105 * @return
106 * - SUCCESS, if CHILD_SA terminated
107 * - NOT_FOUND, if no such CHILD_SA found
108 * - NEED_MORE, if callback returned FALSE
109 * - OUT_OF_RES if timed out
110 */
111 status_t (*terminate_ike)(controller_t *this, u_int32_t unique_id,
112 controller_cb_t callback, void *param,
113 u_int timeout);
114
115 /**
116 * Terminate a CHILD_SA.
117 *
118 * If a callback is provided the function is synchronous and thus blocks
119 * until the CHILD_SA is properly deleted, or the call timed out.
120 *
121 * @param unique_id CHILD_SA unique ID to terminate
122 * @param cb logging callback
123 * @param param parameter to include in each call of cb
124 * @param timeout timeout in ms to wait for callbacks, 0 to disable
125 * @return
126 * - SUCCESS, if CHILD_SA terminated
127 * - NOT_FOUND, if no such CHILD_SA found
128 * - NEED_MORE, if callback returned FALSE
129 * - OUT_OF_RES if timed out
130 */
131 status_t (*terminate_child)(controller_t *this, u_int32_t unique_id,
132 controller_cb_t callback, void *param,
133 u_int timeout);
134
135 /**
136 * Destroy a controller_t instance.
137 */
138 void (*destroy) (controller_t *this);
139 };
140
141 /**
142 * Creates a controller instance.
143 *
144 * @return controller_t object
145 */
146 controller_t *controller_create();
147
148 #endif /** CONTROLLER_H_ @}*/