WdfFdoRetrieveNextStaticChild method
[Applies to KMDF only]
The WdfFdoRetrieveNextStaticChild method retrieves a handle to the next framework device object in a list of child devices.
Syntax
WDFDEVICE WdfFdoRetrieveNextStaticChild( [in] WDFDEVICE Fdo, [in, optional] WDFDEVICE PreviousChild, [in] ULONG Flags );
Parameters
- Fdo [in]
-
A handle to a framework device object that represents the parent device.
- PreviousChild [in, optional]
-
A handle to a framework device object that represents the child device that was returned by a previous call to WdfFdoRetrieveNextStaticChild. For the first call to WdfFdoRetrieveNextStaticChild, this value must be NULL.
- Flags [in]
-
A WDF_RETRIEVE_CHILD_FLAGS-typed enumerator value that identifies the type of child devices that the method should retrieve. This parameter cannot be zero.
Return value
If the operation succeeds, the method returns a handle to a framework device object. Otherwise it returns NULL.
A system bug check occurs if the driver supplies an invalid object handle.
Remarks
Bus drivers that use static bus enumeration can call WdfFdoRetrieveNextStaticChild.
To retrieve the items in a list of child devices, the driver should:
-
Call WdfFdoLockStaticChildListForIteration to lock the child list.
-
Repeatedly call WdfFdoRetrieveNextStaticChild to obtain the items in the list, one at a time, until the method returns NULL.
-
Call WdfFdoUnlockStaticChildListFromIteration to unlock the child list.
For more information about static child lists, see Enumerating the Devices on a Bus.
Examples
The following code example searches a static child list until it finds a child device with a serial number that matches a specific value. For other example uses of WdfFdoRetrieveNextStaticChild, see the Toaster sample bus driver.
PPDO_DEVICE_DATA pdoData; WDFDEVICE hChild; NTSTATUS status = STATUS_INVALID_PARAMETER; WdfFdoLockStaticChildListForIteration(Device); while ((hChild = WdfFdoRetrieveNextStaticChild( Device, hChild, WdfRetrieveAddedChildren )) != NULL) { // // Obtain device object context data and check the // stored serial number. // pdoData = PdoGetData(hChild); if (SerialNo == pdoData->SerialNo) { status = STATUS_SUCCESS; WdfPdoRequestEject(hChild); break; } } WdfFdoUnlockStaticChildListFromIteration(Device);
Requirements
Minimum KMDF version | 1.0 |
---|---|
Header |
|
Library |
|
IRQL | <= DISPATCH_LEVEL |
DDI compliance rules | DriverCreate, KmdfIrql, KmdfIrql2, PdoDeviceInitAPI |
See also