Core interface wrappers and smart pointers
The Unknown
class wraps the IUnknown
interface, and it’s the base class for all
the COM interface wrapper classes implemented by the Harlinn.Common.Core and Harlinn.Windows
libraries. The Unknown
class is also the base class for the generic ComPtr
smart pointer
template class.
The COM wrapper classes was created to make it simpler to write apps consuming COM interfaces.
The Unknown
implementation details, below, provides a detailed description
of the Unknown
class, but first two example apps. The first implemented using an interface wrapper, the second
working directly with the interfaces. and both apps implementing the same functionality.
The following app uses the Dom::Document
class, which wraps the IXMLDOMDocument
interface from
MSXML,
to load an xml document into a DOM document:
#include <HCCXML.h>
using namespace Harlinn::Common::Core;
using namespace Harlinn::Common::Core::Xml;
void loadDOM( )
{
auto document = Dom::Document::Create( );
document.SetAsync( false );
document.SetValidateOnParse( false );
document.SetResolveExternals( false );
auto success = document.Load( L"stocks.xml" );
if ( success )
{
auto xml = document.Xml( );
wprintf( L"XML DOM loaded from stocks.xml:\n%s\n", xml.c_str() );
}
else
{
auto parserError = document.ParseError( );
auto reason = parserError.Reason( );
wprintf( L"Failed to load DOM from stocks.xml. %s\n", reason.c_str() );
}
}
int main()
{
try
{
ComInitialize init;
loadDOM( );
}
catch ( const std::exception& exc )
{
printf( "Exception: %s", exc.what( ) );
}
}
That was pretty simple, and the only thing that’s COM specific, is the single statement ComInitialize init;
, which ensures that
COM is initialized for the process.
The code below is an example from Microsoft, loadDom.cpp, doing the same thing as the above app:
#include <stdio.h>
#include <tchar.h>
#import <msxml6.dll> raw_interfaces_only
// Macro that calls a COM method returning HRESULT value.
#define CHK_HR(stmt) do { hr=(stmt); if (FAILED(hr)) goto CleanUp; } while(0)
// Macro to verify memory allcation.
#define CHK_ALLOC(p) do { if (!(p)) { hr = E_OUTOFMEMORY; goto CleanUp; } } while(0)
// Macro that releases a COM object if not NULL.
#define SAFE_RELEASE(p) do { if ((p)) { (p)->Release(); (p) = NULL; } } while(0)
// Helper function to create a VT_BSTR variant from a null terminated string.
HRESULT VariantFromString(PCWSTR wszValue, VARIANT &Variant)
{
HRESULT hr = S_OK;
BSTR bstr = SysAllocString(wszValue);
CHK_ALLOC(bstr);
V_VT(&Variant) = VT_BSTR;
V_BSTR(&Variant) = bstr;
CleanUp:
return hr;
}
// Helper function to create a DOM instance.
HRESULT CreateAndInitDOM(IXMLDOMDocument **ppDoc)
{
HRESULT hr = CoCreateInstance(__uuidof(MSXML2::DOMDocument60), NULL, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(ppDoc));
if (SUCCEEDED(hr))
{
// these methods should not fail so don't inspect result
(*ppDoc)->put_async(VARIANT_FALSE);
(*ppDoc)->put_validateOnParse(VARIANT_FALSE);
(*ppDoc)->put_resolveExternals(VARIANT_FALSE);
}
return hr;
}
void loadDOM()
{
HRESULT hr = S_OK;
IXMLDOMDocument *pXMLDom=NULL;
IXMLDOMParseError *pXMLErr = NULL;
BSTR bstrXML = NULL;
BSTR bstrErr = NULL;
VARIANT_BOOL varStatus;
VARIANT varFileName;
VariantInit(&varFileName);
CHK_HR(CreateAndInitDOM(&pXMLDom));
// XML file name to load
CHK_HR(VariantFromString(L"stocks.xml", varFileName));
CHK_HR(pXMLDom->load(varFileName, &varStatus));
if (varStatus == VARIANT_TRUE)
{
CHK_HR(pXMLDom->get_xml(&bstrXML));
printf("XML DOM loaded from stocks.xml:\n%S\n", bstrXML);
}
else
{
// Failed to load xml, get last parsing error
CHK_HR(pXMLDom->get_parseError(&pXMLErr));
CHK_HR(pXMLErr->get_reason(&bstrErr));
printf("Failed to load DOM from stocks.xml. %S\n", bstrErr);
}
CleanUp:
SAFE_RELEASE(pXMLDom);
SAFE_RELEASE(pXMLErr);
SysFreeString(bstrXML);
SysFreeString(bstrErr);
VariantClear(&varFileName);
}
int _tmain(int argc, _TCHAR* argv[])
{
HRESULT hr = CoInitialize(NULL);
if(SUCCEEDED(hr))
{
loadDOM();
CoUninitialize();
}
return 0;
}
That’s a lot of code, mostly dealing with error handling and resource lifetime management.
As demonstrated by the first example, the C++ wrapper classes, and supporting code, removes most the burden imposed on programmers by COM.
Unknown implementation details
The Unknown
class wraps a pointer to the IUnknown
interface ensuring that
the lifetime of the wrapped interfaces are handled properly and efficiently.
unknown_
is the only data member of Unknown
and derived classes
must not add any additional data members, ensuring that Unknown
,
and derived classes, are binary compatible with the raw interface
pointers they wrap.
class Unknown
{
protected:
IUnknown* unknown_;
public:
Unknown
, and every derived class, is required to declare InterfaceType
as the
type of the interface they are implemented for.
using InterfaceType = IUnknown;
Constructors
The default constructor ensures that the internal pointer to IUnknown
is set to nullptr
.
constexpr Unknown( ) noexcept
: unknown_( nullptr )
{ }
Constructs a new Unknown
, taking ownership of the interface pointer held
by unknown
, a pointer to an IUnknown
interface, or an interface derived from IUnknown
.
If addref
is set to true
, this constructor calls AddRef
on the interface pointer held
by unknown
.
explicit Unknown( IUnknown* unknown, bool addref = false ) noexcept
: unknown_( unknown )
{
if ( addref && ( unknown_ != nullptr ) )
{
unknown_->AddRef( );
}
}
Initializes the new object to the interface identified
by the iid
parameter by querying the interface
held by unknown
for the requested interface.
If throwIfNoInterface
is set to false
this prevents the constructor
from throwing an exception if the requested interface is not supported.
Unknown( REFIID iid, const Unknown& unknown, bool throwIfNoInterface = true )
: unknown_( nullptr )
{
if ( unknown )
{
IUnknown* pInterface = nullptr;
auto hr = unknown.unknown_->QueryInterface( iid, (void**)&pInterface );
if ( FAILED( hr ) )
{
if ( throwIfNoInterface == false && hr == E_NOINTERFACE )
{
return;
}
CheckHRESULT( hr );
}
unknown_ = pInterface;
}
}
The copy constructor, calls AddRef
on the interface pointer held
by other
.
Unknown( const Unknown& other ) noexcept
: unknown_( other.unknown_ )
{
if ( unknown_ )
{
unknown_->AddRef( );
}
}
The move constructor takes ownership of the interface pointer held by other
.
Unknown( Unknown&& other ) noexcept
: unknown_( other.unknown_ )
{
if ( unknown_ )
{
other.unknown_ = nullptr;
}
}
The destructor calls Release
on the wrapped interface.
~Unknown( ) noexcept
{
IUnknown* tmp = unknown_;
unknown_ = nullptr;
if ( tmp )
{
tmp->Release( );
}
}
Operators and member functions
constexpr operator bool( ) const noexcept
Returns true
if this object references an interface.
constexpr operator bool( ) const noexcept
{
return unknown_ != nullptr;
}
Unknown& operator = ( const Unknown& other ) noexcept
Copy assignment, which does nothing if other
holds the same interface pointer as this object; and
if not, calls Release
on the currently
held interface pointer, then copying the
interface pointer from other
, calling
AddRef
on the newly assigned interface pointer.
Unknown& operator = ( const Unknown& other ) noexcept
{
if ( unknown_ != other.unknown_ )
{
if ( unknown_ )
{
unknown_->Release( );
}
unknown_ = other.unknown_;
if ( unknown_ )
{
unknown_->AddRef( );
}
}
return *this;
}
Unknown& operator = ( Unknown&& other ) noexcept
Move assignment exchanges the current interface pointer,
with the interface pointer held by other
.
Unknown& operator = ( Unknown&& other ) noexcept
{
std::swap( unknown_, other.unknown_ );
return *this;
}
void swap( Unknown& other ) noexcept
Exchanges the current interface pointer,
with the interface pointer held by other
.
void swap( Unknown& other ) noexcept
{
std::swap( unknown_, other.unknown_ );
}
friend void swap( Unknown& first, Unknown& second ) noexcept
Exchanges the current interface pointers between two
Unknown
objects.
friend void swap( Unknown& first, Unknown& second ) noexcept
{
first.swap( second );
}
void ResetPtr( IUnknown* other = nullptr, bool addRef = false ) noexcept
Calls Release
on the currently held interface pointer
if the interface pointer held by other
points
to a different interface.
if addRef
is true
, and other
is not nullptr
,
ResetPtr
will call AddRef
on the newly
assigned interface pointer.
void ResetPtr( IUnknown* other = nullptr, bool addRef = false ) noexcept
{
if ( unknown_ != other )
{
if ( unknown_ )
{
unknown_->Release( );
}
unknown_ = other;
if ( addRef && ( unknown_ != nullptr ) )
{
unknown_->AddRef( );
}
}
}
Unknown& operator = ( nullptr_t )
Assigning nullptr
to the object, releases the
currently held interface pointer, and sets the
interface pointer to nullptr
.
Unknown& operator = ( nullptr_t )
{
if ( unknown_ )
{
auto tmp = unknown_;
unknown_ = nullptr;
tmp->Release( );
}
return *this;
}
IUnknown* Detach( )
Returns the currently held interface pointer,
setting the interface pointer of the object to
nullptr
.
IUnknown* Detach( )
{
auto tmp = unknown_;
unknown_ = nullptr;
return tmp;
}
T As( ) const
Creates an instance of the interface wrapper class T
, by querying the interface
pointer for the interface type wrapped by T
. Returns an instance of T
,
initialized to the interface wrapped by T
, or nullptr
if the interface is
not supported.
template<typename T>
requires std::is_base_of_v<Unknown, T >
T As( ) const
{
const Unknown& self = *this;
T result( __uuidof(T::InterfaceType), self, false );
return result;
}
bool Is( ) const noexcept
Returns true
if the interface
can successfully be queried for the interface
wrapped by T
.
template<typename T>
requires std::is_base_of_v<Unknown, T>
bool Is( ) const noexcept
{
if ( unknown_ )
{
typename T::InterfaceType* pInterface = nullptr;
auto hr = unknown_->QueryInterface( __uuidof( typename T::InterfaceType ), (void**)&pInterface );
if ( hr == S_OK )
{
pInterface->Release( );
return true;
}
}
return false;
}
ComPtr<T> As( ) const
Creates an instance of the interface smart pointer ComPtr<T>
for the interface T
, by querying the interface
pointer for the interface type T
. Returns an instance of the interface smart pointer
ComPtr<T>
for the interface T
, or nullptr
if the interface is not supported.
template<typename T>
requires std::is_base_of_v<IUnknown, T>
ComPtr<T> As( ) const
{
ComPtr<T> result;
if ( unknown_ )
{
T* pInterface = nullptr;
auto hr = unknown_->QueryInterface( __uuidof( T ), (void**)&pInterface );
if ( hr == S_OK )
{
result.ResetPtr( pInterface );
}
}
return result;
}
bool Is( ) const noexcept
This function can be used to detect if an object supports a particular COM interface
derived from IUnknown
. Returns true if the interface is supported, otherwise false.
If the object does not hold a pointer to a COM interface, this function returns false
.
template<typename T>
requires std::is_base_of_v<IUnknown, T>
bool Is( ) const noexcept
{
if ( unknown_ )
{
T* pInterface = nullptr;
auto hr = unknown_->QueryInterface( __uuidof( T ), (void**)&pInterface );
if ( hr == S_OK )
{
pInterface->Release( );
return true;
}
}
return false;
}
T* GetInterfacePointer( ) const noexcept
Retrieves a pointer to the interface wrapped by this object.
template<typename T = IUnknown>
T* GetInterfacePointer( ) const noexcept
{
return reinterpret_cast<T*>( unknown_ );
}
bool QueryInterface( REFIID riid, void** itf ) const
Queries a COM object for a pointer to one of its interface; identifying the interface by a reference to its interface identifier (IID).
Returns true
if the query succeeded, otherwise false
.
bool QueryInterface( REFIID riid, void** itf ) const
{
auto hr = unknown_->QueryInterface( riid, itf );
if ( hr == S_OK )
{
return true;
}
else
{
if ( hr != E_NOINTERFACE )
{
CheckHRESULT( hr, unknown_ );
}
*itf = nullptr;
return false;
}
}
bool QueryInterface( T** itf ) const
Queries the interface for an interface pointer of type T.
Returns true
if the query succeeded, otherwise false
.
template<typename T>
requires std::is_base_of_v<IUnknown, T>
bool QueryInterface( T** itf ) const
{
return QueryInterface( __uuidof( T ), reinterpret_cast< void** >( itf ) );
}
constexpr bool operator == ( const Unknown& other ) const noexcept
Returns true
if the interface pointer held by this
object is the same as the interface pointer held by the other
object.
constexpr bool operator == ( const Unknown& other ) const noexcept
{
return unknown_ == other.unknown_;
}
constexpr bool operator != ( const Unknown& other ) const noexcept
Returns true
if the interface pointer held by this
object is not the same as the interface pointer held by the other
object.
constexpr bool operator != ( const Unknown& other ) const noexcept
{
return unknown_ != other.unknown_;
}
constexpr bool operator == ( const IUnknown* other ) const noexcept
Returns true
if the interface pointer held by this
object is the same as the interface pointer held by other
.
constexpr bool operator == ( const IUnknown* other ) const noexcept
{
return unknown_ == other;
}
constexpr bool operator != ( const IUnknown* other ) const noexcept
Returns true
if the interface pointer held by this
object is not the same as the interface pointer held by other
.
constexpr bool operator != ( const IUnknown* other ) const noexcept
{
return unknown_ != other;
}
static T CoCreateInstanceFromClassId( const CLSID& clsid, DWORD classContext = CLSCTX_INPROC_SERVER )
Creates and default-initializes a single object of the class associated with a specified CLSID.
template<typename T = Unknown>
requires std::is_base_of_v<Unknown, T>
static T CoCreateInstanceFromClassId( const CLSID& clsid, DWORD classContext = CLSCTX_INPROC_SERVER )
{
typename T::InterfaceType* result = nullptr;
auto hr = CoCreateInstance( clsid, NULL, classContext, __uuidof( typename T::InterfaceType ), (void**)&result );
CheckHRESULT( hr );
return T( result );
}
};