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]

Una EvtChildListIdentificationDescriptionDuplicate función de devolución de llamada de eventos 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 del 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(estado) es igual a 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(estado) es igual a FALSE.

Observaciones

Si un controlador de bus usa enumeración dinámica, puede registrar un EvtChildListIdentificationDescriptionDuplicate función de devolución de llamada 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 de WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER y, posiblemente, asignando dinámicamente memoria adicional para almacenar información de identificación que tiene 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 sola estructura con un tamaño predeterminado especificado por el IdentificationDescriptionSize miembro 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 un EvtChildListIdentificationDescriptionDuplicate función de devolución de llamada. 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 función de devolución de llamada DestinationIdentificationDescription estructura).
Copie otros miembros de la estructura de la función de devolución de llamada de la estructura SourceIdentificationDescription a la estructura de la función de devolución de llamada DestinationIdentificationDescription.

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

El marco adquiere un bloqueo interno de objetos de lista secundaria 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 duplicació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.

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

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