Application Time and Shell Functions
Some THEORY
Application time is usually called "appy time". It simply means the time when the system VM is stable enough to allow interaction between VxDs and the ring-3 applications, especially 16-bit ones. For example, at appy time, VxDs can load and call functions in 16-bit DLLs. This appy time is not available under Windows 3.1x. Under Windows 3.1, a VxD can obtain the address of any function in a 16-bit DLL and simulate a far call to that address. However, this will interrupt whatever task the ring-3 program is doing resulting in VMM reentrancy. So the only APIs which VxDs can call are those that are interrupt-safe, ie PostMessage. Under Windows 95, a VxD can call almost any function in any 16 -bit dll with the help of a time. Simply Put, if Your Vxd Is Notified That Now Is The Appy Time, IT CAN Load 16-Bit Dlls and Call Functions in The Appy Time Is Arrived ? IT Must Register An Appy Time Event with the shell vxd .hen the system vm is in a stable stat, the Shell VxD will call the callback function that the VxD specified when it registered for an appy time event. Shell VxD will call your callback function only once for each registration for appy time event. It's like applying for a job. You go to a recruiting agency, register your name / telephone number with them. Then you go home. When a job is available, the agency phones you about the good news. When you acknowledge that news, they will never call you again. It may take some time before An apppy Time Event Is Available. Appy Time Events Are Not Available Under these Circumstances:
During System Startup and Shutdown When System VM IS in a critical section or waiting for a semaphoremanaging an apppy time evenet
You can register for an apppy time evenet by calling on _shell_callatappytime Which Has The Following Definition:
Vxdcall _shell_callatappytime, << Offset32 Pfncallback>, DwrefData, DWFLAGS, DWTIMEOUT>
pfnCallBackThe flat address of the callback function you want the Shell VxD to call when an appy time event occurs. The function will receive two parameters, dwRefData and dwFlags which are exactly identical to the two parameters you passed to _SHELL_CallAtAppyTime. Note that Shell VxD will call . your callback function with C Calling sequence In short, you have to define your callback function like this: BeginProc OnAppyTime, CCALL, PUBLIC ArgVar dwRefData, DWORD; declare argument name and type ArgVar dwFlags, DWORD EnterProc
.
Simply put, if you want to wait for the appy time event for some period only, use CAAFL_TIMEOUT flag. If you want to wait indefinitely for the appy time event, use NULL. I do not know what CAAFL_RING0 actually does.dwTimeoutThe period of .
This service is asynchronous, meaning that it returns immediately after registering your callback function for the appy time event. If this service call is successful, it returns the application time event handle in eax. If it fails, eax contains 0. You can cancel the appy time registration by calling on _SHELL_CancelAppyTimeEvent which takes only one parameter, the appy time event handle returned by _SHELL_CallAtAppyTime. to be on the safe side, prior to calling _SHELL_CallAtAppyTime, you should check the system if appy time event will be available. For example, what if you register for appy time event while the system is shutting down? Your VxD's callback will never be called! you can query the system wheter appy time event will be available by calling _SHELL_QueryAppyTimeAvailable. This service takes no parameter. It returns 0 in eax Ie the system is closing down or the message server got gp faults. this service doesn't tell you what now is the appy time: it only tells you that there may be appy time events In short, if you want to play safe, call _SHELL_QueryAppyTimeAvailable first and if it returns a nonzero value in eax, you can proceed to call _SHELL_CallAtAppyTime.Application-time Shell Services.
When Appy Time Is Reached, There Are Several Shell Services You Call:
_Shell_calldll _shell_freeelibrary _shell_getprocaddress _shell_loadlibrary _shell_localalocex _shell_localfree
Those Six Services Are Provided SO VXDS CAN CALL 16-BIT FUNCTION IN 16-Bit DLLS / EXE, SUCH AS WINHELP. HOWEVER, SINECE WEA MOVING ON To the 32-BIT World (AND 64-Bit, In the Future), i . I will not go into detail about them If you're interested, you can read about them in Windows 95/98 DDK documentation There are other application-time-only SHELL services which I think are more useful:. _SHELL_ShellExecute and _SHELL_BroadcastSystemMessage With _SHELL_BroadcastSystemMessage. , you can send a message to all top-level windows and all VxDs in one call! If the appy time is available, you can send messages to both windows and VxDs. If the appy time is not available, you can send messages only to ... VxDs _SHELL_ShellExecute is the ring-0 counterpart of ShellExecute function in ring-3 Actually it calls ring-3 ShellExecute to do the job With this Shell service, you can execute / open / print any file _SHELL_ShellExecute has the following definition.: Vxdcall _shell_shellexecute,
IT Takes Only One Parameter, The Flat Address of a Shexpacket Structure. It Returns The Value from Shellexecute In Eax. Let's Examine Shexpacket Structure In detail next.
shex_dwTotalSizeThe size in bytes of SHEXPACKET structure plus the optional parameter, rgchBaggage, which immediately follows this structure. I'll describe what rgchBaggage shortly.shex_dwSizeThe size in bytes of SHEXPACKET structure, not counting rgchBaggage. Combined with shex_dwTotalSize above, the SHELL VxD can calculate the size of rgchBaggage which is of arbitrary length.shex_ibOpThe operation you want to perform. If you specify 0, it means you want to open the file. If the file is an executable one, it executes it. If you want to perform other operation , you must specify the name of the operation somewhere in rgchBaggage and this field must contain the distance in bytes from the start of this SHEXPACKET structure to the first character of the ASCIIZ string that specifies the name of the operation you want to perform. The size Of shexpacket is 32 bytes. if The Operation String Immediately Follows The Shexpacket Structure, The Value In Shex_ibop Must Be 32. As To The List of the O perations you can perform, check ShellExecute. There are three operations defined, "open", "print" and "explore" .shex_ibFileThe relative distance from the start of this structure to the ASCIIZ string that is the name of the file you want to send To shellexecute, Just Like shex_ibop.Shex_ibparamsthe optional parameters you want to pass to the file specified in shex_ibfile. if the file is a document or you do '
t want to pass any parameter to it, use 0. If you want to pass some parameters to the file, put the parameter string somewhere after this structure and put the relative distance from the start of this structure to the string in this field. In short, just like shex_ibOp and shex_ibFile.shex_ibDirThe working directory. Specify 0 if you want to use the Windows directory else you can specify your preferred directory string somewhere after this structure and put the relative distance between the start of this structure and the directory string in this field.shex_dwReservedAs the name implied, it's reserved. Do not mess with it.shex_nCmdShowHow the application window should be shown. It's one of the value you normally pass to ShowWindow, ie. the SW_XXXX value. Look up those values in windows. INC.
All members are DWORDs in size. Now where is that rgchBaggage member I promised I would describe? It's a little difficult to explain. RgchBaggage is a member of SHEXPACKET structure but it can not be included into the structure definition because its size is arbitrary. Check shell .inc, you'd see that rgchBaggage is not defined in SHEXPACKET yet the Windows 9x DDK documentation asserts that it's a member of SHEXPACKET. What's rgchBaggage? It's simply an array of ASCIIZ strings that follows SHEXPACKET structure. Within this array, you can put the name of the operation you want to perform on the file, the name of the file, the parameters you want to pass to the file and the working directory. SHELL VxD obtains the offset of the string in rgchBaggage by adding the relative distance between the SHEXPACKET structure to the first byte of the string to the flat offset of the SHEXPACKET. For example, if the SHEXPACKET structure begins at 60000h, and the string immediately follows the structure, THE DISTANCE BETWEEN THE STRUCTURE AND THE STRING IS The Size of The Structure Itself, 32 Bytes (20H). So shell vxd knows That the string is located at address 60020h.THE EXAMPLE
This will be a very simple example just to show you how to register for an appy time event and use _SHELL_ShellExecute. The VxD will be a dynamic one which is loaded by a simple win32 application. When the user presses the "run Calculator" button, The Win32 App Calls DeviceIocontrol to ask the vxd to register for an apppy time Event and run cagc.exe which is located in the Windows Directory.
; ------------------------------------------------- --------------------------------; vxd source code; ------------- -------------------------------------------------- ----------------- .386p include /masm/include/vmm.inc include /masm/include/vwin32.inc include /masm/include/shell.incvxdname TextEqu
VXD_STATIC_DATA_SEG VXD_STATIC_DATA_ENDS
Vxd_locked_code_seg; ------------------------------------------------ ----------------------------; Remember: The name of the vxd must be uppercase else it Won't work / unload; -------------------------------------------------- ----------------------- Declare_virtual_device% vxdname,% vxdmajorversion,% vxdminorversion,% controlname, undefined_device_id, undefined_init_order
Begin_control_dispatch% vxdname control_dispatch w32_deviceiocontrol, ONDEVICEIOCONTROL END_CONTROL_DISPATCH% VxDName
BeginProc OnDeviceIoControl assume esi: ptr DIOCParams .if [esi] .dwIoControlCode == 1 VxDCall _SHELL_CallAtAppyTime, << OFFSET32 OnAppyTime>, 0,0,0> .endif xor eax, eax ret EndProc OnDeviceIoControl VXD_LOCKED_CODE_ENDS
VXD_PAGEABLE_CODE_SEG BeginProc OnAppyTime, CCALL ArgVar RefData, DWORD ArgVar TheFlag, DWORD EnterProc mov File.shex_dwTotalSize, sizeof SHEXPACKET add File.shex_dwTotalSize, sizeof EXEName mov File.shex_dwSize, sizeof SHEXPACKET mov File.shex_ibOp, 0 mov File.shex_ibFile, sizeof SHEXPACKET mov File .shex_ibParams, 0 mov File.shex_ibDir, 0 mov File.shex_dwReserved, 0 mov File.shex_nCmdShow, 1 VxDCall _SHELL_ShellExecute,
end
Analysis
The VXD WAITS for DeviceIocontrol Messages, Service No.1. When IT Receives, IT Registers for an Application Time Event.
Vxdcall _shell_callatappytime, << offset32 onappytime>, 0, 0, 0>
It passes the flat address of OnAppyTime function to _SHELL_CallAtAppyTime so that Shell VxD will call it when an appy time event occurs. We do not use any reference data and have no need for timeout so all three parameters following the flat address of OnAppyTime are zeroes . When An Appy Time Event Occurs, The Shell Vxd Calls ONAppyTime Function.
BeginProc onappytime, ccall
WE Declare A Function with BeginProc. Since The Shell Vxd Will Call Inappytime with c calling sequence, we need to specify ccall attribute.
Argvar RefData, DWORD Argvar Theflag, DWORD Enterproc ... LeaveProc Return
Since the Shell VxD will call OnAppyTime with two parameters, we must setup the stack frame accordingly ArgVar macro is for adjusting the stack frame for each of the argument passed to the function Its syntax is as follows..:
Argvar Varname, Size, Used
Varnameter. You can use any Any name you like. size is, of course, the size of the parameter in bytes. You can use byte, word, dword or 1, 2, 4. Used is usually omitted. Immediately following the ArgVar macros, we need to use EnterProc and LeaveProc macros to mark the beginning and the end of the instructions in the procedure so that the local variables and parameters can be accessed correctly. use return macro to return to the caller.mov File .shex_dwTotalSize, sizeof SHEXPACKET add File.shex_dwTotalSize, sizeof EXEName mov File.shex_dwSize, sizeof SHEXPACKET mov File.shex_ibOp, 0 mov File.shex_ibFile, sizeof SHEXPACKET mov File.shex_ibParams, 0 mov File.shex_ibDir, 0 mov File.shex_dwReserved, 0 Mov file.Shex_ncmdshow, 1 vxdcall _shell_shellexecute,
The instructions inside the procedure is simple: initialize the SHEXPACKET structure and call _SHELL_ShellExecute service Note that shex_dwTotalSize contains the combined size of the SHEXPACKET structure itself and the size of the string that follows it This is the simple case If the string doesn '... t immediately follow the structure, you must calculate the distance between the first byte of the structure and the last byte of the string yourself. shex_ibFile contains the size of the structure itself because the name of the program immediately follows the structure. shex_ibDir is zero meaning that we want to use the Windows directory as the working directory. Note that this does not mean the program must be in the windows directory. The program can be anywhere so long as Windows can find it. shex_nCmdShow is 1 which is the value SW_SHOWNORMAL .
File Shexpacket <> Exename DB "Calc.exe", 0
We define a shexpacket structure backed immediately by the name of the program. [Icion's win32 assembly homepage]
