EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE função de retorno de chamada (wdfchildlist.h)

Artigo
08/08/2023

[Aplica-se somente ao KMDF]

A função de retorno de chamada de evento EvtChildListAddressDescriptionDuplicate de um driver duplica uma descrição de endereço filho.

Sintaxe

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

Um identificador para um objeto de lista filho da estrutura.

[in] SourceAddressDescription

Um ponteiro para uma estrutura WDF_CHILD_ADDRESS_DESCRIPTION_HEADER que identifica o local de origem da descrição do endereço filho.

[out] DestinationAddressDescription

Um ponteiro para uma estrutura WDF_CHILD_ADDRESS_DESCRIPTION_HEADER que identifica o local de destino da descrição do endereço filho.

Retornar valor

A função de retorno de chamada EvtChildListAddressDescriptionDuplicate deve retornar STATUS_SUCCESS ou outro valor status para o qual NT_SUCCESS(status) é igual a TRUE, se a operação for bem-sucedida. Caso contrário, essa função deve retornar um valor status para o qual NT_SUCCESS(status) é igual a FALSE.

Comentários

Se um driver de barramento estiver usando enumeração dinâmica, ele poderá registrar uma função de retorno de chamada EvtChildListAddressDescriptionDuplicate chamando WdfFdoInitSetDefaultChildListConfig ou WdfChildListCreate.

A estrutura duplica as descrições de endereço fornecidas pelo driver para que possa ter cópias internas das descrições.

A função de retorno de chamada EvtChildListAddressDescriptionDuplicate deve criar uma cópia duplicada de uma descrição de endereço. Um driver deverá fornecer essa função de retorno de chamada se seus dispositivos filho exigirem uma descrição de endereço e se a estrutura não puder chamar RtlCopyMemory para duplicar a descrição do endereço. (A estrutura não poderá chamar RtlCopyMemory se a descrição contiver ponteiros para memória adicional.)

Se o driver fornecer descrições de endereço, mas não fornecer uma função de retorno de chamada EvtChildListAddressDescriptionDuplicate , a estrutura duplicará as descrições de endereço chamando RtlCopyMemory.

As etapas a seguir descrevem um cenário típico:

O driver determina que existe um dispositivo filho.
O driver cria uma descrição de endereço preenchendo uma estrutura definida pelo driver que contém uma estrutura WDF_CHILD_ADDRESS_DESCRIPTION_HEADER e, possivelmente, alocando dinamicamente memória adicional para armazenar informações de endereço que têm um tamanho específico do dispositivo.
O driver chama WdfChildListAddOrUpdateChildDescriptionAsPresent para relatar um dispositivo filho, fornecendo um ponteiro para a descrição do endereço.
A estrutura chama a função de retorno de chamada EvtChildListAddressDescriptionDuplicate (se existir) ou RtlCopyMemory para duplicar a descrição do endereço para que ela possa ter uma cópia interna da descrição.

A estrutura pode usar RtlCopyMemory para duplicar uma descrição de endereço, se a descrição consistir em uma única estrutura com um tamanho predeterminado especificado pelo membro AddressDescriptionSize da estrutura WDF_CHILD_ADDRESS_DESCRIPTION_HEADER. No entanto, às vezes, a descrição também deve conter informações adicionais armazenadas na memória alocada dinamicamente. Nesse caso, você normalmente definirá uma estrutura de descrição para que um membro aponte para a memória alocada dinamicamente e seu driver deve fornecer uma função de retorno de chamada EvtChildListAddressDescriptionDuplicate . A função de retorno de chamada deve fazer o seguinte:

Aloque memória adicional, normalmente chamando ExAllocatePool.
Armazene o endereço da memória alocada na estrutura de descrição de endereço definida pelo driver (ou seja, a estrutura DestinationAddressDescription da função de retorno de chamada).
Copie outros membros da estrutura SourceAddressDescription da função de retorno de chamada para a estrutura DestinationAddressDescription da função de retorno de chamada.

O único método de objeto de lista filho da estrutura que a função de retorno de chamada EvtChildListAddressDescriptionDuplicate de um driver pode chamar é WdfChildListGetDevice.

A estrutura adquire um bloqueio de objeto de lista filho interno antes de chamar a função de retorno de chamada EvtChildListAddressDescriptionDuplicate . A função de retorno de chamada só deve executar operações relacionadas à operação de duplicação descrita, como chamar métodos de objeto de memória da estrutura e acessar o espaço de contexto do objeto. Ele não deve chamar métodos que acessam outros drivers.

Se o driver fornecer uma função de retorno de chamada EvtChildListAddressDescriptionDuplicate , ele também poderá precisar de funções de retorno de chamada EvtChildListAddressDescriptionCopy e EvtChildListAddressDescriptionCleanup .

Para obter mais informações sobre enumeração dinâmica, consulte Enumerando os dispositivos em um barramento.