EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE 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 evento EvtChildListIdentificationDescriptionDuplicate de un controlador duplica una descripción de identificación secundaria.

Sintaxis

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

Parámetros

[in] ChildList

Identificador de un objeto de lista secundaria de marco.

[in] SourceIdentificationDescription

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

[out] DestinationIdentificationDescription

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

Valor devuelto

La función de devolución de llamada EvtChildListIdentificationDescriptionDuplicate debe devolver STATUS_SUCCESS u otro valor de estado para el que NT_SUCCESS(status) sea TRUE, si la operación se realiza correctamente. De lo contrario, esta función de devolución de llamada debe devolver un valor de estado para el que NT_SUCCESS(status) es igual a FALSE.

Comentarios

Si un controlador de bus usa enumeración dinámica, puede registrar una función de devolución de llamada EvtChildListIdentificationDescriptionDuplicate llamando a WdfFdoInitSetDefaultChildListConfig o WdfChildListCreate.

El marco duplica las descripciones de identificación proporcionadas por el controlador para que pueda tener copias internas de las descripciones.

La función de devolución de llamada EvtChildListIdentificationDescriptionDuplicate debe crear una copia duplicada de una descripción de identificación. Un controlador debe proporcionar esta función de devolución de llamada si el marco no puede llamar a RtlCopyMemory para duplicar la descripción de identificación. (El marco no puede llamar a RtlCopyMemory si la descripción contiene punteros a memoria adicional).

Si el controlador no proporciona una función de devolución de llamada EvtChildListIdentificationDescriptionDuplicate , el marco duplica las descripciones de identificación llamando a RtlCopyMemory.

En los pasos siguientes se describe un escenario típico:

El controlador determina que existe un dispositivo secundario.
El controlador crea una descripción de identificación rellenando una estructura definida por el controlador que contiene una estructura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER y posiblemente asignando dinámicamente memoria adicional para almacenar información de identificación que tenga un tamaño específico del dispositivo.
El controlador llama a WdfChildListAddOrUpdateChildDescriptionAsPresent para notificar un dispositivo secundario, proporcionando un puntero a la descripción de identificación.
El marco llama a la función de devolución de llamada EvtChildListIdentificationDescriptionDuplicate (si existe) o RtlCopyMemory para duplicar la descripción de identificación para que pueda tener una copia interna de la descripción.

El marco puede usar RtlCopyMemory para duplicar una descripción de identificación, si la descripción consta de una única 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 EvtChildListIdentificationDescriptionDuplicate . La función de devolución de llamada debe hacer lo siguiente:

Asigne memoria adicional, normalmente llamando a ExAllocatePool.
Almacene la dirección de la memoria asignada en la estructura de descripción de dirección definida por el controlador (es decir, la estructura DestinationIdentificationDescription de la función de devolución de llamada).
Copie otros miembros de estructura de la estructura SourceIdentificationDescription de la función de devolución de llamada a la estructura DestinationIdentificationDescription de la función de devolución de llamada.

El único método de objeto de lista secundaria del marco al que puede llamar la función de devolución de llamada EvtChildListIdentificationDescriptionDuplicate de un controlador es WdfChildListGetDevice.

El marco adquiere un bloqueo de objeto de lista secundaria interno antes de llamar a la función de devolución de llamada EvtChildListIdentificationDescriptionDuplicate . Esta función de devolución de llamada solo debe realizar operaciones relacionadas con la operación de uplication, 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 tengan acceso a otros controladores.

Si el controlador proporciona una función de devolución de llamada EvtChildListIdentificationDescriptionDuplicate , también podría necesitar las funciones de devolución de llamada EvtChildListIdentificationDescriptionCopy, EvtChildListIdentificationDescriptionCompare y EvtChildListIdentificationDescriptionCleanup .

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