proposal-substructure: Fix incorrect type for IKEv2 proposals
[strongswan.git] / src / libcharon / control / controller.h
1 /*
2 * Copyright (C) 2007 Martin Willi
3 * HSR 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 * @param limits whether to check limits regarding IKE_SA initiation
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 * - INVALID_STATE if limits prevented initiation
92 */
93 status_t (*initiate)(controller_t *this,
94 peer_cfg_t *peer_cfg, child_cfg_t *child_cfg,
95 controller_cb_t callback, void *param, u_int timeout,
96 bool limits);
97
98 /**
99 * Terminate an IKE_SA and all of its CHILD_SAs.
100 *
101 * If a callback is provided the function is synchronous and thus blocks
102 * until the IKE_SA is properly deleted, or the call timed out.
103 *
104 * @param unique_id unique id of the IKE_SA to terminate.
105 * @param force whether to immediately destroy the IKE_SA without
106 * waiting for a response or retransmitting the delete,
107 * if a callback is provided and timeout is > 0 the
108 * IKE_SA is destroyed once the timeout is reached but
109 * retransmits are sent until then
110 * @param cb logging callback
111 * @param param parameter to include in each call of cb
112 * @param timeout timeout in ms to wait for callbacks, 0 to disable
113 * @return
114 * - SUCCESS, if CHILD_SA terminated
115 * - NOT_FOUND, if no such CHILD_SA found
116 * - NEED_MORE, if callback returned FALSE
117 * - OUT_OF_RES if timed out
118 */
119 status_t (*terminate_ike)(controller_t *this, uint32_t unique_id,
120 bool force, controller_cb_t callback, void *param,
121 u_int timeout);
122
123 /**
124 * Terminate a CHILD_SA.
125 *
126 * If a callback is provided the function is synchronous and thus blocks
127 * until the CHILD_SA is properly deleted, or the call timed out.
128 *
129 * @param unique_id CHILD_SA unique ID to terminate
130 * @param cb logging callback
131 * @param param parameter to include in each call of cb
132 * @param timeout timeout in ms to wait for callbacks, 0 to disable
133 * @return
134 * - SUCCESS, if CHILD_SA terminated
135 * - NOT_FOUND, if no such CHILD_SA found
136 * - NEED_MORE, if callback returned FALSE
137 * - OUT_OF_RES if timed out
138 */
139 status_t (*terminate_child)(controller_t *this, uint32_t unique_id,
140 controller_cb_t callback, void *param,
141 u_int timeout);
142
143 /**
144 * Destroy a controller_t instance.
145 */
146 void (*destroy) (controller_t *this);
147 };
148
149 /**
150 * Creates a controller instance.
151 *
152 * @return controller_t object
153 */
154 controller_t *controller_create();
155
156 #endif /** CONTROLLER_H_ @}*/