Función QueryActCtxW (winbase.h)

La función QueryActCtxW consulta el contexto de activación.

Sintaxis

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

Este parámetro debe establecerse en uno de los siguientes bits de marca.

Marca Significado
QUERY_ACTCTX_FLAG_USE_ACTIVE_ACTCTX
QueryActCtxW consulta el contexto de activación activo en el subproceso en lugar del contexto especificado por hActCtx. Este suele ser el último contexto de activación pasado a ActivateActCtx. Si no se ha llamado a ActivateActCtx , el contexto de activación activo puede ser el contexto de activación que usa el ejecutable del proceso actual. En otros casos, el sistema operativo determina el contexto de activación activo. Por ejemplo, cuando se llama a la función de devolución de llamada a un subproceso nuevo, el contexto de activación activo puede ser el contexto que estaba activo al crear el subproceso llamando a CreateThread.
QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE
QueryActCtxW interpreta hActCtx como un tipo de datos HMODULE y consulta un contexto de activación asociado a un archivo DLL o EXE.

Cuando se carga un archivo DLL o EXE, el cargador comprueba si hay un manifiesto almacenado en un recurso. Si el cargador encuentra un recurso de RT_MANIFEST con un identificador de recurso establecido en ISOLATIONAWARE_MANIFEST_ RESOURCE_ID, el cargador asocia el contexto de activación resultante con el archivo DLL o EXE. Este es el contexto de activación que QueryActCtxW consulta cuando se ha establecido la marca de QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE.

QUERY_ACTCTX_FLAG_ACTCTX_IS_ADDRESS
QueryActCtxW interpreta hActCtx como una dirección dentro de un archivo DLL o EXE y consulta un contexto de activación que se ha asociado con el archivo DLL o EXE. Puede ser cualquier dirección dentro del archivo DLL o EXE. Por ejemplo, la dirección de cualquier función dentro de un archivo DLL o EXE o la dirección de cualquier dato estático, como una cadena constante.

Cuando se carga un archivo DLL o EXE, el cargador comprueba si hay un manifiesto almacenado en un recurso de la misma manera que QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE.

[in] hActCtx

Controle el contexto de activación que se está consultando.

[in, optional] pvSubInstance

Índice del ensamblado, o combinación de ensamblados y archivos, en el contexto de activación. El significado de pvSubInstance depende de la opción especificada por el valor del parámetro ulInfoClass .

Este parámetro puede ser null.

UlInfoClass (opción) Significado
AssemblyDetailedInformationInActivationContext
Puntero a un DWORD que especifica el índice del ensamblado dentro del contexto de activación. Este es el contexto de activación que consulta QueryActCtxW .
FileInformationInAssemblyOfAssemblyInActivationContext
Puntero a una estructura de ACTIVATION_CONTEXT_QUERY_INDEX . Si se llama a QueryActCtxW con esta opción y la función se realiza correctamente, el búfer devuelto contiene información para un archivo del ensamblado. Esta información tiene la forma de la estructura ASSEMBLY_FILE_DETAILED_INFORMATION .

[in] ulInfoClass

Este parámetro solo puede tener los valores que se muestran en la tabla siguiente.

Opción Significado
ActivationContextBasicInformation
1
No disponible.
ActivationContextDetailedInformation
2
Si se llama a QueryActCtxW con esta opción y la función se realiza correctamente, el búfer devuelto contiene información detallada sobre el contexto de activación. Esta información tiene la forma de la estructura ACTIVATION_CONTEXT_DETAILED_INFORMATION .
AssemblyDetailedInformationInActivationContext
3
Si se llama a QueryActCtxW con esta opción y la función se realiza correctamente, el búfer contiene información sobre el ensamblado que tiene el índice especificado en pvSubInstance. Esta información tiene la forma de la estructura ACTIVATION_CONTEXT_ASSEMBLY_DETAILED_INFORMATION .
FileInformationInAssemblyOfAssemblyInActivationContext
4
Información sobre un archivo en uno de los ensamblados en contexto de activación. El parámetro pvSubInstance debe apuntar a una estructura de ACTIVATION_CONTEXT_QUERY_INDEX . Si se llama a QueryActCtxW con esta opción y la función se realiza correctamente, el búfer devuelto contiene información para un archivo del ensamblado. Esta información tiene la forma de la estructura ASSEMBLY_FILE_DETAILED_INFORMATION .
RunlevelInformationInActivationContext
5
Si se llama a QueryActCtxW con esta opción y la función se realiza correctamente, el búfer contiene información sobre el nivel de ejecución solicitado del contexto de activación. Esta información tiene la forma de la estructura ACTIVATION_CONTEXT_RUN_LEVEL_INFORMATION .

Windows Server 2003 y Windows XP: Este valor no está disponible.

CompatibilityInformationInActivationContext
6
Si se llama a QueryActCtxW con esta opción y la función se realiza correctamente, el búfer contiene información sobre el contexto de compatibilidad solicitado. Esta información tiene la forma de la estructura ACTIVATION_CONTEXT_COMPATIBILITY_INFORMATION .

Windows Server 2008 y versiones anteriores, y Windows Vista y versiones anteriores: Este valor no está disponible. Esta opción está disponible a partir de Windows Server 2008 R2 y Windows 7.

[out] pvBuffer

Puntero a un búfer que contiene la información devuelta. Este parámetro es opcional. Si pvBuffer es null, cbBuffer debe ser cero. Si el tamaño del búfer al que apunta pvBuffer es demasiado pequeño, QueryActCtxW devuelve ERROR_INSUFFICIENT_BUFFER y no se escribe ningún dato en el búfer. Consulte la sección Comentarios del método que puede usar para determinar el tamaño necesario del búfer.

[in, optional] cbBuffer

Tamaño del búfer en bytes al que apunta pvBuffer. Este parámetro es opcional.

[out, optional] pcbWrittenOrRequired

Número de bytes escritos o necesarios. El parámetro pcbWrittenOrRequired solo puede ser NULL cuando pvBuffer es NULL. Si pcbWrittenOrRequired no es NULL, se rellena con el número de bytes necesarios para almacenar el búfer devuelto.

Valor devuelto

Si la función se ejecuta correctamente, devuelve TRUE. De lo contrario, devuelve FALSE.

Esta función establece errores que se pueden recuperar llamando a GetLastError. Para obtener un ejemplo, consulte Recuperación del código de Last-Error. Para obtener una lista completa de los códigos de error, consulte Códigos de error del sistema.

Comentarios

El parámetro cbBuffer especifica el tamaño en bytes del búfer al que apunta pvBuffer. Si pvBuffer es NULL, cbBuffer debe ser 0. El parámetro pcbWrittenOrRequired solo puede ser NULL si pvBuffer es NULL. Si pcbWrittenOrRequired es distinto de NULL en la devolución, se rellena con el número de bytes necesarios para almacenar la información devuelta. Cuando los datos de información devueltos son mayores que el búfer proporcionado, QueryActCtxW devuelve ERROR_INSUFFICIENT_BUFFER y no se escribe ningún dato en el búfer al que apunta pvBuffer.

En el ejemplo siguiente se muestra el método de llamar primero con un búfer pequeño y, a continuación, recuperar si el búfer es demasiado pequeño.

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 Value
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado winbase.h (incluya Windows.h)
Library Kernel32.lib
Archivo DLL Kernel32.dll