getFileMUIPath 函式 (winnls.h)

發行項
03/04/2024

擷取與所提供 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。

傳回值

如果成功或 FALSE，則傳回 TRUE 。否則傳回 TRUE 。如果函式失敗，輸出參數不會變更。

若要取得擴充錯誤資訊，應用程式可以呼叫 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)
程式庫	Kernel32.lib
DLL	Kernel32.dll