Função HeapSetInformation (heapapi.h)
Habilita recursos para um heap especificado.
Sintaxe
BOOL HeapSetInformation(
[in, optional] HANDLE HeapHandle,
[in] HEAP_INFORMATION_CLASS HeapInformationClass,
[in] PVOID HeapInformation,
[in] SIZE_T HeapInformationLength
);
Parâmetros
[in, optional] HeapHandle
Um identificador para o heap em que as informações devem ser definidas. Esse identificador é retornado pela função HeapCreate ou GetProcessHeap .
[in] HeapInformationClass
A classe de informações a ser definida. Esse parâmetro pode ser um dos seguintes valores do tipo de enumeração HEAP_INFORMATION_CLASS .
| Valor | Significado |
|---|---|
|
Habilita recursos de heap. Somente o heap de baixa fragmentação (LFH) tem suporte.
No entanto, não é necessário que os aplicativos habilitem o LFH porque o sistema usa o LFH conforme necessário para atender às solicitações de alocação de memória.
Windows XP e Windows Server 2003: O LFH não está habilitado por padrão. Para habilitar o LFH para o heap especificado, defina a variável apontada pelo parâmetro HeapInformation como 2. Depois que o LFH estiver habilitado para um heap, ele não poderá ser desabilitado. O LFH não pode ser habilitado para heaps criados com HEAP_NO_SERIALIZE ou para heaps criados com um tamanho fixo. O LFH também não poderá ser habilitado se você estiver usando as ferramentas de depuração de heap em Ferramentas de Depuração para Windows ou Verificador de Aplicativos da Microsoft. Quando um processo é executado em qualquer depurador, determinadas opções de depuração de heap são habilitadas automaticamente para todos os heaps no processo. Essas opções de depuração de heap impedem o uso do LFH. Para habilitar o heap de baixa fragmentação ao executar em um depurador, defina o _NO_DEBUG_HEAP variável de ambiente como 1. |
|
Habilita o recurso terminate-on-corruption. Se o gerenciador de heap detectar um erro em qualquer heap usado pelo processo, ele chamará o serviço Relatório de Erros do Windows e encerrará o processo.
Depois que um processo habilita esse recurso, ele não pode ser desabilitado. Windows Server 2003 e Windows XP: Esse valor não tem suporte até o Windows Vista e o Windows XP com SP3. A função é bem-sucedida, mas o valor HeapEnableTerminationOnCorruption é ignorado. |
|
Se HeapSetInformation for chamado com HeapHandle definido como NULL, todos os heaps no processo com um heap de baixa fragmentação (LFH) terão seus caches otimizados e a memória será descompactada, se possível.
Se um ponteiro de heap for fornecido no HeapHandle, somente esse heap será otimizado. Observe que a estrutura de HEAP_OPTIMIZE_RESOURCES_INFORMATION passada em HeapInformation deve ser inicializada corretamente. Nota Esse valor foi adicionado em Windows 8.1. |
[in] HeapInformation
O buffer de informações de heap. O formato desses dados depende do valor do parâmetro HeapInformationClass .
Se o parâmetro HeapInformationClass for HeapCompatibilityInformation, o parâmetro HeapInformation será um ponteiro para uma variável ULONG .
Se o parâmetro HeapInformationClass for HeapEnableTerminationOnCorruption, o parâmetro HeapInformation deverá ser NULL e HeapInformationLength deverá ser 0
[in] HeapInformationLength
O tamanho do buffer HeapInformation , em bytes.
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de zero.
Se a função falhar, o valor retornado será zero (0). Para obter informações de erro estendidas, chame GetLastError.
Comentários
Para recuperar as configurações atuais do heap, use a função HeapQueryInformation .
É altamente recomendável definir a opção HeapEnableTerminateOnCorruption porque reduz a exposição de um aplicativo a explorações de segurança que aproveitam um heap corrompido.
Exemplos
O exemplo a seguir mostra como habilitar o heap de baixa fragmentação.
#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;
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | heapapi.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |