Public Member Functions | Public Attributes

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...

List of all members.

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 IMachine objects living in the VirtualBox server process to coordinate such changes.

There are two typical scenarios in which sessions are used:

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

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 IMachine::launchVMProcess or IMachine::lockMachine calls. Otherwise the state of the machine will be set to MachineState_Aborted 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).

Expected result codes:
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.