DPA_Clone

This function sets up one DPA to list the same items as another.

Declaration

HDPA
DPA_Clone (
    const HDPA hdpaSource,
    HDPA hdpaNew);

Parameters

The hdpaSource argument provides a handle to the DPA whose list of items is to be cloned.

The hdpaNew argument provides a handle to an existing (target) DPA that is to receive the cloned list, or is NULL to create a new DPA as the target.

Return Value

The function returns a handle to the target DPA if successful, else NULL for failure.

Behaviour

This function copies the pointer array from one DPA to another. The target DPA may exist already, but if hdpaNew is NULL, the function creates a new DPA as the target. If necessary, the target DPA grows to meet the capacity of the source DPA. If the target DPA existed already, then all its old pointers are lost.

Though the pointer array is duplicated exactly, other features are not necessarily. If a new DPA is created as the target, it is configured to use the same heap as the source DPA and it inherits the source DPA’s allocation unit. However, if an existing DPA is given as the target, it continues to use whatever heap was selected for it at creation and it retains its allocation unit. Growth of a pre-existing target whose allocation unit differs from the source DPA may result in the target ending with a greater capacity than the source. Whether the target is new or existed already, its allocation unit may increase as a side-effect of any growth in capacity.

A simple coding error in the function’s clean-up on failure affects almost all versions. The natural clean-up is that if the function creates a target DPA but then has to fail, it should destroy this new target that it created and that nobody can want. Instead, the function has its clean-up logic inverted: the function destroys the target on failure only if the target pre-existed. This error is fixed in the version 5.82 from Windows Vista and higher, and in version 6.10 and higher.

Availability

The DPA_Clone function is exported from COMCTL32.DLL as ordinal 331 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 73 in version 7.0 and higher.

Though this function dates from as long ago as 1995, it was still not documented by Microsoft in the MSDN Library at least as late as the CD edition dated January 2004.

This function has, however, got documented since then (in 2006 or perhaps some time during 2005). This article now uses Microsoft’s nomenclature.