Função GetProcessHeaps (heapapi.h)

Artigo
02/07/2024

Retorna o número de heaps ativos e recupera identificadores para todos os heaps ativos para o processo de chamada.

Sintaxe

DWORD GetProcessHeaps(
  [in]  DWORD   NumberOfHeaps,
  [out] PHANDLE ProcessHeaps
);

Parâmetros

[in] NumberOfHeaps

O número máximo de identificadores de heap que podem ser armazenados no buffer apontado por ProcessHeaps.

[out] ProcessHeaps

Um ponteiro para um buffer que recebe uma matriz de identificadores de heap.

Retornar valor

O valor retornado é o número de identificadores para heaps que estão ativos para o processo de chamada.

Se o valor retornado for menor ou igual a NumberOfHeaps, a função armazenará esse número de identificadores de heap no buffer apontado por ProcessHeaps.

Se o valor retornado for maior que NumberOfHeaps, o buffer apontado por ProcessHeaps será muito pequeno para manter todas as alças de heap para o processo de chamada e a função armazenará identificadores NumberOfHeaps no buffer. Use o valor retornado para alocar um buffer grande o suficiente para receber todos os identificadores e chamar a função novamente.

Se o valor retornado for zero, a função falhará porque cada processo tem pelo menos um heap ativo, o heap padrão para o processo. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A função GetProcessHeaps obtém um identificador para o heap padrão do processo de chamada, além de identificadores para quaisquer heaps privados adicionais criados chamando a função HeapCreate em qualquer thread no processo.

A função GetProcessHeaps é útil principalmente para depuração, pois alguns dos heaps privados recuperados pela função podem ter sido criados por outro código em execução no processo e podem ser destruídos após o retorno de GetProcessHeaps . Destruir um heap invalida o identificador para o heap e o uso contínuo desses identificadores pode causar um comportamento indefinido no aplicativo. As funções heap devem ser chamadas somente no heap padrão do processo de chamada e em heaps privados que o processo cria e gerencia.

Para obter um identificador para o heap de processo do processo de chamada, use a função GetProcessHeap .

Exemplos

Para obter um exemplo, consulte Obtendo heaps de processo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	heapapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll