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

[Aplica-se somente ao KMDF]

A função de retorno de chamada de um driver EvtChildListIdentificationDescriptionCompare 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 de 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.

Valor de retorno

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

Observações

Se um driver de ônibus estiver usando de 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 verdadeiro 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:

1. 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.
2. A estrutura percorre a lista filho. Para determinar se a descrição de identificação de uma criança corresponde à que o driver especificou quando chamou WdfChildListRetrieveAddressDescription, a estrutura chama a função de retorno de chamada EvtChildListIdentificationDescriptionCompare (se existir) ou RtlCompareMemory.
3. Se as duas descrições de identificação corresponderem (e a comparação retornar VERDADEIRO), a estrutura interromperá a passagem da lista.
4. A estrutura copia a descrição do endereço na memória fornecida pelo driver quando ele 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 um EvtChildListIdentificationDescriptionCompare função de retorno de chamada.

Essa função de retorno de chamada determina se duas descrições de identificação representam o mesmo dispositivo. Talvez a função de retorno de chamada não precise 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 deve 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 um adicional EvtChildListIdentificationDescriptionCompare função de retorno de chamada que a estrutura usa ao procurar a próxima descrição a ser recuperada. A estrutura procura dispositivos filho que correspondam a sinalizadores WDF_RETRIEVE_CHILD_FLAGSfornecidos pelo driver. Se um driver fornecer um especial EvtChildListIdentificationDescriptionCompare função de retorno de chamada, 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ão chamada RtlCompareMemory-- ela simplesmente retorna cada dispositivo filho que corresponde aos sinalizadores especificados.

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

A estrutura adquire um bloqueio interno de objeto de lista filho antes de chamar o EvtChildListIdentificationDescriptionCompareEvtChildListIdentificationDescriptionCompare função de retorno de chamada. 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.

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
versão mínima do KMDF	1.0
cabeçalho	wdfchildlist.h (inclua Wdf.h)
IRQL	<= DISPATCH_LEVEL

Consulte também

rtlCompareMemory

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER

WDF_RETRIEVE_CHILD_FLAGS

WdfChildListCreate

WdfChildListGetDevice

WdfChildListRetrieveAddressDescription

WdfChildListRetrieveNextDevice

WdfFdoInitSetDefaultChildListConfig