213 lines
12 KiB
HTML
213 lines
12 KiB
HTML
|
<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 "DevCon" 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 "DevCon" 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 "devcon help" will provide a list of commands along with
|
|||
|
|
short descriptions of what each command does. "devcon help
|
|||
|
|
<command>" will give more detailed help on that command. The
|
|||
|
|
interpretation of each command is done via a dispatch table "DispatchTable"
|
|||
|
|
that is at the bottom of "cmds.cpp". Some of the commands make use of
|
|||
|
|
a generic device enumerator "EnumerateDevices". Some of these commands
|
|||
|
|
will work when given a remote target computer, and will also work if using the
|
|||
|
|
32-bit devcon on Wow64. 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 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 & 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 & 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 <20>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
|
|||
|
|
<TARGETPATH> 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
|
|||
|
|
"devcon help".
|
|||
|
|
|
|||
|
|
<H3>TESTING</H3>
|
|||
|
|
|
|||
|
|
<p>Type "devcon find *" to list device instances of all present
|
|||
|
|
devices on the local machine.</p>
|
|||
|
|
|
|||
|
|
<p>Type "devcon status @root\rdp_mou\0000" to list status of the
|
|||
|
|
terminal server mouse driver.</p>
|
|||
|
|
|
|||
|
|
<p>Type "devcon status *PNP05*" 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>© Microsoft Corporation 2001</FONT><FONT face=Verdana size=2>
|
|||
|
|
</P></FONT>
|
|||
|
|
</BODY>
|