Fonction IoGetDeviceProperty (wdm.h)
La routine IoGetDeviceProperty récupère des informations sur un appareil, telles que des informations de configuration et le nom de son PDO.
Syntaxe
NTSTATUS IoGetDeviceProperty(
[in] PDEVICE_OBJECT DeviceObject,
[in] DEVICE_REGISTRY_PROPERTY DeviceProperty,
[in] ULONG BufferLength,
[out, optional] PVOID PropertyBuffer,
[out] PULONG ResultLength
);
Paramètres
[in] DeviceObject
Pointeur vers l’objet d’appareil physique (PDO) pour l’appareil interrogé.
[in] DeviceProperty
Spécifie la propriété d’appareil demandée. Il doit s’agir de l’une des valeurs d’énumération DEVICE_REGISTRY_PROPERTY suivantes :
DevicePropertyAddress
Demande l’adresse de l’appareil sur le bus. PropertyBuffer pointe vers un ULONG.
L’interprétation de cette adresse est propre au bus. L’appelant de cette routine doit appeler à nouveau la routine pour demander devicePropertyBusTypeGuid, ou éventuellement devicePropertyLegacyBusType, afin qu’il puisse interpréter l’adresse. Une valeur d’adresse de 0xFFFFFFFF indique que le pilote de bus sous-jacent n’a pas fourni d’adresse de bus pour l’appareil.
La liste suivante décrit les informations que certains pilotes de bus stockent dans propertyBuffer pour leurs appareils enfants :
| Bus | Description |
|---|---|
| 1394 | Ne fournit pas d’adresse, car les adresses sont volatiles. La valeur par défaut est 0xFFFFFFFF. |
| EISA | Numéro d’emplacement (0-F). |
| IDE | Pour un appareil IDE, l’adresse contient l’ID cible et le numéro d’unité logique. Pour un canal IDE, l’adresse est zéro ou un (0 = canal principal et 1 = canal secondaire). |
| ISApnp | Ne fournit pas d’adresse. La valeur par défaut est 0xFFFFFFFF. |
| Carte PC (PCMCIA) | Numéro de socket (généralement 0x00 ou 0x40). |
| PCI | Le numéro d’appareil dans le mot le plus élevé et le numéro de fonction dans le mot faible. |
| SCSI | ID cible. |
| USB | Numéro de port. |
DevicePropertyBootConfiguration
Demande les ressources matérielles affectées à l’appareil par le microprogramme, sous forme brute. PropertyBuffer pointe vers une structure CM_RESOURCE_LIST .
DevicePropertyBootConfigurationTranslated
Ressources matérielles affectées à l’appareil par le microprogramme, sous forme traduite. PropertyBuffer pointe vers une structure CM_RESOURCE_LIST .
DevicePropertyBusNumber
Demande le numéro de bus hérité du bus à lequel l’appareil est connecté. PropertyBuffer pointe vers un ULONG.
DevicePropertyBusTypeGuid
Demande le GUID du bus auquel l’appareil est connecté. Les GUID de type de bus définis par le système sont répertoriés dans le fichier d’en-tête Wdmguid.h. PropertyBuffer pointe vers un GUID, qui est une structure de 16 octets qui contient le GUID sous forme binaire.
DevicePropertyClassGuid
Demande le GUID pour la classe d’installation de l’appareil. PropertyBuffer pointe vers un tableau de WCHAR terminé par NULL. Cette routine retourne le GUID au format chaîne comme suit, où chaque « c » représente un caractère hexadécimal : {cccccccc-cccc-cccc-cccc-cccccccccc}
DevicePropertyClassName
Demande le nom de la classe d’installation de l’appareil, au format texte. PropertyBuffer pointe vers une chaîne WCHAR terminée par NULL.
DevicePropertyCompatibleIDs
Demande les ID compatibles signalés par l’appareil. PropertyBuffer pointe vers une valeur REG_MULTI_SZ.
DevicePropertyDeviceDescription
Demande une chaîne décrivant l’appareil, telle que « Souris de port Microsoft PS/2 », généralement définie par le fabricant. PropertyBuffer pointe vers une chaîne WCHAR terminée par NULL.
DevicePropertyDriverKeyName
Demande le nom de la clé de Registre spécifique au pilote. PropertyBuffer pointe vers une chaîne WCHAR terminée par NULL.
DevicePropertyEnumeratorName
Demande le nom de l’énumérateur pour l’appareil, par exemple « PCI » ou « root ». PropertyBuffer pointe vers une chaîne WCHAR terminée par NULL.
DevicePropertyFriendlyName
Demande une chaîne qui peut être utilisée pour faire la distinction entre deux appareils similaires, généralement définis par le programme d’installation de classe. PropertyBuffer pointe vers une chaîne WCHAR terminée par NULL.
DevicePropertyHardwareID
Demande les ID matériels fournis par l’appareil qui identifie l’appareil. PropertyBuffer pointe vers une valeur REG_MULTI_SZ.
DevicePropertyInstallState
Demande l’état d’installation de l’appareil. L’état d’installation est retourné en tant que valeur d’énumération DEVICE_INSTALL_STATE .
DevicePropertyLegacyBusType
Demande le type de bus, par exemple PCIBus ou PCMCIABus. PropertyBuffer pointe vers une valeur d’énumération INTERFACE_TYPE .
DevicePropertyLocationInformation
Demande des informations sur l’emplacement de l’appareil dans le bus ; l’interprétation de ces informations est propre au bus. PropertyBuffer pointe vers une chaîne WCHAR terminée par NULL.
DevicePropertyManufacturer
Demande une chaîne identifiant le fabricant de l’appareil. PropertyBuffer pointe vers une chaîne WCHAR terminée par NULL.
DevicePropertyPhysicalDeviceObjectName
Demande le nom de l’AOP pour cet appareil. PropertyBuffer pointe vers une chaîne WCHAR terminée par NULL.
DevicePropertyRemovalPolicy
Demande la stratégie de suppression actuelle de l’appareil. Le système d’exploitation utilise cette valeur comme indicateur pour déterminer comment l’appareil est normalement supprimé. Le paramètre PropertyBuffer pointe vers une valeur d’énumération DEVICE_REMOVAL_POLICY .
DevicePropertyUINumber
Demande un nombre associé à l’appareil qui peut être affiché dans l’interface utilisateur. PropertyBuffer pointe vers une valeur ULONG.
Ce nombre est généralement un numéro d’emplacement perçu par l’utilisateur, tel qu’un numéro imprimé à côté de l’emplacement sur la carte, ou un autre nombre qui facilite la localisation de l’appareil physique pour l’utilisateur. Si l’appareil se trouve sur un bus qui n’a pas de convention de numéro d’interface utilisateur, ou si le pilote de bus de l’appareil ne peut pas déterminer le numéro d’interface utilisateur, cette valeur est 0xFFFFFFFF.
[in] BufferLength
Spécifie la taille, en octets, du PropertyBuffer fourni par l’appelant.
[out, optional] PropertyBuffer
Pointeur vers une mémoire tampon fournie par l’appelant pour recevoir les informations de propriété. La mémoire tampon peut être allouée à partir de la mémoire paginable. Le type de mémoire tampon est déterminé par deviceProperty (voir ci-dessus).
[out] ResultLength
Pointeur vers un ULONG pour recevoir la taille des informations de propriété retournées dans PropertyBuffer. Si IoGetDeviceProperty retourne STATUS_BUFFER_TOO_SMALL, il définit ce paramètre sur la longueur de mémoire tampon requise.
Valeur retournée
IoGetDeviceProperty retourne STATUS_SUCCESS si l’appel a réussi. Les valeurs de retour d’erreur possibles sont les suivantes.
| Code de retour | Description |
|---|---|
| STATUS_BUFFER_TOO_SMALL | La mémoire tampon dans PropertyBuffer était trop petite. ResultLength pointe vers la longueur de mémoire tampon requise. |
| STATUS_INVALID_PARAMETER_2 | La propriété DeviceProperty donnée n’est pas l’une des propriétés gérées par cette routine. |
| STATUS_INVALID_DEVICE_REQUEST | Indique peut-être que l’objet DeviceObject donné n’était pas un pointeur PDO valide. |
Remarques
IoGetDeviceProperty récupère les informations de configuration de l’appareil à partir du Registre. Utilisez cette routine, plutôt que d’accéder directement au Registre, pour isoler un pilote des différences entre les plateformes et des modifications possibles de la structure du Registre.
Pour de nombreuses demandes DeviceProperty , au moins deux appels à IoGetDeviceProperty peuvent être nécessaires pour déterminer le bufferLength requis. Le premier appel doit utiliser une valeur de meilleure estimation. Si le status de retour est STATUS_BUFFER_TOO_SMALL, le pilote doit libérer sa mémoire tampon actuelle, allouer une mémoire tampon de la taille retournée dans ResultLength et appeler à nouveau IoGetDeviceProperty. Étant donné que certaines propriétés d’installation sont dynamiques, la taille des données peut changer entre le moment où la taille requise est retournée et que le pilote appelle à nouveau cette routine. Par conséquent, les pilotes doivent appeler IoGetDeviceProperty à l’intérieur d’une boucle qui s’exécute jusqu’à ce que le status de retour ne soit pas STATUS_BUFFER_TOO_SMALL.
Les pilotes de fonction qui prennent en charge les appareils d’un bus hérité et d’un bus PnP peuvent utiliser les propriétés DevicePropertyBusNumber, DevicePropertyBusTypeGuid et DevicePropertyLegacyBusType pour faire la distinction entre les bus.
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 |
| Règles de conformité DDI | HwStorPortProhibitedDDIs(storport),PowerIrpDDis(wdm) |