archive
/
windows-xp
mirror of https://github.com/tongzx/nt5src
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
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.
9 Commits
1 Branch
0 Tags
2.0 GiB
Tree: 75c48ba87f
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '75c48ba87f'
${ noResults }
windows-xp/Source/XPSP1/NT/base/pnp/tools/devcon/devcon.htm

212 lines
12 KiB
Raw Normal View History

Add source files
4 years ago
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
  1. <HTML>
  2. <HEAD>
  3. <TITLE>Text-mode Device Console Sample</TITLE>
  4. <META content="text/html; charset=windows-1252" http-equiv=Content-Type>
  5. <META content="Microsoft FrontPage 5.0" name=GENERATOR>
  6. </HEAD>
  8. <BODY link=#0000ff><FONT face=Verdana size=5>
  9. <H2>DevCon Sample</H2></FONT><FONT face=Verdana size=2>
  10. <P><SPAN style="COLOR: #ff0000; FONT-FAMILY: Arial; FONT-SIZE: 10pt">[This is
  11. preliminary documentation and subject to change.]</SPAN></P>
  13. <H3>SUMMARY</H3>
  14. This document accompanies the &quot;DevCon&quot; sample which is a text-mode
  15. device console. The instructions herein apply to the Windows XP operating
  16. system. DevCon has been designed for use on Windows 2000 and Windows XP. It will
  17. not work on Windows 95, Windows 98 or Windows ME.<p>The &quot;DevCon&quot; sample described in this article is a command line
  18. utility that acts as an alternative to Device Manager. The sample allows one or more
  19. devices to be enabled, disabled, restarted, updated, removed and queried. The
  20. sample demonstrates how to use SetupAPI and CfgMgr32 API's together effectively
  21. to enumerate devices and perform device operations.
  23. <H3>HOW IT WORKS</H3>
  25. <p>Running &quot;devcon help&quot; will provide a list of commands along with
  26. short descriptions of what each command does. &quot;devcon help
  27. &lt;command&gt;&quot; will give more detailed help on that command. The
  28. interpretation of each command is done via a dispatch table &quot;DispatchTable&quot;
  29. that is at the bottom of &quot;cmds.cpp&quot;. Some of the commands make use of
  30. a generic device enumerator &quot;EnumerateDevices&quot;. Some of these commands
  31. will work when given a remote target computer, and will also work if using the
  32. 32-bit devcon on Wow64.&nbsp; A description of some of the more interesting
  33. functions and the APIs they use follows:<h4>cmdClasses</h4>
  34. <p>This command demonstrates the use of SetupDiBuildClassInfoListEx to enumerate
  35. all device class GUID's. The function SetupDiClassNameFromGuidEx and
  36. SetupDiGetClassDescriptionEx are used to obtain more information about each
  37. device class.<h4>cmdListClass</h4>
  38. <p>This command demonstrates the use of SetupDiClassGuidsFromNameEx to enumerate
  40. one or more class GUID's that match the class name. This command also
  41. demonstrates the use of SetupDiGetClassDevsEx to list all the devices for each
  42. class GUID.<h4>cmdFind cmdFindAll cmdStatus</h4>
  43. <p>A simple use of EnumerateDevices (explained below) to list devices and
  44. display different levels of information about each device. Note that all but cmdFindAll use DIGCF_PRESENT to only list information about devices that are
  45. currently present. The main functionality for these and related devices is done
  46. inside FindCallback.<h4>cmdEnable cmdDisable cmdRestart</h4>
  47. <p>These&nbsp;commands show how to issue DIF_PROPERTYCHANGE to enable a device,
  48. disable a device, or restart a device. The main functionality for each of these
  49. commands is done inside ControlCallback.
  51. <p>These operations cannot be done on a remote machine or in the context of
  52. Wow64. CFGMGR32 API's should not be used as they skip class and co-installers.
  54. <h4>cmdUpdate</h4>
  56. <p>This command shows how to use UpdateDriverForPlugAndPlayDevices to update the
  57. driver for all devices to a specific driver. Normally INSTALLFLAG_FORCE would
  58. not be specified allowing UpdateDriverForPlugAndPlayDevices to determine if
  59. there is a better match already known. It's specified in DevCon to allow DevCon
  60. to be used more effectively as a debugging/testing tool. This cannot be done on
  61. a remote machine or in the context of Wow64.
  63. <h4>cmdInstall</h4>
  64. <p>A variation of cmdUpdate to install a driver when there is no associated
  65. hardware. It creates a new root-enumerated device instance and associates it
  66. with a made up hardware ID specified on the command line (which should correspond to a hardware ID
  67. in the INF). This cannot be done on a remote machine or in the context of Wow64.<h4>cmdRemove</h4>
  68. <p>A command to remove devices. Plug &amp; Play devices that are removed will
  69. reappear in response to cmdRescan. The main functionality of this command is in
  70. RemoveCallback that demonstrates the use of DIF_REMOVE. This cannot be done on a
  71. remote machine or in the context of Wow64. CFGMGR32 API's should not be used as
  72. they skip class and co-installers.<h4>cmdRescan</h4>
  73. <p>This command shows the correct way to rescan for all Plug &amp; Play devices
  74. that may have previously been removed, or that otherwise require a rescan to
  75. detect them.
  77. <h4>Reboot</h4>
  79. <p>This function shows how to correctly reboot the machine from a hardware
  80. install program. In particular it passes flags to ExitWindowsEx that cause the
  81. reboot to be associated with hardware installation. You should never reboot the
  82. machine unnecessarily.<h4>EnumerateDevices</h4>
  83. <p>Demonstrates the use of SetupDiGetClassDevsEx to enumerate all devices or all
  84. present devices, either globally or limited to a specific setup class.
  85. Demonstrates the use of SetupDiCreateDeviceInfoListEx to create a blank list
  86. associated with a class or not (for most cases, a blank list need not be
  87. associated with a class). Demonstrates the use of SetupDiOpenDeviceInfo to add a
  88. device instance into a device info list. These last two API's are ideal to
  89. obtain a DeviceInfoData structure from a device instance and machine name when
  90. mixing CFGMGR32 API's with SETUPAPI API's. SetupDiGetDeviceInfoListDetail is
  91. called to obtain a remote machine handle that may be passed into CFGMGR32 API's. SetupDiEnumDeviceInfo
  92. is called to enumerate each and every device that is in the device info list
  93. (either explicitly added, or determined by the call to SetupDiGetClassDevsEx).
  94. The instance ID is obtained by calling CM_Get_Device_ID_Ex, using information in
  95. devInfo (obtained from SetupDiEnumerateDeviceInfo) and devInfoListDetail
  96. (obtained from SetupDiGetDeviceInfoListDetail). GetHwIds is called to obtain
  97. a list of hardware and compatible ID's (explained below). Once an interesting
  98. device has been determined (typically by checking hardware ID's) then the callback is called to operate on that individual device.<h4>GetHwIds</h4>
  99. <p>Shows how to get the complete list of hardware ID's or compatible ID's for a
  100. device using SetupDiGetDeviceRegistryProperty.<h4>GetDeviceDescription</h4>
  101. <p>Shows how to obtain descriptive information about a device. The friendly name
  102. is used if it exists, otherwise the device description is used.<h4>DumpDeviceWithInfo</h4>
  103. <p>Shows how to obtain an instance ID (or use any CFGMGR32 API) given HDEVINFO
  104. (device info list) and PSP_DEVINFO_DATA (device info data).<h4>DumpDeviceStatus</h4>
  106. <p>Shows how to interpret the information returned by CM_Get_DevNode_Status_Ex.
  107. Refer to cfg.h for information returned by this API.
  109. <h4>DumpDeviceResources</h4>
  110. <p>Shows how to obtain information about resources used by a device.<h4>DumpDeviceDriverFiles</h4>
  111. <p>Provided as a debugging aid, obtains information about the files apparently
  112. being used for a device. It uses SetupDiBuildDriverInfoList to obtain
  113. information about the driver being used for the specified device. The driver
  114. list associated with a device may be enumerated by calling SetupDiEnumDriverInfo.
  115. In this case, there will be no more than one driver listed. This function
  116. proceeds to obtain a list of files that would normally be copied for this driver
  117. using DIF_INSTALLDEVICEFILES. SetupScanFileQueue is used to enumerate the file
  118. queue to display the list of files that are associated with the driver.<h4>DumpDeviceDriverNodes</h4>
  119. <p>Provided as a debugging aid, this function determines the list of compatible
  120. drivers for a device. It uses SetupDiBuildDriverInfoList to obtain the list of
  121. compatible drivers. In this case, all drivers are enumerated, however typically
  122. DIF_SELECTBESTCOMPATDRV and SetupDiGetSelectedDriver would be used together to
  123. find which driver the OS would consider to be the best.
  125. <h4>DumpDeviceStack</h4>
  126. <p>This function determines class and device upper and lower filters.
  128. <H3>BUILDING THE DEVCON SAMPLE</H3>
  129. <h5>To build the devcon sample:</h5>
  130. <ol><li>
  131. <p class="MsoListNumber">Click the Build Environment icon of choice in the
  132. Development Kits Build Environments sub-menu. This will set up the correct build
  133. environment to build this sample. Note that this sample will build in the 64-bit
  134. environments as well as the 32-bit environments.
  135. <li>
  136. <p class="MsoListNumber">In a command window, change to the directory containing the DevCon source code. For example:</li>
  137. <blockquote>
  138. <p><b>cd src\setup\devcon</b>
  139. </blockquote>
  140. <li>
  141. <p class="MsoListNumber">Use the macro BLD or run the following from the command prompt:
  142. </ol><blockquote>
  143. <p><b>build �c</b>
  144. <p>This invokes the Microsoft make routines that produce the Build.log, Build.wrn, and Build.err log files.
  145. <p>When the build completes, the executable will be placed in the ObjXXX\I386 subdirectory of the
  146. &lt;TARGETPATH&gt; directory specified in the Sources file (depending on build
  147. environment chosen).
  148. <p>If the build does not succeed, check for these errors: 1) the build environment is not set up
  149. properly, or 2) modifications made to the sample source code introduced errors.
  150. </blockquote>
  152. <H3>USING DEVCON</H3>
  153. <p>DevCon is provided in ready to run form in tools\devcon. For usage, refer to the document
  154. provided with devcon.exe.
  155. DevCon is a command line utility with built in documentation available by typing
  156. &quot;devcon help&quot;.
  158. <H3>TESTING</H3>
  160. <p>Type &quot;devcon find *&quot; to list device instances of all present
  161. devices on the local machine.</p>
  163. <p>Type &quot;devcon status @root\rdp_mou\0000&quot; to list status of the
  164. terminal server mouse driver.</p>
  166. <p>Type &quot;devcon status *PNP05*&quot; to list status of all COM ports.</p>
  168. <H3>CODE TOUR</H3>
  169. <H4>File Manifest</H4>
  170. </FONT><FONT face="Courier" size="3">
  171. <TABLE BORDER=0 CELLSPACING=1 CELLPADDING=0 width="916">
  172. <TR><TD width="151" valign="top"><U>File</u></TD><TD width="755"><u>Description<u></TD></TR>
  173. <TR><TD width="151" valign="top"><i>DevCon.htm</i></TD><TD width="755">Sample tour documentation for this binary (this file).</TD></TR>
  174. <tr>
  175. <TD width="151" valign="top"><i>DevCon.cpp</i></TD><TD width="755">Source file for
  176. tmain entry point and utility functions.</TD>
  177. </tr>
  178. <tr>
  179. <TD width="151" valign="top"><i>Cmds.cpp</i></TD><TD width="755">Source file for
  180. supported commands.</TD>
  181. </tr>
  182. <tr>
  183. <TD width="151" valign="top"><i>Dump.cpp</i></TD><TD width="755">Source file for
  184. functions that output information about devices.</TD>
  185. </tr>
  186. <TR><TD width="151" valign="top"><i>DevCon.h</i></TD><TD width="755">Header file
  187. for sample.</TD></TR>
  188. <TR><TD width="151" valign="top"><i>DevCon.rc</i></TD><TD width="755">Resource file
  189. containing some strings and version information.</TD></TR>
  190. <tr>
  191. <TD width="151" valign="top"><i>rc_ids.h</i></TD><TD width="755">Header file
  192. for resources.</TD>
  193. </tr>
  194. <TR><TD width="151" valign="top"><i>Msg.mc</i></TD><TD width="755">Message file
  195. that is used to build msg.rc and msg.h used for help texts and other
  196. messages.</TD></TR>
  197. <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>
  198. <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
  199. DDK.</TD></TR>
  200. </TABLE>
  202. <H3>FEEDBACK</H3>
  203. <P>We welcome your comments, problem reports and wish-list requests. Please
  204. submit them by pointing your Internet browser to <A href="http://www.microsoft.com/ddk">http://www.microsoft.com/ddk</A>.
  205. </FONT></P>
  206. <P align=center><FONT face=Verdana size=2><A href="#top">Top of page</A></P></FONT>
  207. <TABLE border=0" cellSpacing="0" width="624">
  208. <TR>
  209. <TD bgColor="#00ffff" height="2" vAlign="middle"></TD></TR></TABLE>
  210. <FONT face="MS Sans Serif" size=1>
  211. <P>&copy; Microsoft Corporation 2001</FONT><FONT face=Verdana size=2>
  212. </P></FONT>
  213. </BODY>