VirtualBoxBase.h revision 8a0d412f03cbeb474ba041dfed47c53da2004f80
#
endif /* !defined(VBOX_WITH_XPCOM) *///////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// * Special version of the Assert macro to be used within VirtualBoxBase * 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 VirtualBoxBase::setError * @param expr Expression which should be true. "Assertion failed: [%s] at '%s' (%d) in %s.\nPlease contact the product vendor!", \
* Special version of the AssertFailed macro to be used within VirtualBoxBase * In the debug build, this macro is equivalent to AssertFailed. * In the release build, this macro uses |setError(E_FAIL, ...)| to set the * error info from the asserted expression. * @see VirtualBoxBase::setError "Assertion failed: at '%s' (%d) in %s.\nPlease contact the product vendor!", \
* Special version of the AssertMsg macro to be used within VirtualBoxBase * See ComAssert for more info. * @param expr Expression which should be true. * @param a printf argument list (in parenthesis). "Assertion failed: [%s] at '%s' (%d) in %s.\n%s.\nPlease contact the product vendor!", \
* Special version of the AssertRC macro to be used within VirtualBoxBase * See ComAssert for more info. * @param vrc VBox status code. * Special version of the AssertMsgRC macro to be used within VirtualBoxBase * See ComAssert for more info. * @param vrc VBox status code. * @param msg printf argument list (in parenthesis). * Special version of the AssertComRC macro to be used within VirtualBoxBase * See ComAssert for more info. * @param rc COM result code /** 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 ComAssertComRC that returns ret if rc does not succeed */ /** Special version of ComAssertComRC that returns rc if rc does not succeed */ /** Special version of ComAssert that returns ret */ /** 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 ComAssertFailed that evaluates eval and breaks */ /** 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 */ /** Special version of ComAssert 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 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 */ /** Special version of ComAssert that throws eval */ //////////////////////////////////////////////////////////////////////////////// * 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...) * Checks that the pointer argument is a valid pointer or NULL and returns * E_INVALIDARG + extended error info on failure. * @param arg Input pointer-type argument (strings, interface pointers...) * 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...) * Checks that a string input argument is valid (not NULL or obviously invalid * pointer), returning E_INVALIDARG + extended error info if invalid. * @param a_bstrIn Input string argument (IN_BSTR). * Checks that the string argument is not a NULL, a invalid pointer or an empty * string, returning E_INVALIDARG + extended error info on failure. * @param a_bstrIn Input string argument (BSTR etc.). * Converts the Guid input argument (string) to a Guid object, returns with * E_INVALIDARG and error message on failure. * @param a_GuidVar The Guid variable name. * Checks that the given expression (that must involve the argument) is true and * returns E_INVALIDARG + extended error info on failure. * @param expr Expression to evaluate. tr(
"Argument %s is invalid (must be %s)"), #
arg, #
expr); \
* 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 * @param expr Expression to evaluate. * @param msg Parenthesized printf-like expression (must start with a verb, * like "must be one of...", "is not within..."). * Checks that the given pointer to an output argument is valid and returns * E_POINTER + extended error info otherwise. * @param arg Pointer argument. tr(
"Output argument %s points to invalid memory location (%p)"), \
* 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. tr(
"Output argument %s points to invalid memory location (%p)"), \
* Sets the extended error info and returns E_NOTIMPL. * 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. * A variant of 'throw' that hits a debug breakpoint first to make * finding the actual thrower possible. * Parent class of VirtualBoxBase which enables translation support (which * Main doesn't have yet, but this provides the tr() function which will one * day provide translations). * This class sits in between Lockable and VirtualBoxBase only for the one * reason that the USBProxyService wants translation support but is not * implemented as a COM object, which VirtualBoxBase implies. * Placeholder method with which translations can one day be implemented * in Main. This gets called by the tr() function. * Translates the given text string by calling 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 //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// * VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT: * This macro must be used once in the declaration of any class derived * from VirtualBoxBase. It implements the pure virtual getClassIID() and * getComponentName() methods. If this macro is not present, instances * of a class derived from VirtualBoxBase cannot be instantiated. * @param X The class name, e.g. "Class". * @param IX The interface name which this class implements, e.g. "IClass". #
else // #ifdef VBOX_WITH_XPCOM#
endif // #ifdef VBOX_WITH_XPCOM * Abstract base class for all component classes implementing COM * interfaces of the VirtualBox COM library. * Declares functionality that should be available in all components. * 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) -----------------------+ | * [*] ---> NotReady ----> (InInit) -----> Ready -----> (InUninit) ----+ * 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 * The NotReady->InInit->Ready, NotReady->InInit->Limited and * NotReady->InInit->InitFailed transition is done by the AutoInitSpan smart * The Limited->InInit->Ready, Limited->InInit->Limited and * Limited->InInit->InitFailed transition is done by the AutoReinitSpan smart * 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 * 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 * Uninitialization method. * Must be called by all final implementations (component classes) when the * last reference to the object is released, before calling the destructor. * @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. * 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. * Pure virtual method for simple run-time type identification without * having to enable C++ RTTI. * This *must* be implemented by every subclass deriving from VirtualBoxBase; * use the VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT macro to do that most easily. * Pure virtual method for simple run-time type identification without * having to enable C++ RTTI. * This *must* be implemented by every subclass deriving from VirtualBoxBase; * use the VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT macro to do that most easily. * Virtual method which determines the locking class to be used for validating * lock order with the standard member lock handle. This method is overridden * in a number of subclasses. * 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! /** Initialize COM for a new thread. */ /** Uninitializes COM for a dying thread. */ /** Primary state of this object */ /** Thread that caused the last state change */ /** Total number of active calls to this object */ /** Posted when the number of callers drops to zero */ /** Posted when the object goes from InInit/InUninit to some other state */ /** Number of threads waiting for mInitUninitDoneSem */ /** Protects access to state related data members */ /** User-level object lock for subclasses */ * 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 * VirtualBoxTranslatable, to make lupdate happy. //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// * and supports data pointer sharing (the instance that shares the pointer is * not responsible for memory deallocation as opposed to the instance that (
"new data must not be shared")
AssertMsg(d, (
"data to copy must not be NULL"));
* Simple template that enhances Shareable<> and supports data * Stores the current data pointer in the backup area, allocates new data * using the copy constructor on current data and makes new data active. * @deprecated Use backupEx to avoid throwing wild out-of-memory exceptions. * Stores the current data pointer in the backup area, allocates new data * using the copy constructor on current data and makes new data active. * @returns S_OK, E_OUTOFMEMORY or E_FAIL (internal error). * Deletes new data created by #backup() and restores previous data pointer * stored in the backup area, making it active again. * 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(). * 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. #
endif // !____H_VIRTUALBOXBASEIMPL