Fungsi GetPrivateProfileString (winbase.h)
Mengambil string dari bagian yang ditentukan dalam file inisialisasi.
Sintaks
DWORD GetPrivateProfileString(
[in] LPCTSTR lpAppName,
[in] LPCTSTR lpKeyName,
[in] LPCTSTR lpDefault,
[out] LPTSTR lpReturnedString,
[in] DWORD nSize,
[in] LPCTSTR lpFileName
);
Parameter
[in] lpAppName
Nama bagian yang berisi nama kunci. Jika parameter ini NULL, fungsi GetPrivateProfileString menyalin semua nama bagian dalam file ke buffer yang disediakan.
[in] lpKeyName
Nama kunci yang string terkaitnya akan diambil. Jika parameter ini NULL, semua nama kunci di bagian yang ditentukan oleh parameter lpAppName disalin ke buffer yang ditentukan oleh parameter lpReturnedString .
[in] lpDefault
String default. Jika kunci lpKeyName tidak dapat ditemukan dalam file inisialisasi, GetPrivateProfileString 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 dalam buffer lpReturnedString untuk menghapus kosong berikutnya.
[out] lpReturnedString
Penunjuk ke buffer yang menerima string yang diambil.
[in] nSize
Ukuran buffer yang ditujukkan oleh parameter lpReturnedString , dalam karakter.
[in] lpFileName
Nama file inisialisasi. Jika parameter ini tidak berisi jalur lengkap ke file, sistem akan mencari file di direktori Windows.
Nilai kembali
Nilai yang dikembalikan adalah jumlah karakter yang disalin ke buffer, tidak termasuk karakter null yang mengakhiri.
Jika lpAppName maupun lpKeyName bukan NULL dan buffer tujuan yang disediakan terlalu kecil untuk menahan string yang diminta, string dipotong dan diikuti oleh karakter null , dan nilai yang dikembalikan sama dengan nSize minus satu.
Jika lpAppName atau lpKeyNameNULL dan buffer tujuan yang disediakan terlalu kecil untuk menahan semua string, string terakhir dipotong dan diikuti oleh dua karakter null . Dalam hal ini, nilai yang dikembalikan sama dengan nSize dikurangi dua.
Jika file inisialisasi yang ditentukan oleh lpFileName tidak ditemukan, atau berisi nilai yang tidak valid, memanggil GetLastError akan mengembalikan '0x2' (File Tidak Ditemukan). Untuk mengambil informasi kesalahan yang diperluas, panggil GetLastError.
Keterangan
Fungsi GetPrivateProfileString mencari file inisialisasi yang ditentukan untuk kunci yang cocok dengan nama yang ditentukan oleh parameter lpKeyName di bawah judul bagian yang ditentukan oleh parameter lpAppName . Jika menemukan kunci, fungsi menyalin string yang sesuai ke buffer. Jika kunci tidak ada, fungsi menyalin string karakter default yang ditentukan oleh parameter lpDefault . Bagian dalam file inisialisasi harus memiliki formulir berikut:
[section]
key=string
.
.
.
Jika lpAppNameADALAH NULL, GetPrivateProfileString menyalin semua nama bagian dalam file yang ditentukan ke buffer yang disediakan. Jika lpKeyNameNULL, fungsi menyalin semua nama kunci di bagian yang ditentukan ke buffer yang disediakan. Aplikasi dapat menggunakan metode ini untuk menghitung semua bagian dan kunci dalam file. Dalam kedua kasus, setiap string diikuti oleh karakter null dan string akhir diikuti oleh karakter null kedua. Jika buffer tujuan yang disediakan terlalu kecil untuk menahan semua string, string terakhir dipotong dan diikuti oleh dua karakter null .
Jika string yang terkait dengan lpKeyName diapit dalam tanda kutip tunggal atau ganda, tanda akan dibuang saat fungsi GetPrivateProfileString mengambil string.
Fungsi GetPrivateProfileString tidak peka huruf besar/kecil; string dapat berupa kombinasi huruf besar dan huruf kecil.
Untuk mengambil string dari file Win.ini, gunakan fungsi GetProfileString .
Sistem memetakan sebagian besar .ini referensi file ke registri, menggunakan pemetaan yang ditentukan di bawah kunci registri berikut:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\IniFileMapping
Pemetaan ini kemungkinan jika aplikasi memodifikasi file inisialisasi komponen sistem, seperti Control.ini, System.ini, dan Winfile.ini. Dalam kasus ini, fungsi 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:
- Lihat di registri untuk nama file inisialisasi di bawah kunci IniFileMapping .
- 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 subkun tangan.
- 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.
- 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 <Tidak Ada Nama>) yang menentukan lokasi default di registri tempat Anda akan menemukan kunci.
- 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 <Tidak Ada Nama>) yang menentukan lokasi default di registri tempat Anda akan menemukan kunci untuk bagian tersebut.
- Jika tidak ada subkuntang atau entri untuk nama bagian, cari file inisialisasi aktual pada disk dan baca kontennya.
- ! - 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 dariHKEY_LOCAL_MACHINE\SOFTWARE, dan teks setelah awalan relatif terhadap kunci tersebut.
Contoh
Contoh berikut menunjukkan penggunaan GetPrivateProfileString.
// Gets a profile string called "Preferred line" and converts it to an int.
GetPrivateProfileString (
"Preference",
"Preferred Line",
gszNULL,
szBuffer,
MAXBUFSIZE,
gszINIfilename
);
// if szBuffer is not empty.
if ( lstrcmp ( gszNULL, szBuffer ) )
{
dwPreferredPLID = (DWORD) atoi( szBuffer );
}
else
{
dwPreferredPLID = (DWORD) -1;
}
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | winbase.h (termasuk Windows.h) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |