Funzione WdfChildListCreate (wdfchildlist.h)

Articolo
02/07/2025

[Si applica solo a KMDF]

Il metodo WdfChildListCreate crea un elenco figlio per un dispositivo padre specificato.

Sintassi

NTSTATUS WdfChildListCreate(
  [in]           WDFDEVICE              Device,
  [in]           PWDF_CHILD_LIST_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES ChildListAttributes,
  [out]          WDFCHILDLIST           *ChildList
);

Parametri

[in] Device

Handle per un oggetto dispositivo framework che rappresenta il dispositivo padre.

[in] Config

Puntatore a una struttura WDF_CHILD_LIST_CONFIG contenente le informazioni di configurazione fornite dal driver per l'elenco figlio.

[in, optional] ChildListAttributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES che contiene attributi di oggetto forniti dal driver per l'oggetto framework child-list. Il membro ParentObject della struttura deve essere NULL.

[out] ChildList

Puntatore a una posizione allocata dal chiamante che riceve un handle a un oggetto elenco figlio del framework.

Valore restituito

WdfChildListCreate restituisce STATUS_SUCCESS o un altro valore di stato per il quale NT_SUCCESS(stato) è 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	Parametro di input non valido.
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare un oggetto.

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 framework crea un elenco figlio predefinito per ogni oggetto dispositivo framework che rappresenta un oggetto dispositivo funzionale (FDO). Per usare l'elenco figlio predefinito, il driver chiama WdfFdoGetDefaultChildList. Se il driver richiede elenchi figlio aggiuntivi, può chiamare WdfChildListCreate per crearli.

L'elemento padre di ogni oggetto elenco figlio è l'oggetto dispositivo framework del dispositivo. Il driver non può modificare questo elemento padre e il membro ParentObject o la struttura WDF_OBJECT_ATTRIBUTES deve essere NULL.

Il driver non può eliminare l'oggetto elenco figlio creato WdfChildListCreate. Il framework elimina l'oggetto al momento corretto.

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

Esempi

Nell'esempio di codice seguente viene inizializzata una struttura di WDF_CHILD_LIST_CONFIG e quindi viene chiamato WdfChildListCreate.

WDF_CHILD_LIST_CONFIG listConfig;

WDF_CHILD_LIST_CONFIG_INIT(
                           &listConfig,
                           sizeof(PDO_IDENTIFICATION_DESCRIPTION),
                           My_EvtDeviceListCreatePdo
                           );

listConfig.AddressDescriptionSize = sizeof(PDO_ADDRESS_DESCRIPTION);

listConfig.EvtChildListScanForChildren = My_EvtChildListScanForChildren;

listConfig.EvtChildListIdentificationDescriptionDuplicate = My_EvtChildListIdentificationDescriptionDuplicate;
listConfig.EvtChildListIdentificationDescriptionCompare = My_EvtChildListIdentificationDescriptionCompare;
listConfig.EvtChildListIdentificationDescriptionCleanup = My_EvtChildListIdentificationDescriptionCleanup;

status = WdfChildListCreate(
                            device,
                            &listConfig,
                            WDF_NO_OBJECT_ATTRIBUTES,
                            &ParentDeviceContext->ChildList
                            );
if (!NT_SUCCESS(status)) {
    return status;
}

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	PASSIVE_LEVEL
regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedere anche

WDF_CHILD_LIST_CONFIG

WDF_CHILD_LIST_CONFIG_INIT

WdfFdoGetDefaultChildList

Condividi tramite