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

- - - - - -

- -