IVirtualBoxSDS Interface Reference

The IVirtualBoxSDS interface represents the system-wide directory service helper. More...

Inheritance diagram for IVirtualBoxSDS:

Public Member Functions
void	registerVBoxSVC (in IVBoxSVCRegistration vboxSVC, in long pid, [retval] out $unknown existingVirtualBox)
	Registers a VBoxSVC instance with VBoxSDS.
void	deregisterVBoxSVC (in IVBoxSVCRegistration vboxSVC, in long pid)
	Registers a VBoxSVC instance with the SDS.
void	launchVMProcess (in wstring machine, in wstring comment, in wstring frontend, in wstring[] environmentChanges, in wstring cmdOptions, in unsigned long sessionId, [retval] out unsigned long pid)
	Spawns a new process that will execute the virtual machine in the interactive windows session of calling user.

Detailed Description

The IVirtualBoxSDS interface represents the system-wide directory service helper.

It exists only on Windows host, and its purpose is to work around design flaws in Microsoft's (D)COM, in particular the local server instantiation behavior.

Interface ID:

{890ED3DC-CC19-43FA-8EBF-BAECB6B9EC87}

Member Function Documentation

registerVBoxSVC()

void IVirtualBoxSDS::registerVBoxSVC	(	in IVBoxSVCRegistration	vboxSVC,
		in long	pid,
		[retval] out $unknown	existingVirtualBox
	)

Registers a VBoxSVC instance with VBoxSDS.

If the caller is not running in a Windows 0 session, the method attempts to run VBoxSVC in that session.

Parameters

vboxSVC	Interface implemented by the VirtualBox class factory.
pid	The process ID of the VBoxSVC instance.
existingVirtualBox	If there is already an VBoxSVC for this user, the an IUnknown interface to its VirtualBox object is returned here, otherwise it is set to NULL.

Expected result codes:

E_PENDING

The caller is not running in a Windows session 0 and no VBoxSVC is registered. VBoxSVC registration begins in Windows session 0. You should call this method again later.

deregisterVBoxSVC()

void IVirtualBoxSDS::deregisterVBoxSVC	(	in IVBoxSVCRegistration	vboxSVC,
		in long	pid
	)

Registers a VBoxSVC instance with the SDS.

Parameters

vboxSVC	Same as specified during registration.
pid	The process ID of the VBoxSVC instance (same as during registration).

launchVMProcess()

void IVirtualBoxSDS::launchVMProcess	(	in wstring	machine,
		in wstring	comment,
		in wstring	frontend,
		in wstring[]	environmentChanges,
		in wstring	cmdOptions,
		in unsigned long	sessionId,
		[retval] out unsigned long	pid
	)

Spawns a new process that will execute the virtual machine in the interactive windows session of calling user.

Any additional checks are performed by created process itself

If launching the VM succeeds, the new VM process will create its own session and write-lock the machine for it, preventing conflicting changes from other processes. If the machine is already locked (because it is already running or because another session has a write lock), launching the VM process will therefore fail. Reversely, future attempts to obtain a write lock will also fail while the machine is running.

Launching a VM process can take some time (a new VM is started in a new process, for which memory and other resources need to be set up) but the method does not wait for completion and just returns the PID of created process.

Parameters

machine	The name or id of the machine the VM will start for.
comment	The comment for VM.
frontend	Front-end to use for the new VM process. The following are currently supported:

• "gui": VirtualBox Qt GUI front-end
• "headless": VBoxHeadless (VRDE Server) front-end
• "sdl": VirtualBox SDL front-end
• "": use the per-VM default frontend if set, otherwise the global default defined in the system properties. If neither are set, the API will launch a "gui" session, which may fail if there is no windowing environment available. See IMachine::defaultFrontend and ISystemProperties::defaultFrontend.

Parameters

environmentChanges	The list of putenv-style changes to the VM process environment. See IMachine::launchVMProcess for details.
cmdOptions	Additional command line options to pass to the VM process.
sessionId	Windows session where the VM process should be launched.
pid	The PID of created process.

Expected result codes:

E_INVALIDARG	Some of the parameters are invalid.
VBOX_E_IPRT_ERROR	Launching process for machine failed.