Fungsi HeapSetInformation (heapapi.h)

Mengaktifkan fitur untuk tumpukan tertentu.

Sintaks

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

Parameter

[in, optional] HeapHandle

Handel ke timbunan tempat informasi akan diatur. Handel ini dikembalikan oleh fungsi HeapCreate atau GetProcessHeap .

[in] HeapInformationClass

Kelas informasi yang akan ditetapkan. Parameter ini bisa menjadi salah satu nilai berikut dari jenis enumerasi HEAP_INFORMATION_CLASS .

Nilai	Makna
HeapCompatibilityInformation 0	Mengaktifkan fitur tumpukan. Hanya tumpukan fragmentasi rendah (LFH) yang didukung. Namun, aplikasi tidak perlu mengaktifkan LFH karena sistem menggunakan LFH sesuai kebutuhan untuk melayani permintaan alokasi memori. Windows XP dan Windows Server 2003: LFH tidak diaktifkan secara default. Untuk mengaktifkan LFH untuk heap yang ditentukan, atur variabel yang diacu oleh parameter HeapInformation ke 2. Setelah LFH diaktifkan untuk heap, LFH tidak dapat dinonaktifkan. LFH tidak dapat diaktifkan untuk tumpukan yang dibuat dengan HEAP_NO_SERIALIZE atau untuk tumpukan yang dibuat dengan ukuran tetap. LFH juga tidak dapat diaktifkan jika Anda menggunakan alat penelusuran kesalahan timbunan di Alat Debugging untuk Windows atau Pemverifikasi Aplikasi Microsoft. Ketika proses dijalankan di bawah debugger apa pun, opsi debug timbunan tertentu secara otomatis diaktifkan untuk semua tumpukan dalam proses. Opsi debug timbunan ini mencegah penggunaan LFH. Untuk mengaktifkan tumpukan fragmentasi rendah saat berjalan di bawah debugger, atur variabel lingkungan _NO_DEBUG_HEAP ke 1.
HeapEnableTerminationOnCorruption 1	Mengaktifkan fitur terminate-on-corruption. Jika manajer timbunan mendeteksi kesalahan dalam timbunan apa pun yang digunakan oleh proses, ia memanggil layanan Pelaporan Galat Windows dan mengakhiri proses. Setelah proses mengaktifkan fitur ini, fitur ini tidak dapat dinonaktifkan. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung sampai Windows Vista dan Windows XP dengan SP3. Fungsi berhasil tetapi nilai HeapEnableTerminationOnCorruption diabaikan.
HeapOptimizeResources 3	Jika HeapSetInformation dipanggil dengan HeapHandle diatur ke NULL, maka semua tumpukan dalam proses dengan tumpukan fragmentasi rendah (LFH) akan mengoptimalkan cache mereka, dan memori akan dinonaktifkan jika memungkinkan. Jika penunjuk tumpukan disediakan di HeapHandle, maka hanya tumpukan yang akan dioptimalkan. Perhatikan bahwa struktur HEAP_OPTIMIZE_RESOURCES_INFORMATION yang diteruskan dalam HeapInformation harus diinisialisasi dengan benar. Catatan Nilai ini ditambahkan dalam Windows 8.1.

[in] HeapInformation

Buffer informasi tumpuk. Format data ini tergantung pada nilai parameter HeapInformationClass .

Jika parameter HeapInformationClass adalah HeapCompatibilityInformation, parameter HeapInformation adalah penunjuk ke variabel ULONG .

Jika parameter HeapInformationClass adalah HeapEnableTerminationOnCorruption, parameter HeapInformation harus NULL dan HeapInformationLength harus 0

[in] HeapInformationLength

Ukuran buffer HeapInformation , dalam byte.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah 0 (nol). Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Untuk mengambil pengaturan saat ini untuk tumpukan, gunakan fungsi HeapQueryInformation .

Mengatur opsi HeapEnableTerminateOnCorruption sangat disarankan karena mengurangi paparan aplikasi terhadap eksploitasi keamanan yang memanfaatkan tumpukan yang rusak.

Contoh

Contoh berikut menunjukkan kepada Anda cara mengaktifkan tumpukan fragmentasi rendah.

#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;
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop | Aplikasi UWP]
Target Platform	Windows
Header	heapapi.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

GetProcessHeap

Fungsi Heap

HeapCreate

HeapQueryInformation

Fungsi Manajemen Memori