Enumeração CLSCTX (wtypesbase.h)

Artigo
03/08/2023

Valores usados em chamadas de ativação para indicar os contextos de execução nos quais um objeto deve ser executado. Esses valores também são usados em chamadas para CoRegisterClassObject para indicar o conjunto de contextos de execução nos quais um objeto de classe deve ser disponibilizado para solicitações para construir instâncias.

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;

Constantes


`CLSCTX_INPROC_SERVER` Valor: 0x1 O código que cria e gerencia objetos dessa classe é um DLL executado no mesmo processo que o chamador da função que especifica o contexto da classe.
`CLSCTX_INPROC_HANDLER` Valor: 0x2 O código que gerencia objetos desta classe é um manipulador em processo. Essa é uma DLL que é executada no processo do cliente e implementa estruturas do lado do cliente dessa classe quando instâncias da classe são acessadas remotamente.
`CLSCTX_LOCAL_SERVER` Valor: 0x4 O código EXE que cria e gerencia objetos desta classe é executado no mesmo computador, mas carregado em um espaço de processo separado.
`CLSCTX_INPROC_SERVER16` Valor: 0x8 Obsoleto.
`CLSCTX_REMOTE_SERVER` Valor: 0x10 Um contexto remoto. O código LocalServer32 ou LocalService que cria e gerencia objetos dessa classe é executado em um computador diferente.
`CLSCTX_INPROC_HANDLER16` Valor: 0x20 Obsoleto.
`CLSCTX_RESERVED1` Valor: 0x40 Reservado.
`CLSCTX_RESERVED2` Valor: 0x80 Reservado.
`CLSCTX_RESERVED3` Valor: 0x100 Reservado.
`CLSCTX_RESERVED4` Valor: 0x200 Reservado.
`CLSCTX_NO_CODE_DOWNLOAD` Valor: 0x400 Desabilita o download do código do serviço de diretório ou da Internet. Esse sinalizador não pode ser definido ao mesmo tempo que CLSCTX_ENABLE_CODE_DOWNLOAD.
`CLSCTX_RESERVED5` Valor: 0x800 Reservado.
`CLSCTX_NO_CUSTOM_MARSHAL` Valor: 0x1000 Especifique se deseja que a ativação falhe se ela usar marshalling personalizado.
`CLSCTX_ENABLE_CODE_DOWNLOAD` Valor: 0x2000 Habilita o download de código do serviço de diretório ou da Internet. Esse sinalizador não pode ser definido ao mesmo tempo que CLSCTX_NO_CODE_DOWNLOAD.
`CLSCTX_NO_FAILURE_LOG` Valor: 0x4000 O CLSCTX_NO_FAILURE_LOG pode ser usado para substituir o registro em log de falhas em CoCreateInstanceEx. Se ActivationFailureLoggingLevel for criado, os seguintes valores poderão determinar a status do registro em log de eventos: 0 = Registro em log discricionário. Faça logon por padrão, mas os clientes podem substituir especificando CLSCTX_NO_FAILURE_LOG em CoCreateInstanceEx. 1 = Sempre registre todas as falhas, independentemente do que o cliente especificou. 2 = Nunca registre falhas, independentemente do cliente especificado. Se a entrada do Registro estiver ausente, o padrão será 0. Se você precisar controlar os aplicativos do cliente, é recomendável definir esse valor como 0 e gravar o código do cliente para substituir falhas. É altamente recomendável que você não defina o valor como 2. Se o log de eventos estiver desabilitado, será mais difícil diagnosticar problemas.
`CLSCTX_DISABLE_AAA` Valor: 0x8000 Desabilita ativações AAA (Ativar como Ativador) apenas para esta ativação. Esse sinalizador substitui a configuração do sinalizador EOAC_DISABLE_AAA da enumeração EOLE_AUTHENTICATION_CAPABILITIES. Esse sinalizador não pode ser definido ao mesmo tempo que CLSCTX_ENABLE_AAA. Qualquer ativação em que um processo de servidor seria iniciado sob a identidade do chamador é conhecida como ativação AAA (ativação ativada como ativadora). Desabilitar ativações AAA permite que um aplicativo executado em uma conta privilegiada (como LocalSystem) ajude a impedir que sua identidade seja usada para iniciar componentes não confiáveis. Os aplicativos de biblioteca que usam chamadas de ativação devem sempre definir esse sinalizador durante essas chamadas. Isso ajuda a impedir que o aplicativo de biblioteca seja usado em um ataque de segurança de escalonamento de privilégios. Essa é a única maneira de desabilitar ativações AAA em um aplicativo de biblioteca porque o sinalizador EOAC_DISABLE_AAA da enumeração EOLE_AUTHENTICATION_CAPABILITIES é aplicado somente ao processo do servidor e não ao aplicativo de biblioteca. Windows 2000: Não há suporte para esse sinalizador.
`CLSCTX_ENABLE_AAA` Valor: 0x10000 Habilita ativações AAA (Ativar como Ativador) apenas para esta ativação. Esse sinalizador substitui a configuração do sinalizador EOAC_DISABLE_AAA da enumeração EOLE_AUTHENTICATION_CAPABILITIES. Esse sinalizador não pode ser definido ao mesmo tempo que CLSCTX_DISABLE_AAA. Qualquer ativação em que um processo de servidor seria iniciado sob a identidade do chamador é conhecida como ativação AAA (ativação ativada como ativadora). Habilitar esse sinalizador permite que um aplicativo transfira sua identidade para um componente ativado. Windows 2000: Não há suporte para esse sinalizador.
`CLSCTX_FROM_DEFAULT_CONTEXT` Valor: 0x20000 Inicie esta ativação do contexto padrão do apartment atual.
`CLSCTX_ACTIVATE_X86_SERVER` Valor: 0x40000
`CLSCTX_ACTIVATE_32_BIT_SERVER` Ativar ou conectar-se a uma versão de 32 bits do servidor; falhará se um não estiver registrado.
`CLSCTX_ACTIVATE_64_BIT_SERVER` Valor: 0x80000 Ativar ou conectar-se a uma versão de 64 bits do servidor; falhará se um não estiver registrado.
`CLSCTX_ENABLE_CLOAKING` Valor: 0x100000 Quando esse sinalizador é especificado, COM usa o token de representação do thread, se houver, para a solicitação de ativação feita pelo thread. Quando esse sinalizador não é especificado ou se o thread não tem um token de representação, COM usa o token de processo do processo do thread para a solicitação de ativação feita pelo thread. Windows Vista ou posterior: Há suporte para esse sinalizador.
`CLSCTX_APPCONTAINER` Valor: 0x400000 Indica que a ativação é para um contêiner de aplicativo. Nota Esse sinalizador é reservado para uso interno e não se destina a ser usado diretamente do código.
`CLSCTX_ACTIVATE_AAA_AS_IU` Valor: 0x800000 Especifique esse sinalizador para o comportamento de ativação do Usuário Interativo para servidores As-Activator. Um aplicativo da Windows Store de IL médio fortemente nomeado pode usar esse sinalizador para iniciar um servidor COM "Como Ativador" sem um nome forte. Além disso, você pode usar esse sinalizador para associar a uma instância em execução do servidor COM iniciada por um aplicativo da área de trabalho. O cliente deve ser IL Médio, deve ser fortemente nomeado, o que significa que ele tem um SysAppID no token de cliente, não pode estar na sessão 0 e deve ter o mesmo usuário que o usuário da ID da sessão no token de cliente. Se o servidor estiver fora do processo e "Como Ativador", ele iniciará o servidor com o token do usuário de sessão do token de cliente. Esse token não será fortemente nomeado. Se o servidor estiver fora do processo e Executar Como "Usuário Interativo", esse sinalizador não terá efeito. Se o servidor estiver fora do processo e for qualquer outro tipo RunAs, a ativação falhará. Esse sinalizador não tem efeito para servidores em processo. As ativações fora do computador falham quando usam esse sinalizador.
`CLSCTX_RESERVED6` Valor: 0x1000000
`CLSCTX_ACTIVATE_ARM32_SERVER` Valor: 0x2000000
`CLSCTX_PS_DLL` Valor: 0x80000000 Usado para carregar DLLs de Proxy/Stub. Nota Esse sinalizador é reservado para uso interno e não se destina a ser usado diretamente do código.

Comentários

Os valores da enumeração CLSCTX são usados em chamadas de ativação (CoCreateInstance, CoCreateInstanceEx, CoGetClassObject e assim por diante) para indicar os contextos de execução preferenciais (em processo, local ou remoto) em que um objeto deve ser executado. Eles também são usados em chamadas para CoRegisterClassObject para indicar o conjunto de contextos de execução nos quais um objeto de classe deve ser disponibilizado para solicitações para construir instâncias (IClassFactory::CreateInstance).

Para indicar que mais de um contexto é aceitável, você pode combinar vários valores com ORs boolianos. Os contextos são testados na ordem em que estão listados.

Dado um conjunto de sinalizadores CLSCTX , o contexto de execução a ser usado depende da disponibilidade de códigos de classe registrados e outros parâmetros de acordo com o algoritmo a seguir.

Se a chamada especificar um dos seguintes, CLSCTX_REMOTE_SERVER será implícita e será adicionada à lista de sinalizadores:
1. Uma estrutura COSERVERINFO explícita que indica um computador diferente do computador atual.
2. Nenhuma estrutura COSERVERINFO explícita especificada, mas a classe especificada é registrada com o valor do registro RemoteServerName ou ActivateAtStorage .
O segundo caso permite que aplicativos gravados antes da versão do COM distribuído sejam a configuração de classes para ativação remota a serem usadas por aplicativos cliente disponíveis antes do DCOM e do sinalizador CLSCTX_REMOTE_SERVER. Os casos em que não haveria nenhuma estrutura COSERVERINFO explícita são quando o valor é especificado como NULL ou quando não é um dos parâmetros de função (como em chamadas para CoCreateInstance e CoGetClassObject).
Se o parâmetro COSERVERINFO explícito indicar o computador atual, CLSCTX_REMOTE_SERVER será removido se estiver presente.

O restante do processamento prossegue examinando os valores na seguinte sequência:

Se os sinalizadores incluirem CLSCTX_REMOTE_SERVER e nenhum parâmetro COSERVERINFO for especificado e se a solicitação de ativação indicar um estado persistente do qual inicializar o objeto (com CoGetInstanceFromFile, CoGetInstanceFromIStorage ou, para um moniker de arquivo, em uma chamada para IMoniker::BindToObject) e a classe tem um ActivateAtStorage subchave ou nenhuma informação do registro de classe, a solicitação para ativar e inicializar é encaminhada para o computador onde reside o estado persistente. (Consulte as funções de ativação remota listadas na seção Consulte Também para obter detalhes.)
Se os sinalizadores incluirem CLSCTX_INPROC_SERVER, o código de classe na DLL encontrado na chave InprocServer32 da classe será usado se essa chave existir. O código de classe será executado no mesmo processo que o chamador.
Se os sinalizadores incluirem CLSCTX_INPROC_HANDLER, o código de classe na DLL encontrado na chave InprocHandler32 da classe será usado se essa chave existir. O código de classe será executado no mesmo processo que o chamador.
Se os sinalizadores incluirem CLSCTX_LOCAL_SERVER, o código de classe no serviço encontrado na chave LocalService da classe será usado se essa chave existir. Se nenhum serviço for especificado, mas um EXE for especificado sob essa mesma chave, o código de classe associado a esse EXE será usado. O código de classe (em ambos os casos) será executado em um processo de serviço separado no mesmo computador que o chamador.
Se o sinalizador estiver definido como CLSCTX_REMOTE_SERVER e um parâmetro COSERVERINFO adicional para a função especificar um computador remoto específico, uma solicitação para ativar será encaminhada para este computador remoto com sinalizadores modificados para definir como CLSCTX_LOCAL_SERVER. O código de classe será executado em seu próprio processo neste computador específico, que deve ser diferente daquele do chamador.
Por fim, se os sinalizadores incluirem CLSCTX_REMOTE_SERVER e nenhum parâmetro COSERVERINFO for especificado e se um nome de computador for fornecido sob o nome-valor RemoteServerName da classe, a solicitação para ativar será encaminhada para este computador remoto com os sinalizadores modificados para serem definidos como CLSCTX_LOCAL_SERVER. O código de classe será executado em seu próprio processo neste computador específico, que deve ser diferente daquele do chamador.

CLSCTX_ACTIVATE_32_BIT_SERVER e CLSCTX_ACTIVATE_64_BIT_SERVER

As versões de 64 bits do Windows apresentam dois novos sinalizadores: CLSCTX_ACTIVATE_32_BIT_SERVER e CLSCTX_ACTIVATE_64_BIT_SERVER. Em um computador de 64 bits, uma versão de 32 bits e 64 bits do mesmo servidor COM pode coexistir. Quando um cliente solicita uma ativação de um servidor fora do processo, esses sinalizadores CLSCTX permitem que o cliente especifique uma versão de 32 bits ou 64 bits do servidor.

Normalmente, um cliente não se importará se ele usa uma versão de 32 bits ou 64 bits do servidor. No entanto, se o próprio servidor carregar um servidor em processo adicional, ele e o servidor em processo deverão ser de 32 ou 64 bits. Por exemplo, suponha que o cliente queira usar um servidor "A", que, por sua vez, carrega um servidor em processo "B". Se apenas uma versão de 32 bits do servidor "B" estiver disponível, o cliente deverá especificar a versão de 32 bits do servidor "A". Se apenas uma versão de 64 bits do servidor "B" estiver disponível, o cliente deverá especificar a versão de 64 bits do servidor "A".

Um servidor pode especificar sua própria preferência de arquitetura por meio da chave do Registro PreferredServerBitness, mas a preferência do cliente, especificada por meio de um sinalizador CLSCTX_ACTIVATE_32_BIT_SERVER ou CLSCTX_ACTIVATE_64_BIT_SERVER, substituirá a preferência do servidor. Se o cliente não especificar uma preferência, a preferência do servidor será usada.

Se o cliente nem o servidor especificar uma preferência, então:

Se o computador que hospeda o servidor estiver executando o Windows Server 2003 com o Service Pack 1 (SP1) ou um sistema posterior, o COM tentará corresponder a arquitetura do servidor à arquitetura do cliente. Em outras palavras, para um cliente de 32 bits, o COM ativará um servidor de 32 bits, se disponível; caso contrário, ele ativará uma versão de 64 bits do servidor. Para um cliente de 64 bits, o COM ativará um servidor de 64 bits, se disponível; caso contrário, ele ativará um servidor de 32 bits.
Se o computador que hospeda o servidor estiver executando o Windows XP ou o Windows Server 2003 sem O SP1 ou posterior instalado, o COM preferirá uma versão de 64 bits do servidor, se disponível; caso contrário, ele ativará uma versão de 32 bits do servidor.

Se uma enumeração CLSCTX tiver os sinalizadores CLSCTX_ACTIVATE_32_BIT_SERVER e CLSCTX_ACTIVATE_64_BIT_SERVER definidos, ela será inválida e a ativação retornará E_INVALIDARG.

A tabela a seguir mostra os resultados das várias combinações de arquiteturas de cliente e configurações de cliente e arquiteturas de servidor e configurações de servidor.

Os sinalizadores CLSCTX_ACTIVATE_32_BIT_SERVER e CLSCTX_ACTIVATE_64_BIT_SERVER fluem entre os limites do computador. Se o computador que hospeda o servidor estiver executando o Windows de 64 bits, ele honrará esses sinalizadores; caso contrário, ele irá ignorá-los.

	Cliente de 32 bits, sem sinalizador	Cliente de 64 bits, sem sinalizador	Cliente de 32 bits, sinalizador de 32 bits¹	Cliente de 32 bits, sinalizador² de 64 bits	Cliente de 64 bits, sinalizador de 32 bits¹	Cliente de 64 bits, sinalizador² de 64 bits
Servidor de 32 bits, valor de registro do cliente correspondido a 32 bits	Servidor de 32 bits	Consulte ⁸	Servidor de 32 bits	Consulte ⁸	Servidor de 32 bits	Consulte ⁸
Servidor de 32 bits, valor do registro de 32 bits⁴	Servidor de 32 bits	Servidor de 32 bits	Servidor de 32 bits	Consulte ⁸	Servidor de 32 bits	Consulte ⁸
Servidor de 32 bits, valor do registro de 64 bits⁵	Consulte ⁸	Consulte ⁸	Servidor de 32 bits	Consulte ⁸	Servidor de 32 bits	Consulte ⁸
Servidor de 32 bits, sem valor do Registro⁶	Servidor de 32 bits	32/64⁹	Servidor de 32 bits	Consulte ⁸	Servidor de 32 bits	Consulte ⁸
Servidor de 32 bits, sem valor do Registro (antes do Windows Server 2003 com SP1)⁷	32/64⁹	32/64⁹	Servidor de 32 bits	Consulte ⁸	Servidor de 32 bits	Consulte ⁸
Servidor de 64 bits, valor de registro do cliente correspondido à úm	Consulte ⁸	Servidor de 64 bits	Consulte ⁸	Servidor de 64 bits	Consulte ⁸	Servidor de 64 bits
Servidor de 64 bits, valor do registro de 32 bits⁴	Consulte ⁸	Consulte ⁸	Consulte ⁸	Servidor de 64 bits	Consulte ⁸	Servidor de 64 bits
Servidor de 64 bits, valor do registro de 64 bits⁵	Servidor de 64 bits	Servidor de 64 bits	Consulte ⁸	Servidor de 64 bits	Consulte ⁸	Servidor de 64 bits
Servidor de 64 bits, nenhum valor do Registro⁶	32/64¹⁰	Servidor de 64 bits	Consulte ⁸	Servidor de 64 bits	Consulte ⁸	Servidor de 64 bits
Servidor de 64 bits, sem valor do Registro (antes do Windows Server 2003 com SP1)⁷	Servidor de 64 bits	Servidor de 64 bits	Consulte ⁸	Servidor de 64 bits	Consulte ⁸	Servidor de 64 bits

PreferredServerBitnessPreferredServerBitnessPreferredServerBitnessPreferredServerBitnessPreferredServerBitnessPreferredServerBitness

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	wtypesbase.h