| #include <winmem32.h> |
| WORD Global32Alloc(dwSize, lpSelector, dwMaxSize, wFlags) | |||||
| DWORD dwSize; | /* size of block to allocate | */ | |||
| LPWORD lpSelector; | /* address of location for selector | */ | |||
| DWORD dwMaxSize; | /* maximum size of object | */ | |||
| WORD wFlags; | /* sharing flag, */ | ||||
The Global32Alloc function allocates a memory object to be used as a 16:32 (USE32) code or data segment and retrieves the selector portion of the 16:32 address of the memory object. The first byte of the object is at offset 0 from this selector.
dwSize
Specifies the initial size, in bytes, of the object to be allocated. This value must be in the range 1 through (16 megabytes – 64K).
lpSelector
Points to a 2-byte location in memory that receives the selector portion of the 16:32 address of the allocated object.
dwMaxSize
Specifies the maximum size, in bytes, that the object will reach when it is reallocated by the Global32Realloc function. This value must be in the range 1 through (16 megabytes – 64 K). If the application will never reallocate this memory object, the dwMaxSize parameter should be set to the same value as the dwSize parameter.
wFlags
Depends on the return value of the GetWinMem32Version function. If the return value is less than 0x0101, this parameter must be zero. If the return value is greater than or equal to 0x0101, this parameter can be set to GMEM_DDESHARE (to make the object shareable). Otherwise, this parameter should be zero. For more information about GMEM_DDESHARE, see the description of the GlobalAlloc function.
The return value is zero if the function is successful. Otherwise, it is an error value, which can be one of the following:
WM32_Insufficient_Mem
WM32_Insufficient_Sels
WM32_Invalid_Arg
WM32_Invalid_Flags
WM32_Invalid_Func
If the Global32Alloc function fails, the value to which the lpSelector parameter points is zero. If the function succeeds, lpSelector points to the selector of the object. The valid range of offsets for the object referenced by this selector is 0 through (but not including) dwSize.
In Windows 3.0 and later, the largest object that can be allocated is 0x00FF0000 (16 megabytes – 64K). This is the limitation placed on WINMEM32.DLL by the current Windows kernel.
The returned selector identifies a descriptor for a data segment that has the following attributes: read-write, expand-up, and big (B bit set). The descriptor privilege level (DPL) and the granularity (the G bit) are set at the system's discretion, so you should make no assumptions regarding these settings. Because the system sets the granularity, the size of the object (and the selector size limit) may be greater than the requested size by up to 4095 bytes (4K minus 1). The DPL and requestor privilege level (RPL) will be appropriate for a Windows application.
Note:
An application must not change the setting of any bits in the DPL or the RPL selector. Doing so can result in a system crash and will prevent the application from running on compatible platforms.
The allocated object is neither movable nor discardable but can be paged. An application should not page-lock a 32-bit memory object. Page-locking an object is useful only if the object contains code or data that is used at interrupt time, and 32-bit memory cannot be used at interrupt time.