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

Artigo
02/26/2024

[Aplica-se somente ao KMDF]

A função de retorno de chamada de evento EvtChildListIdentificationDescriptionCompare de um driver compara uma descrição de identificação filho com outra.

Sintaxe

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE EvtWdfChildListIdentificationDescriptionCompare;

BOOLEAN EvtWdfChildListIdentificationDescriptionCompare(
  [in] WDFCHILDLIST ChildList,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER FirstIdentificationDescription,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SecondIdentificationDescription
)
{...}

Parâmetros

[in] ChildList

Um identificador para um objeto de lista filho da estrutura.

[in] FirstIdentificationDescription

Um ponteiro para uma estrutura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER que identifica a descrição de identificação de um filho.

[in] SecondIdentificationDescription

Um ponteiro para uma estrutura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER que identifica outra descrição de identificação filho.

Retornar valor

A função de retorno de chamada EvtChildListIdentificationDescriptionCompare deverá retornar TRUE se as duas descrições de identificação filho corresponderem. Caso contrário, essa função deverá retornar FALSE.

Comentários

Se um driver de barramento estiver usando enumeração dinâmica, ele poderá registrar uma função de retorno de chamada EvtChildListIdentificationDescriptionCompare chamando WdfFdoInitSetDefaultChildListConfig ou WdfChildListCreate. O driver também pode registrar uma segunda função de retorno de chamada EvtChildListIdentificationDescriptionCompare quando chama WdfChildListRetrieveNextDevice.

A estrutura compara duas descrições de identificação quando deve determinar se ambas as descrições identificam o mesmo dispositivo.

A função de retorno de chamada EvtChildListIdentificationDescriptionCompare deve comparar o conteúdo de duas descrições de identificação e retornar TRUE se corresponderem. Um driver deverá fornecer essa função de retorno de chamada se a estrutura não puder chamar RtlCompareMemory para comparar as descrições de identificação. (A estrutura não poderá chamar RtlCompareMemory se as descrições contiverem ponteiros para memória adicional.)

Se o driver não fornecer uma função de retorno de chamada EvtChildListIdentificationDescriptionCompare , a estrutura comparará as descrições de identificação chamando RtlCompareMemory.

As etapas a seguir descrevem um cenário possível:

O driver chama WdfChildListRetrieveAddressDescription para obter a descrição do endereço associada à cópia da estrutura de uma descrição de identificação, que é armazenada em uma lista filho.
A estrutura atravessa a lista filho. Para determinar se a descrição de identificação de uma criança corresponde à especificada pelo driver quando ele chamou WdfChildListRetrieveAddressDescription, a estrutura chama a função de retorno de chamada EvtChildListIdentificationDescriptionCompare (se existir) ou RtlCompareMemory.
Se as duas descrições de identificação corresponderem (e a comparação retornar TRUE), a estrutura deixará de percorrer a lista.
A estrutura copia a descrição do endereço na memória que o driver forneceu quando chamou WdfChildListRetrieveAddressDescription.

A estrutura pode usar RtlCompareMemory para comparar descrições de identificação, se cada 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 EvtChildListIdentificationDescriptionCompare .

Essa função de retorno de chamada determina se duas descrições de identificação representam o mesmo dispositivo. A função de retorno de chamada pode não precisar comparar todos os membros da estrutura para fazer essa determinação. Por exemplo, suponha que uma descrição de identificação contenha um número de série e um conjunto de identificadores de hardware, da seguinte maneira:

typedef struct _PDO_IDENTIFICATION_DESCRIPTION {
  WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Header;
  ULONG DeviceSerialNumber;
  ULONG CchHardwareIds;
  PWCHAR HardwareIds;
} PDO_IDENTIFICATION_DESCRIPTION, *PPDO_IDENTIFICATION_DESCRIPTION;

Nesse caso, a função de retorno de chamada EvtChildListIdentificationDescriptionCompare provavelmente precisa comparar apenas os membros DeviceSerialNumber para determinar se duas descrições representam o mesmo dispositivo.

Se o driver chamar WdfChildListRetrieveNextDevice para percorrer uma lista de dispositivos, você poderá fornecer uma função de retorno de chamada EvtChildListIdentificationDescriptionCompare adicional que a estrutura usa ao procurar a próxima descrição a ser recuperada. A estrutura procura dispositivos filho que correspondam aos sinalizadores do tipo WDF_RETRIEVE_CHILD_FLAGS fornecidos pelo driver. Se um driver fornecer uma função especial de retorno de chamada EvtChildListIdentificationDescriptionCompare , a estrutura usará a função de retorno de chamada para refinar a pesquisa. Se o driver não fornecer uma função especial de retorno de chamada EvtChildListIdentificationDescriptionCompare , a estrutura nãochamará RtlCompareMemory, ela simplesmente retornará cada dispositivo filho que corresponda aos sinalizadores especificados.

O único método de objeto de lista filho da estrutura que a função de retorno de chamada EvtChildListIdentificationDescriptionCompare 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 EvtChildListIdentificationDescriptionCompareEvtChildListIdentificationDescriptionCompare . A função de retorno de chamada só deve executar operações relacionadas à operação de comparaçã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.

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