HeapSetInformation, fonction (heapapi.h)

Active les fonctionnalités d’un tas spécifié.

Syntaxe

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

Paramètres

[in, optional] HeapHandle

Handle vers le tas où les informations doivent être définies. Ce handle est retourné par la fonction HeapCreate ou GetProcessHeap .

[in] HeapInformationClass

Classe d’informations à définir. Ce paramètre peut être l’une des valeurs suivantes du type d’énumération HEAP_INFORMATION_CLASS .

Valeur	Signification
HeapCompatibilityInformation 0	Active les fonctionnalités de tas. Seul le tas à faible fragmentation (LFH) est pris en charge. Toutefois, il n’est pas nécessaire pour les applications d’activer le LFH, car le système utilise le LFH comme nécessaire pour traiter les demandes d’allocation de mémoire. Windows XP et Windows Server 2003 : Le LFH n’est pas activé par défaut. Pour activer le LFH pour le tas spécifié, définissez la variable pointée vers par le paramètre HeapInformation sur 2. Une fois le LFH activé pour un tas, il ne peut pas être désactivé. Le LFH ne peut pas être activé pour les tas créés avec HEAP_NO_SERIALIZE ou pour les tas créés avec une taille fixe. Le LFH ne peut pas non plus être activé si vous utilisez les outils de débogage de tas dans Outils de débogage pour Windows ou Microsoft Application Verifier. Lorsqu’un processus est exécuté sous un débogueur, certaines options de débogage de tas sont automatiquement activées pour tous les tas du processus. Ces options de débogage de tas empêchent l’utilisation du LFH. Pour activer le tas à faible fragmentation lors de l’exécution sous un débogueur, définissez la variable d’environnement _NO_DEBUG_HEAP sur 1.
HeapEnableTerminationOnCorruption 1	Active la fonctionnalité terminate-on-corruption. Si le gestionnaire de tas détecte une erreur dans un tas utilisé par le processus, il appelle le service Rapport d'erreurs Windows et termine le processus. Une fois qu’un processus a activé cette fonctionnalité, elle ne peut pas être désactivée. Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge tant que Windows Vista et Windows XP avec SP3. La fonction réussit, mais la valeur HeapEnableTerminationOnCorruption est ignorée.
HeapOptimizeResources 3	Si HeapSetInformation est appelé avec HeapHandle défini sur NULL, tous les tas du processus avec un tas à faible fragmentation (LFH) auront leurs caches optimisés et la mémoire sera supprimée si possible. Si un pointeur de tas est fourni dans HeapHandle, seul ce tas sera optimisé. Notez que la structure HEAP_OPTIMIZE_RESOURCES_INFORMATION passée dans HeapInformation doit être correctement initialisée. Note Cette valeur a été ajoutée dans Windows 8.1.

[in] HeapInformation

Mémoire tampon d’informations de tas. Le format de ces données dépend de la valeur du paramètre HeapInformationClass .

Si le paramètre HeapInformationClass est HeapCompatibilityInformation, le paramètre HeapInformation est un pointeur vers une variable ULONG .

Si le paramètre HeapInformationClass est HeapEnableTerminationOnCorruption, le paramètre HeapInformation doit être NULL et HeapInformationLength doit avoir la valeur 0

[in] HeapInformationLength

Taille de la mémoire tampon HeapInformation , en octets.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est zéro (0). Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Pour récupérer les paramètres actuels du tas, utilisez la fonction HeapQueryInformation .

La définition de l’option HeapEnableTerminateOnCorruption est fortement recommandée, car elle réduit l’exposition d’une application aux attaques de sécurité qui tirent parti d’un tas endommagé.

Exemples

L’exemple suivant montre comment activer le tas à faible fragmentation.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau | applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau | applications UWP]
Plateforme cible	Windows
En-tête	heapapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll

Voir aussi

GetProcessHeap

Fonctions de tas

TasCréer

HeapQueryInformation

Fonctions de gestion de la mémoire