EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_COPY 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 EvtChildListAddressDescriptionCopy de um driver copia uma descrição de endereço filho de um local especificado para outro.

Sintaxe

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

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

Nenhum

Comentários

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

A estrutura copia informações de uma descrição de endereço fornecida pelo driver para outra quando precisa atualizar uma descrição existente com novas informações ou quando precisa passar o conteúdo de uma descrição de endereço para o driver.

A função de retorno de chamada EvtChildListAddressDescriptionCopy deve copiar o conteúdo de uma descrição de origem para uma descrição de destino. 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 copiar 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 EvtChildListAddressDescriptionCopy , a estrutura copiará as descrições de endereço chamando RtlCopyMemory.

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

O driver determina que um dispositivo filho existe.
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 determina que o driver havia relatado anteriormente o dispositivo, para que a estrutura possa atualizar a descrição do endereço antigo do dispositivo com novas informações.
A estrutura chama a função de retorno de chamada EvtChildListAddressDescriptionCopy (se existir) ou RtlCopyMemory para copiar as novas informações de descrição do endereço para a descrição do endereço existente.

A estrutura pode usar RtlCopyMemory para copiar 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 EvtChildListAddressDescriptionCopy . A função de retorno de chamada deve fazer o seguinte:

Nas estruturas SourceAddressDescription e DestinationAddressDescription da função de retorno de chamada, localize os ponteiros para a memória alocada dinamicamente.
Copie a memória alocada dinamicamente da origem para o destino, usando os ponteiros.
Copie outros membros de estrutura 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 EvtChildListAddressDescriptionCopy 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 EvtChildListAddressDescriptionCopy . A função de retorno de chamada só deve executar operações relacionadas à operação de cópia 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 EvtChildListAddressDescriptionCopy , ele também precisará de funções de retorno de chamada EvtChildListAddressDescriptionDuplicate e EvtChildListAddressDescriptionCleanup .

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