IoRegisterDeviceInterface, fonction (wdm.h)
L'IoRegisterDeviceInterface routine inscrit une classe d’interface d’appareil , si elle n’a pas déjà été inscrite et crée une nouvelle instance de la classe d’interface, qu’un pilote peut ensuite activer pour une utilisation par des 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’objet PDO de l’appareil.
[in] InterfaceClassGuid
Pointeur vers le GUID de classe qui identifie les fonctionnalités (classe d’interface d’appareil) inscrites.
[in, optional] ReferenceString
Pointe éventuellement vers une UNICODE_STRING. La chaîne ne doit contenir aucun caractère de séparateur 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 sont utilisées uniquement par quelques pilotes de bus, tels que swenum, qui est un pilote de bus qui utilise des instances d’interface de périphérique 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 de l’instance au pilote. La chaîne fait partie du nom de l’instance d’interface (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 être supérieure à 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 d’une 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 chargé de libérer SymbolLinkName avec RtlFreeUnicodeString lorsqu’il n’est plus nécessaire.
Valeur de retour
IoRegisterDeviceInterface retourne STATUS_SUCCESS si l’appel a réussi. Les valeurs de retour d’erreur possibles sont les suivantes.
| Retourner le code | Description |
|---|---|
|
Les paramètres ne sont pas valides. Les possibilités incluent que PhysicalDeviceObject ne pointe pas vers une PDO valide, ou que la chaîne ReferenceString contient un caractère non valide. |
Remarques
IoRegisterDeviceInterface inscrit une classe d’interface d’appareil, s’il n’a pas été précédemment inscrit, et crée une instance de la classe d’interface. Un pilote peut appeler cette routine plusieurs fois pour qu’un appareil donné inscrive plusieurs classes d’interface et crée des instances des classes. Un pilote de fonction ou de filtre inscrit généralement des interfaces d’appareil dans son AddDevice routine. Par exemple, un pilote de volume à tolérance de panne peut inscrire une instance d’une interface de volume tolérante 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 le stockage persistant spécifique à l’instance sous la clé. Les pilotes peuvent accéder à ce stockage persistant à l’aide de IoOpenDeviceInterfaceRegistryKey.
Un pilote inscrit une instance d’interface une fois, puis appelle IoSetDeviceInterfaceState pour activer et désactiver l’interface.
Les interfaces inscrites persistent dans 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’état de réussite des informations STATUS_OBJECT_NAME_EXISTS.
La plupart des pilotes utilisent une chaîne de référence NULL
Les appelants de cette routine ne sont pas tenus de supprimer l’inscription d’une interface d’appareil lorsqu’il n’est plus nécessaire. Les inscriptions d’interface d’appareil peuvent être supprimées du mode utilisateur, si nécessaire.
Les appelants de IoRegisterDeviceInterface doivent s’exécuter à IRQL = PASSIVE_LEVEL dans le contexte d’un thread système.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible à partir de Windows 2000. |
| plateforme cible | Universel |
| d’en-tête | wdm.h (include 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 |