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 后，无法禁用它。 不能为使用 HEAP_NO_SERIALIZE 创建的堆或以固定大小创建的堆启用 LFH。 如果使用 Windows 或 Microsoft 应用程序验证程序调试工具中的堆调试工具，则也无法启用 LFH。 当进程在任何调试器下运行时，将自动为进程中的所有堆启用某些堆调试选项。 这些堆调试选项阻止使用 LFH。 若要在调试器下运行时启用低碎片堆，请将 _NO_DEBUG_HEAP 环境变量设置为 1。 |
|
启用损坏时终止功能。 如果堆管理器在进程使用的任何堆中检测到错误，它将调用Windows 错误报告服务并终止进程。
进程启用此功能后，无法禁用此功能。 Windows Server 2003 和 Windows XP： 在 Windows Vista 和 Windows XP 使用 SP3 之前，不支持此值。 函数成功，但 HeapEnableTerminationOnCorruption 值将被忽略。 |
|
如果在将 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 |