Funzione GetLocaleInfoEx (winnls.h)

Articolo
03/13/2024

Recupera informazioni sulle impostazioni locali specificate in base al nome.

Nota L'applicazione deve chiamare questa funzione in preferenza per GetLocaleInfo se progettata per l'esecuzione solo in Windows Vista e versioni successive.

Nota Questa funzione può recuperare i dati che cambiano tra le versioni, ad esempio a causa di impostazioni locali personalizzate. Se l'applicazione deve mantenere o trasmettere dati, vedere Uso di dati locali persistenti.

Sintassi

int GetLocaleInfoEx(
  [in, optional]  LPCWSTR lpLocaleName,
  [in]            LCTYPE  LCType,
  [out, optional] LPWSTR  lpLCData,
  [in]            int     cchData
);

Parametri

[in, optional] lpLocaleName

Puntatore a un nome delle impostazioni locali o uno dei valori predefiniti seguenti.

[in] LCType

Informazioni sulle impostazioni locali da recuperare. Per i valori possibili, vedere la sezione "Costanti usate nel parametro LCType di GetLocaleInfo, GetLocaleInfoEx e SetLocaleInfo" in Costanti informazioni locali. Si noti che è possibile specificare una sola parte di informazioni locali per chiamata.

L'applicazione può usare l'operatore OR binario per combinare LOCALE_RETURN_NUMBER con qualsiasi altra costante consentita. In questo caso, la funzione recupera il valore come numero anziché una stringa. Il buffer che riceve il valore deve essere almeno la lunghezza di un valore DWORD, ovvero 2.

Attenzione È anche possibile combinare LOCALE_NOUSEROVERRIDE con qualsiasi altra costante. Tuttavia, l'uso di questa costante è fortemente sconsigliato. (Anche senza usare l'override dell'utente corrente, i dati possono essere diversi dal computer al computer e le impostazioni locali personalizzate possono modificare i dati. Ad esempio, anche i nomi di mese o giorno sono soggetti a riforme ortografiche.

Se LCType è impostato su LOCALE_IOPTIONALCALENDAR, la funzione recupera solo il primo calendario alternativo.

Nota Per ottenere tutti i calendari alternativi, l'applicazione deve usare EnumCalendarInfoEx.

A partire da Windows Vista, le applicazioni non devono usare LOCALE_ILANGUAGE nel parametro LCType per evitare errori o recupero di dati imprevisti. È invece consigliabile chiamare GetLocaleInfoEx per le applicazioni.

[out, optional] lpLCData

Puntatore a un buffer in cui questa funzione recupera le informazioni sulle impostazioni locali richieste. Questo puntatore non viene usato se cchData è impostato su 0.

[in] cchData

Dimensioni, in caratteri, 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 terminante.

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 dati, ovvero 2. 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 dati delle impostazioni locali.

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

ERROR_INSUFFICIENT_BUFFER. Una dimensione del buffer fornita non è stata sufficiente oppure è stata impostata in modo errato su NULL.
ERROR_INVALID_FLAGS. I valori forniti per i flag non sono validi.
ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.

Commenti

Questa funzione recupera normalmente informazioni in formato testo. Se le informazioni sono un valore numerico e il valore di LCType è LOCALE_ILANGUAGE o LOCALE_IDEFAULTLANGUAGE, questa funzione recupera stringhe contenenti numeri esadecimali. In caso contrario, il testo recuperato per le informazioni numeriche è un numero decimale.

Esistono due eccezioni a questa regola. Prima di tutto, l'applicazione può recuperare i valori numerici come interi specificando LOCALE_RETURN_NUMBER nel parametro LCType . La seconda eccezione è che LOCALE_FONTSIGNATURE si comporta in modo diverso da tutte le altre costanti delle informazioni locali. L'applicazione deve fornire un buffer di dati di almeno dimensioniof(LOCALESIGNATURE) byte. Al termine della restituzione dalla funzione, il buffer viene compilato come struttura LOCALESIGNATURE .

Nota Anche quando il parametro LCType viene specificato come LOCALE_FONTSIGNATURE, cchData e la funzione restituita sono ancora conteggi dei caratteri. Quando un'applicazione chiama GetLocaleInfoEx con LCType specificato come LOCALE_FONTSIGNATURE, cchData può essere specificato in modo sicuro come sizeof(LOCALESIGNATURE) /sizeof(WCHAR).

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

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                      (LPWSTR)&value,
                      sizeof(value) / sizeof(WCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_FONTSIGNATURE,
                      (LPWSTR)&LocSig,
                      sizeof(LocSig) / sizeof(WCHAR) );

Questa funzione può recuperare i dati dalle impostazioni locali personalizzate. I dati non sono garantiti come uguali da computer a computer o tra esecuzioni di un'applicazione. Se l'applicazione deve mantenere o trasmettere dati, vedere Uso di dati locali persistenti.

A partire da Windows 8: se l'app passa tag di lingua a questa funzione dallo spazio dei nomi Windows.Globalization, deve prima convertire i tag chiamando ResolveLocaleName.

Esempio

Esempi che illustrano l'uso di questa funzione sono disponibili in NLS: Esempi di API basate su nome e NLS: Esempio di mitigazione del nome di dominio internazionale (IDN).

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winnls.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll