ReactOS 0.4.15-dev-8428-g6910fa6
fxchildlistapi.cpp
Go to the documentation of this file.
1/*++
2
3Copyright (c) Microsoft Corporation. All rights reserved.
4
5Module Name:
6
7 FxChildListApi.cpp
8
9Abstract:
10
11 This module exposes the "C" interface to the FxChildList object.
12
13Author:
14
15
16
17Environment:
18
19 Kernel mode only
20
21Revision History:
22
23--*/
24
25#include "fxcorepch.hpp"
26
27extern "C" {
28// #include "FxChildListAPI.tmh"
29}
30
31//
32// extern "C" the entire file
33//
34extern "C" {
35
40WDFEXPORT(WdfChildListCreate)(
41 __in
43 __in
44 WDFDEVICE Device,
45 __in
49 __out
50 WDFCHILDLIST* DeviceList
51 )
52{
58
60 Device,
62 (PVOID*)&pDevice,
64
66 "Enter, WDFDEVICE %p", Device);
67
70
72
75 return status;
76 }
77
79 Config,
81 if (!NT_SUCCESS(status)) {
83 "WDFDEVICE 0x%p Config is invalid", Device);
84 return status;
85 }
86
90 if (!NT_SUCCESS(status)) {
91 return status;
92 }
93
95 if (!NT_SUCCESS(status)) {
96 return status;
97 }
98
103 pDevice,
104 Config);
105 if (!NT_SUCCESS(status)) {
106 return status;
107 }
108
111 pDevice);
112
113 if (!NT_SUCCESS(status)) {
115 "Could not convert object to handle, %!STATUS!",
116 status);
118 }
119
122 }
123
124 return status;
125}
126
128WDFDEVICE
130WDFEXPORT(WdfChildListGetDevice)(
131 __in
133 __in
134 WDFCHILDLIST DeviceList
135 )
136{
139
143 (PVOID*)&pList,
145
147 "Enter: WDFCHILDLIST %p", DeviceList);
148
149 return pList->GetDevice();
150}
151
156WDFEXPORT(WdfChildListRetrieveAddressDescription)(
157 __in
159 __in
160 WDFCHILDLIST DeviceList,
161 __in
163 __inout
165 )
166{
170
174 (PVOID*)&pList,
176
178 "Enter: WDFCHILDLIST %p", DeviceList);
179
182
184 IdentificationDescription->IdentificationDescriptionSize) {
186
189 "identification description size %d incorrect, expected %d, %!STATUS!",
190 IdentificationDescription->IdentificationDescriptionSize,
192
193 return status;
194 }
195
198
200 "cannot retrieve an address description from a list"
201 " which was not initialized to use them, %!STATUS!",
202 status);
203
204 return status;
205 }
206
208 AddressDescription->AddressDescriptionSize) {
210
212 "description size %d incorrect, expected %d, %!STATUS!",
213 AddressDescription->AddressDescriptionSize,
215
216 return status;
217 }
218
221
223 "Exit: WDFCHILDLIST %p, %!STATUS!",
225
226 return status;
227
228}
229
231VOID
233WDFEXPORT(WdfChildListBeginScan)(
234 __in
236 __in
237 WDFCHILDLIST DeviceList
238 )
239{
242
246 (PVOID*)&pList,
248
250 "Enter: WDFCHILDLIST %p", DeviceList);
251
253}
254
256VOID
258WDFEXPORT(WdfChildListEndScan)(
259 __in
261 __in
262 WDFCHILDLIST DeviceList
263 )
264{
267
271 (PVOID*)&pList,
273
275 "Enter: WDFCHILDLIST %p", DeviceList);
276
278}
279
281VOID
283WDFEXPORT(WdfChildListBeginIteration)(
284 __in
286 __in
287 WDFCHILDLIST DeviceList,
288 __in
290 )
291{
294
298 (PVOID*)&pList,
300
302 "Enter: WDFCHILDLIST %p", DeviceList);
303
305
306 if (Iterator->Size != sizeof(WDF_CHILD_LIST_ITERATOR)) {
308 "Iterator Size %d not correct, expected %d, %!STATUS!",
309 Iterator->Size, sizeof(WDF_CHILD_LIST_ITERATOR),
312 return;
313 }
314
315 if ((Iterator->Flags & ~WdfRetrieveAllChildren) != 0) {
318 "Iterator Flags 0x%x not correct, valid mask 0x%x, %!STATUS!",
321 return;
322 }
323
324 RtlZeroMemory(&Iterator->Reserved[0], sizeof(Iterator->Reserved));
325
327}
328
333WDFEXPORT(WdfChildListRetrieveNextDevice)(
334 __in
336 __in
337 WDFCHILDLIST DeviceList,
338 __in
340 __out
341 WDFDEVICE* Device,
344 )
345{
349
353 (PVOID*)&pList,
355
358
359 *Device = NULL;
360
361 if (Iterator->Size != sizeof(WDF_CHILD_LIST_ITERATOR)) {
364 "Iterator Size %d not correct, expected %d, %!STATUS!",
365 Iterator->Size, sizeof(WDF_CHILD_LIST_ITERATOR), status);
366 return status;
367 }
368
369 if ((Iterator->Flags & ~WdfRetrieveAllChildren) != 0) {
373 "Iterator Flags 0x%x not correct, valid mask 0x%x, %!STATUS!",
375 return status;
376 }
377
378 if (Info != NULL) {
379 if (Info->Size != sizeof(WDF_CHILD_RETRIEVE_INFO)) {
383 "Invalid RetrieveInfo Size %d, expected %d, %!STATUS!",
384 Info->Size, sizeof(WDF_CHILD_RETRIEVE_INFO), status);
385 return status;
386 }
387 if (Info->IdentificationDescription != NULL
388 &&
390 Info->IdentificationDescription->IdentificationDescriptionSize) {
392
395 "identification description size %d incorrect, expected %d"
396 "%!STATUS!",
397 Info->IdentificationDescription->IdentificationDescriptionSize,
399
400 return status;
401 }
402
403 if (Info->AddressDescription != NULL) {
406
409 "cannot retrieve an address description from a list"
410 " which was not initialized to use them, %!STATUS!",
411 status);
412
413 return status;
414 }
415 else if (pList->GetAddressDescriptionSize() !=
416 Info->AddressDescription->AddressDescriptionSize) {
418
421 "address description size %d incorrect, expected %d, %!STATUS!",
422 Info->AddressDescription->AddressDescriptionSize,
424
425 return status;
426 }
427 }
428 }
429
431}
432
434VOID
436WDFEXPORT(WdfChildListEndIteration)(
437 __in
439 __in
440 WDFCHILDLIST DeviceList,
441 __in
443 )
444{
447
451 (PVOID*)&pList,
453
455 "Enter: WDFCHILDLIST %p", DeviceList);
456
458
459 if (Iterator->Size != sizeof(WDF_CHILD_LIST_ITERATOR)) {
461 "Iterator Size %d not correct, expected %d, %!STATUS!",
462 Iterator->Size, sizeof(WDF_CHILD_LIST_ITERATOR),
465 return;
466 }
467
468 if ((Iterator->Flags & ~WdfRetrieveAllChildren) != 0) {
471 "Iterator Flags 0x%x not correct, valid mask 0x%x, %!STATUS!",
474 return;
475 }
476
478}
479
480
485WDFEXPORT(WdfChildListAddOrUpdateChildDescriptionAsPresent)(
486 __in
488 __in
489 WDFCHILDLIST DeviceList,
490 __in
494 )
495{
499
503 (PVOID*)&pList,
505
507 "Enter: WDFCHILDLIST %p", DeviceList);
508
510
514
517 "cannot retrieve an address description from a list"
518 " which was not initialized to use them, %!STATUS!", status);
519
520 return status;
521 }
523 AddressDescription->AddressDescriptionSize) {
525
528 "address description size %d incorrect, expected %d, %!STATUS!",
529 AddressDescription->AddressDescriptionSize,
531
532 return status;
533 }
534 }
535 else {
538
541 "Must provide a valid AddressDescription because the"
542 " WDFCHILDLIST 0x%p is configured with AddressDescriptionSize,"
543 " %!STATUS!", DeviceList, status);
544
545 return status;
546 }
547 }
548
550 IdentificationDescription->IdentificationDescriptionSize) {
552
555 "identification description size %d incorrect, expected %d, %!STATUS!",
556 IdentificationDescription->IdentificationDescriptionSize,
558
559 return status;
560 }
561
563
565 "Exit: WDFCHILDLIST %p, %!STATUS!", DeviceList, status);
566
567 return status;
568}
569
574WDFEXPORT(WdfChildListUpdateChildDescriptionAsMissing)(
575 __in
577 __in
578 WDFCHILDLIST DeviceList,
579 __in
581 )
582{
586
590 (PVOID*)&pList,
592
594
596 "Enter: WDFCHILDLIST %p", DeviceList);
597
599 IdentificationDescription->IdentificationDescriptionSize) {
601
604 "identification description size %d incorrect, expected %d, %!STATUS!",
605 IdentificationDescription->IdentificationDescriptionSize,
607
608 return status;
609 }
610
612
614 "Exit: WDFCHILDLIST %p, %!STATUS!",
616
617 return status;
618}
619
621VOID
623WDFEXPORT(WdfChildListUpdateAllChildDescriptionsAsPresent)(
624 __in
626 __in
627 WDFCHILDLIST DeviceList
628 )
629{
632
636 (PVOID*)&pList,
638
640 "Enter: WDFCHILDLIST %p", DeviceList);
641
643
645 "Exit: WDFCHILDLIST %p", DeviceList);
646}
647
650WDFDEVICE
652WDFEXPORT(WdfChildListRetrievePdo)(
653 __in
655 __in
656 WDFCHILDLIST DeviceList,
657 __inout
659 )
660{
666
670 (PVOID*)&pList,
672
674 "Enter: WDFCHILDLIST %p", DeviceList);
675
677
678 if (RetrieveInfo->Size != sizeof(WDF_CHILD_RETRIEVE_INFO)) {
681 "Invalid RetrieveInfo Size %x, expected %d, %!STATUS!",
684 return NULL;
685 }
686
687 pId = RetrieveInfo->IdentificationDescription;
688 if (pId == NULL) {
690 "Invalid ID Description, %!STATUS!",
692 return NULL;
693 }
694
699 "identification description size %d incorrect, expected %d",
702
703 return NULL;
704 }
705
706 pAddr = RetrieveInfo->AddressDescription;
707 if (pAddr != NULL) {
711 "cannot retrieve an address description from a list"
712 " which was not initialized to use them, %!STATUS!",
714 return NULL;
715 }
719 "address description size %d incorrect, expected %d",
721
722 return NULL;
723 }
724 }
725
727
729
730 WDFDEVICE handle;
731
732 if (device != NULL) {
733 handle = device->GetHandle();
734 }
735 else {
736 handle = NULL;
737 }
738
740 "Exit: WDFCHILDLIST %p, WDFDEVICE Pdo %p, "
741 "%!WDF_CHILD_LIST_RETRIEVE_DEVICE_STATUS!",
742 DeviceList, handle, RetrieveInfo->Status);
743
744 return handle;
745}
746
750WDFEXPORT(WdfChildListRequestChildEject)(
751 __in
753 __in
754 WDFCHILDLIST DeviceList,
755 __in
757 )
758{
762
766 (PVOID*)&pList,
768
770 "Enter: WDFCHILDLIST %p", DeviceList);
771
773
775 IdentificationDescription->IdentificationDescriptionSize) {
778 "identification description size 0x%x incorrect, expected 0x%x",
779 IdentificationDescription->IdentificationDescriptionSize,
781
782 return FALSE;
783 }
784
786
788
790
792 "found: WDFCHILDLIST %p, WDFDEVICE PDO %p",
793 DeviceList, device == NULL ? NULL : device->GetHandle());
794
795 if (device != NULL) {
796 PDEVICE_OBJECT pdo;
797
798 //
799 // Make sure we have a valid PDO that can be ejected
800 //
801 pdo = device->GetSafePhysicalDevice();
802
803 if (pdo != NULL) {
805 return TRUE;
806 }
807 else {
809 "PDO WDFDEVICE %p not reported yet to pnp, cannot eject!",
810 device->GetHandle());
811 }
812 }
813
814 return FALSE;
815}
816
817} // extern "C" of entire file
unsigned char BOOLEAN
LONG NTSTATUS
Definition: precomp.h:26
VOID EndScan(__inout_opt PULONG ScanTag=NULL)
_Must_inspect_result_ NTSTATUS GetNextDevice(__out WDFDEVICE *Device, __inout PWDF_CHILD_LIST_ITERATOR Iterator, __inout_opt PWDF_CHILD_RETRIEVE_INFO Info)
BOOLEAN HasAddressDescriptions(VOID)
static _Must_inspect_result_ NTSTATUS _ValidateConfig(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PWDF_CHILD_LIST_CONFIG Config, __in size_t *TotalDescriptionSize)
WDFDEVICE GetDevice(VOID)
VOID BeginScan(__out_opt PULONG ScanTag=NULL)
CfxDevice * GetDeviceFromId(__inout PWDF_CHILD_RETRIEVE_INFO Info)
_Must_inspect_result_ NTSTATUS GetAddressDescription(__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription, __out PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddressDescription)
VOID BeginIteration(__inout PWDF_CHILD_LIST_ITERATOR Iterator)
_Must_inspect_result_ NTSTATUS Add(__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription, __in_opt PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddressDescription, __in_opt PULONG ScanTag=NULL)
static _Must_inspect_result_ NTSTATUS _CreateAndInit(__out FxChildList **ChildList, __in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PWDF_OBJECT_ATTRIBUTES ListAttributes, __in size_t TotalDescriptionSize, __in CfxDevice *Device, __in PWDF_CHILD_LIST_CONFIG ListConfig, __in BOOLEAN Static=FALSE)
VOID EndIteration(__inout PWDF_CHILD_LIST_ITERATOR Iterator)
ULONG GetIdentificationDescriptionSize(VOID)
ULONG GetAddressDescriptionSize(VOID)
VOID UpdateAllAsPresent(__in_opt PULONG ScanTag=NULL)
_Must_inspect_result_ NTSTATUS UpdateAsMissing(__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Description)
virtual _Must_inspect_result_ NTSTATUS AllocateEnumInfo(VOID)
Definition: fxdevice.cpp:1805
virtual VOID SetDeviceTelemetryInfoFlags(_In_ FxDeviceInfoFlags Flag)
Definition: fxdevice.hpp:1807
VOID DeleteFromFailedCreate(VOID)
Definition: fxobject.cpp:391
_Must_inspect_result_ NTSTATUS Commit(__in_opt PWDF_OBJECT_ATTRIBUTES Attributes, __out_opt WDFOBJECT *ObjectHandle, __in_opt FxObject *Parent=NULL, __in BOOLEAN AssignDriverAsDefaultParent=TRUE)
Definition: fxobject.cpp:904
#define __inout_opt
Definition: dbghelp.h:53
#define __in
Definition: dbghelp.h:35
#define __inout
Definition: dbghelp.h:50
#define __in_opt
Definition: dbghelp.h:38
#define __out
Definition: dbghelp.h:62
#define TRACINGPNP
Definition: dbgtrace.h:67
#define TRACINGDEVICE
Definition: dbgtrace.h:58
VOID NTAPI IoRequestDeviceEject(IN PDEVICE_OBJECT PhysicalDeviceObject)
Definition: devaction.c:2203
#define NULL
Definition: types.h:112
#define TRUE
Definition: types.h:120
#define NT_SUCCESS(StatCode)
Definition: apphelp.c:33
#define __drv_maxIRQL(irql)
Definition: driverspecs.h:291
#define PASSIVE_LEVEL
Definition: env_spec_w32.h:693
#define DISPATCH_LEVEL
Definition: env_spec_w32.h:696
FxChildList * pList
_Must_inspect_result_ __in WDFDEVICE __in PWDF_CHILD_LIST_CONFIG __in_opt PWDF_OBJECT_ATTRIBUTES DeviceListAttributes
FxDevice * pDevice
DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_VERBOSE, TRACINGPNP, "Enter, WDFDEVICE %p", Device)
_Must_inspect_result_ __in WDFDEVICE __in PWDF_CHILD_LIST_CONFIG __in_opt PWDF_OBJECT_ATTRIBUTES __out WDFCHILDLIST * DeviceList
WDFDEVICE handle
_Must_inspect_result_ __in WDFCHILDLIST __in PWDF_CHILD_LIST_ITERATOR __out WDFDEVICE __inout_opt PWDF_CHILD_RETRIEVE_INFO Info
size_t totalDescriptionSize
PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER pAddr
PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER pId
_Must_inspect_result_ __in WDFDEVICE __in PWDF_CHILD_LIST_CONFIG Config
FxDevice * device
NTSTATUS status
_Must_inspect_result_ __in WDFCHILDLIST __inout PWDF_CHILD_RETRIEVE_INFO RetrieveInfo
_Must_inspect_result_ __in WDFCHILDLIST __in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription
WDF_CHILD_RETRIEVE_INFO info
_Must_inspect_result_ __in WDFCHILDLIST __in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER __inout PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddressDescription
__in WDFCHILDLIST __in PWDF_CHILD_LIST_ITERATOR Iterator
return FALSE
FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals), Device, FX_TYPE_DEVICE,(PVOID *)&pDevice, &pFxDriverGlobals)
_Must_inspect_result_ __in WDFDEVICE Device
PFX_DRIVER_GLOBALS pFxDriverGlobals
FxVerifierDbgBreakPoint(pFxDriverGlobals)
DriverGlobals
__inline PFX_DRIVER_GLOBALS GetFxDriverGlobals(__in PWDF_DRIVER_GLOBALS DriverGlobals)
Definition: fxglobals.h:597
#define WDFEXPORT(a)
Definition: fxmacros.hpp:157
#define FxPointerNotNull(FxDriverGlobals, Ptr)
Definition: fxmacros.hpp:253
@ DeviceInfoHasDynamicChildren
@ FX_TYPE_DEVICE
Definition: fxtypes.h:47
@ FX_TYPE_CHILD_LIST
Definition: fxtypes.h:82
@ FX_VALIDATE_OPTION_PARENT_NOT_ALLOWED
_Must_inspect_result_ NTSTATUS FxValidateObjectAttributes(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PWDF_OBJECT_ATTRIBUTES Attributes, __in ULONG Flags=FX_VALIDATE_OPTION_NONE_SPECIFIED)
__inline NTSTATUS FxVerifierCheckIrqlLevel(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in KIRQL Irql)
Definition: fxverifier.h:158
#define _Must_inspect_result_
Definition: ms_sal.h:558
#define TRACE_LEVEL_VERBOSE
Definition: storswtr.h:30
#define TRACE_LEVEL_ERROR
Definition: storswtr.h:27
Definition: devices.h:37
Definition: ps.c:97
#define RtlZeroMemory(Destination, Length)
Definition: typedefs.h:262
#define STATUS_INVALID_DEVICE_REQUEST
Definition: udferr_usr.h:138
#define STATUS_INVALID_PARAMETER
Definition: udferr_usr.h:135
#define STATUS_INFO_LENGTH_MISMATCH
Definition: udferr_usr.h:133
#define STDCALL
Definition: wdf.h:45
_In_ WDFCHILDLIST _In_ PWDF_CHILD_LIST_ITERATOR Iterator
Definition: wdfchildlist.h:656
_Must_inspect_result_ _In_ WDFCHILDLIST _Inout_ PWDF_CHILD_RETRIEVE_INFO RetrieveInfo
Definition: wdfchildlist.h:541
_Must_inspect_result_ _In_ WDFCHILDLIST _In_ PWDF_CHILD_LIST_ITERATOR _Out_ WDFDEVICE _Inout_opt_ PWDF_CHILD_RETRIEVE_INFO Info
Definition: wdfchildlist.h:690
_Must_inspect_result_ _In_ WDFDEVICE Device
Definition: wdfchildlist.h:474
@ WdfRetrieveAllChildren
Definition: wdfchildlist.h:65
_In_ PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription
Definition: wdfchildlist.h:124
_Must_inspect_result_ _In_ WDFDEVICE _In_ PWDF_CHILD_LIST_CONFIG Config
Definition: wdfchildlist.h:476
@ WdfChildListRetrieveDeviceUndefined
Definition: wdfchildlist.h:53
_Inout_ PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddressDescription
Definition: wdfchildlist.h:255
FORCEINLINE VOID WDF_CHILD_RETRIEVE_INFO_INIT(_Out_ PWDF_CHILD_RETRIEVE_INFO Info, _In_ PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription)
Definition: wdfchildlist.h:309