CoCreateInstance

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function creates on the local system a single uninitialized object of the class associated with a specified class identifier.

Syntax

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

Parameters

• rclsid
  [in] Class identifier associated with the data and code that are 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] Specifies the context in which the code that manages the newly created object will run. The only valid value for this parameter is CLSCTX_INPROC_SERVER. This is from the enumeration CLSCTX. Any other value results in a return value of E_NOTIMPL.

• riid
  [in] 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.

Return Value

One of the values described in the following table is returned.

Remarks

The CoCreateInstance helper function provides a convenient shortcut by connecting to the class object associated with the specified class identifier, creating an uninitialized instance, and releasing the class object. As such, it encapsulates the following functionality.

CoGetClassObject(rclsid, dwClsContext, NULL, IID_IClassFactory, &pCF); 
hresult = pCF->CreateInstance(pUnkOuter, riid, ppvObj) 
pCF->Release(); 

It is convenient to use CoCreateInstance when you need to create only a single instance of an object on the local machine. When you are creating multiple instances, it is more efficient to obtain a pointer to the class object's IClassFactory interface and use its methods as needed. In the latter case, you should use the CoGetClassObject function.

In the CLSCTX enumeration, you can specify the type of server used to manage the object. The constants can be CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, or any combination of these values. The constant CLSCTX_ALL is defined as the combination of all three. For more information about the use of one or a combination of these constants, refer to CLSCTX.

Passing into this function any invalid and, under some circumstances, NULL pointers result in unexpected termination of the application.

To determine whether the platform supports this function, see Determining Supported COM APIs.

Requirements

See Also

Reference

CoGetClassObject
IClassFactory
IUnknown