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

Статья
03/01/2024

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

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

Синтаксис

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE EvtWdfChildListIdentificationDescriptionCompare;

BOOLEAN EvtWdfChildListIdentificationDescriptionCompare(
  [in] WDFCHILDLIST ChildList,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER FirstIdentificationDescription,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SecondIdentificationDescription
)
{...}

Параметры

[in] ChildList

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

[in] FirstIdentificationDescription

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

[in] SecondIdentificationDescription

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

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

Функция обратного вызова EvtChildListIdentificationDescriptionCompare должна возвращать значение TRUE , если два описания идентификации дочерних объектов совпадают. В противном случае эта функция должна возвращать значение FALSE.

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

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

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

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

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

Драйвер вызывает WdfChildListRetrieveAddressDescription , чтобы получить описание адреса, связанное с копией описания идентификации платформы, которая хранится в дочернем списке.
Платформа просматривает дочерний список. Чтобы определить, совпадает ли описание идентификации дочернего элемента с описанием, указанным драйвером при вызове WdfChildListRetrieveAddressDescription, платформа вызывает функцию обратного вызова EvtChildListIdentificationDescriptionCompareCompare (если она существует) или RtlCompareMemory.
Если два описания идентификации совпадают (и сравнение возвращает значение TRUE), платформа прекращает обход списка.
Платформа копирует описание адреса в память, предоставленную драйвером при вызове WdfChildListRetrieveAddressDescription.

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

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

typedef struct _PDO_IDENTIFICATION_DESCRIPTION {
  WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Header;
  ULONG DeviceSerialNumber;
  ULONG CchHardwareIds;
  PWCHAR HardwareIds;
} PDO_IDENTIFICATION_DESCRIPTION, *PPDO_IDENTIFICATION_DESCRIPTION;

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

Если драйвер вызывает WdfChildListRetrieveNextDevice для просмотра списка устройств, вы можете предоставить дополнительную функцию обратного вызова EvtChildListIdentificationDescriptionCompare , которую платформа использует при поиске следующего описания для извлечения. Платформа ищет дочерние устройства, соответствующие предоставленным драйвером WDF_RETRIEVE_CHILD_FLAGS типизированным флагам. Если драйвер предоставляет специальную функцию обратного вызова EvtChildListIdentificationDescriptionCompare , платформа использует функцию обратного вызова для уточнения поиска. Если драйвер не предоставляет специальную функцию обратного вызова EvtChildListIdentificationDescriptionCompareCompare, платформа не вызывает RtlCompareMemory— она просто возвращает каждое дочернее устройство, соответствующее указанным флагам.

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

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

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

Требования

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