| 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 reorders the items in a DPA.
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);
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.
The function returns TRUE if successful, else FALSE.
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.
The function succeeds trivially if the DPA is empty. The function 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 DPA_Sort function is exported from COMCTL32.DLL as ordinal 338 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.