dlls/comctl32/dsa.c

   1 /*
   2  * Dynamic structure array (DSA) implementation
   3  *
   4  * Copyright 1998 Eric Kohl
   5  *           1998 Juergen Schmied <j.schmied@metronet.de>
   6  *           2000 Eric Kohl for CodeWeavers
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2.1 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
  21  *
  22  * NOTES
  23  *     These functions were involuntarily documented by Microsoft in 2002 as
  24  *     the outcome of an anti-trust suit brought by various U.S. governments.
  25  *     As a result the specifications on MSDN are inaccurate, incomplete
  26  *     and misleading. A much more complete (unofficial) documentation is
  27  *     available at:
  28  *
  29  *     http://members.ozemail.com.au/~geoffch/samples/win32/shell/comctl32
  30  */
  31
  32 #include <stdarg.h>
  33
  34 #include "windef.h"
  35 #include "winbase.h"
  36 #include "winuser.h"
  37 #include "commctrl.h"
  38
  39 #include "comctl32.h"
  40 #include "wine/debug.h"
  41
  42 WINE_DEFAULT_DEBUG_CHANNEL(dsa);
  43
  44 struct _DSA
  45 {
  46     INT  nItemCount;
  47     LPVOID pData;
  48     INT  nMaxCount;
  49     INT  nItemSize;
  50     INT  nGrow;
  51 };
  52
  53 /**************************************************************************
  54  * DSA_Create [COMCTL32.320]
  55  *
  56  * Creates a dynamic storage array
  57  *
  58  * PARAMS
  59  *     nSize [I] size of the array elements
  60  *     nGrow [I] number of elements by which the array grows when it is filled
  61  *
  62  * RETURNS
  63  *     Success: pointer to an array control structure. Use this like a handle.
  64  *     Failure: NULL
  65  *
  66  * NOTES
  67  *     The DSA_ functions can be used to create and manipulate arrays of
  68  *     fixed-size memory blocks. These arrays can store any kind of data
  69  *     (e.g. strings and icons).
  70  */
  71 HDSA WINAPI DSA_Create (INT nSize, INT nGrow)
  72 {
  73     HDSA hdsa;
  74
  75     TRACE("(size=%d grow=%d)\n", nSize, nGrow);
  76
  77     hdsa = Alloc (sizeof(*hdsa));
  78     if (hdsa)
  79     {
  80         hdsa->nItemCount = 0;
  81         hdsa->pData = NULL;
  82         hdsa->nMaxCount = 0;
  83         hdsa->nItemSize = nSize;
  84         hdsa->nGrow = max(1, nGrow);
  85     }
  86
  87     return hdsa;
  88 }
  89
  90
  91 /**************************************************************************
  92  * DSA_Destroy [COMCTL32.321]
  93  *
  94  * Destroys a dynamic storage array
  95  *
  96  * PARAMS
  97  *     hdsa [I] pointer to the array control structure
  98  *
  99  * RETURNS
 100  *     Success: TRUE
 101  *     Failure: FALSE
 102  */
 103 BOOL WINAPI DSA_Destroy (HDSA hdsa)
 104 {
 105     TRACE("(%p)\n", hdsa);
 106
 107     if (!hdsa)
 108         return FALSE;
 109
 110     if (hdsa->pData && (!Free (hdsa->pData)))
 111         return FALSE;
 112
 113     return Free (hdsa);
 114 }
 115
 116
 117 /**************************************************************************
 118  * DSA_GetItem [COMCTL32.322]
 119  *
 120  * Copies the specified item into a caller-supplied buffer.
 121  *
 122  * PARAMS
 123  *     hdsa   [I] pointer to the array control structure
 124  *     nIndex [I] number of the Item to get
 125  *     pDest  [O] destination buffer. Has to be >= dwElementSize.
 126  *
 127  * RETURNS
 128  *     Success: TRUE
 129  *     Failure: FALSE
 130  */
 131 BOOL WINAPI DSA_GetItem (HDSA hdsa, INT nIndex, LPVOID pDest)
 132 {
 133     LPVOID pSrc;
 134
 135     TRACE("(%p %d %p)\n", hdsa, nIndex, pDest);
 136
 137     if (!hdsa)
 138         return FALSE;
 139     if ((nIndex < 0) || (nIndex >= hdsa->nItemCount))
 140         return FALSE;
 141
 142     pSrc = (char *) hdsa->pData + (hdsa->nItemSize * nIndex);
 143     memmove (pDest, pSrc, hdsa->nItemSize);
 144
 145     return TRUE;
 146 }
 147
 148
 149 /**************************************************************************
 150  * DSA_GetItemPtr [COMCTL32.323]
 151  *
 152  * Retrieves a pointer to the specified item.
 153  *
 154  * PARAMS
 155  *     hdsa   [I] pointer to the array control structure
 156  *     nIndex [I] index of the desired item
 157  *
 158  * RETURNS
 159  *     Success: pointer to an item
 160  *     Failure: NULL
 161  */
 162 LPVOID WINAPI DSA_GetItemPtr (HDSA hdsa, INT nIndex)
 163 {
 164     LPVOID pSrc;
 165
 166     TRACE("(%p %d)\n", hdsa, nIndex);
 167
 168     if (!hdsa)
 169         return NULL;
 170     if ((nIndex < 0) || (nIndex >= hdsa->nItemCount))
 171         return NULL;
 172
 173     pSrc = (char *) hdsa->pData + (hdsa->nItemSize * nIndex);
 174
 175     TRACE("-- ret=%p\n", pSrc);
 176
 177     return pSrc;
 178 }
 179
 180
 181 /**************************************************************************
 182  * DSA_SetItem [COMCTL32.325]
 183  *
 184  * Sets the contents of an item in the array.
 185  *
 186  * PARAMS
 187  *     hdsa   [I] pointer to the array control structure
 188  *     nIndex [I] index for the item
 189  *     pSrc   [I] pointer to the new item data
 190  *
 191  * RETURNS
 192  *     Success: TRUE
 193  *     Failure: FALSE
 194  */
 195 BOOL WINAPI DSA_SetItem (HDSA hdsa, INT nIndex, LPVOID pSrc)
 196 {
 197     INT  nSize, nNewItems;
 198     LPVOID pDest, lpTemp;
 199
 200     TRACE("(%p %d %p)\n", hdsa, nIndex, pSrc);
 201
 202     if ((!hdsa) || nIndex < 0)
 203         return FALSE;
 204
 205     if (hdsa->nItemCount <= nIndex) {
 206         /* within the old array */
 207         if (hdsa->nMaxCount > nIndex) {
 208             /* within the allocated space, set a new boundary */
 209             hdsa->nItemCount = nIndex + 1;
 210         }
 211         else {
 212             /* resize the block of memory */
 213             nNewItems =
 214                 hdsa->nGrow * ((((nIndex + 1) - 1) / hdsa->nGrow) + 1);
 215             nSize = hdsa->nItemSize * nNewItems;
 216
 217             lpTemp = ReAlloc (hdsa->pData, nSize);
 218             if (!lpTemp)
 219                 return FALSE;
 220
 221             hdsa->nMaxCount = nNewItems;
 222             hdsa->nItemCount = nIndex + 1;
 223             hdsa->pData = lpTemp;
 224         }
 225     }
 226
 227     /* put the new entry in */
 228     pDest = (char *) hdsa->pData + (hdsa->nItemSize * nIndex);
 229     TRACE("-- move dest=%p src=%p size=%d\n",
 230            pDest, pSrc, hdsa->nItemSize);
 231     memmove (pDest, pSrc, hdsa->nItemSize);
 232
 233     return TRUE;
 234 }
 235
 236
 237 /**************************************************************************
 238  * DSA_InsertItem [COMCTL32.324]
 239  *
 240  * Inserts an item into the array at the specified index.
 241  *
 242  * PARAMS
 243  *     hdsa   [I] pointer to the array control structure
 244  *     nIndex [I] index for the new item
 245  *     pSrc   [I] pointer to the element
 246  *
 247  * RETURNS
 248  *     Success: position of the new item
 249  *     Failure: -1
 250  */
 251 INT WINAPI DSA_InsertItem (HDSA hdsa, INT nIndex, LPVOID pSrc)
 252 {
 253     INT   nNewItems, nSize;
 254     LPVOID  lpTemp, lpDest;
 255
 256     TRACE("(%p %d %p)\n", hdsa, nIndex, pSrc);
 257
 258     if ((!hdsa) || nIndex < 0)
 259         return -1;
 260
 261     /* when nIndex >= nItemCount then append */
 262     if (nIndex >= hdsa->nItemCount)
 263          nIndex = hdsa->nItemCount;
 264
 265     /* do we need to resize ? */
 266     if (hdsa->nItemCount >= hdsa->nMaxCount) {
 267         nNewItems = hdsa->nMaxCount + hdsa->nGrow;
 268         nSize = hdsa->nItemSize * nNewItems;
 269
 270         lpTemp = ReAlloc (hdsa->pData, nSize);
 271         if (!lpTemp)
 272             return -1;
 273
 274         hdsa->nMaxCount = nNewItems;
 275         hdsa->pData = lpTemp;
 276     }
 277
 278     /* do we need to move elements ? */
 279     if (nIndex < hdsa->nItemCount) {
 280         lpTemp = (char *) hdsa->pData + (hdsa->nItemSize * nIndex);
 281         lpDest = (char *) lpTemp + hdsa->nItemSize;
 282         nSize = (hdsa->nItemCount - nIndex) * hdsa->nItemSize;
 283         TRACE("-- move dest=%p src=%p size=%d\n",
 284                lpDest, lpTemp, nSize);
 285         memmove (lpDest, lpTemp, nSize);
 286     }
 287
 288     /* ok, we can put the new Item in */
 289     hdsa->nItemCount++;
 290     lpDest = (char *) hdsa->pData + (hdsa->nItemSize * nIndex);
 291     TRACE("-- move dest=%p src=%p size=%d\n",
 292            lpDest, pSrc, hdsa->nItemSize);
 293     memmove (lpDest, pSrc, hdsa->nItemSize);
 294
 295     return nIndex;
 296 }
 297
 298
 299 /**************************************************************************
 300  * DSA_DeleteItem [COMCTL32.326]
 301  *
 302  * Deletes the specified item from the array.
 303  *
 304  * PARAMS
 305  *     hdsa   [I] pointer to the array control structure
 306  *     nIndex [I] index for the element to delete
 307  *
 308  * RETURNS
 309  *     Success: number of the deleted element
 310  *     Failure: -1
 311  */
 312 INT WINAPI DSA_DeleteItem (HDSA hdsa, INT nIndex)
 313 {
 314     LPVOID lpDest,lpSrc;
 315     INT  nSize;
 316
 317     TRACE("(%p %d)\n", hdsa, nIndex);
 318
 319     if (!hdsa)
 320         return -1;
 321     if (nIndex < 0 || nIndex >= hdsa->nItemCount)
 322         return -1;
 323
 324     /* do we need to move ? */
 325     if (nIndex < hdsa->nItemCount - 1) {
 326         lpDest = (char *) hdsa->pData + (hdsa->nItemSize * nIndex);
 327         lpSrc = (char *) lpDest + hdsa->nItemSize;
 328         nSize = hdsa->nItemSize * (hdsa->nItemCount - nIndex - 1);
 329         TRACE("-- move dest=%p src=%p size=%d\n",
 330                lpDest, lpSrc, nSize);
 331         memmove (lpDest, lpSrc, nSize);
 332     }
 333
 334     hdsa->nItemCount--;
 335
 336     /* free memory ? */
 337     if ((hdsa->nMaxCount - hdsa->nItemCount) >= hdsa->nGrow) {
 338         nSize = hdsa->nItemSize * hdsa->nItemCount;
 339
 340         lpDest = ReAlloc (hdsa->pData, nSize);
 341         if (!lpDest)
 342             return -1;
 343
 344         hdsa->nMaxCount = hdsa->nItemCount;
 345         hdsa->pData = lpDest;
 346     }
 347
 348     return nIndex;
 349 }
 350
 351
 352 /**************************************************************************
 353  * DSA_DeleteAllItems [COMCTL32.327]
 354  *
 355  * Removes all items and reinitializes the array.
 356  *
 357  * PARAMS
 358  *     hdsa [I] pointer to the array control structure
 359  *
 360  * RETURNS
 361  *     Success: TRUE
 362  *     Failure: FALSE
 363  */
 364 BOOL WINAPI DSA_DeleteAllItems (HDSA hdsa)
 365 {
 366     TRACE("(%p)\n", hdsa);
 367
 368     if (!hdsa)
 369         return FALSE;
 370     if (hdsa->pData && (!Free (hdsa->pData)))
 371         return FALSE;
 372
 373     hdsa->nItemCount = 0;
 374     hdsa->pData = NULL;
 375     hdsa->nMaxCount = 0;
 376
 377     return TRUE;
 378 }
 379
 380
 381 /**************************************************************************
 382  * DSA_EnumCallback [COMCTL32.387]
 383  *
 384  * Enumerates all items in a dynamic storage array.
 385  *
 386  * PARAMS
 387  *     hdsa     [I] handle to the dynamic storage array
 388  *     enumProc [I]
 389  *     lParam   [I]
 390  *
 391  * RETURNS
 392  *     none
 393  */
 394 VOID WINAPI DSA_EnumCallback (HDSA hdsa, PFNDSAENUMCALLBACK enumProc,
 395                               LPVOID lParam)
 396 {
 397     INT i;
 398
 399     TRACE("(%p %p %p)\n", hdsa, enumProc, lParam);
 400
 401     if (!hdsa)
 402         return;
 403     if (hdsa->nItemCount <= 0)
 404         return;
 405
 406     for (i = 0; i < hdsa->nItemCount; i++) {
 407         LPVOID lpItem = DSA_GetItemPtr (hdsa, i);
 408         if ((enumProc)(lpItem, lParam) == 0)
 409             return;
 410     }
 411
 412     return;
 413 }
 414
 415
 416 /**************************************************************************
 417  * DSA_DestroyCallback [COMCTL32.388]
 418  *
 419  * Enumerates all items in a dynamic storage array and destroys it.
 420  *
 421  * PARAMS
 422  *     hdsa     [I] handle to the dynamic storage array
 423  *     enumProc [I]
 424  *     lParam   [I]
 425  *
 426  * RETURNS
 427  *     none
 428  */
 429 void WINAPI DSA_DestroyCallback (HDSA hdsa, PFNDSAENUMCALLBACK enumProc,
 430                                  LPVOID lParam)
 431 {
 432     TRACE("(%p %p %p)\n", hdsa, enumProc, lParam);
 433
 434     DSA_EnumCallback (hdsa, enumProc, lParam);
 435     DSA_Destroy (hdsa);
 436 }
 437
 438 /**************************************************************************
 439  * DSA_Clone [COMCTL32.@]
 440  *
 441  * Creates a copy of a dsa
 442  *
 443  * PARAMS
 444  *     hdsa [I] handle to the dynamic storage array
 445  *
 446  * RETURNS
 447  *     Cloned dsa
 448  */
 449 HDSA WINAPI DSA_Clone(HDSA hdsa)
 450 {
 451     HDSA dest;
 452     INT i;
 453
 454     TRACE("(%p)\n", hdsa);
 455
 456     if (!hdsa)
 457         return NULL;
 458
 459     dest = DSA_Create (hdsa->nItemSize, hdsa->nGrow);
 460     if (!dest)
 461         return NULL;
 462
 463     for (i = 0; i < hdsa->nItemCount; i++) {
 464         void *ptr = DSA_GetItemPtr (hdsa, i);
 465         if (DSA_InsertItem (dest, DA_LAST, ptr) == -1) {
 466             DSA_Destroy (dest);
 467             return NULL;
 468         }
 469     }
 470
 471     return dest;
 472 }
 473
 474 /**************************************************************************
 475  * DSA_GetSize [COMCTL32.@]
 476  *
 477  * Returns allocated memory size for this array
 478  *
 479  * PARAMS
 480  *     hdsa [I] handle to the dynamic storage array
 481  *
 482  * RETURNS
 483  *     Size
 484  */
 485 ULONGLONG WINAPI DSA_GetSize(HDSA hdsa)
 486 {
 487     TRACE("(%p)\n", hdsa);
 488
 489     if (!hdsa) return 0;
 490
 491     return sizeof(*hdsa) + (ULONGLONG)hdsa->nMaxCount*hdsa->nItemSize;
 492 }