DevCon Sample

+ +

DevCon Sample

+ +

DEVCON

+ +

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.

+ +

ABOUT THIS DOCUMENT

+ +

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.

+ +

SCOPE

+ +

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.

+ +

HOW IT WORKS

+ +

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:

+ +

cmdClasses

+ +

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.

+ +

cmdListClass

+ +

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.

+ +

cmdFind cmdFindAll cmdStatus

+ +

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.

+ +

cmdEnable cmdDisable cmdRestart

+ +

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.

+ +

cmdUpdate

+ +

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.

+ +

cmdInstall

+ +

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.

+ +

cmdRemove

+ +

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.

+ +

cmdRescan

+ +

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.

+ +

cmdDPAdd

+ +

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.

+ +

cmdDPDelete

+ +

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.

+ +

cmdDPEnum

+ +

This +command allows you to enumerate all of the 3^rd 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).

+ +

cmdDPEnumLegacy

+ +

This +command shows you how to enumerate 3^rd party Driver Packages on +Windows Server 2003 and earlier operating systems.

+ +

Reboot

+ +

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.

+ +

EnumerateDevices

+ +

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.

+ +

GetHwIds

+ +

Shows how to get the +complete list of hardware ID's or compatible ID's for a device using SetupDiGetDeviceRegistryProperty.

+ +

GetDeviceDescription

+ +

Shows +how to obtain descriptive information about a device. The friendly name is used if it exists, otherwise the device description is used.

+ +

DumpDeviceWithInfo

+ +

Shows +how to obtain an instance ID (or use any CFGMGR32 API) given HDEVINFO (device +info list) and PSP_DEVINFO_DATA (device info data).

+ +

DumpDeviceStatus

+ +

Shows +how to interpret the information returned by CM_Get_DevNode_Status_Ex. +Refer to cfg.h for information returned by this API.

+ +

DumpDeviceResources

+ +

Shows +how to obtain information about resources used by a device.

+ +

DumpDeviceDriverFiles

+ +

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.

+ +

DumpDeviceDriverNodes

+ +

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.

+ +

DumpDeviceStack

+ +

This function determines +class and device upper and lower filters.

+ +

BUILDING THE DEVCON SAMPLE

+ +

To build the devcon +sample:

+ +

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. +
+ +

+ +

USING DEVCON

+ +

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".

+ +

TESTING

+ +

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.

+ +

CODE TOUR

+ +

File Manifest

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ 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. +

+ +

FEEDBACK

+ +

We welcome your comments, problem reports +and wish-list requests. Please submit them by pointing your Internet browser to +http://www.microsoft.com/ddk.

+ +

Top of page

+ + + + + +

+ +