WdfRegistryQueryMemory, fonction (wdfregistry.h)

Article
02/27/2024

[S’applique à KMDF et UMDF]

La méthode WdfRegistryQueryMemory récupère les données actuellement affectées à une valeur de Registre spécifiée, stocke les données dans une mémoire tampon allouée par l’infrastructure et crée un objet de mémoire du framework pour représenter la mémoire tampon.

Syntaxe

NTSTATUS WdfRegistryQueryMemory(
  [in]            WDFKEY                 Key,
  [in]            PCUNICODE_STRING       ValueName,
  [in]            POOL_TYPE              PoolType,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES MemoryAttributes,
  [out]           WDFMEMORY              *Memory,
  [out, optional] PULONG                 ValueType
);

Paramètres

[in] Key

Handle d’un objet de clé de Registre qui représente une clé de Registre ouverte.

[in] ValueName

Pointeur vers une structure UNICODE_STRING qui contient un nom de valeur.

[in] PoolType

Valeur de type POOL_TYPE qui spécifie le type de mémoire à allouer à la mémoire tampon de données.

[in, optional] MemoryAttributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui contient des attributs d’objet pour le nouvel objet mémoire. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[out] Memory

Pointeur vers un emplacement qui reçoit un handle vers le nouvel objet mémoire.

[out, optional] ValueType

Pointeur vers un emplacement qui reçoit le type de données. Pour obtenir la liste des valeurs de type de données, consultez le membre Type de KEY_VALUE_BASIC_INFORMATION. Ce pointeur est facultatif et peut être NULL.

Valeur retournée

WdfRegistryQueryMemory retourne STATUS_SUCCESS si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryQueryMemory n’a pas été appelé dans IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été spécifié.
STATUS_INSUFFICIENT_RESOURCES	Impossible d’allouer un objet mémoire.
STATUS_ACCESS_DENIED	Le pilote n’a pas ouvert la clé de Registre avec un accès KEY_QUERY_VALUE, KEY_READ ou KEY_ALL_ACCESS.
STATUS_OBJECT_NAME_NOT_FOUND	La valeur du Registre n’était pas disponible.
STATUS_RESOURCE_DATA_NOT_FOUND	La valeur de Registre existe sous la clé spécifiée, mais est vide.

Pour obtenir la liste des autres valeurs de retour que la méthode WdfRegistryQueryMemory peut retourner, consultez Erreurs de création d’objets framework.

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

Lorsqu’un pilote appelle WdfRegistryQueryMemory, l’infrastructure alloue une mémoire tampon suffisamment grande pour contenir les données de la valeur de Registre spécifiée. Une fois que WdfRegistryQueryMemory est retourné, le pilote peut appeler WdfMemoryGetBuffer pour obtenir un pointeur vers la mémoire tampon et la taille de la mémoire tampon.

Pour plus d’informations sur les objets de clé de Registre, consultez Utilisation du Registre dans les pilotes Framework-Based.

Exemples

L’exemple de code suivant récupère les données affectées à la valeur MyValueName , puis obtient l’adresse et la taille des données.

WDFMEMORY memory;
size_t size;
PUCHAR pBuf;
NTSTATUS status;
ULONG type;
DECLARE_CONST_UNICODE_STRING(valueName1, L"MyValueName");

status = WdfRegistryQueryMemory(
                                Key,
                                &valueName1,
                                PagedPool,
                                NULL,
                                &memory,
                                &type
                                );
pBuf = (PUCHAR)WdfMemoryGetBuffer(
                                   memory,
                                   &size
                                   );

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfregistry.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)