CLSCTX enumeration (wtypesbase.h)
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:
|
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:
- An explicit COSERVERINFO structure indicating a machine different from the current computer.
- No explicit COSERVERINFO structure specified but the specified class is registered with either the RemoteServerName or ActivateAtStorage registry value.
- If the explicit COSERVERINFO parameter indicates the current computer, CLSCTX_REMOTE_SERVER is removed if present.
- 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.
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 |
See also
Creating an Object Through a Class Object