EVT_WDF_CHILD_LIST_ADDRESS_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 eventos EvtChildListAddressDescriptionDuplicate de un controlador duplica una descripción de dirección secundaria.

Sintaxis

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE EvtWdfChildListAddressDescriptionDuplicate;

NTSTATUS EvtWdfChildListAddressDescriptionDuplicate(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER SourceAddressDescription,
  [out] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER DestinationAddressDescription
)
{...}

Parámetros

[in] ChildList

Identificador de un objeto de lista secundaria del marco.

[in] SourceAddressDescription

Puntero a una estructura de WDF_CHILD_ADDRESS_DESCRIPTION_HEADER que identifica la ubicación de origen de la descripción de la dirección secundaria.

[out] DestinationAddressDescription

Puntero a una estructura de WDF_CHILD_ADDRESS_DESCRIPTION_HEADER que identifica la ubicación de destino de la descripción de la dirección secundaria.

Valor devuelto

La función de devolución de llamada EvtChildListAddressDescriptionDuplicate 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 debe devolver un valor de estado para el que NT_SUCCESS(status) es igual a FALSE.

Comentarios

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

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

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

Si el controlador proporciona descripciones de direcciones pero no proporciona una función de devolución de llamada EvtChildListAddressDescriptionDuplicate , el marco duplica las descripciones de direcciones 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 dirección rellenando una estructura definida por el controlador que contiene una estructura de WDF_CHILD_ADDRESS_DESCRIPTION_HEADER y, posiblemente, asignando dinámicamente memoria adicional para almacenar la información de direcció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 la dirección.
El marco llama a la función de devolución de llamada EvtChildListAddressDescriptionDuplicate (si existe) o RtlCopyMemory para duplicar la descripción de la dirección para que pueda tener una copia interna de la descripción.

El marco puede usar RtlCopyMemory para duplicar una descripción de dirección, si la descripción consta de una sola estructura con un tamaño predeterminado especificado por el miembro AddressDescriptionSize de la estructura WDF_CHILD_ADDRESS_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 EvtChildListAddressDescriptionDuplicate . 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 DestinationAddressDescription de la función de devolución de llamada).
Copie otros miembros de estructura de la estructura SourceAddressDescription de la función de devolución de llamada en la estructura DestinationAddressDescription de la función de devolución de llamada.

El único método de objeto child-list del marco al que puede llamar la función de devolución de llamada EvtChildListAddressDescriptionDuplicate 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 EvtChildListAddressDescriptionDuplicate . La función de devolución de llamada solo debe realizar operaciones relacionadas con la operación de duplicación descrita, 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.

Si el controlador proporciona una función de devolución de llamada EvtChildListAddressDescriptionDuplicate , es posible que también necesite funciones de devolución de llamada EvtChildListAddressDescriptionCopy y EvtChildListAddressDescriptionCleanup .

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