e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * AutoStateDep template classes, formerly in MachineImpl.h. Use these if
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * you need to ensure that the machine state does not change over a certain
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * period of time.
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * Copyright (C) 2006-2015 Oracle Corporation
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * available from http://www.virtualbox.org. This file is free software;
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * you can redistribute it and/or modify it under the terms of the GNU
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * General Public License (GPL) as published by the Free Software
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Helper class that safely manages the machine state dependency by
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * calling Machine::addStateDependency() on construction and
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Machine::releaseStateDependency() on destruction. Intended for Machine
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * children. The usage pattern is:
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * AutoCaller autoCaller(this);
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * if (FAILED(autoCaller.rc())) return autoCaller.rc();
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Machine::AutoStateDependency<MutableStateDep> adep(mParent);
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * if (FAILED(stateDep.rc())) return stateDep.rc();
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * // code that depends on the particular machine state
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Note that it is more convenient to use the following individual
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * shortcut classes instead of using this template directly:
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * AutoAnyStateDependency, AutoMutableStateDependency,
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * AutoMutableOrSavedStateDependency, AutoMutableOrRunningStateDependency
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * or AutoMutableOrSavedOrRunningStateDependency. The usage pattern is
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * exactly the same as above except that there is no need to specify the
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * template argument because it is already done by the shortcut class.
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * @param taDepType Dependency type to manage.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync template <Machine::StateDependency taDepType = Machine::AnyStateDep>
d7a2c5e4cc83588b277fd8f28a288773173c3638vboxsync mRC = aThat->i_addStateDependency(taDepType, &mMachineState,
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync /** Decreases the number of dependencies before the instance is
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * destroyed. Note that will reset #rc() to E_FAIL. */
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync /** Restores the number of callers after by #release(). #rc() will be
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * reset to the result of calling addStateDependency() and must be
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * rechecked to ensure the operation succeeded. */
d7a2c5e4cc83588b277fd8f28a288773173c3638vboxsync mRC = mThat->i_addStateDependency(taDepType, &mMachineState,
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync /** Returns the result of Machine::addStateDependency(). */
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync /** Shortcut to SUCCEEDED(rc()). */
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync /** Returns the machine state value as returned by
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Machine::addStateDependency(). */
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync MachineState_T machineState() const { return mMachineState; }
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync /** Returns the machine state value as returned by
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Machine::addStateDependency(). */
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync BOOL machineRegistered() const { return mRegistered; }
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(AutoStateDependency)
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Shortcut to AutoStateDependency<AnyStateDep>.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * See AutoStateDependency to get the usage pattern.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Accepts any machine state and guarantees the state won't change before
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * this object is destroyed. If the machine state cannot be protected (as
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * a result of the state change currently in progress), this instance's
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * #rc() method will indicate a failure, and the caller is not allowed to
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * rely on any particular machine state and should return the failed
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * result code to the upper level.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync typedef AutoStateDependency<Machine::AnyStateDep> AutoAnyStateDependency;
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Shortcut to AutoStateDependency<MutableStateDep>.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * See AutoStateDependency to get the usage pattern.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Succeeds only if the machine state is in one of the mutable states, and
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * guarantees the given mutable state won't change before this object is
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * destroyed. If the machine is not mutable, this instance's #rc() method
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * will indicate a failure, and the caller is not allowed to rely on any
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * particular machine state and should return the failed result code to
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * the upper level.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Intended to be used within all setter methods of IMachine
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * children objects (DVDDrive, NetworkAdapter, AudioAdapter, etc.) to
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * provide data protection and consistency. There must be no VM process,
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * i.e. use for settings changes which are valid when the VM is shut down.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync typedef AutoStateDependency<Machine::MutableStateDep> AutoMutableStateDependency;
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Shortcut to AutoStateDependency<MutableOrSavedStateDep>.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * See AutoStateDependency to get the usage pattern.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Succeeds only if the machine state is in one of the mutable states, or
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * if the machine is in the Saved state, and guarantees the given mutable
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * state won't change before this object is destroyed. If the machine is
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * not mutable, this instance's #rc() method will indicate a failure, and
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * the caller is not allowed to rely on any particular machine state and
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * should return the failed result code to the upper level.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync * Intended to be used within setter methods of IMachine
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * children objects that may operate on shut down or Saved machines.
e549f3c30064b8ab020cf6afba22202b6cb67826vboxsync typedef AutoStateDependency<Machine::MutableOrSavedStateDep> AutoMutableOrSavedStateDependency;
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * Shortcut to AutoStateDependency<MutableOrRunningStateDep>.
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * See AutoStateDependency to get the usage pattern.
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * Succeeds only if the machine state is in one of the mutable states, or
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * if the machine is in the Running or Paused state, and guarantees the
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * given mutable state won't change before this object is destroyed. If
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * the machine is not mutable, this instance's #rc() method will indicate
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * a failure, and the caller is not allowed to rely on any particular
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * machine state and should return the failed result code to the upper
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * Intended to be used within setter methods of IMachine
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * children objects that may operate on shut down or running machines.
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync typedef AutoStateDependency<Machine::MutableOrRunningStateDep> AutoMutableOrRunningStateDependency;
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * Shortcut to AutoStateDependency<MutableOrSavedOrRunningStateDep>.
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * See AutoStateDependency to get the usage pattern.
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * Succeeds only if the machine state is in one of the mutable states, or
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * if the machine is in the Running, Paused or Saved state, and guarantees
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * the given mutable state won't change before this object is destroyed.
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * If the machine is not mutable, this instance's #rc() method will
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * indicate a failure, and the caller is not allowed to rely on any
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * particular machine state and should return the failed result code to
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * the upper level.
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * Intended to be used within setter methods of IMachine
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * children objects that may operate on shut down, running or saved
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync * machines.
fb7940000e0c1e00d24d63bd6bffa8301c27e1bdvboxsync typedef AutoStateDependency<Machine::MutableOrSavedOrRunningStateDep> AutoMutableOrSavedOrRunningStateDependency;
d2eb2dd8411143258dc87a4a93e66d2c03e51e64vboxsync#endif // ____H_AUTOSTATEDEP