Fonction IoCreateDevice (wdm.h)

Article
08/08/2023

La routine IoCreateDevice crée un objet d’appareil à utiliser par un pilote.

Syntaxe

NTSTATUS IoCreateDevice(
  [in]           PDRIVER_OBJECT  DriverObject,
  [in]           ULONG           DeviceExtensionSize,
  [in, optional] PUNICODE_STRING DeviceName,
  [in]           DEVICE_TYPE     DeviceType,
  [in]           ULONG           DeviceCharacteristics,
  [in]           BOOLEAN         Exclusive,
  [out]          PDEVICE_OBJECT  *DeviceObject
);

Paramètres

[in] DriverObject

Pointeur vers l’objet pilote pour l’appelant. Chaque pilote reçoit un pointeur vers son objet pilote dans un paramètre vers sa routine DriverEntry . Les pilotes de fonction WDM et de filtre reçoivent également un pointeur d’objet pilote dans leurs routines AddDevice .

[in] DeviceExtensionSize

Spécifie le nombre d’octets déterminé par le pilote à allouer pour l’extension de l’appareil de l’objet d’appareil. La structure interne de l’extension de périphérique est définie par le pilote.

[in, optional] DeviceName

Pointe éventuellement vers une mémoire tampon contenant une chaîne Unicode terminée par null qui nomme l’objet d’appareil. La chaîne doit être un nom de chemin d’accès complet. Les filtres WDM et les pilotes de fonction ne nomment pas leurs objets d’appareil. Pour plus d’informations, consultez Objets d’appareil nommés.

Si un nom d’appareil n’est pas fourni (autrement dit, DeviceName a la valeur NULL), une liste de contrôle d’accès discrétionnaire (DACL) n’est pas associée à l’objet d’appareil créé par IoCreateDevice. Pour plus d’informations, consultez Descripteurs de sécurité.

[in] DeviceType

Spécifie l’une des constantes FILE_DEVICE_XXX définies par le système qui indiquent le type d’appareil (par exemple, FILE_DEVICE_DISK ou FILE_DEVICE_KEYBOARD) ou une valeur définie par le fournisseur pour un nouveau type d’appareil. Pour plus d’informations, consultez Spécification de types d’appareils.

[in] DeviceCharacteristics

Spécifie une ou plusieurs constantes définies par le système, ORed ensemble, qui fournissent des informations supplémentaires sur l’appareil du pilote. Pour obtenir la liste des caractéristiques possibles de l’appareil, consultez DEVICE_OBJECT. Pour plus d’informations sur la spécification des caractéristiques de l’appareil, consultez Spécification des caractéristiques de l’appareil. La plupart des pilotes spécifient FILE_DEVICE_SECURE_OPEN pour ce paramètre.

[in] Exclusive

Spécifie si l’objet d’appareil représente un appareil exclusif. La plupart des pilotes définissent cette valeur sur FALSE. Pour plus d’informations sur l’accès exclusif, consultez Spécification de l’accès exclusif aux objets d’appareil.

[out] DeviceObject

Pointeur vers une variable qui reçoit un pointeur vers la structure DEVICE_OBJECT nouvellement créée. La structure DEVICE_OBJECT est allouée à partir d’un pool non paginé. L’extension de l’appareil de l’objet d’appareil est zéro.

Valeur retournée

IoCreateDevice retourne STATUS_SUCCESS en cas de réussite ou le code d’erreur NTSTATUS approprié en cas d’échec. Une liste partielle des codes d’échec retournés par cette fonction comprend :

STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_COLLISION

Remarques

IoCreateDevice crée un objet d’appareil et retourne un pointeur vers l’objet. L’appelant est responsable de la suppression de l’objet lorsqu’il n’est plus nécessaire en appelant IoDeleteDevice.

IoCreateDevice peut uniquement être utilisé pour créer un objet d’appareil sans nom ou un objet d’appareil nommé pour lequel un descripteur de sécurité est défini par un fichier INF. Sinon, les pilotes doivent utiliser IoCreateDeviceSecure pour créer des objets d’appareil nommés. Pour plus d’informations, consultez Création d’un objet Device. L’appelant est responsable de la définition de certains membres de l’objet d’appareil retourné. Pour plus d’informations, consultez Initialisation d’un objet d’appareil et la documentation spécifique au type d’appareil pour votre appareil.

Veillez à spécifier les valeurs DeviceType et DeviceCharacteristics dans les paramètres appropriés. Les deux paramètres utilisent des constantes FILE_XXX définies par le système et certains enregistreurs de pilotes spécifient par erreur les valeurs dans les paramètres incorrects.

Un système de fichiers distant qui crée un objet d’appareil nommé pour un redirecteur réseau et qui s’inscrit à l’aide de FsRtlRegisterUncProvider, doit spécifier FILE_REMOTE_DEVICE comme l’une des options du paramètre DeviceCharacteristics d’IoCreateDevice.

Les objets d’appareil pour les disques, les bandes, les CD-ROM et les disques RAM reçoivent un bloc de paramètres de volume (VPB) initialisé pour indiquer que le volume n’a jamais été monté sur l’appareil.

Si l’appel d’un pilote à IoCreateDevice renvoie une erreur, le pilote doit libérer toutes les ressources qu’il a allouées pour cet appareil.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
Règles de conformité DDI	AddDevice(wdm),CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDDIs(storport),IrqlIoPassive1(wdm), MiniportOnlyWdmDevice(kmdf)