Função FindNLSString (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 identificador.

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.

Nota Por motivos de interoperabilidade, o aplicativo deve preferir a função FindNLSStringEx porque a Microsoft está migrando para o uso de nomes de localidade em vez de identificadores de localidade para novas localidades. Embora o FindNLSString dê suporte a localidades personalizadas, a maioria dos aplicativos deve usar FindNLSStringEx para esse tipo de suporte.

Sintaxe

int FindNLSString(
  [in]            LCID    Locale,
  [in]            DWORD   dwFindNLSStringFlags,
  [in]            LPCWSTR lpStringSource,
  [in]            int     cchSource,
  [in]            LPCWSTR lpStringValue,
  [in]            int     cchValue,
  [out, optional] LPINT   pcchFound
);

Parâmetros

[in] Locale

Identificador de localidade que especifica a localidade. Você pode usar a macro MAKELCID para criar um identificador ou usar um dos seguintes valores predefinidos.

Windows Vista e posterior: Também há suporte para os seguintes identificadores de localidade personalizados.

[in] dwFindNLSStringFlags

Sinalizadores especificando detalhes da operação de localização. Para obter definições detalhadas, consulte o parâmetro dwFindNLSStringFlags de FindNLSStringEx.

[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. Para obter detalhes, consulte o parâmetro pcchFound de FindNLSStringEx.

Retornar valor

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

Consulte Comentários para FindNLSStringEx.

Requisitos

Requisito	Valor
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