Search guides and the APICtrl K
  1. API reference
  2. System, devices and network

win_com.h

COM on a thread somebody else owns.

#include <sonore/win_com.h>

Design notes

Media Foundation, the endpoint volume and the disc burner are all COM, and every one of them is called from a thread this SDK did not create: a host's UI thread, a sampler's loader, an application's worker. COM's apartment is a property of the THREAD, chosen by whoever initialises it first, and two mistakes are easy to make here:

  • initialising a thread the host already initialised, in the other model. CoInitializeEx answers RPC_E_CHANGED_MODE and changes nothing -- which is correct, and COM is perfectly usable in the apartment that exists. Treating that answer as failure refuses to work on every DAW's UI thread, which is single-threaded by necessity;
  • balancing a call that did not succeed. CoUninitialize after RPC_E_CHANGED_MODE tears down the HOST's apartment, and the host finds out at some later, unrelated call.

So Apartment initialises only if needed, balances only what it initialised, and says whether COM can be used either way. S_FALSE ("already initialised, same model") is a success that must be balanced: it took a reference.

The multithreaded model when the choice is ours, because nothing here pumps messages and none of these objects needs a window. The scope is always the one call: the apartment is gone when the call returns, so the next thing to initialise this thread chooses freely again.

Nothing public is declared here: the header supports the others in its area, and its notes above say how.

↑↓ to move↵ to openEvery public name in the headers, and every guide