getFileMUIPath 函数 (winnls.h)

  • 项目

检索与提供的 LN 文件关联的所有特定于语言的资源文件的路径。 应用程序必须重复调用此函数才能获取每个资源文件的路径。

语法

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
);

参数

[in] dwFlags

标识语言格式和筛选的标志。 以下标志指定 pwszLanguage 指示的语言的格式。 标志互斥，默认值为MUI_LANGUAGE_NAME。

值 含义
MUI_LANGUAGE_ID
 检索语言 标识符格式的语言 字符串。
MUI_LANGUAGE_NAME
 检索语言 名称格式的语言 字符串。
 

如果 pwszLanguage 设置为 NULL，则以下标志指定用于查找特定于语言的资源文件的函数的筛选。 筛选标志互斥，默认值为MUI_USER_PREFERRED_UI_LANGUAGES。

值 含义
MUI_USE_SEARCH_ALL_LANGUAGES
 检索 pcwszFilePath 指示的路径的所有特定于语言的资源文件，而无需考虑文件许可。 仅当应用程序为 pwszLanguage 提供 null 字符串时，此标志才相关。
MUI_USER_PREFERRED_UI_LANGUAGES
 仅检索在回退列表中实现语言的文件。 连续调用按适当的顺序枚举连续回退。 pcchFileMUIPath 的输出值指示的第一个文件应最适合。 仅当应用程序为 pwszLanguage 提供 null 字符串时，此标志才相关。
MUI_USE_INSTALLED_LANGUAGES
 仅检索计算机上安装的语言的文件。 仅当应用程序为 pwszLanguage 提供 null 字符串时，此标志才相关。
 

以下标志允许用户指示 由 pcwszFilePath 指定的文件类型，以便函数可以确定是否必须向文件名添加“.mui”。 标志是互斥的。 如果应用程序同时传递这两个标志，则函数将失败。 如果应用程序未传递这两个标志，函数会检查根文件夹中的文件，以验证文件类型并决定文件命名。

值 含义
MUI_LANG_NEUTRAL_PE_FILE
 在处理之前，请勿验证 在 pcwszFilePath 中传递的文件，并将“.mui”追加到文件名。 例如，将 Abc.exe 更改为 Abc.exe.mui。
MUI_NON_LANG_NEUTRAL_FILE
 在处理之前，请勿验证 在 pcwszFilePath 中传递的文件，也不要将“.mui”追加到文件名。 例如，使用 Abc.txt 或 Abc.chm。

[in] pcwszFilePath

指向指定文件路径的以 null 结尾的字符串的指针。 路径适用于现有 LN 文件或文件（如 .txt、.inf 或 .msc 文件）。 如果文件是 LN 文件，则函数会查找包含特定于语言的关联资源的文件。 对于所有其他类型的文件，函数将查找与所指示的文件名和路径完全对应的文件。 应用程序可以使用 MUI_LANG_NEUTRAL_PE_FILE 或 MUI_NON_LANG_NEUTRAL_FILE 标志覆盖文件类型检查的行为。 有关详细信息，请参见“备注”部分。

注意 提供的文件路径可以是网络路径：例如“\\machinename\c$\windows\system32\notepad.exe”。
 

[in, out, optional] pwszLanguage

指向包含语言字符串的缓冲区的指针。 输入时，此缓冲区包含应用程序应查找特定于语言的资源文件的语言标识符或语言名称，具体取决于 dwFlags 的设置。 从 函数成功返回后，此参数包含函数找到的语言特定资源文件的语言。

或者，应用程序可以将此参数设置为 NULL，并将 pcchLanguage 引用的值设置为 0。 在这种情况下，函数在 pcchLanguage 中检索所需的缓冲区大小。

[in, out] pcchLanguage

指向 pwszLanguage 指示的语言字符串的缓冲区大小的指针（以字符为单位）。 如果应用程序将此参数引用的值设置为 0，并为 pwszLanguage 传递 NULL，则所需的缓冲区大小将以 pcchLanguage 返回，并且返回的缓冲区大小始终LOCALE_NAME_MAX_LENGTH，因为函数通常连续调用多次。 函数无法确定所有后续调用的语言名称的确切大小，并且无法在后续调用中扩展缓冲区。 因此，LOCALE_NAME_MAX_LENGTH是唯一安全的最大值。

[out, optional] pwszFileMUIPath

指向包含特定于语言的资源文件路径的缓冲区的指针。 强烈建议将此缓冲区分配为大小MAX_PATH。

或者，如果 pcchFileMUIPath 引用的值设置为 0，则此参数可以检索 NULL。 在这种情况下，函数检索 pcchFileMUIPath 中文件路径缓冲区的所需大小。

[in, out] pcchFileMUIPath

指向 pwszFileMUIPath 指示的文件路径的缓冲区大小的指针（以字符为单位）。 从 函数成功返回后，此参数指示检索到的文件路径的大小。 如果应用程序将此参数引用的值设置为 0，则函数检索 pwszFileMUIPath 的 NULL，则所需的缓冲区大小将在 pcchFileMUIPath 中返回，并且返回的缓冲区大小始终MAX_PATH，因为函数通常连续调用多次。 函数无法确定所有连续调用的路径的确切大小，并且无法在后续调用中扩展缓冲区。 因此，MAX_PATH是唯一安全的最大值。

[in, out] pululEnumerator

指向枚举变量的指针。 首次调用此函数时，变量的值应为 0。 在后续调用之间，应用程序不应更改此参数的值。 函数检索所有可能的特定于语言的资源文件路径后，返回 FALSE。

返回值

如果成功，则返回 TRUE ，否则返回 FALSE 。 如果函数失败，则输出参数不会更改。

若要获取扩展错误信息，应用程序可以调用 GetLastError，这会返回以下错误代码：

  • ERROR_INSUFFICIENT_BUFFER。 提供的缓冲区大小不够大，或者错误地设置为 NULL。
  • ERROR_NO_MORE_FILES。 没有更多要处理的文件。

注解

此函数验证是否存在特定于语言的资源文件，但不验证它们是否正确。 它要求根据 应用程序部署中所述的存储约定存储资源文件。

如果对此函数的调用指定MUI_LANGUAGE_ID标志，则提供的语言字符串必须

使用不包含前导 0x 且长度为 4 个字符的十六进制语言标识符。

例如，en-US 应传递为“0409”，将 en 传递为“0009”。 返回的语言字符串将位于

相同的格式。

指定MUI_LANGUAGE_ID时，提供的语言字符串中的每个十六进制值都必须表示实际的语言标识符。 具体而言，无法指定与以下区域设置对应的值：

若要接收枚举信息，应用程序应重复调用此函数，直到返回 FALSE，使 pulEnumerator 的内容在调用之间保持不变。 由于每次调用都会检索不同语言特定资源文件的路径，应用程序必须在调用之间将语言缓冲区清除为空字符串。 如果应用程序不执行此操作， 则 pwszLanguage 的输入值优先于 dwFlags 的设置。

通常，资源加载程序用于查找资源文件。 但是，应用程序还可以使用此函数来查找文件。 如果输入文件路径适用于 LN 文件，则函数在查找相应的特定于语言的资源文件时会附加后缀“.mui”。

例如，当应用程序将 pcwszFilePath 中的字符串“C:\mydir\Example1.dll”作为根文件路径传递时，函数将检索以下文件，并将 dwFlags 设置为 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
首次调用函数会将 pwszFileMUIPath 设置为“C:\mydir\en-US\Example1.dll.mui”。 第二个调用将文件路径设置为“C:\mydir\ja-JP\Example1.dll.mui”。 第三次调用时，函数返回 FALSE，GetLastError 返回ERROR_NO_MORE_FILES。

如果 pcwszFilePath 指示的文件没有资源配置数据，或者该文件不存在，则在查找相应的特定于语言的资源文件时，函数将保留文件名。

例如，应用程序将 pcwszFilePath 中的字符串“C:\mydir\Example2.txt”作为根文件路径传递， 并将 dwFlags 设置为 MUI_LANGUAGE_NAME |MUI_USER_PREFERRED_UI_LANGUAGES。 假设用户首选 UI 语言 (，) 为加泰罗尼亚语、“ca-ES”和西班牙语 (西班牙) 、“es-ES”以及存在以下文件的位置：

  • (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
对 函数的第一次调用确定没有用于“ca-ES”或非特定语言“ca”的资源。 然后，该函数会尝试下一个选项“es-ES”，并成功为其查找匹配项。 在返回之前，函数将 pwszFileMUIPath 设置为“C:\mydir\es-ES\Example2.txt”。 对函数的第二个应用程序调用通过将 pwszFileMUIPath 设置为“C:\mydir\es\Example2.txt”来继续枚举。

如果目标文件及其关联的资源文件实际上是 并行启用的程序集，则 GetFileMUIPath 不能用于检索资源文件的路径。 有关如何使用具有 MUI 支持的并行程序集的详细信息，请参阅将 程序集与多语言用户界面 配合使用。

C# 签名

[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
            );

要求

要求 值
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 winnls.h (包括 Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

GetThreadUILanguage

多语言用户界面

多语言用户界面函数

SetThreadPreferredUILanguages

SetThreadUILanguage