Funzione GetThreadPreferredUILanguages (winnls.h)

Articolo
08/27/2023

Recupera le lingue dell'interfaccia utente preferite del thread per il thread corrente. Per altre informazioni, vedere Gestione del linguaggio dell'interfaccia utente.

Sintassi

BOOL GetThreadPreferredUILanguages(
  [in]            DWORD   dwFlags,
  [out]           PULONG  pulNumLanguages,
  [out, optional] PZZWSTR pwszLanguagesBuffer,
  [in, out]       PULONG  pcchLanguagesBuffer
);

Parametri

[in] dwFlags

Flag che identificano il formato e il filtro della lingua. I flag seguenti specificano il formato della lingua da usare per le lingue dell'interfaccia utente preferite del thread. I flag si escludono a vicenda e il valore predefinito è MUI_LANGUAGE_NAME.

Valore	Significato
MUI_LANGUAGE_ID	Recuperare le stringhe della lingua nel formato dell'identificatore di lingua .
MUI_LANGUAGE_NAME	Recuperare le stringhe della lingua nel formato del nome della lingua .

I flag seguenti specificano il filtro per la funzione da usare per recuperare le lingue dell'interfaccia utente preferite del thread. Il flag predefinito è MUI_MERGE_USER_FALLBACK.

Valore	Significato
MUI_MERGE_SYSTEM_FALLBACK	Usare il fallback di sistema per recuperare un elenco che corrisponde esattamente all'elenco di lingue usato dal caricatore di risorse. Questo flag può essere usato solo in combinazione con MUI_MERGE_USER_FALLBACK. L'uso dei flag in combinazione modifica l'effetto consueto di MUI_MERGE_USER_FALLBACK includendo le lingue di fallback e neutrali nell'elenco.
MUI_MERGE_USER_FALLBACK	Recuperare un elenco composito costituito dalle lingue preferite dell'interfaccia utente del thread, seguite da lingue preferite dell'interfaccia utente, seguite da tutte le lingue preferite dell'interfaccia utente preferite dall'utente, seguite dalla lingua dell'interfaccia utente predefinita del sistema, se non è già presente nell'elenco. Se l'elenco delle lingue dell'interfaccia utente preferite dall'utente è vuoto, la funzione recupera le lingue dell'interfaccia utente preferite dal sistema. Questo flag non può essere combinato con MUI_THREAD_LANGUAGES.
MUI_THREAD_LANGUAGES	Recuperare solo le lingue dell'interfaccia utente preferite del thread per il thread corrente o un elenco vuoto se non sono impostate lingue preferite per il thread corrente. Questo flag non può essere combinato con MUI_MERGE_USER_FALLBACK o MUI_MERGE_SYSTEM_FALLBACK.
MUI_UI_FALLBACK	Recuperare un elenco completo di lingue preferite dell'interfaccia utente con fallback e lingue neutre associate. L'uso di questo flag equivale alla combinazione di MUI_MERGE_SYSTEM_FALLBACK e MUI_MERGE_USER_FALLBACK. (applicabile solo per Windows 7 e versioni successive).

[out] pulNumLanguages

Puntatore al numero di lingue recuperate in pwszLanguagesBuffer.

[out, optional] pwszLanguagesBuffer

facoltativo. Puntatore a un buffer in cui questa funzione recupera un elenco di lingue dell'interfaccia utente preferite delimitate da null, nel formato specificato da dwFlags. Questo elenco termina con due caratteri Null.

In alternativa, se questo parametro è impostato su NULL e pcchLanguagesBuffer è impostato su 0, la funzione recupera le dimensioni necessarie del buffer linguistico in pcchLanguagesBuffer. Le dimensioni necessarie includono i due caratteri Null.

[in, out] pcchLanguagesBuffer

Puntatore alla dimensione, in caratteri, per il buffer linguistico indicato da pwszLanguagesBuffer. Al termine della restituzione dalla funzione, il parametro contiene le dimensioni del buffer del linguaggio recuperato.

In alternativa, se questo parametro è impostato su 0 e pwszLanguagesBuffer è impostato su NULL, la funzione recupera le dimensioni necessarie del buffer linguistico in pcchLanguagesBuffer.

Valore restituito

Restituisce TRUE se ha esito positivo o FALSE in caso contrario. Per ottenere informazioni sull'errore estese, l'applicazione può chiamare GetLastError, che restituisce 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.

Se la funzione ha esito negativo per qualsiasi altro motivo, i parametri pulNumLanguages e pcchLanguagesBuffer non sono definiti.

Commenti

A seconda dei flag specificati dall'applicazione, questa funzione può recuperare un elenco composito costituito dalle lingue dell'interfaccia utente preferite dal thread, elaborare le lingue preferite dell'interfaccia utente, le lingue dell'interfaccia utente preferite dall'utente o le lingue dell'interfaccia utente preferite dal sistema e la lingua predefinita dell'interfaccia utente di sistema. Se rileva un linguaggio duplicato, la funzione recupera solo il primo linguaggio.

Se l'applicazione ha chiamato SetThreadPreferredUILanguages con il flag MUI_CONSOLE_FILTER o MUI_COMPLEX_SCRIPT_FILTER, GetThreadPreferredUILanguages filtra le lingue nell'elenco risultati. La funzione sostituisce le lingue che la console non può visualizzare con una lingua sostitutiva. La sostituzione di una lingua viene determinata dal valore di LOCALE_SCONSOLEFALLBACKNAME per la lingua. Per altre informazioni sulla console, vedere la descrizione di SetThreadUILanguage.

L'uso di MUI_LANGUAGE_NAME è consigliato su MUI_LANGUAGE_ID perché il flag MUI_LANGUAGE_NAME può eseguire un lavoro migliore per gestire le lingue del Language Interface Pack (LIP) corrispondenti alle impostazioni locali supplementari.

Quando si specifica MUI_LANGUAGE_ID, le stringhe di lingua recuperate saranno identificatori di lingua esadecimali

che non includono lo 0x iniziale e avranno una lunghezza di 4 caratteri. Ad esempio, en-US verrà restituito

come "0409" e en come "0009".

Se l'applicazione imposta il flag di MUI_LANGUAGE_ID, le lingue dell'interfaccia utente preferite del thread possono includere una o più lingue corrispondenti alle impostazioni locali supplementari. Al termine della restituzione dalla funzione, il buffer della lingua contiene "1400" per qualsiasi lingua corrispondente a impostazioni locali supplementari. In questo elenco può essere presente una sola lingua di questo tipo. La stringa "1400" corrisponde al valore esadecimale di LOCALE_CUSTOM_UI_DEFAULT. Inoltre, quando viene restituito correttamente dalla funzione, pwszLanguagesBuffer contiene "1000" per qualsiasi altra lingua corrispondente a impostazioni locali supplementari. La stringa "1000" corrisponde al valore esadecimale di LOCALE_CUSTOM_UNSPECIFIED, che non è utile come input per qualsiasi funzione, perché non può distinguere tra le impostazioni locali supplementari.

Firma C#

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean GetThreadPreferredUILanguages(
            System.UInt32 dwFlags,
            ref System.UInt32 pulNumLanguages,
            System.IntPtr pwszLanguagesBuffer,
            ref System.UInt32 pcchLanguagesBuffer
            );

Requisiti


Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winnls.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll