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

Статья
02/29/2024

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

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

Синтаксис

NTSTATUS WdfChildListRetrieveNextDevice(
  [in]      WDFCHILDLIST             ChildList,
  [in]      PWDF_CHILD_LIST_ITERATOR Iterator,
  [out]     WDFDEVICE                *Device,
  [in, out] PWDF_CHILD_RETRIEVE_INFO Info
);

Параметры

[in] ChildList

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

[in] Iterator

Указатель на ту же структуру, выделенную вызывающим объектом WDF_CHILD_LIST_ITERATOR , которую драйвер ранее предоставлял для WdfChildListBeginIteration.

[out] Device

Указатель на расположение, которое получает дескриптор объекта устройства платформы. Полученное значение равно NULL , если параметр Iterator задает флаг WdfRetrievePendingChildren .

[in, out] Info

Указатель на структуру, выделенную вызывающим объектом WDF_CHILD_RETRIEVE_INFO . Этот указатель является необязательным и может иметь значение NULL.

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

WdfChildListRetrieveNextDevice возвращает STATUS_SUCCESS или другое значение состояния, для которого NT_SUCCESS(status) равно TRUE, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_PARAMETER	Входной параметр был недопустимым.
STATUS_INFO_LENGTH_MISMATCH	Неправильный размер структуры WDF_CHILD_LIST_ITERATOR, указанной итератором
STATUS_INVALID_DEVICE_REQUEST	Было указано описание адреса, но дочерний список не содержал описаний адресов.
STATUS_NO_MORE_ENTRIES	Платформа достигла конца дочернего списка.
STATUS_INVALID_DEVICE_STATE	Драйвер не вызывал WdfChildListBeginIteration.

Этот метод также может возвращать другие значения NTSTATUS.

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

Перед вызовом WdfChildListRetrieveNextDevice драйвер должен вызвать WdfChildListBeginIteration. После завершения обхода дочернего списка драйвер должен вызвать WdfChildListEndIteration. Затем платформа информирует руководителя Plug and Play (PnP) о любых изменениях, внесенных в дочерний список.

Каждый раз, когда драйвер вызывает WdfChildListRetrieveNextDevice, метод получает следующий дочерний элемент, соответствующий следующим условиям поиска:

Тип дочернего элемента должен соответствовать WDF_RETRIEVE_CHILD_FLAGS типизированным флагам в структуре WDF_CHILD_LIST_ITERATOR драйвера.
Если драйвер предоставляет указатель на функцию обратного вызова EvtChildListIdentificationDescriptionCompare в своей WDF_CHILD_RETRIEVE_INFO структуре, функция обратного вызова должна возвращать значение TRUE.

Если драйвер предоставляет функцию обратного вызова EvtChildListIdentificationDescriptionCompare , он также должен предоставить описание идентификации в структуре WDF_CHILD_RETRIEVE_INFO. Платформа использует функцию обратного вызова для сравнения переданного дескриптора идентификации с описанием дочернего элемента в дочернем списке, если WDF_RETRIEVE_CHILD_FLAGS типизированные флаги указывают, что дочерний элемент является кандидатом на соответствие. Если функция обратного вызова возвращает значение TRUE, совпадение выполняется успешно. Если функция обратного вызова возвращает значение FALSE, платформа ищет другого кандидата.

Когда WdfChildListRetrieveNextDevice находит совпадение, он копирует описание идентификатора ребенка и описание адреса в структуру WDF_CHILD_RETRIEVE_INFO драйвера, если указатель, который указывает параметр Info , не равен NULL. (Обратите внимание, что эта операция перезаписывает описание идентификации входных данных драйвера.) Метод также помещает дескриптор объекта устройства дочернего элемента в расположение, которое идентифицирует параметр Device .

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

Примеры

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

WDF_CHILD_LIST_ITERATOR  iterator;
WDFDEVICE  hChild;
NTSTATUS  status = STATUS_INVALID_PARAMETER;
WDFCHILDLIST  list;
WDF_CHILD_RETRIEVE_INFO  childInfo;
PDO_IDENTIFICATION_DESCRIPTION  description;
BOOLEAN  ret;

list = WdfFdoGetDefaultChildList(Device);

WDF_CHILD_LIST_ITERATOR_INIT(
                             &iterator,
                             WdfRetrievePresentChildren
                             );
WdfChildListBeginIteration(
                           list,
                           &iterator
                           );
for (;;) {
    WDF_CHILD_RETRIEVE_INFO_INIT(
                                 &childInfo,
                                 &description.Header
                                 );
    WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                     &description.Header,
                                                     sizeof(description)
                                                     );
    status = WdfChildListRetrieveNextDevice(
                                            list, 
                                            &iterator, 
                                            &hChild, 
                                            &childInfo
                                            );
    if (!NT_SUCCESS(status) || status == STATUS_NO_MORE_ENTRIES) {
       break;
    }
    ASSERT(childInfo.Status == WdfChildListRetrieveDeviceSuccess);

    ret = WdfChildListRequestChildEject(
                                        list,
                                        &description.Header
                                        );
    if(!ret) {
       WDFVERIFY(ret);
    }
}
WdfChildListEndIteration(
                         list,
                         &iterator
                         );
if (status == STATUS_NO_MORE_ENTRIES) {
   status = STATUS_SUCCESS;
}
return status;

Требования

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