Fungsi GetPrivateProfileSectionW (winbase.h)

Artikel
20/11/2024

Mengambil semua kunci dan nilai untuk bagian yang ditentukan dari file inisialisasi.

Catatan Fungsi ini disediakan hanya untuk kompatibilitas dengan aplikasi 16-bit yang ditulis untuk Windows. Aplikasi harus menyimpan informasi inisialisasi di registri.

Sintaksis

DWORD GetPrivateProfileSectionW(
  [in]  LPCWSTR lpAppName,
  [out] LPWSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCWSTR lpFileName
);

Parameter

[in] lpAppName

Nama bagian dalam file inisialisasi.

[out] lpReturnedString

Penunjuk ke buffer yang menerima pasangan nama kunci dan nilai yang terkait dengan bagian bernama. Buffer diisi dengan satu atau beberapa string null-terminated; string terakhir diikuti oleh karakter null kedua.

[in] nSize

Ukuran buffer yang diacu oleh parameter lpReturnedString, dalam karakter.

Catatan: Di versi Windows sebelumnya, ukuran bagian profil maksimum adalah 32.767 karakter. Windows 7 dan versi yang lebih baru tidak memiliki batasan ini.

[in] lpFileName

Nama file inisialisasi. Jika parameter ini tidak berisi jalur lengkap ke file, sistem akan mencari file di direktori Windows.

Mengembalikan nilai

Nilai pengembalian menentukan jumlah karakter yang disalin ke buffer, tidak termasuk karakter null yang mengakhiri. Jika buffer tidak cukup besar untuk berisi semua pasangan nama kunci dan nilai yang terkait dengan bagian bernama, nilai pengembalian sama dengan nSize dikurangi dua.

Komentar

Data dalam buffer yang ditunjukkan oleh parameter lpReturnedString terdiri dari satu atau beberapa string null-terminated, diikuti oleh karakter null akhir. Setiap string memiliki format berikut:

stringkunci

Fungsi GetPrivateProfileSection tidak peka huruf besar/kecil; string yang diarahkan oleh parameter lpAppName dapat berupa kombinasi huruf besar dan huruf kecil.

Operasi ini atom; tidak ada pembaruan pada file inisialisasi yang ditentukan yang diizinkan saat pasangan nama kunci dan nilai untuk bagian sedang disalin ke buffer yang ditujukkan oleh parameter lpReturnedString.

Sistem memetakan sebagian besar referensi file .ini 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 subkunjuk.
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 <Tanpa 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 <Tanpa Nama>) yang menentukan lokasi default di registri tempat Anda akan menemukan kunci untuk bagian tersebut.
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.

Komentar (baris apa pun yang dimulai dengan titik koma) dilucuti dan tidak dikembalikan dalam buffer lpReturnedString.

Catatan

Header winbase.h mendefinisikan GetPrivateProfileSection 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

GetPrivateProfileSectionNames

GetProfileSection

WritePrivateProfileSection

Bagikan melalui