VirtualBox Main API

Public Member Functions | List of all members
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.