DPA_CreateEx

This function creates a dynamic pointer array in a specified heap.

Declaration

HDPA
DPA_CreateEx (
    int cpGrow,
    HANDLE hHeap);

Parameters

The cpGrow argument provides the allocation unit for the DPA, measured as a number of pointers.

The hHeap argument provides a handle of the heap to use for the DPA, or is NULL for the default heap.

Return Value

The function returns a handle to the DPA if successful, else NULL for failure.

Behaviour

The function creates a DPA handle as the address of a small control structure also named DPA. Memory for the control structure is obtained from the heap given by the hHeap argument. If this argument is NULL, the function uses the process heap in the NT implementations, else a private heap in the Windows implementations.

Memory for the pointer array itself is not obtained by this function. Instead, the memory block that contains the array grows and shrinks according to the demands of other functions, but always as a multiple of an allocation unit whose initial size is set from the cpGrow argument. This allocation unit has an effective minimum of eight: the function chooses eight as the allocation unit if given any lesser value.

Availability

The DPA_CreateEx function is exported from COMCTL32.DLL as ordinal 340 in version 3.50 and higher. The implementation for version 6.10 and higher is built into a statically linked library and thence is also exported from the Internet Explorer module IERTUTIL.DLL as ordinal 75 in version 7.0 and higher.

Though this function dates from as long ago as 1995, it was still not documented by Microsoft in the MSDN Library at least as late as the CD edition dated January 2004.

This function has, however, got documented since then (in 2006 or perhaps some time during 2005). This article now uses Microsoft’s nomenclature.