IRegistryKey ::QueryValueKey, méthode (portcls.h)

Article
02/07/2025

La méthode QueryValueKey récupère des informations sur les entrées de valeur d’une clé de Registre, y compris leurs noms, types, tailles de données et valeurs.

Syntaxe

NTSTATUS QueryValueKey(
  [in]  PUNICODE_STRING             ValueName,
  [in]  KEY_VALUE_INFORMATION_CLASS KeyValueInformationClass,
  [out] PVOID                       KeyValueInformation,
  [in]  ULONG                       Length,
  [out] PULONG                      ResultLength
);

Paramètres

[in] ValueName

Pointeur vers le nom fourni par le fabricant de l’entrée de valeur. La chaîne de nom est spécifiée par une structure de type UNICODE_STRING.

[in] KeyValueInformationClass

Spécifie le type d’informations à retourner dans la mémoire tampon. Définissez ce paramètre sur l’une des valeurs d’énumération KEY_VALUE_INFORMATION_CLASS suivantes :

KeyValueBasicInformation
KeyValueFullInformation
KeyValuePartialInformation

[out] KeyValueInformation

Pointeur vers une mémoire tampon allouée par l’appelant dans laquelle la méthode écrit les données demandées. La mémoire tampon contient une structure de type KEY_VALUE_BASIC_INFORMATION, KEY_VALUE_FULL_INFORMATIONou KEY_VALUE_PARTIAL_INFORMATION, en fonction de la valeur de KeyValueInformationClass. La structure est suivie de données supplémentaires dont la taille dépend du type de données de la valeur de clé.

[in] Length

Taille en octets de la mémoire tampon KeyValueInformation, que l’appelant doit définir en fonction de la KeyValueInformationClassdonnée. Pour recevoir toutes les données demandées, la mémoire tampon doit être au moins aussi grande que la taille des données demandées.

[out] ResultLength

Pointeur de sortie pour la longueur des données obtenues. Ce paramètre pointe vers une variable ULONG allouée par l’appelant dans laquelle la méthode écrit un nombre d’octets réellement écrits dans la mémoire tampon KeyValueInformation. Si la longueur de la mémoire tampon spécifiée est trop petite pour contenir les informations, toutefois, la méthode génère à la place la taille de mémoire tampon requise et retourne STATUS_BUFFER_OVERFLOW ou STATUS_BUFFER_TOO_SMALL. Pour plus d’informations, consultez la section Remarques suivante.

Valeur de retour

QueryValueKey retourne STATUS_SUCCESS si l’appel a réussi à copier les informations demandées dans la mémoire tampon KeyValueInformation. Si la taille de mémoire tampon spécifiée est trop petite pour recevoir toutes les informations demandées, la méthode retourne STATUS_BUFFER_OVERFLOW. Si la taille de mémoire tampon spécifiée est trop petite pour recevoir les informations demandées, la méthode retourne STATUS_BUFFER_TOO_SMALL. Sinon, la méthode retourne un code d’état d’erreur approprié. Le tableau suivant présente certains des codes d’erreur possibles.

Retourner le code	Description
STATUS_INVALID_PARAMETER	Indique qu’un des paramètres passés à la méthode n’est pas valide.
STATUS_OBJECT_NAME_NOT_FOUND	Indique que l’entrée de valeur portant le nom spécifié n’a pas été trouvée.

Remarques

Si la mémoire tampon KeyValueInformation est trop petite pour contenir les informations demandées, la méthode écrit la taille requise dans * ResultLength et retourne un code d’état de STATUS_BUFFER_OVERFLOW ou de STATUS_BUFFER_TOO_SMALL. La méthode retourne STATUS_BUFFER_OVERFLOW si elle a réussi à écrire uniquement une partie des informations demandées dans la mémoire tampon. La méthode retourne STATUS_BUFFER_TOO_SMALL s’il n’a pas pu écrire d’informations dans la mémoire tampon. La valeur écrite dans *ResultLength indique la taille minimale de la mémoire tampon requise pour contenir toutes les informations demandées.