The ISession interface represents a serialization primitive for virtual machines. More...
Public Member Functions | |
void | close () |
Closes a session that was previously opened. | |
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. |
The ISession interface represents a serialization primitive for virtual machines.
With VirtualBox, every time one wishes to manipulate a virtual machine (e.g. change its settings or start execution), a session object is required. Such an object must be passed to one of the session methods that open the given session, which then initiates the machine manipulation.
A session serves several purposes: it identifies to the inter-process VirtualBox code which process is currently working with the virtual machine, and it ensures that there are no incompatible requests from several processes for the same virtual machine. Session objects can therefore be thought of as mutex semaphores that lock virtual machines to prevent conflicting accesses from several processes.
How sessions objects are used 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. Sessions are mainly used in two variations:
One also can attach to an existing direct session already opened by another process (for example, in order to send a control request to the virtual machine such as the pause or the reset request). This is done by calling IVirtualBox::openExistingSession.
{12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D}
void ISession::close | ( | ) |
Closes a session that was previously opened.
It is recommended that every time an "open session" method (such as IVirtualBox::openRemoteSession or IVirtualBox::openSession) has been called to manipulate a virtual machine, the caller invoke ISession::close() when it's done doing so. Since sessions are serialization primitives much like ordinary mutexes, they are best used the same way: for each "open" call, there should be a matching "close" call, even when errors occur.
Otherwise, if a direct session for a machine opened with IVirtualBox::openSession is not explicitly closed when the application terminates, the state of the machine will be set to MachineState_Aborted on the server.
Generally, it is recommended to close all open sessions explicitly before terminating the application (regardless of the reason for the termination).
E_UNEXPECTED | Session is not open. |
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 is currently open (i.e. its state is SessionType_SessionOpen), 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.