Important: |
---|
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This function provides a pointer to an interface on a class object associated with a specified class identifier. Call CoGetClassObjectdirectly 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 IClassFactoryinterface. You would then call IClassFactory::CreateInstanceto create an uninitialized object. To create a single object on a local machine, use the CoCreateInstancefunction.
STDAPI CoGetClassObject( REFCLSID rclsid , WORD dwClsContext , COSERVERINFO * pServerInfo , REFIID riid , LPVOID * ppv );
Parameters
Return Values
One of the values described in the following table is returned.
Value | Description |
---|---|
S_OK | Location and connection to the specified class object was successful. |
REGDB_E_CLASSNOTREG | Class identifier is not properly registered. Can also indicate that the value you specified in dwClsContextis not in the registry. |
E_NOINTERFACE | Either the object pointed to by ppvdoes not support the interface identified by riid, or the QueryInterfaceoperation on the class object returned E_NOINTERFACE. |
REGDB_E_READREGDB | Error reading the registration database. |
CO_E_DLLNOTFOUND | In-process DLL or handler DLL not found (depends on context). |
CO_E_APPNOTFOUND | EXE not found (CLSCTX_LOCAL_SERVER only). |
E_ACCESSDENIED | General access failure (returned from LoadLibraryor CreateProcess). |
CO_E_ERRORINDLL | EXE has error in image. |
CO_E_APPDIDNTREG | EXE was launched, but it did not register class object (may or may not 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 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 CoGetClassObjectcreates, initializes, and gives the caller access (through a pointer to an interface specified with the riidparameter) to the class object. The class object is the one associated with the class identifier that you specify in the rclsidparameter. 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 COSERVERINFOstructure provided in the pServerInfoparameter allows you to specify the machine on which the server is located. For information on the algorithm used to locate a remote server when pServerInfois NULL, refer to the CLSCTXenumeration.
When calling CoCreateInstanceExor CoGetClassObjectwith 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:
To create and initialize embedded or linked OLE document objects, it is not necessary to call CoGetClassObjectdirectly. Instead, call one of the OleCreateor OleCreate Xxxhelper functions. These functions encapsulate the entire object instantiation and initialization process, and call, among other functions, CoGetClassObject.
The riidparameter 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::CreateInstancemethod, 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 dwClsContextparameter specifies the execution context, allowing one class identifier to be associated with different pieces of code in different execution contexts. The CLSCTXenumeration, defined in Compobj.h, specifies the available context flags. CoGetClassObjectconsults (as appropriate for the context indicated) both the registry and the class objects that are currently registered by calling the CoRegisterClassObjectfunction.
To release a class object, use the class object's Releasemethod. The function CoRevokeClassObjectis 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.
Requirements
Runs On | Versions | Defined in | Include | Link to |
---|---|---|---|---|
Windows CE OS | 2.0 and later | Objbase.h |
Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
See Also
CoCreateInstance, CreateProcess, IClassFactory, IClassFactory::CreateInstance, COSERVERINFO