Funzione WdfDriverCreate (wdfdriver.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfDriverCreate crea un oggetto driver framework per il driver chiamante.

Sintassi

NTSTATUS WdfDriverCreate(
  [in]            PDRIVER_OBJECT         DriverObject,
  [in]            PCUNICODE_STRING       RegistryPath,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES DriverAttributes,
  [in]            PWDF_DRIVER_CONFIG     DriverConfig,
  [out, optional] WDFDRIVER              *Driver
);

Parametri

[in] DriverObject

Puntatore a una struttura DRIVER_OBJECT che rappresenta un oggetto driver WDM (Windows Driver Model). Il driver riceve questo puntatore come input alla routine DriverEntry .

[in] RegistryPath

Puntatore a una struttura UNICODE_STRING contenente la stringa del percorso del Registro di sistema ricevuta dal driver come input alla routine DriverEntry .

[in, optional] DriverAttributes

Puntatore a una struttura di WDF_OBJECT_ATTRIBUTES allocata dal chiamante. Il membro ParentObject della struttura deve essere NULL. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[in] DriverConfig

Puntatore a una struttura WDF_DRIVER_CONFIG allocata dal chiamante.

[out, optional] Driver

Puntatore a una posizione che riceve un handle al nuovo oggetto driver del framework. Questo parametro è facoltativo e può essere WDF_NO_HANDLE.

Valore restituito

WdfDriverCreate restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_DRIVER_INTERNAL_ERROR	Il driver denominato WdfDriverCrea più di una volta.
STATUS_INVALID_PARAMETER	Un driver non Plug and Play (PnP) specificato un driver EvtDriverDeviceAggiungi funzione di callback.

Per altre informazioni sui valori restituiti, vedere Errori di creazione di oggetti Framework.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Un controllo del bug di sistema si verifica se il parametro DriverObject, RegistryPath o DriverConfig è NULL.

Commenti

Un driver che usa Kernel-Mode Driver Framework deve chiamare WdfDriverCreate dall'interno della routine DriverEntry , prima di chiamare qualsiasi altra routine del framework. Per altre informazioni su DriverEntry, vedere DriverEntry per i driver basati su Framework.

Prima che il driver chiami WdfDriverCreate, il driver deve chiamare WDF_DRIVER_CONFIG_INIT per inizializzare la struttura WDF_DRIVER_CONFIG .

L'oggetto driver del framework è la parte superiore dell'albero del driver degli oggetti framework e pertanto non ha un oggetto padre.

Se il driver fornisce funzioni di callback EvtCleanupCallback o EvtDestroyCallback per l'oggetto driver, si noti che il framework chiama queste funzioni di callback in IRQL = PASSIVE_LEVEL.

Esempio

L'esempio di codice seguente è una routine DriverEntry che inizializza una struttura WDF_DRIVER_CONFIG e quindi crea un oggetto driver framework.

NTSTATUS
DriverEntry(
    IN PDRIVER_OBJECT  DriverObject,
    IN PUNICODE_STRING  RegistryPath
    )
{
    WDF_DRIVER_CONFIG  config;
    NTSTATUS  status = STATUS_SUCCESS;

    WDF_DRIVER_CONFIG_INIT(
                           &config,
                           MyEvtDeviceAdd
                           );
    config.EvtDriverUnload = MyEvtDriverUnload;
    status = WdfDriverCreate(
                             DriverObject,
                             RegistryPath,
                             WDF_NO_OBJECT_ATTRIBUTES,
                              &config,
                             WDF_NO_HANDLE
                             );
    if (!NT_SUCCESS(status)) {
        TraceEvents(
                    TRACE_LEVEL_ERROR,
                    DBG_PNP,
                    "WdfDriverCreate failed with status %!STATUS!",
                    status
                    );
    }
    return status;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Versione UMDF minima	2,0
Intestazione	wdfdriver.h (includere Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	ChangeQueueState(kmdf), DriverAttributeChanged(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MiniportOnlyWdmDevice(kmdf)