EVT_WDF_CHILD_LIST_IDENTIFICATION_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 EvtChildListIdentificationDescriptionDuplicate de um driver duplica uma descrição de identificação filho.

Sintaxe

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

Um identificador para um objeto de lista filho da estrutura.

[in] SourceIdentificationDescription

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

[out] DestinationIdentificationDescription

Um ponteiro para uma estrutura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER que identifica o local de destino da descrição de identificação filho duplicada.

Retornar valor

A função de retorno de chamada EvtChildListIdentificationDescriptionDuplicate 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 de retorno de chamada 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 EvtChildListIdentificationDescriptionDuplicate chamando WdfFdoInitSetDefaultChildListConfig ou WdfChildListCreate.

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

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

Se o driver não fornecer uma função de retorno de chamada EvtChildListIdentificationDescriptionDuplicate , a estrutura duplicará as descrições de identificaçã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 identificação preenchendo uma estrutura definida pelo driver que contém uma estrutura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER e, possivelmente, alocando dinamicamente memória de adição para armazenar informações de identificaçã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 da identificação.
A estrutura chama a função de retorno de chamada EvtChildListIdentificationDescriptionDuplicate (se existir) ou RtlCopyMemory para duplicar a descrição de identificação para que ela possa ter uma cópia interna da descrição.

A estrutura pode usar RtlCopyMemory para duplicar uma descrição de identificação, se a descrição consistir em uma única estrutura com um tamanho predeterminado especificado pelo membro IdentificationDescriptionSize da estrutura WDF_CHILD_IDENTIFICATION_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 EvtChildListIdentificationDescriptionDuplicate . 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 DestinationIdentificationDescription da função de retorno de chamada).
Copie outros membros da estrutura SourceIdentificationDescription da função de retorno de chamada para a estrutura DestinationIdentificationDescription 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 EvtChildListIdentificationDescriptionDuplicate 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 EvtChildListIdentificationDescriptionDuplicate . Essa função de retorno de chamada só deve executar operações relacionadas à operação de duplicação, 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 EvtChildListIdentificationDescriptionDuplicate , ele também poderá precisar das funções de retorno de chamada EvtChildListIdentificationDescriptionCopy, EvtChildListIdentificationDescriptionCompare e EvtChildListIdentificationDescriptionCleanup .

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