ReactOS  0.4.15-dev-1636-gf634010
fxchildlistapi.cpp
Go to the documentation of this file.
1 /*++
2 
3 Copyright (c) Microsoft Corporation. All rights reserved.
4 
5 Module Name:
6 
7  FxChildListApi.cpp
8 
9 Abstract:
10 
11  This module exposes the "C" interface to the FxChildList object.
12 
13 Author:
14 
15 
16 
17 Environment:
18 
19  Kernel mode only
20 
21 Revision History:
22 
23 --*/
24 
25 #include "fxcorepch.hpp"
26 
27 extern "C" {
28 // #include "FxChildListAPI.tmh"
29 }
30 
31 //
32 // extern "C" the entire file
33 //
34 extern "C" {
35 
39 STDCALL
40 WDFEXPORT(WdfChildListCreate)(
41  __in
43  __in
44  WDFDEVICE Device,
45  __in
47  __in_opt
49  __out
50  WDFCHILDLIST* DeviceList
51  )
52 {
58 
60  Device,
62  (PVOID*)&pDevice,
64 
66  "Enter, WDFDEVICE %p", Device);
67 
70 
71  *DeviceList = NULL;
72 
74  if (!NT_SUCCESS(status)) {
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 
128 WDFDEVICE
129 STDCALL
130 WDFEXPORT(WdfChildListGetDevice)(
131  __in
133  __in
134  WDFCHILDLIST DeviceList
135  )
136 {
139 
141  DeviceList,
143  (PVOID*)&pList,
145 
147  "Enter: WDFCHILDLIST %p", DeviceList);
148 
149  return pList->GetDevice();
150 }
151 
154 NTSTATUS
155 STDCALL
156 WDFEXPORT(WdfChildListRetrieveAddressDescription)(
157  __in
159  __in
160  WDFCHILDLIST DeviceList,
161  __in
163  __inout
165  )
166 {
170 
172  DeviceList,
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!",
224  DeviceList, status);
225 
226  return status;
227 
228 }
229 
231 VOID
232 STDCALL
233 WDFEXPORT(WdfChildListBeginScan)(
234  __in
236  __in
237  WDFCHILDLIST DeviceList
238  )
239 {
242 
244  DeviceList,
246  (PVOID*)&pList,
248 
250  "Enter: WDFCHILDLIST %p", DeviceList);
251 
252  pList->BeginScan();
253 }
254 
256 VOID
257 STDCALL
258 WDFEXPORT(WdfChildListEndScan)(
259  __in
261  __in
262  WDFCHILDLIST DeviceList
263  )
264 {
267 
269  DeviceList,
271  (PVOID*)&pList,
273 
275  "Enter: WDFCHILDLIST %p", DeviceList);
276 
277  pList->EndScan();
278 }
279 
281 VOID
282 STDCALL
283 WDFEXPORT(WdfChildListBeginIteration)(
284  __in
286  __in
287  WDFCHILDLIST DeviceList,
288  __in
290  )
291 {
294 
296  DeviceList,
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 
331 NTSTATUS
332 STDCALL
333 WDFEXPORT(WdfChildListRetrieveNextDevice)(
334  __in
336  __in
337  WDFCHILDLIST DeviceList,
338  __in
340  __out
341  WDFDEVICE* Device,
344  )
345 {
349 
351  DeviceList,
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) {
404  if (pList->HasAddressDescriptions() == FALSE) {
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 
434 VOID
435 STDCALL
436 WDFEXPORT(WdfChildListEndIteration)(
437  __in
439  __in
440  WDFCHILDLIST DeviceList,
441  __in
443  )
444 {
447 
449  DeviceList,
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 
483 NTSTATUS
484 STDCALL
485 WDFEXPORT(WdfChildListAddOrUpdateChildDescriptionAsPresent)(
486  __in
488  __in
489  WDFCHILDLIST DeviceList,
490  __in
492  __in_opt
494  )
495 {
499 
501  DeviceList,
503  (PVOID*)&pList,
505 
507  "Enter: WDFCHILDLIST %p", DeviceList);
508 
510 
512  if (pList->HasAddressDescriptions() == FALSE) {
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 {
536  if (pList->HasAddressDescriptions()) {
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 
572 NTSTATUS
573 STDCALL
574 WDFEXPORT(WdfChildListUpdateChildDescriptionAsMissing)(
575  __in
577  __in
578  WDFCHILDLIST DeviceList,
579  __in
581  )
582 {
586 
588  DeviceList,
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!",
615  DeviceList, status);
616 
617  return status;
618 }
619 
621 VOID
622 STDCALL
623 WDFEXPORT(WdfChildListUpdateAllChildDescriptionsAsPresent)(
624  __in
626  __in
627  WDFCHILDLIST DeviceList
628  )
629 {
632 
634  DeviceList,
636  (PVOID*)&pList,
638 
640  "Enter: WDFCHILDLIST %p", DeviceList);
641 
643 
645  "Exit: WDFCHILDLIST %p", DeviceList);
646 }
647 
650 WDFDEVICE
651 STDCALL
652 WDFEXPORT(WdfChildListRetrievePdo)(
653  __in
655  __in
656  WDFCHILDLIST DeviceList,
657  __inout
659  )
660 {
666 
668  DeviceList,
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!",
682  RetrieveInfo->Size, sizeof(WDF_CHILD_RETRIEVE_INFO),
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) {
708  if (pList->HasAddressDescriptions() == FALSE) {
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 
748 BOOLEAN
749 STDCALL
750 WDFEXPORT(WdfChildListRequestChildEject)(
751  __in
753  __in
754  WDFCHILDLIST DeviceList,
755  __in
757  )
758 {
760  FxDevice* device;
762 
764  DeviceList,
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
PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER pAddr
BOOLEAN HasAddressDescriptions(VOID)
#define _Must_inspect_result_
Definition: no_sal2.h:62
_Must_inspect_result_ NTSTATUS GetNextDevice(__out WDFDEVICE *Device, __inout PWDF_CHILD_LIST_ITERATOR Iterator, __inout_opt PWDF_CHILD_RETRIEVE_INFO Info)
#define STATUS_INFO_LENGTH_MISMATCH
Definition: udferr_usr.h:133
_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 __in_opt
Definition: dbghelp.h:38
#define TRUE
Definition: types.h:120
#define STATUS_INVALID_PARAMETER
Definition: udferr_usr.h:135
_Must_inspect_result_ __in WDFCHILDLIST __in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription
VOID UpdateAllAsPresent(__in_opt PULONG ScanTag=NULL)
LONG NTSTATUS
Definition: precomp.h:26
NTSTATUS status
#define STATUS_INVALID_DEVICE_REQUEST
Definition: udferr_usr.h:138
WDFDEVICE GetDevice(VOID)
virtual _Must_inspect_result_ NTSTATUS AllocateEnumInfo(VOID)
Definition: fxdevice.cpp:1803
_Must_inspect_result_ __in WDFCHILDLIST __inout PWDF_CHILD_RETRIEVE_INFO RetrieveInfo
virtual VOID SetDeviceTelemetryInfoFlags(_In_ FxDeviceInfoFlags Flag)
Definition: fxdevice.hpp:1807
DriverGlobals
#define __inout_opt
Definition: dbghelp.h:53
VOID EndIteration(__inout PWDF_CHILD_LIST_ITERATOR Iterator)
return FALSE
FxDevice * device
_Must_inspect_result_ _In_ WDFCHILDLIST _In_ PWDF_CHILD_LIST_ITERATOR _Out_ WDFDEVICE _Inout_opt_ PWDF_CHILD_RETRIEVE_INFO Info
Definition: wdfchildlist.h:683
CfxDevice * GetDeviceFromId(__inout PWDF_CHILD_RETRIEVE_INFO Info)
_Must_inspect_result_ __in WDFDEVICE Device
FORCEINLINE VOID WDF_CHILD_RETRIEVE_INFO_INIT(_Out_ PWDF_CHILD_RETRIEVE_INFO Info, _In_ PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription)
Definition: wdfchildlist.h:309
#define TRACE_LEVEL_VERBOSE
Definition: storswtr.h:30
VOID BeginScan(__out_opt PULONG ScanTag=NULL)
Definition: devices.h:37
#define WDFEXPORT(a)
Definition: fxmacros.hpp:157
VOID EndScan(__inout_opt PULONG ScanTag=NULL)
FxChildList * pList
#define __out
Definition: dbghelp.h:62
_Must_inspect_result_ __in WDFCHILDLIST __in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER __inout PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddressDescription
_Must_inspect_result_ __in WDFCHILDLIST __in PWDF_CHILD_LIST_ITERATOR __out WDFDEVICE __inout_opt PWDF_CHILD_RETRIEVE_INFO Info
_Inout_ PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddressDescription
Definition: wdfchildlist.h:255
unsigned char BOOLEAN
_Must_inspect_result_ __in WDFDEVICE __in PWDF_CHILD_LIST_CONFIG __in_opt PWDF_OBJECT_ATTRIBUTES __out WDFCHILDLIST * DeviceList
_Must_inspect_result_ __in WDFDEVICE __in PWDF_CHILD_LIST_CONFIG __in_opt PWDF_OBJECT_ATTRIBUTES DeviceListAttributes
FxDevice * pDevice
__inline NTSTATUS FxVerifierCheckIrqlLevel(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in KIRQL Irql)
Definition: fxverifier.h:158
#define TRACINGDEVICE
Definition: dbgtrace.h:58
PFX_DRIVER_GLOBALS pFxDriverGlobals
#define STDCALL
Definition: wdf.h:45
_Must_inspect_result_ __in WDFDEVICE __in PWDF_CHILD_LIST_CONFIG Config
ULONG GetIdentificationDescriptionSize(VOID)
#define NT_SUCCESS(StatCode)
Definition: apphelp.c:32
_Must_inspect_result_ NTSTATUS GetAddressDescription(__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription, __out PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER AddressDescription)
_In_ WDFCHILDLIST _In_ PWDF_CHILD_LIST_ITERATOR Iterator
Definition: wdfchildlist.h:653
_In_ PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription
Definition: wdfchildlist.h:124
FxPointerNotNull(pFxDriverGlobals, Config)
WDFDEVICE handle
_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)
_Must_inspect_result_ __drv_maxIRQL(PASSIVE_LEVEL) NTSTATUS STDCALL WDFEXPORT(WdfChildListCreate)(__in PWDF_DRIVER_GLOBALS DriverGlobals
_Must_inspect_result_ NTSTATUS FxValidateObjectAttributes(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PWDF_OBJECT_ATTRIBUTES Attributes, __in ULONG Flags=FX_VALIDATE_OPTION_NONE_SPECIFIED)
#define __inout
Definition: dbghelp.h:50
#define PASSIVE_LEVEL
Definition: env_spec_w32.h:693
VOID NTAPI IoRequestDeviceEject(IN PDEVICE_OBJECT PhysicalDeviceObject)
Definition: devaction.c:2720
_Must_inspect_result_ _In_ WDFDEVICE Device
Definition: wdfchildlist.h:474
_Must_inspect_result_ _In_ WDFDEVICE _In_ PWDF_CHILD_LIST_CONFIG Config
Definition: wdfchildlist.h:474
#define TRACE_LEVEL_ERROR
Definition: storswtr.h:27
_Must_inspect_result_ _In_ WDFCHILDLIST _Inout_ PWDF_CHILD_RETRIEVE_INFO RetrieveInfo
Definition: wdfchildlist.h:538
#define DISPATCH_LEVEL
Definition: env_spec_w32.h:696
PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER pId
#define TRACINGPNP
Definition: dbgtrace.h:67
ULONG GetAddressDescriptionSize(VOID)
DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_VERBOSE, TRACINGPNP, "Enter, WDFDEVICE %p", Device)
#define NULL
Definition: types.h:112
_Must_inspect_result_ NTSTATUS UpdateAsMissing(__in PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Description)
__in WDFCHILDLIST __in PWDF_CHILD_LIST_ITERATOR Iterator
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 DeleteFromFailedCreate(VOID)
Definition: fxobject.cpp:391
FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals), Device, FX_TYPE_DEVICE,(PVOID *)&pDevice, &pFxDriverGlobals)
#define RtlZeroMemory(Destination, Length)
Definition: typedefs.h:262
WDF_CHILD_RETRIEVE_INFO info
__inline PFX_DRIVER_GLOBALS GetFxDriverGlobals(__in PWDF_DRIVER_GLOBALS DriverGlobals)
Definition: fxglobals.h:597
static _Must_inspect_result_ NTSTATUS _ValidateConfig(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PWDF_CHILD_LIST_CONFIG Config, __in size_t *TotalDescriptionSize)
#define __in
Definition: dbghelp.h:35
VOID BeginIteration(__inout PWDF_CHILD_LIST_ITERATOR Iterator)
FxVerifierDbgBreakPoint(pFxDriverGlobals)
size_t totalDescriptionSize
Definition: ps.c:97