функция обратного вызова 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, которая определяет целевое расположение описания дочернего адреса.

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

None

Remarks

Если драйвер шины использует динамическое перечисление, он может зарегистрировать функцию обратного вызова 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 и DestinationAddressDescription функции обратного вызова найдите указатели на динамически выделенную память.
Скопируйте динамически выделенную память из источника в место назначения с помощью указателей.
Скопируйте другие элементы структуры из структуры SourceAddressDescription функции обратного вызова в структуру DestinationAddressDescription функции обратного вызова.

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

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

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

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

Требования

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