DPA_GetPtrIndex

This function finds the index for a given item in a given DPA.

Declaration

int
DPA_GetPtrIndex (
    HDPA pdpa,
    const void *p);

Parameters

The pdpa argument provides a handle to the DPA.

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

Return Value

The function returns a 0-based index for the given item if successful, else DPA_ERR (-1).

Behaviour

The function fails if the DPA handle is NULL or if the DPA has no pointer array. Otherwise, it searches the pointer array for the first occurrence of the given pointer. It returns the corresponding 0-based index.

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_GetPtrIndex function is exported from COMCTL32.DLL as ordinal 333 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 82 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.