CoGetClassObject

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function provides a pointer to an interface on a class object associated with a specified class identifier. Call CoGetClassObject directly when you want to create multiple objects through a class object whose class identifier is already in the system registry. Most class objects implement the IClassFactory interface. You would then call IClassFactory::CreateInstance to create an uninitialized object. To create a single object on a local machine, use the CoCreateInstance function.

Syntax

STDAPI CoGetClassObject(
  REFCLSID rclsid, 
  WORD dwClsContext, 
  COSERVERINFO* pServerInfo, 
  REFIID riid, 
  LPVOID* ppv
);

Parameters

• rclsid
  [in] Class identifier associated with the data and code that you will use to create the objects.

• dwClsContext
  [in] Specifies the context in which the executable code is to be 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.

• pServerInfo
  [in] Set to NULL.

• riid
  [in] Reference to the identifier of the interface. This identifier will be supplied in ppv on successful return. This interface will be used to communicate with the class object. Typically this value is IID_IClassFactory, although other values – such as IID_IClassFactory2 which supports a form of licensing – are allowed. All OLE-defined interface IIDs are defined in the OLE header files as **IID_**interfacename, where interfacename is the name of the interface.

• 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

A class object in OLE is an intermediate object that supports an interface that permits operations common to a group of objects. The objects in this group are instances derived from the same object definition represented by a single class identifier. Usually, the interface implemented on a class object is IClassFactory, through which you can create object instances of a given definition (class).

A call to CoGetClassObject creates, initializes, and gives the caller access to the class object through a pointer to an interface specified with the riid parameter. The class object is the one associated with the class identifier that you specify in the rclsid parameter. The details of how the system locates the associated code and data within a given machine are transparent to the caller, as is the dynamic loading of any code that is not already loaded.

If the class context is CLSCTX_REMOTE_SERVER, indicating remote activation is required, the COSERVERINFO structure provided in the pServerInfo parameter allows you to specify the machine on which the server is located. For information on the algorithm used to locate a remote server when pServerInfo is NULL, refer to the CLSCTX enumeration.

When calling CoCreateInstanceEx or CoGetClassObject with the remote machine name set to the local machine and using the CLSTCTX_REMOTE_SERVER flag, the call fails.

There are two places to find a class identifier for a given class:

• The registry holds an association between class identifiers and file suffixes, and between class identifiers and file signatures for determining the class of an object.
• The object store holds the class identifier when an object is saved to persistent storage.

To create and initialize embedded or linked OLE document objects, it is not necessary to call CoGetClassObject directly. Instead, call one of the OleCreate or OleCreateXXX helper functions. These functions encapsulate the entire object instantiation and initialization process, and call, among other functions, CoGetClassObject.

The riid parameter specifies the interface the client will use to communicate with the class object. In most cases, this interface is IClassFactory. This provides access to the IClassFactory::CreateInstance method, through which the caller can then create an uninitialized object of the kind specified in its implementation. All classes registered in the system with a class identifier must implement IClassFactory.

In rare cases, however, you may want to specify some other interface that defines operations common to a set of objects. For example, in the way OLE implements monikers, the interface on the class object is IParseDisplayName, used to transform the display name of an object into a moniker.

The dwClsContext parameter specifies the execution context, allowing one class identifier to be associated with different pieces of code in different execution contexts. The CLSCTX enumeration, defined in Compobj.h, specifies the available context flags. CoGetClassObject consults (as appropriate for the context indicated) both the registry and the class objects that are currently registered by calling the CoRegisterClassObject function.

To release a class object, use the class object's Release method. The function CoRevokeClassObject is to be used only to remove a class object's class identifier from the system registry.

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

CoCreateInstance
IClassFactory
IClassFactory::CreateInstance
COSERVERINFO

Other Resources

CreateProcess