Edit

DPA_Merge function (dpa_dsa.h)

  • Article

[DPA_Merge is available through Windows XP with Service Pack 2 (SP2). It might be altered or unavailable in subsequent versions.]

Combines the contents of two dynamic pointer arrays (DPAs).

Syntax

BOOL DPA_Merge(
  [in, out] HDPA         hdpaDest,
  [in]      HDPA         hdpaSrc,
  [in]      DWORD        dwFlags,
  [in]      PFNDACOMPARE pfnCompare,
  [in]      PFNDPAMERGE  pfnMerge,
  [in]      LPARAM       lParam
);

Parameters

[in, out] hdpaDest

Type: HDPA

A handle to the first DPA. This array can be optionally presorted. When this function returns, contains the handle to the merged array.

[in] hdpaSrc

Type: HDPA

A handle to the second DPA. This array can be optionally presorted.

[in] dwFlags

Type: DWORD

Options determining the method used to merge the two arrays. DPAM_NORMAL, DPAM_UNION, and DPAM_UNION are mutually exclusive—only one of those flags can be set, optionally in conjunction with DPAM_SORTED.

Value Meaning
DPAM_SORTED
0x00000001
 The arrays are presorted; skip sorting. If this flag is not set, the arrays are sorted before they are merged.
DPAM_NORMAL
0x00000002
 The final array consists of all of the elements originally present in hdpaDest. If any of those elements are also found in hdpaSrc, those elements are merged in the final array. The PFNDPAMERGE callback function is called with the DPAMM_MERGE message.

When this flag is set, the final size of the array at hdpaDest is the same as its initial size.
DPAM_UNION
0x00000004
 The final array is the union of all elements in both arrays. Elements found in both arrays are merged in the final array. Elements found in only one array or the other are added as found. When this flag is set, the PFNDPAMERGE callback function can be called with the DPAMM_MERGE or DPAMM_INSERT message.

The final size of the array is at least the size of the larger of hdpaDest and hdpaSrc, and at most the sum of the two.
DPAM_INTERSECT
0x00000008
 Only elements found in both hdpaSrc and hdpaDest are merged to form the final array. When this flag is set, the PFNDPAMERGE callback function can be called with the DPAMM_MERGE or DPAMM_DELETE message.

The final size of the array can range between 0 and the smaller of hdpaDest and hdpaSrc.

[in] pfnCompare

Type: PFNDPACOMPARE

The PFNDPACOMPARE callback function that compares two elements, one from each DPA, to determine whether they are the same item. If so, the callback function pointed to by pfnCompare is called.

[in] pfnMerge

Type: PFNDPAMERGE

The PFNDPAMERGE callback function that merges the contents when an element is found in both DPAs and is found to be the same item by PFNDPACOMPARE.

[in] lParam

Type: LPARAM

Additional parameter used to declare the basis of comparison upon which equality is determined.

Return value

Type: BOOL

TRUE if successful; otherwise, FALSE.

Remarks

DPA_Merge is not exported by name. To use it, you must use GetProcAddress and request ordinal 11 from ComCtl32.dll to obtain a function pointer.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header dpa_dsa.h
DLL Comctl32.dll (version 5.0 or later)