Funzione WritePrivateProfileSectionW (winbase.h)
Sostituisce le chiavi e i valori per la sezione specificata in un file di inizializzazione.
Sintassi
BOOL WritePrivateProfileSectionW(
[in] LPCWSTR lpAppName,
[in] LPCWSTR lpString,
[in] LPCWSTR lpFileName
);
Parametri
[in] lpAppName
Nome della sezione in cui vengono scritti i dati. Questo nome della sezione è in genere il nome dell'applicazione chiamante.
[in] lpString
I nuovi nomi delle chiavi e i valori associati da scrivere nella sezione denominata. Questa stringa è limitata a 65.535 byte.
[in] lpFileName
Nome del file di inizializzazione. Se questo parametro non contiene un percorso completo per il file, la funzione cerca la directory di Windows per il file. Se il file non esiste e lpFileName non contiene un percorso completo, la funzione crea il file nella directory di Windows.
Se il file esiste ed è stato creato usando caratteri Unicode, la funzione scrive i caratteri Unicode nel file. In caso contrario, la funzione crea un file usando caratteri ANSI.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è diverso da zero.
Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
I dati nel buffer a cui punta il parametro lpString sono costituiti da una o più stringhe con terminazione null, seguita da un carattere Null finale. Ogni stringa ha il formato seguente:
Chiave=Stringa
La funzione WritePrivateProfileSection non è distinzione tra maiuscole e minuscole; la stringa puntata dal parametro lpAppName può essere una combinazione di lettere maiuscole e minuscole.
Se nessun nome di sezione corrisponde alla stringa puntata dal parametro lpAppName , WritePrivateProfileSection crea la sezione alla fine del file di inizializzazione specificato e inizializza la nuova sezione con il nome della chiave e le coppie valore specificate.
WritePrivateProfileSection elimina le chiavi e i valori esistenti per la sezione denominata e inserisce i nomi e i valori della chiave nel buffer a cui punta il parametro lpString . La funzione non tenta di correlare i nomi di chiave precedenti e nuovi; se i nuovi nomi vengono visualizzati in un ordine diverso dai nomi precedenti, eventuali commenti associati a chiavi e valori preesistenti nel file di inizializzazione probabilmente saranno associati a chiavi e valori non corretti.
Questa operazione è atomica; non sono consentite operazioni che leggono o scrivono nel file di inizializzazione specificato mentre vengono scritte le informazioni.
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 modifica 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 di file .ini al Registro di sistema usando il mapping definito sotto la chiave del Registro di sistema seguente:
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. Questo sarà un valore denominato nella chiave con il nome del file di inizializzazione o una sottochiave con questo nome o 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 verranno trovate 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 <Nessun> nome) che specifica la posizione predefinita 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 <Nessun> nome) che specifica la posizione predefinita nel Registro di sistema in cui saranno 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 per passare al Registro di sistema e al file .ini su disco.
- # : questo carattere causa l'impostazione del valore del Registro di sistema sul valore nel file 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 è HKEY_CURRENT_USER e il testo dopo il prefisso è relativo a tale chiave.
- SYS: questo prefisso indica HKEY_LOCAL_MACHINE\SOFTWAREe il testo dopo che il prefisso è relativo a tale chiave.
Nota
L'intestazione winbase.h definisce WritePrivateProfileSection come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.
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 |