SupportErrorInfo.h revision e64031e20c39650a7bc902a3e1aba613b9415dee
/* $Id$ */
/** @file
* MS COM / XPCOM Abstraction Layer:
* SupportErrorInfo* class family declarations
*/
/*
* Copyright (C) 2008-2009 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.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#ifndef ___VBox_com_SupportErrorInfo_h
#define ___VBox_com_SupportErrorInfo_h
#include <stdarg.h>
#if !defined (VBOX_WITH_XPCOM)
#else
#endif
{
/**
* The MultiResult class is a com::FWResult enhancement that also acts as a
* switch to turn on multi-error mode for SupportErrorInfo::setError() and
* SupportErrorInfo::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
CheckComRCReturnRC (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 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();
}
~MultiResult() { decCounter(); }
{
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;
}
static void incCounter();
static void decCounter();
};
/**
* The MultiResultRef class is equivalent to MultiResult except that it takes
* a reference to the existing HRESULT variable instead of maintaining its own
* one.
*/
{
{
/* Copied from FWResult */
return *this;
}
};
/**
* The SupportErrorInfoBase template class provides basic error info support.
*
* Basic error info support includes a group of setError() methods to set
* extended error information on the current thread. This support does not
* include all necessary implementation details (for example, implementation of
* the ISupportErrorInfo interface on MS COM) to make the error info support
* fully functional in a target component. These details are provided by the
* SupportErrorInfoDerived class.
*
* This way, this class is intended to be directly inherited only by
* intermediate component base classes that will be then inherited by final
* component classes through the SupportErrorInfoDerived template class. In
* all other cases, the SupportErrorInfoImpl class should be used as a base for
* final component classes instead.
*/
{
const char *aComponent,
bool aWarning,
/**
* Returns an interface ID that is to be used in short setError() variants
* to specify the interface that has defined the error. Must be implemented
* in subclasses.
*/
/**
* Returns an component name (in UTF8) that is to be used in short
* setError() variants to specify the interface that has defined the error.
* Must be implemented in subclasses.
*/
virtual const char *componentName() const = 0;
/**
* Same as #setError (HRESULT, const GUID &, const char *, const char *) but
* interprets the @a aText argument as a RTPrintf-like format string and the
* @a aArgs argument as an argument list for this format string.
*/
const char *aComponent, const char *aText,
{
false /* aWarning */);
}
/**
* Same as #setWarning (HRESULT, const GUID &, const char *, const char *)
* but interprets the @a aText argument as a RTPrintf-like format string and
* the @a aArgs argument as an argument list for this format string.
*/
const char *aComponent, const char *aText,
{
true /* aWarning */);
}
/**
* Same as #setError (HRESULT, const GUID &, const char *, const char *) but
* interprets the @a aText argument as a RTPrintf-like format string and
* takes a variable list of arguments for this format string.
*/
const char *aComponent,
const char *aText,
...);
/**
* Same as #setWarning (HRESULT, const GUID &, const char *, const char *)
* but interprets the @a aText argument as a RTPrintf-like format string and
* takes a variable list of arguments for this format string.
*/
const char *aComponent, const char *aText,
...);
/**
* Sets the given error info object on the current thread.
*
* Note that In multi-error mode (see MultiResult), the existing error info
* object (if any) will be preserved by attaching it to the tail of the
* error chain of the given aInfo object.
*
* @param aInfo Error info object to set (must not be NULL).
*/
{
}
/**
* Same as #setError (HRESULT, const GUID &, const char *, const char *,
* ...) but uses the return value of the mainInterfaceID() method as an @a
* aIID argument and the return value of the componentName() method as a @a
* aComponent argument.
*
* This method is the most common (and convenient) way to set error
* information from within a component method. The typical usage pattern is:
* <code>
* return setError (E_FAIL, "Terrible Error");
* </code>
* or
* <code>
* HRESULT rc = setError (E_FAIL, "Terrible Error");
* ...
* return rc;
* </code>
*/
/**
* Same as #setWarning (HRESULT, const GUID &, const char *, const char *,
* ...) but uses the return value of the mainInterfaceID() method as an @a
* aIID argument and the return value of the componentName() method as a @a
* aComponent argument.
*
* This method is the most common (and convenient) way to set warning
* information from within a component method. The typical usage pattern is:
* <code>
* return setWarning (E_FAIL, "Dangerous warning");
* </code>
* or
* <code>
* HRESULT rc = setWarning (E_FAIL, "Dangerous warning");
* ...
* return rc;
* </code>
*/
/**
* Same as #setError (HRESULT, const char *, ...) but takes a va_list
* argument instead of a variable argument list.
*/
{
}
/**
* Same as #setWarning (HRESULT, const char *, ...) but takes a va_list
* argument instead of a variable argument list.
*/
{
}
/**
* Same as #setError (HRESULT, const char *, ...) but allows to specify the
* interface ID manually.
*/
const char *aText, ...);
/**
* Same as #setWarning (HRESULT, const char *, ...) but allows to specify
* the interface ID manually.
*/
const char *aText, ...);
};
////////////////////////////////////////////////////////////////////////////////
/**
* The SupportErrorInfoDerived template class implements the remaining parts
* of error info support in addition to SupportErrorInfoBase.
*
* These parts include the ISupportErrorInfo implementation on the MS COM
* platform and implementations of mandatory SupportErrorInfoBase virtual
* methods.
*
* On MS COM, the @a C template argument must declare 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 IIDs.
*
* On all platforms, the @a C template argument must be a subclass of
* SupportErrorInfoBase and also define the following method: <tt>public static
* const char *ComponentName()</tt> that will be used as a value returned by the
* SupportErrorInfoBase::componentName() implementation.
*
* If SupportErrorInfoBase is used as a base for an intermediate component base
* class FooBase then the final component FooFinal that inherits FooBase should
* use this template class as follows:
* <code>
* class FooFinal : public SupportErrorInfoDerived <FooBase, FooFinal, IFoo>
* {
* ...
* };
* </code>
*
* Note that if you don not use intermediate component base classes, you should
* use the SupportErrorInfoImpl class as a base for your component instead.
*
* @param B Intermediate component base derived from SupportErrorInfoBase.
* @param C Component class that implements one or more COM interfaces.
* @param I Default interface for the component (for short #setError()
* versions).
*/
#if !defined (VBOX_WITH_XPCOM)
#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) */
};
////////////////////////////////////////////////////////////////////////////////
/**
* The SupportErrorInfoImpl template class provides complete error info support
* for COM component classes.
*
* Complete error info support includes what both SupportErrorInfoBase and
* SupportErrorInfoDerived provide, e.g. a variety of setError() methods to
* set extended error information from within a component's method
* implementation and all necessary additional interface implementations (see
* descriptions of these classes for details).
*
* To add error info support to a Foo component that implements a IFoo
* interface, use the following pattern:
* <code>
* class Foo : public SupportErrorInfoImpl <Foo, IFoo>
* {
* public:
*
* ...
*
* static const char *ComponentName() const { return "Foo"; }
* };
* </code>
*
* Note that your component class (the @a C template argument) must provide the
* ComponentName() implementation as shown above.
*
* @param C Component class that implements one or more COM interfaces.
* @param I Default interface for the component (for short #setError()
* versions).
*/
{
};
} /* namespace com */
#endif /* ___VBox_com_SupportErrorInfo_h */