GetLocaleInfoA, fonction (winnls.h)

Article
11/20/2024

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

Remarque Pour des raisons d’interopérabilité, l’application doit préférer la fonction GetLocaleInfoEx à GetLocaleInfo, car Microsoft migre vers l’utilisation de noms de paramètres régionaux au lieu des identificateurs de paramètres régionaux pour les nouveaux paramètres régionaux. Toute application qui s’exécute uniquement sur Windows Vista et versions ultérieures doit utiliser GetLocaleInfoEx.

Remarque Pour une compatibilité globale, l’application doit préférer les formulaires d’API Unicode « W » aux formulaires « A ». GetLocaleInfoA limite les données de caractères et peut entraîner des résultats qui apparaissent endommagés pour les utilisateurs, en particulier dans les applications globalement activées. Pour cette API, GetLocaleInfoEx est préférable, car il s’agit d’Unicode et prend également en charge les normes de noms de paramètres régionaux modernes.

Syntaxe

int GetLocaleInfoA(
  [in]            LCID   Locale,
  [in]            LCTYPE LCType,
  [out, optional] LPSTR  lpLCData,
  [in]            int    cchData
);

Paramètres

[in] Locale

identificateur de paramètres régionaux pour lequel récupérer des informations. Vous pouvez utiliser la macro MAKELCID pour créer un identificateur de paramètres régionaux ou utiliser l’une des valeurs prédéfinies suivantes.

[in] LCType

Informations de paramètres régionaux à récupérer. Pour obtenir des définitions détaillées, consultez le paramètre LCType de GetLocaleInfoEx.

Remarque Pour GetLocaleInfo, la valeur LOCALE_USE_CP_ACP est pertinente uniquement pour la version ANSI.

[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 a la valeur 0. Pour plus d’informations, consultez la section Remarques.

[in] cchData

Taille, dans les valeurs TCHAR, 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 de retour

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 différente de zéro. Si la fonction réussit, cchData n’est pas zéro et LOCALE_RETURN_NUMBER est spécifié, la valeur de retour est la taille de l’entier récupéré dans la mémoire tampon de données ; autrement dit, 2 pour la version Unicode de la fonction ou 4 pour la version ANSI. 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 de 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 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. L’une des valeurs de paramètre n’est pas valide.

Remarques

Pour l’opération de cette fonction, consultez Remarques pour GetLocaleInfoEx.

Remarque Même lorsque le paramètre LCType est spécifié comme LOCALE_FONTSIGNATURE, cchData et que le retour de la fonction est toujours le nombre TCHAR. Le nombre est différent pour les versions ANSI et Unicode de la fonction. Lorsqu’une application appelle la version générique de GetLocaleInfo avec LOCALE_FONTSIGNATURE, cchData peut être spécifié en toute sécurité en tant que sizeof(LOCALEIGNATURE) / sizeof(TCHAR).

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

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                    (LPTSTR)&value,
                    sizeof(value) / sizeof(TCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_FONTSIGNATURE,
                    (LPWSTR)&LocSig,
                    sizeof(LocSig) / sizeof(TCHAR) );

La chaîne ANSI récupérée par la version ANSI de cette fonction est traduite d’Unicode en ANSI en fonction de la page de codes ANSI par défaut pour l’identificateur de paramètres régionaux. Toutefois, si LOCALE_USE_CP_ACP est spécifié, la traduction est basée sur la page de codes ANSI par défaut du système.

Lorsque la version ANSI de cette fonction est utilisée avec un identificateur de paramètres régionaux Unicode uniquement, la fonction peut réussir, car le système d’exploitation utilise la page de codes système. Toutefois, les caractères qui ne sont pas définis dans la page de codes système apparaissent dans la chaîne sous forme de point d’interrogation ( ?).

Note

L’en-tête winnls.h définit GetLocaleInfo 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 [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	winnls.h (include Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll