WdfRegistryQueryValue, fonction (wdfregistry.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfRegistryQueryValue récupère les données actuellement affectées à une valeur de Registre spécifiée.

Syntaxe

NTSTATUS WdfRegistryQueryValue(
  [in]            WDFKEY           Key,
  [in]            PCUNICODE_STRING ValueName,
  [in]            ULONG            ValueLength,
  [out, optional] PVOID            Value,
  [out, optional] PULONG           ValueLengthQueried,
  [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] ValueLength

Longueur, en octets, de la mémoire tampon vers laquelle value pointe.

[out, optional] Value

Pointeur vers une mémoire tampon allouée par le pilote qui reçoit les données de la valeur de Registre. Si ce pointeur a la valeur NULL, WdfRegistryQueryValue récupère la longueur des données, mais pas les données.

[out, optional] ValueLengthQueried

Pointeur vers un emplacement qui reçoit la longueur des données de la valeur de Registre. Ce pointeur est facultatif et peut être NULL.

[out, optional] ValueType

Pointeur vers un emplacement qui reçoit le type de données de la valeur de Registre. 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

WdfRegistryQueryValue 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	WdfRegistryQueryValue n’a pas été appelé dans IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été spécifié.
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_BUFFER_OVERFLOW	La mémoire tampon vers laquelle pointe le paramètre Value est trop petite et seules des données partielles ont été écrites dans la mémoire tampon.
STATUS_BUFFER_OVERFLOW	La mémoire tampon Value est trop petite et aucune donnée n’a été écrite dans la mémoire tampon.
STATUS_OBJECT_NAME_NOT_FOUND	La valeur du Registre n’était pas disponible.

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

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 ouvre la clé matérielle d’un appareil et récupère les données affectées à la valeur NumberOfToasters , qui est stockée sous la clé matérielle de l’appareil.

WCHAR  comPort[FM_COM_PORT_STRING_LENGTH];
ULONG  length;
NTSTATUS  status;
ULONG  length, valueType, value;
DECLARE_CONST_UNICODE_STRING(valueName, L"NumberOfToasters");
WDFKEY  hKey;

status = WdfDeviceOpenRegistryKey(
                                  Device,
                                  PLUGPLAY_REGKEY_DEVICE,
                                  KEY_QUERY_VALUE,
                                  NULL, 
                                  &hKey
                                  );
if (!NT_SUCCESS (status)) {
    goto Error;
}
status = WdfRegistryQueryValue(
                               hKey,
                               &valueName,
                               sizeof(ULONG),
                               &value,
                               &length,
                               &valueType
                               );

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)