GetFileMUIPath, fonction (winnls.h)

Article
03/09/2024

Récupère le chemin d’accès à tous les fichiers de ressources propres à la langue associés au fichier LN fourni. L’application doit appeler cette fonction à plusieurs reprises pour obtenir le chemin d’accès de chaque fichier de ressources.

Syntaxe

BOOL GetFileMUIPath(
  [in]                DWORD      dwFlags,
  [in]                PCWSTR     pcwszFilePath,
  [in, out, optional] PWSTR      pwszLanguage,
  [in, out]           PULONG     pcchLanguage,
  [out, optional]     PWSTR      pwszFileMUIPath,
  [in, out]           PULONG     pcchFileMUIPath,
  [in, out]           PULONGLONG pululEnumerator
);

Paramètres

[in] dwFlags

Indicateurs identifiant le format de langue et le filtrage. Les indicateurs suivants spécifient le format de la langue indiquée par pwszLanguage. Les indicateurs s’excluent mutuellement et la valeur par défaut est MUI_LANGUAGE_NAME.

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

Les indicateurs suivants spécifient le filtrage de la fonction à utiliser pour localiser des fichiers de ressources spécifiques à la langue si pwszLanguage a la valeur NULL. Les indicateurs de filtrage s’excluent mutuellement, et la valeur par défaut est MUI_USER_PREFERRED_UI_LANGUAGES.

Valeur	Signification
MUI_USE_SEARCH_ALL_LANGUAGES	Récupérez tous les fichiers de ressources propres à la langue pour le chemin indiqué par pcwszFilePath, sans prendre en compte la gestion des licences de fichiers. Cet indicateur est pertinent uniquement si l’application fournit une chaîne null pour pwszLanguage.
MUI_USER_PREFERRED_UI_LANGUAGES	Récupérez uniquement les fichiers qui implémentent les langues dans la liste de secours. Les appels successifs énumèrent les secours successifs, dans l’ordre approprié. Le premier fichier indiqué par la valeur de sortie de pcchFileMUIPath doit être le mieux adapté. Cet indicateur est pertinent uniquement si l’application fournit une chaîne null pour pwszLanguage.
MUI_USE_INSTALLED_LANGUAGES	Récupérez uniquement les fichiers pour les langues installées sur l’ordinateur. Cet indicateur est pertinent uniquement si l’application fournit une chaîne null pour pwszLanguage.

Les indicateurs suivants permettent à l’utilisateur d’indiquer le type de fichier spécifié par pcwszFilePath afin que la fonction puisse déterminer si elle doit ajouter « .mui » au nom de fichier. Les indicateurs s’excluent mutuellement. Si l’application passe les deux indicateurs, la fonction échoue. Si l’application ne transmet aucun indicateur, la fonction vérifie le fichier dans le dossier racine pour vérifier le type de fichier et décider du nommage des fichiers.

Valeur	Signification
MUI_LANG_NEUTRAL_PE_FILE	Ne vérifiez pas le fichier transmis dans pcwszFilePath et ajoutez « .mui » au nom de fichier avant le traitement. Par exemple, remplacez Abc.exe par Abc.exe.mui.
MUI_NON_LANG_NEUTRAL_FILE	Ne vérifiez pas le fichier transmis dans pcwszFilePath et n’ajoutez pas « .mui » au nom de fichier avant le traitement. Par exemple, utilisez Abc.txt ou Abc.chm.

[in] pcwszFilePath

Pointeur vers une chaîne terminée par null spécifiant un chemin d’accès de fichier. Le chemin d’accès est soit pour un fichier LN existant, soit pour un fichier tel qu’un fichier .txt, .inf ou .msc. Si le fichier est un fichier LN, la fonction recherche les fichiers contenant les ressources propres à la langue associées. Pour tous les autres types de fichiers, la fonction recherche des fichiers qui correspondent exactement au nom de fichier et au chemin d’accès indiqués. Votre application peut remplacer le comportement du type de fichier case activée à l’aide de l’indicateur MUI_LANG_NEUTRAL_PE_FILE ou MUI_NON_LANG_NEUTRAL_FILE. Pour plus d'informations, consultez la section Notes.

Note Le chemin d’accès au fichier fourni peut être un chemin d’accès réseau : par exemple, « \\nom_machine\c$\windows\system32\notepad.exe ».

[in, out, optional] pwszLanguage

Pointeur vers une mémoire tampon contenant une chaîne de langue. Lors de l’entrée, cette mémoire tampon contient l’identificateur de langue ou le nom de langue pour lequel l’application doit trouver des fichiers de ressources spécifiques à la langue, en fonction des paramètres de dwFlags. En cas de retour réussi de la fonction, ce paramètre contient la langue du fichier de ressources spécifique à la langue que la fonction a trouvé.

L’application peut également définir ce paramètre sur NULL, avec la valeur référencée par pcchLanguage définie sur 0. Dans ce cas, la fonction récupère la taille de mémoire tampon requise dans pcchLanguage.

[in, out] pcchLanguage

Pointeur vers la taille de la mémoire tampon, en caractères, pour la chaîne de langue indiquée par pwszLanguage. Si l’application définit la valeur référencée par ce paramètre sur 0 et passe NULL pour pwszLanguage, la taille de mémoire tampon requise est retournée dans pcchLanguage et la taille de mémoire tampon retournée est toujours LOCALE_NAME_MAX_LENGTH, car la fonction est généralement appelée plusieurs fois de suite. La fonction ne peut pas déterminer la taille exacte du nom de langue pour tous les appels successifs et ne peut pas étendre la mémoire tampon sur les appels suivants. Par conséquent, LOCALE_NAME_MAX_LENGTH est le seul maximum sûr.

[out, optional] pwszFileMUIPath

Pointeur vers une mémoire tampon contenant le chemin d’accès au fichier de ressources spécifique à la langue. Il est fortement recommandé d’allouer cette mémoire tampon pour qu’elle soit de taille MAX_PATH.

Ce paramètre peut également récupérer null si la valeur référencée par pcchFileMUIPath est définie sur 0. Dans ce cas, la fonction récupère la taille requise pour la mémoire tampon du chemin de fichier dans pcchFileMUIPath.

[in, out] pcchFileMUIPath

Pointeur vers la taille de la mémoire tampon, en caractères, pour le chemin d’accès au fichier indiqué par pwszFileMUIPath. En cas de retour réussi de la fonction, ce paramètre indique la taille du chemin d’accès du fichier récupéré. Si l’application définit la valeur référencée par ce paramètre sur 0, la fonction récupère NULL pour pwszFileMUIPath, la taille de mémoire tampon requise est retournée dans pcchFileMUIPath et la taille de mémoire tampon retournée est toujours MAX_PATH, car la fonction est généralement appelée plusieurs fois de suite. La fonction ne peut pas déterminer la taille exacte du chemin d’accès pour tous les appels successifs et ne peut pas étendre la mémoire tampon lors des appels suivants. Ainsi, MAX_PATH est le seul maximum sécurisé.

[in, out] pululEnumerator

Pointeur vers une variable d’énumération. La première fois que cette fonction est appelée, la valeur de la variable doit être 0. Entre les appels suivants, l’application ne doit pas modifier la valeur de ce paramètre. Une fois que la fonction a récupéré tous les chemins possibles de fichier de ressources spécifiques à la langue, elle retourne FALSE.

Valeur retournée

Retourne TRUE en cas de réussite ou FALSE dans le cas contraire. Si la fonction échoue, les paramètres de sortie ne changent pas.

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_NO_MORE_FILES. Il n’y avait plus de dossiers à traiter.

Remarques

Cette fonction vérifie que les fichiers de ressources spécifiques à la langue existent, mais ne vérifie pas qu’ils sont corrects. Il nécessite que les fichiers de ressources soient stockés conformément à la convention de stockage expliquée dans Déploiement d’applications.

Si l’appel à cette fonction spécifie l’indicateur MUI_LANGUAGE_ID, la chaîne de langue fournie doit

utiliser un identificateur de langue hexadécimal qui n’inclut pas le 0x de début et qui est de 4 caractères.

Par exemple, en-US doit être passé comme « 0409 » et en comme « 0009 ». La chaîne de langue retournée se trouve dans le

même format.

Lorsque MUI_LANGUAGE_ID est spécifié, chaque valeur hexadécimale dans la chaîne de langue fournie doit représenter un identificateur de langue réel. En particulier, les valeurs correspondant aux paramètres régionaux suivants ne peuvent pas être spécifiées :

Pour recevoir des informations énumérées, l’application doit appeler cette fonction à plusieurs reprises jusqu’à ce qu’elle retourne FALSE, en laissant le contenu de pululEnumerator inchangé entre les appels. Étant donné que chaque appel récupère le chemin d’accès à un fichier de ressources spécifique à une langue différente, l’application doit effacer la mémoire tampon de langue dans une chaîne vide entre les appels. Si l’application ne le fait pas, la valeur d’entrée de pwszLanguage est prioritaire sur le paramètre de dwFlags.

En règle générale, le chargeur de ressources est utilisé pour rechercher des fichiers de ressources. Toutefois, votre application peut également utiliser cette fonction pour rechercher les fichiers. Si le chemin d’accès au fichier d’entrée concerne un fichier LN, la fonction joint un suffixe .mui » lors de la recherche des fichiers de ressources spécifiques au langage correspondants.

Par exemple, la fonction récupère les fichiers suivants lorsque l’application transmet la chaîne « C:\mydir\Example1.dll » dans pcwszFilePath comme chemin du fichier racine, avec dwFlags défini sur MUI_LANGUAGE_NAME | MUI_USE_SEARCH_ALL_LANGUAGES :

C:\mydir\Example1.dll
- C:\mydir\en-US\Example1.dll.mui
- C:\mydir\ja-JP\Example1.dll.mui

Le premier appel à la fonction définit pwszFileMUIPath sur « C:\mydir\en-US\Example1.dll.mui ». Le deuxième appel définit le chemin du fichier sur « C:\mydir\ja-JP\Example1.dll.mui ». La fonction retourne FALSE lorsqu’elle est appelée une troisième fois et GetLastError retourne ERROR_NO_MORE_FILES.

Si le fichier indiqué par pcwszFilePath n’a pas de données de configuration des ressources, ou si le fichier n’existe pas, la fonction laisse le nom du fichier tel qu’il est lors de la recherche des fichiers de ressources spécifiques à la langue correspondants.

Par exemple, l’application transmet la chaîne « C:\mydir\Example2.txt » dans pcwszFilePath comme chemin de fichier racine, avec dwFlags défini sur MUI_LANGUAGE_NAME | MUI_USER_PREFERRED_UI_LANGUAGES. Examinons le cas dans lequel les langues d’interface utilisateur préférées de l’utilisateur (dans l’ordre) sont le catalan, « ca-ES » et l’espagnol (Espagne), « es-ES », et où les fichiers suivants existent :

(aucun fichier correspondant dans C :\mydir)
- C:\mydir\en-US\Example2.txt
- C:\mydir\en\Example2.txt
- C:\mydir\es-ES\Example2.txt
- C:\mydir\es\Example2.txt
- C:\mydir\ja-JP\Example2.txt

Le premier appel à la fonction détermine qu’il n’existe aucune ressource pour « ca-ES » ou pour le langage neutre « ca ». La fonction tente ensuite l’option suivante, « es-ES », pour laquelle elle réussit à trouver une correspondance. Avant de retourner, la fonction définit pwszFileMUIPath sur « C:\mydir\es-ES\Example2.txt ». Un deuxième appel d’application à la fonction poursuit l’énumération en définissant pwszFileMUIPath sur « C:\mydir\es\Example2.txt ».

Si le fichier cible et ses fichiers de ressources associés sont en fait des assemblys activés côte à côte, GetFileMUIPath ne peut pas être utilisé pour récupérer le chemin d’accès au fichier de ressources. Consultez Utilisation d’assemblys avec une interface utilisateur multilingue pour plus d’informations sur l’utilisation des assemblys côte à côte avec la prise en charge de l’interface utilisateur unique.

C# Signature

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean GetFileMUIPath(
            System.UInt32 dwFlags,
            System.String pcwszFilePath,
            System.Text.StringBuilder pwszLanguage,
            ref System.UInt32 pcchLanguage,
            System.Text.StringBuilder pwszFileMUIPath,
            ref System.UInt32 pcchFileMUIPath,
            ref System.UInt64 pululEnumerator
            );

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