MachineImpl.h revision 16f69245c1929bf94eb7e61017b1de96c1f8ffcf
/* $Id$ */
/** @file
*
* VirtualBox COM class declaration
*/
/*
* Copyright (C) 2006-2010 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 "MediumAttachmentImpl.h"
#include "NetworkAdapterImpl.h"
#include "AudioAdapterImpl.h"
#include "SerialPortImpl.h"
#include "ParallelPortImpl.h"
#include "BIOSSettingsImpl.h"
#include "StorageControllerImpl.h" // required for MachineImpl.h to compile on Windows
#include "VBox/settings.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
////////////////////////////////////////////////////////////////////////////////
{
struct Snapshot;
struct Hardware;
struct Storage;
struct StorageController;
struct MachineRegistryEntry;
}
// 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) */
/** Session machine object */
/**
* Successfully locked media list. The 2nd value in the pair is true
* if the medium is locked for writing and false if locked for
* reading.
*/
};
Data();
~Data();
/** Flag indicating that the config file is read-only. */
// machine settings XML file
/* Note: These are guarded by VirtualBoxBase::stateLockHandle() */
// protectes the snapshots tree of this machine
};
/**
* 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
{
/**
* Data structure to hold information about a guest property.
*/
struct GuestProperty {
/** Property name */
/** Property value */
/** Property timestamp */
/** Property flags */
};
HWData();
~HWData();
};
/**
* Hard disk and other media data.
*
* The usage policy is the same as for HWData, but a separate structure
* is necessary because hard disk data requires different procedures when
* taking or discarding snapshots, etc.
*
* The data variable is |mMediaData|.
*/
struct MediaData
{
MediaData();
~MediaData();
};
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);
* if (FAILED(autoCaller.rc())) return autoCaller.rc();
*
* Machine::AutoStateDependency<MutableStateDep> adep(mParent);
* if (FAILED(stateDep.rc())) return 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
const Utf8Str &strConfigFile,
void uninit();
void uninitDataAndChildObjects();
// IMachine properties
STDMETHOD(COMGETTER(StorageControllers))(ComSafeArrayOut(IStorageController *, aStorageControllers));
// IMachine methods
STDMETHOD(PassthroughDevice)(IN_BSTR aControllerName, LONG aControllerPort, LONG aDevice, BOOL aPassthrough);
STDMETHOD(EnumerateGuestProperties)(IN_BSTR aPattern, ComSafeArrayOut(BSTR, aNames), ComSafeArrayOut(BSTR, aValues), ComSafeArrayOut(ULONG64, aTimestamps), ComSafeArrayOut(BSTR, aFlags));
STDMETHOD(GetMediumAttachmentsOfController)(IN_BSTR aName, ComSafeArrayOut(IMediumAttachment *, aAttachments));
STDMETHOD(GetMediumAttachment)(IN_BSTR aConstrollerName, LONG aControllerPort, LONG aDevice, IMediumAttachment **aAttachment);
STDMETHOD(AddStorageController)(IN_BSTR aName, StorageBus_T aConnectionType, IStorageController **controller);
STDMETHOD(ReadSavedThumbnailToArray)(BOOL aBGR, ULONG *aWidth, ULONG *aHeight, ComSafeArrayOut(BYTE, aData));
STDMETHOD(ReadSavedScreenshotPNGToArray)(ULONG *aWidth, ULONG *aHeight, ComSafeArrayOut(BYTE, aData));
// public methods only for internal purposes
/**
* Simple run-time type identification without having to enable C++ RTTI.
* The class IDs are defined in VirtualBoxBase.h.
* @return
*/
{
return clsidMachine;
}
/**
* Override of the default locking class to be used for validating lock
* order with the standard member lock handle.
*/
{
return LOCKCLASS_MACHINEOBJECT;
}
/// @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!
// unsafe inline public methods for internal purposes only (ensure there is
// a caller and a read lock before calling them!)
/**
* Returns the VirtualBox object this machine belongs to.
*
* @note This method doesn't check this object's readiness. Intended to be
* used by ready Machine children (whose readiness is bound to the parent's
* one) or after doing addCaller() manually.
*/
/**
* Returns this machine ID.
*
* @note This method doesn't check this object's readiness. Intended to be
* used by ready Machine children (whose readiness is bound to the parent's
* one) or after adding a caller manually.
*/
/**
* Returns the snapshot ID this machine represents or an empty UUID if this
* instance is not SnapshotMachine.
*
* @note This method doesn't check this object's readiness. Intended to be
* used by ready Machine children (whose readiness is bound to the parent's
* one) or after adding a caller manually.
*/
inline const Guid& getSnapshotId() const;
/**
* Returns this machine's full settings file path.
*
* @note This method doesn't lock this object or check its readiness.
* Intended to be used only after doing addCaller() manually and locking it
* for reading.
*/
/**
* Returns this machine name.
*
* @note This method doesn't lock this object or check its readiness.
* Intended to be used only after doing addCaller() manually and locking it
* for reading.
*/
// callback handlers
virtual HRESULT onNetworkAdapterChange(INetworkAdapter * /* networkAdapter */, BOOL /* changeAdapter */) { return S_OK; }
virtual HRESULT onMediumChange(IMediumAttachment * /* mediumAttachment */, BOOL /* force */) { return S_OK; }
#if defined(RT_OS_WINDOWS)
#else
bool aAllowClosing = false);
bool isSessionSpawning();
#endif
bool checkForSpawnFailure();
bool aSetError = false)
{
}
void releaseStateDependency();
// for VirtualBoxSupportErrorInfoImpl
/**
* Returns the handle of the snapshots tree lock. This lock is
* machine-specific because there is one snapshots tree per
* IMachine; the lock protects the "first snapshot" member in
* IMachine and all the children and parent links in snapshot
* objects pointed to therefrom.
*
* Locking order:
* a) object lock of the machine;
* b) snapshots tree lock of the machine;
* c) individual snapshot object locks in parent->child order,
* if needed; they are _not_ needed for the tree itself
* (as defined above).
*/
RWLockHandle* snapshotsTreeLockHandle() const
{
return &mData->mSnapshotsTreeLockHandle;
}
inline Machine *getMachine();
void ensureNoStateDependencies();
bool aSetError = false);
const Guid &aCurSnapshotId,
bool aRegistered,
bool aRegistered,
bool aSetError = false);
bool aSetError = false);
bool aSetError = false);
enum
{
/* flags for #saveSettings() */
SaveS_ResetCurStateModified = 0x01,
SaveS_InformCallbacksAnyway = 0x02,
/* flags for #saveSnapshotSettings() */
SaveSS_CurStateModified = 0x40,
SaveSS_CurrentId = 0x80,
/* flags for #saveStateSettings() */
SaveSTS_CurStateModified = 0x20,
SaveSTS_StateFilePath = 0x40,
SaveSTS_StateTimeStamp = 0x80,
};
bool aOnline);
bool isModified();
bool isReallyModified(bool aIgnoreUserData = false);
void commit();
#ifdef VBOX_WITH_RESOURCE_USAGE_API
#endif /* VBOX_WITH_RESOURCE_USAGE_API */
// 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
/**
* Simple run-time type identification without having to enable C++ RTTI.
* The class IDs are defined in VirtualBoxBase.h.
* @return
*/
{
return clsidSessionMachine;
}
bool checkForDeath();
struct SnapshotData
{
// used when taking snapshot
// used when saving state
};
struct Uninit
{
};
struct SnapshotTask;
struct DeleteSnapshotTask;
struct RestoreSnapshotTask;
friend struct DeleteSnapshotTask;
friend struct RestoreSnapshotTask;
void unlockMedia();
/** interprocess semaphore handle for this machine */
#if defined(RT_OS_WINDOWS)
#elif defined(VBOX_WITH_SYS_V_IPC_SESSION_WATCHER)
int mIPCSem;
# ifdef VBOX_WITH_NEW_SYS_V_KEYGEN
# endif /*VBOX_WITH_NEW_SYS_V_KEYGEN */
#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
const Utf8Str &aStateFilePath);
const Utf8Str &aStateFilePath);
void uninit();
// util::Lockable interface
RWLockHandle *lockHandle() const;
// public methods only for internal purposes
/**
* Simple run-time type identification without having to enable C++ RTTI.
* The class IDs are defined in VirtualBoxBase.h.
* @return
*/
{
return clsidSnapshotMachine;
}
// unsafe inline public methods for internal purposes only (ensure there is
// a caller and a read lock before calling them!)
};
// third party methods that depend on SnapshotMachine definiton
{
return getClassID() != clsidSnapshotMachine
}
////////////////////////////////////////////////////////////////////////////////
/**
* 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 (getClassID() == clsidSessionMachine)
return mPeer;
return this;
}
#endif // ____H_MACHINEIMPL
/* vi: set tabstop=4 shiftwidth=4 expandtab: */