This section contains information about the VWIN32 services. The VWIN32 VxD provides developers of VxDs with a variety of useful services, some of which may be used when implementing asynchronous procedure calls (APC), synchronization, and device input and output control.
Some of the VWIN32 services may be used for asynchronous procedure calls and synchronization. APCs and Win32 events are both mechanisms which can be used to synchronize ring 3 code with ring 0 code. You can create a ring 3 event, get a VxD handle to that event with the function OpenVxDHandle exported by KERNEL32, then use either _VWIN32_WaitSingleObject or _VWIN32_WaitMultipleObjects from ring 0 to wait on the event. These must be called from task time, and not from within VMM events.
To signal the event, you can use the standard ring 3 functions for setting or pulsing events, or you can use the ring 0 services _VWIN32_SetWin32Event and VWIN32_PulseWin32Event. The ring 0 Win32 event services can be called from within VMM events.
The services VWIN32_EnterCrstR0 and VWIN32_LeaveCrstR0 may be used to manage access to critical sections. To enable mutually exclusive access to a shared resource, each thread calls VWIN32_EnterCrstR0 to request ownership of the critical section before executing any section of code that accesses the protected resource. If another thread currently owns the critical section object, VWIN32_EnterCrstR0 blocks the execution of the calling thread indefinitely until the other thread releases its ownership. If the critical section object is currently unowned, the system grants ownership to the requesting thread so it can access the resource. When it has finished executing the protected code, the thread uses the VWIN32_LeaveCrstR0 function to relinquish ownership, enabling another thread to become owner and access the protected resource.
The VWIN32 services VWIN32_DIOCCompletionRoutine and VWIN32_GetCurrentProcessHandle are useful for VxDs that implement device input and output control (IOCTL) services. VWIN32_DIOCCompletionRoutine sets the state of the specified event object to signaled when I/O is complete. VxDs can use VWIN32_GetCurrentProcessHandle to tag the current device IOCTL connection or request with an ID. By using a process ID, the device can cleanup more easily on process termination.
There are a variety of other general purpose VWIN32 services such as _VWIN32_Get_Thread_Context, _VWIN32_Set_Thread_Context, VWIN32_GetCurrentDirectory, and VWIN32_TerminateApp. See the Reference section of this chapter for a complete listing of the various VWIN32 services.
The following VWIN32 services can only be called when the current VM is the system VM:
_VWIN32_PulseWin32Event
_VWIN32_ResetWin32Event
_VWIN32_SetWin32Event
_VWIN32_WaitMultipleObjects
_VWIN32_WaitSingleObject