Leaked source code of windows server 2003
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.

511 lines
16 KiB

  1. /*++ BUILD Version: 0001 // Increment this if a change has global effects
  2. Copyright (c) Microsoft Corporation. All rights reserved.
  3. Module Name:
  4. ntpnpapi.h
  5. Abstract:
  6. This module contains the user APIs for NT Plug and Play, along
  7. with any public data structures needed to call these APIs.
  8. This module should be included by including "nt.h".
  9. Author:
  10. Lonny McMichael (lonnym) 02/06/1995
  11. Revision History:
  12. --*/
  13. #ifndef _NTPNPAPI_
  14. #define _NTPNPAPI_
  15. #if _MSC_VER > 1000
  16. #pragma once
  17. #endif
  18. #include <cfg.h>
  19. #ifdef __cplusplus
  20. extern "C" {
  21. #endif
  22. //
  23. // Define the NtPlugPlayControl Classes
  24. //
  25. typedef enum _PLUGPLAY_EVENT_CATEGORY {
  26. HardwareProfileChangeEvent,
  27. TargetDeviceChangeEvent,
  28. DeviceClassChangeEvent,
  29. CustomDeviceEvent,
  30. DeviceInstallEvent,
  31. DeviceArrivalEvent,
  32. PowerEvent,
  33. VetoEvent,
  34. BlockedDriverEvent,
  35. InvalidIDEvent,
  36. MaxPlugEventCategory
  37. } PLUGPLAY_EVENT_CATEGORY, *PPLUGPLAY_EVENT_CATEGORY;
  38. typedef struct _PLUGPLAY_EVENT_BLOCK {
  39. //
  40. // Common event data
  41. //
  42. GUID EventGuid;
  43. PLUGPLAY_EVENT_CATEGORY EventCategory;
  44. PULONG Result;
  45. ULONG Flags;
  46. ULONG TotalSize;
  47. PVOID DeviceObject;
  48. union {
  49. struct {
  50. GUID ClassGuid;
  51. WCHAR SymbolicLinkName[1];
  52. } DeviceClass;
  53. struct {
  54. WCHAR DeviceIds[1];
  55. } TargetDevice;
  56. struct {
  57. WCHAR DeviceId[1];
  58. } InstallDevice;
  59. struct {
  60. PVOID NotificationStructure;
  61. WCHAR DeviceIds[1];
  62. } CustomNotification;
  63. struct {
  64. PVOID Notification;
  65. } ProfileNotification;
  66. struct {
  67. ULONG NotificationCode;
  68. ULONG NotificationData;
  69. } PowerNotification;
  70. struct {
  71. PNP_VETO_TYPE VetoType;
  72. WCHAR DeviceIdVetoNameBuffer[1]; // DeviceId<NULL>VetoName<NULL><NULL>
  73. } VetoNotification;
  74. struct {
  75. GUID BlockedDriverGuid;
  76. } BlockedDriverNotification;
  77. struct {
  78. WCHAR ParentId[1];
  79. } InvalidIDNotification;
  80. } u;
  81. } PLUGPLAY_EVENT_BLOCK, *PPLUGPLAY_EVENT_BLOCK;
  82. //
  83. //Define the Target Structure for PNP Notifications
  84. //
  85. typedef struct _PLUGPLAY_NOTIFY_HDR {
  86. USHORT Version;
  87. USHORT Size;
  88. GUID Event;
  89. } PLUGPLAY_NOTIFY_HDR, *PPLUGPLAY_NOTIFY_HDR;
  90. //
  91. // Define the custom notification for the u-mode
  92. // receipient of ReportTargetDeviceChange.
  93. // The following structure header is used for all other (i.e., 3rd-party)
  94. // target device change events. The structure accommodates both a
  95. // variable-length binary data buffer, and a variable-length unicode text
  96. // buffer. The header must indicate where the text buffer begins, so that
  97. // the data can be delivered in the appropriate format (ANSI or Unicode)
  98. // to user-mode recipients (i.e., that have registered for handle-based
  99. // notification via RegisterDeviceNotification).
  100. //
  101. typedef struct _PLUGPLAY_CUSTOM_NOTIFICATION {
  102. PLUGPLAY_NOTIFY_HDR HeaderInfo;
  103. //
  104. // Event-specific data
  105. //
  106. PVOID FileObject; // This field must be set to NULL by callers of
  107. // IoReportTargetDeviceChange. Clients that
  108. // have registered for target device change
  109. // notification on the affected PDO will be
  110. // called with this field set to the file object
  111. // they specified during registration.
  112. //
  113. LONG NameBufferOffset; // offset (in bytes) from beginning of
  114. // CustomDataBuffer where text begins (-1 if none)
  115. //
  116. UCHAR CustomDataBuffer[1]; // variable-length buffer, containing (optionally)
  117. // a binary data at the start of the buffer,
  118. // followed by an optional unicode text buffer
  119. // (word-aligned).
  120. //
  121. } PLUGPLAY_CUSTOM_NOTIFICATION, *PPLUGPLAY_CUSTOM_NOTIFICATION;
  122. //
  123. // Define an Asynchronous Procedure Call for PnP event notification
  124. //
  125. typedef
  126. VOID
  127. (*PPLUGPLAY_APC_ROUTINE) (
  128. IN PVOID PnPContext,
  129. IN NTSTATUS Status,
  130. IN PPLUGPLAY_EVENT_BLOCK PnPEvent
  131. );
  132. //
  133. // Define the NtPlugPlayControl Classes
  134. //
  135. typedef enum _PLUGPLAY_CONTROL_CLASS {
  136. PlugPlayControlEnumerateDevice,
  137. PlugPlayControlRegisterNewDevice,
  138. PlugPlayControlDeregisterDevice,
  139. PlugPlayControlInitializeDevice,
  140. PlugPlayControlStartDevice,
  141. PlugPlayControlUnlockDevice,
  142. PlugPlayControlQueryAndRemoveDevice,
  143. PlugPlayControlUserResponse,
  144. PlugPlayControlGenerateLegacyDevice,
  145. PlugPlayControlGetInterfaceDeviceList,
  146. PlugPlayControlProperty,
  147. PlugPlayControlDeviceClassAssociation,
  148. PlugPlayControlGetRelatedDevice,
  149. PlugPlayControlGetInterfaceDeviceAlias,
  150. PlugPlayControlDeviceStatus,
  151. PlugPlayControlGetDeviceDepth,
  152. PlugPlayControlQueryDeviceRelations,
  153. PlugPlayControlTargetDeviceRelation,
  154. PlugPlayControlQueryConflictList,
  155. PlugPlayControlRetrieveDock,
  156. PlugPlayControlResetDevice,
  157. PlugPlayControlHaltDevice,
  158. PlugPlayControlGetBlockedDriverList,
  159. MaxPlugPlayControl
  160. } PLUGPLAY_CONTROL_CLASS, *PPLUGPLAY_CONTROL_CLASS;
  161. //
  162. // Define a device control structure for
  163. // PlugPlayControlEnumerateDevice
  164. // PlugPlayControlRegisterNewDevice
  165. // PlugPlayControlDeregisterDevice
  166. // PlugPlayControlInitializeDevice
  167. // PlugPlayControlStartDevice
  168. // PlugPlayControlUnlockDevice
  169. // PlugPlayControlRetrieveDock
  170. // PlugPlayControlResetDevice
  171. // PlugPlayControlHaltDevice
  172. //
  173. typedef struct _PLUGPLAY_CONTROL_DEVICE_CONTROL_DATA {
  174. UNICODE_STRING DeviceInstance;
  175. ULONG Flags;
  176. } PLUGPLAY_CONTROL_DEVICE_CONTROL_DATA, *PPLUGPLAY_CONTROL_DEVICE_CONTROL_DATA;
  177. //
  178. // Control flags for PlugPlayControlEnumerateDevice
  179. //
  180. #define PNP_ENUMERATE_DEVICE_ONLY 0x00000001
  181. #define PNP_ENUMERATE_ASYNCHRONOUS 0x00000002
  182. //
  183. // Control flags for PlugPlayControlHaltDevice
  184. //
  185. #define PNP_HALT_ALLOW_NONDISABLEABLE_DEVICES 0x00000001
  186. //
  187. // Define control structure for
  188. // PlugPlayControlQueryAndRemoveDevice
  189. //
  190. typedef struct _PLUGPLAY_CONTROL_QUERY_AND_REMOVE_DATA {
  191. UNICODE_STRING DeviceInstance;
  192. ULONG Flags;
  193. PNP_VETO_TYPE VetoType;
  194. LPWSTR VetoName;
  195. ULONG VetoNameLength; // length in characters
  196. } PLUGPLAY_CONTROL_QUERY_AND_REMOVE_DATA, *PPLUGPLAY_CONTROL_QUERY_AND_REMOVE_DATA;
  197. //
  198. // Values for Flags in PLUGPLAY_CONTROL_QUERY_AND_REMOVE_DATA
  199. //
  200. #define PNP_QUERY_AND_REMOVE_NO_RESTART 0x00000001
  201. #define PNP_QUERY_AND_REMOVE_DISABLE 0x00000002
  202. #define PNP_QUERY_AND_REMOVE_UNINSTALL 0x00000004
  203. #define PNP_QUERY_AND_REMOVE_EJECT_DEVICE 0x00000008
  204. //
  205. // Define control structure for
  206. // PlugPlayControlUserResponse
  207. //
  208. typedef struct _PLUGPLAY_CONTROL_USER_RESPONSE_DATA {
  209. ULONG Response;
  210. PNP_VETO_TYPE VetoType;
  211. LPWSTR VetoName;
  212. ULONG VetoNameLength; // length in characters
  213. } PLUGPLAY_CONTROL_USER_RESPONSE_DATA, *PPLUGPLAY_CONTROL_USER_RESPONSE_DATA;
  214. //
  215. // Define control structure for
  216. // PlugPlayControlGenerateLegacyDevice
  217. //
  218. typedef struct _PLUGPLAY_CONTROL_LEGACY_DEVGEN_DATA {
  219. UNICODE_STRING ServiceName;
  220. LPWSTR DeviceInstance;
  221. ULONG DeviceInstanceLength;
  222. } PLUGPLAY_CONTROL_LEGACY_DEVGEN_DATA, *PPLUGPLAY_CONTROL_LEGACY_DEVGEN_DATA;
  223. //
  224. // Define control structure for
  225. // PlugPlayControlGetInterfaceDeviceList
  226. //
  227. typedef struct _PLUGPLAY_CONTROL_INTERFACE_LIST_DATA {
  228. UNICODE_STRING DeviceInstance;
  229. GUID *InterfaceGuid;
  230. PWSTR InterfaceList;
  231. ULONG InterfaceListSize;
  232. ULONG Flags;
  233. } PLUGPLAY_CONTROL_INTERFACE_LIST_DATA, *PPLUGPLAY_CONTROL_INTERFACE_LIST_DATA;
  234. //
  235. // Define control structure for
  236. // PlugPlayControlProperty
  237. //
  238. typedef struct _PLUGPLAY_CONTROL_PROPERTY_DATA {
  239. UNICODE_STRING DeviceInstance;
  240. ULONG PropertyType;
  241. PVOID Buffer;
  242. ULONG BufferSize;
  243. } PLUGPLAY_CONTROL_PROPERTY_DATA, *PPLUGPLAY_CONTROL_PROPERTY_DATA;
  244. //
  245. // Values for PropertyType in PLUGPLAY_CONTROL_PROPERTY_DATA
  246. //
  247. #define PNP_PROPERTY_PDONAME 0x00000001
  248. #define PNP_PROPERTY_BUSTYPEGUID 0x00000002
  249. #define PNP_PROPERTY_LEGACYBUSTYPE 0x00000003
  250. #define PNP_PROPERTY_BUSNUMBER 0x00000004
  251. #define PNP_PROPERTY_POWER_DATA 0x00000005
  252. #define PNP_PROPERTY_REMOVAL_POLICY 0x00000006
  253. #define PNP_PROPERTY_REMOVAL_POLICY_OVERRIDE 0x00000007
  254. #define PNP_PROPERTY_ADDRESS 0x00000008
  255. #define PNP_PROPERTY_REMOVAL_POLICY_HARDWARE_DEFAULT 0x0000000A
  256. #define PNP_PROPERTY_INSTALL_STATE 0x0000000B
  257. #define PNP_PROPERTY_LOCATION_PATHS 0x0000000C
  258. //
  259. // Define control structure for
  260. // PlugPlayControlDeviceClassAssociation
  261. //
  262. typedef struct _PLUGPLAY_CONTROL_CLASS_ASSOCIATION_DATA {
  263. UNICODE_STRING DeviceInstance;
  264. GUID *InterfaceGuid;
  265. UNICODE_STRING Reference; // OPTIONAL
  266. BOOLEAN Register; // TRUE if registering, FALSE if unregistering
  267. LPWSTR SymLink;
  268. ULONG SymLinkLength;
  269. } PLUGPLAY_CONTROL_CLASS_ASSOCIATION_DATA, *PPLUGPLAY_CONTROL_CLASS_ASSOCIATION_DATA;
  270. //
  271. // Define control structure for
  272. // PlugPlayControlGetRelatedDevice
  273. //
  274. typedef struct _PLUGPLAY_CONTROL_RELATED_DEVICE_DATA {
  275. UNICODE_STRING TargetDeviceInstance;
  276. ULONG Relation;
  277. LPWSTR RelatedDeviceInstance;
  278. ULONG RelatedDeviceInstanceLength;
  279. } PLUGPLAY_CONTROL_RELATED_DEVICE_DATA, *PPLUGPLAY_CONTROL_RELATED_DEVICE_DATA;
  280. //
  281. // Values for Relation in PLUGPLAY_CONTROL_RELATED_DEVICE_DATA
  282. //
  283. #define PNP_RELATION_PARENT 0x00000001
  284. #define PNP_RELATION_CHILD 0x00000002
  285. #define PNP_RELATION_SIBLING 0x00000003
  286. //
  287. // Define control structure for
  288. // PlugPlayControlGetInterfaceDeviceAlias
  289. //
  290. typedef struct _PLUGPLAY_CONTROL_INTERFACE_ALIAS_DATA {
  291. UNICODE_STRING SymbolicLinkName;
  292. GUID *AliasClassGuid;
  293. LPWSTR AliasSymbolicLinkName;
  294. ULONG AliasSymbolicLinkNameLength; // length in characters, incl. terminating NULL
  295. } PLUGPLAY_CONTROL_INTERFACE_ALIAS_DATA, *PPLUGPLAY_CONTROL_INTERFACE_ALIAS_DATA;
  296. //
  297. // Define control structure for
  298. // PlugPlayControlGetDeviceStatus
  299. //
  300. typedef struct _PLUGPLAY_CONTROL_STATUS_DATA {
  301. UNICODE_STRING DeviceInstance;
  302. ULONG Operation;
  303. ULONG DeviceStatus;
  304. ULONG DeviceProblem;
  305. } PLUGPLAY_CONTROL_STATUS_DATA, *PPLUGPLAY_CONTROL_STATUS_DATA;
  306. //
  307. // Values for Operation in PLUGPLAY_CONTROL_STATUS_DATA
  308. //
  309. #define PNP_GET_STATUS 0x00000000
  310. #define PNP_SET_STATUS 0x00000001
  311. #define PNP_CLEAR_STATUS 0x00000002
  312. //
  313. // Define control structure for
  314. // PlugPlayControlGetDeviceDepth
  315. //
  316. typedef struct _PLUGPLAY_CONTROL_DEPTH_DATA {
  317. UNICODE_STRING DeviceInstance;
  318. ULONG DeviceDepth;
  319. } PLUGPLAY_CONTROL_DEPTH_DATA, *PPLUGPLAY_CONTROL_DEPTH_DATA;
  320. //
  321. // Define control structure for
  322. // PlugPlayControlQueryDeviceRelations
  323. //
  324. typedef enum _PNP_QUERY_RELATION {
  325. PnpQueryEjectRelations,
  326. PnpQueryRemovalRelations,
  327. PnpQueryPowerRelations,
  328. PnpQueryBusRelations,
  329. MaxPnpQueryRelations
  330. } PNP_QUERY_RELATION, *PPNP_QUERY_RELATION;
  331. typedef struct _PLUGPLAY_CONTROL_DEVICE_RELATIONS_DATA {
  332. UNICODE_STRING DeviceInstance;
  333. PNP_QUERY_RELATION Operation;
  334. ULONG BufferLength; // length in characters, incl. double terminating NULL
  335. LPWSTR Buffer;
  336. } PLUGPLAY_CONTROL_DEVICE_RELATIONS_DATA, *PPLUGPLAY_CONTROL_DEVICE_RELATIONS_DATA;
  337. //
  338. // Define control structure for
  339. // PlugPlayControlTargetDeviceRelation
  340. //
  341. typedef struct _PLUGPLAY_CONTROL_TARGET_RELATION_DATA {
  342. HANDLE UserFileHandle;
  343. NTSTATUS Status;
  344. ULONG DeviceInstanceLen;
  345. LPWSTR DeviceInstance;
  346. } PLUGPLAY_CONTROL_TARGET_RELATION_DATA, *PPLUGPLAY_CONTROL_TARGET_RELATION_DATA;
  347. //
  348. // Define control structure for
  349. // PlugPlayControlQueryInstallList
  350. //
  351. typedef struct _PLUGPLAY_CONTROL_INSTALL_DATA {
  352. ULONG BufferLength; // length in characters, incl. double terminating NULL
  353. LPWSTR Buffer;
  354. } PLUGPLAY_CONTROL_INSTALL_DATA, *PPLUGPLAY_CONTROL_INSTALL_DATA;
  355. //
  356. // Define control structure for
  357. // PlugPlayControlRetrieveDock
  358. //
  359. typedef struct _PLUGPLAY_CONTROL_RETRIEVE_DOCK_DATA {
  360. ULONG DeviceInstanceLength;
  361. LPWSTR DeviceInstance;
  362. } PLUGPLAY_CONTROL_RETRIEVE_DOCK_DATA, *PPLUGPLAY_CONTROL_RETRIEVE_DOCK_DATA;
  363. //
  364. // Structures used by conflict detection
  365. // PlugPlayControlQueryConflictList
  366. //
  367. // PLUGPLAY_CONTROL_CONFLICT_LIST
  368. // is a header, followed by array of PLUGPLAY_CONTROL_CONFLICT_ENTRY,
  369. // followed immediately by PLUGPLAY_CONTROL_CONFLICT_STRINGS
  370. // DeviceType is translated between UserMode and KernelMode
  371. //
  372. typedef struct _PLUGPLAY_CONTROL_CONFLICT_ENTRY {
  373. ULONG DeviceInstance; // offset to NULL-terminated string for device instance in DeviceInstanceStrings
  374. ULONG DeviceFlags; // for passing flags back regarding the device
  375. ULONG ResourceType; // type of range that the conflict is with
  376. ULONGLONG ResourceStart; // start of conflicting address-range
  377. ULONGLONG ResourceEnd; // end of conflicting address-range
  378. ULONG ResourceFlags; // for passing flags back regarding the conflicting resource
  379. } PLUGPLAY_CONTROL_CONFLICT_ENTRY, *PPLUGPLAY_CONTROL_CONFLICT_ENTRY;
  380. #define PNP_CE_LEGACY_DRIVER (0x00000001) // DeviceFlags: DeviceInstance reports back legacy driver name
  381. #define PNP_CE_ROOT_OWNED (0x00000002) // DeviceFlags: Root owned device
  382. #define PNP_CE_TRANSLATE_FAILED (0x00000004) // DeviceFlags: Translation of resource failed, resource range not available for use
  383. typedef struct _PLUGPLAY_CONTROL_CONFLICT_STRINGS {
  384. ULONG NullDeviceInstance; // must be (ULONG)(-1) - exists immediately after ConflictsListed * PLUGPLAY_CONTROL_CONFLICT_ENTRY
  385. WCHAR DeviceInstanceStrings[1]; // first device instance string
  386. } PLUGPLAY_CONTROL_CONFLICT_STRINGS, *PPLUGPLAY_CONTROL_CONFLICT_STRINGS;
  387. typedef struct _PLUGPLAY_CONTROL_CONFLICT_LIST {
  388. ULONG Reserved1; // used by Win2k CfgMgr32
  389. ULONG Reserved2; // used by Win2k CfgMgr32
  390. ULONG ConflictsCounted; // number of conflicts that have been determined
  391. ULONG ConflictsListed; // number of conflicts in this list
  392. ULONG RequiredBufferSize; // filled with buffer size required to report all conflicts
  393. PLUGPLAY_CONTROL_CONFLICT_ENTRY ConflictEntry[1]; // each listed entry
  394. } PLUGPLAY_CONTROL_CONFLICT_LIST, *PPLUGPLAY_CONTROL_CONFLICT_LIST;
  395. typedef struct _PLUGPLAY_CONTROL_CONFLICT_DATA {
  396. UNICODE_STRING DeviceInstance; // device we're querying conflicts for
  397. PCM_RESOURCE_LIST ResourceList; // resource list containing a single resource
  398. ULONG ResourceListSize; // size of resource-list buffer
  399. PPLUGPLAY_CONTROL_CONFLICT_LIST ConflictBuffer; // buffer for return list
  400. ULONG ConflictBufferSize; // length of buffer
  401. ULONG Flags; // Incoming flags
  402. NTSTATUS Status; // return status
  403. } PLUGPLAY_CONTROL_CONFLICT_DATA, *PPLUGPLAY_CONTROL_CONFLICT_DATA;
  404. //
  405. // Define control structure for
  406. // PlugPlayControlGetBlockedDriverList
  407. //
  408. typedef struct _PLUGPLAY_CONTROL_BLOCKED_DRIVER_DATA {
  409. ULONG Flags;
  410. ULONG BufferLength; // size of buffer in bytes
  411. PVOID Buffer;
  412. } PLUGPLAY_CONTROL_BLOCKED_DRIVER_DATA, *PPLUGPLAY_CONTROL_BLOCKED_DRIVER_DATA;
  413. //
  414. // Plug and Play user APIs
  415. //
  416. NTSYSCALLAPI
  417. NTSTATUS
  418. NTAPI
  419. NtGetPlugPlayEvent(
  420. IN HANDLE EventHandle,
  421. IN PVOID Context OPTIONAL,
  422. OUT PPLUGPLAY_EVENT_BLOCK EventBlock,
  423. IN ULONG EventBufferLength
  424. );
  425. NTSYSCALLAPI
  426. NTSTATUS
  427. NTAPI
  428. NtPlugPlayControl(
  429. IN PLUGPLAY_CONTROL_CLASS PnPControlClass,
  430. IN OUT PVOID PnPControlData,
  431. IN ULONG PnPControlDataLength
  432. );
  433. #ifdef __cplusplus
  434. }
  435. #endif
  436. #endif // _NTPNPAPI_