1 /*++ 2 3 Copyright (c) Microsoft Corporation. All rights reserved. 4 5 _WdfVersionBuild_ 6 7 Module Name: 8 9 WdfWMI.h 10 11 Abstract: 12 13 This is the C interface for WMI support 14 15 Environment: 16 17 kernel mode only 18 19 Revision History: 20 21 --*/ 22 23 // 24 // NOTE: This header is generated by stubwork. Please make any 25 // modifications to the corresponding template files 26 // (.x or .y) and use stubwork to regenerate the header 27 // 28 29 #ifndef _WDFWMI_H_ 30 #define _WDFWMI_H_ 31 32 #ifndef WDF_EXTERN_C 33 #ifdef __cplusplus 34 #define WDF_EXTERN_C extern "C" 35 #define WDF_EXTERN_C_START extern "C" { 36 #define WDF_EXTERN_C_END } 37 #else 38 #define WDF_EXTERN_C 39 #define WDF_EXTERN_C_START 40 #define WDF_EXTERN_C_END 41 #endif 42 #endif 43 44 WDF_EXTERN_C_START 45 46 47 48 #if (NTDDI_VERSION >= NTDDI_WIN2K) 49 50 typedef enum _WDF_WMI_PROVIDER_CONTROL { 51 WdfWmiControlInvalid = 0, 52 WdfWmiEventControl, 53 WdfWmiInstanceControl, 54 } WDF_WMI_PROVIDER_CONTROL; 55 56 // 57 // WdfWmiProviderExpensive: 58 // The provider's operations are expensive in terms of resources 59 // 60 // WdfWmiProviderReadOnly: 61 // The provider is read only. No set or set data item callbacks will be 62 // made on all instances of this provider. 63 // 64 // WdfWmiProviderEventOnly: 65 // Data item is being used to fire events only. It will not receive any 66 // callbacks on it to get / set / execute buffers. 67 // 68 typedef enum _WDF_WMI_PROVIDER_FLAGS { 69 WdfWmiProviderEventOnly = 0x0001, 70 WdfWmiProviderExpensive = 0x0002, 71 WdfWmiProviderTracing = 0x0004, 72 WdfWmiProviderValidFlags = WdfWmiProviderEventOnly | WdfWmiProviderExpensive | WdfWmiProviderTracing, 73 } WDF_WMI_PROVIDER_FLAGS; 74 75 76 77 typedef 78 _Function_class_(EVT_WDF_WMI_INSTANCE_QUERY_INSTANCE) 79 _IRQL_requires_same_ 80 _IRQL_requires_max_(PASSIVE_LEVEL) 81 NTSTATUS 82 EVT_WDF_WMI_INSTANCE_QUERY_INSTANCE( 83 _In_ 84 WDFWMIINSTANCE WmiInstance, 85 _In_ 86 ULONG OutBufferSize, 87 _Out_writes_bytes_to_(OutBufferSize, *BufferUsed) 88 PVOID OutBuffer, 89 _Out_ 90 PULONG BufferUsed 91 ); 92 93 typedef EVT_WDF_WMI_INSTANCE_QUERY_INSTANCE *PFN_WDF_WMI_INSTANCE_QUERY_INSTANCE; 94 95 typedef 96 _Function_class_(EVT_WDF_WMI_INSTANCE_SET_INSTANCE) 97 _IRQL_requires_same_ 98 _IRQL_requires_max_(PASSIVE_LEVEL) 99 NTSTATUS 100 EVT_WDF_WMI_INSTANCE_SET_INSTANCE( 101 _In_ 102 WDFWMIINSTANCE WmiInstance, 103 _In_ 104 ULONG InBufferSize, 105 _In_reads_bytes_(InBufferSize) 106 PVOID InBuffer 107 ); 108 109 typedef EVT_WDF_WMI_INSTANCE_SET_INSTANCE *PFN_WDF_WMI_INSTANCE_SET_INSTANCE; 110 111 typedef 112 _Function_class_(EVT_WDF_WMI_INSTANCE_SET_ITEM) 113 _IRQL_requires_same_ 114 _IRQL_requires_max_(PASSIVE_LEVEL) 115 NTSTATUS 116 EVT_WDF_WMI_INSTANCE_SET_ITEM( 117 _In_ 118 WDFWMIINSTANCE WmiInstance, 119 _In_ 120 ULONG DataItemId, 121 _In_ 122 ULONG InBufferSize, 123 _In_reads_bytes_(InBufferSize) 124 PVOID InBuffer 125 ); 126 127 typedef EVT_WDF_WMI_INSTANCE_SET_ITEM *PFN_WDF_WMI_INSTANCE_SET_ITEM; 128 129 typedef 130 _Function_class_(EVT_WDF_WMI_INSTANCE_EXECUTE_METHOD) 131 _IRQL_requires_same_ 132 _IRQL_requires_max_(PASSIVE_LEVEL) 133 NTSTATUS 134 EVT_WDF_WMI_INSTANCE_EXECUTE_METHOD( 135 _In_ 136 WDFWMIINSTANCE WmiInstance, 137 _In_ 138 ULONG MethodId, 139 _In_ 140 ULONG InBufferSize, 141 _In_ 142 ULONG OutBufferSize, 143 _When_(InBufferSize >= OutBufferSize, _Inout_updates_bytes_(InBufferSize)) 144 _When_(InBufferSize < OutBufferSize, _Inout_updates_bytes_(OutBufferSize)) 145 PVOID Buffer, 146 _Out_ 147 PULONG BufferUsed 148 ); 149 150 typedef EVT_WDF_WMI_INSTANCE_EXECUTE_METHOD *PFN_WDF_WMI_INSTANCE_EXECUTE_METHOD; 151 152 typedef 153 _Function_class_(EVT_WDF_WMI_PROVIDER_FUNCTION_CONTROL) 154 _IRQL_requires_same_ 155 _IRQL_requires_max_(PASSIVE_LEVEL) 156 NTSTATUS 157 EVT_WDF_WMI_PROVIDER_FUNCTION_CONTROL( 158 _In_ 159 WDFWMIPROVIDER WmiProvider, 160 _In_ 161 WDF_WMI_PROVIDER_CONTROL Control, 162 _In_ 163 BOOLEAN Enable 164 ); 165 166 typedef EVT_WDF_WMI_PROVIDER_FUNCTION_CONTROL *PFN_WDF_WMI_PROVIDER_FUNCTION_CONTROL; 167 168 typedef struct _WDF_WMI_PROVIDER_CONFIG { 169 // 170 // Size of this structure in bytes 171 // 172 ULONG Size; 173 174 // 175 // The GUID being registered 176 // 177 GUID Guid; 178 179 // 180 // Combination of values from the enum WDF_WMI_PROVIDER_FLAGS 181 // 182 ULONG Flags; 183 184 // 185 // Minimum expected buffer size for query and set instance requests. 186 // Ignored if WdfWmiProviderEventOnly is set in Flags. 187 // 188 ULONG MinInstanceBufferSize; 189 190 // 191 // Callback when caller is opening a provider which ha been marked as 192 // expensive or when a caller is interested in events. 193 // 194 PFN_WDF_WMI_PROVIDER_FUNCTION_CONTROL EvtWmiProviderFunctionControl; 195 196 } WDF_WMI_PROVIDER_CONFIG, *PWDF_WMI_PROVIDER_CONFIG; 197 198 VOID 199 FORCEINLINE 200 WDF_WMI_PROVIDER_CONFIG_INIT( 201 _Out_ PWDF_WMI_PROVIDER_CONFIG Config, 202 _In_ CONST GUID* Guid 203 ) 204 { 205 RtlZeroMemory(Config, sizeof(WDF_WMI_PROVIDER_CONFIG)); 206 207 Config->Size = sizeof(WDF_WMI_PROVIDER_CONFIG); 208 RtlCopyMemory(&Config->Guid, Guid, sizeof(GUID)); 209 } 210 211 typedef struct _WDF_WMI_INSTANCE_CONFIG { 212 // 213 // Size of the structure in bytes 214 // 215 ULONG Size; 216 217 // 218 // Optional parameter. If NULL, ProviderConfig must be set to a valid pointer 219 // value. If specified, indicates the provider to create an instance for. 220 // 221 WDFWMIPROVIDER Provider; 222 223 // 224 // Optional parameter. If NULL, Provider must be set to a valid handle 225 // value. If specifeid, indicates the configuration for a provider to be 226 // created and for this instance to be associated with. 227 // 228 PWDF_WMI_PROVIDER_CONFIG ProviderConfig; 229 230 // 231 // If the Provider is configured as read only and this field is set to TRUE, 232 // the EvtWmiInstanceQueryInstance is ignored and WDF will blindly copy the 233 // context associated with this instance (using RtlCopyMemory, with no locks 234 // held) into the query buffer. 235 // 236 BOOLEAN UseContextForQuery; 237 238 // 239 // If TRUE, the instance will be registered as well as created. 240 // 241 BOOLEAN Register; 242 243 // 244 // Callback when caller wants to query the entire data item's buffer. 245 // 246 PFN_WDF_WMI_INSTANCE_QUERY_INSTANCE EvtWmiInstanceQueryInstance; 247 248 // 249 // Callback when caller wants to set the entire data item's buffer. 250 // 251 PFN_WDF_WMI_INSTANCE_SET_INSTANCE EvtWmiInstanceSetInstance; 252 253 // 254 // Callback when caller wants to set a single field in the data item's buffer 255 // 256 PFN_WDF_WMI_INSTANCE_SET_ITEM EvtWmiInstanceSetItem; 257 258 // 259 // Callback when caller wants to execute a method on the data item. 260 // 261 PFN_WDF_WMI_INSTANCE_EXECUTE_METHOD EvtWmiInstanceExecuteMethod; 262 263 } WDF_WMI_INSTANCE_CONFIG, *PWDF_WMI_INSTANCE_CONFIG; 264 265 266 VOID 267 FORCEINLINE 268 WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER( 269 _Out_ PWDF_WMI_INSTANCE_CONFIG Config, 270 _In_ WDFWMIPROVIDER Provider 271 ) 272 { 273 RtlZeroMemory(Config, sizeof(WDF_WMI_INSTANCE_CONFIG)); 274 Config->Size = sizeof(WDF_WMI_INSTANCE_CONFIG); 275 276 Config->Provider = Provider; 277 } 278 279 VOID 280 FORCEINLINE 281 WDF_WMI_INSTANCE_CONFIG_INIT_PROVIDER_CONFIG( 282 _Out_ PWDF_WMI_INSTANCE_CONFIG Config, 283 _In_ PWDF_WMI_PROVIDER_CONFIG ProviderConfig 284 ) 285 { 286 RtlZeroMemory(Config, sizeof(WDF_WMI_INSTANCE_CONFIG)); 287 Config->Size = sizeof(WDF_WMI_INSTANCE_CONFIG); 288 289 Config->ProviderConfig = ProviderConfig; 290 } 291 292 NTSTATUS 293 FORCEINLINE 294 WDF_WMI_BUFFER_APPEND_STRING( 295 _Out_writes_bytes_(BufferLength) PVOID Buffer, 296 _In_ ULONG BufferLength, 297 _In_ PCUNICODE_STRING String, 298 _Out_ PULONG RequiredSize 299 ) 300 { 301 // 302 // Compute the length of buffer we need to use. Upon error the caller can 303 // use this length to report the required length. On success, the caller 304 // can use this length to know how many bytes were written. 305 // 306 *RequiredSize = String->Length + sizeof(USHORT); 307 308 // 309 // UNICODE_STRING.Length is the length of the string in bytes, not characters 310 // 311 312 // First check to see if there is enough space 313 // 1) to store the length of the string 314 // 2) to store the string itself 315 // 316 if (BufferLength < (String->Length + sizeof(USHORT))) { 317 // 318 // Not enough room in the string, report back how big a buffer is 319 // required. 320 // 321 return STATUS_BUFFER_TOO_SMALL; 322 } 323 324 // 325 // Store the length of the string 326 // 327 *(USHORT *) Buffer = String->Length; 328 329 // 330 // Copy the string to the buffer 331 // 332 RtlCopyMemory(WDF_PTR_ADD_OFFSET(Buffer, sizeof(USHORT)), 333 String->Buffer, 334 String->Length); 335 336 return STATUS_SUCCESS; 337 } 338 339 // 340 // WDF Function: WdfWmiProviderCreate 341 // 342 typedef 343 _Must_inspect_result_ 344 _IRQL_requires_max_(DISPATCH_LEVEL) 345 WDFAPI 346 NTSTATUS 347 (*PFN_WDFWMIPROVIDERCREATE)( 348 _In_ 349 PWDF_DRIVER_GLOBALS DriverGlobals, 350 _In_ 351 WDFDEVICE Device, 352 _In_ 353 PWDF_WMI_PROVIDER_CONFIG WmiProviderConfig, 354 _In_opt_ 355 PWDF_OBJECT_ATTRIBUTES ProviderAttributes, 356 _Out_ 357 WDFWMIPROVIDER* WmiProvider 358 ); 359 360 _Must_inspect_result_ 361 _IRQL_requires_max_(DISPATCH_LEVEL) 362 NTSTATUS 363 FORCEINLINE 364 WdfWmiProviderCreate( 365 _In_ 366 WDFDEVICE Device, 367 _In_ 368 PWDF_WMI_PROVIDER_CONFIG WmiProviderConfig, 369 _In_opt_ 370 PWDF_OBJECT_ATTRIBUTES ProviderAttributes, 371 _Out_ 372 WDFWMIPROVIDER* WmiProvider 373 ) 374 { 375 return ((PFN_WDFWMIPROVIDERCREATE) WdfFunctions[WdfWmiProviderCreateTableIndex])(WdfDriverGlobals, Device, WmiProviderConfig, ProviderAttributes, WmiProvider); 376 } 377 378 // 379 // WDF Function: WdfWmiProviderGetDevice 380 // 381 typedef 382 _IRQL_requires_max_(DISPATCH_LEVEL) 383 WDFAPI 384 WDFDEVICE 385 (*PFN_WDFWMIPROVIDERGETDEVICE)( 386 _In_ 387 PWDF_DRIVER_GLOBALS DriverGlobals, 388 _In_ 389 WDFWMIPROVIDER WmiProvider 390 ); 391 392 _IRQL_requires_max_(DISPATCH_LEVEL) 393 WDFDEVICE 394 FORCEINLINE 395 WdfWmiProviderGetDevice( 396 _In_ 397 WDFWMIPROVIDER WmiProvider 398 ) 399 { 400 return ((PFN_WDFWMIPROVIDERGETDEVICE) WdfFunctions[WdfWmiProviderGetDeviceTableIndex])(WdfDriverGlobals, WmiProvider); 401 } 402 403 // 404 // WDF Function: WdfWmiProviderIsEnabled 405 // 406 typedef 407 _IRQL_requires_max_(DISPATCH_LEVEL) 408 WDFAPI 409 BOOLEAN 410 (*PFN_WDFWMIPROVIDERISENABLED)( 411 _In_ 412 PWDF_DRIVER_GLOBALS DriverGlobals, 413 _In_ 414 WDFWMIPROVIDER WmiProvider, 415 _In_ 416 WDF_WMI_PROVIDER_CONTROL ProviderControl 417 ); 418 419 _IRQL_requires_max_(DISPATCH_LEVEL) 420 BOOLEAN 421 FORCEINLINE 422 WdfWmiProviderIsEnabled( 423 _In_ 424 WDFWMIPROVIDER WmiProvider, 425 _In_ 426 WDF_WMI_PROVIDER_CONTROL ProviderControl 427 ) 428 { 429 return ((PFN_WDFWMIPROVIDERISENABLED) WdfFunctions[WdfWmiProviderIsEnabledTableIndex])(WdfDriverGlobals, WmiProvider, ProviderControl); 430 } 431 432 // 433 // WDF Function: WdfWmiProviderGetTracingHandle 434 // 435 typedef 436 _IRQL_requires_max_(DISPATCH_LEVEL) 437 WDFAPI 438 ULONGLONG 439 (*PFN_WDFWMIPROVIDERGETTRACINGHANDLE)( 440 _In_ 441 PWDF_DRIVER_GLOBALS DriverGlobals, 442 _In_ 443 WDFWMIPROVIDER WmiProvider 444 ); 445 446 _IRQL_requires_max_(DISPATCH_LEVEL) 447 ULONGLONG 448 FORCEINLINE 449 WdfWmiProviderGetTracingHandle( 450 _In_ 451 WDFWMIPROVIDER WmiProvider 452 ) 453 { 454 return ((PFN_WDFWMIPROVIDERGETTRACINGHANDLE) WdfFunctions[WdfWmiProviderGetTracingHandleTableIndex])(WdfDriverGlobals, WmiProvider); 455 } 456 457 // 458 // WDF Function: WdfWmiInstanceCreate 459 // 460 typedef 461 _Must_inspect_result_ 462 _IRQL_requires_max_(DISPATCH_LEVEL) 463 WDFAPI 464 NTSTATUS 465 (*PFN_WDFWMIINSTANCECREATE)( 466 _In_ 467 PWDF_DRIVER_GLOBALS DriverGlobals, 468 _In_ 469 WDFDEVICE Device, 470 _In_ 471 PWDF_WMI_INSTANCE_CONFIG InstanceConfig, 472 _In_opt_ 473 PWDF_OBJECT_ATTRIBUTES InstanceAttributes, 474 _Out_opt_ 475 WDFWMIINSTANCE* Instance 476 ); 477 478 _Must_inspect_result_ 479 _IRQL_requires_max_(DISPATCH_LEVEL) 480 NTSTATUS 481 FORCEINLINE 482 WdfWmiInstanceCreate( 483 _In_ 484 WDFDEVICE Device, 485 _In_ 486 PWDF_WMI_INSTANCE_CONFIG InstanceConfig, 487 _In_opt_ 488 PWDF_OBJECT_ATTRIBUTES InstanceAttributes, 489 _Out_opt_ 490 WDFWMIINSTANCE* Instance 491 ) 492 { 493 return ((PFN_WDFWMIINSTANCECREATE) WdfFunctions[WdfWmiInstanceCreateTableIndex])(WdfDriverGlobals, Device, InstanceConfig, InstanceAttributes, Instance); 494 } 495 496 // 497 // WDF Function: WdfWmiInstanceRegister 498 // 499 typedef 500 _Must_inspect_result_ 501 _IRQL_requires_max_(PASSIVE_LEVEL) 502 WDFAPI 503 NTSTATUS 504 (*PFN_WDFWMIINSTANCEREGISTER)( 505 _In_ 506 PWDF_DRIVER_GLOBALS DriverGlobals, 507 _In_ 508 WDFWMIINSTANCE WmiInstance 509 ); 510 511 _Must_inspect_result_ 512 _IRQL_requires_max_(PASSIVE_LEVEL) 513 NTSTATUS 514 FORCEINLINE 515 WdfWmiInstanceRegister( 516 _In_ 517 WDFWMIINSTANCE WmiInstance 518 ) 519 { 520 return ((PFN_WDFWMIINSTANCEREGISTER) WdfFunctions[WdfWmiInstanceRegisterTableIndex])(WdfDriverGlobals, WmiInstance); 521 } 522 523 // 524 // WDF Function: WdfWmiInstanceDeregister 525 // 526 typedef 527 _IRQL_requires_max_(PASSIVE_LEVEL) 528 WDFAPI 529 VOID 530 (*PFN_WDFWMIINSTANCEDEREGISTER)( 531 _In_ 532 PWDF_DRIVER_GLOBALS DriverGlobals, 533 _In_ 534 WDFWMIINSTANCE WmiInstance 535 ); 536 537 _IRQL_requires_max_(PASSIVE_LEVEL) 538 VOID 539 FORCEINLINE 540 WdfWmiInstanceDeregister( 541 _In_ 542 WDFWMIINSTANCE WmiInstance 543 ) 544 { 545 ((PFN_WDFWMIINSTANCEDEREGISTER) WdfFunctions[WdfWmiInstanceDeregisterTableIndex])(WdfDriverGlobals, WmiInstance); 546 } 547 548 // 549 // WDF Function: WdfWmiInstanceGetDevice 550 // 551 typedef 552 _IRQL_requires_max_(DISPATCH_LEVEL) 553 WDFAPI 554 WDFDEVICE 555 (*PFN_WDFWMIINSTANCEGETDEVICE)( 556 _In_ 557 PWDF_DRIVER_GLOBALS DriverGlobals, 558 _In_ 559 WDFWMIINSTANCE WmiInstance 560 ); 561 562 _IRQL_requires_max_(DISPATCH_LEVEL) 563 WDFDEVICE 564 FORCEINLINE 565 WdfWmiInstanceGetDevice( 566 _In_ 567 WDFWMIINSTANCE WmiInstance 568 ) 569 { 570 return ((PFN_WDFWMIINSTANCEGETDEVICE) WdfFunctions[WdfWmiInstanceGetDeviceTableIndex])(WdfDriverGlobals, WmiInstance); 571 } 572 573 // 574 // WDF Function: WdfWmiInstanceGetProvider 575 // 576 typedef 577 _IRQL_requires_max_(DISPATCH_LEVEL) 578 WDFAPI 579 WDFWMIPROVIDER 580 (*PFN_WDFWMIINSTANCEGETPROVIDER)( 581 _In_ 582 PWDF_DRIVER_GLOBALS DriverGlobals, 583 _In_ 584 WDFWMIINSTANCE WmiInstance 585 ); 586 587 _IRQL_requires_max_(DISPATCH_LEVEL) 588 WDFWMIPROVIDER 589 FORCEINLINE 590 WdfWmiInstanceGetProvider( 591 _In_ 592 WDFWMIINSTANCE WmiInstance 593 ) 594 { 595 return ((PFN_WDFWMIINSTANCEGETPROVIDER) WdfFunctions[WdfWmiInstanceGetProviderTableIndex])(WdfDriverGlobals, WmiInstance); 596 } 597 598 // 599 // WDF Function: WdfWmiInstanceFireEvent 600 // 601 typedef 602 _Must_inspect_result_ 603 _IRQL_requires_max_(APC_LEVEL) 604 WDFAPI 605 NTSTATUS 606 (*PFN_WDFWMIINSTANCEFIREEVENT)( 607 _In_ 608 PWDF_DRIVER_GLOBALS DriverGlobals, 609 _In_ 610 WDFWMIINSTANCE WmiInstance, 611 _In_opt_ 612 ULONG EventDataSize, 613 _In_reads_bytes_opt_(EventDataSize) 614 PVOID EventData 615 ); 616 617 _Must_inspect_result_ 618 _IRQL_requires_max_(APC_LEVEL) 619 NTSTATUS 620 FORCEINLINE 621 WdfWmiInstanceFireEvent( 622 _In_ 623 WDFWMIINSTANCE WmiInstance, 624 _In_opt_ 625 ULONG EventDataSize, 626 _In_reads_bytes_opt_(EventDataSize) 627 PVOID EventData 628 ) 629 { 630 return ((PFN_WDFWMIINSTANCEFIREEVENT) WdfFunctions[WdfWmiInstanceFireEventTableIndex])(WdfDriverGlobals, WmiInstance, EventDataSize, EventData); 631 } 632 633 634 635 #endif // (NTDDI_VERSION >= NTDDI_WIN2K) 636 637 638 639 WDF_EXTERN_C_END 640 641 #endif // _WDFWMI_H_ 642 643