WdfIoTargetAllocAndQueryTargetProperty, fonction (wdfiotarget.h)

Article
03/22/2025

[S’applique uniquement à KMDF]

La méthode WdfIoTargetAllocAndQueryTargetProperty alloue une mémoire tampon et récupère une propriété d’appareil spécifiée pour une cible d’E/S spécifiée.

Syntaxe

NTSTATUS WdfIoTargetAllocAndQueryTargetProperty(
  [in]           WDFIOTARGET              IoTarget,
  [in]           DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]           POOL_TYPE                PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   PropertyMemoryAttributes,
  [out]          WDFMEMORY                *PropertyMemory
);

Paramètres

[in] IoTarget

Handle vers un objet cible d’E/S local ou distant 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 DEVICE_REGISTRY_PROPERTY-typée qui identifie la propriété de l’appareil à récupérer.

[in] PoolType

Valeur POOL_TYPE-typée qui spécifie le type de mémoire à allouer.

[in, optional] PropertyMemoryAttributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES allouée par l’appelant qui décrit les attributs d’objet pour l’objet mémoire que la fonction alloue. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[out] PropertyMemory

Pointeur vers un emplacement typé WDFMEMORY qui reçoit un handle vers un objet mémoire de framework.

Valeur de retour

WdfIoTargetAllocAndQueryTargetProperty 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_INVALID_PARAMETER ou STATUS_INVALID_PARAMETER_2	Valeur que le paramètre DeviceProperty spécifié 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 .

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Remarques

La méthode WdfIoTargetAllocAndQueryTargetProperty détermine la quantité de mémoire nécessaire pour contenir la propriété d’appareil demandée. Cette méthode alloue suffisamment de mémoire pour contenir les données et retourne un handle à un objet de mémoire de framework qui décrit la mémoire allouée. Pour accéder aux données, votre pilote peut appeler WdfMemoryGetBuffer.

Pour plus d’informations sur WdfIoTargetAllocAndQueryTargetProperty, consultez Obtenir des informations sur une cible d’E/S générale.

Pour plus d’informations sur les cibles d’E/S, consultez Utilisation des cibles d’E/S.

Exemples

L’exemple de code suivant appelle WdfIoTargetAllocAndQueryTargetProperty pour obtenir la propriété DevicePropertyFriendlyName. Après WdfIoTargetAllocAndQueryTargetProperty retourne, le pilote peut appeler WdfMemoryGetBuffer pour obtenir un pointeur vers la mémoire tampon qui contient la chaîne de nom.

WDFMEMORY  targetName;
NTSTATUS  status;

status = WdfIoTargetAllocAndQueryTargetProperty(
                                                Target,
                                                DevicePropertyFriendlyName,
                                                NonPagedPool,
                                                WDF_NO_OBJECT_ATTRIBUTES,
                                                &targetName
                                                );

Spécifications

Besoin	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
En-tête	wdfiotarget.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (voir Versioning de la bibliothèque Framework.)
IRQL	PASSIVE_LEVEL
règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)