Função GetNLSVersionEx (winnls.h)

Artigo
03/13/2024

Recupera informações sobre a versão atual de um recurso de NLS especificado para uma localidade especificada por nome.

Nota O aplicativo deve chamar essa função em preferência para GetNLSVersion se projetado para ser executado somente no Windows Vista e posterior.

Sintaxe

BOOL GetNLSVersionEx(
  [in]           NLS_FUNCTION       function,
  [in, optional] LPCWSTR            lpLocaleName,
  [in, out]      LPNLSVERSIONINFOEX lpVersionInformation
);

Parâmetros

[in] function

A funcionalidade nls para consultar. Esse valor deve ser COMPARE_STRING. Consulte a enumeração SYSNLS_FUNCTION .

[in, optional] lpLocaleName

Ponteiro para um nome de localidade ou um dos seguintes valores predefinidos.

[in, out] lpVersionInformation

Ponteiro para uma estrutura NLSVERSIONINFOEX . O aplicativo deve inicializar o membro dwNLSVersionInfoSize para sizeof(NLSVERSIONINFOEX).

Nota No Windows Vista e posteriores, a função pode, como alternativa, fornecer informações de versão em uma estrutura NLSVERSIONINFO .

Retornar valor

Retornará TRUE se e somente se o aplicativo tiver fornecido valores válidos em lpVersionInformation 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.
ERROR_INVALID_FLAGS. Os valores fornecidos para sinalizadores não eram válidos.
ERROR_INVALID_PARAMETER. Qualquer um dos valores de parâmetro era inválido.

Comentários

Essa função permite que um aplicativo como o Active Directory determine se uma alteração de NLS afeta a localidade usada para uma tabela de índice específica. Se isso não acontecer, não será necessário indexar novamente a tabela. Para obter mais informações, consulte Manipulando a classificação em seus aplicativos. Em particular, para saber se uma versão de classificação foi alterada e você precisa reindexar:

Use GetNLSVersionEx para recuperar uma estrutura NLSVERSIONINFOEX ao fazer a indexação original de seus dados.
Armazene as seguintes propriedades com seu índice para identificar a versão:
- NLSVERSIONINFOEX.dwNLSVersion. Isso especifica a versão da tabela de classificação que você está usando.
- NLSVERSIONINFOEX.dwEffectiveId. Isso especifica a localidade efetiva da sua classificação. Uma localidade personalizada apontará para a classificação de uma localidade in-box.
- NLSVERSIONINFOEX.guidCustomVersion. Esse é um GUID que especifica uma classificação personalizada específica para localidades personalizadas que as têm.
Ao usar o índice, use GetNLSVersionEx para descobrir a versão dos dados.
Se qualquer uma das três propriedades tiver sido alterada, os dados de classificação que você está usando poderão retornar resultados diferentes e qualquer indexação que você tiver poderá não encontrar registros.
Se você souber que seus dados não contêm pontos de código Unicode inválidos (ou seja, todas as cadeias de caracteres passaram uma chamada para IsNLSDefinedString), poderá considerá-los da mesma forma se apenas o byte baixo de dwNLSVersion for alterado (a versão secundária descrita acima).

Isso é abordado com mais detalhes na entrada do blog "Como saber se a versão de ordenação foi alterada" (http://blogs.msdn.com/shawnste/archive/2007/06/01/how-to-tell-if-the-collation-version-changed.aspx).

Essa função dá suporte a localidades personalizadas. Se lpLocaleName especificar uma localidade suplementar, os dados recuperados serão os dados corretos para a ordem de classificação associada a essa localidade suplementar.

Começando no Windows 8: se o aplicativo passar marcas de idioma para essa função do namespace Windows.Globalization, ele deverá primeiro converter as marcas chamando ResolveLocaleName.

Requisitos

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