Source code of Windows XP (NT5)
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.
 
 
 
 
 
 

213 lines
12 KiB

<HTML>
<HEAD>
<TITLE>Text-mode Device Console Sample</TITLE>
<META content="text/html; charset=windows-1252" http-equiv=Content-Type>
<META content="Microsoft FrontPage 5.0" name=GENERATOR>
</HEAD>
<BODY link=#0000ff><FONT face=Verdana size=5>
<H2>DevCon Sample</H2></FONT><FONT face=Verdana size=2>
<P><SPAN style="COLOR: #ff0000; FONT-FAMILY: Arial; FONT-SIZE: 10pt">[This is
preliminary documentation and subject to change.]</SPAN></P>
<H3>SUMMARY</H3>
This document accompanies the &quot;DevCon&quot; sample which is a text-mode
device console. The instructions herein apply to the Windows XP operating
system. DevCon has been designed for use on Windows 2000 and Windows XP. It will
not work on Windows 95, Windows 98 or Windows ME.<p>The &quot;DevCon&quot; sample described in this article is a command line
utility that acts as an alternative to Device Manager. The sample allows one or more
devices to be enabled, disabled, restarted, updated, removed and queried. The
sample demonstrates how to use SetupAPI and CfgMgr32 API's together effectively
to enumerate devices and perform device operations.
<H3>HOW IT WORKS</H3>
<p>Running &quot;devcon help&quot; will provide a list of commands along with
short descriptions of what each command does. &quot;devcon help
&lt;command&gt;&quot; will give more detailed help on that command. The
interpretation of each command is done via a dispatch table &quot;DispatchTable&quot;
that is at the bottom of &quot;cmds.cpp&quot;. Some of the commands make use of
a generic device enumerator &quot;EnumerateDevices&quot;. Some of these commands
will work when given a remote target computer, and will also work if using the
32-bit devcon on Wow64.&nbsp; A description of some of the more interesting
functions and the APIs they use follows:<h4>cmdClasses</h4>
<p>This command demonstrates the use of SetupDiBuildClassInfoListEx to enumerate
all device class GUID's. The function SetupDiClassNameFromGuidEx and
SetupDiGetClassDescriptionEx are used to obtain more information about each
device class.<h4>cmdListClass</h4>
<p>This command demonstrates the use of SetupDiClassGuidsFromNameEx to enumerate
one or more class GUID's that match the class name. This command also
demonstrates the use of SetupDiGetClassDevsEx to list all the devices for each
class GUID.<h4>cmdFind cmdFindAll cmdStatus</h4>
<p>A simple use of EnumerateDevices (explained below) to list devices and
display different levels of information about each device. Note that all but cmdFindAll use DIGCF_PRESENT to only list information about devices that are
currently present. The main functionality for these and related devices is done
inside FindCallback.<h4>cmdEnable cmdDisable cmdRestart</h4>
<p>These&nbsp;commands show how to issue DIF_PROPERTYCHANGE to enable a device,
disable a device, or restart a device. The main functionality for each of these
commands is done inside ControlCallback.
<p>These operations cannot be done on a remote machine or in the context of
Wow64. CFGMGR32 API's should not be used as they skip class and co-installers.
<h4>cmdUpdate</h4>
<p>This command shows how to use UpdateDriverForPlugAndPlayDevices to update the
driver for all devices to a specific driver. Normally INSTALLFLAG_FORCE would
not be specified allowing UpdateDriverForPlugAndPlayDevices to determine if
there is a better match already known. It's specified in DevCon to allow DevCon
to be used more effectively as a debugging/testing tool. This cannot be done on
a remote machine or in the context of Wow64.
<h4>cmdInstall</h4>
<p>A variation of cmdUpdate to install a driver when there is no associated
hardware. It creates a new root-enumerated device instance and associates it
with a made up hardware ID specified on the command line (which should correspond to a hardware ID
in the INF). This cannot be done on a remote machine or in the context of Wow64.<h4>cmdRemove</h4>
<p>A command to remove devices. Plug &amp; Play devices that are removed will
reappear in response to cmdRescan. The main functionality of this command is in
RemoveCallback that demonstrates the use of DIF_REMOVE. This cannot be done on a
remote machine or in the context of Wow64. CFGMGR32 API's should not be used as
they skip class and co-installers.<h4>cmdRescan</h4>
<p>This command shows the correct way to rescan for all Plug &amp; Play devices
that may have previously been removed, or that otherwise require a rescan to
detect them.
<h4>Reboot</h4>
<p>This function shows how to correctly reboot the machine from a hardware
install program. In particular it passes flags to ExitWindowsEx that cause the
reboot to be associated with hardware installation. You should never reboot the
machine unnecessarily.<h4>EnumerateDevices</h4>
<p>Demonstrates the use of SetupDiGetClassDevsEx to enumerate all devices or all
present devices, either globally or limited to a specific setup class.
Demonstrates the use of SetupDiCreateDeviceInfoListEx to create a blank list
associated with a class or not (for most cases, a blank list need not be
associated with a class). Demonstrates the use of SetupDiOpenDeviceInfo to add a
device instance into a device info list. These last two API's are ideal to
obtain a DeviceInfoData structure from a device instance and machine name when
mixing CFGMGR32 API's with SETUPAPI API's. SetupDiGetDeviceInfoListDetail is
called to obtain a remote machine handle that may be passed into CFGMGR32 API's. SetupDiEnumDeviceInfo
is called to enumerate each and every device that is in the device info list
(either explicitly added, or determined by the call to SetupDiGetClassDevsEx).
The instance ID is obtained by calling CM_Get_Device_ID_Ex, using information in
devInfo (obtained from SetupDiEnumerateDeviceInfo) and devInfoListDetail
(obtained from SetupDiGetDeviceInfoListDetail). GetHwIds is called to obtain
a list of hardware and compatible ID's (explained below). Once an interesting
device has been determined (typically by checking hardware ID's) then the callback is called to operate on that individual device.<h4>GetHwIds</h4>
<p>Shows how to get the complete list of hardware ID's or compatible ID's for a
device using SetupDiGetDeviceRegistryProperty.<h4>GetDeviceDescription</h4>
<p>Shows how to obtain descriptive information about a device. The friendly name
is used if it exists, otherwise the device description is used.<h4>DumpDeviceWithInfo</h4>
<p>Shows how to obtain an instance ID (or use any CFGMGR32 API) given HDEVINFO
(device info list) and PSP_DEVINFO_DATA (device info data).<h4>DumpDeviceStatus</h4>
<p>Shows how to interpret the information returned by CM_Get_DevNode_Status_Ex.
Refer to cfg.h for information returned by this API.
<h4>DumpDeviceResources</h4>
<p>Shows how to obtain information about resources used by a device.<h4>DumpDeviceDriverFiles</h4>
<p>Provided as a debugging aid, obtains information about the files apparently
being used for a device. It uses SetupDiBuildDriverInfoList to obtain
information about the driver being used for the specified device. The driver
list associated with a device may be enumerated by calling SetupDiEnumDriverInfo.
In this case, there will be no more than one driver listed. This function
proceeds to obtain a list of files that would normally be copied for this driver
using DIF_INSTALLDEVICEFILES. SetupScanFileQueue is used to enumerate the file
queue to display the list of files that are associated with the driver.<h4>DumpDeviceDriverNodes</h4>
<p>Provided as a debugging aid, this function determines the list of compatible
drivers for a device. It uses SetupDiBuildDriverInfoList to obtain the list of
compatible drivers. In this case, all drivers are enumerated, however typically
DIF_SELECTBESTCOMPATDRV and SetupDiGetSelectedDriver would be used together to
find which driver the OS would consider to be the best.
<h4>DumpDeviceStack</h4>
<p>This function determines class and device upper and lower filters.
<H3>BUILDING THE DEVCON SAMPLE</H3>
<h5>To build the devcon sample:</h5>
<ol><li>
<p class="MsoListNumber">Click the Build Environment icon of choice in the
Development Kits Build Environments sub-menu. This will set up the correct build
environment to build this sample. Note that this sample will build in the 64-bit
environments as well as the 32-bit environments.
<li>
<p class="MsoListNumber">In a command window, change to the directory containing the DevCon source code. For example:</li>
<blockquote>
<p><b>cd src\setup\devcon</b>
</blockquote>
<li>
<p class="MsoListNumber">Use the macro BLD or run the following from the command prompt:
</ol><blockquote>
<p><b>build –c</b>
<p>This invokes the Microsoft make routines that produce the Build.log, Build.wrn, and Build.err log files.
<p>When the build completes, the executable will be placed in the ObjXXX\I386 subdirectory of the
&lt;TARGETPATH&gt; directory specified in the Sources file (depending on build
environment chosen).
<p>If the build does not succeed, check for these errors: 1) the build environment is not set up
properly, or 2) modifications made to the sample source code introduced errors.
</blockquote>
<H3>USING DEVCON</H3>
<p>DevCon is provided in ready to run form in tools\devcon. For usage, refer to the document
provided with devcon.exe.
DevCon is a command line utility with built in documentation available by typing
&quot;devcon help&quot;.
<H3>TESTING</H3>
<p>Type &quot;devcon find *&quot; to list device instances of all present
devices on the local machine.</p>
<p>Type &quot;devcon status @root\rdp_mou\0000&quot; to list status of the
terminal server mouse driver.</p>
<p>Type &quot;devcon status *PNP05*&quot; to list status of all COM ports.</p>
<H3>CODE TOUR</H3>
<H4>File Manifest</H4>
</FONT><FONT face="Courier" size="3">
<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=0 width="916">
<TR><TD width="151" valign="top"><U>File</u></TD><TD width="755"><u>Description<u></TD></TR>
<TR><TD width="151" valign="top"><i>DevCon.htm</i></TD><TD width="755">Sample tour documentation for this binary (this file).</TD></TR>
<tr>
<TD width="151" valign="top"><i>DevCon.cpp</i></TD><TD width="755">Source file for
tmain entry point and utility functions.</TD>
</tr>
<tr>
<TD width="151" valign="top"><i>Cmds.cpp</i></TD><TD width="755">Source file for
supported commands.</TD>
</tr>
<tr>
<TD width="151" valign="top"><i>Dump.cpp</i></TD><TD width="755">Source file for
functions that output information about devices.</TD>
</tr>
<TR><TD width="151" valign="top"><i>DevCon.h</i></TD><TD width="755">Header file
for sample.</TD></TR>
<TR><TD width="151" valign="top"><i>DevCon.rc</i></TD><TD width="755">Resource file
containing some strings and version information.</TD></TR>
<tr>
<TD width="151" valign="top"><i>rc_ids.h</i></TD><TD width="755">Header file
for resources.</TD>
</tr>
<TR><TD width="151" valign="top"><i>Msg.mc</i></TD><TD width="755">Message file
that is used to build msg.rc and msg.h used for help texts and other
messages.</TD></TR>
<TR><TD width="151" valign="top"><i>Sources</i></TD><TD width="755">Generic file that lists source files and all the build options.</TD></TR>
<TR><TD width="151" valign="top"><i>Makefile</i></TD><TD width="755">File that redirects to the real make file that is shared by all the driver components of the Windows
DDK.</TD></TR>
</TABLE>
<H3>FEEDBACK</H3>
<P>We welcome your comments, problem reports and wish-list requests. Please
submit them by pointing your Internet browser to <A href="http://www.microsoft.com/ddk">http://www.microsoft.com/ddk</A>.
</FONT></P>
<P align=center><FONT face=Verdana size=2><A href="#top">Top of page</A></P></FONT>
<TABLE border=0" cellSpacing="0" width="624">
<TR>
<TD bgColor="#00ffff" height="2" vAlign="middle"></TD></TR></TABLE>
<FONT face="MS Sans Serif" size=1>
<P>&copy; Microsoft Corporation 2001</FONT><FONT face=Verdana size=2>
</P></FONT>
</BODY>