WdmlibIoCreateDeviceSecure, fonction (wdmsec.h)

Article
02/27/2024

La fonction WdmlibIoCreateDeviceSecure (ou IoCreateDeviceSecure) crée un objet d’appareil nommé et applique les paramètres de sécurité spécifiés.

Syntaxe

NTSTATUS WdmlibIoCreateDeviceSecure(
  [in]           PDRIVER_OBJECT   DriverObject,
  [in]           ULONG            DeviceExtensionSize,
  [in, optional] PUNICODE_STRING  DeviceName,
  [in]           DEVICE_TYPE      DeviceType,
  [in]           ULONG            DeviceCharacteristics,
  [in]           BOOLEAN          Exclusive,
  [in]           PCUNICODE_STRING DefaultSDDLString,
  [in, optional] LPCGUID          DeviceClassGuid,
                 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 qui contient 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. Si aucun nom n’est fourni, l’indicateur FILE_AUTOGENERATED_DEVICE_NAME doit être présent dans le paramètre DeviceCharacteristics . (Pour créer un objet d’appareil sans nom, utilisez la routine IoCreateDevice .)

[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, FILE_DEVICE_KEYBOARD, etc.), 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. (Étant donné qu’un pilote de bus n’a peut-être pas d’informations sur le type d’un appareil, une valeur de type d’appareil pour un PDO peut être spécifiée dans une directive AddReg INF.)

[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, consultez Spécification de l’accès exclusif aux objets d’appareil.

[in] DefaultSDDLString

Spécifie une représentation sous forme de chaîne pour les paramètres de sécurité par défaut de l’objet d’appareil. La sécurité appliquée à l’objet d’appareil est dérivée de cette chaîne, sauf si l’administrateur système place une substitution dans la section du Registre identifiée par le paramètre DeviceClassGuid .

Le paramètre de sécurité est spécifié dans un sous-ensemble du langage SDDL (Security Descriptor Definition Language). Un ensemble de constantes prédéfinies (SDDL_DEVOBJ_XXX) est également fourni. Pour plus d’informations, consultez Sécurisation des objets d’appareil.

[in, optional] DeviceClassGuid

Pointeur vers un GUID qui identifie une section du Registre contenant les remplacements possibles pour les paramètres DefaultSDDLString, DeviceType, DeviceCharacteristics et Exclusive .

Note Vous devez toujours spécifier un GUID de classe personnalisé. Vous ne devez pas spécifier un GUID de classe existant. Si vous spécifiez un GUID de classe existant, d’autres pilotes qui tentent de spécifier que le GUID de classe existant peut ne pas être installé ou peut s’installer avec des paramètres de sécurité incorrects.

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é.

Valeur retournée

WdmlibIoCreateDeviceSecure retourne STATUS_SUCCESS en cas de réussite ou le code d’erreur NTSTATUS approprié en cas d’échec. Voici une liste partielle des codes d’échec qui peuvent être retournés par cette fonction :

Remarques

WdmlibIoCreateDeviceSecure crée un objet d’appareil nommé, applique les paramètres de sécurité spécifiés 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.

Cette routine ne fait pas partie du système d’exploitation. Les pilotes peuvent utiliser la routine en les liant à Wdmsec.lib sur Microsoft Windows 2000 et versions ultérieures de Windows. (La bibliothèque Wdmsec.lib a d’abord été fournie avec les éditions Microsoft Windows XP Service Pack 1 [SP1] et Windows Server 2003 du Kit de développement de pilotes [DDK] et est également fournie avec le Kit de pilotes Windows [WDK].)

Tout pilote qui crée un objet d’appareil nommé dont le descripteur de sécurité n’est pas défini par le fichier INF doit utiliser WdmlibIoCreateDeviceSecure. 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.

L’appelant est responsable de la définition de certains champs dans l’objet d’appareil retourné, comme le champ Indicateurs , et de l’initialisation de l’extension de l’appareil avec toutes les informations définies par le pilote. Pour obtenir d’autres opérations requises sur les nouveaux objets d’appareil, consultez Initialisation d’un objet d’appareil et la documentation spécifique au type d’appareil pour votre appareil.

Le GUID spécifié par le paramètre DeviceClassGuid détermine la classe d’installation de l’appareil pour l’objet d’appareil. (Pour plus d’informations sur les classes d’installation des appareils, consultez Classes de configuration de l’appareil.) Les appelants doivent fournir une valeur afin que les administrateurs système puissent modifier les paramètres de sécurité de l’appareil (pour instance, pour refuser l’accès à certains utilisateurs). Pour plus d’informations, consultez Définition des propriétés du Registre d’objets d’appareil après l’installation.

Les pilotes non WDM spécifient un nouveau GUID, qui n’est pas déjà utilisé par une classe d’installation d’appareil existante. Générez un nouveau GUID à l’aide de l’outil GuidGen.exe inclus dans le Microsoft Windows SDK.

Les pilotes de bus WDM qui gèrent les appareils compatibles en mode brut peuvent spécifier la classe d’installation de l’appareil, mais uniquement si cette classe est garantie qu’elle a déjà été créée. Sinon, créez un GUID.

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 à WdmlibIoCreateDeviceSecure renvoie une erreur, le pilote doit libérer toutes les ressources qu’il a allouées pour cet appareil.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Consultez la section Notes.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	wdmsec.h (inclure Wdmsec.h)
Bibliothèque	Wdmsec.lib
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	AddDevice(wdm),HwStorPortProhibitedDDIs(storport),IrqlIoPassive1(wdm), MiniportOnlyWdmDevice