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

Статья
08/08/2023

[Относится только к KMDF]

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

Синтаксис

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE EvtWdfChildListIdentificationDescriptionDuplicate;

NTSTATUS EvtWdfChildListIdentificationDescriptionDuplicate(
  [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, которая определяет целевое расположение повторяющегося описания идентификации дочернего элемента.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Требования

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