Função WdfChildListAddOrUpdateChildDescriptionAsPresent (wdfchildlist.h)
[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 |
---|---|
|
Um parâmetro de entrada era inválido. |
|
O tamanho da descrição da identificação ou da descrição do endereço estava incorreto. |
|
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. |
|
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.
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) |
Confira também
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER