heapQueryInformation 函式 (heapapi.h)

發行項
02/26/2024

擷取指定堆積的相關信息。

語法

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

參數

[in, optional] HeapHandle

要擷取其信息的堆積句柄。 HeapCreate 或 GetProcessHeap 函式會傳回此句柄。

[in] HeapInformationClass

要擷取的信息類別。此參數可以是 來自HEAP_INFORMATION_CLASS 列舉類型的下列值。

值	意義
HeapCompatibilityInformation 0	指出已啟用的堆積功能。 HeapInformation 參數是 ULONG 變數的指標。如果 HeapInformation 為 0，堆積是不支援待看清單的標準堆積。如果 HeapInformation 是 1，堆積支援待看清單。如需詳細資訊，請參閱＜備註＞。如果 HeapInformation 為 2，則已針對堆積啟用低片段堆積 (LFH) 。啟用 LFH 會停用待看清單。

值

意義

HeapCompatibilityInformation
0

指出已啟用的堆積功能。

HeapInformation 參數是 ULONG 變數的指標。

如果 HeapInformation 為 0，堆積是不支援待看清單的標準堆積。

如果 HeapInformation 是 1，堆積支援待看清單。如需詳細資訊，請參閱＜備註＞。

如果 HeapInformation 為 2，則已針對堆積啟用低片段堆積 (LFH) 。啟用 LFH 會停用待看清單。

[out] HeapInformation

接收堆積信息的緩衝區指標。此數據的格式取決於 HeapInformationClass 參數的值。

[in] HeapInformationLength

要查詢的堆積資訊大小，以位元組為單位。

[out, optional] ReturnLength

變數的指標，可接收寫入 HeapInformation 緩衝區的數據長度。如果緩衝區太小，則函式會失敗， ReturnLength 會指定緩衝區所需的最小大小。

如果您不想收到此資訊，請指定 NULL。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

若要啟用 LFH 或終止損毀功能，請使用 HeapSetInformation 函式。

Windows XP 和 Windows Server 2003： 待看清單是只包含固定大小的區塊的快速記憶體配置機制。默認會針對支援它們的堆積啟用待看清單。從 Windows Vista 開始，不會使用待看清單，預設會啟用 LFH。

一般集區配置的大小會比一般集區配置更快，因為系統不會搜尋符合配置的可用記憶體。此外，使用快速不可部分完成的處理器交換指令，而不是 mutex 或 spinlocks，通常會同步存取待看清單。系統或驅動程式可以建立待看清單。它們可以從分頁或非分頁集區配置。

範例

下列範例使用 GetProcessHeap 來取得預設進程堆積和 HeapQueryInformation 的句柄，以擷取堆積的相關信息。

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

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	heapapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll