MachineImpl.h revision 3c3a5ab35783f4d31cb5d3a15db9daadeb804daa
/* $Id$ */
/** @file
*
* VirtualBox COM class declaration
*/
/*
* Copyright (C) 2006-2007 Sun Microsystems, Inc.
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 USA or visit http://www.sun.com if you need
* additional information or have any questions.
*/
#ifndef ____H_MACHINEIMPL
#define ____H_MACHINEIMPL
#include "VirtualBoxBase.h"
#include "ProgressImpl.h"
#include "SnapshotImpl.h"
#include "VRDPServerImpl.h"
#include "DVDDriveImpl.h"
#include "FloppyDriveImpl.h"
#include "HardDiskAttachmentImpl.h"
#include "Collection.h"
#include "NetworkAdapterImpl.h"
#include "AudioAdapterImpl.h"
#include "SerialPortImpl.h"
#include "ParallelPortImpl.h"
#include "BIOSSettingsImpl.h"
#include "SATAControllerImpl.h"
#ifdef VBOX_WITH_RESOURCE_USAGE_API
#include "PerformanceImpl.h"
#endif /* VBOX_WITH_RESOURCE_USAGE_API */
// generated header
#include "SchemaDefs.h"
#include <list>
// defines
////////////////////////////////////////////////////////////////////////////////
// helper declarations
////////////////////////////////////////////////////////////////////////////////
// Machine class
////////////////////////////////////////////////////////////////////////////////
{
/**
* Internal machine data.
*
* Only one instance of this data exists per every machine --
* it is shared by the Machine, SessionMachine and all SnapshotMachine
* instances associated with the given machine using the util::Shareable
* template through the mData variable.
*
* @note |const| members are persistent during lifetime so can be
* accessed without locking.
*
* @note There is no need to lock anything inside init() or uninit()
* methods, because they are always serialized (see AutoCaller).
*/
struct Data
{
/**
* Data structure to hold information about sessions opened for the
* given machine.
*/
struct Session
{
/** Control of the direct session opened by openSession() */
/** list of controls of all opened remote sessions */
/** openRemoteSession() and OnSessionEnd() progress indicator */
/**
* PID of the session object that must be passed to openSession()
* to finalize the openRemoteSession() request
* (i.e., PID of the process created by openRemoteSession())
*/
/** Current session state */
/** Session type string (for indirect sessions) */
/** Sesison machine object */
};
Data();
~Data();
/* Note: These are guarded by VirtualBoxBase::stateLockHandle() */
};
/**
* Saved state data.
*
* It's actually only the state file path string, but it needs to be
* separate from Data, because Machine and SessionMachine instances
* share it, while SnapshotMachine does not.
*
* The data variable is |mSSData|.
*/
struct SSData
{
};
/**
* User changeable machine data.
*
* This data is common for all machine snapshots, i.e. it is shared
* by all SnapshotMachine instances associated with the given machine
* using the util::Backupable template through the |mUserData| variable.
*
* SessionMachine instances can alter this data and discard changes.
*
* @note There is no need to lock anything inside init() or uninit()
* methods, because they are always serialized (see AutoCaller).
*/
struct UserData
{
UserData();
~UserData();
{
}
};
/**
* Hardware data.
*
* This data is unique for a machine and for every machine snapshot.
* Stored using the util::Backupable template in the |mHWData| variable.
*
* SessionMachine instances can alter this data and discard changes.
*/
struct HWData
{
HWData();
~HWData();
};
/**
* Hard disk data.
*
* The usage policy is the same as for HWData, but a separate structure
* is necessarym because hard disk data requires different procedures when
* taking or discarding snapshots, etc.
*
* The data variable is |mHWData|.
*/
struct HDData
{
HDData();
~HDData();
/**
* Right after Machine::fixupHardDisks(true): |true| if hard disks
* were actually changed, |false| otherwise
*/
bool mHDAttachmentsChanged;
};
enum StateDependency
{
};
/**
* Helper class that safely manages the machine state dependency by
* calling Machine::addStateDependency() on construction and
* Machine::releaseStateDependency() on destruction. Intended for Machine
* children. The usage pattern is:
*
* @code
* AutoCaller autoCaller (this);
* CheckComRCReturnRC (autoCaller.rc());
*
* Machine::AutoStateDependency <MutableStateDep> adep (mParent);
* CheckComRCReturnRC (stateDep.rc());
* ...
* // code that depends on the particular machine state
* ...
* @endcode
*
* Note that it is more convenient to use the following individual
* shortcut classes instead of using this template directly:
* AutoAnyStateDependency, AutoMutableStateDependency and
* AutoMutableOrSavedStateDependency. The usage pattern is exactly the
* same as above except that there is no need to specify the template
* argument because it is already done by the shortcut class.
*
* @param taDepType Dependecy type to manage.
*/
{
, mRegistered (FALSE)
{
&mRegistered);
}
{
}
/** Decreases the number of dependencies before the instance is
* destroyed. Note that will reset #rc() to E_FAIL. */
void release()
{
}
/** Restores the number of callers after by #release(). #rc() will be
* reset to the result of calling addStateDependency() and must be
* rechecked to ensure the operation succeeded. */
void add()
{
&mRegistered);
}
/** Returns the result of Machine::addStateDependency(). */
/** Shortcut to SUCCEEDED (rc()). */
/** Returns the machine state value as returned by
* Machine::addStateDependency(). */
/** Returns the machine state value as returned by
* Machine::addStateDependency(). */
};
/**
* Shortcut to AutoStateDependency <AnyStateDep>.
* See AutoStateDependency to get the usage pattern.
*
* Accepts any machine state and guarantees the state won't change before
* this object is destroyed. If the machine state cannot be protected (as
* a result of the state change currently in progress), this instance's
* #rc() method will indicate a failure, and the caller is not allowed to
* rely on any particular machine state and should return the failed
* result code to the upper level.
*/
/**
* Shortcut to AutoStateDependency <MutableStateDep>.
* See AutoStateDependency to get the usage pattern.
*
* Succeeds only if the machine state is in one of the mutable states, and
* guarantees the given mutable state won't change before this object is
* destroyed. If the machine is not mutable, this instance's #rc() method
* will indicate a failure, and the caller is not allowed to rely on any
* particular machine state and should return the failed result code to
* the upper level.
*
* Intended to be used within all setter methods of IMachine
* children objects (DVDDrive, NetworkAdapter, AudioAdapter, etc.) to
* provide data protection and consistency.
*/
/**
* Shortcut to AutoStateDependency <MutableOrSavedStateDep>.
* See AutoStateDependency to get the usage pattern.
*
* Succeeds only if the machine state is in one of the mutable states, or
* if the machine is in the Saved state, and guarantees the given mutable
* state won't change before this object is destroyed. If the machine is
* not mutable, this instance's #rc() method will indicate a failure, and
* the caller is not allowed to rely on any particular machine state and
* should return the failed result code to the upper level.
*
* Intended to be used within setter methods of IMachine
* children objects that may also operate on Saved machines.
*/
void FinalRelease();
// public initializer/uninitializer for internal purposes only
void uninit();
// IMachine properties
// IMachine methods
STDMETHOD(EnumerateGuestProperties) (INPTR BSTR aPattern, ComSafeArrayOut(BSTR, aKeys), ComSafeArrayOut(BSTR, aValues), ComSafeArrayOut(ULONG64, aTimestamps), ComSafeArrayOut(BSTR, aFlags));
// public methods only for internal purposes
/// @todo (dmik) add lock and make non-inlined after revising classes
// that use it. Note: they should enter Machine lock to keep the returned
// information valid!
/**
* Returns the VirtualBox object this machine belongs to.
*
* @note This method doesn't check this object's readiness as it is
* intended to be used only by Machine children where it is guaranteed
* that this object still exists in memory.
*/
/**
* Returns this machine's name.
*
* @note This method doesn't check this object's readiness as it is
* intended to be used only after adding a caller to this object (that
* guarantees that the object is ready or at least limited).
*/
/**
* Returns this machine's full settings file path.
*
* @note This method doesn't lock this object or check its readiness as
* it is intended to be used only after adding a caller to this object
* (that guarantees that the object is ready) and locking it for reading.
*/
/**
* Returns this machine's name.
*
* @note This method doesn't lock this object or check its readiness as
* it is intended to be used only after adding a caller to this object
* (that guarantees that the object is ready) and locking it for reading.
*/
// callback handlers
bool aSetError = false)
{
}
void releaseStateDependency();
// for VirtualBoxSupportErrorInfoImpl
void uninitDataAndChildObjects();
bool aSetError = false);
bool aSetError = false);
bool aSetError = false);
bool aInformCallbacksAnyway = false);
enum
{
// ops for #saveSnapshotSettings()
SaveSS_OpMask = 0xF,
// flags for #saveSnapshotSettings()
SaveSS_UpdateCurStateModified = 0x40,
SaveSS_UpdateCurrentId = 0x80,
// flags for #saveStateSettings()
SaveSTS_CurStateModified = 0x20,
SaveSTS_StateFilePath = 0x40,
SaveSTS_StateTimeStamp = 0x80,
};
bool aOnline);
/** @note This method is not thread safe */
{
}
bool isModified();
bool isReallyModified (bool aIgnoreUserData = false);
#ifdef VBOX_WITH_RESOURCE_USAGE_API
#endif /* VBOX_WITH_RESOURCE_USAGE_API */
const InstanceType mType;
// so they cannot be a part of HWData
const ComObjPtr <SerialPort>
const ComObjPtr <ParallelPort>
const ComObjPtr <NetworkAdapter>
};
// SessionMachine class
////////////////////////////////////////////////////////////////////////////////
/**
* @note Notes on locking objects of this class:
* SessionMachine shares some data with the primary Machine instance (pointed
* to by the |mPeer| member). In order to provide data consistency it also
* shares its lock handle. This means that whenever you lock a SessionMachine
* instance using Auto[Reader]Lock or AutoMultiLock, the corresponding Machine
* instance is also locked in the same lock mode. Keep it in mind.
*/
{
void FinalRelease();
// public initializer/uninitializer for internal purposes only
// util::Lockable interface
RWLockHandle *lockHandle() const;
// IInternalMachineControl methods
// public methods only for internal purposes
bool checkForDeath();
#if defined (RT_OS_WINDOWS)
#endif
struct SnapshotData
{
// used when taking snapshot
// used when saving state
};
struct Uninit {
};
struct Task;
struct TakeSnapshotTask;
struct DiscardSnapshotTask;
struct DiscardCurrentStateTask;
friend struct TakeSnapshotTask;
friend struct DiscardSnapshotTask;
friend struct DiscardCurrentStateTask;
/** interprocess semaphore handle (id) for this machine */
#if defined(RT_OS_WINDOWS)
#elif defined(VBOX_WITH_SYS_V_IPC_SESSION_WATCHER)
int mIPCSem;
#else
# error "Port me!"
#endif
};
// SnapshotMachine class
////////////////////////////////////////////////////////////////////////////////
/**
* @note Notes on locking objects of this class:
* SnapshotMachine shares some data with the primary Machine instance (pointed
* to by the |mPeer| member). In order to provide data consistency it also
* shares its lock handle. This means that whenever you lock a SessionMachine
* instance using Auto[Reader]Lock or AutoMultiLock, the corresponding Machine
* instance is also locked in the same lock mode. Keep it in mind.
*/
{
void FinalRelease();
// public initializer/uninitializer for internal purposes only
void uninit();
// util::Lockable interface
RWLockHandle *lockHandle() const;
// public methods only for internal purposes
};
////////////////////////////////////////////////////////////////////////////////
/**
* Returns a pointer to the Machine object for this machine that acts like a
* parent for complex machine data objects such as shared folders, etc.
*
* For primary Machine objects and for SnapshotMachine objects, returns this
* object's pointer itself. For SessoinMachine objects, returns the peer
* (primary) machine pointer.
*/
{
if (mType == IsSessionMachine)
return mPeer;
return this;
}
#endif // ____H_MACHINEIMPL