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

另請參閱

GetProcessHeap

堆積函式

HeapCreate

HeapQueryInformation

記憶體管理功能