GetFileMUIPath 함수(winnls.h)

아티클
08/27/2023

제공된 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 문자열을 제공하는 경우에만 관련이 있습니다.

다음 플래그를 사용하면 함수가 파일 이름에 ".mui"를 추가해야 하는지 여부를 확인할 수 있도록 pcwszFilePath 에 지정된 파일 형식을 나타낼 수 있습니다. 플래그는 상호 배타적입니다. 애플리케이션이 두 플래그를 모두 전달하면 함수가 실패합니다. 애플리케이션이 두 플래그를 모두 통과하지 않으면 함수는 루트 폴더의 파일을 검사하여 파일 형식을 확인하고 파일 이름을 결정합니다.

값	의미
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의 설정에 따라 애플리케이션에서 언어별 리소스 파일을 찾아야 하는 언어 식별자 또는 언어 이름이 포함됩니다. 함수에서 성공적으로 반환되면 이 매개 변수는 함수가 찾은 언어별 리소스 파일의 언어를 포함합니다.

또는 애플리케이션이 pcchLanguage에서 참조하는 값을 0으로 설정하여 이 매개 변수를 NULL로 설정할 수 있습니다. 이 경우 함수는 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자인 16진수 언어 식별자를 사용합니다.

예를 들어 en-US는 "0409"로, en은 "0009"로 전달되어야 합니다. 반환된 언어 문자열은

동일한 형식입니다.

MUI_LANGUAGE_ID 지정하면 제공된 언어 문자열의 각 16진수 값이 실제 언어 식별자를 나타내야 합니다. 특히 다음 로캘에 해당하는 값을 지정할 수 없습니다.

열거된 정보를 수신하려면 애플리케이션이 FALSE를 반환할 때까지 이 함수를 반복적으로 호출해야 하며, 호출 간에 pululEnumerator 의 내용은 변경되지 않습니다. 각 호출은 다른 언어별 리소스 파일의 경로를 검색하므로 애플리케이션은 호출 사이에 빈 문자열로 언어 버퍼를 지워야 합니다. 애플리케이션에서 이 작업을 수행하지 않으면 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"로 설정하여 열거형을 계속합니다.

대상 파일 및 관련 리소스 파일이 실제로 Side-by-side 사용 어셈블리인 경우 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 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll