tstVBoxAPIXPCOM.cpp@ 50269

Last change on this file since 50269 was 50117, checked in by vboxsync, 11 years ago
Main+Frontends: clear out some cruft code, outdated EventQueue stuff and whitespace cleanup
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 23.5 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-2014 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	#include <nsMemory.h>
70	#include <nsString.h>
71	#include <nsIServiceManager.h>
72	#include <nsEventQueueUtils.h>
73
74	#include <nsIExceptionService.h>
75
76	#include <VBox/com/com.h>
77	#include <VBox/com/string.h>
78	#include <VBox/com/array.h>
79	#include <VBox/com/Guid.h>
80	#include <VBox/com/ErrorInfo.h>
81	#include <VBox/com/errorprint.h>
82
83	#include <VBox/com/VirtualBox.h>
84
85	#include <iprt/stream.h>
86
87
88	/*
89	* VirtualBox XPCOM interface. This header is generated
90	* from IDL which in turn is generated from a custom XML format.
91	*/
92	#include "VirtualBox_XPCOM.h"
93
94	/*
95	* Prototypes
96	*/
97
98	char nsIDToString(nsID guid);
99	void printErrorInfo();
100
101
102	/**
103	* Display all registered VMs on the screen with some information about each
104	*
105	* @param virtualBox VirtualBox instance object.
106	*/
107	void listVMs(IVirtualBox *virtualBox)
108	{
109	nsresult rc;
110
111	RTPrintf("----------------------------------------------------\n");
112	RTPrintf("VM List:\n\n");
113
114	/*
115	* Get the list of all registered VMs
116	*/
117	IMachine **machines = NULL;
118	PRUint32 machineCnt = 0;
119
120	rc = virtualBox->GetMachines(&machineCnt, &machines);
121	if (NS_SUCCEEDED(rc))
122	{
123	/*
124	* Iterate through the collection
125	*/
126	for (PRUint32 i = 0; i < machineCnt; ++ i)
127	{
128	IMachine *machine = machines[i];
129	if (machine)
130	{
131	PRBool isAccessible = PR_FALSE;
132	machine->GetAccessible(&isAccessible);
133
134	if (isAccessible)
135	{
136	nsXPIDLString machineName;
137	machine->GetName(getter_Copies(machineName));
138	char *machineNameAscii = ToNewCString(machineName);
139	RTPrintf("\tName: %s\n", machineNameAscii);
140	free(machineNameAscii);
141	}
142	else
143	{
144	RTPrintf("\tName: <inaccessible>\n");
145	}
146
147	nsXPIDLString iid;
148	machine->GetId(getter_Copies(iid));
149	const char *uuidString = ToNewCString(iid);
150	RTPrintf("\tUUID: %s\n", uuidString);
151	free((void*)uuidString);
152
153	if (isAccessible)
154	{
155	nsXPIDLString configFile;
156	machine->GetSettingsFilePath(getter_Copies(configFile));
157	char *configFileAscii = ToNewCString(configFile);
158	RTPrintf("\tConfig file: %s\n", configFileAscii);
159	free(configFileAscii);
160
161	PRUint32 memorySize;
162	machine->GetMemorySize(&memorySize);
163	RTPrintf("\tMemory size: %uMB\n", memorySize);
164
165	nsXPIDLString typeId;
166	machine->GetOSTypeId(getter_Copies(typeId));
167	IGuestOSType *osType = nsnull;
168	virtualBox->GetGuestOSType(typeId.get(), &osType);
169	nsXPIDLString osName;
170	osType->GetDescription(getter_Copies(osName));
171	char *osNameAscii = ToNewCString(osName);
172	RTPrintf("\tGuest OS: %s\n\n", osNameAscii);
173	free(osNameAscii);
174	osType->Release();
175	}
176
177	/* don't forget to release the objects in the array... */
178	machine->Release();
179	}
180	}
181	}
182	RTPrintf("----------------------------------------------------\n\n");
183	}
184
185	/**
186	* Create a sample VM
187	*
188	* @param virtualBox VirtualBox instance object.
189	*/
190	void createVM(IVirtualBox *virtualBox)
191	{
192	nsresult rc;
193	/*
194	* First create a unnamed new VM. It will be unconfigured and not be saved
195	* in the configuration until we explicitely choose to do so.
196	*/
197	nsCOMPtr<IMachine> machine;
198	rc = virtualBox->CreateMachine(NULL, /* settings file */
199	NS_LITERAL_STRING("A brand new name").get(),
200	0, nsnull, /* groups (safearray)*/
201	nsnull, /* ostype */
202	nsnull, /* create flags */
203	getter_AddRefs(machine));
204	if (NS_FAILED(rc))
205	{
206	RTPrintf("Error: could not create machine! rc=%Rhrc\n", rc);
207	return;
208	}
209
210	/*
211	* Set some properties
212	*/
213	/* alternative to illustrate the use of string classes */
214	rc = machine->SetName(NS_ConvertUTF8toUTF16("A new name").get());
215	rc = machine->SetMemorySize(128);
216
217	/*
218	* Now a more advanced property -- the guest OS type. This is
219	* an object by itself which has to be found first. Note that we
220	* use the ID of the guest OS type here which is an internal
221	* representation (you can find that by configuring the OS type of
222	* a machine in the GUI and then looking at the <Guest ostype=""/>
223	* setting in the XML file. It is also possible to get the OS type from
224	* its description (win2k would be "Windows 2000") by getting the
225	* guest OS type collection and enumerating it.
226	*/
227	nsCOMPtr<IGuestOSType> osType;
228	rc = virtualBox->GetGuestOSType(NS_LITERAL_STRING("Windows2000").get(),
229	getter_AddRefs(osType));
230	if (NS_FAILED(rc))
231	{
232	RTPrintf("Error: could not find guest OS type! rc=%Rhrc\n", rc);
233	}
234	else
235	{
236	machine->SetOSTypeId(NS_LITERAL_STRING("Windows2000").get());
237	}
238
239	/*
240	* Register the VM. Note that this call also saves the VM config
241	* to disk. It is also possible to save the VM settings but not
242	* register the VM.
243	*
244	* Also note that due to current VirtualBox limitations, the machine
245	* must be registered before we can attach hard disks to it.
246	*/
247	rc = virtualBox->RegisterMachine(machine);
248	if (NS_FAILED(rc))
249	{
250	RTPrintf("Error: could not register machine! rc=%Rhrc\n", rc);
251	printErrorInfo();
252	return;
253	}
254
255	nsCOMPtr<IMachine> origMachine = machine;
256
257	/*
258	* In order to manipulate the registered machine, we must open a session
259	* for that machine. Do it now.
260	*/
261	nsCOMPtr<ISession> session;
262	nsCOMPtr<IMachine> sessionMachine;
263	{
264	nsCOMPtr<nsIComponentManager> manager;
265	rc = NS_GetComponentManager(getter_AddRefs(manager));
266	if (NS_FAILED(rc))
267	{
268	RTPrintf("Error: could not get component manager! rc=%Rhrc\n", rc);
269	return;
270	}
271	rc = manager->CreateInstanceByContractID(NS_SESSION_CONTRACTID,
272	nsnull,
273	NS_GET_IID(ISession),
274	getter_AddRefs(session));
275	if (NS_FAILED(rc))
276	{
277	RTPrintf("Error, could not instantiate session object! rc=%Rhrc\n", rc);
278	return;
279	}
280
281	rc = machine->LockMachine(session, LockType_Write);
282	if (NS_FAILED(rc))
283	{
284	RTPrintf("Error, could not lock the machine for the session! rc=%Rhrc\n", rc);
285	return;
286	}
287
288	/*
289	* After the machine is registered, the initial machine object becomes
290	* immutable. In order to get a mutable machine object, we must query
291	* it from the opened session object.
292	*/
293	rc = session->GetMachine(getter_AddRefs(sessionMachine));
294	if (NS_FAILED(rc))
295	{
296	RTPrintf("Error, could not get machine session! rc=%Rhrc\n", rc);
297	return;
298	}
299	}
300
301	/*
302	* Create a virtual harddisk
303	*/
304	nsCOMPtr<IMedium> hardDisk = 0;
305	rc = virtualBox->CreateHardDisk(NS_LITERAL_STRING("VDI").get(),
306	NS_LITERAL_STRING("TestHardDisk.vdi").get(),
307	getter_AddRefs(hardDisk));
308	if (NS_FAILED(rc))
309	{
310	RTPrintf("Failed creating a hard disk object! rc=%Rhrc\n", rc);
311	}
312	else
313	{
314	/*
315	* We have only created an object so far. No on disk representation exists
316	* because none of its properties has been set so far. Let's continue creating
317	* a dynamically expanding image.
318	*/
319	nsCOMPtr<IProgress> progress;
320	com::SafeArray<MediumVariant_T> mediumVariant;
321	mediumVariant.push_back(MediumVariant_Standard);
322	rc = hardDisk->CreateBaseStorage(100, // size in megabytes
323	ComSafeArrayAsInParam(mediumVariant),
324	getter_AddRefs(progress)); // optional progress object
325	if (NS_FAILED(rc))
326	{
327	RTPrintf("Failed creating hard disk image! rc=%Rhrc\n", rc);
328	}
329	else
330	{
331	/*
332	* Creating the image is done in the background because it can take quite
333	* some time (at least fixed size images). We have to wait for its completion.
334	* Here we wait forever (timeout -1) which is potentially dangerous.
335	*/
336	rc = progress->WaitForCompletion(-1);
337	PRInt32 resultCode;
338	progress->GetResultCode(&resultCode);
339	if (NS_FAILED(rc) \|\| NS_FAILED(resultCode))
340	{
341	RTPrintf("Error: could not create hard disk! rc=%Rhrc\n",
342	NS_FAILED(rc) ? rc : resultCode);
343	}
344	else
345	{
346	/*
347	* Now that it's created, we can assign it to the VM.
348	*/
349	rc = sessionMachine->AttachDevice(
350	NS_LITERAL_STRING("IDE Controller").get(), // controller identifier
351	0, // channel number on the controller
352	0, // device number on the controller
353	DeviceType_HardDisk,
354	hardDisk);
355	if (NS_FAILED(rc))
356	{
357	RTPrintf("Error: could not attach hard disk! rc=%Rhrc\n", rc);
358	}
359	}
360	}
361	}
362
363	/*
364	* It's got a hard disk but that one is new and thus not bootable. Make it
365	* boot from an ISO file. This requires some processing. First the ISO file
366	* has to be registered and then mounted to the VM's DVD drive and selected
367	* as the boot device.
368	*/
369	nsCOMPtr<IMedium> dvdImage;
370	rc = virtualBox->OpenMedium(NS_LITERAL_STRING("/home/vbox/isos/winnt4ger.iso").get(),
371	DeviceType_DVD,
372	AccessMode_ReadOnly,
373	false /* fForceNewUuid */,
374	getter_AddRefs(dvdImage));
375	if (NS_FAILED(rc))
376	RTPrintf("Error: could not open CD image! rc=%Rhrc\n", rc);
377	else
378	{
379	/*
380	* Now assign it to our VM
381	*/
382	rc = sessionMachine->MountMedium(
383	NS_LITERAL_STRING("IDE Controller").get(), // controller identifier
384	2, // channel number on the controller
385	0, // device number on the controller
386	dvdImage,
387	PR_FALSE); // aForce
388	if (NS_FAILED(rc))
389	{
390	RTPrintf("Error: could not mount ISO image! rc=%Rhrc\n", rc);
391	}
392	else
393	{
394	/*
395	* Last step: tell the VM to boot from the CD.
396	*/
397	rc = sessionMachine->SetBootOrder(1, DeviceType::DVD);
398	if (NS_FAILED(rc))
399	{
400	RTPrintf("Could not set boot device! rc=%Rhrc\n", rc);
401	}
402	}
403	}
404
405	/*
406	* Save all changes we've just made.
407	*/
408	rc = sessionMachine->SaveSettings();
409	if (NS_FAILED(rc))
410	RTPrintf("Could not save machine settings! rc=%Rhrc\n", rc);
411
412	/*
413	* It is always important to close the open session when it becomes not
414	* necessary any more.
415	*/
416	session->UnlockMachine();
417
418	com::SafeIfaceArray<IMedium> aMedia;
419	rc = machine->Unregister((CleanupMode_T)CleanupMode_DetachAllReturnHardDisksOnly,
420	ComSafeArrayAsOutParam(aMedia));
421	if (NS_FAILED(rc))
422	RTPrintf("Unregistering the machine failed! rc=%Rhrc\n", rc);
423	else
424	{
425	ComPtr<IProgress> pProgress;
426	rc = machine->DeleteConfig(ComSafeArrayAsInParam(aMedia), pProgress.asOutParam());
427	if (NS_FAILED(rc))
428	RTPrintf("Deleting of machine failed! rc=%Rhrc\n", rc);
429	else
430	{
431	rc = pProgress->WaitForCompletion(-1);
432	PRInt32 resultCode;
433	pProgress->GetResultCode(&resultCode);
434	if (NS_FAILED(rc) \|\| NS_FAILED(resultCode))
435	RTPrintf("Failed to delete the machine! rc=%Rhrc\n",
436	NS_FAILED(rc) ? rc : resultCode);
437	}
438	}
439	}
440
441	// main
442	///////////////////////////////////////////////////////////////////////////////
443
444	int main(int argc, char *argv[])
445	{
446	/*
447	* Check that PRUnichar is equal in size to what compiler composes L""
448	* strings from; otherwise NS_LITERAL_STRING macros won't work correctly
449	* and we will get a meaningless SIGSEGV. This, of course, must be checked
450	* at compile time in xpcom/string/nsTDependentString.h, but XPCOM lacks
451	* compile-time assert macros and I'm not going to add them now.
452	*/
453	if (sizeof(PRUnichar) != sizeof(wchar_t))
454	{
455	RTPrintf("Error: sizeof(PRUnichar) {%lu} != sizeof(wchar_t) {%lu}!\n"
456	"Probably, you forgot the -fshort-wchar compiler option.\n",
457	(unsigned long) sizeof(PRUnichar),
458	(unsigned long) sizeof(wchar_t));
459	return -1;
460	}
461
462	nsresult rc;
463
464	/*
465	* This is the standard XPCOM init procedure.
466	* What we do is just follow the required steps to get an instance
467	* of our main interface, which is IVirtualBox.
468	*
469	* Note that we scope all nsCOMPtr variables in order to have all XPCOM
470	* objects automatically released before we call NS_ShutdownXPCOM at the
471	* end. This is an XPCOM requirement.
472	*/
473	{
474	nsCOMPtr<nsIServiceManager> serviceManager;
475	rc = NS_InitXPCOM2(getter_AddRefs(serviceManager), nsnull, nsnull);
476	if (NS_FAILED(rc))
477	{
478	RTPrintf("Error: XPCOM could not be initialized! rc=%Rhrc\n", rc);
479	return -1;
480	}
481
482	#if 0
483	/*
484	* Register our components. This step is only necessary if this executable
485	* implements XPCOM components itself which is not the case for this
486	* simple example.
487	*/
488	nsCOMPtr<nsIComponentRegistrar> registrar = do_QueryInterface(serviceManager);
489	if (!registrar)
490	{
491	RTPrintf("Error: could not query nsIComponentRegistrar interface!\n");
492	return -1;
493	}
494	registrar->AutoRegister(nsnull);
495	#endif
496
497	/*
498	* Make sure the main event queue is created. This event queue is
499	* responsible for dispatching incoming XPCOM IPC messages. The main
500	* thread should run this event queue's loop during lengthy non-XPCOM
501	* operations to ensure messages from the VirtualBox server and other
502	* XPCOM IPC clients are processed. This use case doesn't perform such
503	* operations so it doesn't run the event loop.
504	*/
505	nsCOMPtr<nsIEventQueue> eventQ;
506	rc = NS_GetMainEventQ(getter_AddRefs(eventQ));
507	if (NS_FAILED(rc))
508	{
509	RTPrintf("Error: could not get main event queue! rc=%Rhrc\n", rc);
510	return -1;
511	}
512
513	/*
514	* Now XPCOM is ready and we can start to do real work.
515	* IVirtualBox is the root interface of VirtualBox and will be
516	* retrieved from the XPCOM component manager. We use the
517	* XPCOM provided smart pointer nsCOMPtr for all objects because
518	* that's very convenient and removes the need deal with reference
519	* counting and freeing.
520	*/
521	nsCOMPtr<nsIComponentManager> manager;
522	rc = NS_GetComponentManager(getter_AddRefs(manager));
523	if (NS_FAILED(rc))
524	{
525	RTPrintf("Error: could not get component manager! rc=%Rhrc\n", rc);
526	return -1;
527	}
528
529	nsCOMPtr<IVirtualBox> virtualBox;
530	rc = manager->CreateInstanceByContractID(NS_VIRTUALBOX_CONTRACTID,
531	nsnull,
532	NS_GET_IID(IVirtualBox),
533	getter_AddRefs(virtualBox));
534	if (NS_FAILED(rc))
535	{
536	RTPrintf("Error, could not instantiate VirtualBox object! rc=%Rhrc\n", rc);
537	return -1;
538	}
539	RTPrintf("VirtualBox object created\n");
540
541	////////////////////////////////////////////////////////////////////////////////
542	////////////////////////////////////////////////////////////////////////////////
543	////////////////////////////////////////////////////////////////////////////////
544
545
546	listVMs(virtualBox);
547
548	createVM(virtualBox);
549
550
551	////////////////////////////////////////////////////////////////////////////////
552	////////////////////////////////////////////////////////////////////////////////
553	////////////////////////////////////////////////////////////////////////////////
554
555	/* this is enough to free the IVirtualBox instance -- smart pointers rule! */
556	virtualBox = nsnull;
557
558	/*
559	* Process events that might have queued up in the XPCOM event
560	* queue. If we don't process them, the server might hang.
561	*/
562	eventQ->ProcessPendingEvents();
563	}
564
565	/*
566	* Perform the standard XPCOM shutdown procedure.
567	*/
568	NS_ShutdownXPCOM(nsnull);
569	RTPrintf("Done!\n");
570	return 0;
571	}
572
573
574	//////////////////////////////////////////////////////////////////////////////////////////////////////
575	//// Helpers
576	//////////////////////////////////////////////////////////////////////////////////////////////////////
577
578	/**
579	* Helper function to convert an nsID into a human readable string
580	*
581	* @returns result string, allocated. Has to be freed using free()
582	* @param guid Pointer to nsID that will be converted.
583	*/
584	char nsIDToString(nsID guid)
585	{
586	char res = (char)malloc(39);
587
588	if (res != NULL)
589	{
590	RTStrPrintf(res, 39, "{%08x-%04x-%04x-%02x%02x-%02x%02x%02x%02x%02x%02x}",
591	guid->m0, (PRUint32)guid->m1, (PRUint32)guid->m2,
592	(PRUint32)guid->m3[0], (PRUint32)guid->m3[1], (PRUint32)guid->m3[2],
593	(PRUint32)guid->m3[3], (PRUint32)guid->m3[4], (PRUint32)guid->m3[5],
594	(PRUint32)guid->m3[6], (PRUint32)guid->m3[7]);
595	}
596	return res;
597	}
598
599	/**
600	* Helper function to print XPCOM exception information set on the current
601	* thread after a failed XPCOM method call. This function will also print
602	* extended VirtualBox error info if it is available.
603	*/
604	void printErrorInfo()
605	{
606	nsresult rc;
607
608	nsCOMPtr<nsIExceptionService> es;
609	es = do_GetService(NS_EXCEPTIONSERVICE_CONTRACTID, &rc);
610	if (NS_SUCCEEDED(rc))
611	{
612	nsCOMPtr<nsIExceptionManager> em;
613	rc = es->GetCurrentExceptionManager(getter_AddRefs(em));
614	if (NS_SUCCEEDED(rc))
615	{
616	nsCOMPtr<nsIException> ex;
617	rc = em->GetCurrentException(getter_AddRefs(ex));
618	if (NS_SUCCEEDED(rc) && ex)
619	{
620	nsCOMPtr<IVirtualBoxErrorInfo> info;
621	info = do_QueryInterface(ex, &rc);
622	if (NS_SUCCEEDED(rc) && info)
623	{
624	/* got extended error info */
625	RTPrintf("Extended error info (IVirtualBoxErrorInfo):\n");
626	PRInt32 resultCode = NS_OK;
627	info->GetResultCode(&resultCode);
628	RTPrintf(" resultCode=%08X\n", resultCode);
629	nsXPIDLString component;
630	info->GetComponent(getter_Copies(component));
631	RTPrintf(" component=%s\n", NS_ConvertUTF16toUTF8(component).get());
632	nsXPIDLString text;
633	info->GetText(getter_Copies(text));
634	RTPrintf(" text=%s\n", NS_ConvertUTF16toUTF8(text).get());
635	}
636	else
637	{
638	/* got basic error info */
639	RTPrintf("Basic error info (nsIException):\n");
640	nsresult resultCode = NS_OK;
641	ex->GetResult(&resultCode);
642	RTPrintf(" resultCode=%08X\n", resultCode);
643	nsXPIDLCString message;
644	ex->GetMessage(getter_Copies(message));
645	RTPrintf(" message=%s\n", message.get());
646	}
647
648	/* reset the exception to NULL to indicate we've processed it */
649	em->SetCurrentException(NULL);
650
651	rc = NS_OK;
652	}
653	}
654	}
655	}

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Main/testcase/tstVBoxAPIXPCOM.cpp@ 50269

Download in other formats: