Fungsi WritePrivateProfileStringA (winbase.h)
Menyalin string ke bagian yang ditentukan dari file inisialisasi.
Sintaks
BOOL WritePrivateProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpString,
[in] LPCSTR lpFileName
);
Parameter
[in] lpAppName
Nama bagian tempat string akan disalin. Jika bagian tidak ada, bagian tersebut dibuat. Nama bagian ini tidak bergantung pada huruf besar/kecil; string dapat berupa kombinasi huruf besar dan huruf kecil.
[in] lpKeyName
Nama kunci yang akan dikaitkan dengan string. Jika kunci tidak ada di bagian yang ditentukan, kunci akan dibuat. Jika parameter ini NULL, seluruh bagian, termasuk semua entri dalam bagian , akan dihapus.
[in] lpString
String yang dihentikan null untuk ditulis ke file. Jika parameter ini ADALAH NULL, kunci yang ditujukkan oleh parameter lpKeyName akan dihapus.
[in] lpFileName
Nama file inisialisasi.
Jika file dibuat menggunakan karakter Unicode, fungsi menulis karakter Unicode ke file. Jika tidak, fungsi menulis karakter ANSI.
Nilai kembali
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 lpFileName 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 lpFileName berisi jalur lengkap dan nama file dan file tidak ada, WritePrivateProfileString 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.
- ! - 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.
- Pastikan bahwa tidak ada file .ini dari nama yang ditentukan pada sistem.
- Pastikan bahwa ada entri kunci dalam registri yang menentukan file .ini. Entri ini harus berada di bawah jalur HKEY_LOCAL_MACHINE\SOFTWARE \Microsoft\Windows NT\CurrentVersion\IniFileMapping.
- Tentukan nilai untuk entri kunci file .ini yang menentukan bagian. Artinya, aplikasi harus menentukan nama bagian, seperti yang akan muncul dalam file .ini atau entri registri. Berikut adalah contoh: [Bagian Saya].
- Untuk file sistem, tentukan SYS untuk nilai tambah.
- Untuk file aplikasi, tentukan USR dalam nilai tambah. Berikut adalah contoh: "Bagian Saya: USR: Nama Aplikasi\Bagian". Dan, karena USR menunjukkan pemetaan di bawah HKEY_CURRENT_USER, aplikasi juga harus membuat kunci di bawah HKEY_CURRENT_USER yang menentukan nama aplikasi yang tercantum dalam nilai tambah. Untuk contoh yang baru saja diberikan, itu akan menjadi "Nama Aplikasi".
- Setelah mengikuti langkah-langkah sebelumnya, program penyiapan aplikasi harus memanggil WritePrivateProfileString dengan tiga parameter pertama diatur ke NULL, dan parameter keempat diatur ke nama file INI. Contohnya:
WritePrivateProfileString( NULL, NULL, NULL, L"appname.ini" ); - Panggilan seperti itu menyebabkan pemetaan file .ini ke registri berlaku sebelum reboot sistem berikutnya. Sistem dibaca ulang informasi pemetaan ke dalam memori bersama. Pengguna tidak perlu me-reboot komputer mereka setelah menginstal aplikasi untuk meminta pemanggilan aplikasi di masa mendatang melihat pemetaan file .ini ke registri.
Contoh
Contoh kode berikut mengilustrasikan panduan sebelumnya dan didasarkan pada beberapa asumsi:
- Ada aplikasi bernama Nama Aplikasi.
- Aplikasi tersebut menggunakan file .ini bernama AppName.ini.
- Ada bagian dalam file .ini yang ingin kita lihat seperti ini:
[Section1] FirstKey = It all worked out okay. SecondKey = By golly, it works. ThirdKey = Another test. - Pengguna tidak perlu me-reboot sistem agar pemanggilan aplikasi di masa mendatang melihat pemetaan file .ini ke registri.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
int main()
{
TCHAR inBuf[80];
HKEY hKey1, hKey2;
DWORD dwDisposition;
LONG lRetCode;
TCHAR szData[] = TEXT("USR:App Name\\Section1");
// Create the .ini file key.
lRetCode = RegCreateKeyEx ( HKEY_LOCAL_MACHINE,
TEXT("SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\IniFileMapping\\appname.ini"),
0,
NULL,
REG_OPTION_NON_VOLATILE,
KEY_WRITE,
NULL,
&hKey1,
&dwDisposition);
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in creating appname.ini key (%d).\n", lRetCode);
return (0) ;
}
// Set a section value
lRetCode = RegSetValueEx ( hKey1,
TEXT("Section1"),
0,
REG_SZ,
(BYTE *)szData,
sizeof(szData));
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in setting Section1 value\n");
// Close the key
lRetCode = RegCloseKey( hKey1 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return (0) ;
}
}
// Create an App Name key
lRetCode = RegCreateKeyEx ( HKEY_CURRENT_USER,
TEXT("App Name"),
0,
NULL,
REG_OPTION_NON_VOLATILE,
KEY_WRITE,
NULL,
&hKey2,
&dwDisposition);
if (lRetCode != ERROR_SUCCESS)
{
printf ("Error in creating App Name key (%d).\n", lRetCode);
// Close the key
lRetCode = RegCloseKey( hKey2 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return (0) ;
}
}
// Force the system to read the mapping into shared memory
// so that future invocations of the application will see it
// without the user having to reboot the system
WritePrivateProfileStringW( NULL, NULL, NULL, L"appname.ini" );
// Write some added values
WritePrivateProfileString (TEXT("Section1"),
TEXT("FirstKey"),
TEXT("It all worked out OK."),
TEXT("appname.ini"));
WritePrivateProfileString (TEXT("Section1"),
TEXT("SecondKey"),
TEXT("By golly, it works!"),
TEXT("appname.ini"));
WritePrivateProfileString (TEXT("Section1"),
TEXT("ThirdKey"),
TEXT("Another test..."),
TEXT("appname.ini"));
// Test
GetPrivateProfileString (TEXT("Section1"),
TEXT("FirstKey"),
TEXT("Error: GPPS failed"),
inBuf,
80,
TEXT("appname.ini"));
_tprintf (TEXT("Key: %s\n"), inBuf);
// Close the keys
lRetCode = RegCloseKey( hKey1 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return(0);
}
lRetCode = RegCloseKey( hKey2 );
if( lRetCode != ERROR_SUCCESS )
{
printf("Error in RegCloseKey (%d).\n", lRetCode);
return(0);
}
return(1);
}
Catatan
Header winbase.h mendefinisikan WritePrivateProfileString 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 |