Moved data structures to new collections subfolder
[strongswan.git] / src / dumm / guest.h
1 /*
2 * Copyright (C) 2008-2009 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 <collections/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 * 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 * A guest is a UML instance running on the host.
72 **/
73 struct guest_t {
74
75 /**
76 * Get the name of this guest.
77 *
78 * @return name of the guest
79 */
80 char* (*get_name) (guest_t *this);
81
82 /**
83 * 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 * 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 * 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 * 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 * 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 * 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 * 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 * Adds a COWFS overlay. The directory is created if it does not exist.
138 *
139 * @param dir directory where overlay diff should point to
140 * @return FALSE, if failed
141 */
142 bool (*add_overlay)(guest_t *this, char *dir);
143
144 /**
145 * Removes the specified COWFS overlay.
146 *
147 * @param dir directory where overlay diff points to
148 * @return FALSE, if no found
149 */
150 bool (*del_overlay)(guest_t *this, char *dir);
151
152 /**
153 * Removes the latest COWFS overlay.
154 *
155 * @return FALSE, if no overlay was found
156 */
157 bool (*pop_overlay)(guest_t *this);
158
159 /**
160 * Execute a command on the guests mconsole.
161 *
162 * @param cb callback to call for each read block
163 * @param data data to pass to callback
164 * @param cmd command to execute
165 * @param ... printf style argument list for cmd
166 * @return return value
167 */
168 int (*exec)(guest_t *this, void(*cb)(void*,char*,size_t), void *data,
169 char *cmd, ...);
170
171 /**
172 * Execute a command on the guests mconsole, with output formatter.
173 *
174 * If lines is TRUE, callback is invoked for each output line. Otherwise
175 * the full result is returned in one callback invocation.
176 *
177 * @note This function does not work with binary output.
178 *
179 * @param cb callback to call for each line or for the complete output
180 * @param lines TRUE if the callback should be called for each line
181 * @param data data to pass to callback
182 * @param cmd command to execute
183 * @param ... printf style argument list for cmd
184 * @return return value
185 */
186 int (*exec_str)(guest_t *this, void(*cb)(void*,char*), bool lines,
187 void *data, char *cmd, ...);
188
189 /**
190 * Called whenever a SIGCHILD for the guests PID is received.
191 */
192 void (*sigchild)(guest_t *this);
193
194 /**
195 * Close and destroy a guest with all interfaces
196 */
197 void (*destroy) (guest_t *this);
198 };
199
200 /**
201 * Create a new, unstarted guest.
202 *
203 * @param parent parent directory to create the guest in
204 * @param name name of the guest to create
205 * @param kernel kernel this guest uses
206 * @param master read-only master filesystem for guest
207 * @param args additional args to pass to kernel
208 * @param mem amount of memory to give the guest
209 */
210 guest_t *guest_create(char *parent, char *name, char *kernel,
211 char *master, char *args);
212
213 /**
214 * Load a guest created with guest_create().
215 *
216 * @param parent parent directory to look for a guest
217 * @param name name of the guest directory
218 */
219 guest_t *guest_load(char *parent, char *name);
220
221 #endif /* GUEST_H */
222