← Back to branch summary

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

« back to all changes in this revision

Viewing changes to include/VBox/com/ErrorInfo.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/ErrorInfo.h
4
4
 */
5
5
 
6
6
/*
7
 
 * Copyright (C) 2006-2007 Oracle Corporation
 
7
 * Copyright (C) 2006-2010 Oracle Corporation
8
8
 *
9
9
 * This file is part of VirtualBox Open Source Edition (OSE), as
10
10
 * available from http://www.virtualbox.org. This file is free software;
32
32
#include "VBox/com/Guid.h"
33
33
#include "VBox/com/assert.h"
34
34
 
35
 
#include <iprt/memory> // for auto_copy_ptr
36
 
 
37
35
struct IProgress;
38
36
struct IVirtualBoxErrorInfo;
39
37
 
56
54
 *      IFoo *foo;
57
55
 *      ...
58
56
 *      HRESULT rc = foo->SomeMethod();
59
 
 *      if (FAILED (rc)) {
60
 
 *          ErrorInfo info (foo);
 
57
 *      if (FAILED(rc)) {
 
58
 *          ErrorInfo info(foo);
61
59
 *          if (info.isFullAvailable()) {
62
 
 *              printf ("error message = %ls\n", info.getText().raw());
 
60
 *              printf("error message = %ls\n", info.getText().raw());
63
61
 *          }
64
62
 *      }
65
63
 *  </code>
108
106
     *  pointer available.
109
107
     */
110
108
    explicit ErrorInfo()
111
 
        : mIsBasicAvailable (false), mIsFullAvailable (false)
112
 
        , mResultCode (S_OK)
113
 
        { init(); }
114
 
 
115
 
    /**
116
 
     *  Constructs a new, "interfaceless" ErrorInfo instance that takes
117
 
     *  the error information possibly set on the current thread by an
118
 
     *  interface method of the given interface pointer.
119
 
 
120
 
     *  If the given interface does not support providing error information or,
121
 
     *  for some reason didn't set any error information, both
122
 
     *  #isFullAvailable() and #isBasicAvailable() will return |false|.
123
 
     *
124
 
     *  @param aPtr pointer to the interface whose method returned an
125
 
     *              error
126
 
     */
127
 
    template <class I> ErrorInfo (I *aPtr)
128
 
        : mIsBasicAvailable (false), mIsFullAvailable (false)
129
 
        , mResultCode (S_OK)
130
 
        { init (aPtr, COM_IIDOF(I)); }
131
 
 
132
 
    /**
133
 
     *  Constructs a new ErrorInfo instance from the smart interface pointer.
134
 
     *  See template <class I> ErrorInfo (I *aPtr) for details
135
 
     *
136
 
     *  @param aPtr smart pointer to the interface whose method returned
137
 
     *              an error
138
 
     */
139
 
    template <class I> ErrorInfo (const ComPtr <I> &aPtr)
140
 
        : mIsBasicAvailable (false), mIsFullAvailable (false)
141
 
        , mResultCode (S_OK)
142
 
        { init (static_cast <I*> (aPtr), COM_IIDOF(I)); }
 
109
        : mIsBasicAvailable(false),
 
110
          mIsFullAvailable(false),
 
111
          mResultCode(S_OK),
 
112
          m_pNext(NULL)
 
113
    {
 
114
        init();
 
115
    }
 
116
 
 
117
    ErrorInfo(IUnknown *pObj, const GUID &aIID)
 
118
        : mIsBasicAvailable(false),
 
119
          mIsFullAvailable(false),
 
120
          mResultCode(S_OK),
 
121
          m_pNext(NULL)
 
122
    {
 
123
        init(pObj, aIID);
 
124
    }
143
125
 
144
126
    /** Specialization for the IVirtualBoxErrorInfo smart pointer */
145
127
    ErrorInfo (const ComPtr <IVirtualBoxErrorInfo> &aPtr)
160
142
        , mResultCode (S_OK)
161
143
        { init (aInfo); }
162
144
 
163
 
    virtual ~ErrorInfo();
 
145
    ErrorInfo(const ErrorInfo &x)
 
146
    {
 
147
        copyFrom(x);
 
148
    }
 
149
 
 
150
    virtual ~ErrorInfo()
 
151
    {
 
152
        cleanup();
 
153
    }
 
154
 
 
155
    ErrorInfo& operator=(const ErrorInfo& x)
 
156
    {
 
157
        cleanup();
 
158
        copyFrom(x);
 
159
        return *this;
 
160
    }
164
161
 
165
162
    /**
166
163
     *  Returns whether basic error info is actually available for the current
174
171
     *  The appropriate methods of this class provide meaningful info only when
175
172
     *  this method returns true (otherwise they simply return NULL-like values).
176
173
     */
177
 
    bool isBasicAvailable() const { return mIsBasicAvailable; }
 
174
    bool isBasicAvailable() const
 
175
    {
 
176
        return mIsBasicAvailable;
 
177
    }
178
178
 
179
179
    /**
180
180
     *  Returns whether full error info is actually available for the current
188
188
     *  The appropriate methods of this class provide meaningful info only when
189
189
     *  this method returns true (otherwise they simply return NULL-like values).
190
190
     */
191
 
    bool isFullAvailable() const { return mIsFullAvailable; }
192
 
 
193
 
    /**
194
 
     *  Returns @c true if both isBasicAvailable() and isFullAvailable() are
195
 
     *  @c false.
196
 
     */
197
 
    bool isNull() const { return !mIsBasicAvailable && !mIsFullAvailable; }
 
191
    bool isFullAvailable() const
 
192
    {
 
193
        return mIsFullAvailable;
 
194
    }
198
195
 
199
196
    /**
200
197
     *  Returns the COM result code of the failed operation.
201
198
     */
202
 
    HRESULT getResultCode() const { return mResultCode; }
 
199
    HRESULT getResultCode() const
 
200
    {
 
201
        return mResultCode;
 
202
    }
203
203
 
204
204
    /**
205
205
     *  Returns the IID of the interface that defined the error.
206
206
     */
207
 
    const Guid &getInterfaceID() const { return mInterfaceID; }
 
207
    const Guid& getInterfaceID() const
 
208
    {
 
209
        return mInterfaceID;
 
210
    }
208
211
 
209
212
    /**
210
213
     *  Returns the name of the component that generated the error.
211
214
     */
212
 
    const Bstr &getComponent() const { return mComponent; }
 
215
    const Bstr& getComponent() const
 
216
    {
 
217
        return mComponent;
 
218
    }
213
219
 
214
220
    /**
215
221
     *  Returns the textual description of the error.
216
222
     */
217
 
    const Bstr &getText() const { return mText; }
 
223
    const Bstr& getText() const
 
224
    {
 
225
        return mText;
 
226
    }
218
227
 
219
228
    /**
220
229
     *  Returns the next error information object or @c NULL if there is none.
221
230
     */
222
 
    const ErrorInfo *getNext() const { return mNext.get(); }
 
231
    const ErrorInfo* getNext() const
 
232
    {
 
233
        return m_pNext;
 
234
    }
223
235
 
224
236
    /**
225
237
     *  Returns the name of the interface that defined the error
226
238
     */
227
 
    const Bstr &getInterfaceName() const { return mInterfaceName; }
 
239
    const Bstr& getInterfaceName() const
 
240
    {
 
241
        return mInterfaceName;
 
242
    }
228
243
 
229
244
    /**
230
245
     *  Returns the IID of the interface that returned the error.
231
246
     *
232
247
     *  This method returns a non-null IID only if the instance was created
233
 
     *  using #template <class I> ErrorInfo (I *i) or
234
 
     *  template <class I> ErrorInfo (const ComPtr <I> &i) constructor.
 
248
     *  using #template <class I> ErrorInfo(I *i) or
 
249
     *  template <class I> ErrorInfo(const ComPtr<I> &i) constructor.
235
250
     */
236
 
    const Guid &getCalleeIID() const { return mCalleeIID; }
 
251
    const Guid& getCalleeIID() const
 
252
    {
 
253
        return mCalleeIID;
 
254
    }
237
255
 
238
256
    /**
239
257
     *  Returns the name of the interface that returned the error
240
258
     *
241
259
     *  This method returns a non-null name only if the instance was created
242
 
     *  using #template <class I> ErrorInfo (I *i) or
243
 
     *  template <class I> ErrorInfo (const ComPtr <I> &i) constructor.
 
260
     *  using #template <class I> ErrorInfo(I *i) or
 
261
     *  template <class I> ErrorInfo(const ComPtr<I> &i) constructor.
244
262
     */
245
 
    const Bstr &getCalleeName() const { return mCalleeName; }
 
263
    const Bstr& getCalleeName() const
 
264
    {
 
265
        return mCalleeName;
 
266
    }
246
267
 
247
268
    /**
248
 
     *  Resets all collected error information. #isNull() will
249
 
     *  return @c true after this method is called.
 
269
     *  Resets all collected error information. #isBasicAvailable() and
 
270
     *  #isFullAvailable will return @c true after this method is called.
250
271
     */
251
272
    void setNull()
252
273
    {
253
 
        mIsBasicAvailable = false;
254
 
        mIsFullAvailable = false;
255
 
 
256
 
        mResultCode = S_OK;
257
 
        mInterfaceID.clear();
258
 
        mComponent.setNull();
259
 
        mText.setNull();
260
 
        mNext.reset();
261
 
        mInterfaceName.setNull();
262
 
        mCalleeIID.clear();
263
 
        mCalleeName.setNull();
264
 
        mErrorInfo.setNull();
 
274
        cleanup();
265
275
    }
266
276
 
267
277
protected:
268
278
 
269
 
    ErrorInfo (bool /* aDummy */)
270
 
        : mIsBasicAvailable (false), mIsFullAvailable (false)
271
 
        , mResultCode (S_OK)
272
 
        {}
273
 
 
274
 
    void init (bool aKeepObj = false);
275
 
    void init (IUnknown *aUnk, const GUID &aIID, bool aKeepObj = false);
276
 
    void init (IVirtualBoxErrorInfo *aInfo);
 
279
    ErrorInfo(bool /* aDummy */)
 
280
        : mIsBasicAvailable(false),
 
281
          mIsFullAvailable(false),
 
282
          mResultCode(S_OK),
 
283
          m_pNext(NULL)
 
284
    { }
 
285
 
 
286
    void copyFrom(const ErrorInfo &x);
 
287
    void cleanup();
 
288
 
 
289
    void init(bool aKeepObj = false);
 
290
    void init(IUnknown *aUnk, const GUID &aIID, bool aKeepObj = false);
 
291
    void init(IVirtualBoxErrorInfo *aInfo);
277
292
 
278
293
    bool mIsBasicAvailable : 1;
279
294
    bool mIsFullAvailable : 1;
283
298
    Bstr    mComponent;
284
299
    Bstr    mText;
285
300
 
286
 
    cppx::auto_copy_ptr <ErrorInfo> mNext;
 
301
    ErrorInfo *m_pNext;
287
302
 
288
303
    Bstr mInterfaceName;
289
304
    Guid mCalleeIID;
290
305
    Bstr mCalleeName;
291
306
 
292
 
    ComPtr <IUnknown> mErrorInfo;
 
307
    ComPtr<IUnknown> mErrorInfo;
293
308
};
294
309
 
295
310
/**
310
325
     *
311
326
     *  @param  progress    the progress object representing a failed operation
312
327
     */
313
 
    ProgressErrorInfo (IProgress *progress);
 
328
    ProgressErrorInfo(IProgress *progress);
314
329
};
315
330
 
316
331
/**
330
345
 *  The usage pattern is:
331
346
 *  <code>
332
347
 *      rc = foo->method();
333
 
 *      if (FAILED (rc))
 
348
 *      if (FAILED(rc))
334
349
 *      {
335
350
 *           ErrorInfoKeeper eik;
336
351
 *           ...
356
371
     *  @param aIsNull  @c true to prevent fetching error info and leave
357
372
     *                  the instance uninitialized.
358
373
     */
359
 
    ErrorInfoKeeper (bool aIsNull = false)
360
 
        : ErrorInfo (false), mForgot (aIsNull)
 
374
    ErrorInfoKeeper(bool aIsNull = false)
 
375
        : ErrorInfo(false), mForgot(aIsNull)
361
376
    {
362
377
        if (!aIsNull)
363
 
            init (true /* aKeepObj */);
 
378
            init(true /* aKeepObj */);
364
379
    }
365
380
 
366
381
    /**
380
395
    {
381
396
        setNull();
382
397
        mForgot = false;
383
 
        init (true /* aKeepObj */);
 
398
        init(true /* aKeepObj */);
384
399
    }
385
400
 
386
401
    /**
402
417
     *  being restored by #restore() or by the destructor, and returns the
403
418
     *  stored error info object to the caller.
404
419
     */
405
 
    ComPtr <IUnknown> takeError() { mForgot = true; return mErrorInfo; }
 
420
    ComPtr<IUnknown> takeError() { mForgot = true; return mErrorInfo; }
406
421
 
407
422
private:
408
423