Функция WdfChildListAddOrUpdateChildDescriptionAsPresent (wdfchildlist.h)
[Относится только к 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, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:
Код возврата | Описание |
---|---|
|
Входной параметр был недопустимым. |
|
Неправильный размер описания идентификации или адреса. |
|
Дочерний элемент с указанным описанием идентификации уже существует. В этом случае платформа копирует предоставленное описание адреса в существующий дочерний элемент. |
|
Может быть выделено дочернее описание. |
Этот метод также может возвращать другие значения NTSTATUS.
Системная ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.
Комментарии
Метод WdfChildListAddOrUpdateChildDescriptionAsPresent ищет в указанном дочернем списке дочерний элемент, соответствующий указанному описанию идентификации. Если совпадение найдено, платформа обновляет описание дочернего адреса, если указано, и возвращает STATUS_OBJECT_NAME_EXISTS. Если совпадения не найдены, платформа создает новый дочерний элемент, используя предоставленные описания идентификации и адреса.
Драйвер может вызвать WdfChildListAddOrUpdateChildDescriptionAsPresent , чтобы добавить или обновить одно дочернее описание. Платформа немедленно обновляет дочерний список и информирует руководителя Plug and Play (PnP) о внесении изменений.
Кроме того, драйвер может выполнять следующие действия.
- Вызовите WdfChildListBeginScan , чтобы подготовить дочерний список к обновлению.
- Вызовите WdfChildListAddOrUpdateChildDescriptionAsPresent несколько раз, чтобы добавить или обновить дочерние описания для всех дочерних элементов родительского устройства.
- Вызовите WdfChildListEndScan для обработки изменений в дочернем списке.
Через некоторое время после вызова драйвера 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) |
См. также раздел
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER