ErrorInfo.h revision dc09cb937d0a66e030b4d7bef88dec429f41e060
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * MS COM / XPCOM Abstraction Layer:
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * ErrorInfo class declaration
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * Copyright (C) 2006-2007 Oracle Corporation
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * available from http://www.virtualbox.org. This file is free software;
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * you can redistribute it and/or modify it under the terms of the GNU
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * General Public License (GPL) as published by the Free Software
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
a16eb14ad7a4b5ef91ddc22d3e8e92d930f736fcvboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * The contents of this file may alternatively be used under the terms
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * of the Common Development and Distribution License Version 1.0
1c94c0a63ba68be1a7b2c640e70d7a06464e4fcavboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * VirtualBox OSE distribution, in which case the provisions of the
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * CDDL are applicable instead of those of the GPL.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * You may elect to license modified versions of this file under the
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * terms and conditions of either the GPL or the CDDL or both.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * The ErrorInfo class provides a convenient way to retrieve error
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * information set by the most recent interface method, that was invoked on
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * the current thread and returned an unsuccessful result code.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Once the instance of this class is created, the error information for
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * the current thread is cleared.
223cf005b18af2c21352a70693ebaf0582f68ebcvboxsync * There is no sense to use instances of this class after the last
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * invoked interface method returns a success.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * The class usage pattern is as follows:
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * IFoo *foo;
afed5ab737f4aacfae3fe73776f40e989190a7cavboxsync * HRESULT rc = foo->SomeMethod();
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * if (FAILED (rc)) {
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * ErrorInfo info (foo);
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * if (info.isFullAvailable()) {
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * printf ("error message = %ls\n", info.getText().raw());
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * This class fetches error information using the IErrorInfo interface on
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Win32 (MS COM) or the nsIException interface on other platforms (XPCOM),
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * or the extended IVirtualBoxErrorInfo interface when when it is available
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * (i.e. a given IErrorInfo or nsIException instance implements it).
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Currently, IVirtualBoxErrorInfo is only available for VirtualBox components.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * ErrorInfo::isFullAvailable() and ErrorInfo::isBasicAvailable() determine
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * what level of error information is available. If #isBasicAvailable()
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * returns true, it means that only IErrorInfo or nsIException is available as
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * the source of information (depending on the platform), but not
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * IVirtualBoxErrorInfo. If #isFullAvailable() returns true, it means that all
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * three interfaces are available. If both methods return false, no error info
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * is available at all.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Here is a table of correspondence between this class methods and
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * and IErrorInfo/nsIException/IVirtualBoxErrorInfo attributes/methods:
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * ErrorInfo IErrorInfo nsIException IVirtualBoxErrorInfo
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * --------------------------------------------------------------------
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * getResultCode -- result resultCode
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * getIID GetGUID -- interfaceID
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * getComponent GetSource -- component
7e960d3a0a8a3a84d7aba2cca45d72b1c31cc97bvboxsync * getText GetDescription message text
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * '--' means that this interface does not provide the corresponding portion
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * of information, therefore it is useless to query it if only
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * #isBasicAvailable() returns true. As it can be seen, the amount of
726fc44ad0bd65a178ad4c3ab46ebd6cd3208e99vboxsync * information provided at the basic level, depends on the platform
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * (MS COM or XPCOM).
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Constructs a new, "interfaceless" ErrorInfo instance that takes
726fc44ad0bd65a178ad4c3ab46ebd6cd3208e99vboxsync * the error information possibly set on the current thread by an
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * interface method of some COM component or by the COM subsystem.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * This constructor is useful, for example, after an unsuccessful attempt
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * to instantiate (create) a component, so there is no any valid interface
3080f6c0871099df43a4e91b31894d9c2b1369a8vboxsync * pointer available.
3080f6c0871099df43a4e91b31894d9c2b1369a8vboxsync : mIsBasicAvailable (false), mIsFullAvailable (false)
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Constructs a new, "interfaceless" ErrorInfo instance that takes
fdea543f71872a3ec3909536a4fce37ab7aa3a8bvboxsync * the error information possibly set on the current thread by an
726fc44ad0bd65a178ad4c3ab46ebd6cd3208e99vboxsync * interface method of the given interface pointer.
726fc44ad0bd65a178ad4c3ab46ebd6cd3208e99vboxsync * If the given interface does not support providing error information or,
fdea543f71872a3ec3909536a4fce37ab7aa3a8bvboxsync * for some reason didn't set any error information, both
726fc44ad0bd65a178ad4c3ab46ebd6cd3208e99vboxsync * #isFullAvailable() and #isBasicAvailable() will return |false|.
726fc44ad0bd65a178ad4c3ab46ebd6cd3208e99vboxsync * @param aPtr pointer to the interface whose method returned an
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync : mIsBasicAvailable (false), mIsFullAvailable (false)
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * Constructs a new ErrorInfo instance from the smart interface pointer.
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * See template <class I> ErrorInfo (I *aPtr) for details
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * @param aPtr smart pointer to the interface whose method returned
3080f6c0871099df43a4e91b31894d9c2b1369a8vboxsync template <class I> ErrorInfo (const ComPtr <I> &aPtr)
3080f6c0871099df43a4e91b31894d9c2b1369a8vboxsync : mIsBasicAvailable (false), mIsFullAvailable (false)
3080f6c0871099df43a4e91b31894d9c2b1369a8vboxsync /** Specialization for the IVirtualBoxErrorInfo smart pointer */
3080f6c0871099df43a4e91b31894d9c2b1369a8vboxsync ErrorInfo (const ComPtr <IVirtualBoxErrorInfo> &aPtr)
3080f6c0871099df43a4e91b31894d9c2b1369a8vboxsync : mIsBasicAvailable (false), mIsFullAvailable (false)
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * Constructs a new ErrorInfo instance from the IVirtualBoxErrorInfo
726fc44ad0bd65a178ad4c3ab46ebd6cd3208e99vboxsync * interface pointer. If this pointer is not NULL, both #isFullAvailable()
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * and #isBasicAvailable() will return |true|.
726fc44ad0bd65a178ad4c3ab46ebd6cd3208e99vboxsync * @param aInfo pointer to the IVirtualBoxErrorInfo interface that
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * holds error info to be fetched by this instance
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync : mIsBasicAvailable (false), mIsFullAvailable (false)
26824086a3f6b36cd911058f1d9b4c0b944706fbvboxsync * Returns whether basic error info is actually available for the current
26824086a3f6b36cd911058f1d9b4c0b944706fbvboxsync * thread. If the instance was created from an interface pointer that
26824086a3f6b36cd911058f1d9b4c0b944706fbvboxsync * supports basic error info and successfully provided it, or if it is an
68ef804c4ec232c58e2c03c8fc6afe3765c5c0d1vboxsync * "interfaceless" instance and there is some error info for the current
68ef804c4ec232c58e2c03c8fc6afe3765c5c0d1vboxsync * thread, the returned value will be true.
3080f6c0871099df43a4e91b31894d9c2b1369a8vboxsync * See the class description for details about the basic error info level.
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * The appropriate methods of this class provide meaningful info only when
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * this method returns true (otherwise they simply return NULL-like values).
26824086a3f6b36cd911058f1d9b4c0b944706fbvboxsync bool isBasicAvailable() const { return mIsBasicAvailable; }
b8aaccdbdd143967110d499670605dd7ff6ecc72vboxsync * Returns whether full error info is actually available for the current
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * thread. If the instance was created from an interface pointer that
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync * supports full error info and successfully provided it, or if it is an
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * "interfaceless" instance and there is some error info for the current
7e960d3a0a8a3a84d7aba2cca45d72b1c31cc97bvboxsync * thread, the returned value will be true.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * See the class description for details about the full error info level.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * The appropriate methods of this class provide meaningful info only when
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * this method returns true (otherwise they simply return NULL-like values).
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync bool isFullAvailable() const { return mIsFullAvailable; }
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Returns @c true if both isBasicAvailable() and isFullAvailable() are
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * @c false.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync bool isNull() const { return !mIsBasicAvailable && !mIsFullAvailable; }
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Returns the COM result code of the failed operation.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync HRESULT getResultCode() const { return mResultCode; }
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Returns the IID of the interface that defined the error.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync const Guid &getInterfaceID() const { return mInterfaceID; }
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Returns the name of the component that generated the error.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync const Bstr &getComponent() const { return mComponent; }
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Returns the textual description of the error.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Returns the next error information object or @c NULL if there is none.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync const ErrorInfo *getNext() const { return mNext.get(); }
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Returns the name of the interface that defined the error
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync const Bstr &getInterfaceName() const { return mInterfaceName; }
3ecf9412133496b2aeb090cfd33a286404ec59fbvboxsync * Returns the IID of the interface that returned the error.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * This method returns a non-null IID only if the instance was created
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * using #template <class I> ErrorInfo (I *i) or
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * template <class I> ErrorInfo (const ComPtr <I> &i) constructor.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync const Guid &getCalleeIID() const { return mCalleeIID; }
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Returns the name of the interface that returned the error
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * This method returns a non-null name only if the instance was created
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * using #template <class I> ErrorInfo (I *i) or
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * template <class I> ErrorInfo (const ComPtr <I> &i) constructor.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync const Bstr &getCalleeName() const { return mCalleeName; }
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Resets all collected error information. #isNull() will
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * return @c true after this method is called.
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync : mIsBasicAvailable (false), mIsFullAvailable (false)
50df3da42ff6589b0ecc4f50f2288811bc370186vboxsync void init (IUnknown *aUnk, const GUID &aIID, bool aKeepObj = false);
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * A convenience subclass of ErrorInfo that, given an IProgress interface
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * pointer, reads its errorInfo attribute and uses the returned
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * IVirtualBoxErrorInfo instance to construct itself.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Constructs a new instance by fetching error information from the
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * IProgress interface pointer. If the progress object is not NULL,
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * its completed attribute is true, resultCode represents a failure,
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * and the errorInfo attribute returns a valid IVirtualBoxErrorInfo pointer,
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * both #isFullAvailable() and #isBasicAvailable() will return true.
e08de24d4792d31b7f2aac29db5cb8840d940009vboxsync * @param progress the progress object representing a failed operation
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * A convenience subclass of ErrorInfo that allows to preserve the current
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * error info. Instances of this class fetch an error info object set on the
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * current thread and keep a reference to it, which allows to restore it
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * later using the #restore() method. This is useful to preserve error
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * information returned by some method for the duration of making another COM
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * call that may set its own error info and overwrite the existing
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * one. Preserving and restoring error information makes sense when some
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * method wants to return error information set by other call as its own
f9147fe1eaa4e35287f8f39282c7f92f0d7de0b7vboxsync * error information while it still needs to make another call before return.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Instead of calling #restore() explicitly you may let the object destructor
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * do it for you, if you correctly limit the object's lifetime.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * The usage pattern is:
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * rc = foo->method();
da936e0446fb2b56b813d5d938f1dfc6e4bf8b13vboxsync * if (FAILED (rc))
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * ErrorInfoKeeper eik;
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * // bar may return error info as well
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * bar->method();
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * // no need to call #restore() explicitly here because the eik's
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * // destructor will restore error info fetched after the failed
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * // call to foo before returning to the caller
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * return rc;
da936e0446fb2b56b813d5d938f1dfc6e4bf8b13vboxsync * Constructs a new instance that will fetch the current error info if
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * @a aIsNull is @c false (by default) or remain uninitialized (null)
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * otherwise.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * @param aIsNull @c true to prevent fetching error info and leave
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * the instance uninitialized.
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * Destroys this instance and automatically calls #restore() which will
d408b82da0773c7e8cd4b3a01cb8a065a2c73a2dvboxsync * either restore error info fetched by the constructor or do nothing
533ffcb943c4af2c5fe6385d816d0ba3eda9383bvboxsync * if #forget() was called before destruction.
00599f6d39cc25ca39845c2433cd75de7b9f6971vboxsync * Tries to (re-)fetch error info set on the current thread. On success,
00599f6d39cc25ca39845c2433cd75de7b9f6971vboxsync * the previous error information, if any, will be overwritten with the
533ffcb943c4af2c5fe6385d816d0ba3eda9383bvboxsync * new error information. On failure, or if there is no error information
533ffcb943c4af2c5fe6385d816d0ba3eda9383bvboxsync * available, this instance will be reset to null.
1843553dbdf4e46417158b4c6348c503adf10740vboxsync * Restores error info fetched by the constructor and forgets it
1843553dbdf4e46417158b4c6348c503adf10740vboxsync * afterwards. Does nothing if the error info was forgotten by #forget().
1843553dbdf4e46417158b4c6348c503adf10740vboxsync * @return COM result of the restore operation.
1843553dbdf4e46417158b4c6348c503adf10740vboxsync * Forgets error info fetched by the constructor to prevent it from
1843553dbdf4e46417158b4c6348c503adf10740vboxsync * being restored by #restore() or by the destructor.
1843553dbdf4e46417158b4c6348c503adf10740vboxsync * Forgets error info fetched by the constructor to prevent it from
1843553dbdf4e46417158b4c6348c503adf10740vboxsync * being restored by #restore() or by the destructor, and returns the
ebbb1f6c7e8bae363a4efda4b35b58c8467d24bcvboxsync * stored error info object to the caller.
1843553dbdf4e46417158b4c6348c503adf10740vboxsync ComPtr <IUnknown> takeError() { mForgot = true; return mErrorInfo; }
1843553dbdf4e46417158b4c6348c503adf10740vboxsync} /* namespace com */