Making COM error-safe

Classes
class	Confdump::System::Wmi::Win32Error
	Win32 base exception class, usually not thrown directly. More...
class	Confdump::System::Wmi::ComError
	Thrown on COM errors, contains specific information. More...
class	Confdump::System::Wmi::WmiError
	Thrown on WMI errors, contains specific information. More...
class	Confdump::System::Wmi::WmiDiagnostics
	Provides diagnostics for WMI errors. More...
Functions
template<class T >
boost::shared_ptr< T >	Confdump::System::Wmi::guardComObject (T *ptr)
void	Confdump::System::Wmi::throwOnComError (HRESULT hr, QString action)
	Check hr for errors, throw if FAILED()
void	Confdump::System::Wmi::throwOnWmiError (HRESULT hr, QString action, QString element=QString())
	Check hr for errors, throw if FAILED()

---

Detailed Description

The default error handling in COM is horrible: exception-unsafe code, boilerplate error checking snippets everywhere, ... Because we want Confdump to be nice and easy to maintain, the utilities detailed here make it less painful to write correct COM code.

General usage:

• Use guardComObject() to apply RAII to your raw COM pointers
• Use throwOnComError() and throwOnWmiError() for exception-based nearly automatic error handling
• Catch std::runtime_error& somewhere, as the provided COM/WMI exceptions subclass it.

Note:

Microsoft provides a subset of the following as _com_raise_error and _com_error, however it still leaves too much boilerplate code to the caller and their exception class does not inherit from std::exception. They also do not provide meaningful error messages.

---

Function Documentation

template<class T >

boost::shared_ptr<T> Confdump::System::Wmi::guardComObject

(

T *

ptr

)

Wraps a COM object in a shared_ptr that will automatically call Release() on destruction.

See also _com_ptr_t (but my solution is more elegant.)

Typical usage:

 IWhatever *rawObject = 0;
 HRESULT hr = SomeComCall( &rawObject );
 throwOnComError( hr, "call the COM" );
 shared_ptr<IWhatever> object = guardComObject( rawObject );

Definition at line 74 of file Wmi/errors.hpp.

Referenced by Confdump::System::Wmi::WbemServices::execQuery(), Confdump::System::Wmi::WbemQueryIterator::increment(), Confdump::System::Wmi::WbemServices::listAllClasses(), Confdump::System::Win32::ScheduledTask::ScheduledTask(), and Confdump::System::Wmi::throwOnWmiError().

void Confdump::System::Wmi::throwOnComError	(	HRESULT	hr,
		QString	action
	)

Check hr for errors, throw if FAILED()

If this HRESULT is set as FAILED(), throws an exception including the action explanation string.

Parameters:

hr	A HRESULT code obtained from a previous COM call
action	A textual description of the action that failed, worded to match "Failed to <action>"

Exception safety notes for "out" parameters: the COM documentation states that in error cases the called function will clean its own objects up and set these out pointers to NULL. So it's safe for the caller to only take ownership (and cleanup) created objects when the COM call does not throw.

Typical usage:

 HRESULT hr = object->Method( args );
 throwOnComError( hr, "method the object with arg" );
 // Will produce a message "Failed to method the ..." if FAILED( hr )

Exceptions:

ComError

Definition at line 130 of file Wmi/errors.cpp.

Referenced by Confdump::System::Wmi::ComContext::GuardImpl::GuardImpl(), Confdump::System::Win32::ScheduledTask::ScheduledTask(), and Confdump::System::Wmi::throwOnWmiError().

void Confdump::System::Wmi::throwOnWmiError	(	HRESULT	hr,
		QString	action,
		QString	element = QString()
	)

Check hr for errors, throw if FAILED()

This should be called instead of throwOnComError() in WMI code, as it will produce WMI-specific error information. Otherwise, it takes the exact same parameters than its sister function.

Exceptions:

WmiError

Definition at line 92 of file Wmi/errors.cpp.

References Confdump::System::Wmi::guardComObject(), and Confdump::System::Wmi::throwOnComError().

Referenced by Confdump::System::WmiDumper::doListTables(), Confdump::System::WmiDumper::doQueryTable(), Confdump::System::Wmi::WbemServices::execQuery(), Confdump::System::Wmi::WbemQueryIterator::increment(), and Confdump::System::Wmi::WbemServices::listAllClasses().