MachineImpl.h revision 28d4dbbfa7d1c70c7005970547915b8a3a1eefbe
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * VirtualBox COM class declaration
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * available from http://www.virtualbox.org. This file is free software;
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * you can redistribute it and/or modify it under the terms of the GNU
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * General Public License (GPL) as published by the Free Software
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * additional information or have any questions.
3aad980b92149dd95a1ab72ddb8d11d61a28ace6vboxsync#endif /* VBOX_WITH_RESOURCE_USAGE_API */
3aad980b92149dd95a1ab72ddb8d11d61a28ace6vboxsync// generated header
7ccd30dd4bbced565b32c255a11640cd4093abb6vboxsync////////////////////////////////////////////////////////////////////////////////
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync// helper declarations
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync////////////////////////////////////////////////////////////////////////////////
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync// Machine class
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync////////////////////////////////////////////////////////////////////////////////
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync public VirtualBoxSupportErrorInfoImpl <Machine, IMachine>,
d605d5391db09e6395a1c091f148f4b86af84bd3vboxsync enum InstanceType { IsMachine, IsSessionMachine, IsSnapshotMachine };
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * Internal machine data.
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * Only one instance of this data exists per every machine --
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * it is shared by the Machine, SessionMachine and all SnapshotMachine
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * instances associated with the given machine using the util::Shareable
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * template through the mData variable.
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * @note |const| members are persistent during lifetime so can be
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * accessed without locking.
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * @note There is no need to lock anything inside init() or uninit()
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * methods, because they are always serialized (see AutoCaller).
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * Data structure to hold information about sessions opened for the
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * given machine.
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync /** Control of the direct session opened by openSession() */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync typedef std::list <ComPtr <IInternalSessionControl> > RemoteControlList;
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync /** list of controls of all opened remote sessions */
ab93606043a9881487aa83be04191d2f4ea24071vboxsync /** openRemoteSession() and OnSessionEnd() progress indicator */
ab93606043a9881487aa83be04191d2f4ea24071vboxsync * PID of the session object that must be passed to openSession()
ab93606043a9881487aa83be04191d2f4ea24071vboxsync * to finalize the openRemoteSession() request
ab93606043a9881487aa83be04191d2f4ea24071vboxsync * (i.e., PID of the process created by openRemoteSession())
89dfdbb56cf9dddad3c7685b41bda1e4e4c1d6f9vboxsync /** Current session state */
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync /** Session type string (for indirect sessions) */
2e42e0850e182e37277fe28ba5b5d1c37018e783vboxsync /** Session machine object */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync /* Note: These are guarded by VirtualBoxBase::stateLockHandle() */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * Saved state data.
81cfcb51c89626fd5d331d92dcec81c94a5e9d2fvboxsync * It's actually only the state file path string, but it needs to be
89dfdbb56cf9dddad3c7685b41bda1e4e4c1d6f9vboxsync * separate from Data, because Machine and SessionMachine instances
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * share it, while SnapshotMachine does not.
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * The data variable is |mSSData|.
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * User changeable machine data.
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * This data is common for all machine snapshots, i.e. it is shared
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * by all SnapshotMachine instances associated with the given machine
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * using the util::Backupable template through the |mUserData| variable.
ab93606043a9881487aa83be04191d2f4ea24071vboxsync * SessionMachine instances can alter this data and discard changes.
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * @note There is no need to lock anything inside init() or uninit()
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * methods, because they are always serialized (see AutoCaller).
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * Hardware data.
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * This data is unique for a machine and for every machine snapshot.
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * Stored using the util::Backupable template in the |mHWData| variable.
ab93606043a9881487aa83be04191d2f4ea24071vboxsync * SessionMachine instances can alter this data and discard changes.
ab93606043a9881487aa83be04191d2f4ea24071vboxsync * Data structure to hold information about a guest property.
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync /** Property name */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync /** Property value */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync /** Property timestamp */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync /** Property flags */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync DeviceType_T mBootOrder [SchemaDefs::MaxBootPosition];
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync typedef std::list <ComObjPtr <SharedFolder> > SharedFolderList;
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync typedef std::list <GuestProperty> GuestPropertyList;
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * Hard disk data.
d605d5391db09e6395a1c091f148f4b86af84bd3vboxsync * The usage policy is the same as for HWData, but a separate structure
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync * is necessary because hard disk data requires different procedures when
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync * taking or discarding snapshots, etc.
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync * The data variable is |mHWData|.
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync typedef std::list< ComObjPtr<HardDiskAttachment> > AttachmentList;
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync AnyStateDep = 0, MutableStateDep, MutableOrSavedStateDep
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync * Helper class that safely manages the machine state dependency by
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync * calling Machine::addStateDependency() on construction and
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync * Machine::releaseStateDependency() on destruction. Intended for Machine
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync * children. The usage pattern is:
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * AutoCaller autoCaller (this);
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * CheckComRCReturnRC (autoCaller.rc());
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * Machine::AutoStateDependency <MutableStateDep> adep (mParent);
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * CheckComRCReturnRC (stateDep.rc());
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * // code that depends on the particular machine state
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * Note that it is more convenient to use the following individual
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * shortcut classes instead of using this template directly:
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * AutoAnyStateDependency, AutoMutableStateDependency and
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * AutoMutableOrSavedStateDependency. The usage pattern is exactly the
8fdb63a0d23d1618724f651b8c3d11be48b44d35vboxsync * same as above except that there is no need to specify the template
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * argument because it is already done by the shortcut class.
89dfdbb56cf9dddad3c7685b41bda1e4e4c1d6f9vboxsync * @param taDepType Dependecy type to manage.
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync mRC = aThat->addStateDependency (taDepType, &mMachineState,
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync /** Decreases the number of dependencies before the instance is
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * destroyed. Note that will reset #rc() to E_FAIL. */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync /** Restores the number of callers after by #release(). #rc() will be
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * reset to the result of calling addStateDependency() and must be
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * rechecked to ensure the operation succeeded. */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync mRC = mThat->addStateDependency (taDepType, &mMachineState,
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync /** Returns the result of Machine::addStateDependency(). */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync /** Shortcut to SUCCEEDED (rc()). */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync /** Returns the machine state value as returned by
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * Machine::addStateDependency(). */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync MachineState_T machineState() const { return mMachineState; }
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync /** Returns the machine state value as returned by
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * Machine::addStateDependency(). */
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync BOOL machineRegistered() const { return mRegistered; }
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP (AutoStateDependency)
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * Shortcut to AutoStateDependency <AnyStateDep>.
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * See AutoStateDependency to get the usage pattern.
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync * Accepts any machine state and guarantees the state won't change before
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * this object is destroyed. If the machine state cannot be protected (as
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync * a result of the state change currently in progress), this instance's
68308f6fe3c9a03c39acd9615d767ad0b3b5dcedvboxsync * #rc() method will indicate a failure, and the caller is not allowed to
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * rely on any particular machine state and should return the failed
9e5c26690d45216629b5f588aced8fcfb68c23b6vboxsync * result code to the upper level.
333e7ab9cd83b32080826d06ac7b1951c684ccb5vboxsync typedef AutoStateDependency <AnyStateDep> AutoAnyStateDependency;
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * Shortcut to AutoStateDependency <MutableStateDep>.
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * See AutoStateDependency to get the usage pattern.
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * Succeeds only if the machine state is in one of the mutable states, and
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * guarantees the given mutable state won't change before this object is
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * destroyed. If the machine is not mutable, this instance's #rc() method
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * will indicate a failure, and the caller is not allowed to rely on any
333e7ab9cd83b32080826d06ac7b1951c684ccb5vboxsync * particular machine state and should return the failed result code to
333e7ab9cd83b32080826d06ac7b1951c684ccb5vboxsync * the upper level.
333e7ab9cd83b32080826d06ac7b1951c684ccb5vboxsync * Intended to be used within all setter methods of IMachine
333e7ab9cd83b32080826d06ac7b1951c684ccb5vboxsync * children objects (DVDDrive, NetworkAdapter, AudioAdapter, etc.) to
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * provide data protection and consistency.
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync typedef AutoStateDependency <MutableStateDep> AutoMutableStateDependency;
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * Shortcut to AutoStateDependency <MutableOrSavedStateDep>.
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * See AutoStateDependency to get the usage pattern.
333e7ab9cd83b32080826d06ac7b1951c684ccb5vboxsync * Succeeds only if the machine state is in one of the mutable states, or
333e7ab9cd83b32080826d06ac7b1951c684ccb5vboxsync * if the machine is in the Saved state, and guarantees the given mutable
333e7ab9cd83b32080826d06ac7b1951c684ccb5vboxsync * state won't change before this object is destroyed. If the machine is
333e7ab9cd83b32080826d06ac7b1951c684ccb5vboxsync * not mutable, this instance's #rc() method will indicate a failure, and
333e7ab9cd83b32080826d06ac7b1951c684ccb5vboxsync * the caller is not allowed to rely on any particular machine state and
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * should return the failed result code to the upper level.
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * Intended to be used within setter methods of IMachine
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync * children objects that may also operate on Saved machines.
8e342a5c34610667d2b554cb86f1dc2f38a5313cvboxsync typedef AutoStateDependency <MutableOrSavedStateDep> AutoMutableOrSavedStateDependency;
void FinalRelease();
// public initializer/uninitializer for internal purposes only
void uninit();
STDMETHOD(EnumerateGuestProperties) (IN_BSTR aPattern, ComSafeArrayOut(BSTR, aNames), ComSafeArrayOut(BSTR, aValues), ComSafeArrayOut(ULONG64, aTimestamps), ComSafeArrayOut(BSTR, aFlags));
#if defined (RT_OS_WINDOWS)
bool aAllowClosing = false);
bool isSessionSpawning();
bool checkForSpawnFailure();
bool aSetError = false)
void releaseStateDependency();
void uninitDataAndChildObjects();
void ensureNoStateDependencies();
bool aSetError = false);
bool aSetError = false);
bool aSetError = false);
bool aOnline);
bool isModified();
void commit();
#ifdef VBOX_WITH_RESOURCE_USAGE_API
void FinalRelease();
// public initializer/uninitializer for internal purposes only
bool checkForDeath();
struct SnapshotData
struct Uninit
struct Task;
struct TakeSnapshotTask;
struct DiscardSnapshotTask;
struct DiscardCurrentStateTask;
#if defined (RT_OS_WINDOWS)
int mIPCSem;
# ifdef VBOX_WITH_NEW_SYS_V_KEYGEN
void FinalRelease();
// public initializer/uninitializer for internal purposes only
void uninit();
return mPeer;
return this;