VirtualBox

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

Last change on this file since 13762 was 13580, checked in by vboxsync, 16 years ago

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use