GetLocaleInfoEx, fonction (winnls.h)

Article
08/27/2023

Récupère des informations sur les paramètres régionaux spécifiés par nom.

Note L’application doit appeler cette fonction de préférence à GetLocaleInfo si elle est conçue pour s’exécuter uniquement sur Windows Vista et versions ultérieures.

Note Cette fonction peut récupérer des données qui changent d’une version à l’autre, par exemple en raison d’un paramètre régional personnalisé. Si votre application doit conserver ou transmettre des données, consultez Utilisation des données de paramètres régionaux persistants.

Syntaxe

int GetLocaleInfoEx(
  [in, optional]  LPCWSTR lpLocaleName,
  [in]            LCTYPE  LCType,
  [out, optional] LPWSTR  lpLCData,
  [in]            int     cchData
);

Paramètres

[in, optional] lpLocaleName

Pointeur vers un nom de paramètres régionaux ou l’une des valeurs prédéfinies suivantes.

[in] LCType

Informations de paramètres régionaux à récupérer. Pour connaître les valeurs possibles, consultez la section « Constantes utilisées dans le paramètre LCType de GetLocaleInfo, GetLocaleInfoEx et SetLocaleInfo » dans Constantes d’informations locales. Notez qu’un seul élément d’informations de paramètres régionaux peut être spécifié par appel.

L’application peut utiliser l’opérateur OR binaire pour combiner LOCALE_RETURN_NUMBER avec n’importe quelle autre constante autorisée. Dans ce cas, la fonction récupère la valeur sous forme de nombre au lieu d’une chaîne. La mémoire tampon qui reçoit la valeur doit avoir au moins la longueur d’une valeur DWORD, soit 2.

Attention Il est également possible de combiner LOCALE_NOUSEROVERRIDE avec n’importe quelle autre constante. Toutefois, l’utilisation de cette constante est fortement déconseillée. (Même sans utiliser le remplacement de l’utilisateur actuel, les données peuvent différer d’un ordinateur à l’autre, et les paramètres régionaux personnalisés peuvent modifier les données. Par exemple, même les noms de mois ou de jours font l’objet de réformes orthographiques.)

Si LCType est défini sur LOCALE_IOPTIONALCALENDAR, la fonction récupère uniquement le premier calendrier de remplacement.

Note Pour obtenir tous les autres calendriers, l’application doit utiliser EnumCalendarInfoEx.

À compter de Windows Vista, vos applications ne doivent pas utiliser LOCALE_ILANGUAGE dans le paramètre LCType pour éviter l’échec ou la récupération de données inattendues. Au lieu de cela, il est recommandé pour vos applications d’appeler GetLocaleInfoEx.

[out, optional] lpLCData

Pointeur vers une mémoire tampon dans laquelle cette fonction récupère les informations de paramètres régionaux demandés. Ce pointeur n’est pas utilisé si cchData est défini sur 0.

[in] cchData

Taille, en caractères, de la mémoire tampon de données indiquée par lpLCData. L’application peut également définir ce paramètre sur 0. Dans ce cas, la fonction n’utilise pas le paramètre lpLCData et retourne la taille de mémoire tampon requise, y compris le caractère null de fin.

Valeur retournée

Retourne le nombre de caractères récupérés dans la mémoire tampon de données de paramètres régionaux si la valeur est réussie et si cchData est une valeur différente de zéro. Si la fonction réussit, cchData est différent de zéro et LOCALE_RETURN_NUMBER est spécifié, la valeur de retour correspond à la taille de l’entier récupéré dans la mémoire tampon de données, c’est-à-dire 2. Si la fonction réussit et que la valeur de cchData est 0, la valeur renvoyée correspond à la taille requise, en caractères y compris un caractère null, pour la mémoire tampon de données des paramètres régionaux.

La fonction retourne 0 si elle ne réussit pas. Pour obtenir des informations d’erreur étendues, l’application peut appeler GetLastError, qui peut retourner l’un des codes d’erreur suivants :

ERROR_INSUFFICIENT_BUFFER. Une taille de mémoire tampon fournie n’était pas assez grande ou elle a été incorrectement définie sur NULL.
ERROR_INVALID_FLAGS. Les valeurs fournies pour les indicateurs n’étaient pas valides.
ERROR_INVALID_PARAMETER. L’une des valeurs de paramètre n’était pas valide.

Remarques

Cette fonction récupère normalement des informations au format texte. Si les informations sont une valeur numérique et que la valeur de LCType est LOCALE_ILANGUAGE ou LOCALE_IDEFAULTLANGUAGE, cette fonction récupère les chaînes contenant des nombres hexadécimaux. Sinon, le texte récupéré pour les informations numériques est un nombre décimal.

Il existe deux exceptions à cette règle. Tout d’abord, l’application peut récupérer des valeurs numériques sous forme d’entiers en spécifiant LOCALE_RETURN_NUMBER dans le paramètre LCType . La deuxième exception est que LOCALE_FONTSIGNATURE se comporte différemment de toutes les autres constantes d’informations de paramètres régionaux. L’application doit fournir une mémoire tampon de données d’au moins taille d’octets (LOCALESIGNATURE). Une fois le retour réussi de la fonction, la mémoire tampon est remplie en tant que structure LOCALEIGNATURE .

Note Même lorsque le paramètre LCType est spécifié en tant que LOCALE_FONTSIGNATURE, cchData et le retour de la fonction sont toujours des nombres de caractères. Lorsqu’une application appelle GetLocaleInfoEx avec LCType spécifié comme LOCALE_FONTSIGNATURE, cchData peut être spécifié en toute sécurité en tant que sizeof(LOCALESIGNATURE) / sizeof(WCHAR).

Les exemples suivants traitent correctement la taille de la mémoire tampon pour les valeurs autres que le texte :

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                      (LPWSTR)&value,
                      sizeof(value) / sizeof(WCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_FONTSIGNATURE,
                      (LPWSTR)&LocSig,
                      sizeof(LocSig) / sizeof(WCHAR) );

Cette fonction peut récupérer des données à partir de paramètres régionaux personnalisés. Il n’est pas garanti que les données soient identiques d’un ordinateur à l’autre ou entre les exécutions d’une application. Si votre application doit conserver ou transmettre des données, consultez Utilisation des données de paramètres régionaux persistants.

À compter de Windows 8 : si votre application transmet des balises de langue à cette fonction à partir de l’espace de noms Windows.Globalization, elle doit d’abord convertir les balises en appelant ResolveLocaleName.

Exemples

Vous trouverez des exemples illustrant l’utilisation de cette fonction dans NLS : Exemple d’API basées sur le nom et NLS : Exemple d’atténuation IDN (Internationalized Domain Name).

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winnls.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll