WdfDeviceCreate, fonction (wdfdevice.h)

Article
02/27/2024

[S’applique à KMDF et UMDF]

La méthode WdfDeviceCreate crée un objet d’appareil framework.

Syntaxe

NTSTATUS WdfDeviceCreate(
  [in, out]      PWDFDEVICE_INIT        *DeviceInit,
  [in, optional] PWDF_OBJECT_ATTRIBUTES DeviceAttributes,
  [out]          WDFDEVICE              *Device
);

Paramètres

[in, out] DeviceInit

Adresse d’un pointeur vers une structure WDFDEVICE_INIT . Si WdfDeviceCreate ne rencontre aucune erreur, il définit le pointeur sur NULL.

[in, optional] DeviceAttributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES allouée par l’appelant qui contient des attributs pour le nouvel objet. (Le membre ParentObject de la structure doit être NULL.) Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[out] Device

Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet d’appareil d’infrastructure.

Valeur retournée

Si la méthode WdfDeviceCreate ne rencontre aucune erreur, elle retourne STATUS_SUCCESS. Les valeurs de retour supplémentaires sont les suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un handle Device ou DeviceInit non valide est fourni.
STATUS_INVALID_DEVICE_STATE	Le pilote a déjà créé un objet de périphérique pour l’appareil.
STATUS_INVALID_SECURITY_DESCR	le pilote a appelé WdfDeviceInitAssignSDDLString ou WdfDeviceInitSetDeviceClass , mais n’a pas fourni de nom pour l’objet de périphérique.
STATUS_INSUFFICIENT_RESOURCES	Impossible d’allouer un objet d’appareil.
STATUS_OBJECT_NAME_COLLISION	Le nom de l’appareil qui a été spécifié par un appel à WdfDeviceInitAssignName existe déjà. Le pilote peut appeler wdfDeviceInitAssignName à nouveau pour attribuer un nouveau nom.

Pour obtenir la liste des autres valeurs de retour que WdfDeviceCreate peut retourner, consultez Erreurs de création d’objet framework.

La méthode peut retourner d’autres valeurs NTSTATUS.

Remarques

Avant d’appeler WdfDeviceCreate, le pilote doit appeler les fonctions fournies par l’infrastructure qui initialisent la structure WDFDEVICE_INIT. Pour plus d’informations sur l’initialisation de cette structure, consultez WDFDEVICE_INIT. Si le pilote rencontre des erreurs lors de l’appel des fonctions d’initialisation, il ne doit pas appeler WdfDeviceCreate. Dans ce cas, le pilote peut être amené à appeler WdfDeviceInitFree. Pour plus d’informations sur le moment d’appeler WdfDeviceInitFree, consultez WdfDeviceInitFree.

Un appel à WdfDeviceCreate crée un objet d’appareil d’infrastructure qui représente un objet d’appareil fonctionnel (FDO) ou un objet d’appareil physique (PDO). Le type d’objet de périphérique créé par la fonction dépend de la façon dont le pilote a obtenu la structure WDFDEVICE_INIT :

Si le pilote a reçu la structure WDFDEVICE_INIT d’un rappel EvtDriverDeviceAdd , WdfDeviceCreate crée un FDO.
Si le pilote a reçu la structure WDFDEVICE_INIT à partir d’un rappel EvtChildListCreateDevice ou d’un appel à WdfPdoInitAllocate, WdfDeviceCreate crée un PDO.

Une fois que le pilote a appelé WdfDeviceCreate, il ne peut plus accéder à la structure WDFDEVICE_INIT.

Les pilotes miniport qui utilisent l’infrastructure doivent appeler WdfDeviceMiniportCreate au lieu de WdfDeviceCreate.

Le parent de chaque objet de périphérique d’infrastructure est l’objet pilote d’infrastructure du pilote. Le pilote ne peut pas modifier ce parent, et le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES doit avoir la valeur NULL. L’infrastructure supprime chaque objet d’appareil d’infrastructure (à l’exception de certains objets d’appareil de contrôle) lorsque le gestionnaire de Plug-and-Play (PnP) détermine que l’appareil a été supprimé.

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

Pour plus d’informations sur la création d’objets d’appareil, consultez Création d’un objet d’appareil framework.

Exemples

L’exemple de code suivant montre comment une fonction de rappel EvtDriverDeviceAdd peut initialiser et créer un objet d’appareil.

NTSTATUS
MyEvtDeviceAdd(
    IN WDFDRIVER  Driver,
    IN PWDFDEVICE_INIT  DeviceInit
    )
{
    WDF_PNPPOWER_EVENT_CALLBACKS  pnpPowerCallbacks;
    WDF_OBJECT_ATTRIBUTES  attributes;
    NTSTATUS  status;
    WDFDEVICE  device;
 
    //
    // Initialize the WDF_PNPPOWER_EVENT_CALLBACKS structure.
    //
    WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
    pnpPowerCallbacks.EvtDevicePrepareHardware = MyEvtDevicePrepareHardware;
    pnpPowerCallbacks.EvtDeviceD0Entry = MyEvtDeviceD0Entry;
    pnpPowerCallbacks.EvtDeviceD0Exit  = MyEvtDeviceD0Exit;
    WdfDeviceInitSetPnpPowerEventCallbacks(
                                           DeviceInit,
                                           &pnpPowerCallbacks
                                           );
    //
    // This driver uses buffered I/O.
    //
    WdfDeviceInitSetIoType(
                           DeviceInit,
                           WdfDeviceIoBuffered
                           );
 
    //
    // Specify the device object's context space by
    // using a driver-defined DEVICE_CONTEXT structure.
 //
    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                            &attributes,
                                            DEVICE_CONTEXT
                                            );
 //
    // Create the device object.
    //
    status = WdfDeviceCreate(
                             &DeviceInit,
                             &attributes,
                             &device
                             );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    return STATUS_SUCCESS;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfdevice.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	AccessHardwareKey(kmdf), AddPdoToStaticChildList(kmdf), ChangeQueueState(kmdf), ChildDeviceInitAPI(kmdf), ChildListConfiguration(kmdf), ControlDeviceDeleted(kmdf), ControlDeviceInitAllocate(kmdf), ControlDeviceInitAPI(kmdf), CtlDeviceFinishInitDeviceAdd(kmdf), CtlDeviceFiitInitDrEntry(kmdf), DeviceCreateFail(kmdf), DeviceInitAllocate(kmdf), DeviceInitAPI(kmdf), DriverCreate(kmdf), InitFreeDeviceCreate(kmdf), InitFreeDeviceCreateType2(kmdf), InitFreeDeviceCreateType4(kmdf), InitFreeNull(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf), PdoInitFreeDeviceCreate(kmdf), PdoInitFreeDeviceCreateType2(kmdf), PdoInitFreeDeviceCreateType4(kmdf)