← Back to branch summary

~ubuntu-branches/ubuntu/raring/virtualbox-ose/raring

« back to all changes in this revision

Viewing changes to include/VBox/com/SupportErrorInfo.h

  • Committer: Bazaar Package Importer
  • Author(s): Felix Geyer
  • Date: 2011-01-30 23:27:25 UTC
  • mfrom: (0.3.12 upstream)
  • Revision ID: james.westby@ubuntu.com-20110130232725-2ouajjd2ggdet0zd
Tags: 4.0.2-dfsg-1ubuntu1
* Merge from Debian unstable, remaining changes:
  - Add Apport hook.
    - debian/virtualbox-ose.files/source_virtualbox-ose.py
    - debian/virtualbox-ose.install
  - Drop *-source packages.
* Drop ubuntu-01-fix-build-gcc45.patch, fixed upstream.
* Drop ubuntu-02-as-needed.patch, added to the Debian package.

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/VBox/com/SupportErrorInfo.h
1
 
/* $Id: SupportErrorInfo.h $ */
2
 
 
3
 
/** @file
4
 
 * MS COM / XPCOM Abstraction Layer:
5
 
 * SupportErrorInfo* class family declarations
6
 
 */
7
 
 
8
 
/*
9
 
 * Copyright (C) 2008-2009 Oracle Corporation
10
 
 *
11
 
 * This file is part of VirtualBox Open Source Edition (OSE), as
12
 
 * available from http://www.virtualbox.org. This file is free software;
13
 
 * you can redistribute it and/or modify it under the terms of the GNU
14
 
 * General Public License (GPL) as published by the Free Software
15
 
 * Foundation, in version 2 as it comes in the "COPYING" file of the
16
 
 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
17
 
 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
18
 
 *
19
 
 * The contents of this file may alternatively be used under the terms
20
 
 * of the Common Development and Distribution License Version 1.0
21
 
 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
22
 
 * VirtualBox OSE distribution, in which case the provisions of the
23
 
 * CDDL are applicable instead of those of the GPL.
24
 
 *
25
 
 * You may elect to license modified versions of this file under the
26
 
 * terms and conditions of either the GPL or the CDDL or both.
27
 
 */
28
 
 
29
 
#ifndef ___VBox_com_SupportErrorInfo_h
30
 
#define ___VBox_com_SupportErrorInfo_h
31
 
 
32
 
#include "VBox/com/defs.h"
33
 
#include "VBox/com/string.h"
34
 
 
35
 
#include <iprt/cdefs.h>
36
 
 
37
 
#include <stdarg.h>
38
 
 
39
 
#if !defined (VBOX_WITH_XPCOM)
40
 
interface IVirtualBoxErrorInfo;
41
 
#else
42
 
class IVirtualBoxErrorInfo;
43
 
#endif
44
 
 
45
 
namespace com
46
 
{
47
 
 
48
 
/**
49
 
 * The MultiResult class is a com::FWResult enhancement that also acts as a
50
 
 * switch to turn on multi-error mode for SupportErrorInfo::setError() and
51
 
 * SupportErrorInfo::setWarning() calls.
52
 
 *
53
 
 * When an instance of this class is created, multi-error mode is turned on
54
 
 * for the current thread and the turn-on counter is increased by one. In
55
 
 * multi-error mode, a call to setError() or setWarning() does not
56
 
 * overwrite the current error or warning info object possibly set on the
57
 
 * current thread by other method calls, but instead it stores this old
58
 
 * object in the IVirtualBoxErrorInfo::next attribute of the new error
59
 
 * object being set.
60
 
 *
61
 
 * This way, error/warning objects are stacked together and form a chain of
62
 
 * errors where the most recent error is the first one retrieved by the
63
 
 * calling party, the preceding error is what the
64
 
 * IVirtualBoxErrorInfo::next attribute of the first error points to, and so
65
 
 * on, up to the first error or warning occurred which is the last in the
66
 
 * chain. See IVirtualBoxErrorInfo documentation for more info.
67
 
 *
68
 
 * When the instance of the MultiResult class goes out of scope and gets
69
 
 * destroyed, it automatically decreases the turn-on counter by one. If
70
 
 * the counter drops to zero, multi-error mode for the current thread is
71
 
 * turned off and the thread switches back to single-error mode where every
72
 
 * next error or warning object overwrites the previous one.
73
 
 *
74
 
 * Note that the caller of a COM method uses a non-S_OK result code to
75
 
 * decide if the method has returned an error (negative codes) or a warning
76
 
 * (positive non-zero codes) and will query extended error info only in
77
 
 * these two cases. However, since multi-error mode implies that the method
78
 
 * doesn't return control return to the caller immediately after the first
79
 
 * error or warning but continues its execution, the functionality provided
80
 
 * by the base com::FWResult class becomes very useful because it allows to
81
 
 * preserve the error or the warning result code even if it is later assigned
82
 
 * a S_OK value multiple times. See com::FWResult for details.
83
 
 *
84
 
 * Here is the typical usage pattern:
85
 
 *  <code>
86
 
 
87
 
    HRESULT Bar::method()
88
 
    {
89
 
        // assume multi-errors are turned off here...
90
 
 
91
 
        if (something)
92
 
        {
93
 
            // Turn on multi-error mode and make sure severity is preserved
94
 
            MultiResult rc = foo->method1();
95
 
 
96
 
            // return on fatal error, but continue on warning or on success
97
 
            CheckComRCReturnRC (rc);
98
 
 
99
 
            rc = foo->method2();
100
 
            // no matter what result, stack it and continue
101
 
 
102
 
            // ...
103
 
 
104
 
            // return the last worst result code (it will be preserved even if
105
 
            // foo->method2() returns S_OK.
106
 
            return rc;
107
 
        }
108
 
 
109
 
        // multi-errors are turned off here again...
110
 
 
111
 
        return S_OK;
112
 
    }
113
 
 
114
 
 *  </code>
115
 
 *
116
 
 * @note This class is intended to be instantiated on the stack, therefore
117
 
 *       You cannot create them using new(). Although it is possible to copy
118
 
 *       instances of MultiResult or return them by value, please never do
119
 
 *       that as it is breaks the class semantics (and will assert);
120
 
 */
121
 
class MultiResult : public FWResult
122
 
{
123
 
public:
124
 
 
125
 
    /**
126
 
     * @copydoc FWResult::FWResult().
127
 
     */
128
 
    MultiResult (HRESULT aRC = E_FAIL) : FWResult (aRC) { incCounter(); }
129
 
 
130
 
    MultiResult (const MultiResult &aThat) : FWResult (aThat)
131
 
    {
132
 
        /* We need this copy constructor only for GCC that wants to have
133
 
         * it in case of expressions like |MultiResult rc = E_FAIL;|. But
134
 
         * we assert since the optimizer should actually avoid the
135
 
         * temporary and call the other constructor directly instead. */
136
 
        AssertFailed();
137
 
    }
138
 
 
139
 
    ~MultiResult() { decCounter(); }
140
 
 
141
 
    MultiResult &operator= (HRESULT aRC)
142
 
    {
143
 
        FWResult::operator= (aRC);
144
 
        return *this;
145
 
    }
146
 
 
147
 
    MultiResult &operator= (const MultiResult & /* aThat */)
148
 
    {
149
 
        /* We need this copy constructor only for GCC that wants to have
150
 
         * it in case of expressions like |MultiResult rc = E_FAIL;|. But
151
 
         * we assert since the optimizer should actually avoid the
152
 
         * temporary and call the other constructor directly instead. */
153
 
        AssertFailed();
154
 
        return *this;
155
 
    }
156
 
 
157
 
private:
158
 
 
159
 
    DECLARE_CLS_NEW_DELETE_NOOP (MultiResult)
160
 
 
161
 
    static void incCounter();
162
 
    static void decCounter();
163
 
 
164
 
    static RTTLS sCounter;
165
 
 
166
 
    friend class SupportErrorInfoBase;
167
 
    friend class MultiResultRef;
168
 
};
169
 
 
170
 
/**
171
 
 * The MultiResultRef class is equivalent to MultiResult except that it takes
172
 
 * a reference to the existing HRESULT variable instead of maintaining its own
173
 
 * one.
174
 
 */
175
 
class MultiResultRef
176
 
{
177
 
public:
178
 
 
179
 
    MultiResultRef (HRESULT &aRC) : mRC (aRC) { MultiResult::incCounter(); }
180
 
 
181
 
    ~MultiResultRef() { MultiResult::decCounter(); }
182
 
 
183
 
    MultiResultRef &operator= (HRESULT aRC)
184
 
    {
185
 
        /* Copied from FWResult */
186
 
        if ((FAILED (aRC) && !FAILED (mRC)) ||
187
 
            (mRC == S_OK && aRC != S_OK))
188
 
            mRC = aRC;
189
 
 
190
 
        return *this;
191
 
    }
192
 
 
193
 
    operator HRESULT() const { return mRC; }
194
 
 
195
 
    HRESULT *operator&() { return &mRC; }
196
 
 
197
 
private:
198
 
 
199
 
    DECLARE_CLS_NEW_DELETE_NOOP (MultiResultRef)
200
 
 
201
 
    HRESULT &mRC;
202
 
};
203
 
 
204
 
/**
205
 
 * The SupportErrorInfoBase template class provides basic error info support.
206
 
 *
207
 
 * Basic error info support includes a group of setError() methods to set
208
 
 * extended error information on the current thread. This support does not
209
 
 * include all necessary implementation details (for example, implementation of
210
 
 * the ISupportErrorInfo interface on MS COM) to make the error info support
211
 
 * fully functional in a target component. These details are provided by the
212
 
 * SupportErrorInfoDerived class.
213
 
 *
214
 
 * This way, this class is intended to be directly inherited only by
215
 
 * intermediate component base classes that will be then inherited by final
216
 
 * component classes through the SupportErrorInfoDerived template class. In
217
 
 * all other cases, the SupportErrorInfoImpl class should be used as a base for
218
 
 * final component classes instead.
219
 
 */
220
 
class SupportErrorInfoBase
221
 
{
222
 
    static HRESULT setErrorInternal(HRESULT aResultCode,
223
 
                                    const GUID *aIID,
224
 
                                    const char *aComponent,
225
 
                                    const Utf8Str &strText,
226
 
                                    bool aWarning,
227
 
                                    IVirtualBoxErrorInfo *aInfo = NULL);
228
 
 
229
 
protected:
230
 
 
231
 
    /**
232
 
     * Returns an interface ID that is to be used in short setError() variants
233
 
     * to specify the interface that has defined the error. Must be implemented
234
 
     * in subclasses.
235
 
     */
236
 
    virtual const GUID &mainInterfaceID() const = 0;
237
 
 
238
 
    /**
239
 
     * Returns an component name (in UTF8) that is to be used in short
240
 
     * setError() variants to specify the interface that has defined the error.
241
 
     * Must be implemented in subclasses.
242
 
     */
243
 
    virtual const char *componentName() const = 0;
244
 
 
245
 
    /**
246
 
     * Same as #setError (HRESULT, const GUID &, const char *, const char *) but
247
 
     * interprets the @a aText argument as a RTPrintf-like format string and the
248
 
     * @a aArgs argument as an argument list for this format string.
249
 
     */
250
 
    static HRESULT setErrorV(HRESULT aResultCode, const GUID &aIID,
251
 
                             const char *aComponent, const char *aText,
252
 
                             va_list aArgs)
253
 
    {
254
 
        return setErrorInternal(aResultCode, &aIID, aComponent,
255
 
                                Utf8StrFmtVA(aText, aArgs),
256
 
                                false /* aWarning */);
257
 
    }
258
 
 
259
 
    /**
260
 
     * Same as #setWarning (HRESULT, const GUID &, const char *, const char *)
261
 
     * but interprets the @a aText argument as a RTPrintf-like format string and
262
 
     * the @a aArgs argument as an argument list for this format string.
263
 
     */
264
 
    static HRESULT setWarningV(HRESULT aResultCode, const GUID &aIID,
265
 
                               const char *aComponent, const char *aText,
266
 
                               va_list aArgs)
267
 
    {
268
 
        return setErrorInternal(aResultCode, &aIID,
269
 
                                aComponent,
270
 
                                Utf8StrFmtVA(aText, aArgs),
271
 
                                true /* aWarning */);
272
 
    }
273
 
 
274
 
    /**
275
 
     * Same as #setError (HRESULT, const GUID &, const char *, const char *) but
276
 
     * interprets the @a aText argument as a RTPrintf-like format string and
277
 
     * takes a variable list of arguments for this format string.
278
 
     */
279
 
    static HRESULT setError(HRESULT aResultCode,
280
 
                            const GUID &aIID,
281
 
                            const char *aComponent,
282
 
                            const char *aText,
283
 
                            ...);
284
 
 
285
 
    /**
286
 
     * Same as #setWarning (HRESULT, const GUID &, const char *, const char *)
287
 
     * but interprets the @a aText argument as a RTPrintf-like format string and
288
 
     * takes a variable list of arguments for this format string.
289
 
     */
290
 
    static HRESULT setWarning(HRESULT aResultCode, const GUID &aIID,
291
 
                              const char *aComponent, const char *aText,
292
 
                              ...);
293
 
 
294
 
    /**
295
 
     * Sets the given error info object on the current thread.
296
 
     *
297
 
     * Note that In multi-error mode (see MultiResult), the existing error info
298
 
     * object (if any) will be preserved by attaching it to the tail of the
299
 
     * error chain of the given aInfo object.
300
 
     *
301
 
     * @param aInfo     Error info object to set (must not be NULL).
302
 
     */
303
 
    static HRESULT setErrorInfo(IVirtualBoxErrorInfo *aInfo)
304
 
    {
305
 
        AssertReturn (aInfo != NULL, E_FAIL);
306
 
        return setErrorInternal(0, NULL, NULL, Utf8Str::Null, false, aInfo);
307
 
    }
308
 
 
309
 
    /**
310
 
     * Same as #setError (HRESULT, const GUID &, const char *, const char *,
311
 
     * ...) but uses the return value of the mainInterfaceID() method as an @a
312
 
     * aIID argument and the return value of the componentName() method as a @a
313
 
     * aComponent argument.
314
 
     *
315
 
     * This method is the most common (and convenient) way to set error
316
 
     * information from within a component method. The typical usage pattern is:
317
 
     * <code>
318
 
     *     return setError (E_FAIL, "Terrible Error");
319
 
     * </code>
320
 
     * or
321
 
     * <code>
322
 
     *     HRESULT rc = setError (E_FAIL, "Terrible Error");
323
 
     *     ...
324
 
     *     return rc;
325
 
     * </code>
326
 
     */
327
 
    HRESULT setError(HRESULT aResultCode, const char *aText, ...);
328
 
 
329
 
    HRESULT setError(HRESULT aResultCode, const Utf8Str &strText);
330
 
 
331
 
    /**
332
 
     * Same as #setWarning (HRESULT, const GUID &, const char *, const char *,
333
 
     * ...) but uses the return value of the mainInterfaceID() method as an @a
334
 
     * aIID argument and the return value of the componentName() method as a @a
335
 
     * aComponent argument.
336
 
     *
337
 
     * This method is the most common (and convenient) way to set warning
338
 
     * information from within a component method. The typical usage pattern is:
339
 
     * <code>
340
 
     *     return setWarning (E_FAIL, "Dangerous warning");
341
 
     * </code>
342
 
     * or
343
 
     * <code>
344
 
     *     HRESULT rc = setWarning (E_FAIL, "Dangerous warning");
345
 
     *     ...
346
 
     *     return rc;
347
 
     * </code>
348
 
     */
349
 
    HRESULT setWarning (HRESULT aResultCode, const char *aText, ...);
350
 
 
351
 
    /**
352
 
     * Same as #setError (HRESULT, const char *, ...) but takes a va_list
353
 
     * argument instead of a variable argument list.
354
 
     */
355
 
    HRESULT setErrorV (HRESULT aResultCode, const char *aText, va_list aArgs)
356
 
    {
357
 
        return setError (aResultCode, mainInterfaceID(), componentName(),
358
 
                         aText, aArgs);
359
 
    }
360
 
 
361
 
    /**
362
 
     * Same as #setWarning (HRESULT, const char *, ...) but takes a va_list
363
 
     * argument instead of a variable argument list.
364
 
     */
365
 
    HRESULT setWarningV (HRESULT aResultCode, const char *aText, va_list aArgs)
366
 
    {
367
 
        return setWarning (aResultCode, mainInterfaceID(), componentName(),
368
 
                           aText, aArgs);
369
 
    }
370
 
 
371
 
    /**
372
 
     * Same as #setError (HRESULT, const char *, ...) but allows to specify the
373
 
     * interface ID manually.
374
 
     */
375
 
    HRESULT setError (HRESULT aResultCode, const GUID &aIID,
376
 
                      const char *aText, ...);
377
 
 
378
 
    /**
379
 
     * Same as #setWarning (HRESULT, const char *, ...) but allows to specify
380
 
     * the interface ID manually.
381
 
     */
382
 
    HRESULT setWarning (HRESULT aResultCode, const GUID &aIID,
383
 
                        const char *aText, ...);
384
 
};
385
 
 
386
 
////////////////////////////////////////////////////////////////////////////////
387
 
 
388
 
/**
389
 
 * The SupportErrorInfoDerived template class implements the remaining parts
390
 
 * of error info support in addition to SupportErrorInfoBase.
391
 
 *
392
 
 * These parts include the ISupportErrorInfo implementation on the MS COM
393
 
 * platform and implementations of mandatory SupportErrorInfoBase virtual
394
 
 * methods.
395
 
 *
396
 
 * On MS COM, the @a C template argument must declare a COM interface map using
397
 
 * BEGIN_COM_MAP / END_COM_MAP macros and this map must contain a
398
 
 * COM_INTERFACE_ENTRY(ISupportErrorInfo) definition. All interface entries that
399
 
 * follow it will be considered to support IErrorInfo, i.e. the
400
 
 * InterfaceSupportsErrorInfo() implementation will return S_OK for the
401
 
 * corresponding IIDs.
402
 
 *
403
 
 * On all platforms, the @a C template argument must be a subclass of
404
 
 * SupportErrorInfoBase and also define the following method: <tt>public static
405
 
 * const char *ComponentName()</tt> that will be used as a value returned by the
406
 
 * SupportErrorInfoBase::componentName() implementation.
407
 
 *
408
 
 * If SupportErrorInfoBase is used as a base for an intermediate component base
409
 
 * class FooBase then the final component FooFinal that inherits FooBase should
410
 
 * use this template class as follows:
411
 
 * <code>
412
 
 *     class FooFinal : public SupportErrorInfoDerived <FooBase, FooFinal, IFoo>
413
 
 *     {
414
 
 *         ...
415
 
 *     };
416
 
 * </code>
417
 
 *
418
 
 * Note that if you don not use intermediate component base classes, you should
419
 
 * use the SupportErrorInfoImpl class as a base for your component instead.
420
 
 *
421
 
 * @param B     Intermediate component base derived from SupportErrorInfoBase.
422
 
 * @param C     Component class that implements one or more COM interfaces.
423
 
 * @param I     Default interface for the component (for short #setError()
424
 
 *              versions).
425
 
 */
426
 
template <class B, class C, class I>
427
 
class ATL_NO_VTABLE SupportErrorInfoDerived : public B
428
 
#if !defined (VBOX_WITH_XPCOM)
429
 
    , public ISupportErrorInfo
430
 
#endif
431
 
{
432
 
public:
433
 
 
434
 
#if !defined (VBOX_WITH_XPCOM)
435
 
    STDMETHOD(InterfaceSupportsErrorInfo) (REFIID aIID)
436
 
    {
437
 
        const _ATL_INTMAP_ENTRY* pEntries = C::_GetEntries();
438
 
        Assert (pEntries);
439
 
        if (!pEntries)
440
 
            return S_FALSE;
441
 
 
442
 
        BOOL bSupports = FALSE;
443
 
        BOOL bISupportErrorInfoFound = FALSE;
444
 
 
445
 
        while (pEntries->pFunc != NULL && !bSupports)
446
 
        {
447
 
            if (!bISupportErrorInfoFound)
448
 
            {
449
 
                /* skip the COM map entries until ISupportErrorInfo is found */
450
 
                bISupportErrorInfoFound =
451
 
                    InlineIsEqualGUID (*(pEntries->piid), IID_ISupportErrorInfo);
452
 
            }
453
 
            else
454
 
            {
455
 
                /* look for the requested interface in the rest of the com map */
456
 
                bSupports = InlineIsEqualGUID (*(pEntries->piid), aIID);
457
 
            }
458
 
            pEntries++;
459
 
        }
460
 
 
461
 
        Assert (bISupportErrorInfoFound);
462
 
 
463
 
        return bSupports ? S_OK : S_FALSE;
464
 
    }
465
 
#endif /* !defined (VBOX_WITH_XPCOM) */
466
 
 
467
 
protected:
468
 
 
469
 
    virtual const GUID &mainInterfaceID() const { return COM_IIDOF (I); }
470
 
 
471
 
    virtual const char *componentName() const { return C::ComponentName(); }
472
 
};
473
 
 
474
 
////////////////////////////////////////////////////////////////////////////////
475
 
 
476
 
/**
477
 
 * The SupportErrorInfoImpl template class provides complete error info support
478
 
 * for COM component classes.
479
 
 *
480
 
 * Complete error info support includes what both SupportErrorInfoBase and
481
 
 * SupportErrorInfoDerived provide, e.g. a variety of setError() methods to
482
 
 * set extended error information from within a component's method
483
 
 * implementation and all necessary additional interface implementations (see
484
 
 * descriptions of these classes for details).
485
 
 *
486
 
 * To add error info support to a Foo component that implements a IFoo
487
 
 * interface, use the following pattern:
488
 
 * <code>
489
 
 *     class Foo : public SupportErrorInfoImpl <Foo, IFoo>
490
 
 *     {
491
 
 *     public:
492
 
 *
493
 
 *         ...
494
 
 *
495
 
 *         static const char *ComponentName() const { return "Foo"; }
496
 
 *     };
497
 
 * </code>
498
 
 *
499
 
 * Note that your component class (the @a C template argument) must provide the
500
 
 * ComponentName() implementation as shown above.
501
 
 *
502
 
 * @param C Component class that implements one or more COM interfaces.
503
 
 * @param I Default interface for the component (for short #setError()
504
 
 *          versions).
505
 
 */
506
 
template <class C, class I>
507
 
class ATL_NO_VTABLE SupportErrorInfoImpl
508
 
    : public SupportErrorInfoDerived <SupportErrorInfoBase, C, I>
509
 
{
510
 
};
511
 
 
512
 
} /* namespace com */
513
 
 
514
 
#endif /* ___VBox_com_SupportErrorInfo_h */
515