GetLocaleInfoEx, fonction (winnls.h)

Article
03/21/2023
4 minutes de lecture

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

Note L’application doit appeler cette fonction en préférence pour GetLocaleInfo s’il est conçu pour s’exécuter uniquement sur Windows Vista et versions ultérieures.

Note Cette fonction peut récupérer des données qui changent entre les versions, 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 obtenir les valeurs possibles, consultez la section « Constantes utilisées dans le paramètre LCType de GetLocaleInfo, GetLocaleInfoEx et SetLocaleInfo » dans les constantes d’informations locales. Notez qu’une seule partie des informations de paramètres régionaux peut être spécifiée 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 en tant que nombre au lieu d’une chaîne. La mémoire tampon qui reçoit la valeur doit être au moins la longueur d’une valeur DWORD, qui est 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 actuel de l’utilisateur, les données peuvent différer de l’ordinateur à l’ordinateur, et les paramètres régionaux personnalisés peuvent modifier les données. Par exemple, même les noms de mois ou de jour sont soumis à des 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ées. 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 des paramètres régionaux en cas de réussite et cchData est une valeur non nulle. Si la fonction réussit, cchData n’est pas zéro et LOCALE_RETURN_NUMBER est spécifiée, la valeur de retour est la taille de l’entier récupéré dans la mémoire tampon de données, autrement dit, 2. Si la fonction réussit et que la valeur de cchData est 0, la valeur de retour est la taille requise, en caractères incluant un caractère null, pour la mémoire tampon de données des paramètres régionaux.

La fonction retourne 0 s’il 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 suffisamment grande, ou elle était incorrectement définie sur NULL.
ERROR_INVALID_FLAGS. Les valeurs fournies pour les indicateurs n’étaient pas valides.
ERROR_INVALID_PARAMETER. Toutes les valeurs de paramètre n’ont pas été valides.

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 des 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 en tant qu’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 locales. L’application doit fournir une mémoire tampon de données d’au moins sizeof(LOCALIGNATURE) octets. Lors du 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é comme 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(LOCALEIGNATURE) / sizeof(WCHAR).

Les exemples suivants traitent correctement la taille de la mémoire tampon pour les valeurs non textuelles :

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. Les données ne sont pas garanties d’être identiques de l’ordinateur à l’ordinateur 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 montrant 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


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 (include Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll