функция обратного вызова EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE (wdfchildlist.h)

Статья
02/07/2025

[Применимо только к KMDF]

Функция обратного вызова события драйвера EvtChildListAddressDescriptionDuplicate функция обратного вызова событий дублирует описание дочернего адреса.

Синтаксис

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE EvtWdfChildListAddressDescriptionDuplicate;

NTSTATUS EvtWdfChildListAddressDescriptionDuplicate(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER SourceAddressDescription,
  [out] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER DestinationAddressDescription
)
{...}

Параметры

[in] ChildList

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

[in] SourceAddressDescription

Указатель на структуру WDF_CHILD_ADDRESS_DESCRIPTION_HEADER, которая определяет исходное расположение описания дочернего адреса.

[out] DestinationAddressDescription

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

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

Функция обратного вызова EvtChildListAddressDescriptionDuplicate должна возвращать STATUS_SUCCESS или другое значение состояния, для которого NT_SUCCESS(состояние) равно TRUE, если операция завершится успешно. В противном случае эта функция должна возвращать значение состояния, для которого NT_SUCCESS (состояние) равно FALSE.

Замечания

Если драйвер шины использует динамическое перечисление, он может зарегистрировать функцию обратного вызова EvtChildListAddressDescriptionDuplicate путем вызова WdfFdoInitSetDefaultChildListConfig или WdfChildListCreate.

Платформа дублирует описания адресов, предоставленных драйвером, чтобы иметь внутренние копии описаний.

Функция обратного вызова EvtChildListAddressDescriptionDuplicate должна создать дубликатную копию описания адреса. Драйвер должен предоставить эту функцию обратного вызова, если его дочерние устройства требуют описания адреса, и если платформа не может вызвать RtlCopyMemory, чтобы дублировать описание адреса. (Платформа не может вызывать RtlCopyMemory, если описание содержит указатели на дополнительную память.)

Если драйвер предоставляет описание адресов, но не предоставляет EvtChildListAddressDescriptionDuplicate функцию обратного вызова, платформа дублирует описания адресов, вызывая RtlCopyMemory.

Ниже описан типичный сценарий:

Драйвер определяет, существует ли дочернее устройство.
Драйвер создает описание адреса, заполнив определяемую драйвером структуру, содержащую структуру WDF_CHILD_ADDRESS_DESCRIPTION_HEADER, и, возможно, динамически распределив дополнительную память для хранения сведений об адресе с размером устройства.
Драйвер вызывает WdfChildListAddOrUpdateChildDescriptionAsPresent для отправки указателя на описание адреса.
Платформа вызывает функцию обратного вызова EvtChildListAddressDescriptionDuplicate обратного вызова (если она существует) или RtlCopyMemory дублировать описание адреса, чтобы он может иметь внутреннюю копию описания.

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

Выделение дополнительной памяти обычно путем вызова ExAllocatePool.
Сохраните адрес выделенной памяти в структуре описания адресов, определяемой драйвером (то есть структуре функции обратного вызова.
Скопируйте другие члены структуры из структуры функции обратного вызова SourceAddressDescription структуру функции обратного вызова в структуру DestinationAddressDescription.

Единственный метод объекта дочернего списка платформы, что функция обратного вызова драйвера EvtChildListAddressDescriptionDuplicate функция обратного вызова — WdfChildListGetDevice.

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

Если драйвер предоставляет функцию обратного вызова EvtChildListAddressDescriptionDuplicate, может потребоваться также функции обратного вызова EvtChildListAddressDescriptionCopy и EvtChildListAddressDescriptionCleanup функции обратного вызова.

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

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия KMDF	1.0
заголовка	wdfchildlist.h (включая Wdf.h)
IRQL	<= DISPATCH_LEVEL