Modern COM (for C++20)

This library is a header-only lightweight wrapper for utilizing, declaring and implementing of Windows COM interfaces.

Getting Started

This is the code required to define MyObject class that implements two COM interfaces, IFirstInterface and ISecondInterface:

#include <moderncpp/interfaces.h>

class MyObject :
  public belt::com::object<
    MyObject, // our class
    IFirstInterface,  // any number of interfaces
    ISecondInterface> // we implement
{
  // Implement methods of IFirstInterface
  ...
  // Implement methods of ISecondInterface
  ...

  public:
    // MyObject may optionally have non-empty constructor that is
    // allowed to throw exceptions
    MyObject(int a, int b);
};

That's all! AddRef, Release and even QueryInterface methods are automatically generated by the library. The objects of class MyObject may be created on heap, on stack, as singleton or deeply integrated with COM to be automatically constructed via factory objects returned by DllGetClassObject function.

Read further to find out the details!

Features

Supports declaration and implementation of COM interfaces with pure C++ code
Provides automatic generation of QueryInterface, AddRef and Release methods
Supports definition of native C++ classes that implement any number of COM interfaces either directly or through "implementation proxies"
Supports aggregation, objects on stack and singleton objects
Provides interoperability with ATL and serves as a natural upgrade path when upgrading legacy projects that use ATL
Allows classes that implement interfaces to have non-default constructors
Provides the COM "smart pointer" class, which can also be used independently from the rest of the library
Provides compile-time conversion of string GUIDs to GUID, which can be used independently from the rest of the library
Provides various customization points to simplify debugging or extend functionality of the library
Has built-in leak detection mechanism (that can be opted-in per class) to automatically search for leaked COM object references

Requirements

The library requires C++20 and has been tested on Microsoft Visual C++ compiler 19.26.28806 (Visual Studio 2019 16.6.5).

See also FAQ section below for more information.

Installation

The library is header-only and does not require installation. Once brought into the project, the library's include folder should be made visible to the rest of the project.

Documentation

Use the links for fast navigation:

Guid Helpers
Fetching Identifiers
COM Interface Smart Pointer
COM Interface Support
Traits
Object Customization Points
Constructing Objects
Implementing COM DLL Server
Automatic Leak Detection
FAQ

GUID Helpers

In order to support backward compatibility and to simplify migration, the library can fetch interface and class identifiers (GUIDs) attached to classes via Microsoft Visual C++ extension __declspec(uuid("...")).

However, it also provides functions that parse string GUID into GUID structure at compile-time. Those functions are defined in moderncpp/guid.h header and may be used independently from the rest of the library. However, you don't need to include this header if you include any other library's header.

The following functions are defined in the header:

template<size_t N>
constexpr GUID belt::com::make_guid(const char(&str)[N]) { ... }

make_guid converts a passed string ID to GUID. Supports the following formats: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} or XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.

The header also defines a user-defined literal (UDL) _guid, allowing the following code:

constexpr const GUID id = "{AB9A7AF1-6792-4D0A-83BE-8252A8432B45}"_guid;

Fetching Identifiers

To be able to successfully work with interface types, the library must be able to fetch interface ID (as GUID structure) from a type at compile time. By default, it looks for specialization of the following function:

template<class Interface>
constexpr GUID get_guid(Interface *) { ... }

A specialization is found using ADL. If specialization is not found, the default implementation tries to get an ID using Visual C++ extension uuidof(type).

get_guid may also be declared as a public static constexpr member of a class:

class MyClass ...
{
  public:
  static constexpr GUID get_guid() { ... }
};

A specialization of get_guid function is automatically added with BELT_DEFINE_INTERFACE, BELT_DEFINE_CLASS and other macros.

The following function can be used to get GUID from the interface:

template<class Interface>
constexpr GUID get_interface_guid() noexcept;

COM Interface Smart Pointer

#include <moderncpp/com_ptr.h>

This header file provides the following template classes: belt::com::com_ptr and belt::com::ref. For convenience, they are also available in bcom namespace as bcom::ptr and bcom::ref correspondingly.

`bcom::ptr`

template<class Interface>
class com_ptr<Interface>
{
  ...
};

com_ptr takes a single template argument, the interface class itself. The library must be able to fetch an interface ID (IID) from this type.

The following constructors are provided:

Default or null constructors
```
com_ptr();
com_ptr(std::nullptr_t) noexcept;
```
Default-construct or null-construct the smart pointer object. The object becomes empty.
Raw interface pointer constructor
```
com_ptr(Interface *) noexcept;
```
Constructs smart pointer object from a raw interface pointer. Successful construction increments object's usage counter with a call to AddRef method.
Attaching constructor
```
com_ptr(belt::com::attach_t, Interface *);
```
Constructs smart pointer object from a raw interface pointer. DOES NOT call AddRef method. Use a constant object belt::com::attach as a first parameter to constructor.
Other raw pointer constructor
```
template<class OtherInterface>
com_ptr(OtherInterface *punk) noexcept;
```
Constructs smart pointer object from a raw interface pointer to other interface. This constructor checks if Interface and OtherInterface are related:
- If OtherInterface is derived from Interface, a simple static_cast is performed and AddRef is called on Interface.
- Otherwise, an Interface pointer is obtained via QueryInterface.
Reference constructor
```
com_ptr(ref<Interface> p) noexcept;
```
See the bcom::ref class below.
Copy constructor
```
com_ptr(const com_ptr &) noexcept;
```
Move constructor
```
com_ptr(com_ptr &&) noexcept;
```
Other smart pointer copy constructor
```
template<class OtherInterface>
com_ptr(const com_ptr<OtherInterface> &punk) noexcept;
```
Copy constructor from other smart pointer type. This constructor checks if Interface and OtherInterface are related:
- If OtherInterface is derived from Interface, a simple static_cast is performed and AddRef is called on Interface.
- Otherwise, an Interface pointer is obtained via QueryInterface.
Other smart pointer move constructor
```
template<class OtherInterface>
com_ptr(com_ptr<OtherInterface> &&punk) noexcept;
```
Move constructor from other smart pointer type. This constructor checks if Interface and OtherInterface are related:
- If OtherInterface is derived from Interface, no calls to AddRef and Release are made.
- Otherwise, an Interface pointer is obtained via QueryInterface.

com_ptr also provides a symmetric set of assignment operators.

The following methods are provided:

Method	Description
`explicit operator bool() const noexcept`	Checks if the current smart pointer object not empty
`release() noexcept`	Releases a current interface and empties smart pointer object
`reset() noexcept`	Same as `release`
`Interface *operator ->() const noexcept`	Dereferences the current smart pointer object
`bool operator ==(const com_ptr &o) const noexcept`	Checks whether two smart pointer objects are equal
`bool operator !=(const com_ptr &o) const noexcept`	Checks whether two smart pointer objects are not equal
`bool operator <(const com_ptr &o) const noexcept`	Introduces ordering
`void attach(Interface *p) noexcept`	Attaches a raw interface pointer. Asserts if smart pointer object is not empty
`[[nodiscard]] Interface *detach() noexcept`	Detaches the currently stored raw interface pointer
`Interface *get() const noexcept`	Retrieves the currently stored raw interface pointer
`Interface **put() noexcept`	Provides a write access to the stored raw interface pointer. Asserts if the object is not empty
`template<class OtherInterface> auto as() const noexcept`	Constructs another smart pointer object with a given interface type
`template<class OtherInterface> HRESULT QueryInterface(OtherInterface **ppresult) const`	Calls QueryInterface to get raw result
`HRESULT CoCreateInstance(const GUID &clsid, IUnknown *pUnkOuter = nullptr, DWORD dwClsContext = CLSCTX_ALL) noexcept`	Calls `::CoCreateInstance` with provided parameters and stores the result in the current smart pointer object
`HRESULT create_instance(const GUID &clsid, IUnknown *pUnkOuter = nullptr, DWORD dwClsContext = CLSCTX_ALL) noexcept`	Same as `CoCreateInstance`
`static com_ptr create(const GUID &clsid, IUnknown *pUnkOuter = nullptr, DWORD dwClsContext = CLSCTX_ALL)`	Static method that calls `::CoCreateInstance` and returns a smart pointer object if successful. Otherwise throws an instance of `corsl::hresult_error`.

Operators == and != are also provided to any combination of Interface * and const com_ptr<Interface> & pairs.

`bcom::ref`

This class is supposed to be used as a replacement for raw interface pointer in cases when interface pointer is used without adding a reference. Consider the following example:

void serialize(IStream *pStream)
{
  // work with stream object and never store it
  // therefore, we don't have to call AddRef and Release
  ...
}

void foo()
{
  bcom::ptr<IStream> stream { construct_stream() };

  serialize(stream.get());  // have to call get() here
}

serialize function may be rewritten to take an instance of bcom::ref<IStream> instead of a raw pointer. A benefit is additional lifetime checks in debug builds without any overhead in release builds:

void serialize(bcom::ref<IStream> pStream)
{
  // note pStream is passed by value
  // unmodified body of serialize function above
}

void foo()
{
  bcom::ptr<IStream> stream { construct_stream() };

  serialize(stream);  // implicitly construct bcom::ref<IStream> here
}

template<class Interface>
class ref { ... };

bcom::ref takes a single template argument, the interface class itself. The library must be able to fetch an interface ID (IID) from this type.

The following constructors are provided:

Default and null constructors
```
ref() = default;
ref(std::nullptr_t) noexcept;
```
Construct an empty object.
Constructor from a raw pointer
```
ref(Interface *p) noexcept;
```

Constructor from com_ptr<Interface>

ref(const com_ptr<Interface> &o) noexcept;

Constructor from com_ptr<Interface> temporary
```
ref(com_ptr<Interface> &&o) noexcept;
```
This constructor is allowed, however it introduces additional lifetime checks in debug builds, unless the BELT_COM_NO_CHECKED_REFS macro is defined before including the com_ptr.h header.
Constructor from another smart pointer type:
```
template<class OtherInterface>
ref(const com_ptr<OtherInterface> &o) noexcept;
```
This constructor is allowed only if OtherInterface derives from Interface. Otherwise, the code is ill-formed.
Constructor from another smart pointer type temporary:
```
template<class OtherInterface>
ref(com_ptr<OtherInterface> &&o) noexcept;
```
This constructor is allowed only if OtherInterface derives from Interface. Otherwise, the code is ill-formed. Additional lifetime checks are performed in debug builds, unless the BELT_COM_NO_CHECKED_REFS macro is defined before including the com_ptr.h header.
Copy-constructor
```
template<class OtherInterface>
ref(const ref<OtherInterface> &o) noexcept;
```
This constructor is allowed only if OtherInterface derives from Interface. Otherwise, the code is ill-formed.

Assignment operators are prohibited for ref objects.

The same comparison operators are defined for ref class as for com_ptr class.

The following methods are available:

Method	Description
`Interface *operator ->() const noexcept`	Dereferences the current smart pointer object
`Interface *get() const noexcept`	Retrieves the currently stored raw interface pointer
`template<class OtherInterface> auto as() const noexcept`	Constructs another smart pointer object with a given interface type

COM Interface Support

A moderncom/interfaces.h header provides infrastructure for working with COM interfaces in native C++ code.

Declaring Interfaces

The following macros may be used to declare interfaces: {#BELT_DEFINE_INTERFACE}

BELT_DEFINE_INTERFACE(name, guid)
{
  // declare interface members here as normal C++ abstract methods, for example
  virtual int sum(int a, int b) = 0;
};

or

BELT_DEFINE_INTERFACE_BASE(name, baseInterfaceName, guid)
{
  // declare interface members here as normal C++ abstract methods, for example
  virtual int sum(int a, int b) = 0;
};

First macro declares interface name derived from IUnknown and second macro declares interface name derived from baseInterfaceName.

The library is also capable of working with "legacy" interfaces. This basically means that any abstract class that is derived from another legacy interface or IUnknown and for which library can fetch interface id can be directly used by the library.

Implementing Interfaces

Imagine you want to implement a class MyObject that implements two interfaces, IFirstInterface and ISecondInterface. Here's the full class declaration:

#include <moderncpp/interfaces.h>

class __declspec(novtable) MyObject :
  public belt::com::object<
    MyObject,
    IFirstInterface,
    ISecondInterface>
{
  // Implement methods of IFirstInterface
  ...
  // Implement methods of ISecondInterface
  ...
};

Constructing object on heap:

com_ptr<IFirstInterface> construct_object()
{
  return MyObject::create_instance().to_ptr();
}

com_ptr<ISecondInterface> construct_object_second()
{
  return MyObject::create_instance().to_ptr<ISecondInterface>();
}

`object`

object is a variadic template class declared as

template<class Derived, class...Interfaces>
class object;

Derived should be the name of the class that derives from object.

Interfaces is a non-empty list of interfaces the class implements. Every entry in the list must be one of the following:

COM interface class, for which library is able to fetch IID (see above). Must not be IUnknown.
also<SomeInterface>. See below for more information.
eats_all<Derived> class. See below for more information.
aggregates<Derived, OtherInterfaces...>. See below for more information.
A class that derives from intermediate.

Important note: Derived class declaration follows the so-called CRTP pattern and causes the resulting class to effectively derive from all COM interfaces directly or indirectly listed.

object has the following members:

```
using DefaultInterface = unspecified;
```
Returns the "default" (usually first) interface. Never equals IUnknown.
```
IUnknown *GetUnknown() noexcept;
```
Can be used inside or outside of derived class to obtain a direct pointer to IUnknown interface. Does not call AddRef.

virtual HRESULT STDMETHODCALLTYPE QueryInterface(REFIID riid, void **ppvObject) noexcept override;

Implements IUnknown::QueryInterface.

```
template<class...Args> 
static object_holder<unspecified> create_instance(Args &&...args);
```
Static method that should be used to create an instance of Derived class on heap. Arguments, if passed are perfect-forwarded to Derived's constructor. Returns a special wrapper object. See object_holder below.

See also object customization points section below.
```
template<class...Args>
static com_ptr<IUnknown> create_aggregate(IUnknown *pOuterUnknown, Args &&...args);
```
Create new instance of Derived aggregating pOuterUnknown. Derived must has supports_aggregation trait (see below).

Arguments, if passed are perfect-forwarded to Derived's constructor.

See also object customization points section below.
```
template<class OtherInterface = FirstInterface>
com_ptr<OtherInterface> create_copy() const;
```
Creates a copy of the current object (invoking Derived's copy constructor) and queries a copy for a given interface. Derived must derive from OtherInterface or OtherInterface must be IUnknown.
```
auto addref() noexcept;
```
This protected method may be called by Derived class if it needs to explicitly add an object reference.
```
auto release() noexcept;
```
This protected method may be called by Derived class if it needs to explicitly release an object reference.

`also`

also class template should be used whenever Derived implements "legacy" interface that itself derives from another legacy interface. Legacy interfaces are those interfaces that are not declared with BELT_DEFINE_INTERFACE macro.

Consider the following example. IDispatchEx interface is defined in Platform SDK and derives from IDispatch interface. It is a legacy interface. We declare MyClass the following way:

class MyClass :
  public belt::com::object<
    MyObject,
    IDispatchEx>
{
  // Implement IDispatch
  ...
  // Implement IDispatchEx
  ...
};

The generated QueryInterface automatically supports querying for IDispatchEx interface, but does not support querying for IDispatch interface. This example must be fixed in the following way:

class MyClass :
  public belt::com::object<
    MyObject,
    IDispatchEx,
    belt::com::also<IDispatch>>  // fix
{
  // Implement IDispatch
  ...
  // Implement IDispatchEx
  ...
};

If interface is declared using BELT_DEFINE_INTERFACE macro, this fix is not required, even if declared interface derives from "legacy" interface:

BELT_DEFINE_INTERFACE_BASE(IMyDispatch, IDispatch, "{AB9A7AF1-6792-4D0A-83BE-8252A8432B45}")
{
  ...
};

class MyClass :
  public belt::com::object<
    MyObject,
    IMyDispatch>
{
  // Implement IDispatch
  ...
  // Implement IMyDispatch
  ...
};

`eats_all`

One of the QueryInterface customization points is an eats_all<Derived> special entry in interface list. If the class contains this entry, it must implement the following public method:

void *on_eat_all(const IID &id) noexcept
{
  ...
}

If a class supports a given interface, it must obtain a pointer to this interface, call an AddRef method through the obtained pointer and return it, casted to void *. Otherwise, it must return nullptr.

`aggregates`

COM objects may support aggregation. That is, an object may advertise an interface that it does not directly implement. It then "forwards" the query for this particular interface to its class member variable, for example, or obtains the pointer using other ways.

The library supports this scenario with a aggregates<Derived, Interfaces...> entry in interface list. For each aggregate interface listed, the Derived class must implement the following public method:

void *on_query(belt::com::interface_wrapper<ISomeInterface>) noexcept
{
  ...
}

on_query must obtain a pointer to requested interface, call an AddRef method through the obtained pointer and return it, casted to void *:

class MyClass :
  public belt::com::object<
    MyClass,
    IDirectlySupportedInterface,
    belt::com::aggregates<
      MyClass,
      IAggregateInterface
    >
  >
{
  bcom::ptr<ISomeOtherInterface> member { initialize_member() };
  
  // Implement IDirectlySupportedInterface
  ...
  // Implement aggregation
  void *on_query(belt::com::interface_wrapper<IAggregateInterface>) noexcept
  {
    IAggregateInterface *result{};
    member->QueryInterface(&result);
    return result;
  }
};

`intermediate`

It is often convenient to create classes or template classes that provide (partial) implementation of a given interface or interfaces and then use them when implementing final classes.

The library provides a machinery for such "implementation proxy" classes with a help of intermediate class template:

template<class ProxyClass, class...Interfaces>
struct intermediate;

This class template looks similar to object and should be used the same way. However, intermediate does not implement members declared in object.

BELT_DEFINE_INTERFACE(IMyInterface, "{AB9A7AF1-6792-4D0A-83BE-8252A8432B45}")
{
  virtual void Method1() =0;
  virtual void Method2() =0;
};

// Provide a partial implementation of IMyInterface
class MyInterfaceImpl : 
  public belt::com::intermediate<
    MyInterfaceImpl,
    IMyInterface>
{
  // Partially implement Method1
  virtual void Method1() override { ... }
};

// MyClass implements IMyInterface with a help of MyInterfaceImpl:
class MyClass : 
  public belt::com::object<
    MyClass,
    MyInterfaceImpl>
{
  // We still have to implement IMyInterface
  virtual void Method2() override { ... }
};

`object_holder`

object_holder is a temporary object holder class template that is returned by object<Derived, ...>::create_instance method:

template<class T>
class object_holder;

Where T is an unspecified class derived from Derived.

The class has the following members:

```
com_ptr<Derived::DefaultInterface> to_ptr() && noexcept;
```
May only be invoked on temporary object_holder object and "converts" it to com_ptr<Derived::DefaultInterface>.

The object is considered "moved-out" after this method returns.
```
template<class Interface>
com_ptr<Interface> to_ptr() && noexcept;
```
May only be invoked on temporary object_holder object and "converts" it to com_ptr<Interface>. Derived must derive from Interface or Interface must be IUnknown.

The object is considered "moved-out" after this method returns.

Derived *obj() const noexcept;

This special-purpose method is supposed to be used when additional initialization is required on constructed object:

class __declspec(novtable) MyObject :
  public belt::com::object<MyObject, IMyInterface>
{
  public:
    void additional_initialization_method(...);
};

com_ptr<IMyInterface> construct_object()
{
  auto my_object = MyObject::create_instance();
  my_object.obj()->additional_initialization_method();
  return std::move(my_object).to_ptr();
}

Traits

A trait class is a special class that Derived must directly derive from to change various defaults. The following trait classes are available:

singleton_factory
single_cached_instance
supports_aggregation
increments_module_count
enable_leak_detection

Some of these trait classes automatically "propagate" down on inheritance chain. That is, if an implementation proxy class or even an interface class specifies a trait, it will also be present in any derived final class.

`singleton_factory`

When object is constructed using library's default construction mechanism, use the single global instance.

Singleton object is created at the time it is first requested and lives until the program is finished. There is no way to destroy the object before the program ends.

Access to object creation is thread-safe.

`single_cached_instance`

A special case of a singleton. An object is created at the time it is first requested and cached for all subsequent create requests. If the created object's reference count reaches zero, it is destroyed.

Access to object creation and destruction is thread-safe.

`supports_aggregation`

Marks the class as supporting aggregation. A class must be marked so if it is supposed to be used in aggregation (that is, constructed via create_aggregate or via default construction mechanism with non-null pOuterUnknown).

If the class is never to be used in aggregation, you can get more efficient implementation by not including this trait.

`implements_module_count`

Increment global module reference count whenever this class object's is referenced. Can be used in conjunction with DllCanUnloadNow implementation.

`enable_leak_detection`

Turn on leak detection for this class. See Automatic Leak Detection section for more information.

Object Customization Points

Customization points allow the class to execute additional code at various object lifetime events. They are all completely optional.

A customization point is a public method declared in the Derived class. The following customization points are supported:

final_construct
final_release
on_add_ref
on_release
pre_query_interface
post_query_interface

`final_construct`

When constructor of the Derived class executes, reference-counting machinery is not yet initialized. Therefore, constructor cannot make any external calls that expect the current object to be a valid COM object.

For such cases, a class may provide the following public method:

template<class ...Args>
HRESULT final_construct(Args &&...args)
{
  ...
}

The final_construct method is invoked when reference-counting machinery is fully initialized. If arguments are present, the user is supposed to pass belt::com::delayed object as a first argument to create_instance or create_aggregate methods and Derived constructor must take no parameters.

final_construct is allowed to throw exceptions or return non-zero error codes. If final_construct returns an error code, an instance of corsl::hresult_error holding this error code is thrown.

`final_release`

Correspondingly, there is a symmetric final_release method. It must have one of the following signatures:

static void final_release(std::unique_ptr<Derived> ptr) noexcept
{
  ...
}

template<class D>
static void final_release(std::unique_ptr<D> ptr) noexcept
{
  ...
}

Note that final_release method is a static member and it takes a unique pointer to the current object in the heap. By default, the object will be destroyed at the end of the final_release method, but the customization is free to do anything it needs with a passed pointer.

The second variant is used with aggregated objects. An implementation may use if constexpr (std::is_same_v<D, Derived>) to check if it is called with an object or aggregate value of the object. In the latter case, it can obtain a pointer to an object itself with by calling the pointed object's get() method:

class MyObject :
  public belt::com::object<
    MyObject,
    ...>,
  public belt::com::supports_aggregation
{
  void ifinal_release()
  {
    ...
  }
public:
  // customization point
  template<class D>
  static void final_release(std::unique_ptr<D> ptr) noexcept
  {
    if constexpr (std::is_same_v<D, MyObject>)
    {
      ptr->ifinal_release();
    } else
    {
      ptr->get()->ifinal_release();
    }
    // Object will auto-destruct here
  }
};

`on_add_ref`

This customization point is invoked each time an object's reference counter is incremented.

void on_add_ref(int new_counter_value);

`on_release`

This customization point is invoked each time an object's reference counter is decremented.

void on_release(int new_counter_value);

`pre_query_interface`

This customization point is invoked before standard QueryInterface machinery:

HRESULT pre_query_interface(REFIID iid, void **ppresult) noexcept;

If method is capable of producing result, it must store it at *ppresult and return S_OK. Otherwise, it must return E_NOINTERFACE. If this method returns any other value, QueryInterface processing immediately stops and the given error code is returned to the caller. In this case, the method must store nullptr at *ppresult.

If successful result is produced, implementation must call AddRef on obtained interface.

`post_query_interface`

This customization point is invoked after standard QueryInterface machinery was unable to find a requested interface:

HRESULT post_query_interface(REFIID iid, void **ppresult) noexcept;

If method is capable of producing result, it must store it at *ppresult and return S_OK. Otherwise, it must store nullptr at *ppresult and return E_NOINTERFACE.

If successful result is produced, implementation must call AddRef on obtained interface.

Constructing Objects

The library provides several ways to construct COM objects:

Simple Construction in the Heap
Simple Construction on the Stack
Default Construction Mechanism

Simple Construction in the Heap

To construct an object of a given class Derived in the heap, call the static method Derived::create_instance, passing any number of arguments for class's constructor.

If the first argument is belt::com::delayed, then the default constructor is used instead and the rest of arguments are passed to the final_construct customization point.

If object construction succeeds, the method returns a proxy object. This proxy object is usually kept temporary and you will immediately invoke its to_ptr() method, optionally passing an interface you want to query from the created object.

Advanced usages of a proxy object are described above in object_holder section.

Note that the class's constructor or final_construct customization point are allowed to throw exceptions.

Simple Construction on the Stack

For short-lived COM objects or for COM objects for which lifetime can be synchronized with a specific scope, you can use stack-based construction:

class MyClass : public belt::com::object<MyClass, IMyInterface> {...};

void bar(bcom::ref<IMyInterface> p)
{
  ...
}

void foo()
{
  belt::com::value_on_stack<MyClass> obj{/* arguments to constructor or final_construct */};
  bar(&obj);
}

AddRef and Release methods for objects constructed on stack are no-op, however, in debug builds the object's destructor will assert if there were unmatched number of calls to AddRef and Release.

Default Construction Mechanism

This generic mechanism for constructing COM objects can be used in cases when the calling code does not know specific implementation class, or for runtime object construction.

First of all, a class that wants to participate in default construction must register itself using one of the following macros:

BELT_OBJ_ENTRY_AUTO(classname)
BELT_OBJ_ENTRY_AUTO2(classguid, classname)

The BELT_OBJ_ENTRY_AUTO macro registers classname class for which library can automatically fetch class ID.

The BELT_OBJ_ENTRY_AUTO2 macro registers classname with a given CLSID:

BELT_OBJ_ENTRY_AUTO2("{FFDBB4B7-8ECB-42FE-BF68-163B1E0829A2}"_guid, MyClass);

As described above, an ability to automatically fetch the class ID means that either get_guid was specialized for the class, or __declspec(uuid("...")) was added to class's declaration.

The library also provides a macro to attach an ID to a class: {#BELT_DEFINE_CLASS}

BELT_DEFINE_CLASS(classGuidName, guid)

or inside a class

class MyClass ... {
public:
  BELT_CLASS_GUID(guid)
};

After the class is registered, instances of this class may be created using one of the following functions:

```
template<class Interface>
HRESULT create_object(const GUID &clsid, const GUID &iid, void **ppv, IUnknown *pOuterUnknown = nullptr) noexcept;
```
Create an instance of a class with a given CLSID and query an interface with a given IID. Pass a non-null pOuterUnknown if you want a created object to be aggregated.

This function never throws. It returns a non-zero error code. If object creation throws an instance of corsl::hresult_error exception, exception's error code is returned. If object creation throws any other exception, E_FAIL is returned.

template<class Interface>
HRESULT create_object(const GUID &clsid, bcom::ptr<Interface> &result, IUnknown *pOuterUnknown = nullptr) noexcept;

The same as above, but automatically takes IID from Interface and fills result on success.

```
template<class Interface>
bcom::ptr<Interface> create_object(const GUID &clsid, IUnknown *pOuterUnknown = nullptr);
```
Directly returns a smart pointer to a given Interface or throws an instance of corsl::hresult_error when object creation fails.

create_object respects the singleton and single cached instance traits when creating objects.

Implementing COM DLL Server

create_object function described above serves as a foundation for implementing DllGetClassObject.

All you need to do to implement DLL COM server is to add the following code to one of your CPP files:

#include <moderncom/library.h>

HRESULT_export CALLBACK DllCanUnloadNow()
{
  return belt::com::DllCanUnloadNow();
}

HRESULT_export CALLBACK DllGetClassObject(REFCLSID rclsid, REFIID riid, LPVOID * ppvObj)
{
  return belt::com::DllGetClassObject(rclsid, riid, ppvObj);
}

Automatic Leak Detection

The library provides a built-in mechanism to search for leaked object references. It not only shows you which objects were leaked, but also provides detailed stack traces for the corresponding leaked AddRef calls!

Leak detection is only enabled in debug builds.

The following pre-requisites must be done in order for the leak detection to work:

Boost.StackTrace library is a dependency. If you cannot use boost, you must disable automatic leak detection by defining the following macro before including any library header:
```
#define BELT_COM_NO_LEAK_DETECTION
```
belt::com::init_leak_detection() function must be called once before using com_ptr class or creating objects.

Note that this function must be called no matter if you actually use automatic leak detection, unless you completely disable leak detection as described above.

This function is empty in release builds.
Classes that you want to participate in leak detection must opt-in by including belt::com::enable_leak_detection trait.

The recommendation is to only enable leak detection for those classes whose object references are found to be leaking.

Once all pre-requisites are met, you should run your program under debugger. Currently, this mechanism does not detect leaked objects, you should use other facilities to detect leaked objects. For example, you can use tools built into Visual Studio or use tracing to find leaked objects. Alternatively, you can combine automatic leak detection with objects constructed on stack, because in debug builds library automatically asserts when destructor for such object is called with mismatched number of calls to AddRef and Release.

Once leaked objects are found, add them to the Watch window in Visual Studio and expand until you find umb_usages member. It will contain a list of stack traces of calls to AddRef that were not matched with corresponding calls to Release.

Limitations

Leak detection is built into com_ptr and object classes and therefore is unable to track calls to AddRef and Release made by other components. In other words, it always assumes that only com_ptr class makes calls to AddRef and Release.
Leak detection does not currently find leaked objects. Once a leaked object is found by other means, it can be viewed in the debugger to see a list of stack traces.

FAQ

How robust is the library?

This library was extracted from mature production code that had been in use for several years. moderncom should be in a good quality to be used in a project of any size.
Why C++20?

The production code this library was extracted from is constantly updated to use latest language features. Initially moderncom required C++17 and some C++20 requirements were added at a later time.
Why Windows and MSVC only?

COM is a Windows technology that is continued to be used even in modern OS components. In fact, the newest WinRT is also based on COM. However, COM can be considered a technology to provide binary inter-connectivity between native components with a stable C++ ABI and therefore, may theoretically be used on other platforms. It can also be used as a way to establish Inversion of Control principles in code.

There are a few Windows bindings in the code that may be relatively easy decoupled from the rest of the code. After that, the library may be used on other platforms to establish a solid connectivity between application components.

This has not been done, however.
What served as inspiration for this library?

The library was initially created as a way to "renovate" old code base that used ATL for COM support. It was inspired by early works by Kenny Kerr on his moderncpp project (which later became C++/WinRT library). The library may share some ideas (but not implementation) with C++/WinRT. It also does not have dependency on WinRT and does not require Windows 10.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
include/moderncom		include/moderncom
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
AUTHORS.md		AUTHORS.md
LICENSE		LICENSE
README.md		README.md
moderncom.sln		moderncom.sln

License

AlexBAV/moderncom

Folders and files

Latest commit

History

Repository files navigation

Modern COM (for C++20)

Getting Started

Features

Requirements

Installation

Documentation

GUID Helpers

Fetching Identifiers

COM Interface Smart Pointer

bcom::ptr

bcom::ref

COM Interface Support

Declaring Interfaces

Implementing Interfaces

object

also

eats_all

aggregates

intermediate

object_holder

Traits

singleton_factory

single_cached_instance

supports_aggregation

implements_module_count

enable_leak_detection