public class ISession extends IUnknown
IMachine
objects living in the VirtualBox
server process to coordinate such changes.
There are two typical scenarios in which sessions are used:IMachine.lockMachine(org.virtualbox_7_0.ISession,org.virtualbox_7_0.LockType)
.
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.IMachine.launchVMProcess(org.virtualbox_7_0.ISession,String,List)
, 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.createLocalObject()
, a standard COM API.
This object will then act as a local session object in further calls to open
a session.IWebsessionManager.logon(String,String)
is called. A managed object reference to that session object can be retrieved by
callingIWebsessionManager.getSessionObject(org.virtualbox_7_0.IVirtualBox)
.{C0447716-FF5A-4795-B57A-ECD5FFFA18A4}
Constructor and Description |
---|
ISession(java.lang.String wrapped,
org.virtualbox_7_0.ObjectRefManager objMgr,
org.virtualbox_7_0.jaxws.VboxPortType port) |
Modifier and Type | Method and Description |
---|---|
IConsole |
getConsole()
Console object associated with this session.
|
IMachine |
getMachine()
Machine object associated with this session.
|
java.lang.String |
getName()
Name of this session.
|
SessionState |
getState()
Current state of this session.
|
SessionType |
getType()
Type of this session.
|
static ISession |
queryInterface(IUnknown obj) |
void |
setName(java.lang.String value)
Name of this session.
|
void |
unlockMachine()
Unlocks a machine that was previously locked for the current session.
|
getObjMgr, getRemoteWSPort, getWrapped, releaseRemote
public ISession(java.lang.String wrapped, org.virtualbox_7_0.ObjectRefManager objMgr, org.virtualbox_7_0.jaxws.VboxPortType port)
public SessionState getState()
public SessionType getType()
getState()
is Locked), otherwise an error will be returned.public java.lang.String getName()
public void setName(java.lang.String value)
value
- Stringpublic IMachine getMachine()
public IConsole getConsole()
public void unlockMachine()
IMachine.launchVMProcess(org.virtualbox_7_0.ISession,String,List)
orIMachine.lockMachine(org.virtualbox_7_0.ISession,org.virtualbox_7_0.LockType)
calls. Otherwise the state of
the machine will be set toMachineState.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.getState()
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.