VirtualBox Main API
|
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. | |
attribute wstring | name |
Name of this session. | |
readonly attribute IMachine | machine |
Machine object associated with this session. | |
readonly attribute IConsole | console |
Console object associated with this session. | |
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:
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.
How sessions objects are created in a client process depends on whether you use the Main API via COM or via the webservice:
createLocalObject()
, a standard COM API. This object will then act as a local session object in further calls to open a session. {C0447716-FF5A-4795-B57A-ECD5FFFA18A4}
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).
E_UNEXPECTED | Session is not locked. |
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.
attribute wstring ISession::name |
Name of this session.
Important only for VM sessions, otherwise it it will be remembered, but not used for anything significant (and can be left at the empty string which is the default). The value can only be changed when the session state is SessionState_Unlocked. Make sure that you use a descriptive name which does not conflict with the VM process session names: "GUI/Qt", "GUI/SDL" and "headless".
readonly attribute IMachine ISession::machine |
Machine object associated with this session.
readonly attribute IConsole ISession::console |
Console object associated with this session.
Only sessions which locked the machine for a VM process have a non-null console.