Fungsi WritePrivateProfileStructA (winbase.h)

Artikel
08/27/2023

Menyalin data ke dalam kunci di bagian yang ditentukan dari file inisialisasi. Saat menyalin data, fungsi menghitung checksum dan menambahkannya ke akhir data. Fungsi GetPrivateProfileStruct menggunakan checksum untuk memastikan integritas data.

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

Sintaks

BOOL WritePrivateProfileStructA(
  [in] LPCSTR lpszSection,
  [in] LPCSTR lpszKey,
  [in] LPVOID lpStruct,
  [in] UINT   uSizeStruct,
  [in] LPCSTR szFile
);

Parameter

[in] lpszSection

Nama bagian tempat string akan disalin. Jika bagian tidak ada, bagian tersebut dibuat. Nama bagian independen huruf besar/kecil, string dapat berupa kombinasi huruf besar dan huruf kecil.

[in] lpszKey

Nama kunci yang akan dikaitkan dengan string. Jika kunci tidak ada di bagian yang ditentukan, kunci akan dibuat. Jika parameter ini ADALAH NULL, seluruh bagian, termasuk semua kunci dan entri di dalam bagian tersebut, akan dihapus.

[in] lpStruct

Data yang akan disalin. Jika parameter ini NULL, kunci akan dihapus.

[in] uSizeStruct

Ukuran buffer yang diacu oleh parameter lpStruct , dalam byte.

[in] szFile

Nama file inisialisasi. Jika parameter ini NULL, informasi disalin ke dalam file Win.ini.

Jika file dibuat menggunakan karakter Unicode, fungsi menulis karakter Unicode ke file. Jika tidak, fungsi menulis karakter ANSI.

Mengembalikan nilai

Jika fungsi berhasil menyalin string ke file inisialisasi, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, atau jika menghapus versi cache dari file inisialisasi yang terakhir diakses, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Bagian dalam file inisialisasi harus memiliki formulir berikut:

[section]
key=string
      .
      .
      .

Jika parameter szFile tidak berisi jalur lengkap dan nama file untuk file, WritePrivateProfileString mencari direktori Windows untuk file tersebut. Jika file tidak ada, fungsi ini membuat file di direktori Windows.

Jika szFile berisi jalur lengkap dan nama file dan file tidak ada, WriteProfileString akan membuat file. Direktori yang ditentukan harus sudah ada.

Sistem menyimpan versi cache dari pemetaan file registri terbaru untuk meningkatkan performa. Jika semua parameter NULL, fungsi akan menghapus cache. Saat sistem mengedit versi file yang di-cache, proses yang mengedit file itu sendiri akan menggunakan file asli sampai cache telah dibersihkan.

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 hal ini, fungsi menulis informasi ke registri, bukan ke 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 subkunjud dengan nama ini, atau nama tidak akan ada sebagai nilai atau subkunjud.
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 subkunjud, 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.

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 dariHKEY_LOCAL_MACHINE\SOFTWARE, dan teks setelah awalan relatif terhadap kunci tersebut.

Catatan

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

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

Lihat juga

GetPrivateProfileString

WriteProfileString