Win32 API Reference

CoCreateInstance

Creates a single uninitialized object of the specified class. This function is the primary way to create COM objects in an application.

HRESULT CoCreateInstance(

   REFCLSID rclsid,

   LPUNKNOWN pUnkOuter,

   DWORD dwClsContext,

   REFIID riid,

   LPVOID *ppv

);

Parameters

• rclsid: A reference to the CLSID of the object to be created.
• pUnkOuter: If non-NULL, this is a pointer to an aggregating object. If this parameter is NULL, the object is not being created as part of an aggregation.
• dwClsContext: The context in which the executable code that creates the object will be run.
• riid: The IID of the interface to be returned.
• ppv: A pointer to the interface pointer that receives the requested interface for the newly created object.

Return Value

S_OK if the object was successfully created and initialized; otherwise, one of the error codes listed below.

• REGDB_E_CLASSNOTREG: The CLSID is not registered in the system.
• CLASS_E_NOAGGREGATION: This class cannot be created as part of an aggregation.
• E_NOINTERFACE: The specified interface is not supported by this object.

Remarks

This function combines the functionality of CoGetClassObject, creating an object, and the QueryInterface call to obtain the specified interface pointer.

Example

#include <windows.h>
#include <ole2.h>

// Assume IMyObject and MY_OBJECT_CLSID are defined elsewhere

IMyObject *pMyObject = NULL;
HRESULT hr = CoCreateInstance(
    MY_OBJECT_CLSID,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_IMyObject,
    (void **)&pMyObject);

if (SUCCEEDED(hr)) {
    // Use pMyObject...
    pMyObject->Release();
}
            

CoInitializeEx

Initializes the COM library on the current thread and specifies the concurrency model for the thread.

HRESULT CoInitializeEx(

   LPVOID pvReserved,

   DWORD dwCoInit

);

Parameters

• pvReserved: This parameter is reserved and must be NULL.
• dwCoInit: The concurrency model for the current thread. The possible values are:
  • COINIT_APARTMENTTHREADED: Initializes the COM library for use by single-threaded apartment (STA) components.
  • COINIT_MULTITHREADED: Initializes the COM library for use by multithreaded apartment (MTA) components.
  • COINIT_DISABLE_OLE1DDE: Disables DDE for OLE1.
  • COINIT_SPEED_OVER_MEMORY: Specifies that COM should optimize for speed over memory consumption.

Return Value

S_OK if the COM library was successfully initialized for the current thread; S_FALSE if the COM library was already initialized for the current thread; otherwise, one of the error codes listed below.

• RPC_E_CHANGED_MODE: The COM library has already been initialized with a different concurrency model.

Remarks

Every thread that uses the COM library must call CoInitializeEx once before calling any other COM functions. A thread can call CoInitializeEx multiple times, but each successful call must be matched by a corresponding call to CoUninitialize.

Example

#include <windows.h>
#include <ole2.h>

// Initialize COM for single-threaded apartment model
HRESULT hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

if (SUCCEEDED(hr)) {
    // Use COM services...
    CoUninitialize();
}
            

CoUninitialize

Closes the COM library on the current thread, unpacking all previously allocated resources for the thread.

void CoUninitialize(void);

Remarks

CoUninitialize is the counterpart to CoInitializeEx. Each call to CoInitializeEx must be balanced by a call to CoUninitialize. Failure to uninitialize the COM library can lead to resource leaks.

Example

#include <windows.h>
#include <ole2.h>

// ... Initialize COM ...
CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

// ... Use COM services ...

// Uninitialize COM
CoUninitialize();
            

IUnknown Interface

The IUnknown interface is the base interface for all COM interfaces. It provides the core mechanisms for reference counting and querying for other interfaces.

Methods

• QueryInterface: Retrieves pointers to the supported interfaces on an object.
• AddRef: Increments the reference count for the object.
• Release: Decrements the reference count for the object and destroys the object when its reference count reaches zero.

QueryInterface

This method is part of the IUnknown interface. It retrieves pointers to the supported interfaces on an object.

HRESULT QueryInterface(

   REFIID riid,

   LPVOID *ppvObject

);

AddRef

This method is part of the IUnknown interface. It increments the reference count for the object, which ensures that the object remains alive until it is no longer needed.

ULONG AddRef(void);

Release

This method is part of the IUnknown interface. It decrements the reference count for the object. When the reference count reaches zero, the object is destroyed.

ULONG Release(void);