Функция 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, без лицензирования файлов. Этот флаг имеет значение, только если приложение предоставляет строку NULL для pwszLanguage.
MUI_USER_PREFERRED_UI_LANGUAGES	Извлекает из резервного списка только те файлы, которые реализуют языки. Последовательные вызовы перечисляют последовательные резервные варианты в соответствующем порядке. Первый файл, указанный выходным значением pcchFileMUIPath , должен быть наиболее подходящим. Этот флаг имеет значение, только если приложение предоставляет строку NULL для pwszLanguage.
MUI_USE_INSTALLED_LANGUAGES	Получите только файлы для языков, установленных на компьютере. Этот флаг имеет значение, только если приложение предоставляет строку NULL для pwszLanguage.

 

Следующие флаги позволяют пользователю указать тип файла, заданного 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

Указатель на строку с пустым завершением, указывающую путь к файлу. Путь к существующему LN-файлу или файлу, например .txt, INF или MSC-файлу. Если файл является файлом LN, функция ищет файлы, содержащие связанные ресурсы для конкретного языка. Для всех других типов файлов функция ищет файлы, которые точно соответствуют указанному имени файла и пути. Приложение может перезаписать поведение типа файла проверка с помощью флага MUI_LANG_NEUTRAL_PE_FILE или MUI_NON_LANG_NEUTRAL_FILE. Дополнительные сведения см. в разделе «Примечания».

Примечание Предоставленный путь к файлу может быть сетевым путем, например "\\имя_компьютера\c$\windows\system32\notepad.exe".

 

[in, out, optional] pwszLanguage

Указатель на буфер, содержащий строку языка. Во входных данных этот буфер содержит идентификатор языка или имя языка, для которого приложение должно находить файлы ресурсов для конкретного языка в зависимости от параметров dwFlags. При успешном возвращении из функции этот параметр содержит язык файла ресурсов для конкретного языка, найденного функцией.

Кроме того, приложение может присвоить этому параметру значение NULL, а значение, на которое ссылается pcchLanguage , равно 0. В этом случае функция извлекает требуемый размер буфера в pcchLanguage.

[in, out] pcchLanguage

Указатель на размер буфера в символах для строки языка, указанной pwszLanguage. Если приложение задает значение, на которое ссылается этот параметр, равное 0, и передает значение NULL для pwszLanguage, требуемый размер буфера будет возвращен в pcchLanguage , а возвращаемый размер буфера всегда LOCALE_NAME_MAX_LENGTH, так как функция обычно вызывается несколько раз подряд. Функция не может определить точный размер имени языка для всех последовательных вызовов и не может расширить буфер при последующих вызовах. Таким образом, LOCALE_NAME_MAX_LENGTH является единственным безопасным максимумом.

[out, optional] pwszFileMUIPath

Указатель на буфер, содержащий путь к файлу ресурсов для конкретного языка. Настоятельно рекомендуется выделить этот буфер для MAX_PATH размера.

Кроме того, этот параметр может получить значение NULL , если значение, на которое ссылается pcchFileMUIPath , равно 0. В этом случае функция извлекает необходимый размер буфера пути к файлам в pcchFileMUIPath.

[in, out] pcchFileMUIPath

Указатель на размер буфера в символах для пути к файлу, указанного pwszFileMUIPath. При успешном возвращении из функции этот параметр указывает размер полученного пути к файлу. Если приложение задает значение, на которое ссылается этот параметр, равное 0, функция получает значение NULL для pwszFileMUIPath, требуемый размер буфера будет возвращен в 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 каждое шестнадцатеричное значение в предоставленной строке языка должно представлять собой фактический идентификатор языка. В частности, нельзя указать значения, соответствующие следующим языковым параметрам:

• LOCALE_USER_DEFAULT
• LOCALE_SYSTEM_DEFAULT
• LOCALE_CUSTOM_DEFAULT
• LOCALE_CUSTOM_UI_DEFAULT
• LOCALE_CUSTOM_UNSPECIFIED

Чтобы получить перечисленную информацию, приложение должно вызывать эту функцию несколько раз, пока не вернет значение FALSE, оставляя содержимое pululEnumerator без изменений между вызовами. Так как каждый вызов извлекает путь к файлу ресурсов для разных языков, приложение должно очистить языковой буфер до пустой строки между вызовами. Если приложение не делает этого, входное значение pwszLanguage имеет приоритет над параметром dwFlags.

Обычно загрузчик ресурсов используется для поиска файлов ресурсов. Однако приложение также может использовать эту функцию для поиска файлов. Если входной путь к файлу предназначен для LN-файла, функция прикрепляет суффикс .mui при поиске соответствующих файлов ресурсов для конкретного языка.

Например, функция извлекает следующие файлы, когда приложение передает строку "C:\mydir\Example1.dll" в pcwszFilePath в качестве корневого пути к файлу, а 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 , не содержит данных конфигурации ресурсов или файл не существует, функция оставляет имя файла без изменения при поиске соответствующих файлов ресурсов для конкретного языка.

Например, приложение передает строку "C:\mydir\Example2.txt" в pcwszFilePath в качестве корневого пути к файлу с параметром dwFlags для MUI_LANGUAGE_NAME | MUI_USER_PREFERRED_UI_LANGUAGES. Рассмотрим ситуацию, когда пользовательскими языками пользовательского интерфейса (по порядку) являются каталанский, 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 нельзя использовать для получения пути к файлу ресурсов. Дополнительные сведения об использовании параллельных сборок с поддержкой многоязыкового пользовательского интерфейса см. в статье Использование сборок с поддержкой многоязыкового пользовательского интерфейса .

Подпись 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
Header	winnls.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll

См. также

GetThreadUILanguage

Многоязыковой интерфейс пользователя

Функции многоязыкового пользовательского интерфейса

SetThreadPreferredUILanguages

SetThreadUILanguage