7e1053976654d823f7dd77764801f4c64a0e95b4
[libvscmgmt.git] / include / libvscmgmt / libvscmgmt.h
1 /*
2  * libvscmgmt.h: Library for Virtualized Super Computer Management
3  *
4  * Copyright (C) 2009 Matthias Bolte <matthias.bolte@googlemail.com>
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this library; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
19  */
20
21 #ifndef __VSC_MGMT_H__
22 #define __VSC_MGMT_H__
23
24 #include <stdio.h> /* for FILE */
25 #include <sys/time.h> /* for struct timeval */
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 #define VSC_MGMT__VERION__MAJOR 0
32 #define VSC_MGMT__VERION__MINOR 1
33 #define VSC_MGMT__VERION__PATCH 0
34
35 #define VSC_MGMT__UUID__SIZE 16
36 #define VSC_MGMT__UUID__STRING_SIZE (36 + 1)
37
38 #define VSC_MGMT__IPV4__SIZE 4
39 #define VSC_MGMT__IPV4__STRING_SIZE (16 + 1)
40
41 enum VscMgmtCode {
42         VSC_MGMT__CODE__UNDEFINED = 0,
43         VSC_MGMT__CODE__INTERNAL_ERROR,
44         VSC_MGMT__CODE__OUT_OF_MEMORY,
45         VSC_MGMT__CODE__XMLRPC_ERROR,
46         VSC_MGMT__CODE__INVALID_ARGUMENT,
47         VSC_MGMT__CODE__INVALID_CALL,
48         VSC_MGMT__CODE__INVALID_UUID_STRING,
49         VSC_MGMT__CODE__INVALID_IPV4_STRING,
50         VSC_MGMT__CODE__INVALID_HOST_TYPE_STRING,
51         VSC_MGMT__CODE__NOT_INITIALIZED,
52         VSC_MGMT__CODE__NOT_IMPLEMENTED_YET,
53         VSC_MGMT__CODE__TRACE,
54 };
55
56 enum VscMgmtVmState {
57         VSC_MGMT__VM_STATE__UNDEFINED = 0,
58         VSC_MGMT__VM_STATE__RUNNING,
59         VSC_MGMT__VM_STATE__SUSPENDED,
60         VSC_MGMT__VM_STATE__ERROR,
61 };
62
63 enum VscMgmtHostType {
64         VSC_MGMT__HOST_TYPE__UNDEFINED = 0,
65         VSC_MGMT__HOST_TYPE__XEN,
66         VSC_MGMT__HOST_TYPE__ESX,
67         VSC_MGMT__HOST_TYPE__KVM,
68 };
69
70 enum VscMgmtUuidType {
71         VSC_MGMT__UUID_TYPE__UNDEFINED = 0,
72         VSC_MGMT__UUID_TYPE__INVALID,
73         VSC_MGMT__UUID_TYPE__VM,
74         VSC_MGMT__UUID_TYPE__SUSPENSION,
75         VSC_MGMT__UUID_TYPE__CHECKPOINT,
76 };
77
78 struct VscMgmtError {
79         struct VscMgmtError *next;
80         int occured;
81         enum VscMgmtCode code;
82         char *message;
83         const char *file;
84         int line;
85         const char *function;
86         struct timeval timestamp;
87 };
88
89 struct VscMgmtUuid {
90         struct VscMgmtUuid *next;
91         unsigned char bytes[VSC_MGMT__UUID__SIZE];
92 };
93
94 struct VscMgmtIpv4 {
95         struct VscMgmtUuid *next;
96         unsigned char bytes[VSC_MGMT__IPV4__SIZE];
97 };
98
99 struct VscMgmtVmResourceConfig {
100         int dummy;
101 };
102
103 struct VscMgmtVmNetworkConfig {
104         struct VscMgmtIpv4 vm_ipv4;
105         struct VscMgmtIpv4 vm_subnet;
106         struct VscMgmtIpv4 vm_subnet_mask;
107 };
108
109 struct VscMgmtVmInfo {
110         struct VscMgmtUuid vm_uuid;
111         struct VscMgmtIpv4 host_ipv4;
112         enum VscMgmtVmState vm_state;
113         struct VscMgmtVmResourceConfig vm_resource_config;
114         struct VscMgmtVmNetworkConfig vm_network_config;
115 };
116
117 struct VscMgmtSuspensionInfo {
118         int dummy;
119 };
120
121 struct VscMgmtCheckpointInfo {
122         int dummy;
123 };
124
125 struct VscMgmtHostInfo {
126         struct VscMgmtHostInfo *next;
127         struct VscMgmtIpv4 host_ipv4;
128         enum VscMgmtHostType host_type;
129         char *host_username;
130         char *host_password;
131 };
132
133 /*
134  * Error
135  */
136
137 void
138 vsc_mgmt_error_init (struct VscMgmtError *error);
139
140 void
141 vsc_mgmt_error_cleanup (struct VscMgmtError *error);
142
143 /**
144  * Returns the string representaion of the given error code.
145  *
146  * The string must not be freed by the caller.
147  */
148 const char * /* error_string */
149 vsc_mgmt_error_string (enum VscMgmtCode code);
150
151 void
152 vsc_mgmt_error_fprint (struct VscMgmtError *error, FILE *stream);
153
154 /*
155  * Memory
156  */
157
158 void
159 vsc_mgmt_free (void *memory);
160
161 /*
162  * UUID
163  */
164
165 /**
166  * Appends a duplicate of the given UUID to the list.
167  *
168  * Always returns a pointer to the first UUID item in the list, so that this
169  * function can be used for initialization and for appending.
170  */
171 struct VscMgmtUuid * /* uuid_list */
172 vsc_mgmt_uuid_list_append (struct VscMgmtError *error,
173                            struct VscMgmtUuid *uuid_list,
174                            const struct VscMgmtUuid *uuid);
175
176 /**
177  * Recursively frees the given UUID list.
178  */
179 void
180 vsc_mgmt_uuid_list_free (struct VscMgmtUuid *uuid_list);
181
182 /**
183  * Parses a UUID from its string representation.
184  */
185 void
186 vsc_mgmt_uuid_parse (struct VscMgmtError *error, const char *uuid_string,
187                      struct VscMgmtUuid *uuid);
188
189 /**
190  * Formats a UUID to its string representation.
191  */
192 void
193 vsc_mgmt_uuid_format (const struct VscMgmtUuid *uuid, char *uuid_string);
194
195 /*
196  * IPv4
197  */
198
199 /**
200  * Appends a duplicate of the given IPv4 to the list.
201  *
202  * Always returns a pointer to the first IPv4 item in the list, so that this
203  * function can be used for initialization and for appending.
204  */
205 struct VscMgmtIpv4 * /* ipv4_list */
206 vsc_mgmt_ipv4_list_append (struct VscMgmtError *error,
207                            struct VscMgmtIpv4 *ipv4_list,
208                            const struct VscMgmtIpv4 *ipv4);
209
210 /**
211  * Recursively frees the given IPv4 list.
212  */
213 void
214 vsc_mgmt_ipv4_list_free (struct VscMgmtIpv4 *ipv4_list);
215
216 /**
217  * Parses an IPv4 from its string representation.
218  */
219 void
220 vsc_mgmt_ipv4_parse (struct VscMgmtError *error, const char *ipv4_string,
221                      struct VscMgmtIpv4 *ipv4);
222
223 /**
224  * Formats an IPv4 to its string representation.
225  */
226 void
227 vsc_mgmt_ipv4_format (const struct VscMgmtIpv4 *ipv4, char *ipv4_string);
228
229 /*
230  * Global
231  */
232
233 void
234 vsc_mgmt_global_init (struct VscMgmtError *error, const char *backend_config);
235
236 void
237 vsc_mgmt_global_cleanup (void);
238
239 void
240 vsc_mgmt_global_backup (struct VscMgmtError *error);
241
242 void
243 vsc_mgmt_global_recover (struct VscMgmtError *error);
244
245 /*
246  * Virtual Machine
247  */
248
249 struct VscMgmtUuid * /* vm_uuid_list */
250 vsc_mgmt_vm_start (struct VscMgmtError *error, const char* image_path,
251                    const struct VscMgmtIpv4 *host_ipv4_list,
252                    const struct VscMgmtVmResourceConfig *vm_resource_config,
253                    const struct VscMgmtVmNetworkConfig *vm_network_config);
254
255 void
256 vsc_mgmt_vm_stop (struct VscMgmtError *error,
257                   const struct VscMgmtUuid *vm_uuid);
258
259 void
260 vsc_mgmt_vm_reboot (struct VscMgmtError *error,
261                     const struct VscMgmtUuid *vm_uuid);
262
263 void
264 vsc_mgmt_vm_migrate (struct VscMgmtError *error,
265                      const struct VscMgmtUuid *vm_uuid,
266                      const struct VscMgmtIpv4 *host_ipv4);
267
268 void
269 vsc_mgmt_vm_get_info (struct VscMgmtError *error,
270                       const struct VscMgmtUuid *vm_uuid,
271                       struct VscMgmtVmInfo *vm_info);
272
273 void
274 vsc_mgmt_vm_get_uuid (struct VscMgmtError *error,
275                       const struct VscMgmtIpv4 *vm_ipv4,
276                       struct VscMgmtUuid *vm_uuid);
277
278 void
279 vsc_mgmt_vm_get_host (struct VscMgmtError *error,
280                       const struct VscMgmtUuid *vm_uuid,
281                       struct VscMgmtIpv4 *host_ipv4);
282
283 enum VscMgmtVmState /* vm_state */
284 vsc_mgmt_vm_get_state (struct VscMgmtError *error,
285                        const struct VscMgmtUuid *vm_uuid);
286
287 void
288 vsc_mgmt_vm_set_resource_config (struct VscMgmtError *error,
289                                  const struct VscMgmtUuid *vm_uuid,
290                                  const struct VscMgmtVmResourceConfig *vm_resource_config);
291
292 void
293 vsc_mgmt_vm_get_resource_config (struct VscMgmtError *error,
294                                  const struct VscMgmtUuid *vm_uuid,
295                                  struct VscMgmtVmResourceConfig *vm_resource_config);
296
297 void
298 vsc_mgmt_vm_get_network_config (struct VscMgmtError *error,
299                                 const struct VscMgmtUuid *vm_uuid,
300                                 struct VscMgmtVmNetworkConfig *vm_network_config);
301
302 /*
303  * Suspension
304  */
305
306 void
307 vsc_mgmt_suspension_create (struct VscMgmtError *error,
308                             const struct VscMgmtUuid *vm_uuid_list,
309                             struct VscMgmtUuid *suspension_uuid);
310
311 void
312 vsc_mgmt_suspension_resume (struct VscMgmtError *error,
313                             const struct VscMgmtUuid *suspension_uuid);
314
315 void
316 vsc_mgmt_suspension_get_info (struct VscMgmtError *error,
317                               const struct VscMgmtUuid *suspension_uuid,
318                               struct VscMgmtSuspensionInfo *suspension_info);
319
320 /*
321  * Checkpoint
322  */
323
324 void
325 vsc_mgmt_checkpoint_create (struct VscMgmtError *error,
326                             const struct VscMgmtUuid *vm_uuid_list,
327                             struct VscMgmtUuid *checkpoint_uuid);
328
329 void
330 vsc_mgmt_checkpoint_delete (struct VscMgmtError *error,
331                             const struct VscMgmtUuid *checkpoint_uuid);
332
333 void
334 vsc_mgmt_checkpoint_restore (struct VscMgmtError *error,
335                              const struct VscMgmtUuid *checkpoint_uuid);
336
337 void
338 vsc_mgmt_checkpoint_get_info (struct VscMgmtError *error,
339                               const struct VscMgmtUuid *checkpoint_uuid,
340                               struct VscMgmtCheckpointInfo *checkpoint_info);
341
342 /*
343  * Host
344  */
345
346 void
347 vsc_mgmt_host_add (struct VscMgmtError *error,
348                    const struct VscMgmtHostInfo *host_info);
349
350 void
351 vsc_mgmt_host_remove (struct VscMgmtError *error,
352                       const struct VscMgmtIpv4 *host_ipv4);
353
354 void
355 vsc_mgmt_host_get_info (struct VscMgmtError *error,
356                         const struct VscMgmtIpv4 *host_ipv4,
357                         struct VscMgmtHostInfo *host_info);
358
359 /**
360  * Returns a UUID list representing all virtual machines currently available
361  * on the given host.
362  *
363  * The list must be freed by the caller via the vsc_mgmt_uuid_list_free
364  * function.
365  */
366 struct VscMgmtUuid * /* vm_uuid_list */
367 vsc_mgmt_host_get_vm_list (struct VscMgmtError *error,
368                            const struct VscMgmtIpv4 *host_ipv4);
369
370 /*
371  * Host Type
372  */
373
374 /**
375  * Parses a host type from its string representation and returns it.
376  */
377 enum VscMgmtHostType /* host_type */
378 vsc_mgmt_host_type_parse (struct VscMgmtError *error,
379                           const char *host_type_string);
380
381 /**
382  * Returns the string representaion of the given host type.
383  *
384  * The string must not be freed by the caller.
385  */
386 const char * /* host_type_string */
387 vsc_mgmt_host_type_string (enum VscMgmtHostType host_type);
388
389 /*
390  * Misc
391  */
392
393 /**
394  * Returns an IPv4 list representing all currently known host.
395  *
396  * The list must be freed by the caller via the vsc_mgmt_ipv4_list_free
397  * function.
398  */
399 struct VscMgmtIpv4 * /* host_ipv4_list */
400 vsc_mgmt_get_host_list (struct VscMgmtError *error);
401
402 struct VscMgmtUuid * /* checkpoint_uuid_list */
403 vsc_mgmt_get_checkpoint_list (struct VscMgmtError *error);
404
405 enum VscMgmtUuidType /* uuid_type */
406 vsc_mgmt_get_uuid_type (struct VscMgmtError *error,
407                         const struct VscMgmtUuid *uuid);
408
409 void
410 vsc_mgmt_get_version (int *major, int *minor, int *patch);
411
412 #ifdef __cplusplus
413 }
414 #endif
415
416 #endif /* __VSC_MGMT_H__ */