Fonction IoCreateDevice (wdm.h)

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 de l’appelant. Chaque pilote reçoit un pointeur vers son objet pilote dans un paramètre vers sa routine DriverEntry. La fonction WDM et les pilotes de filtre reçoivent également un pointeur d’objet de pilote dans leurs routines d'AddDevice.

[in] DeviceExtensionSize

Spécifie le nombre déterminé par le pilote d’octets à allouer pour l’extension d’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

Si vous le souhaitez, il pointe 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 est NULL), l’objet d’appareil créé par IoCreateDevice n’a pas (et ne peut pas) avoir une liste de contrôle d’accès discrétionnaire (DACL) associée. 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 (tel que 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 des 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 façon de spécifier des caractéristiques d’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 de l’appareil représente und’appareil exclusif . La plupart des pilotes définissent cette valeur sur FALSE. Pour plus d’informations sur l’accès exclusif, consultez Spécification d’un 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 du pool non paginé. L’extension de l’appareil de l’objet d’appareil est zéro.

Valeur de retour

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 inclut :

• 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 chargé de supprimer l’objet lorsqu’il n’est plus nécessaire en appelant IoDeleteDevice.

IoCreateDevice ne peut être utilisé que 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 d’appareil. 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 corrects. Les deux paramètres utilisent des constantes FILE_XXX définies par le système et certains enregistreurs de pilotes spécifient les valeurs dans les paramètres incorrects par erreur.

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 de l'DeviceCharacteristics paramètre d’IoCreateDevice.

Les objets d’appareil pour les disques, bandes, CD-ROMs 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 retourne une erreur, le pilote doit libérer les ressources qu’il a allouées pour cet appareil.

Exigences

Voir aussi

DEVICE_OBJECT

FsRtlRegisterUncProvider

IoAttachDevice

IoAttachDeviceToDeviceStack

IoCreateDeviceSecure

IoCreateSymbolicLink

IoDeleteDevice