WdfChildListRetrieveAddressDescription function (wdfchildlist.h)

Article
02/22/2024

[Applies to KMDF only]

The WdfChildListRetrieveAddressDescription method locates a child device that has a specified identification description and retrieves the device's address description.

Syntax

NTSTATUS WdfChildListRetrieveAddressDescription(
  [in]      WDFCHILDLIST                                 ChildList,
  [in]      PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
  [in, out] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER        AddressDescription
);

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.

[in, out] AddressDescription

A pointer to a WDF_CHILD_ADDRESS_DESCRIPTION_HEADER structure that identifies a child address description. The framework fills in this description.

Return value

WdfChildListRetrieveAddressDescription 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_NO_SUCH_DEVICE	No device matched the specified identification description.
STATUS_INVALID_DEVICE_REQUEST	The child list did not contain address descriptions, or the size of the address description that AddressDescription specified was incorrect.

This method might also return other NTSTATUS values.

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

Remarks

For more information about child lists, see Dynamic Enumeration.

Examples

The following code example searches a child list for a child device whose identification description contains the value that is specified by SomeValue. If WdfChildListRetrieveAddressDescription locates the device, it retrieves the device's address description.

MY_IDENTIFICATION_DESCRIPTION  id;
MY_ADDRESS_DESCRIPTION  addrDescrip;

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                 &id.Header,
                                                 sizeof(id)
                                                 );
WDF_CHILD_ADDRESS_DESCRIPTION_HEADER_INIT(
                                          &addrDescrip.Header,
                                          sizeof(addrDescrip)
                                          );

id.DeviceIdentifier = SomeValue;
status = WdfChildListRetrieveAddressDescription(
                                                list,
                                                &idDescrip.Header,
                                                &addrDescrip.Header
                                                );
if (!NT_SUCCESS(status) {
    return status;
}

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