DevCon is a command-line tool that
displays detailed information about devices, and lets you search for and
manipulate devices from the command line. DevCon
enables, disables, installs, configures, and removes devices on the local
computer and displays detailed information about devices on local and remote
computers. DevCon is included in the Windows DDK.
This document describes
the DevCon source code, which is included in the
Windows DDK in the /src/setup/devcon directory. It
explains the DevCon design, and describes how to use
the SetupAPI and device installation functions to
enumerate devices and perform device operations in a console application.
For a complete
description of DevCon features and instructions for
using them, see the DevCon help file in the DDK
documentation in Driver Development Tools/Tools for Testing Drivers/DevCon.
These instructions
pertain to Windows XP and Windows Server 2003. DevCon
was designed for use on Windows 2000, Windows XP, and Windows Server 2003. It
will not work on Windows 95, Windows 98, or Windows ME.
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".
A few 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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
This
command allows you to add a Driver Package to the machine. The main functionality of this command
demonstrates the use of SetupCopyOEMInf. Adding a Driver
Package to the machine doesn’t mean the drivers are installed on devices, it
simply means the drivers are available automatically when a new device is
plugged in or a existing device is updated.
This
command allows you to uninstall a Driver Package from the machine. The main functionality of this command
demonstrates the use of SetupUninstallOEMInf.
Removing a Driver Package from the machine does not uninstall the drivers
associated with a device. If you want to accomplish both then use cmdRemove on all the devices using a given Driver Package
and then cmdDPDelete to remove the Driver Package
itself from the machine. This functionality is not available in Windows 2000 or
earlier.
This
command allows you to enumerate all of the 3rd party Driver Packages
currently installed on the machine and also shows you how to get some common
properties from a Driver Package (Provider, Class description, DriverVer date and version).
This
command shows you how to enumerate 3rd party Driver Packages on
Windows Server 2003 and earlier operating systems.
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.
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.
Shows how to get the
complete list of hardware ID's or compatible ID's for a device using SetupDiGetDeviceRegistryProperty.
Shows
how to obtain descriptive information about a device. The friendly name is used if it exists, otherwise the device description is used.
Shows
how to obtain an instance ID (or use any CFGMGR32 API) given HDEVINFO (device
info list) and PSP_DEVINFO_DATA (device info data).
Shows
how to interpret the information returned by CM_Get_DevNode_Status_Ex.
Refer to cfg.h for information returned by this API.
Shows
how to obtain information about resources used by a device.
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.
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.
This function determines
class and device upper and lower filters.
1. 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.
2. In a command window, change to the
directory containing the DevCon source code. For
example:
cd src\setup\devcon
3. Use the macro BLD or run the
following from the command prompt:
build –c
This invokes the Microsoft make routines that produce the Build.log, Build.wrn, and Build.err log files.
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).
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.
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".
Type "devcon find *" to list device instances of all present
devices on the local machine.
Type
"devcon status @root\rdp_mou\0000" to list
status of the terminal server mouse driver.
Type
"devcon status *PNP05*" to list status of
all COM ports.
|
File |
Description |
|
DevCon.htm |
Sample tour documentation for this binary (this file). |
|
DevCon.cpp |
Source file for tmain entry point and utility functions. |
|
Cmds.cpp |
Source file for supported commands. |
|
Dump.cpp |
Source file for functions that output information about devices. |
|
DevCon.h |
Header file for sample. |
|
DevCon.rc |
Resource file containing some strings and version information. |
|
rc_ids.h |
Header file for resources. |
|
Msg.mc |
Message file that is used to build msg.rc and msg.h used for help texts and other messages. |
|
Sources |
Generic file that lists source files and all the build options. |
|
Makefile |
File that redirects to the real make file that is shared by all the driver components of the Windows DDK. |
We welcome your comments, problem reports and wish-list requests. Please submit them by pointing your Internet browser to http://www.microsoft.com/ddk.
|
|
© 2004 Microsoft Corporation