SHRegGetUSValueW, fonction (shlwapi.h)

Article
11/20/2024

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 SHRegGetUSValueW(
  [in]                LPCWSTR pszSubKey,
  [in, optional]      LPCWSTR 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 de 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 retourne, contient la taille des données copiées dans pvData.

[in] fIgnoreHKCU

Type : BOOL

Variable qui spécifie la clé à examiner. Quand la valeur est 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 de retour

Type : LSTATUS

Retourne ERROR_SUCCESS si elle réussit, ou un code d’erreur différent de zéro défini dans Winerror.h sinon. 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 est défini sur TRUE, SHRegGetUSValue retourne la valeur de la clé sous HKEY_LOCAL_MACHINE. Lorsque la valeur est FALSE, SHRegGetUSValue tente d’abord de renvoyer 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 dwDefaultDataSize n’est pas zéro, les données par défaut sont copiées dans pvData et ERROR_SUCCESS retourne. ERROR_SUCCESS retourne des données par défaut et non par défaut, et il n’existe aucun moyen de distinguer les valeurs à pvData. Pour empêcher l’utilisation des données par défaut, définissez pvDefaultData sur NULL et dwDefaultDataSize sur zéro.

Cette fonction ouvre la clé chaque fois qu’elle est utilisée. Si votre code implique d’obtenir 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.

Note

L’en-tête shlwapi.h définit SHRegGetUSValue comme 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. Le mélange 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel, Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	shlwapi.h
bibliothèque	Shlwapi.lib
DLL	Shlwapi.dll (version 4.71 ou ultérieure)

Partager via