622
752
friend class AutoUninitSpan;
625
////////////////////////////////////////////////////////////////////////////////
627
// VirtualBoxSupportTranslation, VirtualBoxSupportErrorInfoImpl
629
////////////////////////////////////////////////////////////////////////////////
632
* This macro adds the error info support to methods of the VirtualBoxBase
633
* class (by overriding them). Place it to the public section of the
634
* VirtualBoxBase subclass and the following methods will set the extended
635
* error info in case of failure instead of just returning the result code:
638
* <li>VirtualBoxBase::addCaller()
641
* @note The given VirtualBoxBase subclass must also inherit from both
642
* VirtualBoxSupportErrorInfoImpl and VirtualBoxSupportTranslation templates!
644
* @param C VirtualBoxBase subclass to add the error info support to
646
#define VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT(C) \
647
virtual HRESULT addCaller(VirtualBoxBase::State *aState = NULL, \
648
bool aLimited = false) \
650
VirtualBoxBase::State protoState; \
651
HRESULT rc = VirtualBoxBase::addCaller(&protoState, aLimited); \
654
if (protoState == VirtualBoxBase::Limited) \
655
rc = setError(rc, tr("The object functionality is limited")); \
657
rc = setError(rc, tr("The object is not ready")); \
660
*aState = protoState; \
664
////////////////////////////////////////////////////////////////////////////////
666
/** Helper for VirtualBoxSupportTranslation. */
667
class VirtualBoxSupportTranslationBase
670
static bool cutClassNameFrom__PRETTY_FUNCTION__(char *aPrettyFunctionName);
674
* The VirtualBoxSupportTranslation template implements the NLS string
675
* translation support for the given class.
677
* Translation support is provided by the static #tr() function. This function,
678
* given a string in UTF-8 encoding, looks up for a translation of the given
679
* string by calling the VirtualBoxBase::translate() global function which
680
* receives the name of the enclosing class ("context of translation") as the
681
* additional argument and returns a translated string based on the currently
684
* @param C Class that needs to support the string translation.
686
* @note Every class that wants to use the #tr() function in its own methods
687
* must inherit from this template, regardless of whether its base class
688
* (if any) inherits from it or not. Otherwise, the translation service
689
* will not work correctly. However, the declaration of the derived
691
* the <tt>COM_SUPPORTTRANSLATION_OVERRIDE (<ClassName>)</tt> macro if one
692
* of its base classes also inherits from this template (to resolve the
693
* ambiguity of the #tr() function).
696
class VirtualBoxSupportTranslation : virtual protected VirtualBoxSupportTranslationBase
701
* Translates the given text string by calling VirtualBoxBase::translate()
702
* and passing the name of the C class as the first argument ("context of
703
* translation") See VirtualBoxBase::translate() for more info.
705
* @param aSourceText String to translate.
706
* @param aComment Comment to the string to resolve possible
707
* ambiguities (NULL means no comment).
709
* @return Translated version of the source string in UTF-8 encoding, or
710
* the source string itself if the translation is not found in the
713
inline static const char *tr(const char *aSourceText,
714
const char *aComment = NULL)
716
return VirtualBoxBase::translate(className(), aSourceText, aComment);
721
static const char *className()
723
static char fn[sizeof(__PRETTY_FUNCTION__) + 1];
726
strcpy(fn, __PRETTY_FUNCTION__);
727
cutClassNameFrom__PRETTY_FUNCTION__(fn);
735
static const char *sClassName;
739
const char *VirtualBoxSupportTranslation<C>::sClassName = NULL;
742
* This macro must be invoked inside the public section of the declaration of
743
* the class inherited from the VirtualBoxSupportTranslation template in case
744
* if one of its other base classes also inherits from that template. This is
745
* necessary to resolve the ambiguity of the #tr() function.
747
* @param C Class that inherits the VirtualBoxSupportTranslation template
748
* more than once (through its other base clases).
750
#define VIRTUALBOXSUPPORTTRANSLATION_OVERRIDE(C) \
751
inline static const char *tr(const char *aSourceText, \
752
const char *aComment = NULL) \
754
return VirtualBoxSupportTranslation<C>::tr(aSourceText, aComment); \
758
756
* Dummy macro that is used to shut down Qt's lupdate tool warnings in some
759
757
* situations. This macro needs to be present inside (better at the very
765
763
////////////////////////////////////////////////////////////////////////////////
768
* Helper for the VirtualBoxSupportErrorInfoImpl template.
770
/// @todo switch to com::SupportErrorInfo* and remove
771
class VirtualBoxSupportErrorInfoImplBase
773
static HRESULT setErrorInternal(HRESULT aResultCode,
775
const wchar_t *aComponent,
783
* The MultiResult class is a com::FWResult enhancement that also acts as a
784
* switch to turn on multi-error mode for #setError() or #setWarning()
787
* When an instance of this class is created, multi-error mode is turned on
788
* for the current thread and the turn-on counter is increased by one. In
789
* multi-error mode, a call to #setError() or #setWarning() does not
790
* overwrite the current error or warning info object possibly set on the
791
* current thread by other method calls, but instead it stores this old
792
* object in the IVirtualBoxErrorInfo::next attribute of the new error
795
* This way, error/warning objects are stacked together and form a chain of
796
* errors where the most recent error is the first one retrieved by the
797
* calling party, the preceding error is what the
798
* IVirtualBoxErrorInfo::next attribute of the first error points to, and so
799
* on, up to the first error or warning occurred which is the last in the
800
* chain. See IVirtualBoxErrorInfo documentation for more info.
802
* When the instance of the MultiResult class goes out of scope and gets
803
* destroyed, it automatically decreases the turn-on counter by one. If
804
* the counter drops to zero, multi-error mode for the current thread is
805
* turned off and the thread switches back to single-error mode where every
806
* next error or warning object overwrites the previous one.
808
* Note that the caller of a COM method uses a non-S_OK result code to
809
* decide if the method has returned an error (negative codes) or a warning
810
* (positive non-zero codes) and will query extended error info only in
811
* these two cases. However, since multi-error mode implies that the method
812
* doesn't return control return to the caller immediately after the first
813
* error or warning but continues its execution, the functionality provided
814
* by the base com::FWResult class becomes very useful because it allows to
815
* preserve the error or the warning result code even if it is later assigned
816
* a S_OK value multiple times. See com::FWResult for details.
818
* Here is the typical usage pattern:
821
HRESULT Bar::method()
823
// assume multi-errors are turned off here...
827
// Turn on multi-error mode and make sure severity is preserved
828
MultiResult rc = foo->method1();
830
// return on fatal error, but continue on warning or on success
831
if (FAILED(rc)) return rc;
834
// no matter what result, stack it and continue
838
// return the last worst result code (it will be preserved even if
839
// foo->method2() returns S_OK.
843
// multi-errors are turned off here again...
851
* @note This class is intended to be instantiated on the stack, therefore
852
* You cannot create them using new(). Although it is possible to copy
853
* instances of MultiResult or return them by value, please never do
854
* that as it is breaks the class semantics (and will assert).
856
class MultiResult : public com::FWResult
861
* @copydoc com::FWResult::FWResult().
863
MultiResult(HRESULT aRC = E_FAIL) : FWResult(aRC) { init(); }
865
MultiResult(const MultiResult &aThat) : FWResult(aThat)
867
/* We need this copy constructor only for GCC that wants to have
868
* it in case of expressions like |MultiResult rc = E_FAIL;|. But
869
* we assert since the optimizer should actually avoid the
870
* temporary and call the other constructor directly instead. */
877
MultiResult &operator=(HRESULT aRC)
879
com::FWResult::operator=(aRC);
883
MultiResult &operator=(const MultiResult &aThat)
885
/* We need this copy constructor only for GCC that wants to have
886
* it in case of expressions like |MultiResult rc = E_FAIL;|. But
887
* we assert since the optimizer should actually avoid the
888
* temporary and call the other constructor directly instead. */
890
com::FWResult::operator=(aThat);
896
DECLARE_CLS_NEW_DELETE_NOOP(MultiResult)
900
static RTTLS sCounter;
902
friend class VirtualBoxSupportErrorInfoImplBase;
905
static HRESULT setError(HRESULT aResultCode,
907
const wchar_t *aComponent,
911
return setErrorInternal(aResultCode, aIID, aComponent, aText,
912
false /* aWarning */, aLogIt);
915
static HRESULT setWarning(HRESULT aResultCode,
917
const wchar_t *aComponent,
920
return setErrorInternal(aResultCode, aIID, aComponent, aText,
921
true /* aWarning */, true /* aLogIt */);
924
static HRESULT setError(HRESULT aResultCode,
926
const wchar_t *aComponent,
927
const char *aText, va_list aArgs, bool aLogIt = true)
929
return setErrorInternal(aResultCode, aIID, aComponent,
930
Utf8StrFmtVA (aText, aArgs),
931
false /* aWarning */, aLogIt);
934
static HRESULT setWarning(HRESULT aResultCode,
936
const wchar_t *aComponent,
937
const char *aText, va_list aArgs)
939
return setErrorInternal(aResultCode, aIID, aComponent,
940
Utf8StrFmtVA (aText, aArgs),
941
true /* aWarning */, true /* aLogIt */);
946
* This template implements ISupportErrorInfo for the given component class
947
* and provides the #setError() method to conveniently set the error information
948
* from within interface methods' implementations.
950
* On Windows, the template argument must define a COM interface map using
951
* BEGIN_COM_MAP / END_COM_MAP macros and this map must contain a
952
* COM_INTERFACE_ENTRY(ISupportErrorInfo) definition. All interface entries
953
* that follow it will be considered to support IErrorInfo, i.e. the
954
* InterfaceSupportsErrorInfo() implementation will return S_OK for the
957
* On all platforms, the template argument must also define the following
958
* method: |public static const wchar_t *C::getComponentName()|. See
959
* #setError(HRESULT, const char *, ...) for a description on how it is
963
* component class that implements one or more COM interfaces
965
* default interface for the component. This interface's IID is used
966
* by the shortest form of #setError, for convenience.
968
/// @todo switch to com::SupportErrorInfo* and remove
969
template<class C, class I>
970
class ATL_NO_VTABLE VirtualBoxSupportErrorInfoImpl
971
: protected VirtualBoxSupportErrorInfoImplBase
972
#if !defined (VBOX_WITH_XPCOM)
973
, public ISupportErrorInfo
979
#if !defined (VBOX_WITH_XPCOM)
980
STDMETHOD(InterfaceSupportsErrorInfo)(REFIID riid)
982
const _ATL_INTMAP_ENTRY* pEntries = C::_GetEntries();
987
BOOL bSupports = FALSE;
988
BOOL bISupportErrorInfoFound = FALSE;
990
while (pEntries->pFunc != NULL && !bSupports)
992
if (!bISupportErrorInfoFound)
994
// skip the com map entries until ISupportErrorInfo is found
995
bISupportErrorInfoFound =
996
InlineIsEqualGUID(*(pEntries->piid), IID_ISupportErrorInfo);
1000
// look for the requested interface in the rest of the com map
1001
bSupports = InlineIsEqualGUID(*(pEntries->piid), riid);
1006
Assert(bISupportErrorInfoFound);
1008
return bSupports ? S_OK : S_FALSE;
1010
#endif // !defined (VBOX_WITH_XPCOM)
1015
* Sets the error information for the current thread.
1016
* This information can be retrieved by a caller of an interface method
1017
* using IErrorInfo on Windows or nsIException on Linux, or the cross-platform
1018
* IVirtualBoxErrorInfo interface that provides extended error info (only
1019
* for components from the VirtualBox COM library). Alternatively, the
1020
* platform-independent class com::ErrorInfo (defined in VBox[XP]COM.lib)
1021
* can be used to retrieve error info in a convenient way.
1023
* It is assumed that the interface method that uses this function returns
1024
* an unsuccessful result code to the caller (otherwise, there is no reason
1025
* for the caller to try to retrieve error info after method invocation).
1027
* Here is a table of correspondence between this method's arguments
1028
* and IErrorInfo/nsIException/IVirtualBoxErrorInfo attributes/methods:
1030
* argument IErrorInfo nsIException IVirtualBoxErrorInfo
1031
* ----------------------------------------------------------------
1032
* resultCode -- result resultCode
1033
* iid GetGUID -- interfaceID
1034
* component GetSource -- component
1035
* text GetDescription message text
1037
* This method is rarely needs to be used though. There are more convenient
1038
* overloaded versions, that automatically substitute some arguments
1039
* taking their values from the template parameters. See
1040
* #setError(HRESULT, const char *, ...) for an example.
1042
* @param aResultCode result (error) code, must not be S_OK
1043
* @param aIID IID of the interface that defines the error
1044
* @param aComponent name of the component that generates the error
1045
* @param aText error message (must not be null), an RTStrPrintf-like
1046
* format string in UTF-8 encoding
1047
* @param ... list of arguments for the format string
1050
* the error argument, for convenience, If an error occurs while
1051
* creating error info itself, that error is returned instead of the
1054
static HRESULT setError(HRESULT aResultCode, const GUID &aIID,
1055
const wchar_t *aComponent,
1056
const char *aText, ...)
1059
va_start(args, aText);
1060
HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setError(aResultCode,
1071
* This method is the same as #setError() except that it makes sure @a
1072
* aResultCode doesn't have the error severity bit (31) set when passed
1073
* down to the created IVirtualBoxErrorInfo object.
1075
* The error severity bit is always cleared by this call, thereof you can
1076
* use ordinary E_XXX result code constants, for convenience. However, this
1077
* behavior may be non-standard on some COM platforms.
1079
static HRESULT setWarning(HRESULT aResultCode, const GUID &aIID,
1080
const wchar_t *aComponent,
1081
const char *aText, ...)
1084
va_start(args, aText);
1085
HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setWarning(
1086
aResultCode, aIID, aComponent, aText, args);
1092
* Sets the error information for the current thread.
1093
* A convenience method that automatically sets the default interface
1094
* ID (taken from the I template argument) and the component name
1095
* (a value of C::getComponentName()).
1097
* See #setError(HRESULT, const GUID &, const wchar_t *, const char *text, ...)
1100
* This method is the most common (and convenient) way to set error
1101
* information from within interface methods. A typical pattern of usage
1102
* is looks like this:
1105
* return setError(E_FAIL, "Terrible Error");
1109
* HRESULT rc = setError(E_FAIL, "Terrible Error");
1114
static HRESULT setError(HRESULT aResultCode, const char *aText, ...)
1117
va_start(args, aText);
1118
HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setError(aResultCode,
1120
C::getComponentName(),
1129
* This method is the same as #setError() except that it makes sure @a
1130
* aResultCode doesn't have the error severity bit (31) set when passed
1131
* down to the created IVirtualBoxErrorInfo object.
1133
* The error severity bit is always cleared by this call, thereof you can
1134
* use ordinary E_XXX result code constants, for convenience. However, this
1135
* behavior may be non-standard on some COM platforms.
1137
static HRESULT setWarning(HRESULT aResultCode, const char *aText, ...)
1140
va_start(args, aText);
1141
HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setWarning(aResultCode,
1143
C::getComponentName(),
1151
* Sets the error information for the current thread, va_list variant.
1152
* A convenience method that automatically sets the default interface
1153
* ID (taken from the I template argument) and the component name
1154
* (a value of C::getComponentName()).
1156
* See #setError(HRESULT, const GUID &, const wchar_t *, const char *text, ...)
1157
* and #setError(HRESULT, const char *, ...) for details.
1159
static HRESULT setErrorV(HRESULT aResultCode, const char *aText,
1162
HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setError(aResultCode,
1164
C::getComponentName(),
1172
* This method is the same as #setErrorV() except that it makes sure @a
1173
* aResultCode doesn't have the error severity bit (31) set when passed
1174
* down to the created IVirtualBoxErrorInfo object.
1176
* The error severity bit is always cleared by this call, thereof you can
1177
* use ordinary E_XXX result code constants, for convenience. However, this
1178
* behavior may be non-standard on some COM platforms.
1180
static HRESULT setWarningV(HRESULT aResultCode, const char *aText,
1183
HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setWarning(aResultCode,
1185
C::getComponentName(),
1192
* Sets the error information for the current thread.
1193
* A convenience method that automatically sets the component name
1194
* (a value of C::getComponentName()), but allows to specify the interface
1197
* See #setError(HRESULT, const GUID &, const wchar_t *, const char *text, ...)
1200
static HRESULT setError(HRESULT aResultCode, const GUID &aIID,
1201
const char *aText, ...)
1204
va_start(args, aText);
1205
HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setError(aResultCode,
1207
C::getComponentName(),
1216
* This method is the same as #setError() except that it makes sure @a
1217
* aResultCode doesn't have the error severity bit (31) set when passed
1218
* down to the created IVirtualBoxErrorInfo object.
1220
* The error severity bit is always cleared by this call, thereof you can
1221
* use ordinary E_XXX result code constants, for convenience. However, this
1222
* behavior may be non-standard on some COM platforms.
1224
static HRESULT setWarning(HRESULT aResultCode, const GUID &aIID,
1225
const char *aText, ...)
1228
va_start(args, aText);
1229
HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setWarning(aResultCode,
1231
C::getComponentName(),
1239
* Sets the error information for the current thread but doesn't put
1240
* anything in the release log. This is very useful for avoiding
1241
* harmless error from causing confusion.
1243
* It is otherwise identical to #setError(HRESULT, const char *text, ...).
1245
static HRESULT setErrorNoLog(HRESULT aResultCode, const char *aText, ...)
1248
va_start(args, aText);
1249
HRESULT rc = VirtualBoxSupportErrorInfoImplBase::setError(aResultCode,
1251
C::getComponentName(),
1254
false /* aLogIt */);
1265
* Base class to track VirtualBoxBaseNEXT chlidren of the component.
1267
* This class is a preferrable VirtualBoxBase replacement for components that
1268
* operate with collections of child components. It gives two useful
1272
* Given an IUnknown instance, it's possible to quickly determine
1273
* whether this instance represents a child object that belongs to the
1274
* given component, and if so, get a valid VirtualBoxBase pointer to the
1275
* child object. The returned pointer can be then safely casted to the
1276
* actual class of the child object (to get access to its "internal"
1277
* non-interface methods) provided that no other child components implement
1278
* the same original COM interface IUnknown is queried from.
1280
* When the parent object uninitializes itself, it can easily unintialize
1281
* all its VirtualBoxBase derived children (using their
1282
* VirtualBoxBase::uninit() implementations). This is done simply by
1283
* calling the #uninitDependentChildren() method.
1286
* In order to let the above work, the following must be done:
1288
* When a child object is initialized, it calls #addDependentChild() of
1289
* its parent to register itself within the list of dependent children.
1291
* When the child object it is uninitialized, it calls
1292
* #removeDependentChild() to unregister itself.
1295
* Note that if the parent object does not call #uninitDependentChildren() when
1296
* it gets uninitialized, it must call uninit() methods of individual children
1297
* manually to disconnect them; a failure to do so will cause crashes in these
1298
* methods when children get destroyed. The same applies to children not calling
1299
* #removeDependentChild() when getting destroyed.
1301
* Note that children added by #addDependentChild() are <b>weakly</b> referenced
1302
* (i.e. AddRef() is not called), so when a child object is deleted externally
1303
* (because it's reference count goes to zero), it will automatically remove
1304
* itself from the map of dependent children provided that it follows the rules
1307
* Access to the child list is serialized using the #childrenLock() lock handle
1308
* (which defaults to the general object lock handle (see
1309
* VirtualBoxBase::lockHandle()). This lock is used by all add/remove methods of
1310
* this class so be aware of the need to preserve the {parent, child} lock order
1311
* when calling these methods.
1313
* Read individual method descriptions to get further information.
1315
* @todo This is a VirtualBoxBaseWithChildren equivalent that uses the
1316
* VirtualBoxBaseNEXT implementation. Will completely supersede
1317
* VirtualBoxBaseWithChildren after the old VirtualBoxBase implementation
1320
class VirtualBoxBaseWithChildrenNEXT : public VirtualBoxBase
1324
VirtualBoxBaseWithChildrenNEXT()
1327
virtual ~VirtualBoxBaseWithChildrenNEXT()
1331
* Lock handle to use when adding/removing child objects from the list of
1332
* children. It is guaranteed that no any other lock is requested in methods
1333
* of this class while holding this lock.
1335
* @warning By default, this simply returns the general object's lock handle
1336
* (see VirtualBoxBase::lockHandle()) which is sufficient for most
1339
virtual RWLockHandle *childrenLock() { return lockHandle(); }
1342
* Adds the given child to the list of dependent children.
1344
* Usually gets called from the child's init() method.
1346
* @note @a aChild (unless it is in InInit state) must be protected by
1347
* VirtualBoxBase::AutoCaller to make sure it is not uninitialized on
1348
* another thread during this method's call.
1350
* @note When #childrenLock() is not overloaded (returns the general object
1351
* lock) and this method is called from under the child's read or
1352
* write lock, make sure the {parent, child} locking order is
1353
* preserved by locking the callee (this object) for writing before
1356
* @param aChild Child object to add (must inherit VirtualBoxBase AND
1357
* implement some interface).
1359
* @note Locks #childrenLock() for writing.
1362
void addDependentChild(C *aChild)
1364
AssertReturnVoid(aChild != NULL);
1365
doAddDependentChild(ComPtr<IUnknown>(aChild), aChild);
1369
* Equivalent to template <class C> void addDependentChild (C *aChild)
1370
* but takes a ComObjPtr<C> argument.
1373
void addDependentChild(const ComObjPtr<C> &aChild)
1375
AssertReturnVoid(!aChild.isNull());
1376
doAddDependentChild(ComPtr<IUnknown>(static_cast<C *>(aChild)), aChild);
1380
* Removes the given child from the list of dependent children.
1382
* Usually gets called from the child's uninit() method.
1384
* Keep in mind that the called (parent) object may be no longer available
1385
* (i.e. may be deleted deleted) after this method returns, so you must not
1386
* call any other parent's methods after that!
1388
* @note Locks #childrenLock() for writing.
1390
* @note @a aChild (unless it is in InUninit state) must be protected by
1391
* VirtualBoxBase::AutoCaller to make sure it is not uninitialized on
1392
* another thread during this method's call.
1394
* @note When #childrenLock() is not overloaded (returns the general object
1395
* lock) and this method is called from under the child's read or
1396
* write lock, make sure the {parent, child} locking order is
1397
* preserved by locking the callee (this object) for writing before
1398
* the child's lock. This is irrelevant when the method is called from
1399
* under this object's VirtualBoxBaseProto::AutoUninitSpan (i.e. in
1400
* InUninit state) since in this case no locking is done.
1402
* @param aChild Child object to remove.
1404
* @note Locks #childrenLock() for writing.
1407
void removeDependentChild(C *aChild)
1409
AssertReturnVoid(aChild != NULL);
1410
doRemoveDependentChild(ComPtr<IUnknown>(aChild));
1414
* Equivalent to template <class C> void removeDependentChild (C *aChild)
1415
* but takes a ComObjPtr<C> argument.
1418
void removeDependentChild(const ComObjPtr<C> &aChild)
1420
AssertReturnVoid(!aChild.isNull());
1421
doRemoveDependentChild(ComPtr<IUnknown>(static_cast<C *>(aChild)));
1426
void uninitDependentChildren();
1428
VirtualBoxBase *getDependentChild(const ComPtr<IUnknown> &aUnk);
1431
void doAddDependentChild(IUnknown *aUnk, VirtualBoxBase *aChild);
1432
void doRemoveDependentChild(IUnknown *aUnk);
1434
typedef std::map<IUnknown*, VirtualBoxBase*> DependentChildren;
1435
DependentChildren mDependentChildren;
1438
////////////////////////////////////////////////////////////////////////////////
1440
////////////////////////////////////////////////////////////////////////////////
1443
/// @todo (dmik) remove after we switch to VirtualBoxBaseNEXT completely
765
////////////////////////////////////////////////////////////////////////////////
1445
769
* Simple template that manages data structure allocation/deallocation
1446
770
* and supports data pointer sharing (the instance that shares the pointer is
added
removed
src/VBox/Main/include/VirtualBoxBase.h
