Функция QueryActCtxW (winbase.h)

  • Статья

Функция QueryActCtxW запрашивает контекст активации.

Синтаксис

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

Для этого параметра следует задать один из следующих битов флага.

Flag Значение
QUERY_ACTCTX_FLAG_USE_ACTIVE_ACTCTX
 QueryActCtxW запрашивает активный контекст активации в потоке, а не контекст, указанный в hActCtx. Обычно это последний контекст активации, передаваемый в ActivateActCtx. Если метод ActivateActCtx не был вызван, активным контекстом активации может быть контекст активации, используемый исполняемым файлом текущего процесса. В других случаях операционная система определяет активный контекст активации. Например, при вызове функции обратного вызова для нового потока активный контекст активации может быть контекстом, который был активен при создании потока путем вызова Метода CreateThread.
QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE
 QueryActCtxW интерпретирует hActCtx как тип данных HMODULE и запрашивает контекст активации, связанный с библиотекой DLL или EXE.

При загрузке библиотеки DLL или EXE загрузчик проверяет наличие манифеста, хранящегося в ресурсе. Если загрузчик находит ресурс RT_MANIFEST с идентификатором ресурса, для которого задано значение ISOLATIONAWARE_MANIFEST_ RESOURCE_ID, загрузчик связывает полученный контекст активации с библиотекой DLL или EXE. Это контекст активации, который QueryActCtxW запрашивает при установке флага QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE.
QUERY_ACTCTX_FLAG_ACTCTX_IS_ADDRESS
 QueryActCtxW интерпретирует hActCtx как адрес в библиотеке DLL или EXE и запрашивает контекст активации, связанный с библиотекой DLL или EXE. Это может быть любой адрес в библиотеке DLL или EXE. Например, адрес любой функции в библиотеке DLL или EXE или адрес любых статических данных, таких как константная строка.

При загрузке библиотеки DLL или EXE загрузчик проверяет наличие манифеста, хранящегося в ресурсе, так же, как и QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE.

[in] hActCtx

Обработка контекста активации, к которому выполняется запрос.

[in, optional] pvSubInstance

Индекс сборки или комбинации сборки и файла в контексте активации. Значение pvSubInstance зависит от параметра, заданного значением параметра ulInfoClass .

Этот параметр может быть равен null.

Параметр ulInfoClass Значение
AssemblyDetailedInformationInActivationContext
 Указатель на DWORD , указывающий индекс сборки в контексте активации. Это контекст активации, который запрашивает QueryActCtxW .
FileInformationInAssemblyOfAssemblyInActivationContext
 Указатель на структуру ACTIVATION_CONTEXT_QUERY_INDEX . Если метод QueryActCtxW вызывается с этим параметром и функция завершается успешно, возвращенный буфер содержит сведения о файле в сборке. Эта информация представлена в виде структуры ASSEMBLY_FILE_DETAILED_INFORMATION .

[in] ulInfoClass

Этот параметр может иметь только значения, показанные в следующей таблице.

Параметр Значение
ActivationContextBasicInformation
1
 Недоступно.
ActivationContextDetailedInformation
2
 Если метод QueryActCtxW вызывается с этим параметром и функция завершается успешно, возвращаемый буфер содержит подробные сведения о контексте активации. Эта информация представлена в виде структуры ACTIVATION_CONTEXT_DETAILED_INFORMATION .
AssemblyDetailedInformationInActivationContext
3
 Если queryActCtxW вызывается с этим параметром и функция завершается успешно, буфер содержит сведения о сборке, индекс которого указан в pvSubInstance. Эта информация представлена в виде структуры ACTIVATION_CONTEXT_ASSEMBLY_DETAILED_INFORMATION .
FileInformationInAssemblyOfAssemblyInActivationContext
4
 Сведения о файле в одной из сборок в контексте активации. Параметр pvSubInstance должен указывать на ACTIVATION_CONTEXT_QUERY_INDEX структуру. Если метод QueryActCtxW вызывается с этим параметром и функция завершается успешно, возвращенный буфер содержит сведения о файле в сборке. Эта информация представлена в виде структуры ASSEMBLY_FILE_DETAILED_INFORMATION .
RunlevelInformationInActivationContext
5
 Если queryActCtxW вызывается с этим параметром и функция завершается успешно, буфер содержит сведения о запрошенном уровне выполнения контекста активации. Эта информация представлена в виде структуры ACTIVATION_CONTEXT_RUN_LEVEL_INFORMATION .

Windows Server 2003 и Windows XP: Это значение недоступно.
CompatibilityInformationInActivationContext
6
 Если queryActCtxW вызывается с этим параметром и функция завершается успешно, буфер содержит сведения о запрошенном контексте совместимости. Эта информация представлена в виде структуры ACTIVATION_CONTEXT_COMPATIBILITY_INFORMATION .

Windows Server 2008 и более ранних версий, а также Windows Vista и более ранних версий: Это значение недоступно. Этот параметр доступен начиная с Windows Server 2008 R2 и Windows 7.

[out] pvBuffer

Указатель на буфер, содержащий возвращаемые сведения. Этот параметр является необязательным. Если pvBuffer имеет значение NULL, то cbBuffer должен быть равен нулю. Если размер буфера, на который указывает pvBuffer , слишком мал, QueryActCtxW возвращает ERROR_INSUFFICIENT_BUFFER и никакие данные не записываются в буфер. Метод, который можно использовать для определения требуемого размера буфера, см. в разделе Примечания.

[in, optional] cbBuffer

Размер буфера в байтах, на который указывает pvBuffer. Этот параметр является необязательным.

[out, optional] pcbWrittenOrRequired

Число записанных или обязательных байтов. Параметр pcbWrittenOrRequired может иметь значение NULL , только если pvBuffer имеет значение NULL. Если pcbWrittenOrRequired имеет значение, отличное от NULL, он заполняется количеством байтов, необходимым для хранения возвращаемого буфера.

Возвращаемое значение

Если функция выполняется успешно, возвращается значение TRUE. В противном случае возвращается значение FALSE.

Эта функция задает ошибки, которые можно получить, вызвав Метод GetLastError. Пример см. в разделе Извлечение кода Last-Error. Полный список кодов ошибок см. в разделе Системные коды ошибок.

Комментарии

Параметр cbBuffer задает размер буфера в байтах, на который указывает pvBuffer. Если pvBuffer имеет значение NULL, то cbBuffer должен иметь значение 0. Параметр pcbWrittenOrRequired может иметь значение NULL , только если pvBuffer имеет значение NULL. Если при возврате pcbWrittenOrRequired имеет значение, отличное от NULL , оно заполняется количеством байтов, необходимым для хранения возвращаемых сведений. Если возвращаемые данные больше предоставленного буфера, QueryActCtxW возвращает ERROR_INSUFFICIENT_BUFFER и данные не записываются в буфер, на который указывает pvBuffer.

В следующем примере показан метод вызова сначала с небольшим буфером, а затем для вызова, если буфер слишком мал.

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

Требования

Требование Значение
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows Server 2003 [только классические приложения]
Целевая платформа Windows
Header winbase.h (включая Windows.h)
Библиотека Kernel32.lib
DLL Kernel32.dll