Fonction SHRegGetUSValueA (shlwapi.h)

Article
08/26/2023

Récupère une valeur d’une sous-clé de Registre dans une sous-arborescence spécifique à l’utilisateur (HKEY_CURRENT_USER ou HKEY_LOCAL_MACHINE).

Syntaxe

LSTATUS SHRegGetUSValueA(
  [in]                LPCSTR pszSubKey,
  [in, optional]      LPCSTR pszValue,
  [in, out, optional] DWORD  *pdwType,
  [out, optional]     void   *pvData,
  [in, out, optional] DWORD  *pcbData,
  [in]                BOOL   fIgnoreHKCU,
  [in, optional]      void   *pvDefaultData,
  [in]                DWORD  dwDefaultDataSize
);

Paramètres

[in] pszSubKey

Type : LPCTSTR

Pointeur vers une chaîne terminée par null avec le nom de la sous-clé relative à HKEY_LOCAL_MACHINE et HKEY_CURRENT_USER. Par exemple : « Software\MyCompany\MyProduct ».

[in, optional] pszValue

Type : LPCTSTR

Pointeur vers une chaîne terminée par null avec le nom de la valeur. Cette valeur peut être NULL.

[in, out, optional] pdwType

Type : DWORD*

Pointeur vers un DWORD qui reçoit le type de données stockées dans la valeur récupérée. Lorsque vous utilisez des valeurs par défaut, l’entrée pdwType est le type de la valeur par défaut. Pour connaître les valeurs possibles, consultez Types de données du Registre. Si les informations de type ne sont pas requises, ce paramètre peut être NULL.

[out, optional] pvData

Type : void*

Pointeur vers une mémoire tampon qui reçoit les données de la valeur.

[in, out, optional] pcbData

Type : DWORD*

Pointeur vers une variable qui spécifie la taille, en octets, de la mémoire tampon pointée par pvData. Lorsque SHRegGetUSValue est retourné, pcbData contient la taille des données copiées dans pvData.

[in] fIgnoreHKCU

Type : BOOL

Variable qui spécifie la clé sous laquelle rechercher. Lorsqu’il est défini sur TRUE, SHRegGetUSValue ignore HKEY_CURRENT_USER et retourne la valeur de la clé sous HKEY_LOCAL_MACHINE.

[in, optional] pvDefaultData

Type : void*

Pointeur vers une mémoire tampon qui reçoit les données par défaut de la valeur.

[in] dwDefaultDataSize

Type : DWORD

Longueur, en octets, de la mémoire tampon pointée par pvDefaultData.

Valeur retournée

Type : LSTATUS

Retourne ERROR_SUCCESS en cas de réussite, ou un code d’erreur différent de zéro défini dans Winerror.h dans le cas contraire. Vous pouvez utiliser la fonction FormatMessage avec l’indicateur FORMAT_MESSAGE_FROM_SYSTEM pour récupérer une description générique de l’erreur.

Remarques

Lorsque fIgnoreHKCU a la valeur TRUE, SHRegGetUSValue retourne la valeur de la clé sous HKEY_LOCAL_MACHINE. Lorsque la valeur est FALSE, SHRegGetUSValue tente d’abord de retourner la valeur de la clé sous HKEY_CURRENT_USER. Toutefois, si la clé est introuvable sous HKEY_CURRENT_USER, la valeur est retournée à partir de la clé sous HKEY_LOCAL_MACHINE. Si aucune clé n’est présente ou si une erreur s’est produite et que dwDefaultDataSize est différent de zéro, les données par défaut sont copiées dans pvData et ERROR_SUCCESS retourne. ERROR_SUCCESS retourne à la fois pour les données par défaut et les données non par défaut, et il n’existe aucun moyen de distinguer quelle valeur copie dans pvData. Pour empêcher l’utilisation des données par défaut, définissez pvDefaultData surNULL et dwDefaultDataSize sur zéro.

Cette fonction ouvre la clé chaque fois qu’elle est utilisée. Si votre code implique l’obtention d’une série de valeurs à partir de la même clé, il est plus efficace d’ouvrir la clé une fois avec SHRegOpenUSKey , puis d’utiliser SHRegQueryUSValue pour récupérer les données.

Notes

L’en-tête shlwapi.h définit SHRegGetUSValue en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel, Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shlwapi.h
Bibliothèque	Shlwapi.lib
DLL	Shlwapi.dll (version 4.71 ou ultérieure)

Partager via