Функция 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 .

Значение	Значение
HeapCompatibilityInformation 0	Включает функции кучи. Поддерживается только куча с низким уровнем фрагментации (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.
HeapEnableTerminationOnCorruption 1	Включает функцию завершения при повреждении. Если диспетчер кучи обнаруживает ошибку в любой куче, используемой процессом, он вызывает службу отчеты об ошибках Windows и завершает процесс. После включения этой функции процессом ее нельзя отключить. Windows Server 2003 и Windows XP: Это значение не поддерживается до windows Vista и Windows XP с пакетом обновления 3 (SP3). Функция выполняется успешно, но значение HeapEnableTerminationOnCorruption игнорируется.
HeapOptimizeResources 3	Если метод 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

См. также

GetProcessHeap

Функции кучи

HeapCreate

HeapQueryInformation

Функции управления памятью