Compartilhar via


Enumeração CLSCTX (wtypesbase.h)

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.

  1. 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).
  2. 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:
  1. 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.)
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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

Confira também

BIND_OPTS2

COSERVERINFO

Cocreateinstance

Cocreateinstanceex

Cogetclassobject

CoGetInstanceFromFile

CoGetInstanceFromIStorage

Coregisterclassobject

Criando um objeto por meio de um objeto de classe

IClassActivator::GetClassObject

Localizando um objeto remoto

Registrando um servidor EXE em execução