Função WdfChildListAddOrUpdateChildDescriptionAsPresent (wdfchildlist.h)

Artigo
02/07/2025

[Aplica-se somente ao KMDF]

O método WdfChildListAddOrUpdateChildDescriptionAs Present 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 de WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER que identifica uma descrição de identificação filho.

[in, optional] AddressDescription

Um ponteiro para uma estrutura de 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.

Valor de retorno

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 poderá 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 de identificação ou descrição do endereço estava incorreto.
STATUS_OBJECT_NAME_EXISTS	Já existe uma criança com a descrição de identificação fornecida. Nesse caso, a estrutura copia a descrição de endereço fornecida para o filho existente.
STATUS_INSUFFICIENT_RESOURCES	Uma descrição filho pode ser alocada.

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

Uma verificação de bugs do sistema ocorre se o driver fornece um identificador de objeto inválido.

Observações

O método WdfChildListAddOrUpdateChildDescriptionAsPresent pesquisa a lista filho especificada para 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 do 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 gerente do PnP que as alterações foram feitas. Quando o driver chama WdfChildListBeginScan, a estrutura marca todos os dispositivos relatados anteriormente como não sendo mais presentes. Portanto, o driver deve chamar WdfChildListAddOrUpdateChildDescriptionAsPresent para todas as crianças, não apenas 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
da Plataforma de Destino	Universal
versão mínima do KMDF	1.0
cabeçalho	wdfchildlist.h (inclua Wdf.h)
biblioteca	Wdf01000.sys (consulte o Controle de Versão da Biblioteca da Estrutura.)
IRQL	<= DISPATCH_LEVEL
regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Consulte também

EvtChildListCreateDevice

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER

WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT

WdfChildListBeginScan

WdfChildListEndScan

WdfDeviceCreate

WdfFdoGetDefaultChildList

Compartilhar via