Funzione HeapQueryInformation (heapapi.h)

Recupera informazioni sull'heap specificato.

Sintassi

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

Parametri

[in, optional] HeapHandle

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

[in] HeapInformationClass

Classe di informazioni da recuperare. Questo parametro può essere il valore seguente dal tipo di enumerazione HEAP_INFORMATION_CLASS .

Valore

Significato

HeapCompatibilityInformation 0

Indica le funzionalità dell'heap abilitate. Il parametro HeapInformation è un puntatore a una variabile ULONG . Se HeapInformation è 0, l'heap è un heap standard che non supporta elenchi look-aside. Se HeapInformation è 1, l'heap supporta elenchi look-aside. Per altre informazioni, vedere la sezione Osservazioni. Se HeapInformation è 2, l'heap a frammentazione bassa (LFH) è stato abilitato per l'heap. L'abilitazione di LFH disabilita gli elenchi look-aside.

[out] HeapInformation

Puntatore a un buffer che riceve le informazioni sull'heap. Il formato di questi dati dipende dal valore del parametro HeapInformationClass .

[in] HeapInformationLength

Dimensioni delle informazioni sull'heap su cui viene eseguito una query, in byte.

[out, optional] ReturnLength

Puntatore a una variabile che riceve la lunghezza dei dati scritti nel buffer HeapInformation . Se il buffer è troppo piccolo, la funzione ha esito negativo e ReturnLength specifica le dimensioni minime necessarie per il buffer.

Se non si desidera ricevere queste informazioni, specificare NULL.

Valore restituito

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

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

Commenti

Per abilitare la funzionalità LFH o terminate-on-corruption, usare la funzione HeapSetInformation .

Windows XP e Windows Server 2003: Un elenco look-aside è un meccanismo di allocazione rapida della memoria che contiene solo blocchi di dimensioni fisse. Gli elenchi look-aside sono abilitati per impostazione predefinita per gli heap che li supportano. A partire da Windows Vista, gli elenchi look-aside non vengono usati e LFH è abilitato per impostazione predefinita.

Gli elenchi look-aside sono più veloci rispetto alle allocazioni di pool generali che variano in base alle dimensioni, perché il sistema non cerca memoria libera adatta all'allocazione. Inoltre, l'accesso agli elenchi look-aside viene in genere sincronizzato usando istruzioni di scambio atomico rapido anziché mutex o spinlock. Gli elenchi look-aside possono essere creati dal sistema o dai driver. Possono essere allocate da pool di paging o non di paging.

Esempio

L'esempio seguente usa GetProcessHeap per ottenere un handle per l'heap del processo predefinito e HeapQueryInformation per recuperare informazioni sull'heap.

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

Requisiti

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

Vedere anche

GetProcessHeap

Funzioni heap

HeapCreate

HeapSetInformation

Funzioni di gestione della memoria