CoRegisterClassObject

HRESULT CoRegisterClassObject(clsid, pUnk, grfContext, grfFlags, pdwRegister)

Registers the specified server class factory identified with pUnk with COM in order that it may be connected to by COM Clients. When a server application starts, it creates each class factory it supports and passes them to this function. When a server application exits, it revokes all its registered class objects with CoRevokeClassObject.

Note that an in-process object could call this function to expose a class factory only when the .DLL is already loaded in another process and did not want to expose a class factory until it was loaded for some other reason.

The grfContext flag identifies the execution context of the server and is usually CLSCTX_LOCAL_SERVER. The grfFlags is used to control how connections are made to the class object. Values for this parameter are the following:

typedef enum tagREGCLS
   {
   REGCLS_SINGLEUSE = 0,
   REGCLS_MULTIPLEUSE = 1,
   REGCLS_MULTI_SEPARATE = 2
   } REGCLS;

Value	Description
REGCLS_SINGLEUSE	Once one client has connected to the class object with CoGetClassObject, then the class object should be removed from public view so that no other clients can similarly connect to it; new clients will use a new instance of the class factory, running a new copy of the server application if necessary. Specifying this flag does not affect the responsibility of the server to call CoRevokeClassObject on shutdown.
REGCLS_MULTIPLEUSE	Many CoGetClassObject calls can connect to the same class factory. When a class factory is registered from a local server (grfContext is CLSCTX_LOCAL_SERVER) and grfFlags includes REGCLS_MULTIPLEUSE, then it is the case that the same class factory will be automatically also registered as the in-process server (CLSCTX_IN-PROC_SERVER) for its own process.
REGCLS_MULTI_SEPARATE	The same as REGCLS_MULTIPLEUSE, except that registration as a local server does not automatically also register as an in-process server in that same process (or any other, for that matter).

Thus, registering as

   CLSCTX_LOCAL_SERVER, REGCLS_MULTIPLEUSE

is the equivalent to registering as

   (CLSCTX_INPROC_SERVER | CLSCTX_LOCAL_SERVER), REGCLS_MULTI_SEPARATE

but is different than registering as

   CLSCTX_LOCAL_SERVER, REGCLS_MULTI_SEPARATE.

By using REGCLS_MULTI_SEPARATE, an object implementation can cause different class factories to be used according to whether or not it is being created from within the same process as it is implemented.

The following table summarizes the allowable flag combinations and the registrations that are effected by the various combinations:


___

REGCLS _SINGLEUSE	REGCLS _MULTIPLEUSE	REGCLS _MULTI_SEPARATE	Other
_

CLSCTX_IN- PROC_SERVER	error	In-Process	In-Process	error
CLSCTX_LOCAL _SERVER	Local	In-Process/Local	Just Local	error
Both of the above	error	In-Process/Local	In-Process/Local	error
Other	error	error	error	error

The key difference is in the middle columns and the middle rows. In the REGCLS_MULTIPLEUSE column, they are the same (registers multiple use for both InProc and local); in the REGCLS_MULTI_SEPARATE column, the local server case is local only.

The arguments to this function are as follows:

Argument	Type	Description
rclsid	REFCLSID	The CLSID of the class factory being registered.
pUnk	IUnknown *	The class factory whose availability is being published.
grfContext	DWORD	As in CoGetClassObject.
grfFlags	DWORD	REGCLS values that control the use of the class factory.
pdwRegister	DWORD *	A place at which a token is passed back with which this registration can be revoked in CoRevokeClassObject.

Return Value	Meaning
S_OK	Success.
CO_E_OBJISREG	Error. The indicated class is already registered.
E_OUTOFMEMORY	Memory could not be allocated to service the request.
E_UNEXPECTED	An unknown error occurred.