DPA_SetPtr

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

Declaration

BOOL
DPA_SetPtr (
    HDPA pdpa,
    int index,
    PVOID p);

Parameters

The pdpa argument provides a handle to the DPA.

The index argument provides the 0-based index to associate with the item.

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

Return Value

The function returns TRUE if successful, else FALSE.

Behaviour

The function fails if the DPA handle is NULL or if the 0-based index is negative. If the heap allocation that holds the array is not large enough for the desired position, the function fails unless it can get a suitable reallocation. The new capacity, counted in pointers, is the given index, plus one, rounded up to the next multiple of the allocation unit (which may increase as a side-effect). If the given index is not less than the number of pointers currently in the array, then all the intermediate pointers are set to NULL, as if to append as many empty items as needed on the way to setting the given item at the given position. Finally, the function sets the item into the given DPA at the position described by the given index, replacing any item that is currently stored at this position.

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

For the case where the item is to be set beyond the current end of the pointer array, only in version 5.81 and higher does the function set the intermediate pointers to NULL. This may have been thought unnecessary in earlier versions because the allocation and reallocation of the pointer array is always done with zero-initialisation. However, deleting the last pointer in the array typically just reduces the count of items without clearing the pointer from memory. If a subsequent setting of a pointer at a higher index does not cause a reallocation, then the previously deleted pointer would be restored.

Availability

The DPA_SetPtr function is exported from COMCTL32.DLL as ordinal 335 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 90 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.