DPA_Search

This function finds an item in a list or finds where the item would appear if inserted into the list.

Declaration

int
DPA_Search (
    HDPA pdpa,
    PVOID pFind,
    int iStart,
    PFNDPACOMPARE pfnCmp,
    LPARAM lParam,
    UINT options); 

The comparison callback function has the prototype:

typedef int (*PFNDPACOMPARE) (PVOID p1, PVOID p2, LPARAM lParam);

Parameters

The pdpa argument provides a handle to the DPA.

The pFind argument provides a pointer to the item that is to be searched for, or is NULL to search for an empty position.

The iStart argument provides a 0-based index at which to start the search. This argument is ignored unless performing a linear search.

The pfnCmp argument provides the address of a caller-specific comparison function that may be called back to assess an item in the list against the item that is sought.

The lParam argument provides a caller-specific context to be passed on each invocation of the callback function.

The options argument provides bit flags to direct the search behaviour. Recognised values are:

Return Value

The function returns a 0-based index for the lowest-numbered matching item, else DPA_ERR (-1).

A special case exists when the options have DPAS_SORTED set and either DPAS_INSERTBEFORE or DPAS_INSERTAFTER set. If no matching item is found, the function does not fail but instead returns the 0-based index at which the sought item could be inserted into the list consistently with the existing ordering.

Behaviour

The function performs a linear search by default, but a binary search if DPAS_SORTED is given among the options.

Linear Search

A linear search runs from the position described by iStart to the end of the pointer array. The function fails trivially if the starting index is not less than the current number of pointers in the array. The function returns the 0-based index of the first item that the comparison function declares as matching the sought item. If no such match is found, the function fails.

The comparison function returns zero to indicate that the item at p1 (which will be pFind) matches the item at p2. Any other result is a direction to continue searching. Note that p2 may be NULL if any user of the list has set empty positions in the list.

Binary Search

A binary search applies to the whole list: the iStart argument is ignored. The function returns the 0-based index of the lowest-numbered item that the comparison function declares as matching the sought item. If no such match is found, then the default is for the function to fail.

However, if either the DPA_INSERTBEFORE or DPA_INSERTAFTER bit is set in the options, the function returns the 0-based index at which the sought item could be inserted into the list in keeping with the ordering established by the comparison function. Note that in this case, no indication is given of whether the returned index describes an item that was already in the list or just tells where the sought item might be inserted into the list. Note also that there is no difference in meaning between the DPA_INSERTBEFORE and DPA_INSERTAFTER flags.

The comparison function returns zero to indicate that the item at p1 (which will be pFind) matches the item at p2. A negative or positive result from the comparison function means respectively that the item at p1 is ordered before or after the item at p2.

A binary search can be accurate—indeed, meaningful—only if the list is already ordered consistently with the same combination of callback function and context.

Availability

The DPA_Search function is exported from COMCTL32.DLL as ordinal 339 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 89 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.