Funzione GetUILanguageInfo (winnls.h)

Articolo
08/27/2023

Recupera un'ampia gamma di informazioni su una lingua dell'interfaccia utente installata:

La lingua è installata?
L'utente corrente è autorizzato a usare la lingua?
La lingua è completamente localizzata? Localizzato parzialmente? Parte di un Language Installation Pack (LIP)?
Se è parzialmente localizzata o parte di un LIP:
- Qual è la sua lingua di fallback?
- Se tale linguaggio di fallback è una lingua parzialmente localizzata, qual è la sua base?
- Qual è il linguaggio di fallback predefinito?

Sintassi

BOOL GetUILanguageInfo(
  [in]                DWORD    dwFlags,
  [in]                PCZZWSTR pwmszLanguage,
  [out, optional]     PZZWSTR  pwszFallbackLanguages,
  [in, out, optional] PDWORD   pcchFallbackLanguages,
  [out]               PDWORD   pAttributes
);

Parametri

[in] dwFlags

Contrassegni che definiscono il formato della lingua specificata. I flag sono reciprocamente esclusivi e il valore predefinito è MUI_LANGUAGE_NAME.

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

[in] pwmszLanguage

Puntatore a lingue per cui la funzione deve recuperare informazioni. Questo parametro indica un elenco ordinato e delimitato da null di identificatori di lingua o nomi di lingua, a seconda dell'impostazione del flag. Per informazioni sull'uso di questo parametro, vedere la sezione Osservazioni.

[out, optional] pwszFallbackLanguages

Puntatore a un buffer in cui questa funzione recupera un elenco ordinato e delimitato da null di linguaggi di fallback, formattato come definito dall'impostazione per 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 del linguaggio in pcchLanguagesBuffer. Le dimensioni necessarie includono i due caratteri Null.

[in, out, optional] pcchFallbackLanguages

Puntatore alle dimensioni, in caratteri, per il buffer della lingua indicato da pwszFallbackLanguages. 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 del linguaggio in pcchLanguagesBuffer.

[out] pAttributes

Puntatore ai flag che indicano gli attributi dell'elenco di lingue di input. La funzione recupera sempre il flag che caratterizza l'ultima lingua elencata.

Valore	Significato
MUI_FULL_LANGUAGE	La lingua è completamente localizzata.
MUI_PARTIAL_LANGUAGE	La lingua è parzialmente localizzata.
MUI_LIP_LANGUAGE	La lingua è una lingua LIP.

Inoltre, pdwAttributes include uno o entrambi i flag seguenti, in base alle esigenze.

Valore	Significato
MUI_LANGUAGE_INSTALLED	La lingua è installata in questo computer.
MUI_LANGUAGE_LICENSED	La lingua è autorizzata in modo appropriato per l'utente corrente.

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 può restituire i 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_PARAMETER. Uno dei valori dei parametri non è valido. Per altre informazioni, vedere la sezione Osservazioni.
ERROR_OBJECT_NAME_NOT_FOUND. Il nome dell'oggetto specificato non è stato trovato o non è stato valido oppure la prima lingua nell'elenco di input non è una lingua installata. Per altre informazioni, vedere la sezione Osservazioni.

Se GetLastError restituisce qualsiasi altro codice di errore, i parametri pcchFallbackLanguages e pdwAttributes non sono definiti.

Commenti

MUI_LANGUAGE_NAME è consigliato su MUI_LANGUAGE_ID perché consente alla funzione di gestire meglio i linguaggi LIP che non corrispondono alle impostazioni locali predefinite, ma corrispondono invece a impostazioni locali supplementari. Le lingue LIP che corrispondono alle impostazioni locali predefinite vengono gestite proprio come le lingue non LIP.

Se viene specificato il flag MUI_LANGUAGE_ID, le stringhe di lingua specificate devono essere

usare identificatori di linguaggio esadecimali che non includono i caratteri iniziali 0x e sono 4 caratteri in lunghezza.

Ad esempio, en-US deve essere passato come "0409" e en come "0009". Le stringhe di lingua restituite saranno presenti nell'oggetto

stesso formato.

Quando MUI_LANGUAGE_ID viene specificato e se esiste una lingua di questo tipo nell'elenco delle lingue preferite dell'interfaccia utente, può essere presente una sola lingua nell'elenco. Tale lingua può essere specificata in pwmszLanguage come "1400", che corrisponde al valore esadecimale di LOCALE_CUSTOM_UI_DEFAULT. Nessun altro linguaggio può essere specificato usando MUI_LANGUAGE_ID. Usando "1000", che corrisponde al valore esadecimale di LOCALE_CUSTOM_UNSPECIFIED, nella stringa indicata da pwmszLanguage verrà generato un codice ERROR_INVALID_PARAMETER.

Un linguaggio parzialmente localizzato può avere un linguaggio di fallback parzialmente localizzato, richiedendo chiamate ripetute a GetUILanguageInfo per ottenere informazioni complete. Si consideri il caso di una lingua parzialmente localizzata Lang1 che offre una scelta di tre lingue di fallback. Il linguaggio di fallback lang3 è parzialmente localizzato e offre una scelta di due lingue di fallback. Le dipendenze sono le seguenti, con il fallback predefinito elencato prima:

Lang1
- Lang2
- Lang3
  - Lang5
  - Lang6
- Lang4

Per ottenere le lingue di fallback di Lang1, l'applicazione passa in pwmszLanguage come "Lang1\0\0". Al ritorno dalla funzione , pwszFallbackLanguages è impostato su "Lang2\0Lang3\0Lang4\0\0". Si noti che l'ordinamento di questo elenco indica che Lang2 è il linguaggio di fallback predefinito.

Per ottenere le lingue di fallback di Lang3 in relazione a Lang1, l'applicazione passa in pwmszLanguage come "lang1\0\lang3\0\0\0". Al ritorno dalla funzione , pwszFallbackLanguages è impostato su "Lang5\0Lang6\0\0".

Questa funzione restituisce ERROR_INVALID_PARAMETER per uno dei seguenti elementi:

pwmszLanguage è NULL o vuoto.
Vengono impostati sia MUI_LANGUAGE_ID che MUI_LANGUAGE_NAME.
Vengono impostati flag diversi da MUI_LANGUAGE_ID o MUI_LANGUAGE_NAME.
pcchFallbackLanguages è maggiore di 0 ma pwszFallbackLanguages è NULL.
pwmszLanguage non può essere analizzato come buffer a più stringhe di identificatori di lingua o nomi di lingua, a seconda dell'impostazione del flag.

Il codice di errore ERROR_OBJECT_NAME_NOT_FOUND si verifica se pwmszLanguage può essere analizzato, ma non è valido. Il codice potrebbe anche essere restituito per un identificatore delle impostazioni locali non valido o se la prima lingua nell'elenco di input non è una lingua installata o se un linguaggio completamente localizzato ha definito un linguaggio di fallback.

Firma C#

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean GetUILanguageInfo(
            System.UInt32 dwFlags,
            System.String pwmszLanguage,
            System.IntPtr pwszFallbackLanguages,
            ref System.UInt32 pcchFallbackLanguages,
            ref System.UInt32 pdwAttributes
            );

Requisiti

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

Vedere anche

EnumUILanguages

GetFileMUIInfo

Interfaccia utente multilingue

Funzioni dell'interfaccia utente multilingue

Condividi tramite