Funzione WriteProfileStringA (winbase.h)

  • Articolo

Copia una stringa nella sezione specificata del file Win.ini. Se Win.ini utilizza caratteri Unicode, la funzione scrive caratteri Unicode nel file. In caso contrario, la funzione scrive caratteri ANSI.

Nota Questa funzione viene fornita solo per la compatibilità con le versioni a 16 bit di Windows. Le applicazioni devono archiviare le informazioni di inizializzazione nel Registro di sistema.
 

Sintassi

BOOL WriteProfileStringA(
  [in] LPCSTR lpAppName,
  [in] LPCSTR lpKeyName,
  [in] LPCSTR lpString
);

Parametri

[in] lpAppName

Sezione in cui copiare la stringa. Se la sezione non esiste, viene creata. Il nome della sezione non fa distinzione tra maiuscole e minuscole; la stringa può essere qualsiasi combinazione di lettere maiuscole e minuscole.

[in] lpKeyName

Chiave da associare alla stringa. Se la chiave non esiste nella sezione specificata, viene creata. Se questo parametro è NULL, viene eliminata l'intera sezione, incluse tutte le voci 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.

Valore restituito

Se la funzione copia correttamente la stringa nel file Win.ini, il valore restituito è diverso da zero.

Se la funzione ha esito negativo o se scarica la versione memorizzata nella cache di Win.ini, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Una sezione del file di Win.ini deve avere il formato seguente:stringachiave=.

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

Quando l'operazione è stata mappata, la funzione WriteProfileString 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:

  1. Cercare nel Registro di sistema il nome del file di inizializzazione nella chiave IniFileMapping .
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. Se non è presente alcuna sottochiave o voce per il nome della sezione, cercare il file di inizializzazione effettivo sul disco e leggerne il contenuto.
Quando si esaminano i valori nel Registro di sistema che specificano altri percorsi del Registro di sistema, esistono diversi prefissi che modificano il comportamento del mapping dei file .ini:
  • ! : 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.

Nota

L'intestazione winbase.h definisce WriteProfileString 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

Vedere anche

GetProfileString

WritePrivateProfileString