Logo Search packages:      
Sourcecode: virtualbox-ose version File versions

com::MultiResult Class Reference

#include <SupportErrorInfo.h>

Inheritance diagram for com::MultiResult:

com::FWResult

List of all members.


Detailed Description

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.

This way, error/warning objects are stacked together and form a chain of 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:

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; }

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);

Definition at line 125 of file SupportErrorInfo.h.


Public Member Functions

 MultiResult (const MultiResult &aThat)
 MultiResult (HRESULT aRC=E_FAIL)
HRESULT * operator & ()
 operator HRESULT () const
MultiResultoperator= (const MultiResult &aThat)
MultiResultoperator= (HRESULT aRC)

Static Private Member Functions

static void decCounter ()
static void incCounter ()

Static Private Attributes

static RTTLS sCounter = NIL_RTTLS

Friends

class MultiResultRef
class SupportErrorInfoBase

The documentation for this class was generated from the following files:

Generated by  Doxygen 1.6.0   Back to index