GetThreadPreferredUILanguages, fonction (winnls.h)

Article
08/27/2023

Récupère les langues d’interface utilisateur préférées du thread actuel. Pour plus d’informations, consultez Gestion des langues de l’interface utilisateur.

Syntaxe

BOOL GetThreadPreferredUILanguages(
  [in]            DWORD   dwFlags,
  [out]           PULONG  pulNumLanguages,
  [out, optional] PZZWSTR pwszLanguagesBuffer,
  [in, out]       PULONG  pcchLanguagesBuffer
);

Paramètres

[in] dwFlags

Indicateurs identifiant le format de langue et le filtrage. Les indicateurs suivants spécifient le format de langue à utiliser pour les langues d’interface utilisateur préférées du thread. 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 .

Les indicateurs suivants spécifient le filtrage de la fonction à utiliser pour récupérer les langues d’interface utilisateur préférées des threads. L’indicateur par défaut est MUI_MERGE_USER_FALLBACK.

Valeur	Signification
MUI_MERGE_SYSTEM_FALLBACK	Utilisez le système de secours pour récupérer une liste qui correspond exactement à la liste de langues utilisée par le chargeur de ressources. Cet indicateur ne peut être utilisé qu’en combinaison avec MUI_MERGE_USER_FALLBACK. L’utilisation combinée des indicateurs modifie l’effet habituel de MUI_MERGE_USER_FALLBACK en incluant des langues neutres et de secours dans la liste.
MUI_MERGE_USER_FALLBACK	Récupérez une liste composite composée des langues d’interface utilisateur préférées des threads, suivie des langues d’interface utilisateur préférées du processus, puis de toutes les langues d’interface utilisateur préférées de l’utilisateur qui sont distinctes de celles-ci, suivie de la langue d’interface utilisateur par défaut du système, si elle ne figure pas déjà dans la liste. Si la liste des langues d’interface utilisateur préférées de l’utilisateur est vide, la fonction récupère les langues d’interface utilisateur préférées du système. Cet indicateur ne peut pas être combiné avec MUI_THREAD_LANGUAGES.
MUI_THREAD_LANGUAGES	Récupérez uniquement les langues d’interface utilisateur préférées du thread actuel ou une liste vide si aucune langue préférée n’est définie pour le thread actuel. Cet indicateur ne peut pas être combiné avec MUI_MERGE_USER_FALLBACK ou MUI_MERGE_SYSTEM_FALLBACK.
MUI_UI_FALLBACK	Récupérez une liste complète des langues d’interface utilisateur préférées des threads, ainsi que les langues neutres et de secours associées. L’utilisation de cet indicateur revient à combiner MUI_MERGE_SYSTEM_FALLBACK et MUI_MERGE_USER_FALLBACK. (Applicable uniquement pour Windows 7 et versions ultérieures).

[out] pulNumLanguages

Pointeur vers le nombre de langues récupérées dans pwszLanguagesBuffer.

[out, optional] pwszLanguagesBuffer

facultatif. Pointeur vers une mémoire tampon dans laquelle cette fonction récupère une liste ordonnée et délimitée par des langages d’interface utilisateur préférés de thread, au format spécifié par 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] pcchLanguagesBuffer

Pointeur vers la taille, en caractères, de la mémoire tampon de langue indiquée par pwszLanguagesBuffer. 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.

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 retourne l’un des 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.

Si la fonction échoue pour une autre raison, les paramètres pulNumLanguages et pcchLanguagesBuffer ne sont pas définis.

Remarques

Selon les indicateurs spécifiés par l’application, cette fonction peut récupérer une liste composite composée des langues d’interface utilisateur préférées des threads, du traitement des langues d’interface utilisateur préférées, des langues d’interface utilisateur préférées de l’utilisateur ou des langues d’interface utilisateur préférées du système, ainsi que de la langue d’interface utilisateur par défaut du système. Si elle rencontre une langue en double, la fonction récupère uniquement la première langue.

Si l’application a appelé SetThreadPreferredUILanguages avec l’indicateur MUI_CONSOLE_FILTER ou MUI_COMPLEX_SCRIPT_FILTER, GetThreadPreferredUILanguages filtre les langues dans la liste des résultats. La fonction remplace les langues que la console ne peut pas afficher par une langue de remplacement. La substitution d’une langue est déterminée à partir de la valeur de LOCALE_SCONSOLEFALLBACKNAME pour la langue. Pour plus d’informations sur la console, consultez la description de SetThreadUILanguage.

L’utilisation de MUI_LANGUAGE_NAME est recommandée par rapport à MUI_LANGUAGE_ID, car l’indicateur MUI_LANGUAGE_NAME peut mieux gérer les langues Module linguistique LIP (LIP) qui correspondent à des paramètres régionaux supplémentaires.

Lorsque MUI_LANGUAGE_ID est spécifié, les chaînes de langue récupérées sont des identificateurs de langue hexadécimaux

qui n’incluent pas le 0x de début et ont une longueur de 4 caractères. Par exemple, en-US sera retourné

as « 0409 » et en as « 0009 ».

Si l’application définit l’indicateur MUI_LANGUAGE_ID, les langues d’interface utilisateur préférées du thread peuvent inclure une ou plusieurs langues qui correspondent à des paramètres régionaux supplémentaires. En cas de retour réussi de la fonction, la mémoire tampon de langue contient « 1400 » pour toute langue correspondant à des paramètres régionaux supplémentaires. Il ne peut y avoir qu’une seule langue de ce type dans cette liste. La chaîne « 1400 » correspond à la valeur hexadécimale de LOCALE_CUSTOM_UI_DEFAULT. En cas également de retour réussi de la fonction, pwszLanguagesBuffer contient « 1000 » pour toute autre langue qui correspond à un paramètre régional supplémentaire. La chaîne « 1000 » correspond à la valeur hexadécimale de LOCALE_CUSTOM_UNSPECIFIED, qui n’est pas utile en tant qu’entrée d’une fonction, car elle ne peut pas faire la distinction entre les paramètres régionaux supplémentaires.

C# Signature

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean GetThreadPreferredUILanguages(
            System.UInt32 dwFlags,
            ref System.UInt32 pulNumLanguages,
            System.IntPtr pwszLanguagesBuffer,
            ref System.UInt32 pcchLanguagesBuffer
            );

Configuration requise


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