Função IsNLSDefinedString (winnls.h)

Artigo
08/27/2023

Determina se cada caractere em uma cadeia de caracteres tem um resultado definido para uma funcionalidade de NLS especificada.

Sintaxe

BOOL IsNLSDefinedString(
  [in] NLS_FUNCTION     Function,
  [in] DWORD            dwFlags,
  [in] LPNLSVERSIONINFO lpVersionInformation,
  [in] LPCWSTR          lpString,
  [in] INT              cchStr
);

Parâmetros

[in] Function

Funcionalidade de NLS para consultar. Esse valor deve ser COMPARE_STRING. Consulte a enumeração SYSNLS_FUNCTION .

[in] dwFlags

Sinalizadores definindo a função. Deve ser 0.

[in] lpVersionInformation

Ponteiro para uma estrutura NLSVERSIONINFO que contém informações de versão. Normalmente, as informações são obtidas chamando GetNLSVersion. O aplicativo define esse parâmetro como NULL se a função for usar a versão atual.

[in] lpString

Ponteiro para a cadeia de caracteres UTF-16 a ser examinada.

[in] cchStr

Número de caracteres UTF-16 na cadeia de caracteres indicada por lpString. Essa contagem pode incluir um caractere nulo de terminação. Se o caractere nulo de terminação estiver incluído na contagem de caracteres, ele não afetará o comportamento de verificação porque o caractere nulo de terminação sempre será definido.

O aplicativo deve fornecer -1 para indicar que a cadeia de caracteres foi terminada em nulo. Nesse caso, a função em si calcula o comprimento da cadeia de caracteres.

Valor retornado

Retorna TRUE se tiver êxito, somente se a cadeia de caracteres de entrada for válida 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 diferencia entre cadeias de caracteres definidas e indefinidas, para que um aplicativo como o Active Directory possa rejeitar cadeias de caracteres com pontos de código indefinidos. O uso da função pode minimizar a necessidade de o aplicativo indexar novamente seu banco de dados. Para obter mais informações, consulte Manipulando a classificação em seus aplicativos.

Por exemplo, se Function for definido como COMPARE_STRING, IsNLSDefinedString verificará pontos de código indefinidos, pares alternativos que representam caracteres Unicode indefinidos ou pares alternativos mal formados. Se a função retornar TRUE para uma cadeia de caracteres específica, os resultados, conforme recuperados por CompareString ou LCMapString com LCMAP_SORTKEY conjunto, terão a garantia de serem idênticos, desde que a versão correspondente do NLS não seja alterada.

Requisitos


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