| Home | Table of Contents | Please view with Internet Explorer (version 5.00 or higher) and enable scripting. For reasons, see Browsing This Web Site. |
This function sets an item into a DPA at a given position.
BOOL
DPA_SetPtr (
HDPA pdpa,
int index,
PVOID p);
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.
The function returns TRUE if successful, else FALSE.
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.
The function fails trivially if the DPA handle is NULL or if the 0-based index is negative. If the 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.
If the heap allocation that holds the array is not large enough to reach the desired position, the function fails unless it can get a reallocation. The new capacity, measured 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).
Some variations are known for early implementations. Version 4.00 merely assumes that the DPA handle is not NULL. For the case where the item is to be set beyond the current end of the pointer array, only from version 5.81 does the function set the intermediate pointers to NULL.
The DPA_SetPtr function is exported from COMCTL32.DLL as ordinal 335 in version 3.50 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.