WdfIoTargetQueryTargetProperty, fonction (wdfiotarget.h)
[S’applique à KMDF uniquement]
La méthode WdfIoTargetQueryTargetProperty récupère une propriété d’appareil spécifiée pour une cible d’E/S spécifiée.
Syntaxe
NTSTATUS WdfIoTargetQueryTargetProperty(
[in] WDFIOTARGET IoTarget,
[in] DEVICE_REGISTRY_PROPERTY DeviceProperty,
[in] ULONG BufferLength,
[out, optional] PVOID PropertyBuffer,
[out] PULONG ResultLength
);
Paramètres
[in] IoTarget
Handle vers un objet cible d’E/S local ou distant qui a été obtenu à partir d’un appel précédent à WdfDeviceGetIoTarget ou WdfIoTargetCreate, ou à partir d’une méthode qu’une cible d’E/S spécialisée fournit.
[in] DeviceProperty
Valeur de type DEVICE_REGISTRY_PROPERTY qui identifie la propriété d’appareil à récupérer.
[in] BufferLength
Taille, en octets, de la mémoire tampon vers laquelle PropertyBuffer pointe.
[out, optional] PropertyBuffer
Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit les informations de propriété d’appareil demandées. Ce pointeur peut être NULL si BufferLength est égal à zéro.
[out] ResultLength
Pointeur vers un emplacement qui, au retour, contient la taille, en octets, des informations stockées par WdfIoTargetQueryTargetProperty dans la mémoire tampon vers laquelle PropertyBuffer pointe. Si WdfIoTargetQueryTargetProperty retourne STATUS_BUFFER_TOO_SMALL, cet emplacement reçoit la taille de mémoire tampon requise.
Valeur retournée
WdfIoTargetQueryTargetProperty retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :
| Code de retour | Description |
|---|---|
|
La mémoire tampon vers laquelle le paramètre PropertyBuffer pointait était trop petite pour recevoir les informations demandées. |
|
Valeur que le paramètre DeviceProperty a spécifiée n’est pas valide. |
|
Les pilotes de l’appareil n’ont pas encore signalé les propriétés de l’appareil. |
Cette méthode peut également retourner d’autres valeurs NTSTATUS.
Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.
Remarques
Avant de recevoir des données de propriété de périphérique, les pilotes appellent généralement la méthode WdfIoTargetQueryTargetProperty pour obtenir la taille de mémoire tampon requise. Pour certaines propriétés, la taille des données peut changer entre le moment où la taille requise est retournée et le moment où le pilote appelle À nouveau WdfIoTargetQueryTargetProperty . Par conséquent, les pilotes doivent appeler WdfIoTargetQueryTargetProperty à l’intérieur d’une boucle qui s’exécute jusqu’à ce que la status de retour ne soit pas STATUS_BUFFER_TOO_SMALL.
Au lieu d’appeler WdfIoTargetQueryTargetProperty, votre pilote peut appeler WdfIoTargetAllocAndQueryTargetProperty, qui alloue une mémoire tampon et place les informations de propriété dans la mémoire tampon.
Pour plus d’informations sur WdfIoTargetQueryTargetProperty, consultez Obtention d’informations sur une cible d’E/S générale.
Pour plus d’informations sur les cibles d’E/S, consultez Utilisation de cibles d’E/S.
Exemples
L’exemple de code suivant obtient la propriété DevicePropertyUINumber d’un appareil. L’exemple appelle WdfIoTargetQueryTargetProperty au lieu de WdfIoTargetAllocAndQueryTargetProperty , car la longueur d’un numéro d’interface utilisateur est connue.
ULONG targetUINumber, resultLength;
NTSTATUS status;
status = WdfIoTargetQueryTargetProperty(
target,
DevicePropertyUINumber,
sizeof(targetNumber),
&targetUINumber,
&resultLength
);
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| Version KMDF minimale | 1.0 |
| En-tête | wdfiotarget.h (inclure Wdf.h) |
| Bibliothèque | Wdf01000.sys (consultez Gestion des versions de la bibliothèque d’infrastructure).) |
| IRQL | PASSIVE_LEVEL |
| Règles de conformité DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |