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

Статья
08/08/2023

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

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

Синтаксис

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY EvtWdfChildListAddressDescriptionCopy;

void EvtWdfChildListAddressDescriptionCopy(
  [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, которая определяет место назначения дочернего описания адреса.

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

Никакой

Замечания

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

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

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

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

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

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

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

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

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

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

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

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

Требования

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