DPA_Sort

This function reorders the items in a DPA.

Declaration

BOOL
DPA_Sort (
    HDPA pdpa,
    PFNDPACOMPARE pfnCmp,
    LPARAM lParam);

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 pfnCmp argument provides the address of a caller-specific comparison function that may be called back to obtain the relative order of any pair of items in the list.

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

Return Value

The function returns TRUE if successful, else FALSE.

Behaviour

The function fails if pfnCmp is NULL. It succeeds if the DPA is empty. It requires temporary memory sufficient for half the current number of items in the DPA, and fails if it cannot get this memory from the process heap.

The function sorts by separating into two, sorting each half and merging the sorted halves. The sorting of each half becomes a sorting of two quarters, and so on. Whenever a reduction through halves, quarters, eighths, etc, reaches two items, the caller-defined comparison function is called to discover which of the two items is to appear earlier in the sorted list. The same comparison function is also called to determine the ordering of pairs when merging two halves.

On all calls to the comparison function, the item at p1 was originally earlier in the list than was the item at p2. A positive result from the comparison function is a direction that the item at p1 ought instead appear after the item at p2. Note that either or both items in a comparison may be empty, i.e., that p1 or p2 or both may be NULL, if any user of the list has ever set empty positions in the list.

Variations

Versions before 6.10 simply assume that pfnCmp is not NULL.

Availability

The DPA_Sort function is exported from COMCTL32.DLL as ordinal 338 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 91 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.