Compartilhar via

Função QueryActCtxW (winbase.h)

  • Artigo

A função QueryActCtxW consulta o contexto de ativação.

Sintaxe

BOOL QueryActCtxW(
  [in]            DWORD  dwFlags,
  [in]            HANDLE hActCtx,
  [in, optional]  PVOID  pvSubInstance,
  [in]            ULONG  ulInfoClass,
  [out]           PVOID  pvBuffer,
  [in, optional]  SIZE_T cbBuffer,
  [out, optional] SIZE_T *pcbWrittenOrRequired
);

Parâmetros

[in] dwFlags

Esse parâmetro deve ser definido como um dos bits de sinalizador a seguir.

Sinalizador Significado
QUERY_ACTCTX_FLAG_USE_ACTIVE_ACTCTX
 QueryActCtxW consulta o contexto de ativação ativo no thread em vez do contexto especificado por hActCtx. Geralmente, esse é o último contexto de ativação passado para ActivateActCtx. Se ActivateActCtx não tiver sido chamado, o contexto de ativação ativo poderá ser o contexto de ativação usado pelo executável do processo atual. Em outros casos, o sistema operacional determina o contexto de ativação ativo. Por exemplo, quando a função de retorno de chamada para um novo thread é chamada, o contexto de ativação ativa pode ser o contexto que estava ativo quando você criou o thread chamando CreateThread.
QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE
 QueryActCtxW interpreta hActCtx como um tipo de dados HMODULE e consulta um contexto de ativação associado a uma DLL ou EXE.

Quando uma DLL ou EXE é carregada, o carregador verifica se há um manifesto armazenado em um recurso. Se o carregador encontrar um recurso RT_MANIFEST com um identificador de recurso definido como ISOLATIONAWARE_MANIFEST_ RESOURCE_ID, o carregador associará o contexto de ativação resultante à DLL ou EXE. Esse é o contexto de ativação que QueryActCtxW consulta quando o sinalizador QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE foi definido.
QUERY_ACTCTX_FLAG_ACTCTX_IS_ADDRESS
 QueryActCtxW interpreta hActCtx como um endereço dentro de uma DLL ou EXE e consulta um contexto de ativação que foi associado à DLL ou EXE. Pode ser qualquer endereço dentro da DLL ou EXE. Por exemplo, o endereço de qualquer função dentro de uma DLL ou EXE ou o endereço de quaisquer dados estáticos, como uma cadeia de caracteres constante.

Quando uma DLL ou EXE é carregada, o carregador verifica se há um manifesto armazenado em um recurso da mesma forma que QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE.

[in] hActCtx

Manipule para o contexto de ativação que está sendo consultado.

[in, optional] pvSubInstance

Índice do assembly ou da combinação de assembly e arquivo no contexto de ativação. O significado do pvSubInstance depende da opção especificada pelo valor do parâmetro ulInfoClass .

Esse parâmetro pode ser nulo.

Opção ulInfoClass Significado
AssemblyDetailedInformationInActivationContext
 Ponteiro para um DWORD que especifica o índice do assembly dentro do contexto de ativação. Esse é o contexto de ativação que o QueryActCtxW consulta.
FileInformationInAssemblyOfAssemblyInActivationContext
 Ponteiro para uma estrutura ACTIVATION_CONTEXT_QUERY_INDEX . Se QueryActCtxW for chamado com essa opção e a função for bem-sucedida, o buffer retornado conterá informações para um arquivo no assembly. Essas informações estão na forma da estrutura ASSEMBLY_FILE_DETAILED_INFORMATION .

[in] ulInfoClass

Esse parâmetro pode ter apenas os valores mostrados na tabela a seguir.

Opção Significado
ActivationContextBasicInformation
1
 Não disponível.
ActivationContextDetailedInformation
2
 Se QueryActCtxW for chamado com essa opção e a função for bem-sucedida, o buffer retornado conterá informações detalhadas sobre o contexto de ativação. Essas informações estão na forma da estrutura ACTIVATION_CONTEXT_DETAILED_INFORMATION .
AssemblyDetailedInformationInActivationContext
3
 Se QueryActCtxW for chamado com essa opção e a função for bem-sucedida, o buffer conterá informações sobre o assembly que tem o índice especificado em pvSubInstance. Essas informações estão na forma da estrutura ACTIVATION_CONTEXT_ASSEMBLY_DETAILED_INFORMATION .
FileInformationInAssemblyOfAssemblyInActivationContext
4
 Informações sobre um arquivo em um dos assemblies no Contexto de Ativação. O parâmetro pvSubInstance deve apontar para uma estrutura ACTIVATION_CONTEXT_QUERY_INDEX . Se QueryActCtxW for chamado com essa opção e a função for bem-sucedida, o buffer retornado conterá informações para um arquivo no assembly. Essas informações estão na forma da estrutura ASSEMBLY_FILE_DETAILED_INFORMATION .
RunlevelInformationInActivationContext
5
 Se QueryActCtxW for chamado com essa opção e a função for bem-sucedida, o buffer conterá informações sobre o nível de execução solicitado do contexto de ativação. Essas informações estão na forma da estrutura ACTIVATION_CONTEXT_RUN_LEVEL_INFORMATION .

Windows Server 2003 e Windows XP: Esse valor não está disponível.
CompatibilityInformationInActivationContext
6
 Se QueryActCtxW for chamado com essa opção e a função for bem-sucedida, o buffer conterá informações sobre o contexto de compatibilidade solicitado. Essas informações estão na forma da estrutura ACTIVATION_CONTEXT_COMPATIBILITY_INFORMATION .

Windows Server 2008 e versões anteriores e Windows Vista e anteriores: Esse valor não está disponível. Essa opção está disponível a partir do Windows Server 2008 R2 e do Windows 7.

[out] pvBuffer

Ponteiro para um buffer que contém as informações retornadas. Esse parâmetro é opcional. Se pvBuffer for nulo, cbBuffer deverá ser zero. Se o tamanho do buffer apontado por pvBuffer for muito pequeno, QueryActCtxW retornará ERROR_INSUFFICIENT_BUFFER e nenhum dado será gravado no buffer. Consulte a seção Comentários para o método que você pode usar para determinar o tamanho necessário do buffer.

[in, optional] cbBuffer

Tamanho do buffer em bytes apontados por pvBuffer. Esse parâmetro é opcional.

[out, optional] pcbWrittenOrRequired

Número de bytes gravados ou obrigatórios. O parâmetro pcbWrittenOrRequired só pode ser NULL quando pvBuffer for NULL. Se pcbWrittenOrRequired não for NULL, ele será preenchido com o número de bytes necessários para armazenar o buffer retornado.

Retornar valor

Se a função for bem-sucedida, ela retornará TRUE. Caso contrário, retornará FALSE.

Essa função define erros que podem ser recuperados chamando GetLastError. Para obter um exemplo, consulte Recuperando o código de Last-Error. Para obter uma lista completa de códigos de erro, consulte Códigos de erro do sistema.

Comentários

O parâmetro cbBuffer especifica o tamanho em bytes do buffer apontado por pvBuffer. Se pvBuffer for NULL, cbBuffer deverá ser 0. O parâmetro pcbWrittenOrRequired só poderá ser NULL se pvBuffer for NULL. Se pcbWrittenOrRequired não for NULL no retorno, ele será preenchido com o número de bytes necessários para armazenar as informações retornadas. Quando os dados de informações retornados são maiores que o buffer fornecido, QueryActCtxW retorna ERROR_INSUFFICIENT_BUFFER e nenhum dado é gravado no buffer apontado por pvBuffer.

O exemplo a seguir mostra o método de chamar primeiro com um buffer pequeno e, em seguida, lembrar se o buffer é muito pequeno.

SIZE_T cbRequired;
PVOID pvData = NULL;
SIZE_T cbAvailable = 0;

if (!QueryActCtxW(..., pvData, cbAvailable, &cbRequired) && (GetLastError()== ERROR_INSUFFICIENT_BUFFER))
{
    // Allocate enough space to store the returned buffer, fail if too small
    if (NULL == (pvData = HeapAlloc(GetProcessHeap(), 0, cbRequired)))
    {
        SetLastError(ERROR_NOT_ENOUGH_MEMORY);
        return FALSE;
    }
    cbAvailable = cbRequired;
    // Try again, this should succeed.
    if (QueryActCtxW(..., pvData, cbAvailable, &cbRequired))
    {
        // Use the returned data in pvData
    }
    HeapFree(GetProcessHeap(), 0, pvData);
    pvData = NULL;
}

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho winbase.h (inclua Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll