The QueryActCtxW function queries the activation context.

Syntax

BOOL QueryActCtxW(
  __in       DWORD dwFlags,
  __in       HANDLE hActCtx,
  __in       PVOID pvSubInstance,
  __in       ULONG ulInfoClass,
  __out      PVOID pvBuffer,
  __in_opt   SIZE_T cbBuffer,
  __out_opt  SIZE_T *pcbWrittenOrRequired
);

Parameters

dwFlags [in]

This parameter should be set to one of the following flag bits.

Flag	Meaning
QUERY_ACTCTX_FLAG_USE_ACTIVE_ACTCTX	QueryActCtxW queries the activation context active on the thread instead of the context specified by hActCtx. This is usually the last activation context passed to ActivateActCtx. If ActivateActCtx has not been called, the active activation context can be the activation context used by the executable of the current process. In other cases, the operating system determines the active activation context. For example, when the callback function to a new thread is called, the active activation context may be the context that was active when you created the thread by calling CreateThread.
QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE	QueryActCtxW interprets hActCtx as an HMODULE data type and queries an activation context that is associated with a DLL or EXE. When a DLL or EXE is loaded, the loader checks for a manifest stored in a resource. If the loader finds an RT_MANIFEST resource with a resource identifier set to ISOLATIONAWARE_MANIFEST_ RESOURCE_ID, the loader associates the resulting activation context with the DLL or EXE. This is the activation context that QueryActCtxW queries when the QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE flag has been set.
QUERY_ACTCTX_FLAG_ACTCTX_IS_ADDRESS	QueryActCtxW interprets hActCtx as an address within a DLL or EXE and queries an activation context that has been associated with the DLL or EXE. This can be any address within the DLL or EXE. For example, the address of any function within a DLL or EXE or the address of any static data, such as a constant string. When a DLL or EXE is loaded, the loader checks for a manifest stored in a resource in the same way as QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE.

 

hActCtx [in]

Handle to the activation context that is being queried.

pvSubInstance [in]

Index of the assembly, or assembly and file combination, in the activation context. The meaning of the pvSubInstance depends on the option specified by the value of the ulInfoClass parameter.

ulInfoClass Option	Meaning
AssemblyDetailedInformationInActivationContext	Pointer to a DWORD that specifies the index of the assembly within the activation context. This is the activation context that QueryActCtxW queries.
FileInformationInAssemblyOfAssemblyInActivationContext	Pointer to an ACTIVATION_CONTEXT_QUERY_INDEX structure. If QueryActCtxW is called with this option and the function succeeds, the returned buffer contains information for a file in the assembly. This information is in the form of the ASSEMBLY_FILE_DETAILED_INFORMATION structure.

 

ulInfoClass [in]

This parameter can have only the values shown in the following table.

Option	Meaning
ActivationContextBasicInformation 1	Not available.
ActivationContextDetailedInformation 2	If QueryActCtxW is called with this option and the function succeeds, the returned buffer contains detailed information about the activation context. This information is in the form of the ACTIVATION_CONTEXT_DETAILED_INFORMATION structure.
AssemblyDetailedInformationInActivationContext 3	If QueryActCtxW is called with this option and the function succeeds, the buffer contains information about the assembly that has the index specified in pvSubInstance. This information is in the form of the ACTIVATION_CONTEXT_ASSEMBLY_DETAILED_INFORMATION structure.
FileInformationInAssemblyOfAssemblyInActivationContext 4	Information about a file in one of the assemblies in Activation Context. The pvSubInstance parameter must point to an ACTIVATION_CONTEXT_QUERY_INDEX structure. If QueryActCtxW is called with this option and the function succeeds, the returned buffer contains information for a file in the assembly. This information is in the form of the ASSEMBLY_FILE_DETAILED_INFORMATION structure.
RunlevelInformationInActivationContext 5	If QueryActCtxW is called with this option and the function succeeds, the buffer contains information about requested run level of the activation context. This information is in the form of the ACTIVATION_CONTEXT_RUN_LEVEL_INFORMATION structure. Windows Server 2003 and Windows XP/2000:  This value is not available.
CompatibilityInformationInActivationContext 6	If QueryActCtxW is called with this option and the function succeeds, the buffer contains information about requested compatibility context. This information is in the form of the ACTIVATION_CONTEXT_COMPATIBILITY_INFORMATION structure. Windows Server 2008 and earlier, and Windows Vista and earlier:  This value is not available. This option is available beginning with Windows Server 2008 R2 and Windows 7.

 

pvBuffer [out]

Pointer to a buffer that holds the returned information. This parameter is optional. If pvBuffer is null, then cbBuffer must be zero. If the size of the buffer pointed to by pvBuffer is too small, QueryActCtxW returns ERROR_BUFFER_TOO_SMALL and no data is written into the buffer. See the Remarks section for the method you can use to determine the required size of the buffer.

cbBuffer [in, optional]

Size of the buffer in bytes pointed to by pvBuffer. This parameter is optional.

pcbWrittenOrRequired [out, optional]

Number of bytes written or required. The parameter pcbWrittenOrRequired can only be NULL when pvBuffer is NULL. If pcbWrittenOrRequired is non-NULL, it is filled with the number of bytes required to store the returned buffer.

Return Value

If the function succeeds, it returns TRUE. Otherwise, it returns FALSE.

This function sets errors that can be retrieved by calling GetLastError. For an example, see Retrieving the Last-Error Code. For a complete list of error codes, see System Error Codes.

Remarks

The parameter cbBuffer specifies the size in bytes of the buffer pointed to by pvBuffer. If pvBuffer is NULL, then cbBuffer must be 0. The parameter pcbWrittenOrRequired can only be NULL if pvBuffer is NULL. If pcbWrittenOrRequired is non-NULL on return, it is filled with the number of bytes required to store the returned information. When the information data returned is larger than the provided buffer, QueryActCtxW returns ERROR_INSUFFICIENT_BUFFER and no data is written to the buffer pointed to by pvBuffer.

The following example shows the method of calling first with a small buffer and then recalling if the buffer is too small.

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;
}

Requirements

Send comments about this topic to Microsoft

Build date: 12/17/2009