CoGetClassObject function (combaseapi.h)
Provides a pointer to an interface on a class object associated with a specified CLSID. CoGetClassObject locates, and if necessary, dynamically loads the executable code required to do this.
Call CoGetClassObject directly to create multiple objects through a class object for which there is a CLSID in the system registry. You can also retrieve a class object from a specific remote computer. Most class objects implement the IClassFactory interface. You would then call CreateInstance to create an uninitialized object. It is not always necessary to go through this process however. To create a single object, call the CoCreateInstanceEx function, which allows you to create an instance on a remote machine. This replaces the CoCreateInstance function, which can still be used to create an instance on a local computer. Both functions encapsulate connecting to the class object, creating the instance, and releasing the class object. Two other functions, CoGetInstanceFromFile and CoGetInstanceFromIStorage, provide both instance creation on a remote system and object activation. There are numerous functions and interface methods whose purpose is to create objects of a single type and provide a pointer to an interface on that object.
Syntax
HRESULT CoGetClassObject(
[in] REFCLSID rclsid,
[in] DWORD dwClsContext,
[in, optional] LPVOID pvReserved,
[in] REFIID riid,
[out] LPVOID *ppv
);
Parameters
[in] rclsid
The CLSID associated with the data and code that you will use to create the objects.
[in] dwClsContext
The context in which the executable code is to be run. To enable a remote activation, include CLSCTX_REMOTE_SERVER. For more information on the context values and their use, see the CLSCTX enumeration.
[in, optional] pvReserved
A pointer to computer on which to instantiate the class object. If this parameter is NULL, the class object is instantiated on the current computer or at the computer specified under the class's RemoteServerName key, according to the interpretation of the dwClsCtx parameter. See COSERVERINFO.
[in] riid
Reference to the identifier of the interface, which 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.
[out] ppv
The address of pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppv contains the requested interface pointer.
Return value
This function can return the following values.
| Return code | Description |
|---|---|
|
Location and connection to the specified class object was successful. |
|
The CLSID is not properly registered. This error can also indicate that the value you specified in dwClsContext is not in the registry. |
|
Either the object pointed to by ppv does not support the interface identified by riid, or the QueryInterface operation on the class object returned E_NOINTERFACE. |
|
There was an error reading the registration database. |
|
Either the in-process DLL or handler DLL was not found (depending on the context). |
|
The executable (.exe) was not found (CLSCTX_LOCAL_SERVER only). |
|
There was a general access failure on load. |
|
There is an error in the executable image. |
|
The executable was launched, but it did not register the class object (and it may have shut down). |
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 CLSID. 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 (through a pointer to an interface specified with the riid parameter) to the class object. The class object is the one associated with the CLSID that you specify in the rclsid parameter. The details of how the system locates the associated code and data within a computer 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 computer 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.
There are two places to find a CLSID for a class:
- The registry holds an association between CLSIDs and file suffixes, and between CLSIDs and file signatures for determining the class of an object.
- When an object is saved to persistent storage, its CLSID is stored with its data.
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 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 CLSID 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 CLSID to be associated with different pieces of code in different execution contexts. The CLSCTX enumeration 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 CLSID from the system registry.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | combaseapi.h (include Objbase.h) |
| Library | Ole32.lib |
| DLL | Ole32.dll |