Función HeapSetInformation (heapapi.h)

Habilita las características de un montón especificado.

Sintaxis

BOOL HeapSetInformation(
  [in, optional] HANDLE                 HeapHandle,
  [in]           HEAP_INFORMATION_CLASS HeapInformationClass,
  [in]           PVOID                  HeapInformation,
  [in]           SIZE_T                 HeapInformationLength
);

Parámetros

[in, optional] HeapHandle

Identificador del montón donde se va a establecer la información. Este identificador lo devuelve la función HeapCreate o GetProcessHeap .

[in] HeapInformationClass

Clase de información que se va a establecer. Este parámetro puede ser uno de los siguientes valores del tipo de enumeración HEAP_INFORMATION_CLASS .

Valor	Significado
HeapCompatibilityInformation 0	Habilita las características del montón. Solo se admite el montón de fragmentación baja (LFH). Sin embargo, no es necesario que las aplicaciones habiliten el LFH porque el sistema usa el LFH según sea necesario para atender las solicitudes de asignación de memoria. Windows XP y Windows Server 2003: El LFH no está habilitado de forma predeterminada. Para habilitar el LFH para el montón especificado, establezca la variable a la que apunta el parámetro HeapInformation en 2. Después de habilitar el LFH para un montón, no se puede deshabilitar. El LFH no se puede habilitar para los montones creados con HEAP_NO_SERIALIZE o para montones creados con un tamaño fijo. El LFH tampoco se puede habilitar si usa las herramientas de depuración del montón en Herramientas de depuración para Windows o Comprobador de aplicaciones de Microsoft. Cuando se ejecuta un proceso en cualquier depurador, ciertas opciones de depuración del montón se habilitan automáticamente para todos los montones del proceso. Estas opciones de depuración del montón impiden el uso del LFH. Para habilitar el montón de baja fragmentación cuando se ejecuta en un depurador, establezca la variable de entorno _NO_DEBUG_HEAP en 1.
HeapEnableTerminationOnCorruption 1	Habilita la característica terminate-on-corruption. Si el administrador del montón detecta un error en cualquier montón usado por el proceso, llama al servicio Informe de errores de Windows y finaliza el proceso. Una vez que un proceso habilita esta característica, no se puede deshabilitar. Windows Server 2003 y Windows XP: Este valor no se admite hasta Windows Vista y Windows XP con SP3. La función se realiza correctamente, pero se omite el valor HeapEnableTerminationOnCorruption .
HeapOptimizeResources 3	Si se llama a HeapSetInformation con HeapHandle establecido en NULL, todos los montones del proceso con un montón de fragmentación baja (LFH) tendrán optimizadas sus memorias caché y la memoria se descomprimirá si es posible. Si se proporciona un puntero de montón en HeapHandle, solo se optimizará ese montón. Tenga en cuenta que la estructura de HEAP_OPTIMIZE_RESOURCES_INFORMATION pasada en HeapInformation debe inicializarse correctamente. Nota Este valor se agregó en Windows 8.1.

[in] HeapInformation

Búfer de información del montón. El formato de estos datos depende del valor del parámetro HeapInformationClass .

Si el parámetro HeapInformationClass es HeapCompatibilityInformation, el parámetro HeapInformation es un puntero a una variable ULONG .

Si el parámetro HeapInformationClass es HeapEnableTerminationOnCorruption, el parámetro HeapInformation debe ser NULL y HeapInformationLength debe ser 0.

[in] HeapInformationLength

Tamaño del búfer HeapInformation , en bytes.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es 0 (cero). Para obtener información de error extendida, llame a GetLastError.

Comentarios

Para recuperar la configuración actual del montón, use la función HeapQueryInformation .

Se recomienda establecer la opción HeapEnableTerminateOnCorruption porque reduce la exposición de una aplicación a vulnerabilidades de seguridad que aprovechan un montón dañado.

Ejemplos

En el ejemplo siguiente se muestra cómo habilitar el montón de baja fragmentación.

#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	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	heapapi.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll

Vea también

GetProcessHeap

Funciones del montón

MontónCrear

HeapQueryInformation

Funciones de administración de memoria