Fonction WdfDeviceQueryProperty (wdfdevice.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfDeviceQueryProperty récupère une propriété d’appareil spécifiée.

Syntaxe

NTSTATUS WdfDeviceQueryProperty(
  [in]  WDFDEVICE                Device,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

Paramètres

[in] Device

Handle d’un objet d’appareil framework.

[in] DeviceProperty

Énumérateur 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 pointée par PropertyBuffer.

[out] PropertyBuffer

Pointeur fourni par l’appelant vers une mémoire tampon allouée à l’appelant qui reçoit les informations demandées. Le pointeur peut avoir la valeur NULL si le paramètre BufferLength est égal à zéro.

[out] ResultLength

Emplacement fourni par l’appelant qui, au retour, contient la taille, en octets, des informations que la méthode stockée dans PropertyBuffer. Si la valeur de retour de la fonction est STATUS_BUFFER_TOO_SMALL, cet emplacement reçoit la taille de mémoire tampon requise.

Valeur retournée

Si l’opération réussit, WdfDeviceQueryProperty retourne STATUS_SUCCESS. Les valeurs de retour supplémentaires sont les suivantes :

Code de retour	Description
STATUS_BUFFER_TOO_SMALL	La mémoire tampon fournie est trop petite pour recevoir les informations.
STATUS_INVALID_PARAMETER_2	La valeur DeviceProperty 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.

La méthode peut 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 les données de propriété d’appareil, les pilotes appellent généralement la méthode WdfDeviceQueryProperty juste 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 lorsque le pilote appelle À nouveau WdfDeviceQueryProperty . Par conséquent, les pilotes doivent appeler WdfDeviceQueryProperty à l’intérieur d’une boucle qui s’exécute jusqu’à ce que la status de retour ne soit pas STATUS_BUFFER_TOO_SMALL.

Il est préférable d’utiliser WdfDeviceQueryProperty uniquement si la taille de mémoire tampon requise est connue et inchangée, car dans ce cas, le pilote ne doit appeler WdfDeviceQueryProperty qu’une seule fois. Si la taille de mémoire tampon requise est inconnue ou varie, le pilote doit appeler WdfDeviceAllocAndQueryProperty.

Vous pouvez également utiliser WdfDeviceQueryPropertyEx pour accéder aux propriétés de l’appareil exposées via le modèle de propriété unifié.

Exemples

L’exemple de code suivant obtient la propriété DevicePropertyBusTypeGuid d’un appareil. L’exemple appelle WdfDeviceQueryProperty au lieu de WdfDeviceAllocAndQueryProperty , car la longueur d’un GUID est connue.

GUID  busTypeGuid;
ULONG  resultLength = 0;
NTSTATUS  status;

status = WdfDeviceQueryProperty( 
                                device,
                                DevicePropertyBusTypeGuid,
                                sizeof(GUID),
                                (PVOID)&busTypeGuid,
                                &resultLength
                                );

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfdevice.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi

WdfDeviceAllocAndQueryProperty

WdfFdoInitQueryProperty

Partager via