Função FindNLSStringEx (winnls.h)

Artigo
08/27/2023

Localiza uma cadeia de caracteres Unicode (caracteres largos) ou seu equivalente em outra cadeia de caracteres Unicode para uma localidade especificada pelo nome.

Cuidado Como cadeias de caracteres com representações binárias muito diferentes podem ser comparadas como idênticas, essa função pode gerar certas preocupações de segurança. Para obter mais informações, consulte a discussão de funções de comparação em Considerações de segurança: recursos internacionais.

Sintaxe

int FindNLSStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFindNLSStringFlags,
  [in]            LPCWSTR          lpStringSource,
  [in]            int              cchSource,
  [in]            LPCWSTR          lpStringValue,
  [in]            int              cchValue,
  [out, optional] LPINT            pcchFound,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

Parâmetros

[in, optional] lpLocaleName

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

[in] dwFindNLSStringFlags

Sinalizadores especificando detalhes da operação de localização. Esses sinalizadores são mutuamente exclusivos, com FIND_FROMSTART sendo o padrão. O aplicativo pode especificar apenas um dos sinalizadores de localização com qualquer um dos sinalizadores de filtragem definidos na próxima tabela. Se o aplicativo não especificar um sinalizador, a função usará a comparação padrão para a localidade especificada. Conforme discutido em Tratamento de Classificação em Seus Aplicativos, não há modo de comparação binária.

Valor	Significado
FIND_FROMSTART	Pesquise a cadeia de caracteres, começando com o primeiro caractere da cadeia de caracteres.
FIND_FROMEND	Pesquise a cadeia de caracteres na direção inversa, começando com o último caractere da cadeia de caracteres.
FIND_STARTSWITH	Teste para descobrir se o valor especificado por lpStringValue é o primeiro valor na cadeia de caracteres de origem indicada por lpStringSource.
FIND_ENDSWITH	Teste para descobrir se o valor especificado por lpStringValue é o último valor na cadeia de caracteres de origem indicada por lpStringSource.

O aplicativo pode usar os sinalizadores de filtragem definidos abaixo em combinação com um sinalizador de localização.

Valor	Significado
LINGUISTIC_IGNORECASE	Ignore o caso na pesquisa, conforme linguisticamente apropriado. Para obter mais informações, consulte a seção Comentários.
LINGUISTIC_IGNOREDIACRITIC	Ignorar diacríticos, conforme linguisticamente apropriado. Para obter mais informações, consulte a seção Comentários. Nota Esse sinalizador nem sempre produz resultados previsíveis quando usado com caracteres decompostos, ou seja, caracteres em que um caractere base e um ou mais caracteres sem espaçamento têm valores de ponto de código distintos.
NORM_IGNORECASE	Ignorar maiúsculas e minúsculas na pesquisa. Para obter mais informações, consulte a seção Comentários.
NORM_IGNOREKANATYPE	Não diferencie entre caracteres hiragana e katakana. Os caracteres hiragana e katakana correspondentes são comparados como iguais.
NORM_IGNORENONSPACE	Ignorar caracteres sem espaçamento. Para obter mais informações, consulte a seção Comentários.
NORM_IGNORESYMBOLS	Ignorar símbolos e pontuação.
NORM_IGNOREWIDTH	Ignore a diferença entre caracteres de meia largura e largura total, por exemplo, C a t == cat. A forma de largura total é uma distinção de formatação usada em scripts chineses e japoneses.
NORM_LINGUISTIC_CASING	Use regras linguísticas para uso de maiúsculas e minúsculas, em vez de regras do sistema de arquivos (padrão). Para obter mais informações, consulte a seção Comentários.

[in] lpStringSource

Ponteiro para a cadeia de caracteres de origem, na qual a função pesquisa a cadeia de caracteres especificada por lpStringValue.

[in] cchSource

Tamanho, em caracteres excluindo o caractere nulo de terminação, da cadeia de caracteres indicada por lpStringSource. O aplicativo não pode especificar 0 ou nenhum número negativo diferente de -1 para esse parâmetro. O aplicativo especifica -1 se a cadeia de caracteres de origem for terminada em nulo e a função deverá calcular o tamanho automaticamente.

[in] lpStringValue

Ponteiro para a cadeia de caracteres de pesquisa, para a qual a função pesquisa na cadeia de caracteres de origem.

[in] cchValue

Tamanho, em caracteres excluindo o caractere nulo de terminação, da cadeia de caracteres indicada por lpStringValue. O aplicativo não pode especificar 0 ou nenhum número negativo diferente de -1 para esse parâmetro. O aplicativo especifica -1 se a cadeia de caracteres de pesquisa for terminada em nulo e a função deverá calcular o tamanho automaticamente.

[out, optional] pcchFound

Ponteiro para um buffer que contém o comprimento da cadeia de caracteres que a função encontra. A cadeia de caracteres pode ser maior ou menor do que a cadeia de caracteres de pesquisa. Se a função não encontrar a cadeia de caracteres de pesquisa, esse parâmetro não será modificado.

A função pode recuperar NULL nesse parâmetro. Nesse caso, a função não indica se o comprimento da cadeia de caracteres encontrada difere do comprimento da cadeia de caracteres de origem.

Observe que o valor de pcchFound geralmente é idêntico ao valor fornecido em cchValue, mas pode ser diferente nos seguintes casos:

O valor fornecido em cchValue é negativo.
As cadeias de caracteres são equivalentes, mas têm comprimentos diferentes. Por exemplo, "A" mais "Combining Ring" (U+0041 U+030A) é equivalente ao "Anel A" (U+00c5).

[in, optional] lpVersionInformation

Reservados; deve ser NULL.

[in, optional] lpReserved

Reservados; deve ser NULL.

[in, optional] sortHandle

Reservados; deve ser 0.

Valor retornado

Retorna um índice baseado em 0 na cadeia de caracteres de origem indicada por lpStringSource se tiver êxito . Em combinação com o valor em pcchFound, esse índice fornece o local exato de toda a cadeia de caracteres encontrada na cadeia de caracteres de origem. Um valor retornado de 0 é um índice sem erros na cadeia de caracteres de origem e a cadeia de caracteres correspondente está na cadeia de caracteres de origem no deslocamento 0.

A função retornará -1 se não for bem-sucedida. Para obter informações de erro estendidas, o aplicativo pode chamar GetLastError, que pode retornar um dos seguintes códigos de erro:

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.
ERROR_SUCCESS. A ação foi concluída com êxito, mas não rendeu resultados.

Comentários

Essa função fornece uma variedade de opções de pesquisa, incluindo direção de pesquisa, filtragem de equivalência de caracteres e filtragem específica da localidade. Observe que a equivalência depende da localidade e dos sinalizadores especificados na chamada para a função. Os sinalizadores de filtragem podem alterar os resultados da pesquisa. Por exemplo, as possíveis correspondências aumentam quando a função ignora marcas de maiúsculas e minúsculas ou diacríticas ao executar a pesquisa.

Por padrão, essa função mapeia o "i" minúsculo para o maiúsculo "I", mesmo quando o parâmetro Locale especifica turco (Turquia) ou Azerbaijão (Azerbaijão). Para substituir esse comportamento para turco ou Azerbaijão, o aplicativo deve especificar NORM_LINGUISTIC_CASING. Se esse sinalizador for especificado para a localidade correta, "ı" (minúsculas sem ponto I) é a forma minúscula de "I" (maiúsculas e minúsculas sem ponto I) e "i" (minúsculas pontilhadas I) é a forma minúscula de "ı" (maiúscula pontilhada I).

Para muitos scripts (notadamente scripts latinos), NORM_IGNORENONSPACE coincide com LINGUISTIC_IGNOREDIACRITIC e NORM_IGNORECASE coincide com LINGUISTIC_IGNORECASE, com as seguintes exceções:

NORM_IGNORENONSPACE ignora qualquer distinção secundária, seja uma diacrítica ou não. Scripts para idiomas coreano, japonês, chinês, índice e outros usam essa distinção para fins diferentes de diacríticos. LINGUISTIC_IGNOREDIACRITIC ignora apenas os diacríticos reais, em vez de simplesmente ignorar o segundo peso de classificação.
NORM_IGNORECASE ignora qualquer distinção terciária, seja ou não um caso linguístico. Por exemplo, em scripts árabes e índices, esse sinalizador distingue formas alternativas de um caractere. No entanto, as diferenças não correspondem ao caso linguístico. LINGUISTIC_IGNORECASE ignora apenas maiúsculas e minúsculas linguísticas reais, em vez de ignorar o terceiro peso de classificação.

Ao contrário de outras funções da API nls, que retornam 0 para falha, essa função retornará -1 se falhar. Com êxito, ele retorna um índice baseado em 0. O uso desse índice ajuda a função a evitar erros off-by-one e estouros de buffer de um caractere.

Essa função é uma das poucas funções NLS que chama SetLastError mesmo quando é bem-sucedida. Ele faz essa chamada para limpar o último erro em um thread quando ele não corresponde à cadeia de caracteres de pesquisa. Isso limpa o valor retornado por GetLastError.

A partir do 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


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