DPA_DeletePtr

This function deletes an item from a DPA.

Declaration

PVOID
DPA_Delete (
    HDPA pdpa,
    int index);

Parameters

The pdpa argument provides a handle to the DPA.

The index argument provides the 0-based index of the item.

Return Value

If successful, the function returns a pointer to the item, including to return NULL for an empty item. The function returns NULL for failure.

Behaviour

The function fails if the DPA handle is NULL, or if the index is negative or is not not less than the current number of pointers in the array.

Otherwise, the function deletes from the DPA whatever pointer is described by the given index. If this was not the last pointer in the array, then each pointer further into the array is moved one position towards the start of the array. If the deletion leaves the pointer array more than one allocation unit smaller than the current capacity, the function reduces the capacity by one allocation unit and gives back the last allocation unit from the memory used for the pointer array.

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.)

Availability

The DPA_DeletePtr function is exported from COMCTL32.DLL as ordinal 336 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 76 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.