Fonction SHRegGetValueW (shlwapi.h)

Article
03/04/2024

[SHRegGetValue peut être modifié ou indisponible dans les versions ultérieures du système d’exploitation ou du produit. Utilisez RegGetValue à sa place.]

Récupère une valeur de Registre.

Syntaxe

LSTATUS SHRegGetValueW(
  [in]      HKEY    hkey,
  [in]      LPCWSTR pszSubKey,
  [in]      LPCWSTR pszValue,
  [in]      SRRF    srrfFlags,
  [in, out] DWORD   *pdwType,
  [out]     void    *pvData,
  [in, out] DWORD   *pcbData
);

Paramètres

[in] hkey

Type : HKEY

Handle de la clé actuellement ouverte ou de l’une des valeurs prédéfinies suivantes.

HKEY_CLASSES_ROOT

HKEY_CURRENT_CONFIG

HKEY_CURRENT_USER

HKEY_LOCAL_MACHINE

HKEY_PERFORMANCE_DATA

HKEY_USERS

[in] pszSubKey

Type : LPCTSTR

Pointeur vers une chaîne terminée par null qui spécifie le chemin d’accès relatif de hkey à la sous-clé à partir de laquelle récupérer la valeur. Ce paramètre peut être NULL ou une chaîne vide, auquel cas les données sont récupérées à partir de l’emplacement hkey .

[in] pszValue

Type : LPCTSTR

Pointeur vers une chaîne terminée par null qui contient le nom de la valeur. Ce paramètre peut être NULL ou une chaîne vide, auquel cas les données sont récupérées à partir de la valeur Par défaut.

[in] srrfFlags

Type : SRRF

Un ou plusieurs des indicateurs SRRF qui limitent les données à récupérer. Au moins une valeur de restriction de type (SRRF_RT) doit être spécifiée.

[in, out] pdwType

Type : LPDWORD

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 l’indicateur SRRF_NOEXPAND n’est pas défini, REG_EXPAND_SZ types sont automatiquement développés et retournés en tant que REG_SZ. Si les informations de type ne sont pas requises, ce paramètre peut être NULL.

[out] pvData

Type : LPVOID

Pointeur vers une mémoire tampon qui reçoit les données de la valeur. Ce paramètre peut être NULL si les données ne sont pas nécessaires. Par exemple, si vous testiez uniquement l’existence d’une valeur, les données de valeur spécifiques seraient superflues.

[in, out] pcbData

Type : LPDWORD

Pointeur vers un DWORD qui, lors de l’entrée, contient la taille de la mémoire tampon de données de destination pvData, en octets. Cette valeur peut être NULL uniquement si pvData a la valeur NULL. À la sortie, pcbData pointe vers l’une de ces valeurs.

pvData	Valeur renvoyée	pcbData
NULL	ERROR_SUCCESS	Taille en octets suffisante pour contenir les données du Registre. Notez qu’il n’est pas garanti qu’il s’agit de la taille précise, mais seulement d’une taille suffisante.
Non NULL	ERROR_SUCCESS	Nombre exact d’octets écrits dans pvData.
Non NULL	ERROR_MORE_DATA	Taille en octets nécessaire pour contenir l’intégralité des données. Notez qu’il n’est pas garanti qu’il s’agit de la taille précise, mais seulement d’une taille suffisante.

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

SHRegGetValue fournit la vérification du type de données, la vérification du mode de démarrage, l’expansion automatique des données REG_EXPAND_SZ et l’arrêt null garanti des données REG_SZ, REG_EXPAND_SZ et REG_MULTI_SZ.

La clé identifiée par hkey doit avoir été ouverte avec KEY_QUERY_VALUE accès de sécurité. Si pszSubKey n’a pas la valeur NULL ou une chaîne vide, cette clé doit également pouvoir être ouverte avec KEY_QUERY_VALUE accès de sécurité dans le contexte d’appel actuel.

Si le type des données est REG_SZ, REG_EXPAND_SZ ou REG_MULTI_SZ, toutes les données retournées incluent ou prennent en compte l’arrêt null de la chaîne. Par exemple, si pvData n’a pas la valeur NULL, les données retournées dans cette mémoire tampon se terminent par une valeur Null. Si pcbData n’a pas la valeur NULL, la taille de la mémoire tampon vers laquelle il pointe inclut les octets requis pour contenir le caractère null de fin.

Sauf si l’indicateur SRRF_NOEXPAND est défini, les données de chaîne de type REG_EXPAND_SZ sont automatiquement développées avant d’être retournées. Le type de la chaîne développée est signalé dans pdwType en tant que REG_SZ, le paramètre pcbData pointe vers le nombre d’octets écrits pour la chaîne développée, et la mémoire tampon vers laquelle pointe pvData contient la version développée de la chaîne.

Notes sur les performances

Si pszSubKey n’a pas la valeur NULL ou une chaîne vide, cette clé est ouverte et fermée par cette fonction chaque fois qu’elle est accessible. Si votre application doit récupérer une série de valeurs à partir de la même sous-clé, vous obtiendrez de meilleures performances en ouvrant la clé à l’aide de RegOpenKeyEx avant d’appeler SHRegGetValue. Utilisez la clé retournée dans le paramètre phkResult de RegOpenKeyEx comme paramètre hkey dans cette fonction, avec pszSubKey défini sur NULL.

La possibilité d’un appel supplémentaire au Registre pour lire ou relire les données existe lorsque le type de données est REG_EXPAND_SZ et que l’indicateur SRRF_NOEXPAND n’a pas été défini. Les conditions suivantes entraînent cet appel supplémentaire.

pvData a la valeur NULL, pcbData n’est pas NULL. Bien que les données ne soient pas récupérées, le Registre doit être lu pour obtenir la chaîne et cette chaîne développée pour déterminer la taille requise de la mémoire tampon de données.
pvData n’est pas NULL, mais est trop petit pour contenir les données. Les données sont réus pour obtenir la chaîne complète, la chaîne est développée et la taille totale requise est déterminée.

Notes

L’en-tête shlwapi.h définit SHRegGetValue 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 XP avec SP2 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shlwapi.h
Bibliothèque	Shlwapi.lib
DLL	Shlwapi.dll (version 6.0 ou ultérieure)

Voir aussi

RegQueryValueEx

Partager via