Função QueryActCtxW (winbase.h)

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.

[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.

[in] ulInfoClass

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

[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