You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
155 lines
6.4 KiB
155 lines
6.4 KiB
<HTML>
|
|
<HEAD>
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-
|
|
1252">
|
|
<META NAME="Generator" CONTENT="Microsoft Word 97">
|
|
<TITLE>Ports Class Installer
|
|
</TITLE>
|
|
</HEAD>
|
|
<BODY LINK="#0000ff">
|
|
|
|
<FONT FACE="Verdana" SIZE=5><H2>Ports Class Installer
|
|
</H2>
|
|
</FONT><FONT FACE="Verdana" SIZE=2>
|
|
<P><span style="color:#FF0000;font-size:10pt;font-family:Arial">[This is preliminary
|
|
documentation and subject to change.]</span></P>
|
|
|
|
<H3>SUMMARY</H3></FONT><FONT FACE="Verdana" SIZE=2>
|
|
<P>
|
|
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.
|
|
</P>
|
|
|
|
<blockquote>
|
|
<b>Note:</b> 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.
|
|
</blockquote>
|
|
|
|
The sample runs on the x86 platform. It has only been tested in a 32-bit environment.
|
|
|
|
<p>
|
|
<H3>BUILDING THE SAMPLE</H3></FONT><FONT FACE="Verdana"
|
|
SIZE=2><P>
|
|
|
|
Enter the checked or free build environment. Then,
|
|
while in the Class Installer sample directory, type <b>build</b>. A successful build produces
|
|
the executable <i>pnpports.dll.</i>
|
|
|
|
<H3>RELEASE NOTES</H3></FONT><FONT FACE="Verdana" SIZE=2><P>
|
|
|
|
<H3>CODE TOUR</H3>
|
|
<H4>File Manifest</H4>
|
|
</FONT>
|
|
<U><PRE>File		Description</U>
|
|
<I>advandlg.c</I>	Advanced dialog for COM port property page
|
|
<I>ports.h</I>	 Ports header file
|
|
<I>ports.c</I>	 Class Installer for the Ports clas
|
|
<I>pp.c</I>	 Property Page Provider for COM ports
|
|
<I>pp.h</I>	 Definitions for pp.c
|
|
<I>pp_lpt.c</I>	Property Page Provider for LPT and ECP ports
|
|
<I>pp_lpt.h</I>	Definitions for pp_lpt.c
|
|
<I>util.c</I>	 Utility functions
|
|
<I>ports.rc</I>	Resources
|
|
<I>ports.rc2</I>	Resources
|
|
<I>pnpports.def</I>	Exports file
|
|
<I>ports.htm</I>	This file
|
|
<I>Sources</I>	 needed to build
|
|
<I>Makefile</I>	needed to build
|
|
</pre>
|
|
|
|
<h4><font face="Verdana">Programming Tour</font></h4>
|
|
<font face="Verdana" size="2">
|
|
|
|
<p>This programming tour shows the specifics of the class installer and how the property
|
|
pages are added and initialized.</p>
|
|
|
|
<h5><font face="Verdana">The Class Installer</font></h5>
|
|
|
|
<p>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 <b>PortSubClass</b> in the driver key for the device instance. Please see
|
|
the sections [LptPort.AddReg], [EcpPort.AddReg], and [ComPort.AddReg] in
|
|
<I>msports.inf</I>.</p>
|
|
|
|
<p>The class installer handles ths following DIF codes:</p>
|
|
|
|
<font FACE="Verdana" SIZE="2">
|
|
<ul>
|
|
<li>DIF_INSTALLDEVICE</li>
|
|
<li>DIF_REMOVE</li>
|
|
</ul>
|
|
</font>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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 <I>msports.dll</I> (which <I>pnpports.dll</I> links against). The
|
|
database provides concurrent access to the list of names that have already
|
|
been claimed by other ports and modems.</p>
|
|
|
|
<p>The COM port class installer assigns a name to the port in this priority:
|
|
|
|
<font FACE="Verdana" SIZE="2">
|
|
<ol>
|
|
<li>The presence of a value named <B>PortName</B> 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.</li>
|
|
<li>The presence of a value named <B>DosDeviceName</B> in the device node. This
|
|
value will have been written to the device node by the ACPI driver.</li>
|
|
<li>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.</li>
|
|
<li>The COM name database is consulted and the next free port name is assigned
|
|
to the device.</li>
|
|
</ol>
|
|
</font>
|
|
|
|
</p>
|
|
|
|
<p>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)."</p>
|
|
|
|
<p>If the DIF code is DIF_REMOVE and the device is a COM port, the port name is freed from the
|
|
COM name database.</p>
|
|
|
|
<h5><font face="Verdana">Property Pages</font></h5>
|
|
|
|
<p>The property pages are loaded using the <B>EnumPropPages32</B> value in the device driver key of the registry. Please see the sections
|
|
[LptPort.NT.AddReg] and [ComPort.NT.AddReg] in <I>msports.inf</I> to see how to
|
|
correctly write the values via an .inf file.</p>
|
|
|
|
<p>When the property page provider function is called
|
|
(<B>SerialPortPropPageProvider</B> or <B>ParallelPortPropPageProvider</B>), it sets the
|
|
<I>pfnCallback</I> field of the <B>PROPSHEETPAGE</B>structure. This is done so that the
|
|
<B>PPORT_PARAMS</B> or <B>PLPT_PORT_PARAMS</B> 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.
|
|
</p>
|
|
|
|
</font>
|
|
<P ALIGN="CENTER"><A HREF="#top"><FONT FACE="Verdana" SIZE=2>
|
|
Top of page</FONT></A><FONT FACE="Verdana" SIZE=2> </P></FONT>
|
|
|
|
<TABLE CELLSPACING=0 BORDER=0 WIDTH=624>
|
|
<TR>
|
|
<TD VALIGN="MIDDLE" BGCOLOR="#00ffff" HEIGHT=2><P></TD>
|
|
</TR>
|
|
</TABLE>
|
|
|
|
<FONT FACE="MS Sans Serif" SIZE=1>
|
|
<P> © Microsoft Corporation 1999</FONT>
|
|
<FONT FACE="Verdana" SIZE=2> </P></FONT>
|
|
|
|
</BODY>
|