WdfDeviceAllocAndQueryProperty, fonction (wdfdevice.h)

Article
02/29/2024

[S’applique à KMDF et UMDF]

La méthode WdfDeviceAllocAndQueryProperty alloue une mémoire tampon et récupère une propriété d’appareil spécifiée.

Syntaxe

NTSTATUS WdfDeviceAllocAndQueryProperty(
  [in]           WDFDEVICE                Device,
  [in]           DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]           POOL_TYPE                PoolType,
  [in, optional] PWDF_OBJECT_ATTRIBUTES   PropertyMemoryAttributes,
  [out]          WDFMEMORY                *PropertyMemory
);

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

Énumérateur 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

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

Code de retour	Description
STATUS_INVALID_PARAMETER ou 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

La méthode WdfDeviceAllocAndQueryProperty détermine la quantité de mémoire nécessaire pour contenir la propriété d’appareil demandée. Il 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.

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

Exemples

L’exemple de code suivant initialise une structure de WDF_OBJECT_ATTRIBUTES avec des attributs pour l’objet de mémoire framework que l’infrastructure va créer pour la propriété demandée. Ensuite, l’exemple appelle WdfDeviceAllocAndQueryProperty pour obtenir la propriété DevicePropertyPhysicalDeviceObjectName . Une fois que WdfDeviceAllocAndQueryProperty est retourné, le pilote peut appeler WdfMemoryGetBuffer pour obtenir un pointeur vers la mémoire tampon qui contient la chaîne de nom.

WDF_OBJECT_ATTRIBUTES  attributes;
NTSTATUS  status;
WDFDEVICE  device;
WDFMEMORY  memory;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = device;

status = WdfDeviceAllocAndQueryProperty(device,
                                        DevicePropertyPhysicalDeviceObjectName,
                                        NonPagedPool,
                                        &attributes,
                                        &memory
                                        );
if (!NT_SUCCESS(status)) {
    return STATUS_UNSUCCESSFUL;
}

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

WdfDeviceQueryProperty

Partager via