Funzione WritePrivateProfileStringA (winbase.h)
Copia una stringa nella sezione specificata di un file di inizializzazione.
Sintassi
BOOL WritePrivateProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpString,
[in] LPCSTR lpFileName
);
Parametri
[in] lpAppName
Nome della sezione in cui verrà copiata la stringa. Se la sezione non esiste, viene creata. Il nome della sezione è indipendente dal caso; la stringa può essere qualsiasi combinazione di lettere maiuscole e minuscole.
[in] lpKeyName
Nome della chiave da associare a una stringa. Se la chiave non esiste nella sezione specificata, viene creata. Se questo parametro è NULL, viene eliminata l'intera sezione, incluse tutte le voci all'interno della sezione.
[in] lpString
Stringa con terminazione Null da scrivere nel file. Se questo parametro è NULL, la chiave a cui punta il parametro lpKeyName viene eliminata.
[in] lpFileName
Nome del file di inizializzazione.
Se il file è stato creato usando caratteri Unicode, la funzione scrive caratteri Unicode nel file. In caso contrario, la funzione scrive caratteri ANSI.
Valore restituito
Se la funzione copia correttamente la stringa nel file di inizializzazione, il valore restituito è diverso da zero.
Se la funzione ha esito negativo o se scarica la versione memorizzata nella cache del file di inizializzazione accessibile più di recente, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
Una sezione nel file di inizializzazione deve avere il formato seguente:
[section]
key=string
.
.
.
Se il parametro lpFileName non contiene un percorso completo e un nome file per il file, WritePrivateProfileString cerca il file nella directory di Windows. Se il file non esiste, questa funzione crea il file nella directory di Windows.
Se lpFileName contiene un percorso completo e un nome file e il file non esiste, WritePrivateProfileString crea il file. La directory specificata deve esistere già.
Il sistema mantiene una versione memorizzata nella cache del mapping dei file del Registro di sistema più recente per migliorare le prestazioni. Se tutti i parametri sono NULL, la funzione scarica la cache. Mentre il sistema sta modificando la versione memorizzata nella cache del file, i processi che modificano il file stesso useranno il file originale fino a quando la cache non è stata cancellata.
Il sistema esegue il mapping della maggior parte dei riferimenti al file .ini al Registro di sistema, usando il mapping definito nella seguente chiave del Registro di sistema:
HKEY_LOCAL_MACHINE SOFTWARE Microsoft Windows NT CurrentVersion IniFileMapping
Questo mapping è probabile se un'applicazione modifica i file di inizializzazione dei componenti di sistema, ad esempio Control.ini, System.ini e Winfile.ini. In questo caso, la funzione scrive le informazioni nel Registro di sistema, non nel file di inizializzazione; la modifica nella posizione di archiviazione non ha alcun effetto sul comportamento della funzione.
Le funzioni del profilo usano i passaggi seguenti per individuare le informazioni di inizializzazione:
- Cercare nel Registro di sistema il nome del file di inizializzazione nella chiave IniFileMapping .
- Cercare il nome della sezione specificato da lpAppName. Si tratta di un valore denominato nella chiave con il nome del file di inizializzazione o di una sottochiave con questo nome oppure il nome non esisterà come valore o sottochiave.
- Se il nome della sezione specificato da lpAppName è un valore denominato, tale valore specifica dove nel Registro di sistema troverai le chiavi per la sezione.
- Se il nome della sezione specificato da lpAppName è una sottochiave, i valori denominati nella sottochiave specificano dove nel Registro di sistema sono disponibili le chiavi per la sezione. Se la chiave che si sta cercando non esiste come valore denominato, sarà presente un valore senza nome (visualizzato come <No Name>) che specifica il percorso predefinito nel Registro di sistema in cui si troverà la chiave.
- Se il nome della sezione specificato da lpAppName non esiste come valore denominato o come sottochiave, sarà presente un valore senza nome (visualizzato come <No Name>) che specifica il percorso predefinito nel Registro di sistema in cui sono disponibili le chiavi per la sezione.
- Se non è presente alcuna sottochiave o voce per il nome della sezione, cercare il file di inizializzazione effettivo sul disco e leggerne il contenuto.
- ! : questo carattere forza tutte le scritture a passare sia al Registro di sistema che al file .ini su disco.
- # : questo carattere fa sì che il valore del Registro di sistema venga impostato sul valore nel file di Windows 3.1 .ini quando un nuovo utente accede per la prima volta dopo l'installazione.
- @ : questo carattere impedisce alle letture di passare al file di .ini su disco se i dati richiesti non vengono trovati nel Registro di sistema.
- USR: questo prefisso è l'acronimo di HKEY_CURRENT_USER e il testo dopo il prefisso è relativo a tale chiave.
- SYS: questo prefisso è l'acronimo di HKEY_LOCAL_MACHINE\SOFTWAREe il testo dopo il prefisso è relativo a tale chiave.
- Verificare che nel sistema non esista alcun file .ini del nome specificato.
- Assicurarsi che nel Registro di sistema sia presente una voce di chiave che specifica il file .ini. Questa voce deve trovarsi nel percorso HKEY_LOCAL_MACHINE\SOFTWARE \Microsoft\Windows NT\CurrentVersion\IniFileMapping.
- Specificare un valore per tale .ini voce di chiave del file che specifica una sezione. Ad esempio, un'applicazione deve specificare un nome di sezione, come appare all'interno di una voce del registro o di un file .ini. Di seguito è riportato un esempio: [Sezione personale].
- Per i file di sistema, specificare SYS per un valore aggiunto.
- Per i file dell'applicazione, specificare USR all'interno del valore aggiunto. Ecco un esempio: "My Section: USR: App Name\Section". Inoltre, poiché USR indica un mapping in HKEY_CURRENT_USER, l'applicazione deve anche creare una chiave in HKEY_CURRENT_USER che specifica il nome dell'applicazione elencato nel valore aggiunto. Per l'esempio appena specificato, si tratta di "Nome app".
- Dopo aver seguito i passaggi precedenti, un programma di installazione dell'applicazione deve chiamare WritePrivateProfileString con i primi tre parametri impostati su NULL e il quarto parametro impostato sul nome del file INI. Ad esempio:
WritePrivateProfileString( NULL, NULL, NULL, L"appname.ini" ); - Tale chiamata fa sì che il mapping di un file di .ini al Registro di sistema venga applicato prima del successivo riavvio del sistema. Il sistema rilegge le informazioni di mapping in memoria condivisa. Un utente non dovrà riavviare il computer dopo l'installazione di un'applicazione per fare in modo che le chiamate future dell'applicazione visualizzino il mapping del file .ini al Registro di sistema.
Esempio
Il codice di esempio seguente illustra le linee guida precedenti e si basa su diversi presupposti:
- È presente un'applicazione denominata Nome app.
- Tale applicazione usa un file di .ini denominato AppName.ini.
- Nel file di .ini è presente una sezione simile alla seguente:
[Section1] FirstKey = It all worked out okay. SecondKey = By golly, it works. ThirdKey = Another test. - L'utente non dovrà riavviare il sistema per fare in modo che le chiamate future dell'applicazione visualizzino il mapping del file .ini al Registro di sistema.
#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);
}
Nota
L'intestazione winbase.h definisce WritePrivateProfileString come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winbase.h (include Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |