tstVBoxAPIXPCOM.cpp revision 340c9153ef85fdaf7acf99926a068a62197308cf
/** @file
*
* tstVBoxAPIXPCOM - sample program to illustrate the VirtualBox
* XPCOM API for machine management.
* It only uses standard C/C++ and XPCOM semantics,
*/
/*
* Copyright (C) 2006-2015 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*/
/*
* PURPOSE OF THIS SAMPLE PROGRAM
* ------------------------------
*
* This sample program is intended to demonstrate the minimal code necessary
* to use VirtualBox XPCOM API for learning puroses only. The program uses
* pure XPCOM and doesn't have any extra dependencies to let you better
* understand what is going on when a client talks to the VirtualBox core
* using the XPCOM framework.
*
* However, if you want to write a real application, it is highly recommended
* to use our MS COM XPCOM Glue library and helper C++ classes. This way, you
* will get at least the following benefits:
*
* a) better portability: both the MS COM (used on Windows) and XPCOM (used
* everywhere else) VirtualBox client application from the same source code
* (including common smart C++ templates for automatic interface pointer
* reference counter and string data management);
* b) simpler XPCOM initialization and shutdown (only a single method call
* that does everything right).
*
* Currently, there is no separate sample program that uses the VirtualBox MS
* COM XPCOM Glue library. Please refer to the sources of stock VirtualBox
* applications such as the VirtualBox GUI frontend or the VBoxManage command
* line frontend.
*
*
* RUNNING THIS SAMPLE PROGRAM
* ---------------------------
*
* This sample program needs to know where the VirtualBox core files reside
* and where to search for VirtualBox shared libraries. Therefore, you need to
* use the following (or similar) command to execute it:
*
* $ env VBOX_XPCOM_HOME=../../.. LD_LIBRARY_PATH=../../.. ./tstVBoxAPIXPCOM
*
* The above command assumes that VBoxRT.so, VBoxXPCOM.so and others reside in
* the directory ../../..
*/
#include <stdio.h>
#include <stdlib.h>
#include <iconv.h>
/*
* Include the XPCOM headers
*/
#include <nsMemory.h>
#include <nsString.h>
#include <nsIServiceManager.h>
#include <nsEventQueueUtils.h>
#include <nsIExceptionService.h>
/*
* VirtualBox XPCOM interface. This header is generated
* from IDL which in turn is generated from a custom XML format.
*/
#include "VirtualBox_XPCOM.h"
/*
* Prototypes
*/
void printErrorInfo();
/**
* Display all registered VMs on the screen with some information about each
*
* @param virtualBox VirtualBox instance object.
*/
{
printf("----------------------------------------------------\n");
printf("VM List:\n\n");
/*
* Get the list of all registered VMs
*/
PRUint32 machineCnt = 0;
if (NS_SUCCEEDED(rc))
{
/*
* Iterate through the collection
*/
for (PRUint32 i = 0; i < machineCnt; ++ i)
{
if (machine)
{
if (isAccessible)
{
}
else
{
printf("\tName: <inaccessible>\n");
}
free((void*)uuidString);
if (isAccessible)
{
}
/* don't forget to release the objects in the array... */
}
}
}
printf("----------------------------------------------------\n\n");
}
/**
* Create a sample VM
*
* @param virtualBox VirtualBox instance object.
*/
{
/*
* First create a unnamed new VM. It will be unconfigured and not be saved
* in the configuration until we explicitely choose to do so.
*/
0, nsnull, /* groups (safearray)*/
nsnull, /* ostype */
nsnull, /* create flags */
{
return;
}
/*
* Set some properties
*/
/* alternative to illustrate the use of string classes */
/*
* Now a more advanced property -- the guest OS type. This is
* an object by itself which has to be found first. Note that we
* use the ID of the guest OS type here which is an internal
* representation (you can find that by configuring the OS type of
* a machine in the GUI and then looking at the <Guest ostype=""/>
* setting in the XML file. It is also possible to get the OS type from
* its description (win2k would be "Windows 2000") by getting the
* guest OS type collection and enumerating it.
*/
{
}
else
{
}
/*
* Register the VM. Note that this call also saves the VM config
* to disk. It is also possible to save the VM settings but not
* register the VM.
*
* Also note that due to current VirtualBox limitations, the machine
* must be registered *before* we can attach hard disks to it.
*/
{
return;
}
/*
* In order to manipulate the registered machine, we must open a session
* for that machine. Do it now.
*/
{
{
return;
}
{
return;
}
{
return;
}
/*
* After the machine is registered, the initial machine object becomes
* immutable. In order to get a mutable machine object, we must query
* it from the opened session object.
*/
{
return;
}
}
/*
* Create a virtual harddisk
*/
{
}
else
{
/*
* We have only created an object so far. No on disk representation exists
* because none of its properties has been set so far. Let's continue creating
* a dynamically expanding image.
*/
{
}
else
{
/*
* Creating the image is done in the background because it can take quite
* some time (at least fixed size images). We have to wait for its completion.
* Here we wait forever (timeout -1) which is potentially dangerous.
*/
{
printf("Error: could not create hard disk! rc=%#x\n",
}
else
{
/*
* Now that it's created, we can assign it to the VM.
*/
0, // channel number on the controller
0, // device number on the controller
hardDisk);
{
}
}
}
}
/*
* It's got a hard disk but that one is new and thus not bootable. Make it
* boot from an ISO file. This requires some processing. First the ISO file
* has to be registered and then mounted to the VM's DVD drive and selected
* as the boot device.
*/
false /* fForceNewUuid */,
else
{
/*
* Now assign it to our VM
*/
2, // channel number on the controller
0, // device number on the controller
PR_FALSE); // aForce
{
}
else
{
/*
* Last step: tell the VM to boot from the CD.
*/
{
}
}
}
/*
* Save all changes we've just made.
*/
/*
* It is always important to close the open session when it becomes not
* necessary any more.
*/
session->UnlockMachine();
else
{
else
{
printf("Failed to delete the machine! rc=%#x\n",
}
}
}
// main
///////////////////////////////////////////////////////////////////////////////
{
/*
* Check that PRUnichar is equal in size to what compiler composes L""
* strings from; otherwise NS_LITERAL_STRING macros won't work correctly
* and we will get a meaningless SIGSEGV. This, of course, must be checked
* at compile time in xpcom/string/nsTDependentString.h, but XPCOM lacks
* compile-time assert macros and I'm not going to add them now.
*/
if (sizeof(PRUnichar) != sizeof(wchar_t))
{
printf("Error: sizeof(PRUnichar) {%lu} != sizeof(wchar_t) {%lu}!\n"
"Probably, you forgot the -fshort-wchar compiler option.\n",
(unsigned long) sizeof(PRUnichar),
(unsigned long) sizeof(wchar_t));
return -1;
}
/*
* This is the standard XPCOM init procedure.
* What we do is just follow the required steps to get an instance
* of our main interface, which is IVirtualBox.
*
* Note that we scope all nsCOMPtr variables in order to have all XPCOM
* objects automatically released before we call NS_ShutdownXPCOM at the
* end. This is an XPCOM requirement.
*/
{
{
return -1;
}
#if 0
/*
* Register our components. This step is only necessary if this executable
* implements XPCOM components itself which is not the case for this
* simple example.
*/
if (!registrar)
{
printf("Error: could not query nsIComponentRegistrar interface!\n");
return -1;
}
#endif
/*
* Make sure the main event queue is created. This event queue is
* responsible for dispatching incoming XPCOM IPC messages. The main
* thread should run this event queue's loop during lengthy non-XPCOM
* operations to ensure messages from the VirtualBox server and other
* XPCOM IPC clients are processed. This use case doesn't perform such
* operations so it doesn't run the event loop.
*/
{
return -1;
}
/*
* Now XPCOM is ready and we can start to do real work.
* IVirtualBox is the root interface of VirtualBox and will be
* retrieved from the XPCOM component manager. We use the
* XPCOM provided smart pointer nsCOMPtr for all objects because
* that's very convenient and removes the need deal with reference
* counting and freeing.
*/
{
return -1;
}
{
return -1;
}
printf("VirtualBox object created\n");
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/* this is enough to free the IVirtualBox instance -- smart pointers rule! */
virtualBox = nsnull;
/*
* Process events that might have queued up in the XPCOM event
* queue. If we don't process them, the server might hang.
*/
}
/*
* Perform the standard XPCOM shutdown procedure.
*/
printf("Done!\n");
return 0;
}
//////////////////////////////////////////////////////////////////////////////////////////////////////
//// Helpers
//////////////////////////////////////////////////////////////////////////////////////////////////////
/**
* Helper function to convert an nsID into a human readable string
*
* @returns result string, allocated. Has to be freed using free()
* @param guid Pointer to nsID that will be converted.
*/
{
{
}
return res;
}
/**
* Helper function to print XPCOM exception information set on the current
* thread after a failed XPCOM method call. This function will also print
* extended VirtualBox error info if it is available.
*/
void printErrorInfo()
{
if (NS_SUCCEEDED(rc))
{
if (NS_SUCCEEDED(rc))
{
{
{
/* got extended error info */
printf("Extended error info (IVirtualBoxErrorInfo):\n");
}
else
{
/* got basic error info */
printf("Basic error info (nsIException):\n");
}
/* reset the exception to NULL to indicate we've processed it */
}
}
}
}