WdfChildListUpdateChildDescriptionAsMissing function (wdfchildlist.h)

Article
04/18/2022

[Applies to KMDF only]

The WdfChildListUpdateChildDescriptionAsMissing method informs the framework that a specified child device is currently unplugged or otherwise unavailable.

Syntax

NTSTATUS WdfChildListUpdateChildDescriptionAsMissing(
  [in] WDFCHILDLIST                                 ChildList,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription
);

Parameters

[in] ChildList

A handle to a child list object.

[in] IdentificationDescription

A pointer to a caller-allocated WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER structure that identifies a driver-supplied child identification description.

Return value

WdfChildListUpdateChildDescriptionAsMissing returns STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE, if the operation succeeds. Otherwise, this method might return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	An input parameter was invalid.
STATUS_INVALID_DEVICE_REQUEST	The size of the structure that IdentificationDescription points to was incorrect.
STATUS_NO_SUCH_DEVICE	The specified device was not found in the child list.

This method might also return other NTSTATUS values.

A system bug check occurs if the driver supplies an invalid object handle.

Remarks

Your driver can report that a device is unavailable even if the driver never called WdfChildListAddOrUpdateChildDescriptionAsPresent to report that the device was present. In this case, the WdfChildListUpdateChildDescriptionAsMissing method just returns STATUS_NO_SUCH_DEVICE.

If you want to report that all devices in a child list are unavailable, your driver can simply call WdfChildListBeginScan, followed immediately by WdfChildListEndScan, instead of calling WdfChildListUpdateChildDescriptionAsMissing for each device.

For more information about child devices and child lists, see Dynamic Enumeration.

Examples

The following code example informs the framework that a child device with a specified serial number is unavailable.

PDO_IDENTIFICATION_DESCRIPTION  description;
NTSTATUS  status;

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                 &description.Header,
                                                 sizeof(description)
                                                 );

description.SerialNo = SerialNo;
status = WdfChildListUpdateChildDescriptionAsMissing(
                                                     list,
                                                     &description.Header
                                                     );

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Header	wdfchildlist.h (include Wdf.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Share via