genthunk.txt

《Delphi开发人员指南》配书原码

   dwBytes          Size of block pointed to by vp

   fProtectedMode   1 - upper 16 bits are treated as a selector in the local
                        descriptor table
                    0 - upper 16 bits are treated as a real-mode segment value

Returns

If the API is successful, the return value the 32-bit address. The return value
is NULL if the selector is invalid.

Comments

Limit checking is not performed in the retail build of Windows NT. It is
performed in the checked (debug) build of WOW32.DLL, which will cause NULL to
be returned when the limit is exceeded by the supplied offset.

----------

LPVOID WINAPI WOWGetVDMPointerFix(DWORD vp, 
                                  DWORD dwBytes,
                                  BOOL fProtectedMode);
VOID WINAPI WOWGetVDMPointerUnfix(DWORD vp);


The WOWGetVDMPointerFix is functionally equivalent to WOWGetVDMPointer on 
Windows NT.  However, on future releases of Windows this function
will call GlobalFix before returning the flat address, so that the 16-bit 
memory will not move around in linear space.  WOWGetVDMPointerUnFix will
GlobalUnFix the memory and return.

The reason for this is that while the 32-bit code called through Generic
Thunks is executing on Windows NT, no other 16-bit code will execute in that
VDM. As a result, the 16-bit memory will not move around in linear
(32-bit) memory.  However, this will not be the case on all platforms
that support these APIs.

Please note that Windows NT 3.5 does not GlobalFix the memory when you use
this call so if your thunks use callbacks (WOWCallback16 and WOWCallback16Ex)
then it is possible that the 16-bit memory will move around in linear space on
Windows NT during the callback. In that case you should either GlobalFix the 
memory before calling the thunk or discard all flat pointers and call 
WOWGetVDMPointer after returning from the callback.

Also, if you use any of the WOWGlobalAlloc16 family of APIs, its possible that
any 32-bit pointers that you have to 16-bit memory may become invalidated as the
16-bit heap is shuffled during the callback.

----------

WORD  WINAPI WOWGlobalAlloc16(WORD wFlags, DWORD cb);
WORD  WINAPI WOWGlobalFree16(WORD hMem);
DWORD WINAPI WOWGlobalLock16(WORD hMem);
BOOL  WINAPI WOWGlobalUnlock16(WORD hMem);

These APIs thunk to the 16-bit side and call the Win16 versions of 
these APIs.

----------

DWORD WINAPI WOWGlobalAllocLock16(WORD wFlags, DWORD cb, WORD *phMem);
WORD  WINAPI WOWGlobalUnlockFree16(DWORD vpMem);
DWORD WINAPI WOWGlobalLockSize16(WORD hMem, PDWORD pcb);

These APIs combine several common Win16 operations into one call
across the thunk.

----------

VOID WINAPI WOWYield16(VOID);
VOID WINAPI WOWDirectedYield16(WORD htask16);

These APIs, like the WOWGlobalAlloc16 family of APIs, thunk down to the
Win16 forms of these APIs to allow other tasks to run while the thunk
is doing a lengthy operation.  Note that 16-bit blocks of memory that have
not been GlobalFix'd may move in memory as a result of this call.

----------

DWORD WINAPI WOWCallback16(DWORD vpfn16, DWORD dwParam);

Used in 32-bit code called from 16-bit code via Generic Thunks to call back
to the 16-bit side (Generic Callback).

Parameters

   vpfn16   Pointer to 16-bit callback routine, which is passed from the
            16-bit side

   dwParam  Parameter for the 16-bit callback routine

Returns

The value comes from the callback routine. If the callback routine returns a
WORD instead of a DWORD, the upper 16 bits of the return value are undefined.
If the callback routine has no return value, the entire return value of this
API is undefined.

Comments

The 16-bit function to be called must be declared with one of the following
types:

   LONG FAR PASCAL CallbackRoutine(DWORD dwParam);

   -or-

   LONG FAR PASCAL CallbackRoutine(VOID FAR *vp);

depending on whether the parameter is a pointer or not.

NOTE: If you are passing a pointer, you'll need to get the pointer using
either WOWGlobalAlloc16() or WOWGlobalAllocLock16() (see wownt32.h).

----------

BOOL WINAPI WOWCallback16Ex(
              DWORD  vpfn16,
              DWORD  dwFlags,
              DWORD  cbArgs,
              PVOID  pArgs,
              PDWORD pdwRetCode
              );

Used in 32-bit code called from 16-bit code via Generic Thunks to call back
to the 16-bit side (Generic Callback).

Parameters

   vpfn16      Pointer to 16-bit callback routine, which is passed from the
               16-bit side

   dwFlags     WCB16_PASCAL - to call a _pascal callback routine (default)
               WCB16_CDECL  - to call a _cdecl callback routine

   cbArgs      Count of bytes in arguments (used to properly clean 16-bit stack)

   pArgs       Arguments for the callback routine

   pdwRetCode  The return code from the callback routine

Returns

If cbArgs is larger than the WCB16_MAX_ARGS which the system supports, the
return value is FALSE and GetLastError() returns ERROR_INVALID_PARAMETER.
Otherwise, the return value is TRUE and the DWORD pointed to by pdwRetCode
contains the return code from the callback routine. If the callback routine
returns a WORD, the HIWORD of the return code is undefined and should be
ignored by using LOWORD(dwRetCode).

Comments

WOWCallback16Ex() allows any combination of arguments up to WCB16_MAX_CBARGS
bytes total to be passed to the 16-bit callback routine. Regardless of the
value of cbArgs, WCB16_MAX_CBARGS bytes will always be copied from pArgs to the
16-bit stack. If pArgs is less than WCB16_MAX_CBARGS bytes from the end of a
page and the next page is inaccessible, WOWCallback16Ex() will incur an access
violation.

The arguments pointed to by pArgs must be in the correct order for the callback
routine's calling convention. For example, to call the PASCAL routine
SetWindowText()

   LONG FAR PASCAL SetWindowText(HWND hwnd, LPCSTR lpsz);

pArgs would point to an array of words:

   WORD SetWindowTextArgs[] = {OFFSETOF(lpsz), SELECTOROF(lpsz), hwnd};

In other words, the arguments are placed in the array in reverse order, with
the least significant word first for DWORDs and offset first for FAR pointers.

To call the CDECL routine wsprintf()

   LPSTR lpszFormat = "%d %s";
   int _cdecl wsprintf(lpsz, lpszFormat, nValue. lpszString);

pArgs would point to the array:

   WORD wsprintfArgs[] = {OFFSETOF(lpsz), SELECTOROF(lpsz),
                          OFFSETOF(lpszFormat), SELECTOROF(lpszFormat),
                          nValue,
                          OFFSETOF(lpszString), SELECTOROF(lpszString)};

In other words, the arguments are placed in the array in the order listed in
the function prototype with the least significant word first for DWORDs and
offset first for FAR pointers.

----------

HANDLE WINAPI WOWHandle32 (WORD, WOW_HANDLE_TYPE);
WORD WINAPI WOWHandle16 (HANDLE, WOW_HANDLE_TYPE);

These APIs (and the associated macros) are used to map a
16-bit handle to a 32-bit handle (and vice-versa).  These
APIs should be used in lieu of any private knowledge of
the relationship between a Win16 handle and a Win32 handle.

The reason is that the relationship between a Win16 handle
and a Win32 handle can change (and has done so between
Windows NT 3.1 and Windows NT 3.5).  We expect that they
may change in the future.

These APIs use the WOW_HANDLE_TYPE to indicate the type of
handle being translated.  Types supported include:
HWND, HMENU, HDWP, HDROP, HDC, HFONT, HMETAFILE, HRGN,
HBITMAP, HBRUSH, HPALETTE, HPEN, HACCEL, HTASK, FULLHWND

The WOW_HANDLE_TYPE corresponding to each of these is of
the form WOW_TYPE_<handle>, e.g. WOW_TYPE_HWND.

Also, there are macros in WOWNT32.H to use to map handles between
Win16 and Win32.  For example, to map a Win16 HWND to a Win32
HWND, you would use the HWND_32 macro (e.g. hWnd32 = HWND_32(hWnd16)).

A "full" hWnd is a hWnd that a Win32 app would see (and therefore can
be used in comparisons with 32-bit hWnds received from Win32 APIs.) 
The other hWnd type has a different value but is recognized by the 
system.  Please do not make assumptions about the relationship between
the 16-bit hWnd, the 32-bit Hwnd, and the 32-bit Full hWnd.  This
relationship has changed in the past (for performance reasons) and it
may change again in the future.