Share via

CLSCTX (Compact 2013)

  • Article

3/26/2014

This enumeration contains values used in activation calls to indicate the execution contexts of the object.

In calls to CoRegisterClassObject, the CLSCTX enumeration values indicate a set of execution contexts that are available for request when a class object is instantiated.

Syntax

typedef enum tagCLSCTX {
  CLSCTX_INPROC_SERVER = 0x1,
  CLSCTX_INPROC_HANDLER = 0x2,
  CLSCTX_LOCAL_SERVER = 0x4,
  CLSCTX_REMOTE_SERVER = 0x10
} CLSCTX;

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 dynamic-link library (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, which 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 (such as CoCreateInstance, CoCreateInstanceEx, and CoGetClassObject) 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

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 internally 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 the distributed Component Object Model (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 an explicit COSERVERINFO structure indicating a machine different from the current machine, or if there is no explicit COSERVERINFO structure specified, but the specified class is registered with either the RemoteServerName or ActivateAtStorage named value, 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 and (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 computer, CLSCTX_REMOTE_SERVER is removed (if present) from dwClsCtx.

The rest of the processing proceeds by looking at the values of dwClsCtx in the following sequence.

  1. If dwClsCtx includes CLSCTX_REMOTE_SERVER and no COSERVERINFO parameter is specified, and the activation request indicates a persistent state from which to initialize the object (with CoGetInstanceFromFile or CoGetInstanceFromIStorage or, for a file moniker, in a call to IMoniker::BindToObject), and the class has an ActivateAtStorage subkey or no class registry information whatsoever, the request to activate and initialize is forwarded to the computer where the persistent state resides.
  2. 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.
  3. 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.
  4. If dwClsCtx includes CLSCTX_LOCAL_SERVER, the class code in the Microsoft® 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.
  5. 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.
  6. If dwClsCtx includes CLSCTX_REMOTE_SERVER and no COSERVERINFO parameter is specified and a computer name is given under the class's RemoteServerName named value, the request to activate is forwarded to this remote computer with dwClsCtx modified to be CLSCTX_LOCAL_SERVER.
    The class code will run in its own process on this specific computer, which must be different from that of the caller.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Requirements

Header

wtypes.h

See Also

Reference

COM Structures and Enumerations
CoCreateInstance
CoCreateInstanceEx
CoGetClassObject
CoGetInstanceFromFile
CoGetInstanceFromIStorage
CoRegisterClassObject
CoUnmarshalInterface
GetClassFile
IClassFactory::CreateInstance
IMoniker::BindToObject
IRunnableObject::Run
COSERVERINFO