Funzione HeapSetInformation (heapapi.h)

Abilita le funzionalità per un heap specificato.

Sintassi

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

Parametri

[in, optional] HeapHandle

Handle per l'heap in cui devono essere impostate le informazioni. Questo handle viene restituito dalla funzione HeapCreate o GetProcessHeap .

[in] HeapInformationClass

Classe di informazioni da impostare. Questo parametro può essere uno dei valori seguenti dal tipo di enumerazione HEAP_INFORMATION_CLASS .

Valore	Significato
HeapCompatibilityInformation 0	Abilita le funzionalità dell'heap. È supportato solo l'heap a bassa frammentazione (LFH). Non è tuttavia necessario che le applicazioni abilitino l'LFH perché il sistema usa LFH in base alle esigenze per gestire le richieste di allocazione della memoria. Windows XP e Windows Server 2003: LFH non è abilitato per impostazione predefinita. Per abilitare LFH per l'heap specificato, impostare la variabile a cui punta il parametro HeapInformation su 2. Dopo che l'LFH è abilitato per un heap, non può essere disabilitato. LFH non può essere abilitato per gli heap creati con HEAP_NO_SERIALIZE o per heap creati con una dimensione fissa. LFH non può essere abilitato anche se si usano gli strumenti di debug dell'heap in Strumenti di debug per Windows o Microsoft Application Verifier. Quando un processo viene eseguito in qualsiasi debugger, alcune opzioni di debug dell'heap vengono abilitate automaticamente per tutti gli heap nel processo. Queste opzioni di debug dell'heap impediscono l'uso di LFH. Per abilitare l'heap a bassa frammentazione durante l'esecuzione in un debugger, impostare la variabile di ambiente _NO_DEBUG_HEAP su 1.
HeapEnableTerminationOnCorruption 1	Abilita la funzionalità terminate-on-corruption. Se il gestore dell'heap rileva un errore in qualsiasi heap usato dal processo, chiama il servizio Segnalazione errori Windows e termina il processo. Dopo che un processo abilita questa funzionalità, non può essere disabilitata. Windows Server 2003 e Windows XP: Questo valore non è supportato finché Windows Vista e Windows XP con SP3. La funzione ha esito positivo, ma il valore HeapEnableTerminationOnCorruption viene ignorato.
HeapOptimizeResources 3	Se HeapSetInformation viene chiamato con HeapHandle impostato su NULL, tutti gli heap nel processo con un heap a bassa frammentazione (LFH) avranno le cache ottimizzate e la memoria verrà decommessa, se possibile. Se viene fornito un puntatore heap in HeapHandle, verrà ottimizzato solo l'heap. Si noti che la struttura HEAP_OPTIMIZE_RESOURCES_INFORMATION passata in HeapInformation deve essere inizializzata correttamente. Nota Questo valore è stato aggiunto in Windows 8.1.

[in] HeapInformation

Buffer delle informazioni sull'heap. Il formato di questi dati dipende dal valore del parametro HeapInformationClass .

Se il parametro HeapInformationClass è HeapCompatibilityInformation, il parametro HeapInformation è un puntatore a una variabile ULONG .

Se il parametro HeapInformationClass è HeapEnableTerminationOnCorruption, il parametro HeapInformation deve essere NULL e HeapInformationLength deve essere 0

[in] HeapInformationLength

Dimensioni del buffer HeapInformation , in byte.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è 0 (zero). Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Per recuperare le impostazioni correnti per l'heap, usare la funzione HeapQueryInformation .

L'impostazione dell'opzione HeapEnableTerminateOnCorruption è fortemente consigliata perché riduce l'esposizione di un'applicazione agli exploit di sicurezza che sfruttano un heap danneggiato.

Esempio

L'esempio seguente illustra come abilitare l'heap a bassa frammentazione.

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop | App UWP]
Server minimo supportato	Windows Server 2003 [app desktop | App UWP]
Piattaforma di destinazione	Windows
Intestazione	heapapi.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll

Vedere anche

GetProcessHeap

Funzioni heap

HeapCreate

HeapQueryInformation

Funzioni di gestione della memoria