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

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

Функция обратного вызова события СобытияCompare драйвера 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.

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

  1. Драйвер вызывает WdfChildListRetrieveAddressDescription для получения описания адреса, связанного с копией описания идентификации платформы, которая хранится в дочернем списке.
  2. Платформа проходит по дочернему списку. Чтобы определить, соответствует ли описание идентификации дочернего элемента драйверу, указанному при вызове WdfChildListRetrieveAddressDescription, платформа вызывает либо функцию обратного вызова EvtChildListIdentificationDescriptionCompare (если она существует) или RtlCompareMemory.
  3. Если два описания идентификации совпадают (и сравнение возвращает значение TRUE), платформа прекращает обход списка.
  4. Платформа копирует описание адреса в память, которую драйвер предоставил при вызове 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

См. также

RtlCompareMemory

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER

WDF_RETRIEVE_CHILD_FLAGS

WdfChildListCreate

WdfChildListGetDevice

WdfChildListRetrieveAddressDescription

WdfChildListRetrieveNextDevice

WdfFdoInitSetDefaultChildListConfig