HeapSetInformation-Funktion (heapapi.h)

  • Artikel

Aktiviert Features für einen angegebenen Heap.

Syntax

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

Parameter

[in, optional] HeapHandle

Ein Handle für den Heap, in dem Informationen festgelegt werden sollen. Dieses Handle wird entweder von der Funktion HeapCreate oder GetProcessHeap zurückgegeben.

[in] HeapInformationClass

Die Klasse der festzulegenden Informationen. Dieser Parameter kann einer der folgenden Werte aus dem HEAP_INFORMATION_CLASS Enumerationstyp sein.

Wert Bedeutung
HeapCompatibilityInformation
0
 Aktiviert Heapfeatures. Nur der Heap mit geringer Fragmentierung (LFH) wird unterstützt. Es ist jedoch nicht erforderlich, dass Anwendungen die LFH aktivieren, da das System den LFH bei Bedarf verwendet, um Speicherzuordnungsanforderungen zu verwalten.

Windows XP und Windows Server 2003: Die LFH ist standardmäßig nicht aktiviert. Um die LFH für den angegebenen Heap zu aktivieren, legen Sie die Variable, auf die der HeapInformation-Parameter verweist, auf 2 fest. Nachdem die LFH für einen Heap aktiviert wurde, kann sie nicht deaktiviert werden.

Die LFH kann nicht für Heaps aktiviert werden, die mit HEAP_NO_SERIALIZE erstellt wurden, oder für Heaps, die mit einer festen Größe erstellt wurden. Die LFH kann auch nicht aktiviert werden, wenn Sie die Heap-Debugtools in Debugtools für Windows oder Microsoft Application Verifier verwenden.

Wenn ein Prozess unter einem Debugger ausgeführt wird, werden bestimmte Heapdebugoptionen automatisch für alle Heaps im Prozess aktiviert. Diese Heapdebugoptionen verhindern die Verwendung des LFH. Um den Heap mit geringer Fragmentierung bei der Ausführung unter einem Debugger zu aktivieren, legen Sie die _NO_DEBUG_HEAP Umgebungsvariable auf 1 fest.
HeapEnableTerminationOnCorruption
1
 Aktiviert das Feature "Beschädigung beenden". Wenn der Heap-Manager einen Fehler in einem heap erkennt, der vom Prozess verwendet wird, ruft er den Windows-Fehlerberichterstattung-Dienst auf und beendet den Prozess.

Nachdem ein Prozess dieses Feature aktiviert hat, kann es nicht deaktiviert werden.

Windows Server 2003 und Windows XP: Dieser Wert wird erst unter Windows Vista und Windows XP mit SP3 unterstützt. Die Funktion ist erfolgreich, aber der HeapEnableTerminationOnCorruption-Wert wird ignoriert.
HeapOptimizeResources
3
 Wenn HeapSetInformation aufgerufen wird und HeapHandle auf NULL festgelegt ist, werden die Caches für alle Heaps im Prozess mit einem Heap mit geringer Fragmentierung (LFH) optimiert, und der Arbeitsspeicher wird nach Möglichkeit dekomprimiert.

Wenn ein Heapzeiger in HeapHandle bereitgestellt wird, wird nur dieser Heap optimiert.

Beachten Sie, dass die in HeapInformation übergebene HEAP_OPTIMIZE_RESOURCES_INFORMATION-Struktur ordnungsgemäß initialisiert werden muss.

Hinweis Dieser Wert wurde in Windows 8.1 hinzugefügt.

[in] HeapInformation

Der Heapinformationspuffer. Das Format dieser Daten hängt vom Wert des HeapInformationClass-Parameters ab.

Wenn der HeapInformationClass-ParameterHeapCompatibilityInformation ist, ist der HeapInformation-Parameter ein Zeiger auf eine ULONG-Variable .

Wenn der HeapInformationClass-ParameterHeapEnableTerminationOnCorruption ist, sollte der HeapInformation-ParameterNULL und HeapInformationLength 0 sein.

[in] HeapInformationLength

Die Größe des HeapInformation-Puffers in Bytes.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert 0 (null). Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Um die aktuellen Einstellungen für den Heap abzurufen, verwenden Sie die HeapQueryInformation-Funktion .

Das Festlegen der Option HeapEnableTerminateOnCorruption wird dringend empfohlen, da dies die Exposition einer Anwendung gegenüber Sicherheitsexbissen verringert, die einen beschädigten Heap ausnutzen.

Beispiele

Das folgende Beispiel zeigt, wie Sie den Heap mit geringer Fragmentierung aktivieren.

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

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile heapapi.h (einschließlich Windows.h)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

GetProcessHeap

Heapfunktionen

HeapCreate

HeapQueryInformation

Speicherverwaltungsfunktionen