DPA_InsertPtr

This function inserts an item into a DPA at a given position.

Declaration

int
DPA_InsertPtr (
    HDPA pdpa,
    int index,
    PVOID p);

Parameters

The pdpa argument provides a handle to the DPA.

The index argument provides the 0-based index at which to insert the item, or is DPA_APPEND (0x7FFFFFFF) to add the item to the end of the list.

The p argument provides a pointer to the item, or is NULL to insert an empty item.

Return Value

The function returns the 0-based index at which the item was added to the list, else DPA_ERR (-1) for failure.

Behaviour

The function fails if the DPA handle is NULL or if the 0-based index is negative. If the index is greater than the number of pointers currently in the array, then the function inserts at the end of the array. This case may be arranged most conveniently by giving DPA_APPEND as the index.

The function inserts the given item into the given DPA at the position described by the given index (subject to one exceptional case noted below). All pointers at or above the insertion point are moved one position further along the array to make room for the new pointer.

If memory for the array is not large enough for one more pointer, the function fails unless it can get a reallocation. The new capacity, measured in pointers, is the current number of pointers in the array, plus one, rounded up to the next multiple of the allocation unit (which may increase as a side-effect).

Variations

Defence against a NULL pdpa argument begins in a build of version 4.0. Specifically, there is no defence in the version 4.0 from Windows 95, or in any earlier version, but there is in the version 4.0 for Internet Explorer 3.00 for Windows NT. (I have no copy of an Internet Explorer 3.00 for Windows 95. See the list of COMCTL32 versions found for this survey.)

That said, the defence is defective in versions earlier than 4.71: the function does not fail, but instead returns zero.

In version 6.10, the function checks explicitly that adding 1 to the current capacity does not take the capacity beyond 0x7FFFFFFF.

Availability

The DPA_InsertPtr function is exported from COMCTL32.DLL as ordinal 334 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 85 in version 7.0 and higher.

This function was documented among the Settlement Program Interfaces in December 2002, but with Windows 2000 cited as the minimum operating system, despite many years of earlier availability.