Infrared (Network) Class Coinstaller

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

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