Funzione GetPrivateProfileSection (winbase.h)

  • Articolo

Recupera tutte le chiavi e i valori per la sezione specificata di un file di inizializzazione.

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

Sintassi

DWORD GetPrivateProfileSection(
  [in]  LPCTSTR lpAppName,
  [out] LPTSTR  lpReturnedString,
  [in]  DWORD   nSize,
  [in]  LPCTSTR lpFileName
);

Parametri

[in] lpAppName

Nome della sezione nel file di inizializzazione.

[out] lpReturnedString

Puntatore a un buffer che riceve le coppie nome chiave e valore associate alla sezione denominata. Il buffer viene riempito con una o più stringhe con terminazione Null; l'ultima stringa è seguita da un secondo carattere Null.

[in] nSize

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

La dimensione massima della sezione del profilo è di 32.767 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 specifica il numero di caratteri copiati nel buffer, senza includere il carattere null di terminazione. Se il buffer non è sufficientemente grande da contenere tutte le coppie nome chiave e valore associate alla sezione denominata, il valore restituito è uguale a nSize meno due.

Commenti

I dati nel buffer a cui punta il parametro lpReturnedString sono costituiti da una o più stringhe con terminazione Null, seguite da un carattere Null finale. Ogni stringa ha il formato seguente:

Chiave=Stringa

La funzione GetPrivateProfileSection non fa distinzione tra maiuscole e minuscole; la stringa a cui punta il parametro lpAppName può essere una combinazione di lettere maiuscole e minuscole.

Questa operazione è atomica; non sono consentiti aggiornamenti al file di inizializzazione specificato mentre le coppie nome chiave e valore per la sezione vengono copiate nel buffer a cui punta il parametro lpReturnedString .

Il sistema esegue il mapping della maggior parte dei riferimenti di 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 questi casi, la funzione recupera le 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 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.
I commenti (qualsiasi riga che inizia con un punto e virgola) viene rimossa e non restituita nel buffer lpReturnedString .

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

GetPrivateProfileSectionNames

GetProfileSection

WritePrivateProfileSection