Função WdfChildListAddOrUpdateChildDescriptionAsPresent (wdfchildlist.h)

Artigo
08/08/2023

[Aplica-se somente ao KMDF]

O método WdfChildListAddOrUpdateChildDescriptionAsPresent adiciona uma nova descrição filho a uma lista de filhos ou atualiza uma descrição filho existente.

Sintaxe

NTSTATUS WdfChildListAddOrUpdateChildDescriptionAsPresent(
  [in]           WDFCHILDLIST                                 ChildList,
  [in]           PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
  [in, optional] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER        AddressDescription
);

Parâmetros

[in] ChildList

Um identificador para um objeto de lista filho da estrutura.

[in] IdentificationDescription

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

[in, optional] AddressDescription

Um ponteiro para uma estrutura WDF_CHILD_ADDRESS_DESCRIPTION_HEADER que identifica uma descrição de endereço filho. Se uma descrição de endereço não for necessária, esse parâmetro poderá ser NULL.

Retornar valor

WdfChildListAddOrUpdateChildDescriptionAsPresent retorna STATUS_SUCCESS ou outro valor de status do tipo NTSTATUS para o qual NT_SUCCESS(status) é igual a TRUE, se a operação for bem-sucedida. Caso contrário, esse método pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro de entrada era inválido.
STATUS_INVALID_DEVICE_REQUEST	O tamanho da descrição da identificação ou da descrição do endereço estava incorreto.
STATUS_OBJECT_NAME_EXISTS	Uma criança com a descrição de identificação fornecida já existe. Nesse caso, a estrutura copia a descrição do endereço fornecido para o filho existente.
STATUS_INSUFFICIENT_RESOURCES	Uma descrição filho pode ser alocada.

Esse método também pode retornar outros valores NTSTATUS.

Um bug do sistema marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

O método WdfChildListAddOrUpdateChildDescriptionAsPresent pesquisa na lista filho especificada um filho que corresponda à descrição de identificação fornecida. Se uma correspondência for encontrada, a estrutura atualizará a descrição do endereço do filho, se fornecida, e retornará STATUS_OBJECT_NAME_EXISTS. Se nenhuma correspondência for encontrada, a estrutura criará um novo filho usando as descrições de endereço e identificação fornecidas.

Um driver pode chamar WdfChildListAddOrUpdateChildDescriptionAsPresent para adicionar ou atualizar uma única descrição filho. A estrutura atualiza imediatamente a lista filho e informa ao gerenciador de Plug and Play (PnP) que foram feitas alterações.

Como alternativa, o driver pode fazer o seguinte:

Chame WdfChildListBeginScan para preparar a lista filho para atualização.
Chame WdfChildListAddOrUpdateChildDescriptionAsPresent várias vezes para adicionar ou atualizar as descrições filho para todos os filhos do dispositivo pai.
Chame WdfChildListEndScan para processar alterações na lista filho.

Se o driver usar esse procedimento alternativo, a estrutura aguardará até que o driver chame WdfChildListEndScan antes de atualizar a lista filho e informar ao gerenciador PnP que foram feitas alterações. Quando o driver chama WdfChildListBeginScan, a estrutura marca todos os dispositivos relatados anteriormente como não mais presentes. Portanto, o driver deve chamar WdfChildListAddOrUpdateChildDescriptionAsPresent para todos os filhos, não apenas para crianças recém-descobertas.

Em algum momento, depois que um driver chama WdfChildListAddOrUpdateChildDescriptionAsPresent, a estrutura chama a função de retorno de chamada EvtChildListCreateDevice do driver para que o driver possa criar um objeto de dispositivo chamando WdfDeviceCreate.

Para obter mais informações sobre listas filho, consulte Enumeração dinâmica.

Exemplos

O exemplo de código a seguir baseia-se no código que o exemplo de kmdf_fx2 contém. O exemplo adiciona descrições filho à lista filho padrão de um dispositivo. Ele recupera as configurações de comutador armazenadas anteriormente no espaço de contexto de um objeto de dispositivo e, em seguida, chama WdfChildListAddOrUpdateChildDescriptionAsPresent para cada comutador definido.

PDEVICE_CONTEXT  pDeviceContext;
WDFCHILDLIST  list;
UCHAR  i;
NTSTATUS  status;

pDeviceContext = GetDeviceContext(Device);
list = WdfFdoGetDefaultChildList(Device);

WdfChildListBeginScan(list);
 
for (i = 0; i < RTL_BITS_OF(UCHAR); i++) {
    if (pDeviceContext->CurrentSwitchState & (1<<i)) {
        PDO_IDENTIFICATION_DESCRIPTION description;
        WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                 &description.Header,
                                                 sizeof(description)
                                                 );
        description.SwitchNumber = i; 
 
        status = WdfChildListAddOrUpdateChildDescriptionAsPresent(
                                                 list, 
                                                 &description.Header, 
                                                 NULL
                                                 );
        if (!NT_SUCCESS(status) && (status != STATUS_OBJECT_NAME_EXISTS)) {
            break;
        }
    }
}
WdfChildListEndScan(list);

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Cabeçalho	wdfchildlist.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.)
IRQL	<= DISPATCH_LEVEL
Regras de conformidade da DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)