# 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:

- When using the COM API directly, an object of the Session class from the VirtualBox type library needs to be created. In regular COM C++ client code, this can be done by calling `createLocalObject()`, a standard COM API. This object will then act as a local session object in further calls to open a session.
- In the webservice, the session manager (IWebsessionManager) instead creates one session object automatically when IWebsessionManager::logon is called. A managed object reference to that session object can be retrieved by calling IWebsessionManager::getSessionObject. This session object reference can then be used to open sessions.

Sessions are mainly used in two variations:

- To start a virtual machine in a separate process, one would call IVirtualBox::openRemoteSession, which requires a session object as its first parameter. This session then identifies the caller and lets him control the started machine (for example, pause machine execution or power it down) as well as be notified about machine execution state changes.
- To alter machine settings, or to start machine execution within the current process, one needs to open a direct session for the machine first by calling IVirtualBox::openSession. While a direct session is open within one process, no any other process may open another direct session for the same machine. This prevents the machine from being changed by other processes while it is running or while the machine is being configured.

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.