HeapQueryInformation, fonction (heapapi.h)

Récupère des informations sur le tas spécifié.

Syntaxe

BOOL HeapQueryInformation(
  [in, optional]  HANDLE                 HeapHandle,
  [in]            HEAP_INFORMATION_CLASS HeapInformationClass,
  [out]           PVOID                  HeapInformation,
  [in]            SIZE_T                 HeapInformationLength,
  [out, optional] PSIZE_T                ReturnLength
);

Paramètres

[in, optional] HeapHandle

Handle du tas dont les informations doivent être récupérées. Ce handle est retourné par la fonction HeapCreate ou GetProcessHeap .

[in] HeapInformationClass

Classe d’informations à récupérer. Ce paramètre peut être la valeur suivante du type d’énumération HEAP_INFORMATION_CLASS .

Valeur

Signification

HeapCompatibilityInformation 0

Indique les fonctionnalités de tas activées. Le paramètre HeapInformation est un pointeur vers une variable ULONG . Si HeapInformation a la valeur 0, le tas est un tas standard qui ne prend pas en charge les listes de look-aside. Si HeapInformation a la valeur 1, le tas prend en charge les listes de look-aside. Pour plus d'informations, consultez la section Notes. Si HeapInformation a la valeur 2, le tas à faible fragmentation (LFH) a été activé pour le tas. L’activation de LFH désactive les listes de look-aside.

[out] HeapInformation

Pointeur vers une mémoire tampon qui reçoit les informations du tas. Le format de ces données dépend de la valeur du paramètre HeapInformationClass .

[in] HeapInformationLength

Taille des informations de tas interrogées, en octets.

[out, optional] ReturnLength

Pointeur vers une variable qui reçoit la longueur des données écrites dans la mémoire tampon HeapInformation . Si la mémoire tampon est trop petite, la fonction échoue et ReturnLength spécifie la taille minimale requise pour la mémoire tampon.

Si vous ne souhaitez pas recevoir ces informations, spécifiez NULL.

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 égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Pour activer la fonction LFH ou terminate-on-corruption, utilisez la fonction HeapSetInformation .

Windows XP et Windows Server 2003 : Une liste de choix est un mécanisme d’allocation de mémoire rapide qui contient uniquement des blocs de taille fixe. Les listes de recherche sont activées par défaut pour les tas qui les prennent en charge. À compter de Windows Vista, les listes de recherche ne sont pas utilisées et le LFH est activé par défaut.

Les listes de recherche sont plus rapides que les allocations de pool générales qui varient en taille, car le système ne recherche pas de mémoire libre qui correspond à l’allocation. En outre, l’accès aux listes de recherche de côté est généralement synchronisé à l’aide d’instructions d’échange de processeur atomique rapide au lieu de mutexes ou de spinlocks. Les listes de recherche peuvent être créées par le système ou les pilotes. Ils peuvent être alloués à partir d’un pool paginé ou non paginé.

Exemples

L’exemple suivant utilise GetProcessHeap pour obtenir un handle vers le tas de processus par défaut et HeapQueryInformation pour récupérer des informations sur le tas.

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

#define HEAP_STANDARD 0
#define HEAP_LAL 1
#define HEAP_LFH 2

int __cdecl _tmain()
{
    BOOL bResult;
    HANDLE hHeap;
    ULONG HeapInformation;

    //
    // Get a handle to the default process heap.
    //
    hHeap = GetProcessHeap();
    if (hHeap == NULL) {
        _tprintf(TEXT("Failed to retrieve default process heap with LastError %d.\n"),
                 GetLastError());
        return 1;
    }

    //
    // Query heap features that are enabled.
    //
    bResult = HeapQueryInformation(hHeap,
                                   HeapCompatibilityInformation,
                                   &HeapInformation,
                                   sizeof(HeapInformation),
                                   NULL);
    if (bResult == FALSE) {
        _tprintf(TEXT("Failed to retrieve heap features with LastError %d.\n"),
                 GetLastError());
        return 1;
    }

    //
    // Print results of the query.
    //
    _tprintf(TEXT("HeapCompatibilityInformation is %d.\n"), HeapInformation);
    switch(HeapInformation)
    {
    case HEAP_STANDARD:
        _tprintf(TEXT("The default process heap is a standard heap.\n"));
        break;
    case HEAP_LAL:
        _tprintf(TEXT("The default process heap supports look-aside lists.\n"));
        break;
    case HEAP_LFH:
        _tprintf(TEXT("The default process heap has the low-fragmentation ") \
                 TEXT("heap enabled.\n"));
        break;
    default:
        _tprintf(TEXT("Unrecognized HeapInformation reported for the default ") \
                 TEXT("process heap.\n"));
        break;
     }

    return 0;
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
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

HeapSetInformation

Fonctions de gestion de la mémoire