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 后，无法禁用它。

不能为使用 HEAP_NO_SERIALIZE 创建的堆或以固定大小创建的堆启用 LFH。 如果使用 Windows 或 Microsoft 应用程序验证程序调试工具中的堆调试工具，则也无法启用 LFH。

当进程在任何调试器下运行时，将自动为进程中的所有堆启用某些堆调试选项。 这些堆调试选项阻止使用 LFH。 若要在调试器下运行时启用低碎片堆，请将 _NO_DEBUG_HEAP 环境变量设置为 1。
HeapEnableTerminationOnCorruption
1
 启用损坏时终止功能。 如果堆管理器在进程使用的任何堆中检测到错误，它将调用Windows 错误报告服务并终止进程。

进程启用此功能后，无法禁用此功能。

Windows Server 2003 和 Windows XP： 在 Windows Vista 和 Windows XP 使用 SP3 之前，不支持此值。 函数成功，但 HeapEnableTerminationOnCorruption 值将被忽略。
HeapOptimizeResources
3
 如果在将 HeapHandle 设置为 NULL 的情况下调用 HeapSetInformation，则进程中具有 低碎片堆 (LFH) 的所有堆都将优化其缓存，并且内存将尽可能取消提交。

如果在 HeapHandle 中提供了堆指针，则只会优化该堆。

请注意，必须正确初始化 HeapInformation 中传递的HEAP_OPTIMIZE_RESOURCES_INFORMATION结构。

注意此值已添加到 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
标头 heapapi.h (包括 Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

GetProcessHeap

堆函数

HeapCreate

HeapQueryInformation

内存管理函数