CoCreateInstance

Description

Creates a COM object. COM objects provide a wide variety of functionality. The class identifier (CLSID) will tell you which file contains the code that implements the COM object.

Call CoCreateInstance when you want to create only one object on the local system.

To create a single object on a remote system, call the CoCreateInstanceEx function.

To create multiple objects based on a single CLSID, call the CoGetClassObject function.

Syntax

HRESULT CoCreateInstance(
  _In_   REFCLSID rclsid,
  _In_   LPUNKNOWN pUnkOuter,
  _In_   DWORD dwClsContext,
  _In_   REFIID riid,
  _Out_  LPVOID *ppv
);

Parameters

rclsid [in]

The CLSID associated with the data and code that will be used to create the object.

pUnkOuter [in]

If NULL, indicates that the object is not being created as part of an aggregate.

If non-NULL, pointer to the aggregate object's IUnknown interface (the controlling IUnknown).

dwClsContext [in]

Context in which the code that manages the newly created object will run. The values are taken from the enumeration CLSCTX.

riid [in]

A reference to the identifier of the interface to be used to communicate with the object.

ppv [out]

Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppv contains the requested interface pointer. Upon failure, *ppv contains NULL.

Return value

This function can return the following values.

Return code	Description
S_OK	An instance of the specified object class was successfully created.
REGDB_E_CLASSNOTREG	A specified class is not registered in the registration database. Also can indicate that the type of server you requested in the CLSCTX enumeration is not registered or the values for the server types in the registry are corrupt.
CLASS_E_NOAGGREGATION	This class cannot be created as part of an aggregate.
E_NOINTERFACE	The specified class does not implement the requested interface, or the controlling IUnknown does not expose the requested interface.
E_POINTER	The ppv parameter is NULL.

Example

.text:0040100F                 lea     eax, [esp+24h+ppv]
.text:00401013                 push    eax             ; ppv
.text:00401014                 push    offset riid     ; riid
.text:00401019                 push    4               ; dwClsContext
.text:0040101B                 push    0               ; pUnkOuter
.text:0040101D                 push    offset rclsid   ; rclsid
.text:00401022                 call    ds:CoCreateInstance