Função GetSystemPreferredUILanguages (winnls.h)

Artigo
08/27/2023

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

Sintaxe

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

Parâmetros

[in] dwFlags

Sinalizadores que identificam o formato de linguagem e a filtragem. Os sinalizadores a seguir especificam o formato a ser usado para os idiomas de interface do usuário preferenciais do sistema. 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 do idioma .

O sinalizador a seguir especifica se a função deve validar a lista de idiomas (padrão) ou recuperar a lista de idiomas de interface do usuário preferenciais do sistema exatamente como ela é armazenada no registro.

Valor	Significado
MUI_MACHINE_LANGUAGE_SETTINGS	Recupere a lista de idiomas de interface do usuário preferenciais do sistema armazenado, verificando apenas para garantir que cada nome de idioma corresponda a uma localidade válida do NLS. Se esse sinalizador não estiver definido, a função recuperará as linguagens de interface do usuário preferenciais do sistema em pwszLanguagesBuffer, desde que a lista não esteja vazia e atenda aos critérios de validação. Caso contrário, a função recuperará a linguagem de interface do usuário padrão do sistema no buffer de idioma.

Valor

Significado

MUI_MACHINE_LANGUAGE_SETTINGS

Recupere a lista de idiomas de interface do usuário preferenciais do sistema armazenado, verificando apenas para garantir que cada nome de idioma corresponda a uma localidade válida do NLS. Se esse sinalizador não estiver definido, a função recuperará as linguagens de interface do usuário preferenciais do sistema em pwszLanguagesBuffer, desde que a lista não esteja vazia e atenda aos critérios de validação. Caso contrário, a função recuperará a linguagem de interface do usuário padrão do sistema no buffer de idioma.

[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 do sistema delimitada por nulo ordenada, 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 no 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 no 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 pode retornar um dos seguintes códigos de erro:

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

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

Comentários

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á 4 caracteres de comprimento. Por exemplo, en-US será retornado

como "0409" e en como "0009".

As linguagens de interface do usuário preferenciais do sistema não podem incluir mais de uma linguagem LIP (Language Interface Pack) que corresponda a uma localidade complementar. Se a lista incluir mais de um desses idiomas e se o aplicativo especificar MUI_LANGUAGE_ID na chamada para a função, o buffer de idioma conterá "1400" para esse idioma. Essa cadeia de caracteres corresponde ao valor hexadecimal de LOCALE_CUSTOM_UI_DEFAULT.

Se o sinalizador MUI_MACHINE_LANGUAGE_SETTINGS estiver definido, essa função verificará cada idioma na lista que representa uma localidade válida do NLS. A lista recuperada pode conter os seguintes itens:

Idiomas não instalados no sistema
Entradas de idioma duplicadas
Uma cadeia de caracteres vazia

Se o sinalizador MUI_MACHINE_LANGUAGE_SETTINGS estiver definido e a lista de idiomas de interface do usuário preferenciais do sistema estiver vazia, a função recuperará uma cadeia de caracteres vazia no buffer de idioma (dois caracteres nulos, pois é um buffer de várias cadeias de caracteres), 0 para o número de idiomas e 2 para o tamanho do buffer.

Se o sinalizador MUI_MACHINE_LANGUAGE_SETTINGS não estiver definido, a lista de idiomas recuperada terá as seguintes características:

Cada idioma representa uma localidade válida do NLS.
Cada idioma é instalado no sistema operacional.
A lista contém uma entrada para cada idioma, sem entradas duplicadas.

Assinatura do C#

[DllImport("Kernel32.dll", CharSet = CharSet.Auto)]
        static extern System.Boolean GetSystemPreferredUILanguages(
            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