共用方式為


heapSetInformation 函式 (heapapi.h)

啟用指定堆積的功能。

語法

BOOL HeapSetInformation(
  [in, optional] HANDLE                 HeapHandle,
  [in]           HEAP_INFORMATION_CLASS HeapInformationClass,
  [in]           PVOID                  HeapInformation,
  [in]           SIZE_T                 HeapInformationLength
);

參數

[in, optional] HeapHandle

要設定資訊的堆積句柄。 HeapCreateGetProcessHeap 函式會傳回此句柄。

[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 參數應為 NULLHeapInformationLength 應為 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

另請參閱

GetProcessHeap

堆積函式

HeapCreate

HeapQueryInformation

記憶體管理功能