DPA_Merge function

[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 WINAPI DPA_Merge(
  _Inout_ HDPA          hdpaDest,
  _In_    HDPA          hdpaSrc,
  _In_    DWORD         dwFlags,
  _In_    PFNDPACOMPARE pfnCompare,
  _In_    PFNDPAMERGE   pfnMerge,
  _In_    LPARAM        lParam
);

Parameters

hdpaDest [in, out]

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.

hdpaSrc [in]

Type: HDPA

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

dwFlags [in]

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.

ValueMeaning
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.

 

pfnCompare [in]

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.

pfnMerge [in]

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.

lParam [in]

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

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Dpa_dsa.h

DLL

Comctl32.dll (version 5.0 or later)

 

 

Show: