WdfIoTargetAllocAndQueryTargetProperty, fonction (wdfiotarget.h)

Article
08/08/2023

[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 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] PoolType

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

[in, optional] PropertyMemoryAttributes

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

[out] PropertyMemory

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

Valeur retournée

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	La valeur spécifiée par le paramètre DeviceProperty n’était 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

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 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 Obtention d’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 . Une fois que WdfIoTargetAllocAndQueryTargetProperty est retourné, 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
                                                );

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 de version de la bibliothèque d’infrastructure.)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)