Funzione WdfChildListAddOrUpdateChildDescriptionAsPresent (wdfchildlist.h)

Articolo
08/08/2023

[Si applica solo a KMDF]

Il metodo WdfChildListAddOrUpdateChildDescriptionAsPresent aggiunge una nuova descrizione figlio a un elenco di elementi figlio o aggiorna una descrizione figlio esistente.

Sintassi

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

Parametri

[in] ChildList

Handle per un oggetto elenco figlio del framework.

[in] IdentificationDescription

Puntatore a una struttura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER che identifica una descrizione dell'identificazione figlio.

[in, optional] AddressDescription

Puntatore a una struttura WDF_CHILD_ADDRESS_DESCRIPTION_HEADER che identifica una descrizione dell'indirizzo figlio. Se non è necessaria una descrizione dell'indirizzo, questo parametro può essere NULL.

Valore restituito

WdfChildListAddOrUpdateChildDescriptionAsPresent restituisce STATUS_SUCCESS o un altro valore di stato tipizzato NTSTATUS per il quale NT_SUCCESS(status) è uguale a TRUE, se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Un parametro di input non è valido.
STATUS_INVALID_DEVICE_REQUEST	La dimensione della descrizione dell'identificazione o della descrizione dell'indirizzo non è corretta.
STATUS_OBJECT_NAME_EXISTS	Esiste già un elemento figlio con la descrizione dell'identificazione specificata. In questo caso, il framework copia la descrizione dell'indirizzo specificata nell'elemento figlio esistente.
STATUS_INSUFFICIENT_RESOURCES	È possibile allocare una descrizione figlio.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Un controllo del bug di sistema si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Il metodo WdfChildListAddOrUpdateChildDescriptionAsPresent cerca l'elenco figlio specificato per un figlio corrispondente alla descrizione dell'identificazione specificata. Se viene trovata una corrispondenza, il framework aggiorna la descrizione dell'indirizzo figlio, se specificato e restituisce STATUS_OBJECT_NAME_EXISTS. Se non viene trovata alcuna corrispondenza, il framework crea un nuovo elemento figlio usando le descrizioni di identificazione e indirizzo fornite.

Un driver può chiamare WdfChildListAddOrUpdateChildDescriptionAsPresent per aggiungere o aggiornare una singola descrizione figlio. Il framework aggiorna immediatamente l'elenco figlio e informa il gestore Plug and Play (PnP) che sono state apportate modifiche.

In alternativa, il driver può eseguire le operazioni seguenti:

Chiamare WdfChildListBeginScan per preparare l'elenco figlio per l'aggiornamento.
Chiamare WdfChildListAddOrUpdateChildDescriptionAsPresent più volte per aggiungere o aggiornare le descrizioni figlio per tutti gli elementi figlio del dispositivo padre.
Chiamare WdfChildListEndScan per elaborare le modifiche all'elenco figlio.

Se il driver usa questa procedura alternativa, il framework attende fino a quando il driver chiama WdfChildListEndScan prima di aggiornare l'elenco figlio e informare il gestore PnP che sono state apportate modifiche. Quando il driver chiama WdfChildListBeginScan, il framework contrassegna tutti i dispositivi segnalati in precedenza come non più presenti. Pertanto, il driver deve chiamare WdfChildListAddOrUpdateChildDescriptionAsPresent per tutti gli elementi figlio, non solo i bambini appena individuati.

In qualche momento dopo che un driver chiama WdfChildListAddOrUpdateChildDescriptionAsPresent, il framework chiama la funzione di callback evtChildListCreateDevice del driver in modo che il driver possa creare un oggetto dispositivo chiamando WdfDeviceCreate.

Per altre informazioni sugli elenchi figlio, vedere Enumerazione dinamica.

Esempio

L'esempio di codice seguente si basa sul codice contenente l'esempio di kmdf_fx2 . Nell'esempio vengono aggiunte descrizioni figlio all'elenco figlio predefinito di un dispositivo. Recupera le impostazioni del commutatore archiviato in precedenza nello spazio di contesto di un oggetto dispositivo e quindi chiama WdfChildListAddOrUpdateChildDescriptionAsPresent per ogni commutatore impostato.

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);

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Intestazione	wdfchildlist.h (includere Wdf.h)
Libreria	Wdf01000.sys (vedere Framework Library Versioning).
IRQL	<= DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)