tstVBoxAPIWin.cpp revision df2e37f58f19997178bb9be53867a17509a3a2f9
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * tstVBoxAPIWin - sample program to illustrate the VirtualBox
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * COM API for machine management on Windows.
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync It only uses standard C/C++ and COM semantics,
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * no additional VBox classes/macros/helpers. To
f14d3c62ebf4ccb64bd11528e5c4ec60b4528a1avboxsync * make things even easier to follow, only the
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * standard Win32 API has been used. Typically,
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * C++ developers would make use of Microsoft's
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * ATL to ease development.
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * available from http://www.virtualbox.org. This file is free software;
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * you can redistribute it and/or modify it under the terms of the GNU
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * General Public License (GPL) as published by the Free Software
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * additional information or have any questions.
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * PURPOSE OF THIS SAMPLE PROGRAM
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * ------------------------------
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * This sample program is intended to demonstrate the minimal code necessary
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * to use VirtualBox COM API for learning puroses only. The program uses pure
628ddfbd43ad5365d69fddda4007598242956577vboxsync * Win32 API and doesn't have any extra dependencies to let you better
628ddfbd43ad5365d69fddda4007598242956577vboxsync * understand what is going on when a client talks to the VirtualBox core
628ddfbd43ad5365d69fddda4007598242956577vboxsync * using the COM framework.
628ddfbd43ad5365d69fddda4007598242956577vboxsync * However, if you want to write a real application, it is highly recommended
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * to use our MS COM XPCOM Glue library and helper C++ classes. This way, you
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * will get at least the following benefits:
f14d3c62ebf4ccb64bd11528e5c4ec60b4528a1avboxsync * a) better portability: both the MS COM (used on Windows) and XPCOM (used
f14d3c62ebf4ccb64bd11528e5c4ec60b4528a1avboxsync * everywhere else) VirtualBox client application from the same source code
f14d3c62ebf4ccb64bd11528e5c4ec60b4528a1avboxsync * (including common smart C++ templates for automatic interface pointer
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * reference counter and string data management);
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * b) simpler XPCOM initialization and shutdown (only a signle method call
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * that does everything right).
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * Currently, there is no separate sample program that uses the VirtualBox MS
9fbcdff887bd2d679720a8a50f5601df57b32b1bvboxsync * COM XPCOM Glue library. Please refer to the sources of stock VirtualBox
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * applications such as the VirtualBox GUI frontend or the VBoxManage command
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * line frontend.
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync * First we have to get a list of all registered VMs
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync rc = SafeArrayAccessData (machinesArray, (void **) &machines);
37e7010b28a4667800196960b59cd63b5434b7d7vboxsync for (ULONG i = 0; i < machinesArray->rgsabound[0].cElements; ++i)
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync /* Try to find a machine that doesn't exist */
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync rc = virtualBox->FindMachine(machineName, &machine);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync printf("Error getting error info! rc = 0x%x\n", rc);
3ca89d9d8c4fc158ba28bdf82c9cc3697625ce12vboxsync printf("Error getting error description! rc = 0x%x\n", rc);
3ca89d9d8c4fc158ba28bdf82c9cc3697625ce12vboxsync printf("Successfully retrieved error description: %S\n", errorDescription);
bdd15592ca3578b623ff588055a561f58b7e5586vboxsync /* Try to start a VM called "WinXP SP2". */
7f5e9cb0292dcce87c0a6794c775c14fb9c2a1e7vboxsync rc = virtualBox->FindMachine(machineName, &machine);
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync printf("Error getting error info! rc = 0x%x\n", rc);
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync printf("Error getting error description! rc = 0x%x\n", rc);
551d9b8ee3568ad3e11b65ce6ef2867c36375f37vboxsync printf("Successfully retrieved error description: %S\n", errorDescription);
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync rc = machine->get_Id(&guid); /* Get the GUID of the machine. */
3ca89d9d8c4fc158ba28bdf82c9cc3697625ce12vboxsync printf("Error retrieving machine ID! rc = 0x%x\n", rc);
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync /* Create the session object. */
3ca89d9d8c4fc158ba28bdf82c9cc3697625ce12vboxsync rc = CoCreateInstance(CLSID_Session, /* the VirtualBox base object */
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync CLSCTX_INPROC_SERVER, /* the object lives in a server process on this machine */
39592d8ff3243f6116c4e99be391bcf30a4ad187vboxsync printf("Error creating Session instance! rc = 0x%x\n", rc);
6f6e182fde44ac8c4f95d8684e10fbbea937f26evboxsync /* Start a VM session using the delivered VBox GUI. */
6f6e182fde44ac8c4f95d8684e10fbbea937f26evboxsync rc = virtualBox->OpenRemoteSession (session, guid, sessiontype,
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync printf("Could not open remote session! rc = 0x%x\n", rc);
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync /* Wait until VM is running. */
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync /* Get console object. */
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync /* Bring console window to front. */
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync printf ("Press enter to power off VM and close the session...\n");
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync /* Power down the machine. */
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync /* Close the session. */
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync } while (0);
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync /* Initialize the COM subsystem. */
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync /* Instantiate the VirtualBox root object. */
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync rc = CoCreateInstance(CLSID_VirtualBox, /* the VirtualBox base object */
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync CLSCTX_LOCAL_SERVER, /* the object lives in a server process on this machine */
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync printf("Error creating VirtualBox instance! rc = 0x%x\n", rc);
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync /* Enable the following line to get a VM started. */
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync //testStartVM(virtualBox);
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync /* Release the VirtualBox object. */
1c2c968fd241148110002d75b2c0fdeddc211e14vboxsync } while (0);