Funzione GetProfileStringA (winbase.h)

Recupera la stringa associata a una chiave nella sezione specificata del file Win.ini.

Sintassi

DWORD GetProfileStringA(
  [in]  LPCSTR lpAppName,
  [in]  LPCSTR lpKeyName,
  [in]  LPCSTR lpDefault,
  [out] LPSTR  lpReturnedString,
  [in]  DWORD  nSize
);

Parametri

[in] lpAppName

Nome della sezione contenente la chiave. Se questo parametro è NULL, la funzione 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, la funzione copia tutte le chiavi nella sezione specificata nel buffer fornito. Ogni stringa è seguita da un carattere null e la stringa finale è seguita da un secondo carattere null.

[in] lpDefault

Stringa predefinita. Se non è possibile trovare la chiave lpKeyName nel file di inizializzazione, GetProfileString 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 a un buffer che riceve la stringa di caratteri.

[in] nSize

Dimensioni del buffer a cui punta il parametro lpReturnedString, in caratteri.

Valore restituito

Il valore restituito è il numero di caratteri copiati nel buffer, senza includere il nullcarattere di terminazione.

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.

Osservazioni

Se la stringa associata al parametro lpKeyName è racchiusa tra virgolette singole o doppie, i segni vengono eliminati quando la funzione GetProfileString restituisce la stringa.

La funzione GetProfileString non fa distinzione tra maiuscole e minuscole; le stringhe possono contenere una combinazione di lettere maiuscole e minuscole.

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

[section]
key=string
      .
      .
      .

Un'applicazione può usare la funzione GetPrivateProfileString per recuperare una stringa da un file di inizializzazione specificato.

Il parametro lpDefault deve puntare a una stringa valida, anche se la stringa è vuota( ovvero, anche se il primo carattere è un carattere null).

Windows Server 2003 e Windows XP/2000: Le chiamate alle funzioni di profilo possono essere mappate al Registro di sistema anziché ai file di inizializzazione. Questo mapping si verifica quando il file di inizializzazione e la sezione vengono specificati nel Registro di sistema nelle chiavi seguenti:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\IniFileMapping

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

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 in tale sottochiave specificano dove nel Registro di sistema si troveranno 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 il percorso predefinito nel Registro di sistema in cui si trova 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 <Nessun nome>) che specifica il percorso predefinito nel Registro di sistema in cui si troveranno 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.

• ! : 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 .ini su disco se i dati richiesti non vengono trovati nel Registro di sistema.
• USR: questo prefisso è l'acronimo di HKEY_CURRENT_USERe 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.

Fabbisogno

Vedere anche

GetPrivateProfileString

WriteProfileString