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

Статья
02/29/2024

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

Метод WdfChildListAddOrUpdateChildDescriptionAsPresent добавляет новое дочернее описание в список дочерних элементов или обновляет существующее дочернее описание.

Синтаксис

NTSTATUS WdfChildListAddOrUpdateChildDescriptionAsPresent(
  [in]           WDFCHILDLIST                                 ChildList,
  [in]           PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
  [in, optional] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER        AddressDescription
);

Параметры

[in] ChildList

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

[in] IdentificationDescription

Указатель на структуру WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER , которая идентифицирует описание идентификации дочернего элемента.

[in, optional] AddressDescription

Указатель на структуру WDF_CHILD_ADDRESS_DESCRIPTION_HEADER , которая определяет описание дочернего адреса. Если описание адреса не требуется, этот параметр может иметь значение NULL.

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

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

Код возврата	Описание
STATUS_INVALID_PARAMETER	Входной параметр был недопустимым.
STATUS_INVALID_DEVICE_REQUEST	Неправильный размер описания идентификации или адреса.
STATUS_OBJECT_NAME_EXISTS	Дочерний элемент с указанным описанием идентификации уже существует. В этом случае платформа копирует предоставленное описание адреса в существующий дочерний элемент.
STATUS_INSUFFICIENT_RESOURCES	Может быть выделено дочернее описание.

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

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

Метод WdfChildListAddOrUpdateChildDescriptionAsPresent ищет в указанном дочернем списке дочерний элемент, соответствующий указанному описанию идентификации. Если совпадение найдено, платформа обновляет описание дочернего адреса, если указано, и возвращает STATUS_OBJECT_NAME_EXISTS. Если совпадения не найдены, платформа создает новый дочерний элемент, используя предоставленные описания идентификации и адреса.

Драйвер может вызвать WdfChildListAddOrUpdateChildDescriptionAsPresent , чтобы добавить или обновить одно дочернее описание. Платформа немедленно обновляет дочерний список и информирует руководителя Plug and Play (PnP) о внесении изменений.

Кроме того, драйвер может выполнять следующие действия.

Вызовите WdfChildListBeginScan , чтобы подготовить дочерний список к обновлению.
Вызовите WdfChildListAddOrUpdateChildDescriptionAsPresent несколько раз, чтобы добавить или обновить дочерние описания для всех дочерних элементов родительского устройства.
Вызовите WdfChildListEndScan для обработки изменений в дочернем списке.

Если драйвер использует эту альтернативную процедуру, платформа ожидает, пока драйвер не вызовет WdfChildListEndScan , прежде чем обновить дочерний список и сообщить диспетчеру PnP о внесении изменений. Когда драйвер вызывает WdfChildListBeginScan, платформа помечает все ранее сообщаемые устройства как отсутствуют. Поэтому драйвер должен вызывать WdfChildListAddOrUpdateChildDescriptionAsPresent для всех дочерних элементов, а не только для новых дочерних элементов.

Через некоторое время после вызова драйвера WdfChildListAddOrUpdateChildDescriptionAsPresent платформа вызывает функцию обратного вызова EvtChildListCreateDevice драйвера, чтобы драйвер смог создать объект устройства, вызвав WdfDeviceCreate.

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

Примеры

Следующий пример кода основан на коде, который содержится в примере kmdf_fx2 . В этом примере дочерние описания добавляются в список дочерних элементов устройства по умолчанию. Он извлекает параметры коммутатора, ранее сохраненные драйвером в контекстном пространстве объекта устройства, а затем вызывает WdfChildListAddOrUpdateChildDescriptionAsPresent для каждого заданного параметра.

PDEVICE_CONTEXT  pDeviceContext;
WDFCHILDLIST  list;
UCHAR  i;
NTSTATUS  status;

pDeviceContext = GetDeviceContext(Device);
list = WdfFdoGetDefaultChildList(Device);

WdfChildListBeginScan(list);
 
for (i = 0; i < RTL_BITS_OF(UCHAR); i++) {
    if (pDeviceContext->CurrentSwitchState & (1<<i)) {
        PDO_IDENTIFICATION_DESCRIPTION description;
        WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                 &description.Header,
                                                 sizeof(description)
                                                 );
        description.SwitchNumber = i; 
 
        status = WdfChildListAddOrUpdateChildDescriptionAsPresent(
                                                 list, 
                                                 &description.Header, 
                                                 NULL
                                                 );
        if (!NT_SUCCESS(status) && (status != STATUS_OBJECT_NAME_EXISTS)) {
            break;
        }
    }
}
WdfChildListEndScan(list);

Требования

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