GetUILanguageInfo, fonction (winnls.h)

Article
08/27/2023

Récupère diverses informations sur une langue d’interface utilisateur installée :

La langue est-elle installée ?
L’utilisateur actuel est-il autorisé à utiliser la langue ?
La langue est-elle entièrement localisée ? Partiellement localisé ? Partie d’un pack d’installation linguistique (LIP) ?
S’il est partiellement localisé ou fait partie d’un LIP :
- Quel est son langage de secours ?
- Si cette langue de secours est une langue partiellement localisée, quelle est sa base ?
- Quelle est la langue de secours par défaut ?

Syntaxe

BOOL GetUILanguageInfo(
  [in]                DWORD    dwFlags,
  [in]                PCZZWSTR pwmszLanguage,
  [out, optional]     PZZWSTR  pwszFallbackLanguages,
  [in, out, optional] PDWORD   pcchFallbackLanguages,
  [out]               PDWORD   pAttributes
);

Paramètres

[in] dwFlags

Indicateurs définissant le format de la langue spécifiée. Les indicateurs s’excluent mutuellement et la valeur par défaut est MUI_LANGUAGE_NAME.

Valeur	Signification
MUI_LANGUAGE_ID	Récupérez les chaînes de langue au format d’identificateur de langue .
MUI_LANGUAGE_NAME	Récupérez les chaînes de langue au format de nom de langue .

[in] pwmszLanguage

Pointeur vers les langues pour lesquelles la fonction doit récupérer des informations. Ce paramètre indique une liste ordonnée et délimitée par des valeurs Null d’identificateurs de langue ou de noms de langue, en fonction du paramètre d’indicateur. Pour plus d’informations sur l’utilisation de ce paramètre, consultez la section Remarques.

[out, optional] pwszFallbackLanguages

Pointeur vers une mémoire tampon dans laquelle cette fonction récupère une liste ordonnée et délimitée par des valeurs Null de langues de secours, mise en forme comme défini par le paramètre dwFlags. Cette liste se termine par deux caractères Null.

Si ce paramètre est défini sur NULL et que pcchLanguagesBuffer a la valeur 0, la fonction récupère la taille requise de la mémoire tampon de langue dans pcchLanguagesBuffer. La taille requise inclut les deux caractères Null.

[in, out, optional] pcchFallbackLanguages

Pointeur vers la taille, en caractères, de la mémoire tampon de langue indiquée par pwszFallbackLanguages. En cas de retour réussi de la fonction, le paramètre contient la taille de la mémoire tampon de langue récupérée.

Si ce paramètre est défini sur 0 et que pwszLanguagesBuffer a la valeur NULL, la fonction récupère la taille requise de la mémoire tampon de langue dans pcchLanguagesBuffer.

[out] pAttributes

Pointeur vers des indicateurs indiquant les attributs de la liste des langues d’entrée. La fonction récupère toujours l’indicateur qui caractérise la dernière langue répertoriée.

Valeur	Signification
MUI_FULL_LANGUAGE	La langue est entièrement localisée.
MUI_PARTIAL_LANGUAGE	La langue est partiellement localisée.
MUI_LIP_LANGUAGE	La langue est une langue LIP.

En outre, pdwAttributes inclut l’un des indicateurs suivants, ou les deux, selon le cas.

Valeur	Signification
MUI_LANGUAGE_INSTALLED	La langue est installée sur cet ordinateur.
MUI_LANGUAGE_LICENSED	La langue est concédée sous licence pour l’utilisateur actuel.

Valeur retournée

Retourne TRUE en cas de réussite ou FALSE dans le cas contraire. Pour obtenir des informations d’erreur étendues, l’application peut appeler GetLastError, qui peut retourner les codes d’erreur suivants :

ERROR_INSUFFICIENT_BUFFER. Une taille de mémoire tampon fournie n’était pas suffisamment grande ou a été incorrectement définie sur NULL.
ERROR_INVALID_PARAMETER. L’une des valeurs de paramètre n’était pas valide. Pour plus d'informations, consultez la section Notes.
ERROR_OBJECT_NAME_NOT_FOUND. Le nom de l’objet spécifié est introuvable ou n’est pas valide, ou la première langue de la liste d’entrée n’est pas une langue installée. Pour plus d'informations, consultez la section Notes.

Si GetLastError retourne un autre code d’erreur, les paramètres pcchFallbackLanguages et pdwAttributes ne sont pas définis.

Remarques

MUI_LANGUAGE_NAME est recommandé sur MUI_LANGUAGE_ID, car elle permet à la fonction de mieux gérer les langues LIP qui ne correspondent pas à des paramètres régionaux prédéfinis, mais correspondent plutôt à des paramètres régionaux supplémentaires. Les langues LIP qui correspondent à des paramètres régionaux prédéfinis sont gérées comme les langues non LIP.

Si l’indicateur MUI_LANGUAGE_ID est spécifié, les chaînes de langue fournies doivent

utilisent des identificateurs de langue hexadécimale qui n’incluent pas le 0x de début et qui sont de 4 caractères.

Par exemple, en-US doit être passé comme « 0409 » et en comme « 0009 ». Les chaînes de langue retournées se trouveront dans le

même format.

Lorsque MUI_LANGUAGE_ID est spécifié, et s’il existe une telle langue dans la liste des langues d’interface utilisateur préférées de l’utilisateur, il ne peut y avoir qu’une seule langue de ce type dans la liste. Cette langue peut être spécifiée dans pwmszLanguage sous la forme « 1400 », ce qui correspond à la valeur hexadécimale de LOCALE_CUSTOM_UI_DEFAULT. Aucune autre langue de ce type ne peut être spécifiée à l’aide de MUI_LANGUAGE_ID. L’utilisation de « 1000 », qui correspond à la valeur hexadécimale de LOCALE_CUSTOM_UNSPECIFIED, dans la chaîne indiquée par pwmszLanguage génère un code ERROR_INVALID_PARAMETER.

Une langue partiellement localisée peut avoir une langue de secours partiellement localisée, nécessitant des appels répétés à GetUILanguageInfo pour obtenir des informations complètes. Prenons le cas d’une langue partiellement localisée Lang1 qui offre un choix de trois langues de secours. La langue de secours Lang3 est partiellement localisée et offre un choix de deux langues de secours. Les dépendances sont les suivantes, avec le secours par défaut répertorié en premier :

Lang1
- Lang2
- Lang3
  - Lang5
  - Lang6
- Lang4

Pour obtenir la ou les langues de secours de Lang1, l’application transmet pwmszLanguage en tant que « Lang1\0\0 ». Lors du retour de la fonction, pwszFallbackLanguages est défini sur « Lang2\0Lang3\0Lang4\0\0 ». Notez que le classement de cette liste indique que Lang2 est la langue de secours par défaut.

Pour obtenir la ou les langues de secours de Lang3 par rapport à Lang1, l’application transmet pwmszLanguage comme « lang1\0\lang3\0\0\0 ». Au retour de la fonction, pwszFallbackLanguages est défini sur « Lang5\0Lang6\0\0 ».

Cette fonction retourne ERROR_INVALID_PARAMETER pour l’un des éléments suivants :

pwmszLanguage a la valeur NULL ou vide.
Les MUI_LANGUAGE_ID et les MUI_LANGUAGE_NAME sont définis.
Tous les indicateurs autres que MUI_LANGUAGE_ID ou MUI_LANGUAGE_NAME sont définis.
pcchFallbackLanguages est supérieur à 0, mais pwszFallbackLanguages a la valeur NULL.
pwmszLanguage ne peut pas être analysé en tant que mémoire tampon à chaînes multiples d’identificateurs de langue ou de noms de langue, en fonction du paramètre d’indicateur.

Le code d’erreur ERROR_OBJECT_NAME_NOT_FOUND se produit si pwmszLanguage peut être analysé, mais n’est pas valide. Le code peut également être retourné pour un identificateur de paramètres régionaux non valide, ou si la première langue de la liste d’entrée n’est pas une langue installée, ou si une langue entièrement localisée a défini une langue de secours.

C# Signature

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean GetUILanguageInfo(
            System.UInt32 dwFlags,
            System.String pwmszLanguage,
            System.IntPtr pwszFallbackLanguages,
            ref System.UInt32 pcchFallbackLanguages,
            ref System.UInt32 pdwAttributes
            );

Configuration requise

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

Voir aussi

EnumUILanguages

GetFileMUIInfo

Interface utilisateur multilingue

Fonctions d’interface utilisateur multilingues