CoGetClassObject - OLE Programmer's Reference (ole.hlp)

CoGetClassObject

Provides the caller with a pointer to an interface on a class object associated with a specified CLSID. The CoGetClassObject function transparently locates, and if necessary, dynamically loads the executable code required to do this.

Call CoGetClassObject when you want to create multiple objects through a class object for which there is a CLSID in the system registry. You would then call IClassFactory::CreateInstance to create an uninitialized object. It is not always necessary to go through this process. To create a single object, call instead the CoCreateInstance function, which encapsulates connecting to the class object, creating the instance, and releasing the class object. OLE also provides many other ways to create an object in the form of numerous helper functions and interface member functions whose function is to create objects of a single type and provide a pointer to an interface on that object.

STDAPI CoGetClassObject(

REFCLSID rclsid,	//CLSID associated with the class object
DWORD dwClsContext,	//Context for running executable code
LPVOID pvReserved,	//Must be NULL
REFIID riid,	//Interface identifier
LPVOID * ppv	//On return, pointer to location of interface pointer
);

Parameters
rclsid

Specifies the CLSID that will associate the correct data and code.

dwClsContext

Specifies the context in which the executable code is to be run. For information on the context values and their use, see the CLSCTX enumeration.

pvReserved

Reserved for future use. Must be NULL.

riid

Specifies the interface to be used to communicate with the class object. This interface is almost always IClassFactory (represented by the riid IID_IClassFactory).
ppv

Points to where the resulting interface pointer is to be stored.

Return Values
S_OK

Location and connection to the specified class object was successful.
REGDB_E_CLASSNOTREG

CLSID is not properly registered.

E_NOINTERFACE

The object pointed to by ppv does not support the interface identified by riid.

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 LoadLib/CreateProcess).

CO_E_ERRORINDLL

EXE has error in image.

CO_E_APPDIDNTREG

EXE was launched, but it didn't register class object (may or may not have shutdown).

E_OUTOFMEMORY

Out of memory.

E_INVALIDARG

One or more arguments are invalid.

E_UNEXPECTED

An unexpected error occurred.

E_NOINTERFACE

The QueryInterface on the class object returned E_NOINTERFACE.

Comments
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 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 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. Details of how code and data are located and associated are transparent to the caller, as is the dynamic loading of associated code not already loaded. There are two places to find a CLSID for a given object definition:

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.

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 member function, through which the caller can then create an uninitialized object of the kind specified in its implementation. All object definitions 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 , defined in COMPOBJ.H, specifies the available context flags. CoGetClassObject consults (as appropriate for the context indicated) both the registration database and the class objects that are currently registered by calling the CoRegisterClassObject function.

See Also
CoRegisterClassObject, CoRevokeClassObject, OleLoad, CLSCTX

More Online Helps

Win32 Programmer's Reference (win32.hlp)
Win32 Multimedia Programmer's Reference (mmedia.hlp)
Microsoft Windows Pen API Programmer's Reference (penapi.hlp)
Microsoft Windows Sockets 2 Reference (sock2.hlp)
Microsoft Windows Telephony API (TAPI) Programmer's Reference (sock2.hlp)
Unix Manual Pages

greatis just4fun network