VirtualBox Main API
Public Member Functions | Public Attributes | List of all members
ISession Interface Reference

The ISession interface represents a client process and allows for locking virtual machines (represented by IMachine objects) to prevent conflicting changes to the machine. More...

Public Member Functions

void unlockMachine ()
 Unlocks a machine that was previously locked for the current session.

Public Attributes

readonly attribute SessionState state
 Current state of this session.
readonly attribute SessionType type
 Type of this session.
readonly attribute IMachine machine
 Machine object associated with this session.
readonly attribute IConsole console
 Console object associated with this session.

Detailed Description

The ISession interface represents a client process and allows for locking virtual machines (represented by IMachine objects) to prevent conflicting changes to the machine.

  Any caller wishing to manipulate a virtual machine needs to create a session
  object first, which lives in its own process space. Such session objects are
  then associated with @link ::IMachine IMachine@endlink<b></b> objects living in the VirtualBox
  server process to coordinate such changes.

  There are two typical scenarios in which sessions are used:

  <ul>

To alter machine settings or control a running virtual machine, one needs to lock a machine for a given session (client process) by calling IMachine::lockMachine.

Whereas multiple sessions may control a running virtual machine, only one process can obtain a write lock on the machine to prevent conflicting changes. A write lock is also needed if a process wants to actually run a virtual machine in its own context, such as the VirtualBox GUI or VBoxHeadless front-ends. They must also lock a machine for their own sessions before they are allowed to power up the virtual machine.

As a result, no machine settings can be altered while another process is already using it, either because that process is modifying machine settings or because the machine is running. To start a VM using one of the existing VirtualBox front-ends (e.g. the VirtualBox GUI or VBoxHeadless), one would use IMachine::launchVMProcess, which also takes a session object as its first parameter. This session then identifies the caller and lets the caller control the started machine (for example, pause machine execution or power it down) as well as be notified about machine execution state changes.

  How sessions objects are created in a client process depends on whether you use
  the Main API via COM or via the webservice:

  <ul>

When using the COM API directly, an object of the Session class from the VirtualBox type library needs to be created. In regular COM C++ client code, this can be done by calling createLocalObject(), a standard COM API. This object will then act as a local session object in further calls to open a session. In the webservice, the session manager (IWebsessionManager) instead creates a session object automatically whenever IWebsessionManager::logon is called. A managed object reference to that session object can be retrieved by calling IWebsessionManager::getSessionObject.

Interface ID:
{12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D}

Member Function Documentation

void ISession::unlockMachine ( )

Unlocks a machine that was previously locked for the current session.

    Calling this method is required every time a machine has been locked
    for a particular session using the @link IMachine::launchVMProcess IMachine::launchVMProcess@endlink<b></b>
    or @link IMachine::lockMachine IMachine::lockMachine@endlink<b></b> calls. Otherwise the state of
    the machine will be set to @link ::MachineState_Aborted MachineState_Aborted@endlink<b></b> on the
    server, and changes made to the machine settings will be lost.

    Generally, it is recommended to unlock all machines explicitly
    before terminating the application (regardless of the reason for
    the termination).

  @par Expected result codes:
<table><tr>

E_UNEXPECTED

Session is not locked.

Note
Do not expect the session state (ISession::state to return to "Unlocked" immediately after you invoke this method, particularly if you have started a new VM process. The session state will automatically return to "Unlocked" once the VM is no longer executing, which can of course take a very long time.

Member Data Documentation

readonly attribute SessionState ISession::state

Current state of this session.

readonly attribute SessionType ISession::type

Type of this session.

The value of this attribute is valid only if the session currently has a machine locked (i.e. its state is Locked), otherwise an error will be returned.

readonly attribute IMachine ISession::machine

Machine object associated with this session.

readonly attribute IConsole ISession::console

Console object associated with this session.