WdfIoTargetQueryTargetProperty, fonction (wdfiotarget.h)

Article
02/27/2024

[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
STATUS_BUFFER_TOO_SMALL	La mémoire tampon vers laquelle le paramètre PropertyBuffer pointait était trop petite pour recevoir les informations demandées.
STATUS_INVALID_PARAMETER_2	Valeur que le paramètre DeviceProperty a spécifiée n’est pas valide.
STATUS_INVALID_DEVICE_REQUEST	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)