ID: Q180586
The information in this article applies to:
The Windows 95 Device Driver Kit display driver sample code uses the GlobalSmartPageLock() API, but this API is not documented in currently released development kits or the MSDN Library. This article documents the API for display driver developers.
UINT GlobalSmartPageLock(hglb) HGLOBAL hglb;
Parameters:
hglb - handle to the global memory object to be locked.
Return value:
This function does not return a value.
Comments:
This information is provided as a supplement to the Windows 95 Device Driver Kit sample code and documentation. Applications should not use the GlobalSmartPageLock() API since it violates several Windows programming practices.
The GlobalSmartPageLock() API was originally developed in Windows 3.0. It's purpose was to allow one system call to "smartly" lock a memory region regardless of how virtual memory paging is being managed. This API will internally determine if the operating system is paging through real mode MS- DOS drivers, or through protected mode Windows drivers. Based on this determination, GlobalSmartPageLock() will call either GlobalFix() or GlobalPageLock() API. Currently, it is very unlikely that a end-user will be using real mode MS-DOS drivers, so in most cases GlobalSmartPageLock() will call GlobalPageLock(). However, the display system driver developer cannot assume that this is always true, which is why the DDK sample code uses GlobalSmartPageLock().
See the comments below for GlobalPageLock() and GlobalFix(). The GlobalSmartPageLock() functionality is useful to the Windows system drivers during the initialization process. This article does not document the corresponding xxxUnlock API since the display driver is not unloaded while Windows is still running and there is no need to unlock the memory. This situation may change with new multiple monitor capabilities in future versions of Windows that will use dynamically loaded hardware devices. Please contact Microsoft Technical Support if you need more information.
The following information was copied from the Windows 3.1 SDK references:
Windows version 3.0:
UINT GlobalPageLock(hglb)
HGLOBAL hglb; /* selector of global memory to lock */
The GlobalPageLock function increments (increases by one) the page-lock
count for the memory associated with the given global selector. As long
as its page-lock count is nonzero, the data that the selector references
is guaranteed to remain in memory at the same physical address.
Parameters:
hglb - Specifies the selector of the memory to be page-locked.
Return Value:
The return value specifies the page-lock count after the function has
incremented it. If the function fails, the return value is zero.
Comments:
Because using this function violates preferred Windows programming
practices, an application should not use it unless absolutely necessary.
The function is intended to be used for dynamically allocated data that
must be accessed at interrupt time. For this reason, it must be called
only from a dynamic-link library (DLL). The GlobalPageLock function
increments the page-lock count for the block of memory, and the
GlobalPageUnlock function decrements (decreases by one) the page-lock
count. Page-locking operations can be nested, but each page-locking must
be balanced by a corresponding unlocking.
See also GlobalPageUnlock.
Windows version 3.0:
void GlobalFix(hglb)
HGLOBAL hglb; /* handle of object to fix */
The GlobalFix function prevents the given global memory object from
moving in linear memory. This function interferes with effective Windows
memory management and can result in linear-address fragmentation. Few
applications need to fix memory in linear address space.
Parameters:
hglb - Identifies the global memory object to be fixed in linear memory.
Return Value:
This function does not return a value.
Comments:
The object is locked into linear memory at its current address, and its
lock count is incremented (increased by one). Locked memory is not
subject to moving or discarding except when the memory object is being
reallocated by the GlobalReAlloc function. The object remains locked in
memory until its lock count is decreased to zero. Each time an
application calls the GlobalFix function for a memory object, it must
eventually call the GlobalUnfix function, which decrements (decreases by
one) the lock count for the object. Other functions also can affect the
lock count of a memory object. For a list of these functions, see the
description of the GlobalFlags function.
See also GlobalFlags, GlobalReAlloc, GlobalUnfix.
Windows 3.1 SDK
Windows 95 DDK
For additional information, please see the following article in the Microsoft Knowledge Base:
ARTICLE-ID: Q85329
TITLE : BUG: GlobalPageLock() Moves Memory Fixed by GlobalFix()
Version : WINDOWS:4.0
Platform : WINDOWS
Hardware : x86
Issue type : kbinfoLast Reviewed: June 24, 1998