EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE función de devolución de llamada (wdfchildlist.h)

Artículo
02/07/2025

[Solo se aplica a KMDF]

La función de devolución de llamada de eventos EvtChildListIdentificationDescriptionCompare compara una descripción de identificación secundaria con otra.

Sintaxis

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
)
{...}

Parámetros

[in] ChildList

Identificador de un objeto de lista secundaria del marco.

[in] FirstIdentificationDescription

Puntero a una estructura de WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER que identifica la descripción de identificación secundaria.

[in] SecondIdentificationDescription

Puntero a una estructura de WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER que identifica otra descripción de identificación secundaria.

Valor devuelto

La función de devolución de llamada EvtChildListIdentificationDescriptionCompare debe devolver TRUE si coinciden las dos descripciones de identificación secundarias. De lo contrario, esta función debe devolver FALSE.

Observaciones

Si un controlador de bus usa enumeración dinámica, puede registrar un EvtChildListIdentificationDescriptionCompare función de devolución de llamada llamando a WdfFdoInitSetDefaultChildListConfig o WdfChildListCreate. El controlador también puede registrar un segundo caso especial EvtChildListIdentificationDescriptionCompare función de devolución de llamada cuando llama a WdfChildListRetrieveNextDevice.

El marco compara dos descripciones de identificación cuando debe determinar si ambas descripciones identifican el mismo dispositivo.

La función de devolución de llamada EvtChildListIdentificationDescriptionCompare debe comparar el contenido de dos descripciones de identificación y devolver TRUE si coinciden. Un controlador debe proporcionar esta función de devolución de llamada si el marco no puede llamar a RtlCompareMemory para comparar las descripciones de identificación. (El marco no puede llamar a rtlCompareMemory si las descripciones contienen punteros a memoria adicional).

Si el controlador no proporciona una función de devolución de llamada EvtChildListIdentificationDescriptionCompare, el marco compara las descripciones de identificación llamando a RtlCompareMemory.

En los pasos siguientes se describe un escenario posible:

El controlador llama a WdfChildListRetrieveAddressDescription para obtener la descripción de la dirección asociada a la copia del marco de una descripción de identificación, que se almacena en una lista secundaria.
El marco recorre la lista secundaria. Para determinar si la descripción de identificación de un elemento secundario coincide con la especificada por el controlador cuando llamó a función WdfChildListRetrieveAddressDescription, el marco llama al EvtChildListIdentificationDescriptionCompare función de devolución de llamada (si existe) o RtlCompareMemory.
Si las dos descripciones de identificación coinciden (y la comparación devuelve TRUE), el marco deja de atravesar la lista.
El marco copia la descripción de la dirección en la memoria que el controlador proporcionó cuando llamó a WdfChildListRetrieveAddressDescription.

El marco puede usar RtlCompareMemory para comparar descripciones de identificación, si cada descripción consta de una sola estructura con un tamaño predeterminado especificado por el IdentificationDescriptionSize miembro de la estructura de WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER. Sin embargo, a veces la descripción también debe contener información adicional almacenada en memoria asignada dinámicamente. En este caso, normalmente definirá una estructura de descripción para que un miembro apunte a la memoria asignada dinámicamente y el controlador debe proporcionar un EvtChildListIdentificationDescriptionCompare función de devolución de llamada.

Esta función de devolución de llamada determina si dos descripciones de identificación representan el mismo dispositivo. Es posible que la función de devolución de llamada no tenga que comparar todos los miembros de la estructura para realizar esa determinación. Por ejemplo, supongamos que una descripción de identificación contiene un número de serie y un conjunto de identificadores de hardware, como se indica a continuación:

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

En este caso, la función de devolución de llamada EvtChildListIdentificationDescriptionCompa re probablemente tenga que comparar solo los miembros DeviceSerialNumber para determinar si dos descripciones representan el mismo dispositivo.

Si el controlador llama a WdfChildListRetrieveNextDevice para atravesar una lista de dispositivos, puede proporcionar un adicional EvtChildListIdentificationDescriptionCompare función de devolución de llamada que usa el marco al buscar la siguiente descripción para recuperar. El marco busca dispositivos secundarios que coincidan con marcas de tipo WDF_RETRIEVE_CHILD_FLAGSproporcionados por el controlador. Si un controlador proporciona una función de devolución de llamada EvtChildListIdentificationDescriptionCompare, el marco usa la función de devolución de llamada para refinar la búsqueda. Si el controlador no proporciona una función de devolución de llamada EvtChildListIdentificationDescriptionCompare, el marco no llama a RtlCompareMemory, simplemente devuelve cada dispositivo secundario que coincida con las marcas especificadas.

El único método de objeto framework child-list que la función de devolución de llamada EvtChildListIdentificationDescriptionCompare puede llamar es WdfChildListGetDevice.

El marco adquiere un bloqueo interno de objeto de lista secundaria antes de llamar a la función de devolución de llamada EvtChildListIdentificationDescriptionCompareEvtChildListIdentificationDescriptionCompare. La función de devolución de llamada solo debe realizar operaciones relacionadas con la operación de comparación, como llamar a métodos de objetos de memoria del marco y acceder al espacio de contexto del objeto. No debe llamar a métodos que accedan a otros controladores.

Para obtener más información sobre la enumeración dinámica, vea Enumerar los dispositivos en un bus.