Fonction IoRegisterDeviceInterface (wdm.h)

La routine IoRegisterDeviceInterface inscrit une classe d’interface d’appareil, si elle n’a pas été inscrite précédemment, et crée une nouvelle instance de la classe d’interface, qu’un pilote peut ensuite activer pour une utilisation par les applications ou d’autres composants système.

Syntaxe

NTSTATUS IoRegisterDeviceInterface(
  [in]           PDEVICE_OBJECT  PhysicalDeviceObject,
  [in]           const GUID      *InterfaceClassGuid,
  [in, optional] PUNICODE_STRING ReferenceString,
  [out]          PUNICODE_STRING SymbolicLinkName
);

Paramètres

[in] PhysicalDeviceObject

Pointeur vers l’AOP de l’appareil.

[in] InterfaceClassGuid

Pointeur vers le GUID de classe qui identifie la fonctionnalité (classe d’interface d’appareil) inscrite.

[in, optional] ReferenceString

Pointe éventuellement vers un UNICODE_STRING. La chaîne ne doit pas contenir de caractères séparateurs de chemin (« / » ou « \ »). Les pilotes de fonction spécifient généralement NULL pour ce paramètre. Les pilotes de filtre doivent spécifier NULL.

Les chaînes de référence ne sont utilisées que par quelques pilotes de bus, tels que swenum, qui est un pilote de bus qui utilise des instances d’interface d’appareil comme espaces réservés pour les appareils logiciels créés à la demande. Lorsqu’une instance d’une interface est ouverte, le gestionnaire d’E/S transmet la chaîne de référence du instance au pilote. La chaîne fait partie du nom de l’interface instance (en tant que composant de chemin d’accès ajouté). Le pilote peut ensuite utiliser la chaîne de référence pour différencier deux instances d’interface de la même classe pour un seul appareil.

Sur les systèmes Microsoft Windows 98/Me, la valeur ReferenceString ne peut pas dépasser MAX_PATH caractères. Il n’existe aucune limite de longueur sur Windows 2000 et les versions ultérieures de Windows.

[out] SymbolicLinkName

Pointeur vers une structure de chaîne Unicode allouée par l’appelant. Si cette routine réussit, elle initialise la chaîne Unicode et alloue la mémoire tampon de chaîne contenant le chemin d’accès en mode noyau au lien symbolique pour un instance de la classe d’interface d’appareil spécifiée.

L’appelant doit traiter SymbolicLinkName comme opaque et ne doit pas le désassembler.

L’appelant est responsable de la libération de SymbolicLinkName avec RtlFreeUnicodeString lorsqu’il n’est plus nécessaire.

Valeur retournée

IoRegisterDeviceInterface retourne STATUS_SUCCESS si l’appel a réussi. Les valeurs de retour d’erreur possibles sont les suivantes.

Code de retour	Description
STATUS_INVALID_DEVICE_REQUEST	Les paramètres ne sont pas valides. Les possibilités incluent que PhysicalDeviceObject ne pointe pas vers un PDO valide ou que la chaîne ReferenceString contient un caractère non valide.

Remarques

IoRegisterDeviceInterface inscrit une classe d’interface d’appareil, si elle n’a pas été inscrite précédemment, et crée une nouvelle instance de la classe d’interface. Un pilote peut appeler cette routine plusieurs fois pour un appareil donné afin d’inscrire plusieurs classes d’interface et de créer des instances des classes. Un pilote de fonction ou de filtre inscrit généralement des interfaces d’appareil dans sa routine AddDevice . Par exemple, un pilote de volume tolérant aux pannes peut inscrire une instance d’une interface de volume tolérant aux pannes et une instance d’une interface de volume pour un volume particulier.

Si la classe d’interface d’appareil n’a pas été inscrite précédemment, le gestionnaire d’E/S crée une clé de Registre pour celle-ci, ainsi que instance stockage persistant spécifique sous la clé. Les pilotes peuvent accéder à ce stockage persistant à l’aide de IoOpenDeviceInterfaceRegistryKey.

Un pilote inscrit une interface instance une fois, puis appelle IoSetDeviceInterfaceState pour activer et désactiver l’interface.

Les interfaces inscrites persistent entre les redémarrages du système d’exploitation. Si l’interface spécifiée est déjà inscrite, le gestionnaire d’E/S passe son nom dans SymbolicLinkName et retourne l’information de réussite status STATUS_OBJECT_NAME_EXISTS.

La plupart des pilotes utilisent une chaîne de référence NULL pour une interface d’appareil instance. Si un pilote utilise une chaîne de référence non NULL , il doit effectuer un travail supplémentaire, y compris éventuellement gérer son propre espace de noms et sa propre sécurité. Un pilote de filtre qui expose une interface d’appareil doit utiliser une chaîne de référenceNULL pour éviter les conflits avec d’autres pilotes de la pile d’appareils.

Les appelants de cette routine ne sont pas tenus de supprimer l’inscription pour une interface d’appareil quand elle n’est plus nécessaire. Les inscriptions d’interface d’appareil peuvent être supprimées du mode utilisateur, si nécessaire.

Les appelants d’IoRegisterDeviceInterface doivent s’exécuter à IRQL = PASSIVE_LEVEL dans le contexte d’un thread système.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 2000.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (voir la section Remarques)
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport),IrqlIoPassive3(wdm), PowerIrpDDis(wdm)

Voir aussi

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString