Partager via


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)

Voir aussi

CM_RESOURCE_LIST

DEVICE_REMOVAL_POLICY

ExAllocatePoolWithTag

GUID

INTERFACE_TYPE

IO_RESOURCE_REQUIREMENTS_LIST