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) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |