VirtualBoxBase.h revision 5e3a885d489b1c99d79d576813f8f321bae46927
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * VirtualBox COM base classes definition
804197ca1d56719343cd21af782ddc2c695a6760vboxsync * Copyright (C) 2006-2009 Sun Microsystems, Inc.
804197ca1d56719343cd21af782ddc2c695a6760vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
804197ca1d56719343cd21af782ddc2c695a6760vboxsync * available from http://www.virtualbox.org. This file is free software;
804197ca1d56719343cd21af782ddc2c695a6760vboxsync * you can redistribute it and/or modify it under the terms of the GNU
804197ca1d56719343cd21af782ddc2c695a6760vboxsync * General Public License (GPL) as published by the Free Software
804197ca1d56719343cd21af782ddc2c695a6760vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
804197ca1d56719343cd21af782ddc2c695a6760vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
804197ca1d56719343cd21af782ddc2c695a6760vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * additional information or have any questions.
6988e736149e8800875f9fbb001a6018926d6562vboxsync// avoid including VBox/settings.h and VBox/xml.h;
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync// only declare the classes
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/* use a special version of the singleton class factory,
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * see KB811591 in msdn for more info. */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync#define DECLARE_CLASSFACTORY_SINGLETON(obj) DECLARE_CLASSFACTORY_EX(CMyComClassFactorySingleton<obj>)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsyncclass CMyComClassFactorySingleton : public CComClassFactory
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync // IClassFactory
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync STDMETHOD(CreateInstance)(LPUNKNOWN pUnkOuter, REFIID riid, void** ppvObj)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync // Aggregation is not supported in singleton objects.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync // Fix: The following If statement was moved inside the __try statement.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync // Did another thread arrive here first?
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync // lock the module to indicate activity
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync // (necessary for the monitor shutdown thread to correctly
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync // terminate the module in case when CreateInstance() fails)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync m_hrCreate = CComObjectCached<T>::CreateInstance(&p);
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync m_hrCreate = p->QueryInterface(IID_IUnknown, (void**)&m_spObj);
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync#endif /* !defined (VBOX_WITH_XPCOM) */
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync////////////////////////////////////////////////////////////////////////////////
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * Special version of the Assert macro to be used within VirtualBoxBase
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * In the debug build, this macro is equivalent to Assert.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * In the release build, this macro uses |setError (E_FAIL, ...)| to set the
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * error info from the asserted expression.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @see VirtualBoxSupportErrorInfoImpl::setError
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param expr Expression which should be true.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync#if defined (DEBUG)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync setError (E_FAIL, "Assertion failed: [%s] at '%s' (%d) in %s.\n" \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync "Please contact the product vendor!", \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Special version of the AssertMsg macro to be used within VirtualBoxBase
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * See ComAssert for more info.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param expr Expression which should be true.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param a printf argument list (in parenthesis).
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync#if defined (DEBUG)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync setError (E_FAIL, "Assertion failed: [%s] at '%s' (%d) in %s.\n" \
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync "Please contact the product vendor!", \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync #expr, __FILE__, __LINE__, __PRETTY_FUNCTION__, Utf8StrFmt a .raw()); \
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Special version of the AssertRC macro to be used within VirtualBoxBase
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * See ComAssert for more info.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param vrc VBox status code.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync#if defined (DEBUG)
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync#define ComAssertRC(vrc) ComAssertMsgRC (vrc, ("%Rra", vrc))
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Special version of the AssertMsgRC macro to be used within VirtualBoxBase
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * See ComAssert for more info.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param vrc VBox status code.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param msg printf argument list (in parenthesis).
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync#if defined (DEBUG)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync#define ComAssertMsgRC(vrc, msg) AssertMsgRC (vrc, msg)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync#define ComAssertMsgRC(vrc, msg) ComAssertMsg (RT_SUCCESS (vrc), msg)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Special version of the AssertFailed macro to be used within VirtualBoxBase
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * See ComAssert for more info.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync#if defined (DEBUG)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync setError (E_FAIL, "Assertion failed at '%s' (%d) in %s.\n" \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync "Please contact the product vendor!", \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Special version of the AssertMsgFailed macro to be used within VirtualBoxBase
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * See ComAssert for more info.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param a printf argument list (in parenthesis).
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync#if defined (DEBUG)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync setError (E_FAIL, "Assertion failed at '%s' (%d) in %s.\n" \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync "Please contact the product vendor!", \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync __FILE__, __LINE__, __PRETTY_FUNCTION__, Utf8StrFmt a .raw()); \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Special version of the ComAssertMsgFailed macro that additionally takes
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * line number, file and function arguments to inject an assertion position
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * that differs from the position where this macro is instantiated.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param a printf argument list (in parenthesis).
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param file, line, func Line number (int), file and function (const char *).
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync#if defined (DEBUG)
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync#define ComAssertMsgFailedPos(a, file, line, func) \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync#define ComAssertMsgFailedPos(a, file, line, func) \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync "Assertion failed at '%s' (%d) in %s.\n" \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync "Please contact the product vendor!", \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync } while (0)
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * Special version of the AssertComRC macro to be used within VirtualBoxBase
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * subclasses that also inherit the VirtualBoxSupportErrorInfoImpl template.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * See ComAssert for more info.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param rc COM result code
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync#if defined (DEBUG)
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync#define ComAssertComRC(rc) ComAssertMsg (SUCCEEDED (rc), ("COM RC = %Rhrc (0x%08X)", (rc), (rc)))
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync/** Special version of ComAssert that returns ret if expr fails */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync do { ComAssert (expr); if (!(expr)) return (ret); } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertMsg that returns ret if expr fails */
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync do { ComAssertMsg (expr, a); if (!(expr)) return (ret); } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertRC that returns ret if vrc does not succeed */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync do { ComAssertRC (vrc); if (!RT_SUCCESS (vrc)) return (ret); } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertMsgRC that returns ret if vrc does not succeed */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync do { ComAssertMsgRC (vrc, msg); if (!RT_SUCCESS (vrc)) return (ret); } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertFailed that returns ret */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertMsgFailed that returns ret */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync do { ComAssertMsgFailed (msg); return (ret); } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertComRC that returns ret if rc does not succeed */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync do { ComAssertComRC (rc); if (!SUCCEEDED (rc)) return (ret); } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertComRC that returns rc if rc does not succeed */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync do { ComAssertComRC (rc); if (!SUCCEEDED (rc)) return (rc); } while (0)
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync/** Special version of ComAssert that evaluates eval and breaks if expr fails */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssert (expr); if (!(expr)) { eval; break; } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertMsg that evaluates eval and breaks if expr fails */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertMsg (expr, a); if (!(expr)) { eval; break; } } else do {} while (0)
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync/** Special version of ComAssertRC that evaluates eval and breaks if vrc does not succeed */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertRC (vrc); if (!RT_SUCCESS (vrc)) { eval; break; } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertMsgRC that evaluates eval and breaks if vrc does not succeed */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertMsgRC (vrc, msg); if (!RT_SUCCESS (vrc)) { eval; break; } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertFailed that evaluates eval and breaks */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertFailed(); { eval; break; } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertMsgFailed that evaluates eval and breaks */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertMsgFailed (msg); { eval; break; } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertComRC that evaluates eval and breaks if rc does not succeed */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertComRC (rc); if (!SUCCEEDED (rc)) { eval; break; } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertComRC that just breaks if rc does not succeed */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertComRC (rc); if (!SUCCEEDED (rc)) { break; } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssert that evaluates eval and throws it if expr fails */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssert (expr); if (!(expr)) { throw (eval); } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertMsg that evaluates eval and throws it if expr fails */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertMsg (expr, a); if (!(expr)) { throw (eval); } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertRC that evaluates eval and throws it if vrc does not succeed */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertRC (vrc); if (!RT_SUCCESS (vrc)) { throw (eval); } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertMsgRC that evaluates eval and throws it if vrc does not succeed */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertMsgRC (vrc, msg); if (!RT_SUCCESS (vrc)) { throw (eval); } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertFailed that evaluates eval and throws it */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertFailed(); { throw (eval); } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertMsgFailed that evaluates eval and throws it */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertMsgFailed (msg); { throw (eval); } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertComRC that evaluates eval and throws it if rc does not succeed */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertComRC (rc); if (!SUCCEEDED (rc)) { throw (eval); } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/** Special version of ComAssertComRC that just throws rc if rc does not succeed */
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync if (1) { ComAssertComRC (rc); if (!SUCCEEDED (rc)) { throw rc; } } else do {} while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync////////////////////////////////////////////////////////////////////////////////
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Checks that the pointer argument is not NULL and returns E_INVALIDARG +
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * extended error info on failure.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param arg Input pointer-type argument (strings, interface pointers...)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync return setError (E_INVALIDARG, tr ("Argument %s is NULL"), #arg); \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Checks that safe array argument is not NULL and returns E_INVALIDARG +
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * extended error info on failure.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param arg Input safe array argument (strings, interface pointers...)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync return setError (E_INVALIDARG, tr ("Argument %s is NULL"), #arg); \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync } while (0)
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * Checks that the string argument is not a NULL or empty string and returns
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * E_INVALIDARG + extended error info on failure.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param arg Input string argument (BSTR etc.).
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Checks that the given expression (that must involve the argument) is true and
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * returns E_INVALIDARG + extended error info on failure.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param arg Argument.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param expr Expression to evaluate.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync tr ("Argument %s is invalid (must be %s)"), #arg, #expr); \
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Checks that the given expression (that must involve the argument) is true and
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * returns E_INVALIDARG + extended error info on failure. The error message must
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * be customized.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param arg Argument.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param expr Expression to evaluate.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param msg Parenthesized printf-like expression (must start with a verb,
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * like "must be one of...", "is not within...").
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync return setError (E_INVALIDARG, tr ("Argument %s %s"), \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Checks that the given pointer to an output argument is valid and returns
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * E_POINTER + extended error info otherwise.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param arg Pointer argument.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync tr ("Output argument %s points to invalid memory location (%p)"), \
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Checks that the given pointer to an output safe array argument is valid and
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * returns E_POINTER + extended error info otherwise.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param arg Safe array argument.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync tr ("Output argument %s points to invalid memory location (%p)"), \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Sets the extended error info and returns E_NOTIMPL.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync return setError (E_NOTIMPL, tr ("Method %s is not implemented"), __FUNCTION__); \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync////////////////////////////////////////////////////////////////////////////////
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync/// @todo (dmik) remove after we switch to VirtualBoxBaseNEXT completely
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Checks whether this object is ready or not. Objects are typically ready
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * after they are successfully created by their parent objects and become
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * not ready when the respective parent itself becomes not ready or gets
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * destroyed while a reference to the child is still held by the caller
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * (which prevents it from destruction).
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * When this object is not ready, the macro sets error info and returns
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * E_ACCESSDENIED (the translatable error message is defined in null context).
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Otherwise, the macro does nothing.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * This macro <b>must</b> be used at the beginning of all interface methods
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * (right after entering the class lock) in classes derived from both
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * VirtualBoxBase and VirtualBoxSupportErrorInfoImpl.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync return setError (E_ACCESSDENIED, tr ("The object is not ready")); \
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync } while (0)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Declares an empty constructor and destructor for the given class.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * This is useful to prevent the compiler from generating the default
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * ctor and dtor, which in turn allows to use forward class statements
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * (instead of including their header files) when declaring data members of
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * non-fundamental types with constructors (which are always called implicitly
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * by constructors and by the destructor of the class).
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * This macro is to be placed within (the public section of) the class
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * declaration. Its counterpart, DEFINE_EMPTY_CTOR_DTOR, must be placed
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * somewhere in one of the translation units (usually .cpp source files).
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * @param cls class to declare a ctor and dtor for
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Defines an empty constructor and destructor for the given class.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * See DECLARE_EMPTY_CTOR_DTOR for more info.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync////////////////////////////////////////////////////////////////////////////////
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * A wrapper around the container that owns pointers it stores.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Ownership is recognized only when destructing the container!
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Pointers are not deleted when erased using erase() etc.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * @param container
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * class that meets Container requirements (for example, an instance of
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * std::list<>, std::vector<> etc.). The given class must store
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * pointers (for example, std::list <MyType *>).
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync for (typename container::iterator it = container::begin();
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync////////////////////////////////////////////////////////////////////////////////
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Abstract base class for all component classes implementing COM
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * interfaces of the VirtualBox COM library.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Declares functionality that should be available in all components.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Note that this class is always subclassed using the virtual keyword so
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * that only one instance of its VTBL and data is present in each derived class
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * even in case if VirtualBoxBaseProto appears more than once among base classes
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * of the particular component as a result of multiple inheritance.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * This makes it possible to have intermediate base classes used by several
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * components that implement some common interface functionality but still let
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * the final component classes choose what VirtualBoxBase variant it wants to
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Among the basic functionality implemented by this class is the primary object
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * state that indicates if the object is ready to serve the calls, and if not,
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * what stage it is currently at. Here is the primary state diagram:
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * +-------------------------------------------------------+
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * | (InitFailed) -----------------------+ |
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * [*] ---> NotReady ----> (InInit) -----> Ready -----> (InUninit) ----+
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * ^ | ^ | ^
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * | v | v |
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * | Limited | (MayUninit) --> (WillUninit)
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * +-------+ +-------+
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * The object is fully operational only when its state is Ready. The Limited
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * state means that only some vital part of the object is operational, and it
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * requires some sort of reinitialization to become fully operational. The
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * NotReady state means the object is basically dead: it either was not yet
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * initialized after creation at all, or was uninitialized and is waiting to be
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * destroyed when the last reference to it is released. All other states are
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * transitional.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * The NotReady->InInit->Ready, NotReady->InInit->Limited and
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * NotReady->InInit->InitFailed transition is done by the AutoInitSpan smart
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * The Limited->InInit->Ready, Limited->InInit->Limited and
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Limited->InInit->InitFailed transition is done by the AutoReinitSpan smart
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * The Ready->InUninit->NotReady, InitFailed->InUninit->NotReady and
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * WillUninit->InUninit->NotReady transitions are done by the AutoUninitSpan
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * smart class.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * The Ready->MayUninit->Ready and Ready->MayUninit->WillUninit transitions are
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * done by the AutoMayUninitSpan smart class.
65a755c25b49d32c914e2d569fcdfb766e1ee879vboxsync * In order to maintain the primary state integrity and declared functionality
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * all subclasses must:
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * 1) Use the above Auto*Span classes to perform state transitions. See the
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * individual class descriptions for details.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * 2) All public methods of subclasses (i.e. all methods that can be called
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * directly, not only from within other methods of the subclass) must have a
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * standard prolog as described in the AutoCaller and AutoLimitedCaller
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * documentation. Alternatively, they must use addCaller()/releaseCaller()
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * directly (and therefore have both the prolog and the epilog), but this is
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * not recommended.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsyncclass ATL_NO_VTABLE VirtualBoxBaseProto : public Lockable
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync enum State { NotReady, Ready, InInit, InUninit, InitFailed, Limited,
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync // util::Lockable interface
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Unintialization method.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * Must be called by all final implementations (component classes) when the
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * last reference to the object is released, before calling the destructor.
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * This method is also automatically called by the uninit() method of this
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * object's parent if this object is a dependent child of a class derived
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * from VirtualBoxBaseWithChildren (see
ababd7e83ee3d23c5191a0d3802f10764df69e36vboxsync * VirtualBoxBaseWithChildren::addDependentChild).
if (mObj)
void release()
if (mObj)
void add()
release();
add();
* autoInitSpan.setSucceeded();
~AutoInitSpan();
* autoReinitSpan.setSucceeded();
~AutoReinitSpan();
~AutoUninitSpan();
unsigned mCallers;
unsigned mInitUninitWaiters;
#define VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT(C) \
bool aLimited = false) \
if (aState) \
return rc; \
#if !defined (VBOX_WITH_XPCOM)
mReady = false;
bool isReady()
return mReady;
const char *comment = 0);
bool mReady;
void lock();
void unlock();
bool isReady();
static const char *className()
if (!sClassName)
return sClassName;
static const char *sClassName;
#define VIRTUALBOXSUPPORTTRANSLATION_OVERRIDE(C) \
#define Q_OBJECT
AssertFailed();
init();
~MultiResult();
return *this;
AssertFailed();
return *this;
void init();
bool aLogIt = true)
#if !defined (VBOX_WITH_XPCOM)
#if !defined (VBOX_WITH_XPCOM)
if (!pEntries)
return S_FALSE;
if (!bISupportErrorInfoFound)
pEntries++;
const char *aText, ...)
return rc;
const char *aText, ...)
return rc;
return rc;
return rc;
return rc;
return rc;
return rc;
return rc;
const char *aText, ...)
return rc;
const char *aText, ...)
return rc;
return rc;
void uninitDependentChildren();
unsigned mChildrenLeft;
void uninitDependentChildren();
if (mInUninit)
if (mInUninit)
* returned by #dependentChildren() using AutoReadLock/AutoWriteLock:
void uninitDependentChildren()
mInUninit = true;
if (child)
mInUninit = false;
void removeDependentChildren()
bool mInUninit;
void uninitDependentChildren()
if (child)
void removeDependentChildren()
* Simple template that manages data structure allocation/deallocation
if (mData) {
if (!mIsShared)
mIsShared = false;
mIsShared = false;
mIsShared = true;
if (data)
D *d = mData;
mIsShared = false;
D *data() const {
return mData;
D *operator->() const {
return mData;
D *mData;
bool mIsShared;
void free()
rollback();
D *detach()
rollback();
void backup()
void rollback()
void commit()
void commitCopy()
if (!mBackupData)
bool isBackedUp() const
bool hasActualChanges() const
D *backedUpData() const
return mBackupData;
D *mBackupData;