Funzione WdfChildListAddOrUpdateChildDescriptionAsPresent (wdfchildlist.h)

Articolo
02/07/2025

[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 di WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER che identifica una descrizione di identificazione figlio.

[in, optional] AddressDescription

Puntatore a una struttura di 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 cui NT_SUCCESS(status) è uguale TRUE, se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Parametro di input non valido.
STATUS_INVALID_DEVICE_REQUEST	Le dimensioni della descrizione o della descrizione dell'indirizzo di identificazione non sono corrette.
STATUS_OBJECT_NAME_EXISTS	Esiste già un elemento figlio con la descrizione dell'identificazione fornita. In questo caso, il framework copia la descrizione dell'indirizzo fornito nell'elemento figlio esistente.
STATUS_INSUFFICIENT_RESOURCES	È possibile allocare una descrizione figlio.

Questo metodo può anche restituire altri valori NTSTATUS .

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo dei bug di sistema.

Osservazioni

Il metodo WdfChildListAddOrUpdateChildDescriptionAsPresent cerca nell'elenco figlio specificato un elemento figlio corrispondente alla descrizione dell'identificazione fornita. 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 apportate all'elenco figlio.

Se il driver usa questa procedura alternativa, il framework attende fino a quando il driver non 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 per gli elementi figlio appena individuati.

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

Per altre informazioni sugli elenchi figlio, vedere 'enumerazione dinamica.

Esempi

L'esempio di codice seguente si basa sul codice contenuto nell'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 nel contesto di un oggetto dispositivo e quindi chiama WdfChildListAddOrUpdateChildDescriptionAsPresent per ogni opzione impostata.

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

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
intestazione	wdfchildlist.h (include Wdf.h)
libreria	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
IRQL	<= DISPATCH_LEVEL
regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)