Funzione GetPrivateProfileStringA (winbase.h)
Recupera una stringa dalla sezione specificata in un file di inizializzazione.
Sintassi
DWORD GetPrivateProfileStringA(
[in] LPCSTR lpAppName,
[in] LPCSTR lpKeyName,
[in] LPCSTR lpDefault,
[out] LPSTR lpReturnedString,
[in] DWORD nSize,
[in] LPCSTR lpFileName
);
Parametri
[in] lpAppName
Nome della sezione contenente il nome della chiave. Se questo parametro è NULL, la funzione GetPrivateProfileString copia tutti i nomi di sezione nel file nel buffer fornito.
[in] lpKeyName
Nome della chiave la cui stringa associata deve essere recuperata. Se questo parametro è NULL, tutti i nomi delle chiavi nella sezione specificata dal parametro lpAppName vengono copiati nel buffer specificato dal parametro lpReturnedString .
[in] lpDefault
Stringa predefinita. Se la chiave lpKeyName non è disponibile nel file di inizializzazione, GetPrivateProfileString copia la stringa predefinita nel buffer lpReturnedString .
Se questo parametro è NULL, il valore predefinito è una stringa vuota, "".
Evitare di specificare una stringa predefinita con caratteri vuoti finali. La funzione inserisce un carattere Null nel buffer lpReturnedString per rimuovere eventuali spazi vuoti finali.
[out] lpReturnedString
Puntatore al buffer che riceve la stringa recuperata.
[in] nSize
Dimensioni del buffer a cui punta il parametro lpReturnedString , in caratteri.
[in] lpFileName
Nome del file di inizializzazione. Se questo parametro non contiene un percorso completo del file, il sistema cerca il file nella directory di Windows.
Valore restituito
Il valore restituito è il numero di caratteri copiati nel buffer, non incluso il carattere null terminante.
Se né lpAppName né lpKeyName è NULL e il buffer di destinazione fornito è troppo piccolo per contenere la stringa richiesta, la stringa viene troncata e seguita da un carattere Null e il valore restituito è uguale a nSize meno uno.
Se lpAppName o lpKeyName è NULL e il buffer di destinazione fornito è troppo piccolo per contenere tutte le stringhe, l'ultima stringa viene troncata e seguita da due caratteri Null. In questo caso, il valore restituito è uguale a nSize meno due.
Se il file di inizializzazione specificato da lpFileName non viene trovato o contiene valori non validi, questa funzione imposta errorno con un valore "0x2" (File non trovato). Per recuperare informazioni sull'errore estese, chiamare GetLastError.
Commenti
La funzione GetPrivateProfileString cerca il file di inizializzazione specificato per una chiave corrispondente al nome specificato dal parametro lpKeyName nell'intestazione della sezione specificata dal parametro lpAppName . Se trova la chiave, la funzione copia la stringa corrispondente nel buffer. Se la chiave non esiste, la funzione copia la stringa di caratteri predefinita specificata dal parametro lpDefault . Una sezione nel file di inizializzazione deve avere il formato seguente:
[section]
key=string
.
.
.
Se lpAppName è NULL, GetPrivateProfileString copia tutti i nomi di sezione nel file specificato nel buffer fornito. Se lpKeyName è NULL, la funzione copia tutti i nomi delle chiavi nella sezione specificata nel buffer fornito. Un'applicazione può usare questo metodo per enumerare tutte le sezioni e le chiavi in un file. In entrambi i casi, ogni stringa viene seguita da un carattere Null e la stringa finale viene seguita da un secondo carattere Null . Se il buffer di destinazione specificato è troppo piccolo per contenere tutte le stringhe, l'ultima stringa viene troncata e seguita da due caratteri Null .
Se la stringa associata a lpKeyName è racchiusa tra virgolette singole o doppie, i segni vengono eliminati quando la funzione GetPrivateProfileString recupera la stringa.
La funzione GetPrivateProfileString non è distinzione tra maiuscole e minuscole; le stringhe possono essere una combinazione di lettere maiuscole e minuscole.
Per recuperare una stringa dal file Win.ini, usare la funzione GetProfileString .
Il sistema esegue il mapping della maggior parte dei riferimenti .ini file 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 questi casi, la funzione recupera informazioni dal Registro di sistema, non dal 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.
Esempio
Nell'esempio seguente viene illustrato l'uso di GetPrivateProfileString.
// Gets a profile string called "Preferred line" and converts it to an int.
GetPrivateProfileString (
"Preference",
"Preferred Line",
gszNULL,
szBuffer,
MAXBUFSIZE,
gszINIfilename
);
// if szBuffer is not empty.
if ( lstrcmp ( gszNULL, szBuffer ) )
{
dwPreferredPLID = (DWORD) atoi( szBuffer );
}
else
{
dwPreferredPLID = (DWORD) -1;
}
Nota
L'intestazione winbase.h definisce GetPrivateProfileString 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 |