12.4. Open a Handle to the Kernel PlugIn


	Chapter 12. Creating a Kernel PlugIn Driver

To open a handle to a Kernel PlugIn driver, WD_KernelPlugIn() (see the WinDriver PCI Low-Level API Reference) needs to be called from the user mode. This low-level function is called both from WDC_KernelPlugInOpen() [B.3.17], and from the WDC_xxxDeviceOpen() functions (PCI [B.3.10] / PCMCIA [B.3.11] / ISA [B.3.12]) — when they are called with the name of a Kernel PlugIn driver.

When using the high-level WDC API [B.2] you can use either of the following methods to open a Kernel PlugIn handle:

First open a regular device handle — by calling the relevant WDC_xxxDeviceOpen() function without the name of a Kernel PlugIn driver. Then call WDC_KernelPlugInOpen(), passing to it the handle to the opened device. WDC_KernelPlugInOpen() opens a handle to the Kernel PlugIn driver, and stores it within the kerPlug field of the provided device structure [B.4.3].
Open a handle to the device, using the relevant WDC_xxxDeviceOpen() function, and pass the name of a Kernel PlugIn driver within the function's pcKPDriverName parameter. The device handle returned by the function will also contain (within the kerPlug field) a Kernel PlugIn handle opened by the function.
This method cannot be used to open a handle to a 64-bit Kernel PlugIn driver from a 32-bit application, or to open a Kernel PlugIn handle from a .NET application.


	To ensure that your code works correctly in all the supported configurations, use the first method described above.

The generated DriverWizard and the sample pci_diag shared library (xxx_lib.c / pci_lib.c) demonstrate how to open a handle to the Kernel PlugIn — see the generated/sample XXX_DeviceOpen()/PCI_DeviceOpen() library function (which is called from the generated/sample xxx_diag/pci_diag user-mode application).

The handle to the Kernel PlugIn driver is closed when the WD_KernelPlugInClose() function (see the WinDriver PCI Low-Level API Reference) is called from the user mode. When using the low-level WinDriver API, this function is called directly from the user-mode application. When using the high-level WDC API [B.2], the function is called automatically when calling WDC_xxxDeviceClose() (PCI [B.3.13] / PCMCIA [B.3.14] / ISA [B.3.15]) with a device handle that contains an open Kernel PlugIn handle. The function is also called by WinDriver as part of the application cleanup, for any identified open Kernel PlugIn handles.


	This method cannot be used to open a handle to a 64-bit Kernel PlugIn driver from a 32-bit application, or to open a Kernel PlugIn handle from a .NET application.


12.3. Create a New Kernel PlugIn Project		12.5. Set Interrupt Handling in the Kernel PlugIn