Public Member Functions | Public Attributes

ISession Interface Reference

The ISession interface represents a serialization primitive for virtual machines. More...

List of all members.

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.

Detailed Description

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:

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.

Note:
Unless you are trying to write a new VirtualBox front-end that performs direct machine execution (like the VirtualBox or VBoxSDL front-ends), don't call IConsole::powerUp in a direct session opened by IVirtualBox::openSession and use this session only to change virtual machine settings. If you simply want to start virtual machine execution using one of the existing front-ends (for example the VirtualBox GUI or headless server), simply use IVirtualBox::openRemoteSession; these front-ends will power up the machine automatically for you.
Interface ID:
{12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D}

Member Function Documentation

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

Expected result codes:
E_UNEXPECTED Session is not open.
Note:
Do not expect the session state (ISession::state to return to "Closed" immediately after you invoke ISession::close(), particularly if you have started a remote session to execute the VM in a new process. The session state will automatically return to "Closed" 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 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.