QueryActCtxW function (winbase.h)
The QueryActCtxW function queries the activation context.
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
);
[in] dwFlags
This parameter should be set to one of the following flag bits.
Flag | Meaning |
---|---|
|
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. |
|
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. |
|
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. |
[in] hActCtx
Handle to the activation context that is being queried.
[in, optional] pvSubInstance
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.
This parameter may be null.
ulInfoClass Option | Meaning |
---|---|
|
Pointer to a DWORD that specifies the index of the assembly within the activation context. This is the activation context that QueryActCtxW queries. |
|
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. |
[in] ulInfoClass
This parameter can have only the values shown in the following table.
Option | Meaning |
---|---|
|
Not available. |
|
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. |
|
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. |
|
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. |
|
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: This value is not available. |
|
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. |
[out] pvBuffer
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_INSUFFICIENT_BUFFER 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.
[in, optional] cbBuffer
Size of the buffer in bytes pointed to by pvBuffer. This parameter is optional.
[out, optional] pcbWrittenOrRequired
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.
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.
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;
}
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps only] |
Minimum supported server | Windows Server 2003 [desktop apps only] |
Target Platform | Windows |
Header | winbase.h (include Windows.h) |
Library | Kernel32.lib |
DLL | Kernel32.dll |