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

Artículo
08/08/2023

[Solo se aplica a KMDF]

La función de devolución de llamada de eventos EvtChildListIdentificationDescriptionCompare de un controlador 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 las dos descripciones de identificación secundarias coinciden. De lo contrario, esta función debe devolver FALSE.

Comentarios

Si un controlador de bus usa una enumeración dinámica, puede registrar una función de devolución de llamada EvtChildListIdentificationDescriptionCompare llamando a WdfFdoInitSetDefaultChildListConfig o WdfChildListCreate. El controlador también puede registrar una segunda función de devolución de llamada EvtChildListIdentificationDescriptionCompare de segundo caso especial 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 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 WdfChildListRetrieveAddressDescription, el marco llama a la función de devolución de llamada EvtChildListIdentificationDescriptionCompare (si existe) o RtlCompareMemory.
Si las dos descripciones de identificación coinciden (y la comparación devuelve TRUE), el marco deja de recorrer la lista.
El marco copia la descripción de la dirección en memoria que el controlador proporcionó cuando llamó a WdfChildListRetrieveAddressDescription.

El marco de trabajo 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 miembro IdentificationDescriptionSize de la estructura 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 una función de devolución de llamada EvtChildListIdentificationDescriptionCompare .

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 tomar 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 EvtChildListIdentificationDescriptionCompare probablemente tenga que comparar solo los miembros DeviceSerialNumber para determinar si dos descripciones representan el mismo dispositivo.

Si el controlador llama a WdfChildListRetrieveNextDevice para recorrer una lista de dispositivos, puede proporcionar una función de devolución de llamada EvtChildListIdentificationDescriptionCompare adicional que usa el marco al buscar la siguiente descripción para recuperar. El marco busca dispositivos secundarios que coincidan con las marcas de tipo WDF_RETRIEVE_CHILD_FLAGS proporcionadas por el controlador. Si un controlador proporciona una función de devolución de llamada EvtChildListIdentificationDescriptionCompare especial, 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 especial, el marco no llama a RtlCompareMemory, simplemente devuelve cada dispositivo secundario que coincida con las marcas especificadas.

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

El marco adquiere un bloqueo interno de objeto child-list antes de llamar a la función de devolución de llamada EvtChildListIdentificationDescriptionCompare. 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 objeto 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.