CLSCTX enumeration (wtypesbase.h)

Article
05/24/2022

Values that 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.

Syntax

typedef enum tagCLSCTX {
  CLSCTX_INPROC_SERVER = 0x1,
  CLSCTX_INPROC_HANDLER = 0x2,
  CLSCTX_LOCAL_SERVER = 0x4,
  CLSCTX_INPROC_SERVER16 = 0x8,
  CLSCTX_REMOTE_SERVER = 0x10,
  CLSCTX_INPROC_HANDLER16 = 0x20,
  CLSCTX_RESERVED1 = 0x40,
  CLSCTX_RESERVED2 = 0x80,
  CLSCTX_RESERVED3 = 0x100,
  CLSCTX_RESERVED4 = 0x200,
  CLSCTX_NO_CODE_DOWNLOAD = 0x400,
  CLSCTX_RESERVED5 = 0x800,
  CLSCTX_NO_CUSTOM_MARSHAL = 0x1000,
  CLSCTX_ENABLE_CODE_DOWNLOAD = 0x2000,
  CLSCTX_NO_FAILURE_LOG = 0x4000,
  CLSCTX_DISABLE_AAA = 0x8000,
  CLSCTX_ENABLE_AAA = 0x10000,
  CLSCTX_FROM_DEFAULT_CONTEXT = 0x20000,
  CLSCTX_ACTIVATE_X86_SERVER = 0x40000,
  CLSCTX_ACTIVATE_32_BIT_SERVER,
  CLSCTX_ACTIVATE_64_BIT_SERVER = 0x80000,
  CLSCTX_ENABLE_CLOAKING = 0x100000,
  CLSCTX_APPCONTAINER = 0x400000,
  CLSCTX_ACTIVATE_AAA_AS_IU = 0x800000,
  CLSCTX_RESERVED6 = 0x1000000,
  CLSCTX_ACTIVATE_ARM32_SERVER = 0x2000000,
  CLSCTX_ALLOW_LOWER_TRUST_REGISTRATION,
  CLSCTX_PS_DLL = 0x80000000
} CLSCTX;

Constants


`CLSCTX_INPROC_SERVER` Value: 0x1 The code that creates and manages objects of this class is a DLL that runs in the same process as the caller of the function specifying the class context.
`CLSCTX_INPROC_HANDLER` Value: 0x2 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` Value: 0x4 The EXE code that creates and manages objects of this class runs on same machine but is loaded in a separate process space.
`CLSCTX_INPROC_SERVER16` Value: 0x8 Obsolete.
`CLSCTX_REMOTE_SERVER` Value: 0x10 A remote context. The LocalServer32 or LocalService code that creates and manages objects of this class is run on a different computer.
`CLSCTX_INPROC_HANDLER16` Value: 0x20 Obsolete.
`CLSCTX_RESERVED1` Value: 0x40 Reserved.
`CLSCTX_RESERVED2` Value: 0x80 Reserved.
`CLSCTX_RESERVED3` Value: 0x100 Reserved.
`CLSCTX_RESERVED4` Value: 0x200 Reserved.
`CLSCTX_NO_CODE_DOWNLOAD` Value: 0x400 Disables the downloading of code from the directory service or the Internet. This flag cannot be set at the same time as CLSCTX_ENABLE_CODE_DOWNLOAD.
`CLSCTX_RESERVED5` Value: 0x800 Reserved.
`CLSCTX_NO_CUSTOM_MARSHAL` Value: 0x1000 Specify if you want the activation to fail if it uses custom marshalling.
`CLSCTX_ENABLE_CODE_DOWNLOAD` Value: 0x2000 Enables the downloading of code from the directory service or the Internet. This flag cannot be set at the same time as CLSCTX_NO_CODE_DOWNLOAD.
`CLSCTX_NO_FAILURE_LOG` Value: 0x4000 The CLSCTX_NO_FAILURE_LOG can be used to override the logging of failures in CoCreateInstanceEx. If the ActivationFailureLoggingLevel is created, the following values can determine the status of event logging: 0 = Discretionary logging. Log by default, but clients can override by specifying CLSCTX_NO_FAILURE_LOG in CoCreateInstanceEx. 1 = Always log all failures no matter what the client specified. 2 = Never log any failures no matter what client specified. If the registry entry is missing, the default is 0. If you need to control customer applications, it is recommended that you set this value to 0 and write the client code to override failures. It is strongly recommended that you do not set the value to 2. If event logging is disabled, it is more difficult to diagnose problems.
`CLSCTX_DISABLE_AAA` Value: 0x8000 Disables activate-as-activator (AAA) activations for this activation only. This flag overrides the setting of the EOAC_DISABLE_AAA flag from the EOLE_AUTHENTICATION_CAPABILITIES enumeration. This flag cannot be set at the same time as CLSCTX_ENABLE_AAA. Any activation where a server process would be launched under the caller's identity is known as an activate-as-activator (AAA) activation. Disabling AAA activations allows an application that runs under a privileged account (such as LocalSystem) to help prevent its identity from being used to launch untrusted components. Library applications that use activation calls should always set this flag during those calls. This helps prevent the library application from being used in an escalation-of-privilege security attack. This is the only way to disable AAA activations in a library application because the EOAC_DISABLE_AAA flag from the EOLE_AUTHENTICATION_CAPABILITIES enumeration is applied only to the server process and not to the library application. Windows 2000: This flag is not supported.
`CLSCTX_ENABLE_AAA` Value: 0x10000 Enables activate-as-activator (AAA) activations for this activation only. This flag overrides the setting of the EOAC_DISABLE_AAA flag from the EOLE_AUTHENTICATION_CAPABILITIES enumeration. This flag cannot be set at the same time as CLSCTX_DISABLE_AAA. Any activation where a server process would be launched under the caller's identity is known as an activate-as-activator (AAA) activation. Enabling this flag allows an application to transfer its identity to an activated component. Windows 2000: This flag is not supported.
`CLSCTX_FROM_DEFAULT_CONTEXT` Value: 0x20000 Begin this activation from the default context of the current apartment.
`CLSCTX_ACTIVATE_X86_SERVER` Value: 0x40000
`CLSCTX_ACTIVATE_32_BIT_SERVER` Activate or connect to a 32-bit version of the server; fail if one is not registered.
`CLSCTX_ACTIVATE_64_BIT_SERVER` Value: 0x80000 Activate or connect to a 64 bit version of the server; fail if one is not registered.
`CLSCTX_ENABLE_CLOAKING` Value: 0x100000 When this flag is specified, COM uses the impersonation token of the thread, if one is present, for the activation request made by the thread. When this flag is not specified or if the thread does not have an impersonation token, COM uses the process token of the thread's process for the activation request made by the thread. Windows Vista or later: This flag is supported.
`CLSCTX_APPCONTAINER` Value: 0x400000 Indicates activation is for an app container. Note This flag is reserved for internal use and is not intended to be used directly from your code.
`CLSCTX_ACTIVATE_AAA_AS_IU` Value: 0x800000 Specify this flag for Interactive User activation behavior for As-Activator servers. A strongly named Medium IL Windows Store app can use this flag to launch an "As Activator" COM server without a strong name. Also, you can use this flag to bind to a running instance of the COM server that's launched by a desktop application. The client must be Medium IL, it must be strongly named, which means that it has a SysAppID in the client token, it can't be in session 0, and it must have the same user as the session ID's user in the client token. If the server is out-of-process and "As Activator", it launches the server with the token of the client token's session user. This token won't be strongly named. If the server is out-of-process and RunAs "Interactive User", this flag has no effect. If the server is out-of-process and is any other RunAs type, the activation fails. This flag has no effect for in-process servers. Off-machine activations fail when they use this flag.
`CLSCTX_RESERVED6` Value: 0x1000000
`CLSCTX_ACTIVATE_ARM32_SERVER` Value: 0x2000000
`CLSCTX_PS_DLL` Value: 0x80000000 Used for loading Proxy/Stub DLLs. Note This flag is reserved for internal use and is not intended to be used directly from your code.

Remarks

Values from the CLSCTX enumeration are used in activation calls (CoCreateInstance, CoCreateInstanceEx, CoGetClassObject, and so on) 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 combine multiple values with Boolean ORs. The contexts are tried in the order in which they are listed.

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

If the call specifies one of the following, CLSCTX_REMOTE_SERVER is implied and is added to the list of flags:
1. An explicit COSERVERINFO structure indicating a machine different from the current computer.
2. No explicit COSERVERINFO structure specified but the specified class is registered with either the RemoteServerName or ActivateAtStorage registry value.
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 when the value is specified as NULL or when it is not one of the function parameters (as in calls to CoCreateInstance and CoGetClassObject).
If the explicit COSERVERINFO parameter indicates the current computer, CLSCTX_REMOTE_SERVER is removed if present.

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

If the flags include CLSCTX_REMOTE_SERVER and no COSERVERINFO parameter is specified and 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 subkey or no class registry information whatsoever, the request to activate and initialize is forwarded to the computer where the persistent state resides. (Refer to the remote activation functions listed in the See Also section for details.)
If the flags include 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 the flags include 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 the flags include CLSCTX_LOCAL_SERVER, the class code in the service found under the class's LocalService key is used if this key exists. If no 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 computer as the caller.
If the flag is set to CLSCTX_REMOTE_SERVER and an additional COSERVERINFO parameter to the function specifies a particular remote computer, a request to activate is forwarded to this remote computer with flags modified to set to 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.
Finally, if the flags include CLSCTX_REMOTE_SERVER and no COSERVERINFO parameter is specified and if a computer name is given under the class's RemoteServerName named-value, the request to activate is forwarded to this remote computer with the flags modified to be set to 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.

CLSCTX_ACTIVATE_32_BIT_SERVER and CLSCTX_ACTIVATE_64_BIT_SERVER

The 64-bit versions of Windows introduce two new flags: CLSCTX_ACTIVATE_32_BIT_SERVER and CLSCTX_ACTIVATE_64_BIT_SERVER. On a 64-bit computer, a 32-bit and 64-bit version of the same COM server may coexist. When a client requests an activation of an out-of-process server, these CLSCTX flags allow the client to specify a 32-bit or a 64-bit version of the server.

Usually, a client will not care whether it uses a 32-bit or a 64-bit version of the server. However, if the server itself loads an additional in-process server, then it and the in-process server must both be either 32-bit or 64-bit. For example, suppose that the client wants to use a server "A", which in turn loads an in-process server "B". If only a 32-bit version of server "B" is available, then the client must specify the 32-bit version of server "A". If only a 64-bit version of server "B" is available, then the client must specify the 64-bit version of server "A".

A server can specify its own architecture preference via the PreferredServerBitness registry key, but the client's preference, specified via a CLSCTX_ACTIVATE_32_BIT_SERVER or CLSCTX_ACTIVATE_64_BIT_SERVER flag, will override the server's preference. If the client does not specify a preference, then the server's preference will be used.

If neither the client nor the server specifies a preference, then:

If the computer that hosts the server is running Windows Server 2003 with Service Pack 1 (SP1) or a later system, then COM will try to match the server architecture to the client architecture. In other words, for a 32-bit client, COM will activate a 32-bit server if available; otherwise it will activate a 64-bit version of the server. For a 64-bit client, COM will activate a 64-bit server if available; otherwise it will activate a 32-bit server.
If the computer that hosts the server is running Windows XP or Windows Server 2003 without SP1 or later installed, then COM will prefer a 64-bit version of the server if available; otherwise it will activate a 32-bit version of the server.

If a CLSCTX enumeration has both the CLSCTX_ACTIVATE_32_BIT_SERVER and CLSCTX_ACTIVATE_64_BIT_SERVER flags set, then it is invalid and the activation will return E_INVALIDARG.

The following table shows the results of the various combinations of client architectures and client settings and server architectures and server settings.

The flags CLSCTX_ACTIVATE_32_BIT_SERVER and CLSCTX_ACTIVATE_64_BIT_SERVER flow across computer boundaries. If the computer that hosts the server is running the 64-bit Windows, then it will honor these flags; otherwise it will ignore them.

	32-bit client, no flag	64-bit client, no flag	32-bit client, 32-bit flag¹	32-bit client, 64-bit flag²	64-bit client, 32-bit flag¹	64-bit client, 64-bit flag²
32-bit server, match client registry value³	32-bit server	See ⁸	32-bit server	See ⁸	32-bit server	See ⁸
32-bit server, 32-bit registry value⁴	32-bit server	32-bit server	32-bit server	See ⁸	32-bit server	See ⁸
32-bit server, 64-bit registry value⁵	See ⁸	See ⁸	32-bit server	See ⁸	32-bit server	See ⁸
32-bit server, no registry value⁶	32-bit server	64/32⁹	32-bit server	See ⁸	32-bit server	See ⁸
32-bit server, no registry value (before Windows Server 2003 with SP1)⁷	64/32⁹	64/32⁹	32-bit server	See ⁸	32-bit server	See ⁸
64-bit server, match client registry value³	See ⁸	64-bit server	See ⁸	64-bit server	See ⁸	64-bit server
64-bit server, 32-bit registry value⁴	See ⁸	See ⁸	See ⁸	64-bit server	See ⁸	64-bit server
64-bit server, 64-bit registry value⁵	64-bit server	64-bit server	See ⁸	64-bit server	See ⁸	64-bit server
64-bit server, no registry value⁶	32/64¹⁰	64-bit server	See ⁸	64-bit server	See ⁸	64-bit server
64-bit server, no registry value (before Windows Server 2003 with SP1)⁷	64-bit server	64-bit server	See ⁸	64-bit server	See ⁸	64-bit server

PreferredServerBitness PreferredServerBitness PreferredServerBitness PreferredServerBitness PreferredServerBitness PreferredServerBitness

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	wtypesbase.h