IoGetDeviceProperty, fonction (wdm.h)
La routine IoGetDeviceProperty récupère des informations sur un appareil, telles que les 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
Énumérateur DEVICE_REGISTRY_PROPERTY-typé qui identifie la propriété de l’appareil à récupérer.
[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 la mémoire tampon est déterminé par le DeviceProperty (voir ci-dessus).
[out] ResultLength
Pointeur vers un ULONG pour recevoir la taille des informations de propriété retournées à PropertyBuffer. Si IoGetDeviceProperty retourne STATUS_BUFFER_TOO_SMALL, il définit ce paramètre sur la longueur de mémoire tampon requise.
Valeur de retour
IoGetDeviceProperty retourne STATUS_SUCCESS si l’appel a réussi. Les valeurs de retour d’erreur possibles sont les suivantes.
| Retourner le code | Description |
|---|---|
| STATUS_BUFFER_TOO_SMALL | La mémoire tampon à PropertyBuffer était trop petite. ResultLength pointe vers la longueur de mémoire tampon requise. |
| STATUS_INVALID_PARAMETER_2 | La 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 le DeviceObject donné n’était pas un pointeur PDO valide. |
Remarques
IoGetDeviceProperty récupère les informations d’installation 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 dans la structure du Registre.
Pour de nombreuses requêtes DeviceProperty, il peut prendre deux appels ou plus pour IoGetDeviceProperty pour déterminer la BufferLength requise. Le premier appel doit utiliser une valeur de meilleure estimation. Si l’état 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 IoGetDeviceProperty à nouveau. É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 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 l’état de retour ne soit pas STATUS_BUFFER_TOO_SMALL.
Les pilotes de fonction qui prennent en charge les appareils sur un bus hérité et un bus PnP peuvent utiliser les propriétés DevicePropertyBusNumber, DevicePropertyBusTypeGuidet DevicePropertyLegacyBusType pour distinguer les bus.
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 |
| règles de conformité DDI | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |