CLSCTX

Values from the CLSCTX enumeration are used in activation calls to indicate the execution contexts in which an object is to be run. These values are also used in calls to CoRegisterClassObject to indicate the set of execution contexts in which a class object is to be made available for requests to construct instances.

typedef enum tagCLSCTX 
{ 
    CLSCTX_INPROC_SERVER   = 1, 
    CLSCTX_INPROC_HANDLER  = 2, 
    CLSCTX_LOCAL_SERVER    = 4 
    CLSCTX_REMOTE_SERVER = 16
} CLSCTX; 
#define CLSCTX_SERVER    (CLSCTX_INPROC_SERVER | CLSCTX_LOCAL_SERVER | CLSCTX_REMOTE_SERVER)
#define CLSCTX_ALL       (CLSCTX_INPROC_HANDLER | CLSCTX_SERVER)

Elements

CLSCTX_INPROC_SERVER: The code that creates and manages objects of this class runs in the same process as the caller of the function specifying the class context.
CLSCTX_INPROC_HANDLER: The code that manages objects of this class is an in-process handler. This is a DLL that runs in the client process and implements client-side structures of this class when instances of the class are accessed remotely.
CLSCTX_LOCAL_SERVER: The EXE code that creates and manages objects of this class is loaded in a separate process space (runs on same machine but in a different process).
CLSCTX_REMOTE_SERVER: A remote machine context. The LocalServer32 or LocalService code that creates and manages objects of this class is run on a different machine.

Defined Terms

CLSCTX_SERVER: Indicates server code, whether in-process, local, or remote. This definition ORs CLSCTX_INPROC_SERVER, CLSCTX_LOCAL_SERVER, and CLSCTX_REMOTE_SERVER.
CLSCTX_ALL: Indicates all class contexts. This definition ORs CLSCTX_INPROC_HANDLER and CLSCTX_SERVER.

Remarks

Values from the CLSCTX enumeration are used in activation calls ( CoCreateInstance, CoCreateInstanceEx, CoGetClassObject, etc.) to indicate the preferred execution contexts in-process, local, or remote in which an object is to be run. They are also used in calls to CoRegisterClassObject to indicate the set of execution contexts in which a class object is to be made available for requests to construct instances ( IClassFactory::CreateInstance).

To indicate that more than one context is acceptable, you can string multiple values together with Boolean ORs. The contexts are tried in the order in which they are listed.

The following table shows how other OLE functions and methods that call CoGetClassObject use the CLSCTX values:

Function Called

Context Flag Used

OleLoad

CLSCTX_INPROC_HANDLER | CLSCTX_INPROC_SERVER
Putting an OLE object into the loaded state requires in-process access; but, it doesn’t matter if all of the object’s function is presently available.

IRunnableObject::Run

CLSCTX_INPROC_SERVER | CLSCTX_LOCAL_SERVER
Running an OLE object requires connecting to the full code of the object wherever it is located.

CoUnMarshalInterface

CLSCTX_INPROC_HANDLER
Unmarshaling needs the form of the class designed for remote access.

IMoniker::BindToObject, for a file moniker created through a call to CreateFileMoniker

In this case, uses CLSCTX_SERVER interally to create the instance after calling GetClassFile to determine the class to be instantiated.

The CLSCTX_REMOTE_SERVER value is added to the CLSCTX enumeration for distributed COM. The CLSCTX_SERVER and CLSCTX_ALL constants are further updated to include the CLSCTX_REMOTE_SERVER value.

Given a set of CLSCTX flags, dwClsCtx, the execution context to be used depends on the availability of registered class codes and other parameters according to the following algorithm:

The first part of the processing determines whether CLSCTX_REMOTE SERVER should be specified as follows:

If the call specifies either
1. a) an explicit COSERVERINFO structure indicating a machine different from the current machine, or
2. b) there is no explicit COSERVERINFO structure specified, but the specified class is registered with either the RemoteServerName or ActivateAtStorage named-value.
then CLSCTX_REMOTE_SERVER is implied and is added to dwClsCtx. The second case allows applications written prior to the release of distributed COM to be the configuration of classes for remote activation to be used by client applications available prior to DCOM and the CLSCTX_REMOTE_SERVER flag. The cases in which there would be no explicit COSERVERINFO structure are 1) The value is specified as NULL, or 2) It is not one of the function parameters, as would be the case in calls to CoCreateInstance or CoGetClassObject in existing applications.
If the explicit COSERVERINFO parameter indicates the current machine, CLSCTX_REMOTE_SERVER is removed (if present) from dwClsCtx.

The rest of the processing proceeds by looking at the value(s) of dwClsCtx in the following sequence.

If dwClsCtx includes CLSCTX_REMOTE_SERVER and no COSERVERINFO parameter is specified, if the activation request indicates a persistent state from which to initialize the object (with CoGetInstanceFromFile, CoGetInstanceFromIStorage, or, for a file moniker, in a call to IMoniker::BindToObject) and the class has an ActivateAtStorage sub-key or no class registry information whatsoever, the request to activate and initialize is forwarded to the machine where the persistent state resides. (Refer to the remote activation functions listed in the See Also section for details.)
If dwClsCtx includes CLSCTX_INPROC_SERVER, the class code in the DLL found under the class’s InprocServer32 key is used if this key exists. The class code will run within the same process as the caller.
If dwClsCtx includes CLSCTX_INPROC_HANDLER, the class code in the DLL found under the class’s InprocHandler32 key is used if this key exists. The class code will run within the same process as the caller.
If dwClsCtx includes CLSCTX_LOCAL_SERVER, the class code in the Win32 service found under the class’s LocalService key is used if this key exists. If no Win32 service is specified, but an EXE is specified under that same key, the class code associated with that EXE is used. The class code (in either case) will be run in a separate service process on the same machine as the caller.
If dwClsCtx is set to CLSCTX_REMOTE_SERVER and an additional COSERVERINFO parameter to the function specifies a particular remote machine, a request to activate is forwarded to this remote machine with dwClsCtx modified to be CLSCTX_LOCAL_SERVER. The class code will run in its own process on this specific machine, which must be different from that of the caller.
Finally, if dwClsCtx includes CLSCTX_REMOTE_SERVER and no COSERVERINFO parameter is specified, if a machine name is given under the class’s RemoteServerName named-value, the request to activate is forwarded to this remote machine with dwClsCtx modified to be CLSCTX_LOCAL_SERVER. The class code will run in its own process on this specific machine, which must be different from that of the caller.

Function Called	Context Flag Used
OleLoad	CLSCTX_INPROC_HANDLER \| CLSCTX_INPROC_SERVER Putting an OLE object into the loaded state requires in-process access; but, it doesn’t matter if all of the object’s function is presently available.
IRunnableObject::Run	CLSCTX_INPROC_SERVER \| CLSCTX_LOCAL_SERVER Running an OLE object requires connecting to the full code of the object wherever it is located.
CoUnMarshalInterface	CLSCTX_INPROC_HANDLER Unmarshaling needs the form of the class designed for remote access.
IMoniker::BindToObject, for a file moniker created through a call to CreateFileMoniker	In this case, uses CLSCTX_SERVER interally to create the instance after calling GetClassFile to determine the class to be instantiated.