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

Статья
08/08/2023

[Относится только к 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(status) равно TRUE, если операция выполнена успешно. В противном случае эта функция должна возвращать значение состояния, для которого NT_SUCCESS(status) равно FALSE.

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

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

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

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

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

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

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

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

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

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

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

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

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Верхняя часть	wdfchildlist.h (включая Wdf.h)
IRQL	<= DISPATCH_LEVEL