Bagikan melalui

Fungsi GetProfileStringW (winbase.h)

Mengambil string yang terkait dengan kunci di bagian yang ditentukan dari file Win.ini.

Catatan Fungsi ini disediakan hanya untuk kompatibilitas dengan aplikasi berbasis Windows 16-bit, oleh karena itu fungsi ini tidak boleh dipanggil dari kode server. Aplikasi harus menyimpan informasi inisialisasi di registri.
 

Sintaksis

DWORD GetProfileStringW(
  [in]  LPCWSTR lpAppName,
  [in]  LPCWSTR lpKeyName,
  [in]  LPCWSTR lpDefault,
  [out] LPWSTR  lpReturnedString,
  [in]  DWORD   nSize
);

Parameter

[in] lpAppName

Nama bagian yang berisi kunci. Jika parameter ini NULL, fungsi menyalin semua nama bagian dalam file ke buffer yang disediakan.

[in] lpKeyName

Nama kunci yang string terkaitnya akan diambil. Jika parameter ini null, fungsi menyalin semua kunci di bagian yang diberikan ke buffer yang disediakan. Setiap string diikuti oleh karakter null , dan string akhir diikuti oleh karakter null kedua.

[in] lpDefault

String default. Jika kunci lpKeyName tidak dapat ditemukan dalam file inisialisasi, GetProfileString menyalin string default ke buffer lpReturnedString. Jika parameter ini NULL, defaultnya adalah string kosong, "".

Hindari menentukan string default dengan karakter kosong berikutnya. Fungsi ini menyisipkan karakter null di buffer lpReturnedString untuk menghapus semua kosong berikutnya.

[out] lpReturnedString

Penunjuk ke buffer yang menerima string karakter.

[in] nSize

Ukuran buffer yang diacu oleh parameter lpReturnedString, dalam karakter.

Mengembalikan nilai

Nilai yang dikembalikan adalah jumlah karakter yang disalin ke buffer, tidak termasuk karakter null-mengakhiri.

Jika lpAppName atau lpKeyName null dan buffer tujuan yang disediakan terlalu kecil untuk menahan string yang diminta, string dipotong dan diikuti oleh karakter null , dan nilai pengembalian sama dengan nSize minus satu.

Jika lpAppName atau lpKeyName NULL dan buffer tujuan yang disediakan terlalu kecil untuk menahan semua string, string terakhir dipotong dan diikuti oleh dua karakter null. Dalam hal ini, nilai pengembalian sama dengan nSize minus dua.

Komentar

Jika string yang terkait dengan parameter lpKeyName diapit dalam tanda kutip tunggal atau ganda, tanda dibuang saat fungsi GetProfileString mengembalikan string.

Fungsi GetProfileString tidak peka huruf besar/kecil; string dapat berisi kombinasi huruf besar dan huruf kecil.

Bagian dalam file Win.ini harus memiliki formulir berikut:

[section]
key=string
      .
      .
      .

Aplikasi dapat menggunakan fungsi GetPrivateProfileString untuk mengambil string dari file inisialisasi tertentu.

Parameter lpDefault harus menunjuk ke string yang valid, bahkan jika string kosong (yaitu, bahkan jika karakter pertamanya adalah karakter null ).

Windows Server 2003 dan Windows XP/2000: Panggilan ke fungsi profil dapat dipetakan ke registri alih-alih ke file inisialisasi. Pemetaan ini terjadi ketika file dan bagian inisialisasi ditentukan dalam registri di bawah kunci berikut:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\IniFileMapping

Ketika operasi telah dipetakan, fungsi GetProfileString mengambil informasi dari registri, bukan dari file inisialisasi; perubahan lokasi penyimpanan tidak berpengaruh pada perilaku fungsi.

Fungsi profil menggunakan langkah-langkah berikut untuk menemukan informasi inisialisasi:

  1. Lihat di registri untuk nama file inisialisasi di bawah kunci IniFileMapping.
  2. Cari nama bagian yang ditentukan oleh lpAppName. Ini akan menjadi nilai bernama di bawah kunci yang memiliki nama file inisialisasi, atau subkunjuk dengan nama ini, atau nama tidak akan ada sebagai nilai atau subkunjuk.
  3. Jika nama bagian yang ditentukan oleh lpAppName adalah nilai bernama, maka nilai tersebut menentukan di mana dalam registri Anda akan menemukan kunci untuk bagian tersebut.
  4. Jika nama bagian yang ditentukan oleh lpAppName adalah subkunci, maka nilai bernama di bawah subkunci tersebut menentukan di mana dalam registri Anda akan menemukan kunci untuk bagian tersebut. Jika kunci yang Anda cari tidak ada sebagai nilai bernama, maka akan ada nilai yang tidak disebutkan namanya (ditampilkan sebagai <Tanpa Nama>) yang menentukan lokasi default di registri tempat Anda akan menemukan kunci.
  5. Jika nama bagian yang ditentukan oleh lpAppName tidak ada sebagai nilai bernama atau sebagai subkey, maka akan ada nilai yang tidak disebutkan namanya (ditampilkan sebagai <Tanpa Nama>) yang menentukan lokasi default di registri tempat Anda akan menemukan kunci untuk bagian tersebut.
  6. Jika tidak ada subkuntang atau entri untuk nama bagian, maka cari file inisialisasi aktual pada disk dan baca kontennya.
Saat melihat nilai dalam registri yang menentukan lokasi registri lain, ada beberapa awalan yang mengubah perilaku pemetaan file .ini:
  • ! - karakter ini memaksa semua penulisan untuk masuk ke registri dan ke file .ini pada disk.
  • # - karakter ini menyebabkan nilai registri diatur ke nilai dalam file .ini Windows 3.1 saat pengguna baru masuk untuk pertama kalinya setelah penyiapan.
  • @ - karakter ini mencegah pembacaan masuk ke file .ini pada disk jika data yang diminta tidak ditemukan di registri.
  • USR: - awalan ini adalah singkatan dari HKEY_CURRENT_USER, dan teks setelah awalan relatif terhadap kunci tersebut.
  • SYS: - awalan ini adalah singkatan dari HKEY_LOCAL_MACHINE\SOFTWARE, dan teks setelah awalan relatif terhadap kunci tersebut.

Nota

Header winbase.h mendefinisikan GetProfileString sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Syarat Nilai
klien minimum yang didukung Windows 2000 Professional [hanya aplikasi desktop]
server minimum yang didukung Windows 2000 Server [hanya aplikasi desktop]
Platform Target Windows
Header winbase.h (termasuk Windows.h)
Pustaka Kernel32.lib
DLL Kernel32.dll

Lihat juga

GetPrivateProfileString

WriteProfileString