WdfDriverCreate, fonction (wdfdriver.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfDriverCreate crée un objet de pilote d’infrastructure pour le pilote appelant.

Syntaxe

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

Paramètres

[in] DriverObject

Pointeur vers une structure DRIVER_OBJECT qui représente un objet de pilote WDM (Windows Driver Model). Le pilote reçoit ce pointeur comme entrée dans sa routine DriverEntry .

[in] RegistryPath

Pointeur vers une structure UNICODE_STRING qui contient la chaîne de chemin d’accès du Registre que le pilote a reçue comme entrée dans sa routine DriverEntry .

[in, optional] DriverAttributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES allouée par l’appelant. (Le membre ParentObject de la structure doit avoir la valeur NULL.) Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[in] DriverConfig

Pointeur vers une structure de WDF_DRIVER_CONFIG allouée par l’appelant.

[out, optional] Driver

Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet pilote d’infrastructure. Ce paramètre est facultatif et peut être WDF_NO_HANDLE.

Valeur retournée

WdfDriverCreate retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_DRIVER_INTERNAL_ERROR	Le pilote a appelé WdfDriverCreate plusieurs fois.
STATUS_INVALID_PARAMETER	Un pilote non Plug-and-Play (PnP) a spécifié une fonction de rappel EvtDriverDeviceAdd.

Pour plus d’informations sur les valeurs de retour, consultez Erreurs de création d’objet Framework.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Un bogue système case activée se produit si le paramètre DriverObject, RegistryPath ou DriverConfig a la valeur NULL.

Remarques

Un pilote qui utilise Kernel-Mode Driver Framework doit appeler WdfDriverCreate à partir de sa routine DriverEntry avant d’appeler d’autres routines d’infrastructure. Pour plus d’informations sur DriverEntry, consultez DriverEntry pour les pilotes basés sur framework.

Avant d’appeler WdfDriverCreate, le pilote doit appeler WDF_DRIVER_CONFIG_INIT pour initialiser sa structure WDF_DRIVER_CONFIG .

L’objet de pilote d’infrastructure est le haut de l’arborescence d’objets framework de votre pilote et n’a donc pas d’objet parent.

Si votre pilote fournit des fonctions de rappel EvtCleanupCallback ou EvtDestroyCallback pour l’objet pilote, notez que l’infrastructure appelle ces fonctions de rappel à l’adresse IRQL = PASSIVE_LEVEL.

Exemples

L’exemple de code suivant est une routine DriverEntry qui initialise une structure WDF_DRIVER_CONFIG, puis crée un objet de pilote d’infrastructure.

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

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfdriver.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	ChangeQueueState(kmdf), DriverAttributeChanged(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MiniportOnlyWdmDevice(kmdf)