added missing includes
[strongswan.git] / src / dumm / guest.h
1 /*
2 * Copyright (C) 2008 Tobias Brunner
3 * Copyright (C) 2007 Martin Willi
4 * Hochschule fuer Technik Rapperswil
5 *
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation; either version 2 of the License, or (at your
9 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * for more details.
15 */
16
17 #ifndef GUEST_H
18 #define GUEST_H
19
20 #include <library.h>
21 #include <utils/enumerator.h>
22
23 typedef enum guest_state_t guest_state_t;
24 typedef struct guest_t guest_t;
25
26 #include "iface.h"
27
28 /**
29 * @brief State of a guest (started, stopped, ...)
30 */
31 enum guest_state_t {
32 /** guest kernel not running at all */
33 GUEST_STOPPED,
34 /** kernel started, but not yet available */
35 GUEST_STARTING,
36 /** guest is up and running */
37 GUEST_RUNNING,
38 /** guest has been paused */
39 GUEST_PAUSED,
40 /** guest is stopping (shutting down) */
41 GUEST_STOPPING,
42 };
43
44 /**
45 * string mappings for guest_state_t
46 */
47 extern enum_name_t *guest_state_names;
48
49 /**
50 * Invoke function which lauches the UML guest.
51 *
52 * Consoles are all set to NULL, you may change them by adding additional UML
53 * options to args before invocation.
54 *
55 * @param data callback data
56 * @param guest guest to start
57 * @param args args to use for guest invocation, args[0] is kernel
58 * @param argc number of elements in args
59 * @param idle
60 * @return PID of child, 0 if failed
61 */
62 typedef pid_t (*invoke_function_t)(void *data, guest_t *guest,
63 char *args[], int argc);
64
65 /**
66 * Idle function to pass to start().
67 */
68 typedef void (*idle_function_t)(void);
69
70 /**
71 * @brief A guest is a UML instance running on the host.
72 **/
73 struct guest_t {
74
75 /**
76 * @brief Get the name of this guest.
77 *
78 * @return name of the guest
79 */
80 char* (*get_name) (guest_t *this);
81
82 /**
83 * @brief Get the process ID of the guest child process.
84 *
85 * @return name of the guest
86 */
87 pid_t (*get_pid) (guest_t *this);
88
89 /**
90 * @brief Get the state of the guest (stopped, started, etc.).
91 *
92 * @return guests state
93 */
94 guest_state_t (*get_state)(guest_t *this);
95
96 /**
97 * @brief Start the guest.
98 *
99 * @param invoke UML guest invocation function
100 * @param data data to pass back to invoke function
101 * @param idle idle function to call while waiting on child
102 * @return TRUE if guest successfully started
103 */
104 bool (*start) (guest_t *this, invoke_function_t invoke, void *data,
105 idle_function_t idle);
106
107 /**
108 * @brief Kill the guest.
109 *
110 * @param idle idle function to call while waiting to termination
111 */
112 void (*stop) (guest_t *this, idle_function_t idle);
113
114 /**
115 * @brief Create a new interface in the current scenario.
116 *
117 * @param name name of the interface in the guest
118 * @return created interface, or NULL if failed
119 */
120 iface_t* (*create_iface)(guest_t *this, char *name);
121
122 /**
123 * @brief Destroy an interface on guest.
124 *
125 * @param iface interface to destroy
126 */
127 void (*destroy_iface)(guest_t *this, iface_t *iface);
128
129 /**
130 * @brief Create an enumerator over all guest interfaces.
131 *
132 * @return enumerator over iface_t's
133 */
134 enumerator_t* (*create_iface_enumerator)(guest_t *this);
135
136 /**
137 * @brief Set the template COWFS overlay to use.
138 *
139 * @param parent parent directory where template diff should point to
140 * @return FALSE if failed
141 */
142 bool (*load_template)(guest_t *this, char *parent);
143
144 /**
145 * Execute a command on the guests mconsole.
146 *
147 * @param cb callback to call for each read block
148 * @param data data to pass to callback
149 * @param cmd command to execute
150 * @param ... printf style argument list for cmd
151 * @return return value
152 */
153 int (*exec)(guest_t *this, void(*cb)(void*,char*,size_t), void *data,
154 char *cmd, ...);
155
156 /**
157 * Execute a command on the guests mconsole, with output formatter.
158 *
159 * If lines is TRUE, callback is invoked for each output line. Otherwise
160 * the full result is returned in one callback invocation.
161 *
162 * @note This function does not work with binary output.
163 *
164 * @param cb callback to call for each line or for the complete output
165 * @param lines TRUE if the callback should be called for each line
166 * @param data data to pass to callback
167 * @param cmd command to execute
168 * @param ... printf style argument list for cmd
169 * @return return value
170 */
171 int (*exec_str)(guest_t *this, void(*cb)(void*,char*), bool lines,
172 void *data, char *cmd, ...);
173
174 /**
175 * @brief Called whenever a SIGCHILD for the guests PID is received.
176 */
177 void (*sigchild)(guest_t *this);
178
179 /**
180 * @brief Close and destroy a guest with all interfaces
181 */
182 void (*destroy) (guest_t *this);
183 };
184
185 /**
186 * @brief Create a new, unstarted guest.
187 *
188 * @param parent parent directory to create the guest in
189 * @param name name of the guest to create
190 * @param kernel kernel this guest uses
191 * @param master read-only master filesystem for guest
192 * @param args additional args to pass to kernel
193 * @param mem amount of memory to give the guest
194 */
195 guest_t *guest_create(char *parent, char *name, char *kernel,
196 char *master, char *args);
197
198 /**
199 * @brief Load a guest created with guest_create().
200 *
201 * @param parent parent directory to look for a guest
202 * @param name name of the guest directory
203 */
204 guest_t *guest_load(char *parent, char *name);
205
206 #endif /* GUEST_H */
207