Funzione GetLocaleInfoA (winnls.h)

Articolo
11/20/2024

Recupera informazioni sulle impostazioni locali specificate dall'identificatore.

Nota Per motivi di interoperabilità, l'applicazione deve preferire la funzione GetLocaleInfoEx a GetLocaleInfo perché Microsoft sta eseguendo la migrazione verso l'uso dei nomi delle impostazioni locali anziché degli identificatori delle impostazioni locali per le nuove impostazioni locali. Qualsiasi applicazione eseguita solo in Windows Vista e versioni successive deve usare GetLocaleInfoEx.

Nota Per la compatibilità globale, l'applicazione deve preferire i moduli API Unicode "W" ai moduli "A". GetLocaleInfoA limiterà i dati di tipo carattere e potrebbe comportare risultati danneggiati agli utenti, in particolare nelle applicazioni abilitate a livello globale. Per questa API, GetLocaleInfoEx è preferibile perché è Unicode e supporta anche gli standard moderni per i nomi delle impostazioni locali.

Sintassi

int GetLocaleInfoA(
  [in]            LCID   Locale,
  [in]            LCTYPE LCType,
  [out, optional] LPSTR  lpLCData,
  [in]            int    cchData
);

Parametri

[in] Locale

identificatore delle impostazioni locali per cui recuperare informazioni. È possibile utilizzare la macro MAKELCID per creare un identificatore delle impostazioni locali o usare uno dei valori predefiniti seguenti.

[in] LCType

Informazioni sulle impostazioni locali da recuperare. Per le definizioni dettagliate, vedere il parametro LCType di GetLocaleInfoEx.

Nota Per GetLocaleInfo, il valore LOCALE_USE_CP_ACP è rilevante solo per la versione ANSI.

[out, optional] lpLCData

Puntatore a un buffer in cui questa funzione recupera le informazioni sulle impostazioni locali richieste. Questo puntatore non viene utilizzato se cchData è impostato su 0. Per altre informazioni, vedere la sezione Osservazioni.

[in] cchData

Dimensioni, in valori TCHAR, del buffer di dati indicato da lpLCData. In alternativa, l'applicazione può impostare questo parametro su 0. In questo caso, la funzione non usa il parametro lpLCData e restituisce le dimensioni del buffer necessarie, incluso il carattere Null di terminazione.

Valore restituito

Restituisce il numero di caratteri recuperati nel buffer dei dati delle impostazioni locali se ha esito positivo e cchData è un valore diverso da zero. Se la funzione ha esito positivo, cchData è diverso da zero e LOCALE_RETURN_NUMBER viene specificato, il valore restituito è la dimensione dell'intero recuperato nel buffer di dati; ovvero 2 per la versione Unicode della funzione o 4 per la versione ANSI. Se la funzione ha esito positivo e il valore di cchData è 0, il valore restituito è la dimensione necessaria, in caratteri inclusi un carattere Null, per il buffer dei dati delle impostazioni locali.

La funzione restituisce 0 se non riesce. Per ottenere informazioni estese sull'errore, l'applicazione può chiamare GetLastError, che può restituire uno dei codici di errore seguenti:

ERROR_INSUFFICIENT_BUFFER. Le dimensioni del buffer fornite non sono sufficienti o non sono state impostate correttamente su NULL.
ERROR_INVALID_FLAGS. I valori specificati per i flag non sono validi.
ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.

Osservazioni

Per l'operazione di questa funzione, vedere Osservazioni per GetLocaleInfoEx.

Nota Anche quando il parametro LCType viene specificato come LOCALE_FONTSIGNATURE, cchData e la funzione restituita sono ancora conteggi TCHAR. Il conteggio è diverso per le versioni ANSI e Unicode della funzione. Quando un'applicazione chiama la versione generica di GetLocaleInfo con LOCALE_FONTSIGNATURE, cchData può essere specificata in modo sicuro come sizeof(LOCALESIGNATURE) / sizeof(TCHAR).

Gli esempi seguenti gestiscono correttamente le dimensioni del buffer per i valori non di testo:

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                    (LPTSTR)&value,
                    sizeof(value) / sizeof(TCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_FONTSIGNATURE,
                    (LPWSTR)&LocSig,
                    sizeof(LocSig) / sizeof(TCHAR) );

La stringa ANSI recuperata dalla versione ANSI di questa funzione viene convertita da Unicode a ANSI in base alla tabella codici ANSI predefinita per l'identificatore delle impostazioni locali. Tuttavia, se si specifica LOCALE_USE_CP_ACP, la traduzione si basa sulla tabella codici ANSI predefinita del sistema.

Quando la versione ANSI di questa funzione viene usata con un identificatore delle impostazioni locali solo Unicode, la funzione può avere esito positivo perché il sistema operativo usa la tabella codici del sistema. Tuttavia, i caratteri non definiti nella tabella codici di sistema vengono visualizzati nella stringa come punto interrogativo (?).

Nota

L'intestazione winnls.h definisce GetLocaleInfo 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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [app desktop \| App UWP]
server minimo supportato	Windows 2000 Server [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	winnls.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll