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 typedef enum _VscMgmtCode VscMgmtCode;
  42 typedef enum _VscMgmtVmState VscMgmtVmState;
  43 typedef enum _VscMgmtHostType VscMgmtHostType;
  44 typedef enum _VscMgmtUuidType VscMgmtUuidType;
  45 typedef struct _VscMgmtError VscMgmtError;
  46 typedef struct _VscMgmtUuid VscMgmtUuid;
  47 typedef struct _VscMgmtIpv4 VscMgmtIpv4;
  48 typedef struct _VscMgmtVmInfo VscMgmtVmInfo;
  49 typedef struct _VscMgmtVmResourceConfig VscMgmtVmResourceConfig;
  50 typedef struct _VscMgmtVmNetworkConfig VscMgmtVmNetworkConfig;
  51 typedef struct _VscMgmtSuspensionInfo VscMgmtSuspensionInfo;
  52 typedef struct _VscMgmtCheckpointInfo VscMgmtCheckpointInfo;
  53 typedef struct _VscMgmtHostInfo VscMgmtHostInfo;
  54
  55 enum _VscMgmtCode {
  56         VSC_MGMT__CODE__UNDEFINED = 0,
  57         VSC_MGMT__CODE__INTERNAL_ERROR,
  58         VSC_MGMT__CODE__OUT_OF_MEMORY,
  59         VSC_MGMT__CODE__XMLRPC_ERROR,
  60         VSC_MGMT__CODE__INVALID_ARGUMENT,
  61         VSC_MGMT__CODE__INVALID_CALL,
  62         VSC_MGMT__CODE__INVALID_UUID_STRING,
  63         VSC_MGMT__CODE__INVALID_IPV4_STRING,
  64         VSC_MGMT__CODE__INVALID_HOST_TYPE_STRING,
  65         VSC_MGMT__CODE__NOT_INITIALIZED,
  66         VSC_MGMT__CODE__NOT_IMPLEMENTED_YET,
  67         VSC_MGMT__CODE__TRACE,
  68 };
  69
  70 enum _VscMgmtVmState {
  71         VSC_MGMT__VM_STATE__UNDEFINED = 0,
  72         VSC_MGMT__VM_STATE__RUNNING,
  73         VSC_MGMT__VM_STATE__SUSPENDED,
  74         VSC_MGMT__VM_STATE__ERROR,
  75 };
  76
  77 enum _VscMgmtHostType {
  78         VSC_MGMT__HOST_TYPE__UNDEFINED = 0,
  79         VSC_MGMT__HOST_TYPE__XEN,
  80         VSC_MGMT__HOST_TYPE__ESX,
  81         VSC_MGMT__HOST_TYPE__KVM,
  82 };
  83
  84 enum _VscMgmtUuidType {
  85         VSC_MGMT__UUID_TYPE__UNDEFINED = 0,
  86         VSC_MGMT__UUID_TYPE__INVALID,
  87         VSC_MGMT__UUID_TYPE__VM,
  88         VSC_MGMT__UUID_TYPE__SUSPENSION,
  89         VSC_MGMT__UUID_TYPE__CHECKPOINT,
  90 };
  91
  92 struct _VscMgmtError {
  93         VscMgmtError *next;
  94         int occured;
  95         VscMgmtCode code;
  96         char *message;
  97         const char *file;
  98         int line;
  99         const char *function;
 100         struct timeval timestamp;
 101 };
 102
 103 struct _VscMgmtUuid {
 104         VscMgmtUuid *next;
 105         unsigned char bytes[VSC_MGMT__UUID__SIZE];
 106 };
 107
 108 struct _VscMgmtIpv4 {
 109         VscMgmtUuid *next;
 110         unsigned char bytes[VSC_MGMT__IPV4__SIZE];
 111 };
 112
 113 struct _VscMgmtVmResourceConfig {
 114         int dummy;
 115 };
 116
 117 struct _VscMgmtVmNetworkConfig {
 118         VscMgmtIpv4 vm_ipv4;
 119         VscMgmtIpv4 vm_subnet;
 120         VscMgmtIpv4 vm_subnet_mask;
 121 };
 122
 123 struct _VscMgmtVmInfo {
 124         VscMgmtUuid vm_uuid;
 125         VscMgmtIpv4 host_ipv4;
 126         VscMgmtVmState vm_state;
 127         VscMgmtVmResourceConfig vm_resource_config;
 128         VscMgmtVmNetworkConfig vm_network_config;
 129 };
 130
 131 struct _VscMgmtSuspensionInfo {
 132         int dummy;
 133 };
 134
 135 struct _VscMgmtCheckpointInfo {
 136         int dummy;
 137 };
 138
 139 struct _VscMgmtHostInfo {
 140         VscMgmtHostInfo *next;
 141         VscMgmtIpv4 host_ipv4;
 142         VscMgmtHostType host_type;
 143         char *host_username;
 144         char *host_password;
 145 };
 146
 147 /*
 148  * Error
 149  */
 150
 151 void
 152 vsc_mgmt_error_init (VscMgmtError *error);
 153
 154 void
 155 vsc_mgmt_error_cleanup (VscMgmtError *error);
 156
 157 /**
 158  * Returns the string representaion of the given error code.
 159  *
 160  * The string must not be freed by the caller.
 161  */
 162 const char * /* error_string */
 163 vsc_mgmt_error_string (VscMgmtCode code);
 164
 165 void
 166 vsc_mgmt_error_fprint (VscMgmtError *error, FILE *stream);
 167
 168 /*
 169  * Memory
 170  */
 171
 172 void
 173 vsc_mgmt_free (void *memory);
 174
 175 /*
 176  * UUID
 177  */
 178
 179 /**
 180  * Appends a duplicate of the given UUID to the list.
 181  *
 182  * Always returns a pointer to the first UUID item in the list, so that this
 183  * function can be used for initialization and for appending.
 184  */
 185 VscMgmtUuid * /* uuid_list */
 186 vsc_mgmt_uuid_list_append (VscMgmtError *error, VscMgmtUuid *uuid_list,
 187                            const VscMgmtUuid *uuid);
 188
 189 /**
 190  * Recursively frees the given UUID list.
 191  */
 192 void
 193 vsc_mgmt_uuid_list_free (VscMgmtUuid *uuid_list);
 194
 195 /**
 196  * Parses a UUID from its string representation.
 197  */
 198 void
 199 vsc_mgmt_uuid_parse (VscMgmtError *error, const char *uuid_string,
 200                      VscMgmtUuid *uuid);
 201
 202 /**
 203  * Formats a UUID to its string representation.
 204  */
 205 void
 206 vsc_mgmt_uuid_format (const VscMgmtUuid *uuid, char *uuid_string);
 207
 208 /*
 209  * IPv4
 210  */
 211
 212 /**
 213  * Appends a duplicate of the given IPv4 to the list.
 214  *
 215  * Always returns a pointer to the first IPv4 item in the list, so that this
 216  * function can be used for initialization and for appending.
 217  */
 218 VscMgmtIpv4 * /* ipv4_list */
 219 vsc_mgmt_ipv4_list_append (VscMgmtError *error,
 220                            VscMgmtIpv4 *ipv4_list,
 221                            const VscMgmtIpv4 *ipv4);
 222
 223 /**
 224  * Recursively frees the given IPv4 list.
 225  */
 226 void
 227 vsc_mgmt_ipv4_list_free (VscMgmtIpv4 *ipv4_list);
 228
 229 /**
 230  * Parses an IPv4 from its string representation.
 231  */
 232 void
 233 vsc_mgmt_ipv4_parse (VscMgmtError *error, const char *ipv4_string,
 234                      VscMgmtIpv4 *ipv4);
 235
 236 /**
 237  * Formats an IPv4 to its string representation.
 238  */
 239 void
 240 vsc_mgmt_ipv4_format (const VscMgmtIpv4 *ipv4, char *ipv4_string);
 241
 242 /*
 243  * Global
 244  */
 245
 246 void
 247 vsc_mgmt_global_init (VscMgmtError *error, const char *backend_config);
 248
 249 void
 250 vsc_mgmt_global_cleanup (void);
 251
 252 void
 253 vsc_mgmt_global_backup (VscMgmtError *error);
 254
 255 void
 256 vsc_mgmt_global_recover (VscMgmtError *error);
 257
 258 /*
 259  * Virtual Machine
 260  */
 261
 262 VscMgmtUuid * /* vm_uuid_list */
 263 vsc_mgmt_vm_start (VscMgmtError *error, const char* image_path,
 264                    const VscMgmtIpv4 *host_ipv4_list,
 265                    const VscMgmtVmResourceConfig *vm_resource_config,
 266                    const VscMgmtVmNetworkConfig *vm_network_config);
 267
 268 void
 269 vsc_mgmt_vm_stop (VscMgmtError *error,
 270                   const VscMgmtUuid *vm_uuid);
 271
 272 void
 273 vsc_mgmt_vm_reboot (VscMgmtError *error,
 274                     const VscMgmtUuid *vm_uuid);
 275
 276 void
 277 vsc_mgmt_vm_migrate (VscMgmtError *error,
 278                      const VscMgmtUuid *vm_uuid,
 279                      const VscMgmtIpv4 *host_ipv4);
 280
 281 void
 282 vsc_mgmt_vm_get_info (VscMgmtError *error,
 283                       const VscMgmtUuid *vm_uuid,
 284                       VscMgmtVmInfo *vm_info);
 285
 286 void
 287 vsc_mgmt_vm_get_uuid (VscMgmtError *error,
 288                       const VscMgmtIpv4 *vm_ipv4,
 289                       VscMgmtUuid *vm_uuid);
 290
 291 void
 292 vsc_mgmt_vm_get_host (VscMgmtError *error,
 293                       const VscMgmtUuid *vm_uuid,
 294                       VscMgmtIpv4 *host_ipv4);
 295
 296 VscMgmtVmState /* vm_state */
 297 vsc_mgmt_vm_get_state (VscMgmtError *error,
 298                        const VscMgmtUuid *vm_uuid);
 299
 300 void
 301 vsc_mgmt_vm_set_resource_config (VscMgmtError *error,
 302                                  const VscMgmtUuid *vm_uuid,
 303                                  const VscMgmtVmResourceConfig *vm_resource_config);
 304
 305 void
 306 vsc_mgmt_vm_get_resource_config (VscMgmtError *error,
 307                                  const VscMgmtUuid *vm_uuid,
 308                                  VscMgmtVmResourceConfig *vm_resource_config);
 309
 310 void
 311 vsc_mgmt_vm_get_network_config (VscMgmtError *error,
 312                                 const VscMgmtUuid *vm_uuid,
 313                                 VscMgmtVmNetworkConfig *vm_network_config);
 314
 315 /*
 316  * Suspension
 317  */
 318
 319 void
 320 vsc_mgmt_suspension_create (VscMgmtError *error,
 321                             const VscMgmtUuid *vm_uuid_list,
 322                             VscMgmtUuid *suspension_uuid);
 323
 324 void
 325 vsc_mgmt_suspension_resume (VscMgmtError *error,
 326                             const VscMgmtUuid *suspension_uuid);
 327
 328 void
 329 vsc_mgmt_suspension_get_info (VscMgmtError *error,
 330                               const VscMgmtUuid *suspension_uuid,
 331                               VscMgmtSuspensionInfo *suspension_info);
 332
 333 /*
 334  * Checkpoint
 335  */
 336
 337 void
 338 vsc_mgmt_checkpoint_create (VscMgmtError *error,
 339                             const VscMgmtUuid *vm_uuid_list,
 340                             VscMgmtUuid *checkpoint_uuid);
 341
 342 void
 343 vsc_mgmt_checkpoint_delete (VscMgmtError *error,
 344                             const VscMgmtUuid *checkpoint_uuid);
 345
 346 void
 347 vsc_mgmt_checkpoint_restore (VscMgmtError *error,
 348                              const VscMgmtUuid *checkpoint_uuid);
 349
 350 void
 351 vsc_mgmt_checkpoint_get_info (VscMgmtError *error,
 352                               const VscMgmtUuid *checkpoint_uuid,
 353                               VscMgmtCheckpointInfo *checkpoint_info);
 354
 355 /*
 356  * Host
 357  */
 358
 359 void
 360 vsc_mgmt_host_add (VscMgmtError *error,
 361                    const VscMgmtHostInfo *host_info);
 362
 363 void
 364 vsc_mgmt_host_remove (VscMgmtError *error,
 365                       const VscMgmtIpv4 *host_ipv4);
 366
 367 void
 368 vsc_mgmt_host_get_info (VscMgmtError *error,
 369                         const VscMgmtIpv4 *host_ipv4,
 370                         VscMgmtHostInfo *host_info);
 371
 372 /**
 373  * Returns a UUID list representing all virtual machines currently available
 374  * on the given host.
 375  *
 376  * The list must be freed by the caller via the vsc_mgmt_uuid_list_free
 377  * function.
 378  */
 379 VscMgmtUuid * /* vm_uuid_list */
 380 vsc_mgmt_host_get_vm_list (VscMgmtError *error,
 381                            const VscMgmtIpv4 *host_ipv4);
 382
 383 /*
 384  * Host Type
 385  */
 386
 387 /**
 388  * Parses a host type from its string representation and returns it.
 389  */
 390 VscMgmtHostType /* host_type */
 391 vsc_mgmt_host_type_parse (VscMgmtError *error,
 392                           const char *host_type_string);
 393
 394 /**
 395  * Returns the string representaion of the given host type.
 396  *
 397  * The string must not be freed by the caller.
 398  */
 399 const char * /* host_type_string */
 400 vsc_mgmt_host_type_string (VscMgmtHostType host_type);
 401
 402 /*
 403  * Misc
 404  */
 405
 406 /**
 407  * Returns an IPv4 list representing all currently known host.
 408  *
 409  * The list must be freed by the caller via the vsc_mgmt_ipv4_list_free
 410  * function.
 411  */
 412 VscMgmtIpv4 * /* host_ipv4_list */
 413 vsc_mgmt_get_host_list (VscMgmtError *error);
 414
 415 VscMgmtUuid * /* checkpoint_uuid_list */
 416 vsc_mgmt_get_checkpoint_list (VscMgmtError *error);
 417
 418 VscMgmtUuidType /* uuid_type */
 419 vsc_mgmt_get_uuid_type (VscMgmtError *error, const VscMgmtUuid *uuid);
 420
 421 void
 422 vsc_mgmt_get_version (int *major, int *minor, int *patch);
 423
 424 #ifdef __cplusplus
 425 }
 426 #endif
 427
 428 #endif /* __VSC_MGMT_H__ */