VirtualBoxBase.h revision eac182663e63d061d767c2f783a6e1be8c1209ca
/** @file
*
* VirtualBox COM base classes definition
*/
/*
* Copyright (C) 2006-2010 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_VIRTUALBOXBASEIMPL
#define ____H_VIRTUALBOXBASEIMPL
#include <list>
#include <map>
#include "VBox/com/ErrorInfo.h"
#include "VBox/com/SupportErrorInfo.h"
#include "VBox/com/AutoLock.h"
#include "VBox/com/VirtualBox.h"
// avoid including VBox/settings.h and VBox/xml.h;
// only declare the classes
{
}
////////////////////////////////////////////////////////////////////////////////
//
// COM helpers
//
////////////////////////////////////////////////////////////////////////////////
#if !defined (VBOX_WITH_XPCOM)
#include <atlcom.h>
/* use a special version of the singleton class factory,
* see KB811591 in msdn for more info. */
#define DECLARE_CLASSFACTORY_SINGLETON(obj) DECLARE_CLASSFACTORY_EX(CMyComClassFactorySingleton<obj>)
{
// IClassFactory
{
{
// Aggregation is not supported in singleton objects.
else
{
{
Lock();
{
// Fix: The following If statement was moved inside the __try statement.
// Did another thread arrive here first?
{
// lock the module to indicate activity
// (necessary for the monitor shutdown thread to correctly
// terminate the module in case when CreateInstance() fails)
_pAtlModule->Lock();
CComObjectCached<T> *p;
if (SUCCEEDED(m_hrCreate))
{
if (FAILED(m_hrCreate))
{
delete p;
}
}
_pAtlModule->Unlock();
}
}
{
Unlock();
}
}
if (m_hrCreate == S_OK)
{
}
else
{
hRes = m_hrCreate;
}
}
}
return hRes;
}
};
#endif /* !defined (VBOX_WITH_XPCOM) */
////////////////////////////////////////////////////////////////////////////////
//
// Macros
//
////////////////////////////////////////////////////////////////////////////////
/**
* Special version of the Assert macro to be used within VirtualBoxBase
* subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
*
* In the debug build, this macro is equivalent to Assert.
* In the release build, this macro uses |setError(E_FAIL, ...)| to set the
* error info from the asserted expression.
*
* @see VirtualBoxSupportErrorInfoImpl::setError
*
* @param expr Expression which should be true.
*/
#if defined (DEBUG)
#else
do { \
if (RT_UNLIKELY(!(expr))) \
"Please contact the product vendor!", \
} while (0)
#endif
/**
* Special version of the AssertMsg macro to be used within VirtualBoxBase
* subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
*
* See ComAssert for more info.
*
* @param expr Expression which should be true.
* @param a printf argument list (in parenthesis).
*/
#if defined (DEBUG)
#else
#define ComAssertMsg(expr, a) \
do { \
if (RT_UNLIKELY(!(expr))) \
"%s.\n" \
"Please contact the product vendor!", \
} while (0)
#endif
/**
* Special version of the AssertRC macro to be used within VirtualBoxBase
* subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
*
* See ComAssert for more info.
*
* @param vrc VBox status code.
*/
#if defined (DEBUG)
#else
#endif
/**
* Special version of the AssertMsgRC macro to be used within VirtualBoxBase
* subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
*
* See ComAssert for more info.
*
* @param vrc VBox status code.
* @param msg printf argument list (in parenthesis).
*/
#if defined (DEBUG)
#else
#endif
/**
* Special version of the AssertComRC macro to be used within VirtualBoxBase
* subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
*
* See ComAssert for more info.
*
* @param rc COM result code
*/
#if defined (DEBUG)
#else
#endif
/** Special version of ComAssert that returns ret if expr fails */
/** Special version of ComAssertMsg that returns ret if expr fails */
/** Special version of ComAssertRC that returns ret if vrc does not succeed */
/** Special version of ComAssertMsgRC that returns ret if vrc does not succeed */
/** Special version of ComAssertFailed that returns ret */
#define ComAssertFailedRet(ret) \
do { ComAssertFailed(); return (ret); } while (0)
/** Special version of ComAssertMsgFailed that returns ret */
/** Special version of ComAssertComRC that returns ret if rc does not succeed */
/** Special version of ComAssertComRC that returns rc if rc does not succeed */
#define ComAssertComRCRetRC(rc) \
/** Special version of ComAssert that evaluates eval and breaks if expr fails */
/** Special version of ComAssertMsg that evaluates eval and breaks if expr fails */
/** Special version of ComAssertRC that evaluates eval and breaks if vrc does not succeed */
/** Special version of ComAssertMsgRC that evaluates eval and breaks if vrc does not succeed */
/** Special version of ComAssertFailed that evaluates eval and breaks */
#define ComAssertFailedBreak(eval) \
/** Special version of ComAssertMsgFailed that evaluates eval and breaks */
/** Special version of ComAssertComRC that evaluates eval and breaks if rc does not succeed */
/** Special version of ComAssertComRC that just breaks if rc does not succeed */
#define ComAssertComRCBreakRC(rc) \
/** Special version of ComAssert that evaluates eval and throws it if expr fails */
/** Special version of ComAssertMsg that evaluates eval and throws it if expr fails */
/** Special version of ComAssertRC that evaluates eval and throws it if vrc does not succeed */
/** Special version of ComAssertMsgRC that evaluates eval and throws it if vrc does not succeed */
/** Special version of ComAssertFailed that evaluates eval and throws it */
#define ComAssertFailedThrow(eval) \
/** Special version of ComAssertMsgFailed that evaluates eval and throws it */
/** Special version of ComAssertComRC that evaluates eval and throws it if rc does not succeed */
/** Special version of ComAssertComRC that just throws rc if rc does not succeed */
#define ComAssertComRCThrowRC(rc) \
////////////////////////////////////////////////////////////////////////////////
/**
* Checks that the pointer argument is not NULL and returns E_INVALIDARG +
* extended error info on failure.
* @param arg Input pointer-type argument (strings, interface pointers...)
*/
#define CheckComArgNotNull(arg) \
do { \
} while (0)
/**
* Checks that safe array argument is not NULL and returns E_INVALIDARG +
* extended error info on failure.
* @param arg Input safe array argument (strings, interface pointers...)
*/
#define CheckComArgSafeArrayNotNull(arg) \
do { \
} while (0)
/**
* Checks that the string argument is not a NULL or empty string and returns
* E_INVALIDARG + extended error info on failure.
* @param arg Input string argument (BSTR etc.).
*/
#define CheckComArgStrNotEmptyOrNull(arg) \
do { \
return setError(E_INVALIDARG, \
} while (0)
/**
* Checks that the given expression (that must involve the argument) is true and
* returns E_INVALIDARG + extended error info on failure.
* @param arg Argument.
* @param expr Expression to evaluate.
*/
do { \
if (RT_UNLIKELY(!(expr))) \
return setError(E_INVALIDARG, \
} while (0)
/**
* Checks that the given expression (that must involve the argument) is true and
* returns E_INVALIDARG + extended error info on failure. The error message must
* be customized.
* @param arg Argument.
* @param expr Expression to evaluate.
* @param msg Parenthesized printf-like expression (must start with a verb,
* like "must be one of...", "is not within...").
*/
do { \
if (RT_UNLIKELY(!(expr))) \
} while (0)
/**
* Checks that the given pointer to an output argument is valid and returns
* E_POINTER + extended error info otherwise.
* @param arg Pointer argument.
*/
#define CheckComArgOutPointerValid(arg) \
do { \
tr("Output argument %s points to invalid memory location (%p)"), \
} while (0)
/**
* Checks that the given pointer to an output safe array argument is valid and
* returns E_POINTER + extended error info otherwise.
* @param arg Safe array argument.
*/
#define CheckComArgOutSafeArrayPointerValid(arg) \
do { \
tr("Output argument %s points to invalid memory location (%p)"), \
} while (0)
/**
* Sets the extended error info and returns E_NOTIMPL.
*/
#define ReturnComNotImplemented() \
do { \
} while (0)
/**
* Declares an empty constructor and destructor for the given class.
* This is useful to prevent the compiler from generating the default
* ctor and dtor, which in turn allows to use forward class statements
* (instead of including their header files) when declaring data members of
* non-fundamental types with constructors (which are always called implicitly
* by constructors and by the destructor of the class).
*
* This macro is to be placed within (the public section of) the class
* declaration. Its counterpart, DEFINE_EMPTY_CTOR_DTOR, must be placed
* somewhere in one of the translation units (usually .cpp source files).
*
* @param cls class to declare a ctor and dtor for
*/
/**
* Defines an empty constructor and destructor for the given class.
* See DECLARE_EMPTY_CTOR_DTOR for more info.
*/
#define DEFINE_EMPTY_CTOR_DTOR(cls) \
////////////////////////////////////////////////////////////////////////////////
//
// VirtualBoxBase
//
////////////////////////////////////////////////////////////////////////////////
/**
* This enum is used in the virtual method VirtualBoxBasePro::getClassID() to
* allow VirtualBox classes to identify themselves. Subclasses can override
* that method and return a value from this enum if run-time identification is
* needed anywhere.
*/
enum VBoxClsID
{
};
/**
* Abstract base class for all component classes implementing COM
* interfaces of the VirtualBox COM library.
*
* Declares functionality that should be available in all components.
*
* Note that this class is always subclassed using the virtual keyword so
* that only one instance of its VTBL and data is present in each derived class
* even in case if VirtualBoxBaseProto appears more than once among base classes
* of the particular component as a result of multiple inheritance.
*
* This makes it possible to have intermediate base classes used by several
* components that implement some common interface functionality but still let
* the final component classes choose what VirtualBoxBase variant it wants to
* use.
*
* Among the basic functionality implemented by this class is the primary object
* state that indicates if the object is ready to serve the calls, and if not,
* what stage it is currently at. Here is the primary state diagram:
*
* +-------------------------------------------------------+
* | |
* | (InitFailed) -----------------------+ |
* | ^ | |
* v | v |
* [*] ---> NotReady ----> (InInit) -----> Ready -----> (InUninit) ----+
* ^ |
* | v
* | Limited
* | |
* +-------+
*
* The object is fully operational only when its state is Ready. The Limited
* state means that only some vital part of the object is operational, and it
* requires some sort of reinitialization to become fully operational. The
* NotReady state means the object is basically dead: it either was not yet
* initialized after creation at all, or was uninitialized and is waiting to be
* destroyed when the last reference to it is released. All other states are
* transitional.
*
* The NotReady->InInit->Ready, NotReady->InInit->Limited and
* NotReady->InInit->InitFailed transition is done by the AutoInitSpan smart
* class.
*
* The Limited->InInit->Ready, Limited->InInit->Limited and
* Limited->InInit->InitFailed transition is done by the AutoReinitSpan smart
* class.
*
* The Ready->InUninit->NotReady and InitFailed->InUninit->NotReady
* transitions are done by the AutoUninitSpan smart class.
*
* In order to maintain the primary state integrity and declared functionality
* all subclasses must:
*
* 1) Use the above Auto*Span classes to perform state transitions. See the
* individual class descriptions for details.
*
* 2) All public methods of subclasses (i.e. all methods that can be called
* directly, not only from within other methods of the subclass) must have a
* standard prolog as described in the AutoCaller and AutoLimitedCaller
* documentation. Alternatively, they must use addCaller()/releaseCaller()
* directly (and therefore have both the prolog and the epilog), but this is
* not recommended.
*/
{
const char *comment = 0);
/**
* Unintialization method.
*
* Must be called by all final implementations (component classes) when the
* last reference to the object is released, before calling the destructor.
*
* This method is also automatically called by the uninit() method of this
* object's parent if this object is a dependent child of a class derived
* from VirtualBoxBaseWithChildren (see
* VirtualBoxBaseWithChildren::addDependentChild).
*
* @note Never call this method the AutoCaller scope or after the
* #addCaller() call not paired by #releaseCaller() because it is a
* guaranteed deadlock. See AutoUninitSpan for details.
*/
virtual void releaseCaller();
/**
* Adds a limited caller. This method is equivalent to doing
* <tt>addCaller (aState, true)</tt>, but it is preferred because provides
* better self-descriptiveness. See #addCaller() for more info.
*/
{
}
/**
* Simple run-time type identification without having to enable C++ RTTI.
* The class IDs are defined in VirtualBoxBase.h.
* @return
*/
{
return clsidOther;
}
/**
* Override of the default locking class to be used for validating lock
* order with the standard member lock handle.
*/
{
return LOCKCLASS_OTHEROBJECT;
}
/**
* Returns a lock handle used to protect the primary state fields (used by
* #addCaller(), AutoInitSpan, AutoUninitSpan, etc.). Only intended to be
* used for similar purposes in subclasses. WARNING: NO any other locks may
* be requested while holding this lock!
*/
{
}
/** Primary state of this object */
/** Thread that caused the last state change */
/** Total number of active calls to this object */
unsigned mCallers;
/** Posted when the number of callers drops to zero */
/** Number of threads waiting for mInitUninitDoneSem */
unsigned mInitUninitWaiters;
/** Protects access to state related data members */
/** User-level object lock for subclasses */
};
////////////////////////////////////////////////////////////////////////////////
//
// VirtualBoxSupportTranslation, VirtualBoxSupportErrorInfoImpl
//
////////////////////////////////////////////////////////////////////////////////
/**
* This macro adds the error info support to methods of the VirtualBoxBase
* class (by overriding them). Place it to the public section of the
* VirtualBoxBase subclass and the following methods will set the extended
* error info in case of failure instead of just returning the result code:
*
* <ul>
* <li>VirtualBoxBase::addCaller()
* </ul>
*
* @note The given VirtualBoxBase subclass must also inherit from both
* VirtualBoxSupportErrorInfoImpl and VirtualBoxSupportTranslation templates!
*
* @param C VirtualBoxBase subclass to add the error info support to
*/
#define VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT(C) \
bool aLimited = false) \
{ \
{ \
else \
} \
if (aState) \
*aState = protoState; \
return rc; \
} \
////////////////////////////////////////////////////////////////////////////////
/** Helper for VirtualBoxSupportTranslation. */
{
static bool cutClassNameFrom__PRETTY_FUNCTION__(char *aPrettyFunctionName);
};
/**
* The VirtualBoxSupportTranslation template implements the NLS string
* translation support for the given class.
*
* Translation support is provided by the static #tr() function. This function,
* given a string in UTF-8 encoding, looks up for a translation of the given
* string by calling the VirtualBoxBase::translate() global function which
* receives the name of the enclosing class ("context of translation") as the
* additional argument and returns a translated string based on the currently
* active language.
*
* @param C Class that needs to support the string translation.
*
* @note Every class that wants to use the #tr() function in its own methods
* must inherit from this template, regardless of whether its base class
* (if any) inherits from it or not. Otherwise, the translation service
* will not work correctly. However, the declaration of the derived
* class must contain
* the <tt>COM_SUPPORTTRANSLATION_OVERRIDE (<ClassName>)</tt> macro if one
* of its base classes also inherits from this template (to resolve the
* ambiguity of the #tr() function).
*/
{
/**
* Translates the given text string by calling VirtualBoxBase::translate()
* and passing the name of the C class as the first argument ("context of
* translation") See VirtualBoxBase::translate() for more info.
*
* @param aSourceText String to translate.
* @param aComment Comment to the string to resolve possible
* ambiguities (NULL means no comment).
*
* @return Translated version of the source string in UTF-8 encoding, or
* the source string itself if the translation is not found in the
* specified context.
*/
inline static const char *tr(const char *aSourceText,
{
}
static const char *className()
{
if (!sClassName)
{
sClassName = fn;
}
return sClassName;
}
static const char *sClassName;
};
/**
* This macro must be invoked inside the public section of the declaration of
* the class inherited from the VirtualBoxSupportTranslation template in case
* if one of its other base classes also inherits from that template. This is
* necessary to resolve the ambiguity of the #tr() function.
*
* @param C Class that inherits the VirtualBoxSupportTranslation template
* more than once (through its other base clases).
*/
#define VIRTUALBOXSUPPORTTRANSLATION_OVERRIDE(C) \
inline static const char *tr(const char *aSourceText, \
{ \
}
/**
* Dummy macro that is used to shut down Qt's lupdate tool warnings in some
* situations. This macro needs to be present inside (better at the very
* beginning) of the declaration of the class that inherits from
* VirtualBoxSupportTranslation template, to make lupdate happy.
*/
#define Q_OBJECT
////////////////////////////////////////////////////////////////////////////////
/**
* Helper for the VirtualBoxSupportErrorInfoImpl template.
*/
/// @todo switch to com::SupportErrorInfo* and remove
{
const wchar_t *aComponent,
bool aWarning,
bool aLogIt);
/**
* The MultiResult class is a com::FWResult enhancement that also acts as a
* switch to turn on multi-error mode for #setError() or #setWarning()
* calls.
*
* When an instance of this class is created, multi-error mode is turned on
* for the current thread and the turn-on counter is increased by one. In
* multi-error mode, a call to #setError() or #setWarning() does not
* overwrite the current error or warning info object possibly set on the
* current thread by other method calls, but instead it stores this old
* object in the IVirtualBoxErrorInfo::next attribute of the new error
* object being set.
*
* errors where the most recent error is the first one retrieved by the
* calling party, the preceding error is what the
* IVirtualBoxErrorInfo::next attribute of the first error points to, and so
* on, up to the first error or warning occurred which is the last in the
* chain. See IVirtualBoxErrorInfo documentation for more info.
*
* When the instance of the MultiResult class goes out of scope and gets
* destroyed, it automatically decreases the turn-on counter by one. If
* the counter drops to zero, multi-error mode for the current thread is
* turned off and the thread switches back to single-error mode where every
* next error or warning object overwrites the previous one.
*
* Note that the caller of a COM method uses a non-S_OK result code to
* decide if the method has returned an error (negative codes) or a warning
* (positive non-zero codes) and will query extended error info only in
* these two cases. However, since multi-error mode implies that the method
* doesn't return control return to the caller immediately after the first
* error or warning but continues its execution, the functionality provided
* by the base com::FWResult class becomes very useful because it allows to
* preserve the error or the warning result code even if it is later assigned
* a S_OK value multiple times. See com::FWResult for details.
*
* Here is the typical usage pattern:
* <code>
HRESULT Bar::method()
{
// assume multi-errors are turned off here...
if (something)
{
// Turn on multi-error mode and make sure severity is preserved
MultiResult rc = foo->method1();
// return on fatal error, but continue on warning or on success
if (FAILED(rc)) return rc;
rc = foo->method2();
// no matter what result, stack it and continue
// ...
// return the last worst result code (it will be preserved even if
// foo->method2() returns S_OK.
return rc;
}
// multi-errors are turned off here again...
return S_OK;
}
* </code>
*
*
* @note This class is intended to be instantiated on the stack, therefore
* You cannot create them using new(). Although it is possible to copy
* instances of MultiResult or return them by value, please never do
* that as it is breaks the class semantics (and will assert).
*/
{
/**
* @copydoc com::FWResult::FWResult().
*/
{
/* We need this copy constructor only for GCC that wants to have
* it in case of expressions like |MultiResult rc = E_FAIL;|. But
* we assert since the optimizer should actually avoid the
* temporary and call the other constructor directly instead. */
AssertFailed();
init();
}
~MultiResult();
{
return *this;
}
{
/* We need this copy constructor only for GCC that wants to have
* it in case of expressions like |MultiResult rc = E_FAIL;|. But
* we assert since the optimizer should actually avoid the
* temporary and call the other constructor directly instead. */
AssertFailed();
return *this;
}
void init();
};
const wchar_t *aComponent,
bool aLogIt = true)
{
false /* aWarning */, aLogIt);
}
const wchar_t *aComponent,
{
true /* aWarning */, true /* aLogIt */);
}
const wchar_t *aComponent,
{
false /* aWarning */, aLogIt);
}
const wchar_t *aComponent,
{
true /* aWarning */, true /* aLogIt */);
}
};
/**
* This template implements ISupportErrorInfo for the given component class
* and provides the #setError() method to conveniently set the error information
* from within interface methods' implementations.
*
* On Windows, the template argument must define a COM interface map using
* BEGIN_COM_MAP / END_COM_MAP macros and this map must contain a
* COM_INTERFACE_ENTRY(ISupportErrorInfo) definition. All interface entries
* that follow it will be considered to support IErrorInfo, i.e. the
* InterfaceSupportsErrorInfo() implementation will return S_OK for the
* corresponding IID.
*
* On all platforms, the template argument must also define the following
* method: |public static const wchar_t *C::getComponentName()|. See
* #setError(HRESULT, const char *, ...) for a description on how it is
* used.
*
* @param C
* component class that implements one or more COM interfaces
* @param I
* default interface for the component. This interface's IID is used
* by the shortest form of #setError, for convenience.
*/
/// @todo switch to com::SupportErrorInfo* and remove
#if !defined (VBOX_WITH_XPCOM)
#else
#endif
{
#if !defined (VBOX_WITH_XPCOM)
{
if (!pEntries)
return S_FALSE;
{
if (!bISupportErrorInfoFound)
{
// skip the com map entries until ISupportErrorInfo is found
}
else
{
// look for the requested interface in the rest of the com map
}
pEntries++;
}
}
#endif // !defined (VBOX_WITH_XPCOM)
/**
* Sets the error information for the current thread.
* This information can be retrieved by a caller of an interface method
* using IErrorInfo on Windows or nsIException on Linux, or the cross-platform
* IVirtualBoxErrorInfo interface that provides extended error info (only
* for components from the VirtualBox COM library). Alternatively, the
* platform-independent class com::ErrorInfo (defined in VBox[XP]COM.lib)
* can be used to retrieve error info in a convenient way.
*
* It is assumed that the interface method that uses this function returns
* an unsuccessful result code to the caller (otherwise, there is no reason
* for the caller to try to retrieve error info after method invocation).
*
* Here is a table of correspondence between this method's arguments
*
* argument IErrorInfo nsIException IVirtualBoxErrorInfo
* ----------------------------------------------------------------
* resultCode -- result resultCode
* iid GetGUID -- interfaceID
* component GetSource -- component
* text GetDescription message text
*
* This method is rarely needs to be used though. There are more convenient
* overloaded versions, that automatically substitute some arguments
* taking their values from the template parameters. See
* #setError(HRESULT, const char *, ...) for an example.
*
* @param aResultCode result (error) code, must not be S_OK
* @param aIID IID of the interface that defines the error
* @param aComponent name of the component that generates the error
* @param aText error message (must not be null), an RTStrPrintf-like
* format string in UTF-8 encoding
* @param ... list of arguments for the format string
*
* @return
* the error argument, for convenience, If an error occurs while
* creating error info itself, that error is returned instead of the
* error argument.
*/
const wchar_t *aComponent,
const char *aText, ...)
{
aIID,
args,
true /* aLogIt */);
return rc;
}
/**
* This method is the same as #setError() except that it makes sure @a
* aResultCode doesn't have the error severity bit (31) set when passed
* down to the created IVirtualBoxErrorInfo object.
*
* The error severity bit is always cleared by this call, thereof you can
* use ordinary E_XXX result code constants, for convenience. However, this
* behavior may be non-standard on some COM platforms.
*/
const wchar_t *aComponent,
const char *aText, ...)
{
return rc;
}
/**
* Sets the error information for the current thread.
* A convenience method that automatically sets the default interface
* ID (taken from the I template argument) and the component name
* (a value of C::getComponentName()).
*
* See #setError(HRESULT, const GUID &, const wchar_t *, const char *text, ...)
* for details.
*
* This method is the most common (and convenient) way to set error
* information from within interface methods. A typical pattern of usage
* is looks like this:
*
* <code>
* return setError(E_FAIL, "Terrible Error");
* </code>
* or
* <code>
* HRESULT rc = setError(E_FAIL, "Terrible Error");
* ...
* return rc;
* </code>
*/
{
COM_IIDOF(I),
C::getComponentName(),
args,
true /* aLogIt */);
return rc;
}
/**
* This method is the same as #setError() except that it makes sure @a
* aResultCode doesn't have the error severity bit (31) set when passed
* down to the created IVirtualBoxErrorInfo object.
*
* The error severity bit is always cleared by this call, thereof you can
* use ordinary E_XXX result code constants, for convenience. However, this
* behavior may be non-standard on some COM platforms.
*/
{
COM_IIDOF(I),
C::getComponentName(),
args);
return rc;
}
/**
* Sets the error information for the current thread, va_list variant.
* A convenience method that automatically sets the default interface
* ID (taken from the I template argument) and the component name
* (a value of C::getComponentName()).
*
* See #setError(HRESULT, const GUID &, const wchar_t *, const char *text, ...)
* and #setError(HRESULT, const char *, ...) for details.
*/
{
COM_IIDOF(I),
C::getComponentName(),
true /* aLogIt */);
return rc;
}
/**
* This method is the same as #setErrorV() except that it makes sure @a
* aResultCode doesn't have the error severity bit (31) set when passed
* down to the created IVirtualBoxErrorInfo object.
*
* The error severity bit is always cleared by this call, thereof you can
* use ordinary E_XXX result code constants, for convenience. However, this
* behavior may be non-standard on some COM platforms.
*/
{
COM_IIDOF(I),
C::getComponentName(),
aArgs);
return rc;
}
/**
* Sets the error information for the current thread.
* A convenience method that automatically sets the component name
* (a value of C::getComponentName()), but allows to specify the interface
* id manually.
*
* See #setError(HRESULT, const GUID &, const wchar_t *, const char *text, ...)
* for details.
*/
const char *aText, ...)
{
aIID,
C::getComponentName(),
args,
true /* aLogIt */);
return rc;
}
/**
* This method is the same as #setError() except that it makes sure @a
* aResultCode doesn't have the error severity bit (31) set when passed
* down to the created IVirtualBoxErrorInfo object.
*
* The error severity bit is always cleared by this call, thereof you can
* use ordinary E_XXX result code constants, for convenience. However, this
* behavior may be non-standard on some COM platforms.
*/
const char *aText, ...)
{
aIID,
C::getComponentName(),
args);
return rc;
}
/**
* Sets the error information for the current thread but doesn't put
* anything in the release log. This is very useful for avoiding
* harmless error from causing confusion.
*
* It is otherwise identical to #setError(HRESULT, const char *text, ...).
*/
{
COM_IIDOF(I),
C::getComponentName(),
args,
false /* aLogIt */);
return rc;
}
};
/**
* Base class to track VirtualBoxBaseNEXT chlidren of the component.
*
* This class is a preferrable VirtualBoxBase replacement for components that
* operate with collections of child components. It gives two useful
* possibilities:
*
* <ol><li>
* Given an IUnknown instance, it's possible to quickly determine
* whether this instance represents a child object that belongs to the
* given component, and if so, get a valid VirtualBoxBase pointer to the
* child object. The returned pointer can be then safely casted to the
* actual class of the child object (to get access to its "internal"
* non-interface methods) provided that no other child components implement
* the same original COM interface IUnknown is queried from.
* </li><li>
* When the parent object uninitializes itself, it can easily unintialize
* all its VirtualBoxBase derived children (using their
* VirtualBoxBase::uninit() implementations). This is done simply by
* calling the #uninitDependentChildren() method.
* </li></ol>
*
* In order to let the above work, the following must be done:
* <ol><li>
* When a child object is initialized, it calls #addDependentChild() of
* its parent to register itself within the list of dependent children.
* </li><li>
* When the child object it is uninitialized, it calls
* #removeDependentChild() to unregister itself.
* </li></ol>
*
* Note that if the parent object does not call #uninitDependentChildren() when
* it gets uninitialized, it must call uninit() methods of individual children
* manually to disconnect them; a failure to do so will cause crashes in these
* methods when children get destroyed. The same applies to children not calling
* #removeDependentChild() when getting destroyed.
*
* Note that children added by #addDependentChild() are <b>weakly</b> referenced
* (i.e. AddRef() is not called), so when a child object is deleted externally
* (because it's reference count goes to zero), it will automatically remove
* itself from the map of dependent children provided that it follows the rules
* described here.
*
* Access to the child list is serialized using the #childrenLock() lock handle
* (which defaults to the general object lock handle (see
* this class so be aware of the need to preserve the {parent, child} lock order
* when calling these methods.
*
* Read individual method descriptions to get further information.
*
* @todo This is a VirtualBoxBaseWithChildren equivalent that uses the
* VirtualBoxBaseNEXT implementation. Will completely supersede
* VirtualBoxBaseWithChildren after the old VirtualBoxBase implementation
* has gone.
*/
{
{}
{}
/**
* children. It is guaranteed that no any other lock is requested in methods
* of this class while holding this lock.
*
* @warning By default, this simply returns the general object's lock handle
* (see VirtualBoxBase::lockHandle()) which is sufficient for most
* cases.
*/
/**
* Adds the given child to the list of dependent children.
*
* Usually gets called from the child's init() method.
*
* @note @a aChild (unless it is in InInit state) must be protected by
* VirtualBoxBase::AutoCaller to make sure it is not uninitialized on
* another thread during this method's call.
*
* @note When #childrenLock() is not overloaded (returns the general object
* lock) and this method is called from under the child's read or
* write lock, make sure the {parent, child} locking order is
* preserved by locking the callee (this object) for writing before
* the child's lock.
*
* @param aChild Child object to add (must inherit VirtualBoxBase AND
* implement some interface).
*
* @note Locks #childrenLock() for writing.
*/
void addDependentChild(C *aChild)
{
}
/**
* Equivalent to template <class C> void addDependentChild (C *aChild)
* but takes a ComObjPtr<C> argument.
*/
{
}
/**
* Removes the given child from the list of dependent children.
*
* Usually gets called from the child's uninit() method.
*
* Keep in mind that the called (parent) object may be no longer available
* (i.e. may be deleted deleted) after this method returns, so you must not
* call any other parent's methods after that!
*
* @note Locks #childrenLock() for writing.
*
* @note @a aChild (unless it is in InUninit state) must be protected by
* VirtualBoxBase::AutoCaller to make sure it is not uninitialized on
* another thread during this method's call.
*
* @note When #childrenLock() is not overloaded (returns the general object
* lock) and this method is called from under the child's read or
* write lock, make sure the {parent, child} locking order is
* preserved by locking the callee (this object) for writing before
* the child's lock. This is irrelevant when the method is called from
* under this object's VirtualBoxBaseProto::AutoUninitSpan (i.e. in
* InUninit state) since in this case no locking is done.
*
* @param aChild Child object to remove.
*
* @note Locks #childrenLock() for writing.
*/
void removeDependentChild(C *aChild)
{
}
/**
* Equivalent to template <class C> void removeDependentChild (C *aChild)
* but takes a ComObjPtr<C> argument.
*/
{
}
void uninitDependentChildren();
};
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @todo (dmik) remove after we switch to VirtualBoxBaseNEXT completely
/**
* Simple template that manages data structure allocation/deallocation
* and supports data pointer sharing (the instance that shares the pointer is
* not responsible for memory deallocation as opposed to the instance that
* owns it).
*/
{
if (mData) {
if (!mIsShared)
mIsShared = false;
}
}
void attach(D *d) {
AssertMsg(d, ("new data must not be NULL"));
if (d && mData != d) {
mData = d;
mIsShared = false;
}
}
("new data must not be shared")
);
d.mIsShared = true;
}
}
void share(D *d) {
AssertMsg(d, ("new data must not be NULL"));
if (mData != d) {
mData = d;
mIsShared = true;
}
}
void attachCopy(const D *d) {
AssertMsg(d, ("data to copy must not be NULL"));
if (d)
}
void attachCopy(const Shareable &d) {
attachCopy(d.mData);
}
D *d = mData;
mIsShared = false;
return d;
}
D *data() const {
return mData;
}
D *operator->() const {
return mData;
}
D *mData;
bool mIsShared;
};
/// @todo (dmik) remove after we switch to VirtualBoxBaseNEXT completely
/**
* Simple template that enhances Shareable<> and supports data
* structure).
*/
{
void free()
{
rollback();
}
D *detach()
{
rollback();
}
void share(const Backupable &d)
{
if (!d.isBackedUp())
}
/**
* Stores the current data pointer in the backup area, allocates new data
* using the copy constructor on current data and makes new data active.
*/
void backup()
{
{
}
}
/**
* Deletes new data created by #backup() and restores previous data pointer
* stored in the backup area, making it active again.
*/
void rollback()
{
{
mBackupData = NULL;
}
}
/**
* Commits current changes by deleting backed up data and clearing up the
* backup area. The new data pointer created by #backup() remains active
* and becomes the only managed pointer.
*
* This method is much faster than #commitCopy() (just a single pointer
* assignment operation), but makes the previous data pointer invalid
* (because it is freed). For this reason, this method must not be
* used if it's possible that data managed by this instance is shared with
* some other Shareable instance. See #commitCopy().
*/
void commit()
{
{
mBackupData = NULL;
}
}
/**
* Commits current changes by assigning new data to the previous data
* pointer stored in the backup area using the assignment operator.
* New data is deleted, the backup area is cleared and the previous data
* pointer becomes active and the only managed pointer.
*
* This method is slower than #commit(), but it keeps the previous data
* pointer valid (i.e. new data is copied to the same memory location).
* For that reason it's safe to use this method on instances that share
* managed data with other Shareable instances.
*/
void commitCopy()
{
{
mBackupData = NULL;
}
}
void assignCopy(const D *pData)
{
{
if (!mBackupData)
{
}
else
}
}
void assignCopy(const Backupable &d)
{
assignCopy(d.mData);
}
bool isBackedUp() const
{
return mBackupData != NULL;
}
D *backedUpData() const
{
return mBackupData;
}
D *mBackupData;
};
#endif // !____H_VIRTUALBOXBASEIMPL