Partager via

SHRegGetValueA, fonction (shlwapi.h)

  • Article

[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 SHRegGetValueA(
  [in]      HKEY   hkey,
  [in]      LPCSTR pszSubKey,
  [in]      LPCSTR pszValue,
  [in]      SRRF   srrfFlags,
  [in, out] DWORD  *pdwType,
  [out]     void   *pvData,
  [in, out] DWORD  *pcbData
);

Paramètres

[in] hkey

Type : HKEY

Handle vers la clé actuellement ouverte, ou 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 null-terminated qui spécifie le chemin relatif de clé hkey vers 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 null-terminated 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 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 de Registre. Si l’indicateur SRRF_NOEXPAND n’est pas défini, les types REG_EXPAND_SZ 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 est NULL. À la sortie, bpcData pointe vers l’une de ces valeurs.

pvData Valeur de retour bpcData
NULL ERROR_SUCCESS Taille en octets suffisantes pour contenir les données du Registre. Notez qu’il ne s’agit pas de la taille précise, mais seulement d’une taille suffisante.
NULL non ERROR_SUCCESS Nombre exact d’octets écrits dans pvData.
NULL non ERROR_MORE_DATA Taille en octets nécessaires pour contenir l’intégralité des données. Notez qu’il ne s’agit pas de la taille précise, mais seulement d’une taille suffisante.

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

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 les données null-arrêt de REG_SZ, REG_EXPAND_SZ et REG_MULTI_SZ données.

La clé identifiée par hkey doit avoir été ouverte avec KEY_QUERY_VALUE accès à la sécurité. Si pszSubKey n’est pas NULL ou une chaîne vide, cette clé doit également ê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 les null-arrêt de la chaîne. Par exemple, si pvData n’est pas NULL, les données retournées dans cette mémoire tampon sont -terminated. Si n’est pas NULL, la taille de la mémoire tampon qu’elle pointe pour inclure les octets requis pour contenir le caractère null.

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 pointe vers le nombre d’octets écrits pour la chaîne développée, et la mémoire tampon pointée par pvData contient la version développée de la chaîne.

Notes de performances

Si pszSubKey n’est pas 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 verrez 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.

Le risque 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 de SRRF_NOEXPAND n’a pas été défini. Les conditions suivantes entraînent cet appel supplémentaire.

  • pvData est NULL, 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 il est trop petit pour contenir les données. Les données sont réécrites pour obtenir la chaîne complète, la chaîne est développée et la taille totale requise est déterminée.

Note

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

Voir aussi

RegQueryValueEx