Fungsi GetFileMUIPath (winnls.h)

Artikel
03/08/2023

Mengambil jalur ke semua file sumber daya khusus bahasa yang terkait dengan file LN yang disediakan. Aplikasi harus memanggil fungsi ini berulang kali untuk mendapatkan jalur untuk setiap file sumber daya.

Sintaks

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

Parameter

[in] dwFlags

Bendera yang mengidentifikasi format dan pemfilteran bahasa. Bendera berikut menentukan format bahasa yang ditunjukkan oleh pwszLanguage. Bendera saling eksklusif, dan defaultnya adalah MUI_LANGUAGE_NAME.

Nilai	Makna
MUI_LANGUAGE_ID	Ambil string bahasa dalam format pengidentifikasi bahasa .
MUI_LANGUAGE_NAME	Ambil string bahasa dalam format nama bahasa .

Bendera berikut menentukan pemfilteran untuk fungsi yang akan digunakan dalam menemukan file sumber daya khusus bahasa jika pwszLanguage diatur ke NULL. Bendera pemfilteran saling eksklusif, dan defaultnya adalah MUI_USER_PREFERRED_UI_LANGUAGES.

Nilai	Makna
MUI_USE_SEARCH_ALL_LANGUAGES	Ambil semua file sumber daya khusus bahasa untuk jalur yang ditunjukkan oleh pcwszFilePath, tanpa mempertimbangkan lisensi file. Bendera ini hanya relevan jika aplikasi memasok string null untuk pwszLanguage.
MUI_USER_PREFERRED_UI_LANGUAGES	Ambil hanya file yang mengimplementasikan bahasa dalam daftar fallback. Panggilan berturut-turut menghitung fallback berturut-turut, dalam urutan yang sesuai. File pertama yang ditunjukkan oleh nilai output pcchFileMUIPath harus paling cocok. Bendera ini hanya relevan jika aplikasi memasok string null untuk pwszLanguage.
MUI_USE_INSTALLED_LANGUAGES	Ambil hanya file untuk bahasa yang terinstal di komputer. Bendera ini hanya relevan jika aplikasi memasok string null untuk pwszLanguage.

Bendera berikut memungkinkan pengguna untuk menunjukkan jenis file yang ditentukan oleh pcwszFilePath sehingga fungsi dapat menentukan apakah harus menambahkan ".mui" ke nama file. Bendera saling eksklusif. Jika aplikasi melewati kedua bendera, fungsi gagal. Jika aplikasi tidak meneruskan bendera, fungsi memeriksa file di folder akar untuk memverifikasi jenis file dan memutuskan penamaan file.

Nilai	Makna
MUI_LANG_NEUTRAL_PE_FILE	Jangan verifikasi file yang diteruskan di pcwszFilePath dan tambahkan ".mui" ke nama file sebelum diproses. Misalnya, ubah Abc.exe menjadi Abc.exe.mui.
MUI_NON_LANG_NEUTRAL_FILE	Jangan verifikasi file yang diteruskan di pcwszFilePath dan jangan tambahkan ".mui" ke nama file sebelum diproses. Misalnya, gunakan Abc.txt atau Abc.chm.

[in] pcwszFilePath

Penunjuk ke string yang dihentikan null yang menentukan jalur file. Jalur ini adalah untuk file LN yang ada atau untuk file seperti file .txt, .inf, atau .msc. Jika file adalah file LN, fungsi mencari file yang berisi sumber daya khusus bahasa terkait. Untuk semua jenis file lainnya, fungsi mencari file yang sesuai persis dengan nama file dan jalur yang ditunjukkan. Aplikasi Anda dapat menimpa perilaku pemeriksaan jenis file dengan menggunakan bendera MUI_LANG_NEUTRAL_PE_FILE atau MUI_NON_LANG_NEUTRAL_FILE. Untuk informasi lebih lanjut, lihat bagian Keterangan.

Catatan Jalur file yang disediakan dapat berupa jalur jaringan: misalnya, "\\machinename\c$\windows\system32\notepad.exe".

[in, out, optional] pwszLanguage

Penunjuk ke buffer yang berisi string bahasa. Pada input, buffer ini berisi pengidentifikasi bahasa atau nama bahasa yang aplikasinya harus menemukan file sumber daya khusus bahasa, tergantung pada pengaturan dwFlags. Setelah berhasil dikembalikan dari fungsi, parameter ini berisi bahasa file sumber daya khusus bahasa yang telah ditemukan fungsi.

Atau, aplikasi dapat mengatur parameter ini ke NULL, dengan nilai yang dirujuk oleh pcchLanguage diatur ke 0. Dalam hal ini, fungsi mengambil ukuran buffer yang diperlukan di pcchLanguage.

[in, out] pcchLanguage

Penunjuk ke ukuran buffer, dalam karakter, untuk string bahasa yang ditunjukkan oleh pwszLanguage. Jika aplikasi menetapkan nilai yang direferensikan oleh parameter ini ke 0 dan meneruskan NULL untuk pwszLanguage, maka ukuran buffer yang diperlukan akan dikembalikan dalam pcchLanguage dan ukuran buffer yang dikembalikan selalu LOCALE_NAME_MAX_LENGTH, karena fungsi biasanya disebut beberapa kali berturut-turut. Fungsi tidak dapat menentukan ukuran nama bahasa yang tepat untuk semua panggilan berturut-turut, dan tidak dapat memperluas buffer pada panggilan berikutnya. Dengan demikian LOCALE_NAME_MAX_LENGTH adalah satu-satunya maksimum yang aman.

[out, optional] pwszFileMUIPath

Penunjuk ke buffer yang berisi jalur ke file sumber daya khusus bahasa. Sangat disarankan untuk mengalokasikan buffer ini untuk berukuran MAX_PATH.

Atau, parameter ini dapat mengambil NULL jika nilai yang dirujuk oleh pcchFileMUIPath diatur ke 0. Dalam hal ini, fungsi mengambil ukuran yang diperlukan untuk buffer jalur file di pcchFileMUIPath.

[in, out] pcchFileMUIPath

Penunjuk ke ukuran buffer, dalam karakter, untuk jalur file yang ditunjukkan oleh pwszFileMUIPath. Setelah berhasil dikembalikan dari fungsi, parameter ini menunjukkan ukuran jalur file yang diambil. Jika aplikasi menetapkan nilai yang direferensikan oleh parameter ini ke 0, fungsi mengambil NULL untuk pwszFileMUIPath, ukuran buffer yang diperlukan akan dikembalikan dalam pcchFileMUIPath dan ukuran buffer yang dikembalikan selalu MAX_PATH, karena fungsi biasanya disebut beberapa kali berturut-turut. Fungsi tidak dapat menentukan ukuran jalur yang tepat untuk semua panggilan berturut-turut, dan tidak dapat memperluas buffer pada panggilan berikutnya. Dengan demikian MAX_PATH adalah satu-satunya maksimum yang aman.

[in, out] pululEnumerator

Arahkan ke variabel enumerasi. Pertama kali fungsi ini dipanggil, nilai variabel harus 0. Di antara panggilan berikutnya, aplikasi tidak boleh mengubah nilai parameter ini. Setelah fungsi mengambil semua kemungkinan jalur file sumber daya khusus bahasa, fungsi mengembalikan FALSE.

Mengembalikan nilai

Mengembalikan TRUE jika berhasil atau FALSE sebaliknya. Jika fungsi gagal, parameter output tidak berubah.

Untuk mendapatkan informasi kesalahan yang diperluas, aplikasi dapat memanggil GetLastError, yang dapat mengembalikan kode kesalahan berikut:

ERROR_INSUFFICIENT_BUFFER. Ukuran buffer yang disediakan tidak cukup besar, atau salah diatur ke NULL.
ERROR_NO_MORE_FILES. Tidak ada lagi file untuk diproses.

Keterangan

Fungsi ini memverifikasi bahwa file sumber daya khusus bahasa ada, tetapi tidak memverifikasi bahwa file tersebut benar. Ini mengharuskan file sumber daya disimpan sesuai dengan konvensi penyimpanan yang dijelaskan dalam Penyebaran Aplikasi.

Jika panggilan ke fungsi ini menentukan bendera MUI_LANGUAGE_ID, string bahasa yang disediakan harus

gunakan pengidentifikasi bahasa heksadesimal yang tidak menyertakan 0x di depannya, dan panjangnya 4 karakter.

Misalnya, en-US harus diteruskan sebagai "0409" dan en sebagai "0009". String bahasa yang dikembalikan akan berada di

format yang sama.

Ketika MUI_LANGUAGE_ID ditentukan, setiap nilai heksadesimal dalam string bahasa yang disediakan harus mewakili pengidentifikasi bahasa aktual. Secara khusus, nilai yang terkait dengan lokal berikut ini tidak dapat ditentukan:

Untuk menerima informasi yang dijumlahkan, aplikasi harus memanggil fungsi ini berulang kali sampai mengembalikan FALSE, membiarkan konten pululEnumerator tidak berubah di antara panggilan. Karena setiap panggilan mengambil jalur ke file sumber daya khusus bahasa yang berbeda, aplikasi harus menghapus buffer bahasa ke string kosong di antara panggilan. Jika aplikasi tidak melakukan ini, nilai input pwszLanguage lebih diutamakan daripada pengaturan dwFlags.

Biasanya pemuat sumber daya digunakan untuk menemukan file sumber daya. Namun, aplikasi Anda juga dapat menggunakan fungsi ini untuk menemukan file. Jika jalur file input adalah untuk file LN, fungsi melampirkan akhiran ".mui" saat mencari file sumber daya khusus bahasa yang sesuai.

Misalnya, fungsi mengambil file berikut ketika aplikasi meneruskan string "C:\mydir\Example1.dll" di pcwszFilePath sebagai jalur file akar, dengan dwFlags diatur ke 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

Panggilan pertama ke fungsi mengatur pwszFileMUIPath ke "C:\mydir\en-US\Example1.dll.mui". Panggilan kedua mengatur jalur file ke "C:\mydir\ja-JP\Example1.dll.mui". Fungsi mengembalikan FALSE saat dipanggil untuk ketiga kalinya dan GetLastError mengembalikan ERROR_NO_MORE_FILES.

Jika file yang ditunjukkan oleh pcwszFilePath tidak memiliki data konfigurasi sumber daya, atau jika file tidak ada, fungsi meninggalkan nama file seperti saat mencari file sumber daya khusus bahasa yang sesuai.

Misalnya, aplikasi meneruskan string "C:\mydir\Example2.txt" di pcwszFilePath sebagai jalur file akar, dengan dwFlags diatur ke MUI_LANGUAGE_NAME | MUI_USER_PREFERRED_UI_LANGUAGES. Mari kita pertimbangkan kasus di mana bahasa UI pilihan pengguna (berurutan) adalah Katalan, "ca-ES", dan Spanyol (Spanyol), "es-ES", dan di mana file berikut ada:

(tidak ada file yang sesuai di 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

Panggilan pertama ke fungsi menentukan bahwa tidak ada sumber daya untuk "ca-ES" atau untuk bahasa netral "ca". Fungsi kemudian mencoba opsi berikutnya, "es-ES", yang berhasil menemukan kecocokan. Sebelum kembali, fungsi mengatur pwszFileMUIPath ke "C:\mydir\es-ES\Example2.txt". Panggilan aplikasi kedua ke fungsi melanjutkan enumerasi dengan mengatur pwszFileMUIPath ke "C:\mydir\es\Example2.txt".

Jika file target dan file sumber daya terkait sebenarnya rakitan yang diaktifkan berdampingan, GetFileMUIPath tidak dapat digunakan untuk mengambil jalur ke file sumber daya. Silakan merujuk ke Menggunakan Rakitan dengan Antarmuka Pengguna Multibahasa untuk detail tentang cara menggunakan rakitan berdampingan dengan dukungan MUI.

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

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	winnls.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll