动态数组API

Tags: /超级猛料/API.Windows应用程序接口/其他相关/   Date Created:

http://www.geocities.com/SiliconValley/4942/arrays.html  
Undocumented
Windows ? 95
 
Dynamic Array Routines
You may be wondering why anyone would want to use a bunch of undocumented array routines, with fairly  limited functionality, when the typical class library these days includes dozens of useful container classes. Well, if you're trying to keep your application as small as possible, it is essential that you make the most of the facilities already implemented by the operating system.
     There are two groups of array functions covered in this article: those that handle Dynamic Pointer Arrays (all pre-fixed with DPA), and those that handle Dynamic Structure 
Arrays (prefixed with DSA). I'm actually just guessing what DPA and DSA stand for, but I think it's a fairly plausible interpretation. The functions are all exported from COMCTL32.DLL, and they are all exported by ordinal.
Dynamic Pointer Arrays
Dynamic pointer arrays are the more versatile of the two array groups. In addition to resizing automatically as items are added and removed, they can also be sorted and searched using a callback comparison function. They even allow you to specify the heap that should be used for memory allocations. That may not sound particularly useful, until you realise that on Windows 95 these functions default to using the undocumented shared heap, which may not always be such a great idea.
     Their only real limitation is that the array items can only be four bytes in size. Typically the items would be pointers(hence the name 'Dynamic Pointer Array'), but they could
just as easily be integers or some other four byte data item.
If you do choose to use pointers, though, bare in mind that it is the application's responsibility to allocate and free those items.
The DPA Handle
Every array that you create is identified by a DPA handle. Each of the create functions return a handle, and all other functions require a handle as their first parameter. A DPA handle is just a pointer to a 20 byte structure containing information about the state of the array. Ideally you would just treat it as a generic HANDLE, but that isn't always possible. As an example, the only efficient way to obtain the array size, is by accessing the structure directly (see Figure 1 for the structure definition).
     nItems specifies the number of items in the array. nCapacity, on the other hand, specifies the maximum number of items that can be placed in the array before new storage will have to be allocated.

typedef struct {
 int     nItems;
 LPVOID *lpItems;
 HANDLE  hHeap;
 int     nCapacity;
 int     nDelta;
} * HDPA;

Figure 1  DPA Handle Structure
nDelta specifies the amount by which the array will grow whenever new storage is required. On NT, though, this delta value is doubled every time the array is resized(unless is it already greater than 255). lpItems is a pointer to the memory where the array items are stored and hHeap is the heap handle used to allocate that memory.    
Creating and Destroying

The functions for createing and destroying arrays can be seen in Figure 2. To create a new array, you would typically use the DPA_Create function (ordinal 328). It takes only one parameter, the delta size, and returns a DPA handle as the result. If you would like the array data to be allocated from a specific heap, you should use the DPA_CreateEx function (ordinal 340). It requires a second parameter, which specifies the handle of the heap to use. If hHeap is NULL, you just get default heap used by DPA_Create (on Windows 95 it's the undocumented shared heap; on Windows NT, though, it's just the process heap).
     The DPA_Clone function (ordinal 331) can be used to create a duplicate of an existing array, by passing the source handle as the first parameter and NULL as the second. If you want the new array to use a different delta size or a different  heap, you should create the array first with DPA_Create or DPA_CreateEx, and then pass that handle as the second parameter to DPA_Clone. Your new array will be 'overwritten' with the data from the source array, but it will keep its delta size and heap handle.

HDPA WINAPI DPA_Create(
 int nDelta);
HDPA WINAPI DPA_CreateEx(
 int nDelta,
 HANDLE hHeap);
HDPA WINAPI DPA_Clone(
 HDPA hSource,
 HDPA hDest);
BOOL WINAPI DPA_Destroy(
 HDPA hArray);

Figure 2  Create and Destroy Functions

     All of these function return the handle of the newly created array. If they fail for any reason, the return value will be NULL. When you are finished using an array, you should destroy it by passing the handle to DPA_Destroy (ordinal 329). The return value is TRUE if the array was destroyed successfully (it even returns TRUE if you pass it a NULL handle). The return value is FALSE if an error occured when freeing the data.    
Storing Values
The functions related to storing array items can be seen in Figure 3. The first function, DPA_InsertPtr (ordinal 334), will insert an item at a particular point in the array. If you try to insert an item beyond the end of the array, the item will be appended. Typically you would set the insert position to MAXINT if you wanted to append an item (a negative insert position will fail). The return value is the actual position at which the item was inserted, or -1 if the insertion failed.
     DPA_SetPtr, on the other hand, will store a value at a particular position in the array, overwriting the value that was previously there. It has an ordinal value of 335. If you attempt to store an item beyond the end of the array, the array will  be expanded so that the operation will succeed. The return value is TRUE if the operation was successful. If the operation fails, the function will return FALSE.