Ports Class Installer

[This is preliminary documentation and subject to change.]

SUMMARY

This sample demonstrates a class installer and property page provider for the ports class of devices. The ports class is divided into two types of devices, COM (serial) ports and LPT or ECP (printer) ports. A separate property page is provided for each type of device. Furthermore, the class installer distinguishes both types of devices and installs each type of device differently.

Note: When using this sample, you need to code whatever is specific to your class. This sample is specific to port class only. Copying and pasting this code without modification may lead to disaster for other classes.
The sample runs on the x86 platform. It has only been tested in a 32-bit environment.

BUILDING THE SAMPLE

Enter the checked or free build environment. Then, while in the Class Installer sample directory, type build. A successful build produces the executable pnpports.dll.

RELEASE NOTES

CODE TOUR

File Manifest

 
File		Description
advandlg.c	Advanced dialog for COM port property page
ports.h		Ports header file
ports.c		Class Installer for the Ports clas
pp.c		Property Page Provider for COM ports
pp.h		Definitions for pp.c
pp_lpt.c	Property Page Provider for LPT and ECP ports
pp_lpt.h	Definitions for pp_lpt.c
util.c		Utility functions
ports.rc	Resources
ports.rc2	Resources
pnpports.def	Exports file
ports.htm	This file
Sources		needed to build
Makefile	needed to build

Programming Tour

This programming tour shows the specifics of the class installer and how the property pages are added and initialized.

The Class Installer

When the device is being installed, the class installer must first determine whether a COM or LPT port is being installed. The class installer relies on the .inf file that installed the device to write this value into the registry. The .inf must include an AddReg directive which writes a binary value named PortSubClass in the driver key for the device instance. Please see the sections [LptPort.AddReg], [EcpPort.AddReg], and [ComPort.AddReg] in msports.inf.

The class installer handles ths following DIF codes:

The handling DIF_INSTALLDEVICE is specific to the device type. This example demonstrates how to handle DIF_INSTALLDEVICE for COM ports. While the Ports Class installer shipped with the system also handles LPT ports in DIF_INSTALLDEVICE, this sample just informs Setup to perform the default installation.

The primary purpose of the COM ports class installer is to assign a port name, e.g. COM1, to the device and to create a friendly name for the device that includes the port name. Providing a unique name to the port can prove to be difficult; with that in mind, a COM name database was created. The API for the database resides in msports.dll (which pnpports.dll links against). The database provides concurrent access to the list of names that have already been claimed by other ports and modems.

The COM port class installer assigns a name to the port in this priority:

  1. The presence of a value named PortName in the device node. This value will have been written to the device node by either the class installer (if this is an upgrade) or by the mapper, a kernel component that creates devices based on what the BIOS reports.
  2. The presence of a value named DosDeviceName in the device node. This value will have been written to the device node by the ACPI driver.
  3. If the enumerator is ACPI or root (and the root enumerated flag is not set), then the first free port name, starting at COM1, is chosen.
  4. The COM name database is consulted and the next free port name is assigned to the device.

The friendly name for the device must now be set. This is done by concatenating the device description of the device with port name chosen for the device. For instance, if the device description is "Communications Port" and the chosen port name is COM2, then the friendly name would be "Communications Port (COM2)."

If the DIF code is DIF_REMOVE and the device is a COM port, the port name is freed from the COM name database.

Property Pages

The property pages are loaded using the EnumPropPages32 value in the device driver key of the registry. Please see the sections [LptPort.NT.AddReg] and [ComPort.NT.AddReg] in msports.inf to see how to correctly write the values via an .inf file.

When the property page provider function is called (SerialPortPropPageProvider or ParallelPortPropPageProvider), it sets the pfnCallback field of the PROPSHEETPAGEstructure. This is done so that the PPORT_PARAMS or PLPT_PORT_PARAMS structure that was previously allocated will be freed whether the page was created or not. Note that the property page is not created until the user chooses it for the first time.

Top of page

© Microsoft Corporation 1999