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

Статья
08/08/2023

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

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

Синтаксис

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COPY EvtWdfChildListIdentificationDescriptionCopy;

void EvtWdfChildListIdentificationDescriptionCopy(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SourceIdentificationDescription,
  [out] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER DestinationIdentificationDescription
)
{...}

Параметры

[in] ChildList

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

[in] SourceIdentificationDescription

Указатель на структуру WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER , которая определяет исходное расположение описания идентификации ребенка.

[out] DestinationIdentificationDescription

Указатель на структуру WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER , идентифицирующая целевое расположение описания идентификации дочерних объектов.

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

None

Remarks

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

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

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

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

Ниже описан возможный сценарий.

Драйвер, просматривающий дочерний список, вызывает WdfChildListRetrieveNextDevice. Драйвер предоставляет структуру WDF_CHILD_RETRIEVE_INFO , чтобы получить описание идентификации дочернего устройства.
Платформа вызывает функцию обратного вызова EvtChildListIdentificationDescriptionCopy (если она существует) или RtlCopyMemory для копирования описания идентификации устройства. Источником операции копирования является внутренняя копия описания платформы. Назначение — это память, выделенная драйвером и определяемая в его WDF_CHILD_RETRIEVE_INFO структуре.

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

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

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

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

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

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

Требования

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