Creating a COM Object

There are several ways to create Component Object Model (COM) objects. The two most common ones used in Microsoft?DirectX?programming are:

• Directly, by passing the object's class identifier (CLSID) to the CoCreateInstance function. The function will create an instance of the object, and it will return a pointer to an interface that you specify.
• Indirectly, by calling a DirectX method or function that creates the object for you. The method creates the object and returns an interface on the object. When you create an object this way, you usually cannot specify which interface should be returned.

Before you create any objects, COM must be initialized by calling the CoInitialize function. If you are creating objects indirectly, the object creation method will handle this task. If you need to create an object with CoCreateInstance, you must call CoInitialize explicitly. When you are finished, COM must be uninitialized by calling CoUninitialize If you make a call to CoInitialize you must match it with a call to CoUninitialize. Typically, applications that need to explicitly initialize COM do so in their startup routine, and they uninitialize COM in their cleanup routine.

To create a new instance of a COM object with CoCreateInstance, you must have the object's CLSID. If this CLSID is publicly available, you will find it in the reference documentation or the appropriate header file. If the CLSID is not publicly available, you cannot create the object directly.

The CoCreateInstance function has five parameters. For the COM objects you will be using with DirectX, you can normally set the parameters as follows

• rclsid. Set this parameter to the CLSID of the object you want to create.
• pUnkOuter. Set this parameter to NULL. It is used only if you are aggregating objects. See Further Information for a discussion of aggregation.
• dwClsContext. Set this parameter to CLSCTX_INPROC_SERVER. This setting indicates that the object is implemented as a dynamic-link library (DLL) and will run as part of your application's process.
• riid. Set this parameter to the interface identifier (IID) of the interface that you would like to have returned. The function will create the object, and it will return the requested interface pointer in the ppv parameter.
• ppv. Set this parameter to the address of a pointer that will be set to the interface specified by riid when the function returns. This variable should be declared as a pointer to the requested interface, and the reference to the pointer in the parameter list should be cast as (LPVOID *).

For example, the following code fragment creates a new instance of the Microsoft DirectPlay?peer object, and returns a pointer to the object's IDirectPlay8Peer interface in the g_pDP variable. If an error occurs, a message box is displayed, and the application terminates.

IDirectPlay8Peer*  g_pDP = NULL;
...
CoInitialize( NULL );
...
hr = CoCreateInstance( CLSID_DirectPlay8, NULL, CLSCTX_INPROC_SERVER,
                         IID_IDirectPlay8Peer, (LPVOID*) &g_pDP );

if( FAILED( hr ) ) 
  {
    MessageBox( NULL, TEXT("Failed Creating IDirectPlay8Peer. "),
                  TEXT("DirectPlay Sample"), MB_OK | MB_ICONERROR );
    return FALSE;
  }
...

Creating an object indirectly is usually much simpler. You pass the object creation method the address of an interface pointer. The method then creates the object and returns an interface pointer. When you create an object indirectly, you typically cannot choose which interface the method will return. However, you can often specify a variety of things about how the object should be created. For example, the following code fragment calls the IDirect3D9::CreateDevice method discussed earlier to create a device object to represent a display adapter. It returns a pointer to the object's IDirect3DDevice9 interface. The first four parameters provide a variety of information needed to create the object, and the fifth parameter receives the interface pointer. See the reference documentation for details.

IDirect3DDevice9 *g_pd3dDevice = NULL;
...
if( FAILED( g_pD3D->CreateDevice(D3DADAPTER_DEFAULT,
                                 3DDEVTYPE_HAL,
                                 hWnd,
                                 D3DCREATE_SOFTWARE_VERTEXPROCESSING,
                                 &d3dpp,
                                 &g_pd3dDevice )))

  return E_FAIL;