Функция HeapSetInformation (heapapi.h)
Включает компоненты для указанной кучи.
Синтаксис
BOOL HeapSetInformation(
[in, optional] HANDLE HeapHandle,
[in] HEAP_INFORMATION_CLASS HeapInformationClass,
[in] PVOID HeapInformation,
[in] SIZE_T HeapInformationLength
);
Параметры
[in, optional] HeapHandle
Дескриптор кучи, в которой должна быть задана информация. Этот дескриптор возвращается функцией HeapCreate или GetProcessHeap .
[in] HeapInformationClass
Класс сведений, которые необходимо задать. Этот параметр может быть одним из следующих значений из типа перечисления HEAP_INFORMATION_CLASS .
Значение | Значение |
---|---|
|
Включает функции кучи. Поддерживается только куча с низким уровнем фрагментации (LFH).
Однако для приложений нет необходимости включать LFH, так как система использует LFH по мере необходимости для обслуживания запросов на выделение памяти.
Windows XP и Windows Server 2003: По умолчанию LFH не включен. Чтобы включить LFH для указанной кучи, задайте для переменной, на которую указывает параметр HeapInformation , значение 2. После включения LFH для кучи ее нельзя отключить. Невозможно включить LFH для кучи, созданных с помощью HEAP_NO_SERIALIZE , или для кучи, созданных с фиксированным размером. LFH также нельзя включить, если вы используете средства отладки кучи в средствах отладки для Windows или Microsoft Application Verifier. При запуске процесса в любом отладчике некоторые параметры отладки кучи автоматически включаются для всех кучи в процессе. Эти параметры отладки кучи предотвращают использование LFH. Чтобы включить кучу с низкой фрагментацией при выполнении в отладчике, задайте для переменной среды _NO_DEBUG_HEAP значение 1. |
|
Включает функцию завершения при повреждении. Если диспетчер кучи обнаруживает ошибку в любой куче, используемой процессом, он вызывает службу отчеты об ошибках Windows и завершает процесс.
После включения этой функции процессом ее нельзя отключить. Windows Server 2003 и Windows XP: Это значение не поддерживается до windows Vista и Windows XP с пакетом обновления 3 (SP3). Функция выполняется успешно, но значение HeapEnableTerminationOnCorruption игнорируется. |
|
Если метод HeapSetInformation вызывается с параметром HeapHandle со значением NULL, то все кучи в процессе с кучей с низким уровнем фрагментации (LFH) будут оптимизированы для кэша, а память по возможности будет списана.
Если в HeapHandle указан указатель кучи, то будет оптимизирована только эта куча. Обратите внимание, что структура HEAP_OPTIMIZE_RESOURCES_INFORMATION, переданная в HeapInformation , должна быть правильно инициализирована. Примечание Это значение было добавлено в Windows 8.1. |
[in] HeapInformation
Буфер сведений кучи. Формат этих данных зависит от значения параметра HeapInformationClass .
Если параметр HeapInformationClass имеет значение HeapCompatibilityInformation, то параметр HeapInformation является указателем на переменную ULONG .
Если параметр HeapInformationClass имеет значение HeapEnableTerminationOnCorruption, параметр HeapInformation должен иметь значение NULL , а HeapInformationLength — 0.
[in] HeapInformationLength
Размер буфера HeapInformation в байтах.
Возвращаемое значение
Если функция выполняется успешно, возвращается ненулевое значение.
Если функция завершается сбоем, возвращается значение 0 (ноль). Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Комментарии
Чтобы получить текущие параметры для кучи, используйте функцию HeapQueryInformation .
Настоятельно рекомендуется задать параметр HeapEnableTerminateOnCorruption , так как он снижает уязвимость приложения к эксплойтам безопасности, которые используют преимущества поврежденной кучи.
Примеры
В следующем примере показано, как включить кучу с низким уровнем фрагментации.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#define HEAP_LFH 2
int __cdecl _tmain()
{
BOOL bResult;
HANDLE hHeap;
ULONG HeapInformation;
//
// Enable heap terminate-on-corruption.
// A correct application can continue to run even if this call fails,
// so it is safe to ignore the return value and call the function as follows:
// (void)HeapSetInformation(NULL, HeapEnableTerminationOnCorruption, NULL, 0);
// If the application requires heap terminate-on-corruption to be enabled,
// check the return value and exit on failure as shown in this example.
//
bResult = HeapSetInformation(NULL,
HeapEnableTerminationOnCorruption,
NULL,
0);
if (bResult != FALSE) {
_tprintf(TEXT("Heap terminate-on-corruption has been enabled.\n"));
}
else {
_tprintf(TEXT("Failed to enable heap terminate-on-corruption with LastError %d.\n"),
GetLastError());
return 1;
}
//
// Create a new heap with default parameters.
//
hHeap = HeapCreate(0, 0, 0);
if (hHeap == NULL) {
_tprintf(TEXT("Failed to create a new heap with LastError %d.\n"),
GetLastError());
return 1;
}
//
// Enable the low-fragmentation heap (LFH). Starting with Windows Vista,
// the LFH is enabled by default but this call does not cause an error.
//
HeapInformation = HEAP_LFH;
bResult = HeapSetInformation(hHeap,
HeapCompatibilityInformation,
&HeapInformation,
sizeof(HeapInformation));
if (bResult != FALSE) {
_tprintf(TEXT("The low-fragmentation heap has been enabled.\n"));
}
else {
_tprintf(TEXT("Failed to enable the low-fragmentation heap with LastError %d.\n"),
GetLastError());
return 1;
}
return 0;
}
Требования
Требование | Значение |
---|---|
Минимальная версия клиента | Windows XP [классические приложения | Приложения UWP] |
Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
Целевая платформа | Windows |
Header | heapapi.h (включая Windows.h) |
Библиотека | Kernel32.lib |
DLL | Kernel32.dll |