Функция WdfChildListRetrievePdo (wdfchildlist.h)

Статья
08/08/2023

[Относится только к KMDF]

Метод WdfChildListRetrievePdo возвращает дескриптор объекту устройства платформы, связанному с указанным дочерним описанием в дочернем списке.

Синтаксис

WDFDEVICE WdfChildListRetrievePdo(
  [in]      WDFCHILDLIST             ChildList,
  [in, out] PWDF_CHILD_RETRIEVE_INFO RetrieveInfo
);

Параметры

[in] ChildList

Дескриптор дочернего объекта списка.

[in, out] RetrieveInfo

Указатель на структуру, выделенную драйвером WDF_CHILD_RETRIEVE_INFO , которую драйвер инициализирует с описанием идентификации извлекаемого дочернего элемента.

Возвращаемое значение

WdfChildListRetrievePdo возвращает дескриптор объекту устройства платформы, если указанное дочернее устройство находится в дочернем списке, если объект устройства платформы существует для дочернего устройства и если платформа сообщила о существовании устройства диспетчеру PnP. В противном случае метод возвращает значение NULL. Платформа возвращает дополнительные сведения о состоянии в элементе Status структуры WDF_CHILD_RETRIEVE_INFO .

Системная ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Метод WdfChildListRetrievePdo просматривает указанный список дочерних элементов, ища дочерний элемент с описанием идентификации, соответствующим описанию, предоставленному драйвером в структуре WDF_CHILD_RETRIEVE_INFO. Если платформа находит совпадение и если дочерний элемент содержит описание адреса, платформа заполняет описание адреса структуры.

Обязательно заключите этот вызов в оболочку wdfChildListBeginIteration и WdfChildListEndIteration , чтобы защитить вызывающий объект от внезапного удаления PnP PDO в другом потоке.

Дополнительные сведения о дочерних списках см. в разделе Динамическое перечисление.

Примеры

В следующем примере кода выполняется поиск дочернего списка, чтобы найти дочернее устройство, описание идентификации которого содержит указанный серийный номер, и получает дескриптор объекта устройства, представляющего дочернее устройство.

WDF_CHILD_LIST_ITERATOR iterator;
PDO_IDENTIFICATION_DESCRIPTION description;
WDF_CHILD_RETRIEVE_INFO info;
WDFDEVICE hChild;

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

description.SerialNo = DeviceSerialNumber;

WDF_CHILD_RETRIEVE_INFO_INIT(
                             &info,
                             &description.Header
                             );

WDF_CHILD_LIST_ITERATOR_INIT(&iterator, WdfRetrieveAllChildren);
WdfChildListBeginIteration(childList, &iterator);

hChild = WdfChildListRetrievePdo(
                                 childList,
                                 &info
                                 );

... access hChild ...

WdfChildListEndIteration(childList, &iterator);

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Верхняя часть	wdfchildlist.h (включая Wdf.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки Платформы).
IRQL	<= DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

См. также раздел

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT

WDF_CHILD_RETRIEVE_INFO

WDF_CHILD_RETRIEVE_INFO_INIT