EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY 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 EvtChildListAddressDescriptionCopy de un controlador copia una descripción de dirección secundaria de una ubicación especificada a otra.

Sintaxis

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY EvtWdfChildListAddressDescriptionCopy;

void EvtWdfChildListAddressDescriptionCopy(
  [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 de marco.

[in] SourceAddressDescription

Puntero a una estructura 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 WDF_CHILD_ADDRESS_DESCRIPTION_HEADER que identifica la ubicación de destino de la descripción de la dirección secundaria.

Valor devuelto

None

Observaciones

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

El marco copia información de una descripción de dirección proporcionada por el controlador a otra cuando necesita actualizar una descripción existente con nueva información, o cuando necesita pasar el contenido de una descripción de dirección al controlador.

La función de devolución de llamada EvtChildListAddressDescriptionCopy debe copiar el contenido de una descripción de origen en una descripción de destino. 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 copiar 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 EvtChildListAddressDescriptionCopy , el marco copia las descripciones de direcciones mediante una llamada 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 de forma dinámica 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 determina que el controlador había notificado previamente el dispositivo, por lo que el marco puede actualizar la descripción de la dirección antigua del dispositivo con nueva información.
El marco llama a la función de devolución de llamada EvtChildListAddressDescriptionCopy (si existe) o RtlCopyMemory para copiar la nueva información de descripción de dirección en la descripción de la dirección existente.

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

En las estructuras SourceAddressDescription y DestinationAddressDescription de la función de devolución de llamada, busque los punteros a la memoria asignada dinámicamente.
Copie la memoria asignada dinámicamente desde el origen al destino mediante los punteros.
Copie otros miembros de la estructura SourceAddressDescription de la función de devolución de llamada a la estructura DestinationAddressDescription 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 EvtChildListAddressDescriptionCopy 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 EvtChildListAddressDescriptionCopy . La función de devolución de llamada solo debe realizar operaciones relacionadas con la operación de copia descrita, 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 tengan acceso a otros controladores.

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

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