Compartilhar via


Função GetThreadPreferredUILanguages (winnls.h)

Recupera os idiomas de interface do usuário preferenciais do thread para o thread atual. Para obter mais informações, consulte Gerenciamento de linguagem de interface do usuário.

Sintaxe

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

Parâmetros

[in] dwFlags

Sinalizadores que identificam o formato de idioma e a filtragem. Os sinalizadores a seguir especificam o formato de idioma a ser usado para os idiomas de interface do usuário preferenciais do thread. Os sinalizadores são mutuamente exclusivos e o padrão é MUI_LANGUAGE_NAME.

Valor Significado
MUI_LANGUAGE_ID
Recupere as cadeias de caracteres de idioma no formato de identificador de idioma .
MUI_LANGUAGE_NAME
Recupere as cadeias de caracteres de idioma no formato de nome de idioma .
 

Os sinalizadores a seguir especificam a filtragem para a função a ser usada na recuperação dos idiomas de interface do usuário preferenciais do thread. O sinalizador padrão é MUI_MERGE_USER_FALLBACK.

Valor Significado
MUI_MERGE_SYSTEM_FALLBACK
Use o fallback do sistema para recuperar uma lista que corresponda exatamente à lista de idiomas usada pelo carregador de recursos. Esse sinalizador só pode ser usado em combinação com MUI_MERGE_USER_FALLBACK. Usar os sinalizadores em combinação altera o efeito usual de MUI_MERGE_USER_FALLBACK incluindo fallback e idiomas neutros na lista.
MUI_MERGE_USER_FALLBACK
Recupere uma lista composta que consiste nos idiomas de interface do usuário preferenciais do thread, seguidos por idiomas de interface do usuário preferenciais do processo, seguidos por qualquer idioma de interface do usuário preferencial do usuário que seja distinto deles, seguido pelo idioma de interface do usuário padrão do sistema, se ele ainda não estiver na lista. Se a lista de idiomas de interface do usuário preferencial do usuário estiver vazia, a função recuperará os idiomas de interface do usuário preferenciais do sistema. Esse sinalizador não pode ser combinado com MUI_THREAD_LANGUAGES.
MUI_THREAD_LANGUAGES
Recupere apenas os idiomas de interface do usuário preferenciais do thread para o thread atual ou uma lista vazia se nenhum idioma preferencial estiver definido para o thread atual. Esse sinalizador não pode ser combinado com MUI_MERGE_USER_FALLBACK ou MUI_MERGE_SYSTEM_FALLBACK.
MUI_UI_FALLBACK
Recupere uma lista completa de idiomas de interface do usuário preferenciais do thread juntamente com o fallback associado e os idiomas neutros. O uso desse sinalizador é equivalente à combinação de MUI_MERGE_SYSTEM_FALLBACK e MUI_MERGE_USER_FALLBACK. (Aplicável somente para Windows 7 e posterior).

[out] pulNumLanguages

Ponteiro para o número de idiomas recuperados em pwszLanguagesBuffer.

[out, optional] pwszLanguagesBuffer

Opcional. Ponteiro para um buffer no qual essa função recupera uma lista de idiomas de interface do usuário preferenciais de thread delimitado por nulo ordenado, no formato especificado por dwFlags. Essa lista termina com dois caracteres nulos.

Como alternativa, se esse parâmetro for definido como NULL e pcchLanguagesBuffer estiver definido como 0, a função recuperará o tamanho necessário do buffer de idioma em pcchLanguagesBuffer. O tamanho necessário inclui os dois caracteres nulos.

[in, out] pcchLanguagesBuffer

Ponteiro para o tamanho, em caracteres, para o buffer de idioma indicado por pwszLanguagesBuffer. No retorno bem-sucedido da função, o parâmetro contém o tamanho do buffer de idioma recuperado.

Como alternativa, se esse parâmetro for definido como 0 e pwszLanguagesBuffer estiver definido como NULL, a função recuperará o tamanho necessário do buffer de idioma em pcchLanguagesBuffer.

Valor retornado

Retornará TRUE se tiver êxito ou FALSE caso contrário. Para obter informações de erro estendidas, o aplicativo pode chamar GetLastError, que retorna um dos seguintes códigos de erro:

  • ERROR_INSUFFICIENT_BUFFER. Um tamanho de buffer fornecido não era grande o suficiente ou estava definido incorretamente como NULL.

Se a função falhar por qualquer outro motivo, os parâmetros pulNumLanguages e pcchLanguagesBuffer serão indefinidos.

Comentários

Dependendo dos sinalizadores especificados pelo aplicativo, essa função pode recuperar uma lista composta que consiste nos idiomas de interface do usuário preferenciais do thread, processar idiomas de interface do usuário preferenciais, idiomas de interface do usuário preferenciais do usuário ou idiomas de interface do usuário preferenciais do sistema e o idioma da interface do usuário padrão do sistema. Se encontrar uma linguagem duplicada, a função só recuperará o primeiro idioma.

Se o aplicativo tiver chamado SetThreadPreferredUILanguages com o sinalizador MUI_CONSOLE_FILTER ou MUI_COMPLEX_SCRIPT_FILTER, GetThreadPreferredUILanguages filtrará os idiomas na lista de resultados. A função substitui os idiomas que o console não pode exibir por um idioma substituto. A substituição de um idioma é determinada pelo valor de LOCALE_SCONSOLEFALLBACKNAME para o idioma. Para obter mais informações do console, consulte a descrição de SetThreadUILanguage.

O uso de MUI_LANGUAGE_NAME é recomendado em MUI_LANGUAGE_ID porque o sinalizador MUI_LANGUAGE_NAME pode fazer um trabalho melhor de manipulação de idiomas lip (Language Interface Pack) que correspondem a localidades complementares.

Quando MUI_LANGUAGE_ID for especificado, as cadeias de caracteres de idioma recuperadas serão identificadores de linguagem hexadecimal

que não incluem o 0x à esquerda e terão 4 caracteres de comprimento. Por exemplo, en-US será retornado

como "0409" e en como "0009".

Se o aplicativo definir o sinalizador MUI_LANGUAGE_ID, os idiomas de interface do usuário preferenciais do thread poderão incluir um ou mais idiomas que correspondam a localidades complementares. No retorno bem-sucedido da função, o buffer de idioma contém "1400" para qualquer idioma correspondente a uma localidade complementar. Só pode haver um idioma dessa forma nesta lista. A cadeia de caracteres "1400" corresponde ao valor hexadecimal de LOCALE_CUSTOM_UI_DEFAULT. Também no retorno bem-sucedido da função, o pwszLanguagesBuffer contém "1000" para qualquer outro idioma que corresponda a uma localidade complementar. A cadeia de caracteres "1000" corresponde ao valor hexadecimal de LOCALE_CUSTOM_UNSPECIFIED, que não é útil como entrada para qualquer função, pois não pode distinguir entre localidades complementares.

Assinatura do 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
            );

Requisitos

   
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho winnls.h (inclua Windows.h)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

GetThreadUILanguage

Interface do Usuário Multilíngue

Funções de interface do usuário multilíngue

SetThreadPreferredUILanguages

SetThreadUILanguage