VirtualBox

source: vbox/trunk/src/VBox/Main/testcase/tstVBoxAPILinux.cpp@ 37952

Last change on this file since 37952 was 37662, checked in by vboxsync, 13 years ago

eliminate unneeded include file

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 22.2 KB
Line 
1/** @file
2 *
3 * tstVBoxAPILinux - sample program to illustrate the VirtualBox
4 * XPCOM API for machine management on Linux.
5 * It only uses standard C/C++ and XPCOM semantics,
6 * no additional VBox classes/macros/helpers.
7 */
8
9/*
10 * Copyright (C) 2006-2011 Oracle Corporation
11 *
12 * This file is part of VirtualBox Open Source Edition (OSE), as
13 * available from http://www.virtualbox.org. This file is free software;
14 * you can redistribute it and/or modify it under the terms of the GNU
15 * General Public License (GPL) as published by the Free Software
16 * Foundation, in version 2 as it comes in the "COPYING" file of the
17 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
18 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
19 */
20
21/*
22 * PURPOSE OF THIS SAMPLE PROGRAM
23 * ------------------------------
24 *
25 * This sample program is intended to demonstrate the minimal code necessary
26 * to use VirtualBox XPCOM API for learning puroses only. The program uses
27 * pure XPCOM and doesn't have any extra dependencies to let you better
28 * understand what is going on when a client talks to the VirtualBox core
29 * using the XPCOM framework.
30 *
31 * However, if you want to write a real application, it is highly recommended
32 * to use our MS COM XPCOM Glue library and helper C++ classes. This way, you
33 * will get at least the following benefits:
34 *
35 * a) better portability: both the MS COM (used on Windows) and XPCOM (used
36 * everywhere else) VirtualBox client application from the same source code
37 * (including common smart C++ templates for automatic interface pointer
38 * reference counter and string data management);
39 * b) simpler XPCOM initialization and shutdown (only a single method call
40 * that does everything right).
41 *
42 * Currently, there is no separate sample program that uses the VirtualBox MS
43 * COM XPCOM Glue library. Please refer to the sources of stock VirtualBox
44 * applications such as the VirtualBox GUI frontend or the VBoxManage command
45 * line frontend.
46 *
47 *
48 * RUNNING THIS SAMPLE PROGRAM
49 * ---------------------------
50 *
51 * This sample program needs to know where the VirtualBox core files reside
52 * and where to search for VirtualBox shared libraries. Therefore, you need to
53 * use the following (or similar) command to execute it:
54 *
55 * $ env VBOX_XPCOM_HOME=../../.. LD_LIBRARY_PATH=../../.. ./tstVBoxAPILinux
56 *
57 * The above command assumes that VBoxRT.so, VBoxXPCOM.so and others reside in
58 * the directory ../../..
59 */
60
61
62#include <stdio.h>
63#include <stdlib.h>
64#include <iconv.h>
65
66/*
67 * Include the XPCOM headers
68 */
69
70#if defined(XPCOM_GLUE)
71#include <nsXPCOMGlue.h>
72#endif
73
74#include <nsMemory.h>
75#include <nsString.h>
76#include <nsIServiceManager.h>
77#include <nsEventQueueUtils.h>
78
79#include <nsIExceptionService.h>
80
81/*
82 * VirtualBox XPCOM interface. This header is generated
83 * from IDL which in turn is generated from a custom XML format.
84 */
85#include "VirtualBox_XPCOM.h"
86
87/*
88 * Prototypes
89 */
90
91char *nsIDToString(nsID *guid);
92void printErrorInfo();
93
94
95/**
96 * Display all registered VMs on the screen with some information about each
97 *
98 * @param virtualBox VirtualBox instance object.
99 */
100void listVMs(IVirtualBox *virtualBox)
101{
102 nsresult rc;
103
104 printf("----------------------------------------------------\n");
105 printf("VM List:\n\n");
106
107 /*
108 * Get the list of all registered VMs
109 */
110 IMachine **machines = NULL;
111 PRUint32 machineCnt = 0;
112
113 rc = virtualBox->GetMachines(&machineCnt, &machines);
114 if (NS_SUCCEEDED(rc))
115 {
116 /*
117 * Iterate through the collection
118 */
119 for (PRUint32 i = 0; i < machineCnt; ++ i)
120 {
121 IMachine *machine = machines[i];
122 if (machine)
123 {
124 PRBool isAccessible = PR_FALSE;
125 machine->GetAccessible(&isAccessible);
126
127 if (isAccessible)
128 {
129 nsXPIDLString machineName;
130 machine->GetName(getter_Copies(machineName));
131 char *machineNameAscii = ToNewCString(machineName);
132 printf("\tName: %s\n", machineNameAscii);
133 free(machineNameAscii);
134 }
135 else
136 {
137 printf("\tName: <inaccessible>\n");
138 }
139
140 nsXPIDLString iid;
141 machine->GetId(getter_Copies(iid));
142 const char *uuidString = ToNewCString(iid);
143 printf("\tUUID: %s\n", uuidString);
144 free((void*)uuidString);
145
146 if (isAccessible)
147 {
148 nsXPIDLString configFile;
149 machine->GetSettingsFilePath(getter_Copies(configFile));
150 char *configFileAscii = ToNewCString(configFile);
151 printf("\tConfig file: %s\n", configFileAscii);
152 free(configFileAscii);
153
154 PRUint32 memorySize;
155 machine->GetMemorySize(&memorySize);
156 printf("\tMemory size: %uMB\n", memorySize);
157
158 nsXPIDLString typeId;
159 machine->GetOSTypeId(getter_Copies(typeId));
160 IGuestOSType *osType = nsnull;
161 virtualBox->GetGuestOSType (typeId.get(), &osType);
162 nsXPIDLString osName;
163 osType->GetDescription(getter_Copies(osName));
164 char *osNameAscii = ToNewCString(osName);
165 printf("\tGuest OS: %s\n\n", osNameAscii);
166 free(osNameAscii);
167 osType->Release();
168 }
169
170 /* don't forget to release the objects in the array... */
171 machine->Release();
172 }
173 }
174 }
175 printf("----------------------------------------------------\n\n");
176}
177
178/**
179 * Create a sample VM
180 *
181 * @param virtualBox VirtualBox instance object.
182 */
183void createVM(IVirtualBox *virtualBox)
184{
185 nsresult rc;
186 /*
187 * First create a unnamed new VM. It will be unconfigured and not be saved
188 * in the configuration until we explicitely choose to do so.
189 */
190 nsCOMPtr<IMachine> machine;
191 rc = virtualBox->CreateMachine(NULL, /* settings file */
192 NS_LITERAL_STRING("A brand new name").get(),
193 nsnull, /* ostype */
194 nsnull, /* machine uuid */
195 false, /* forceOverwrite */
196 getter_AddRefs(machine));
197 if (NS_FAILED(rc))
198 {
199 printf("Error: could not create machine! rc=%08X\n", rc);
200 return;
201 }
202
203 /*
204 * Set some properties
205 */
206 /* alternative to illustrate the use of string classes */
207 rc = machine->SetName(NS_ConvertUTF8toUTF16("A new name").get());
208 rc = machine->SetMemorySize(128);
209
210 /*
211 * Now a more advanced property -- the guest OS type. This is
212 * an object by itself which has to be found first. Note that we
213 * use the ID of the guest OS type here which is an internal
214 * representation (you can find that by configuring the OS type of
215 * a machine in the GUI and then looking at the <Guest ostype=""/>
216 * setting in the XML file. It is also possible to get the OS type from
217 * its description (win2k would be "Windows 2000") by getting the
218 * guest OS type collection and enumerating it.
219 */
220 nsCOMPtr<IGuestOSType> osType;
221 rc = virtualBox->GetGuestOSType(NS_LITERAL_STRING("win2k").get(),
222 getter_AddRefs(osType));
223 if (NS_FAILED(rc))
224 {
225 printf("Error: could not find guest OS type! rc=%08X\n", rc);
226 }
227 else
228 {
229 machine->SetOSTypeId (NS_LITERAL_STRING("win2k").get());
230 }
231
232 /*
233 * Register the VM. Note that this call also saves the VM config
234 * to disk. It is also possible to save the VM settings but not
235 * register the VM.
236 *
237 * Also note that due to current VirtualBox limitations, the machine
238 * must be registered *before* we can attach hard disks to it.
239 */
240 rc = virtualBox->RegisterMachine(machine);
241 if (NS_FAILED(rc))
242 {
243 printf("Error: could not register machine! rc=%08X\n", rc);
244 printErrorInfo();
245 return;
246 }
247
248 /*
249 * In order to manipulate the registered machine, we must open a session
250 * for that machine. Do it now.
251 */
252 nsCOMPtr<ISession> session;
253 {
254 nsCOMPtr<nsIComponentManager> manager;
255 rc = NS_GetComponentManager (getter_AddRefs (manager));
256 if (NS_FAILED(rc))
257 {
258 printf("Error: could not get component manager! rc=%08X\n", rc);
259 return;
260 }
261 rc = manager->CreateInstanceByContractID (NS_SESSION_CONTRACTID,
262 nsnull,
263 NS_GET_IID(ISession),
264 getter_AddRefs(session));
265 if (NS_FAILED(rc))
266 {
267 printf("Error, could not instantiate session object! rc=0x%x\n", rc);
268 return;
269 }
270
271 rc = machine->LockMachine(session, LockType_Write);
272 if (NS_FAILED(rc))
273 {
274 printf("Error, could not lock the machine for the session! rc=0x%x\n", rc);
275 return;
276 }
277
278 /*
279 * After the machine is registered, the initial machine object becomes
280 * immutable. In order to get a mutable machine object, we must query
281 * it from the opened session object.
282 */
283 rc = session->GetMachine(getter_AddRefs(machine));
284 if (NS_FAILED(rc))
285 {
286 printf("Error, could not get machine session! rc=0x%x\n", rc);
287 return;
288 }
289 }
290
291 /*
292 * Create a virtual harddisk
293 */
294 nsCOMPtr<IMedium> hardDisk = 0;
295 rc = virtualBox->CreateHardDisk(NS_LITERAL_STRING("VDI").get(),
296 NS_LITERAL_STRING("TestHardDisk.vdi").get(),
297 getter_AddRefs(hardDisk));
298 if (NS_FAILED(rc))
299 {
300 printf("Failed creating a hard disk object! rc=%08X\n", rc);
301 }
302 else
303 {
304 /*
305 * We have only created an object so far. No on disk representation exists
306 * because none of its properties has been set so far. Let's continue creating
307 * a dynamically expanding image.
308 */
309 nsCOMPtr <IProgress> progress;
310 rc = hardDisk->CreateBaseStorage(100, // size in megabytes
311 MediumVariant_Standard,
312 getter_AddRefs(progress)); // optional progress object
313 if (NS_FAILED(rc))
314 {
315 printf("Failed creating hard disk image! rc=%08X\n", rc);
316 }
317 else
318 {
319 /*
320 * Creating the image is done in the background because it can take quite
321 * some time (at least fixed size images). We have to wait for its completion.
322 * Here we wait forever (timeout -1) which is potentially dangerous.
323 */
324 rc = progress->WaitForCompletion(-1);
325 PRInt32 resultCode;
326 progress->GetResultCode(&resultCode);
327 if (NS_FAILED(rc) || NS_FAILED(resultCode))
328 {
329 printf("Error: could not create hard disk! rc=%08X\n",
330 NS_FAILED(rc) ? rc : resultCode);
331 }
332 else
333 {
334 /*
335 * Now that it's created, we can assign it to the VM.
336 */
337 rc = machine->AttachDevice(NS_LITERAL_STRING("IDE Controller").get(), // controller identifier
338 0, // channel number on the controller
339 0, // device number on the controller
340 DeviceType_HardDisk,
341 hardDisk);
342 if (NS_FAILED(rc))
343 {
344 printf("Error: could not attach hard disk! rc=%08X\n", rc);
345 }
346 }
347 }
348 }
349
350 /*
351 * It's got a hard disk but that one is new and thus not bootable. Make it
352 * boot from an ISO file. This requires some processing. First the ISO file
353 * has to be registered and then mounted to the VM's DVD drive and selected
354 * as the boot device.
355 */
356 nsCOMPtr<IMedium> dvdImage;
357 rc = virtualBox->OpenMedium(NS_LITERAL_STRING("/home/vbox/isos/winnt4ger.iso").get(),
358 DeviceType_DVD,
359 AccessMode_ReadOnly,
360 false /* fForceNewUuid */,
361 getter_AddRefs(dvdImage));
362 if (NS_FAILED(rc))
363 printf("Error: could not open CD image! rc=%08X\n", rc);
364 else
365 {
366 /*
367 * Now assign it to our VM
368 */
369 rc = machine->MountMedium(NS_LITERAL_STRING("IDE Controller").get(), // controller identifier
370 2, // channel number on the controller
371 0, // device number on the controller
372 dvdImage,
373 PR_FALSE); // aForce
374 if (NS_FAILED(rc))
375 {
376 printf("Error: could not mount ISO image! rc=%08X\n", rc);
377 }
378 else
379 {
380 /*
381 * Last step: tell the VM to boot from the CD.
382 */
383 rc = machine->SetBootOrder (1, DeviceType::DVD);
384 if (NS_FAILED(rc))
385 {
386 printf("Could not set boot device! rc=%08X\n", rc);
387 }
388 }
389 }
390
391 /*
392 * Save all changes we've just made.
393 */
394 rc = machine->SaveSettings();
395 if (NS_FAILED(rc))
396 {
397 printf("Could not save machine settings! rc=%08X\n", rc);
398 }
399
400 /*
401 * It is always important to close the open session when it becomes not
402 * necessary any more.
403 */
404 session->UnlockMachine();
405}
406
407// main
408///////////////////////////////////////////////////////////////////////////////
409
410int main(int argc, char *argv[])
411{
412 /*
413 * Check that PRUnichar is equal in size to what compiler composes L""
414 * strings from; otherwise NS_LITERAL_STRING macros won't work correctly
415 * and we will get a meaningless SIGSEGV. This, of course, must be checked
416 * at compile time in xpcom/string/nsTDependentString.h, but XPCOM lacks
417 * compile-time assert macros and I'm not going to add them now.
418 */
419 if (sizeof(PRUnichar) != sizeof(wchar_t))
420 {
421 printf("Error: sizeof(PRUnichar) {%lu} != sizeof(wchar_t) {%lu}!\n"
422 "Probably, you forgot the -fshort-wchar compiler option.\n",
423 (unsigned long) sizeof(PRUnichar),
424 (unsigned long) sizeof(wchar_t));
425 return -1;
426 }
427
428 nsresult rc;
429
430 /*
431 * This is the standard XPCOM init procedure.
432 * What we do is just follow the required steps to get an instance
433 * of our main interface, which is IVirtualBox.
434 */
435#if defined(XPCOM_GLUE)
436 XPCOMGlueStartup(nsnull);
437#endif
438
439 /*
440 * Note that we scope all nsCOMPtr variables in order to have all XPCOM
441 * objects automatically released before we call NS_ShutdownXPCOM at the
442 * end. This is an XPCOM requirement.
443 */
444 {
445 nsCOMPtr<nsIServiceManager> serviceManager;
446 rc = NS_InitXPCOM2(getter_AddRefs(serviceManager), nsnull, nsnull);
447 if (NS_FAILED(rc))
448 {
449 printf("Error: XPCOM could not be initialized! rc=0x%x\n", rc);
450 return -1;
451 }
452
453#if 0
454 /*
455 * Register our components. This step is only necessary if this executable
456 * implements XPCOM components itself which is not the case for this
457 * simple example.
458 */
459 nsCOMPtr<nsIComponentRegistrar> registrar = do_QueryInterface(serviceManager);
460 if (!registrar)
461 {
462 printf("Error: could not query nsIComponentRegistrar interface!\n");
463 return -1;
464 }
465 registrar->AutoRegister(nsnull);
466#endif
467
468 /*
469 * Make sure the main event queue is created. This event queue is
470 * responsible for dispatching incoming XPCOM IPC messages. The main
471 * thread should run this event queue's loop during lengthy non-XPCOM
472 * operations to ensure messages from the VirtualBox server and other
473 * XPCOM IPC clients are processed. This use case doesn't perform such
474 * operations so it doesn't run the event loop.
475 */
476 nsCOMPtr<nsIEventQueue> eventQ;
477 rc = NS_GetMainEventQ(getter_AddRefs (eventQ));
478 if (NS_FAILED(rc))
479 {
480 printf("Error: could not get main event queue! rc=%08X\n", rc);
481 return -1;
482 }
483
484 /*
485 * Now XPCOM is ready and we can start to do real work.
486 * IVirtualBox is the root interface of VirtualBox and will be
487 * retrieved from the XPCOM component manager. We use the
488 * XPCOM provided smart pointer nsCOMPtr for all objects because
489 * that's very convenient and removes the need deal with reference
490 * counting and freeing.
491 */
492 nsCOMPtr<nsIComponentManager> manager;
493 rc = NS_GetComponentManager (getter_AddRefs (manager));
494 if (NS_FAILED(rc))
495 {
496 printf("Error: could not get component manager! rc=%08X\n", rc);
497 return -1;
498 }
499
500 nsCOMPtr<IVirtualBox> virtualBox;
501 rc = manager->CreateInstanceByContractID (NS_VIRTUALBOX_CONTRACTID,
502 nsnull,
503 NS_GET_IID(IVirtualBox),
504 getter_AddRefs(virtualBox));
505 if (NS_FAILED(rc))
506 {
507 printf("Error, could not instantiate VirtualBox object! rc=0x%x\n", rc);
508 return -1;
509 }
510 printf("VirtualBox object created\n");
511
512 ////////////////////////////////////////////////////////////////////////////////
513 ////////////////////////////////////////////////////////////////////////////////
514 ////////////////////////////////////////////////////////////////////////////////
515
516
517 listVMs(virtualBox);
518
519 createVM(virtualBox);
520
521
522 ////////////////////////////////////////////////////////////////////////////////
523 ////////////////////////////////////////////////////////////////////////////////
524 ////////////////////////////////////////////////////////////////////////////////
525
526 /* this is enough to free the IVirtualBox instance -- smart pointers rule! */
527 virtualBox = nsnull;
528
529 /*
530 * Process events that might have queued up in the XPCOM event
531 * queue. If we don't process them, the server might hang.
532 */
533 eventQ->ProcessPendingEvents();
534 }
535
536 /*
537 * Perform the standard XPCOM shutdown procedure.
538 */
539 NS_ShutdownXPCOM(nsnull);
540#if defined(XPCOM_GLUE)
541 XPCOMGlueShutdown();
542#endif
543 printf("Done!\n");
544 return 0;
545}
546
547
548//////////////////////////////////////////////////////////////////////////////////////////////////////
549//// Helpers
550//////////////////////////////////////////////////////////////////////////////////////////////////////
551
552/**
553 * Helper function to convert an nsID into a human readable string
554 *
555 * @returns result string, allocated. Has to be freed using free()
556 * @param guid Pointer to nsID that will be converted.
557 */
558char *nsIDToString(nsID *guid)
559{
560 char *res = (char*)malloc(39);
561
562 if (res != NULL)
563 {
564 snprintf(res, 39, "{%08x-%04x-%04x-%02x%02x-%02x%02x%02x%02x%02x%02x}",
565 guid->m0, (PRUint32)guid->m1, (PRUint32)guid->m2,
566 (PRUint32)guid->m3[0], (PRUint32)guid->m3[1], (PRUint32)guid->m3[2],
567 (PRUint32)guid->m3[3], (PRUint32)guid->m3[4], (PRUint32)guid->m3[5],
568 (PRUint32)guid->m3[6], (PRUint32)guid->m3[7]);
569 }
570 return res;
571}
572
573/**
574 * Helper function to print XPCOM exception information set on the current
575 * thread after a failed XPCOM method call. This function will also print
576 * extended VirtualBox error info if it is available.
577 */
578void printErrorInfo()
579{
580 nsresult rc;
581
582 nsCOMPtr <nsIExceptionService> es;
583 es = do_GetService (NS_EXCEPTIONSERVICE_CONTRACTID, &rc);
584 if (NS_SUCCEEDED(rc))
585 {
586 nsCOMPtr <nsIExceptionManager> em;
587 rc = es->GetCurrentExceptionManager (getter_AddRefs (em));
588 if (NS_SUCCEEDED(rc))
589 {
590 nsCOMPtr<nsIException> ex;
591 rc = em->GetCurrentException (getter_AddRefs (ex));
592 if (NS_SUCCEEDED(rc) && ex)
593 {
594 nsCOMPtr <IVirtualBoxErrorInfo> info;
595 info = do_QueryInterface(ex, &rc);
596 if (NS_SUCCEEDED(rc) && info)
597 {
598 /* got extended error info */
599 printf ("Extended error info (IVirtualBoxErrorInfo):\n");
600 PRInt32 resultCode = NS_OK;
601 info->GetResultCode (&resultCode);
602 printf (" resultCode=%08X\n", resultCode);
603 nsXPIDLString component;
604 info->GetComponent (getter_Copies (component));
605 printf (" component=%s\n", NS_ConvertUTF16toUTF8(component).get());
606 nsXPIDLString text;
607 info->GetText (getter_Copies (text));
608 printf (" text=%s\n", NS_ConvertUTF16toUTF8(text).get());
609 }
610 else
611 {
612 /* got basic error info */
613 printf ("Basic error info (nsIException):\n");
614 nsresult resultCode = NS_OK;
615 ex->GetResult (&resultCode);
616 printf (" resultCode=%08X\n", resultCode);
617 nsXPIDLCString message;
618 ex->GetMessage (getter_Copies (message));
619 printf (" message=%s\n", message.get());
620 }
621
622 /* reset the exception to NULL to indicate we've processed it */
623 em->SetCurrentException (NULL);
624
625 rc = NS_OK;
626 }
627 }
628 }
629}
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette