MachineImpl.h revision 1a3fdaf7f4fdfc0680a7091ba9c1e7309098ff2b
/* $Id$ */
/** @file
* Implementation of IMachine in VBoxSVC - Header.
*/
/*
* Copyright (C) 2006-2013 Oracle Corporation
*
* 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.
*/
#ifndef ____H_MACHINEIMPL
#define ____H_MACHINEIMPL
#include "VirtualBoxBase.h"
#include "SnapshotImpl.h"
#include "ProgressImpl.h"
#include "VRDEServerImpl.h"
#include "MediumAttachmentImpl.h"
#include "PCIDeviceAttachmentImpl.h"
#include "MediumLock.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 "BandwidthControlImpl.h"
#include "BandwidthGroupImpl.h"
#include "VBox/settings.h"
#ifdef VBOX_WITH_RESOURCE_USAGE_API
#include "Performance.h"
#include "PerformanceImpl.h"
#endif /* VBOX_WITH_RESOURCE_USAGE_API */
// generated header
#include "SchemaDefs.h"
#include "VBox/com/ErrorInfo.h"
#include <list>
#include <vector>
// defines
////////////////////////////////////////////////////////////////////////////////
// helper declarations
////////////////////////////////////////////////////////////////////////////////
{
struct Snapshot;
struct Hardware;
struct Storage;
struct StorageController;
struct MachineRegistryEntry;
}
// Machine class
////////////////////////////////////////////////////////////////////////////////
{
enum StateDependency
{
AnyStateDep = 0,
};
/**
* 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 lockMachine() */
/** list of controls of all opened remote sessions */
/** launchVMProcess() and OnSessionEnd() progress indicator */
/**
* PID of the session object that must be passed to openSession()
* to finalize the launchVMProcess() request (i.e., PID of the
* process created by launchVMProcess())
*/
/** Current session state */
/** Session type string (for indirect sessions) */
/** Session machine object */
/** Medium object lock collection. */
};
Data();
~Data();
// machine settings XML file
/* Note: These are guarded by VirtualBoxBase::stateLockHandle() */
/** Guest properties have been modified and need saving since the
* machine was started, or there are transient properties which need
* deleting and the machine is being shut down. */
// list of files to delete in Delete(); this list is filled by Unregister()
};
/**
* 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
{
};
/**
* 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 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 deleting snapshots, etc.
*
* The data variable is |mMediaData|.
*/
struct MediaData
{
MediaData();
~MediaData();
};
void FinalRelease();
// public initializer/uninitializer for internal purposes only:
// initializer for creating a new, empty machine
const Utf8Str &strConfigFile,
const StringsList &llGroups,
bool fForceOverwrite,
bool fDirectoryIncludesUUID);
// initializer for loading existing machine XML (either registered or not)
const Utf8Str &strConfigFile,
// initializer for machine config in memory (OVF import)
void uninit();
#ifdef VBOX_WITH_RESOURCE_USAGE_API
// Needed from VirtualBox, for the delayed metrics cleanup.
#endif /* VBOX_WITH_RESOURCE_USAGE_API */
const Utf8Str &strConfigFile);
void uninitDataAndChildObjects();
// IMachine properties
STDMETHOD(COMGETTER(StorageControllers))(ComSafeArrayOut(IStorageController *, aStorageControllers));
// IMachine methods
STDMETHOD(LaunchVMProcess)(ISession *aSession, IN_BSTR aType, IN_BSTR aEnvironment, IProgress **aProgress);
STDMETHOD(PassthroughDevice)(IN_BSTR aControllerName, LONG aControllerPort, LONG aDevice, BOOL aPassthrough);
STDMETHOD(TemporaryEjectDevice)(IN_BSTR aControllerName, LONG aControllerPort, LONG aDevice, BOOL aTempEject);
STDMETHOD(NonRotationalDevice)(IN_BSTR aControllerName, LONG aControllerPort, LONG aDevice, BOOL aNonRotational);
STDMETHOD(SetAutoDiscardForDevice)(IN_BSTR aControllerName, LONG aControllerPort, LONG aDevice, BOOL aDiscard);
STDMETHOD(ExportTo)(IAppliance *aAppliance, IN_BSTR location, IVirtualSystemDescription **aDescription);
STDMETHOD(EnumerateGuestProperties)(IN_BSTR aPattern, ComSafeArrayOut(BSTR, aNames), ComSafeArrayOut(BSTR, aValues), ComSafeArrayOut(LONG64, 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(QuerySavedGuestScreenInfo)(ULONG uScreenId, ULONG *puOriginX, ULONG *puOriginY, ULONG *puWidth, ULONG *puHeight, BOOL *pfEnabled);
STDMETHOD(ReadSavedThumbnailToArray)(ULONG aScreenId, BOOL aBGR, ULONG *aWidth, ULONG *aHeight, ComSafeArrayOut(BYTE, aData));
STDMETHOD(ReadSavedThumbnailPNGToArray)(ULONG aScreenId, ULONG *aWidth, ULONG *aHeight, ComSafeArrayOut(BYTE, aData));
STDMETHOD(QuerySavedScreenshotPNGSize)(ULONG aScreenId, ULONG *aSize, ULONG *aWidth, ULONG *aHeight);
STDMETHOD(ReadSavedScreenshotPNGToArray)(ULONG aScreenId, ULONG *aWidth, ULONG *aHeight, ComSafeArrayOut(BYTE, aData));
STDMETHOD(CloneTo(IMachine *pTarget, CloneMode_T mode, ComSafeArrayIn(CloneOptions_T, options), IProgress **pProgress));
// public methods only for internal purposes
virtual bool isSnapshotMachine() const
{
return false;
}
virtual bool isSessionMachine() const
{
return false;
}
/**
* 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.
*/
/**
* Checks if this machine is accessible, without attempting to load the
* config file.
*
* @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.
*/
enum
{
IsModified_MachineData = 0x0001,
IsModified_Storage = 0x0002,
IsModified_NetworkAdapters = 0x0008,
IsModified_SerialPorts = 0x0010,
IsModified_ParallelPorts = 0x0020,
IsModified_VRDEServer = 0x0040,
IsModified_AudioAdapter = 0x0080,
IsModified_USB = 0x0100,
IsModified_BIOS = 0x0200,
IsModified_SharedFolders = 0x0400,
IsModified_Snapshots = 0x0800,
IsModified_BandwidthControl = 0x1000
};
/**
* Returns various information about this machine.
*
* @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; }
NATProtocol_T /* protocol */, IN_BSTR /* host ip */, LONG /* host port */, IN_BSTR /* guest port */, LONG /* guest port */ ) { return S_OK; }
virtual HRESULT onMediumChange(IMediumAttachment * /* mediumAttachment */, BOOL /* force */) { return S_OK; }
virtual HRESULT onStorageDeviceChange(IMediumAttachment * /* mediumAttachment */, BOOL /* remove */, BOOL /* silent */) { return S_OK; }
const Utf8Str &strEnvironment,
{
if (!*directControl)
rc = E_ACCESSDENIED;
else
return rc;
}
#if defined(RT_OS_WINDOWS)
#else
bool aAllowClosing = false);
bool isSessionSpawning();
#endif
bool checkForSpawnFailure();
bool aSetError = false)
{
}
void releaseStateDependency();
bool fSetError = false)
{
}
Machine *getMachine();
void ensureNoStateDependencies();
bool aSetError = false);
const Guid *puuidRegistry);
const Guid &aCurSnapshotId,
const Guid *puuidRegistry,
const Guid *puuidSnapshot);
const Guid *puuidRegistry,
const Guid *puuidSnapshot);
bool aSetError = false);
bool aSetError = false);
bool aSetError = false);
enum
{
/* flags for #saveSettings() */
SaveS_ResetCurStateModified = 0x01,
SaveS_InformCallbacksAnyway = 0x02,
SaveS_Force = 0x04,
/* flags for #saveStateSettings() */
SaveSTS_CurStateModified = 0x20,
SaveSTS_StateFilePath = 0x40,
SaveSTS_StateTimeStamp = 0x80
};
bool aOnline);
void commitMedia(bool aOnline = false);
void rollbackMedia();
void commit();
struct DeleteTask;
#ifdef VBOX_WITH_GUEST_PROPS
#endif /* VBOX_WITH_GUEST_PROPS */
#ifdef VBOX_WITH_RESOURCE_USAGE_API
#endif /* VBOX_WITH_RESOURCE_USAGE_API */
VirtualBox * const mParent;
// so they cannot be a part of HWData
};
// 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
STDMETHOD(UnlockMedia)();
// public methods only for internal purposes
virtual bool isSessionMachine() const
{
return true;
}
bool checkForDeath();
void unlockMedia();
struct ConsoleTaskData
{
{ }
// used when taking snapshot
// used when saving state (either as part of a snapshot or separate)
};
struct Uninit
{
};
struct SnapshotTask;
struct DeleteSnapshotTask;
struct RestoreSnapshotTask;
friend struct DeleteSnapshotTask;
friend struct RestoreSnapshotTask;
const Guid &snapshotId,
bool fOnlineMergePossible,
bool &fMergeForward,
bool &fNeedOnlineMerge,
const MediaList &aChildrenToReparent,
bool fNeedsOnlineMerge,
const Guid &aSnapshotId);
bool fMergeForward,
const MediaList &aChildrenToReparent,
bool *pfNeedsMachineSaveSettings);
/** 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
virtual bool isSnapshotMachine() const
{
return true;
}
// unsafe inline public methods for internal purposes only (ensure there is
// a caller and a read lock before calling them!)
/** This field replaces mPeer for SessionMachine instances, as having
* a peer reference is plain meaningless and causes many subtle problems
* with saving settings and the like. */
};
// third party methods that depend on SnapshotMachine definition
{
return (isSnapshotMachine())
}
#endif // ____H_MACHINEIMPL
/* vi: set tabstop=4 shiftwidth=4 expandtab: */