/// <summary>Indicates a failure on the DSA_InsertItem when returned.</summary>
publicconstintDA_ERR=-1;
/// <summary>Used by DSA_InsertItem to indicate that the item should be inserted at the end of the array.</summary>
publicconstintDA_LAST=0x7FFFFFFF;
/// <summary>Defines the prototype for the compare function used by <c>DSA_Sort</c>.</summary>
/// <param name="p1">
/// <para>Type: <c>void*</c></para>
/// <para>A pointer to the first item in the comparison.</para>
/// </param>
/// <param name="p2">
/// <para>Type: <c>void*</c></para>
/// <para>A pointer to the second item in the comparison.</para>
/// </param>
/// <param name="lParam">
/// <para>Type: <c><c>LPARAM</c></c></para>
/// <para>Additional data passed to pfnCmp.</para>
/// </param>
/// <returns>
/// <para>Type: <c>int</c></para>
/// <para>
/// The meaning of the return values depends on the function that uses this callback prototype. The return values for <c>DSA_Sort</c> are the following.
/// </para>
/// <para>
/// <list type="table">
/// <listheader>
/// <term>less than 0</term>
/// <term>If p1 should be sorted ahead of p2.</term>
/// </listheader>
/// <item>
/// <term>equal to 0</term>
/// <term>If p1 and p2 should be sorted together.</term>
/// <summary>Defines the prototype for the compare function used by <c>DSA_Sort</c> when the items being compared are constant objects.</summary>
/// <param name="p1">
/// <para>Type: <c>const void*</c></para>
/// <para>A pointer to the first item in the comparison.</para>
/// </param>
/// <param name="p2">
/// <para>Type: <c>const void*</c></para>
/// <para>A pointer to the second item in the comparison.</para>
/// </param>
/// <param name="lParam">
/// <para>Type: <c><c>LPARAM</c></c></para>
/// <para>Additional data passed to pfnCmp.</para>
/// </param>
/// <returns>
/// <para>Type: <c>int</c></para>
/// <para>The meaning of the return values depends on the function that uses this callback prototype. The return values for <c>DSA_Sort</c> are as follows:</para>
/// <para>
/// <list type="table">
/// <listheader>
/// <term>less than 0</term>
/// <term>If p1 should be sorted ahead of p2.</term>
/// </listheader>
/// <item>
/// <term>equal to 0</term>
/// <term>If p1 and p2 should be sorted together.</term>
/// <summary>Defines the prototype for the callback function used by dynamic structure array (DSA) and dynamic pointer array (DPA) functions.</summary>
/// <param name="p">
/// <para>Type: <c>void*</c></para>
/// <para>A pointer to the structure to be enumerated.</para>
/// </param>
/// <param name="pData">
/// <para>Type: <c>void*</c></para>
/// <para>The value that was passed in the pData parameter to function <c>DSA_EnumCallback</c>.</para>
/// </param>
/// <returns>
/// <para>Type: <c>int</c></para>
/// <para>
/// The return value is used to determine whether to terminate or continue the iteration. A return value of zero indicates that the iteration should
/// stop; nonzero indicates that the iteration should continue.
/// <summary>Defines the prototype for the merge function used by <c>DPA_Merge</c>.</summary>
/// <param name="uMsg">
/// <para>Type: <c><c>UINT</c></c></para>
/// <para>A message that instructs this function how to handle the merge. One of the following values.</para>
/// <para>
/// <list type="table">
/// <listheader>
/// <term>Value</term>
/// <term>Meaning</term>
/// </listheader>
/// <item>
/// <term>DPAMM_MERGE0x1</term>
/// <term>
/// Perform any additional processing needed when merging pvSrc into pvDest. The function should return a pointer to an item that contains the result of
/// the merge. The value returned by the merge function is stored into the destination, which overwrites the previous value. If the merge function
/// returns NULL, then the merge operation is abandoned.
/// </term>
/// </item>
/// <item>
/// <term>DPAMM_DELETE0x2</term>
/// <term>Perform any additional processing needed when a delete occurs as part of the merge. The function should return NULL.</term>
/// </item>
/// <item>
/// <term>DPAMM_INSERT0x3</term>
/// <term>
/// Perform any user-defined processing when the merge results in an item being inserted as part of the merge. The return value of this function should
/// point to the item result that is inserted as part of the merge. If the merge function returns NULL, then the merge operation is abandoned.
/// </term>
/// </item>
/// </list>
/// </para>
/// </param>
/// <param name="pvDest">
/// <para>Type: <c>void*</c></para>
/// <para>A pointer to the first item in the merge.</para>
/// </param>
/// <param name="pvSrc">
/// <para>Type: <c>void*</c></para>
/// <para>A pointer to the second item in the merge.</para>
/// </param>
/// <param name="lParam">
/// <para>Type: <c><c>LPARAM</c></c></para>
/// <para>Additional data that can be used by the merge callback.</para>
/// </param>
/// <returns>
/// A pointer to the item which results from the merge or <c>NULL</c> if there is a failure when <c>DPAMM_MERGE</c> or <c>DPAMM_INSERT</c> is used.
/// <summary>Defines the prototype for the merge function used by <c>DPA_Merge</c>, using constant values.</summary>
/// <param name="uMsg">
/// <para>Type: <c><c>UINT</c></c></para>
/// <para>A message that instructs this function how to handle the merge. One of the following values.</para>
/// <para>
/// <list type="table">
/// <listheader>
/// <term>Value</term>
/// <term>Meaning</term>
/// </listheader>
/// <item>
/// <term>DPAMM_MERGE0x1</term>
/// <term>
/// Perform any additional processing needed when merging p2 into p1. The function should return a pointer to an item that contains the result of the merge.
/// </term>
/// </item>
/// <item>
/// <term>DPAMM_DELETE0x2</term>
/// <term>Perform any additional processing needed when a delete occurs as part of the merge. The function should return NULL.</term>
/// </item>
/// <item>
/// <term>DPAMM_INSERT0x3</term>
/// <term>
/// Perform any user-defined processing when the merge results in an item being inserted as part of the merge. The return value of this function should
/// point to the item result that is inserted as part of the merge.
/// </term>
/// </item>
/// </list>
/// </para>
/// </param>
/// <param name="pvDest">
/// <para>Type: <c>const void*</c></para>
/// <para>A pointer to the destination item in the merge.</para>
/// </param>
/// <param name="pvSrc">
/// <para>Type: <c>const void*</c></para>
/// <para>A pointer to the source item in the merge.</para>
/// </param>
/// <param name="lParam">
/// <para>Type: <c><c>LPARAM</c></c></para>
/// <para>Additional data that can be used by the merge callback.</para>
/// </param>
/// <returns>
/// <para>Type: <c>const void*</c></para>
/// <para>A pointer to constant data which results from the merge, or <c>NULL</c> if there is a failure when DPAMM_MERGE or DPAMM_INSERT is used.</para>
/// Options determining the method used to merge the two arrays. DPAM_NORMAL, DPAM_UNION, and DPAM_UNION are mutually exclusive<76>only one of those flags
/// can be set, optionally in conjunction with DPAM_SORTED.
/// </summary>
[Flags]
publicenumDPAM
{
/// <summary>The arrays are presorted; skip sorting. If this flag is not set, the arrays are sorted before they are merged.</summary>
DPAM_SORTED=0x00000001,
/// <summary>
/// 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.
/// </summary>
DPAM_NORMAL=0x00000002,
/// <summary>
/// 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.
/// </summary>
DPAM_UNION=0x00000004,
/// <summary>
/// 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.
/// </summary>
DPAM_INTERSECT=0x00000008,
}
/// <summary>A message that instructs this function how to handle the merge.</summary>
publicenumDPAMM
{
/// <summary>
/// Perform any additional processing needed when merging pvSrc into pvDest. The function should return a pointer to an item that contains the result
/// of the merge. The value returned by the merge function is stored into the destination, which overwrites the previous value. If the merge function
/// returns NULL, then the merge operation is abandoned.
/// </summary>
DPAMM_MERGE=1,
/// <summary>Perform any additional processing needed when a delete occurs as part of the merge. The function should return NULL.</summary>
DPAMM_DELETE=2,
/// <summary>
/// Perform any user-defined processing when the merge results in an item being inserted as part of the merge. The return value of this function
/// should point to the item result that is inserted as part of the merge. If the merge function returns NULL, then the merge operation is abandoned.
/// </summary>
DPAMM_INSERT=3
}
/// <summary>Options for DPA_Search.</summary>
[Flags]
publicenumDPAS
{
/// <summary>Indicates that the DPA is sorted.</summary>
DPAS_SORTED=0x0001,
/// <summary>
/// This value is only valid in conjunction with DPAS_SORTED. If the item is not found, return the position where the item is expected to be found in
/// the sorted DPA.
/// </summary>
DPAS_INSERTBEFORE=0x0002,
/// <summary>
/// This value is only valid in conjunction with DPAS_SORTED. If the item is not found, return the position where the item is expected to be found in
/// the sorted DPA.
/// </summary>
DPAS_INSERTAFTER=0x0004
}
/// <summary>Inserts a new item at the end of a dynamic pointer array (DPA).</summary>
/// <param name="pdpa">A handle to a DPA.</param>
/// <param name="pitem">A pointer to the item that is to be inserted.</param>
/// <returns>Returns the index of the new item or , if the append action fails.</returns>
// int DPA_AppendPtr( HDPA pdpa, void *pitem); https://msdn.microsoft.com/en-us/library/windows/desktop/bb775585(v=vs.85).aspx
/// <para>[ <c>DPA_Clone</c> is available through Windows XP with Service Pack 2 (SP2). It might be altered or unavailable in subsequent versions.]</para>
/// <para>Duplicates a dynamic pointer array (DPA).</para>
/// </summary>
/// <param name="hdpaSource">
/// <para>Type: <c>const HDPA</c></para>
/// <para>A handle to an existing DPA to copy.</para>
/// </param>
/// <param name="hdpaNew">
/// <para>Type: <c>HDPA</c></para>
/// <para>When <c>NULL</c>, a new array is copied from hdpaSource.</para>
/// <para>
/// This parameter can also contain an array created with <c>DPA_Create</c> or <c>DPA_CreateEx</c>. The data is overwritten but the original delta size
/// and heap handle retained.
/// </para>
/// </param>
/// <returns>
/// <para>Type: <c>HDPA</c></para>
/// <para>The handle to the new or altered DPA (hdpaNew) if successful; otherwise, <c>NULL</c>.</para>
/// [ <c>DPA_DeleteAllPtrs</c> is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in
/// subsequent versions.]
/// </para>
/// <para>Removes all items from a dynamic pointer array (DPA) and shrinks the DPA accordingly.</para>
/// </summary>
/// <param name="pdpa">
/// <para>Type: <c>HDPA</c></para>
/// <para>Handle to a DPA.</para>
/// </param>
/// <returns>
/// <para>Type: <c><c>BOOL</c></c></para>
/// <para>Returns <c>TRUE</c> on success or <c>FALSE</c> on failure.</para>
/// [ <c>DPA_DestroyCallback</c> is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in
/// subsequent versions.]
/// </para>
/// <para>Calls pfnCB on each element of the dynamic pointer array (DPA), then frees the DPA.</para>
/// <para>[ <c>DPA_GetPtrIndex</c> is available through Windows XP with Service Pack 2 (SP2). It might be altered or unavailable in subsequent versions.]</para>
/// <para>Gets the index of a matching item found in a dynamic pointer array (DPA).</para>
/// </summary>
/// <param name="hdpa">
/// <para>Type: <c>HDPA</c></para>
/// <para>A handle to an existing DPA.</para>
/// </param>
/// <param name="pvoid">
/// <para>Type: <c>const void*</c></para>
/// <para>A pointer to an item to locate in hdpa.</para>
/// </param>
/// <returns>
/// <para>Type: <c>int</c></para>
/// <para>The index of the item pointed to by pvoid, if found; otherwise, -1.</para>
/// <summary>Gets the pointer to the internal pointer array of a dynamic pointer array (DPA).</summary>
/// <param name="hdpa">A handle to an existing DPA.</param>
/// <returns>Returns a pointer to the array of pointers managed by the DPA. To retrieve the number of pointers in the array, call macro <c>DPA_GetPtrCount</c>.</returns>
/// [ <c>DPA_InsertPtr</c> is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in
/// subsequent versions.]
/// </para>
/// <para>Inserts a new item at a specified position in a dynamic pointer array (DPA). If neccessary, the DPA expands to accommodate the new item.</para>
/// </summary>
/// <param name="pdpa">
/// <para>Type: <c>HDPA</c></para>
/// <para>A handle to a DPA.</para>
/// </param>
/// <param name="index">
/// <para>Type: <c>int</c></para>
/// <para>Tbe position where new item is to be inserted.</para>
/// </param>
/// <param name="p">
/// <para>Type: <c>void*</c></para>
/// <para>A pointer to the item that is to be inserted.</para>
/// </param>
/// <returns>
/// <para>Type: <c>int</c></para>
/// <para>Returns the index of the new item or , if the insertion fails.</para>
/// </returns>
// int WINAPI DPA_InsertPtr( HDPA pdpa, int index, void *p); https://msdn.microsoft.com/en-us/library/windows/desktop/bb775625(v=vs.85).aspx
/// <para>[ <c>DPA_Merge</c> is available through Windows XP with Service Pack 2 (SP2). It might be altered or unavailable in subsequent versions.]</para>
/// <para>Combines the contents of two dynamic pointer arrays (DPAs).</para>
/// </summary>
/// <param name="hdpaDest">
/// <para>Type: <c>HDPA</c></para>
/// <para>A handle to the first DPA. This array can be optionally presorted. When this function returns, contains the handle to the merged array.</para>
/// </param>
/// <param name="hdpaSrc">
/// <para>Type: <c>HDPA</c></para>
/// <para>A handle to the second DPA. This array can be optionally presorted.</para>
/// </param>
/// <param name="dwFlags">
/// <para>Type: <c><c>DWORD</c></c></para>
/// <para>
/// Options determining the method used to merge the two arrays. DPAM_NORMAL, DPAM_UNION, and DPAM_UNION are mutually exclusive<76>only one of those flags
/// can be set, optionally in conjunction with DPAM_SORTED.
/// </para>
/// <para>
/// <list type="table">
/// <listheader>
/// <term>Value</term>
/// <term>Meaning</term>
/// </listheader>
/// <item>
/// <term>DPAM_SORTED0x00000001</term>
/// <term>The arrays are presorted; skip sorting. If this flag is not set, the arrays are sorted before they are merged.</term>
/// </item>
/// <item>
/// <term>DPAM_NORMAL0x00000002</term>
/// <term>
/// 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.
/// </term>
/// </item>
/// <item>
/// <term>DPAM_UNION0x00000004</term>
/// <term>
/// 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.
/// </term>
/// </item>
/// <item>
/// <term>DPAM_INTERSECT0x00000008</term>
/// <term>
/// 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.
/// The <c>PFNDPACOMPARE</c> 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.
/// </para>
/// </param>
/// <param name="pfnMerge">
/// <para>Type: <c><c>PFNDPAMERGE</c></c></para>
/// <para>
/// The <c>PFNDPAMERGE</c> callback function that merges the contents when an element is found in both DPAs and is found to be the same item by <c>PFNDPACOMPARE</c>.
/// </para>
/// </param>
/// <param name="lParam">
/// <para>Type: <c><c>LPARAM</c></c></para>
/// <para>Additional parameter used to declare the basis of comparison upon which equality is determined.</para>
/// </param>
/// <returns>
/// <para>Type: <c><c>BOOL</c></c></para>
/// <para><c>TRUE</c> if successful; otherwise, <c>FALSE</c>.</para>
/// <para>A comparison function pointer. See <c>PFNDPACOMPARE</c> for the comparison function prototype.</para>
/// </param>
/// <param name="lParam">
/// <para>Type: <c><c>LPARAM</c></c></para>
/// <para>An additional parameter to be passed to pfnCmp.</para>
/// </param>
/// <param name="options">
/// <para>Type: <c><c>UINT</c></c></para>
/// <para>This parameter may be one or more of the following.</para>
/// <para>
/// <list type="table">
/// <listheader>
/// <term>Value</term>
/// <term>Meaning</term>
/// </listheader>
/// <item>
/// <term>DPAS_SORTED</term>
/// <term>Indicates that the DPA is sorted.</term>
/// </item>
/// <item>
/// <term>DPAS_INSERTBEFORE</term>
/// <term>
/// This value is only valid in conjunction with DPAS_SORTED. If the item is not found, return the position where the item is expected to be found in the
/// sorted DPA.
/// </term>
/// </item>
/// <item>
/// <term>DPAS_INSERTAFTER</term>
/// <term>
/// This value is only valid in conjunction with DPAS_SORTED. If the item is not found, return the position where the item is expected to be found in the
/// sorted DPA.
/// </term>
/// </item>
/// </list>
/// </para>
/// </param>
/// <returns>
/// <para>Type: <c>int</c></para>
/// <para>Returns the index where the item was found in the DPA or if the item was not found.</para>
/// </returns>
// int WINAPI DPA_Search( HDPA pdpa, void *pFind, int iStart, PFNDPACOMPARE pfnCmp, LPARAM lParam, UINT options); https://msdn.microsoft.com/en-us/library/windows/desktop/bb775633(v=vs.85).aspx
/// [ <c>DPA_Sort</c> is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions.]
/// </para>
/// <para>Sorts the items in a Dynamic Pointer Array (DPA).</para>
/// <para>[ <c>DSA_DeleteItem</c> is available through Windows XP with Service Pack 2 (SP2). It might be altered or unavailable in subsequent versions.]</para>
/// <para>Deletes an item from a dynamic structure array (DSA).</para>
/// </summary>
/// <param name="hdsa">
/// <para>Type: <c>HDSA</c></para>
/// <para>A handle to an existing DSA.</para>
/// </param>
/// <param name="nPosition">
/// <para>Type: <c>int</c></para>
/// <para>The zero-based index of the item to delete.</para>
/// </param>
/// <returns>
/// <para>Type: <c><c>BOOL</c></c></para>
/// <para><c>TRUE</c> if the item was successfully deleted; otherwise, <c>FALSE</c>.</para>
/// [ <c>DSA_DestroyCallback</c> is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in
/// subsequent versions.]
/// </para>
/// <para>
/// Iterates through a dynamic structure array (DSA), calling a specified callback function on each item. Upon reaching the end of the array, the DSA is freed.
/// </para>
/// </summary>
/// <param name="pdsa">
/// <para>Type: <c>HDSA</c></para>
/// <para>A handle to a DSA to walk and destroy.</para>
/// <summary>Gets the size of the dynamic structure array (DSA).</summary>
/// <param name="hdsa">
/// <para>Type: <c>HDSA</c></para>
/// <para>A handle to an existing DSA.</para>
/// </param>
/// <returns>
/// <para>Type: <c><c>ULONGLONG</c></c></para>
/// <para>Returns the size of the DSA, including the internal bookkeeping information, in bytes. If hdsa is <c>NULL</c>, the function returns zero.</para>
/// <summary>Initializes a new instance of the <see cref="HDPA"/> class and assigns an existing handle.</summary>
/// <param name="preexistingHandle">An <see cref="IntPtr"/> object that represents the pre-existing handle to use.</param>
/// <param name="ownsHandle"><see langword="true"/> to reliably release the handle during the finalization phase; otherwise, <see langword="false"/> (not recommended).</param>
/// <summary>Initializes a new instance of the <see cref="HDSA"/> class and assigns an existing handle.</summary>
/// <param name="preexistingHandle">An <see cref="IntPtr"/> object that represents the pre-existing handle to use.</param>
/// <param name="ownsHandle"><see langword="true"/> to reliably release the handle during the finalization phase; otherwise, <see langword="false"/> (not recommended).</param>