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