SUMMARY
This
sample demonstrates the handling of DIF_ calls during device installation and
the insertion of a property page into the install wizard and into the device
properties.
BUILDING THE SAMPLE
To build Irclass.dll,
select either the checked or free DDK environment, change to the directory Irclass, and type BUILD.
This sample is included
as part of Windows® 2000 for installing and configuring serial infrared
devices. The corresponding .inf file, Netirsir.inf, can be found in the \WinNt\Inf
directory after installation of the operating system.
CODE TOUR
File Manifest
Files Description
Irclass.htm The documentation for this sample (this file)
Sources The generic file for building the code sample
Irclass.c The only source code for this sample
Irclass.h Header for Irclass.c
Irclass.def DLL definition and exports
Irclass.rc Dialogs and string tables
Irexe.ico Icon for infrared devices
Makefile Standard makefile
Resource.h Microsoft Developer Studio generated include file
Programming Tour
This code tour focuses on
insertion of page into the install wizard.
The major topics covered
in this tour include the following.
- Device Coinstaller
- Property Page Provider
Device Coinstaller
Device Coinstallers are meant to handle special cases of
installation of which a generic class installer may not be aware.
Infrared devices are essentially network devices, and so the majority of the
installation is handled by the network class installer. There are details
about an infrared device of which the network class installer is unaware, such
as the selection of the serial port the device is attached to, and the device coinstaller mechanism is provided to extend the
functionality of a more generic class installer in these situations.
A device coinstaller is very similar to a regular class installer.
It receives each DIF_* call before the regular class installer does, but it
only needs to provide handlers for those DIF_* calls where it desires to modify
or extend the behavior or the regular class installer. In this sample, IrSIRClassCoinstaller is the main coinstaller
function, and it only handles two calls, DIF_INSTALLDEVICE and
DIF_NEWDEVICEWIZARD_FINISHINSTALL.
DIF_INSTALLDEVICE is
handled by the coinstaller to allow it to check and
modify the UPPERFILTER and LOWERFILTER values for the Irsir.sys
driver. Irsir.sys may use Serial.sys
as a lower filter, and it sets this value here. It reads the LowerFilters entry from Netirsir.inf,
and writes this value to the registry. It also clears the UPPERFILTER
value because Serial.sys may use Serenum.sys
as an upper filter, which is inappropriate for Irsir.sys.
DIF_INSTALLDEVICE is the most convenient place to do this because at
this point the driver has not yet been loaded.
DIF_NEWDEVICEWIZARD_FINISHINSTALL
is the coinstaller's best opportunity to prompt for
special parameters for the driver. The driver may have already been
started at this point, so you should ensure that your driver does not crash if
any parameter is not set yet. This function allows us to insert a final
page into the wizard to query the user. The PortSelectionDlg
function handles inserting the page, which will subsequently be invoked by the
install mechanism.
Property Page Provider
You should note that the
Property Page Provider and the Wizard page share a common message handling
function, PortDlgProc. Minor differences are
handled by the FirstTimeInstall flag which is set to
TRUE in the wizard page initialization code, and FALSE otherwise. At the
dialog completion, it calls WriteRegistrySettings,
which sets the flag DI_FLAGSEX_PROPCHANGE_PENDING. This is the cue to
the OS that a driver's settings have changed, and the driver needs to either
reload them or be restarted depending on its capabilities.
Top of page
© 1999 Microsoft
Corporation