Función FindNLSStringEx (winnls.h)

Artículo
08/27/2023

Busca una cadena Unicode (caracteres anchos) o su equivalente en otra cadena Unicode para una configuración regional especificada por nombre.

Precaución Dado que las cadenas con representaciones binarias muy diferentes pueden compararse como idénticas, esta función puede generar ciertos problemas de seguridad. Para obtener más información, vea la explicación de las funciones de comparación en Consideraciones de seguridad: Características internacionales.

Sintaxis

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

Puntero a un nombre de configuración regional o uno de los siguientes valores predefinidos.

[in] dwFindNLSStringFlags

Marcas que especifican detalles de la operación de búsqueda. Estas marcas son mutuamente excluyentes, con FIND_FROMSTART siendo el valor predeterminado. La aplicación puede especificar solo una de las marcas de búsqueda con cualquiera de las marcas de filtrado definidas en la tabla siguiente. Si la aplicación no especifica una marca, la función usa la comparación predeterminada para la configuración regional especificada. Como se describe en Control de la ordenación en las aplicaciones, no hay ningún modo de comparación binaria.

Valor	Significado
FIND_FROMSTART	Busque la cadena, empezando por el primer carácter de la cadena.
FIND_FROMEND	Busque la cadena en la dirección inversa, empezando por el último carácter de la cadena.
FIND_STARTSWITH	Pruebe para averiguar si el valor especificado por lpStringValue es el primer valor de la cadena de origen indicado por lpStringSource.
FIND_ENDSWITH	Pruebe para averiguar si el valor especificado por lpStringValue es el último valor de la cadena de origen indicado por lpStringSource.

La aplicación puede usar las marcas de filtrado definidas a continuación en combinación con una marca de búsqueda.

Valor	Significado
LINGUISTIC_IGNORECASE	Omita mayúsculas y minúsculas en la búsqueda, según corresponda lingüísticamente. Para obtener más información, vea la sección Comentarios.
LINGUISTIC_IGNOREDIACRITIC	Omita los diacríticos, según corresponda lingüísticamente. Para obtener más información, vea la sección Comentarios. Nota Esta marca no siempre genera resultados predecibles cuando se usan con caracteres descomponidos, es decir, caracteres en los que un carácter base y uno o varios caracteres sin espaciado tienen valores de punto de código distintos.
NORM_IGNORECASE	Omita mayúsculas y minúsculas en la búsqueda. Para obtener más información, vea la sección Comentarios.
NORM_IGNOREKANATYPE	No diferencie entre caracteres hiragana y katakana. Los caracteres hiragana y katakana correspondientes se comparan como iguales.
NORM_IGNORENONSPACE	Omitir caracteres sin espaciado. Para obtener más información, vea la sección Comentarios.
NORM_IGNORESYMBOLS	Omitir símbolos y puntuación.
NORM_IGNOREWIDTH	Omita la diferencia entre los caracteres de ancho medio y ancho completo, por ejemplo, C a t == cat. El formato de ancho completo es una distinción de formato que se usa en scripts chinos y japoneses.
NORM_LINGUISTIC_CASING	Use reglas lingüísticas para el uso de mayúsculas y minúsculas, en lugar de las reglas del sistema de archivos (valor predeterminado). Para obtener más información, vea la sección Comentarios.

[in] lpStringSource

Puntero a la cadena de origen, en la que la función busca la cadena especificada por lpStringValue.

[in] cchSource

Tamaño, en caracteres excepto el carácter nulo de terminación, de la cadena indicada por lpStringSource. La aplicación no puede especificar 0 o ningún número negativo distinto de -1 para este parámetro. La aplicación especifica -1 si la cadena de origen termina en null y la función debe calcular el tamaño automáticamente.

[in] lpStringValue

Puntero a la cadena de búsqueda, para la que la función busca en la cadena de origen.

[in] cchValue

Tamaño, en caracteres excepto el carácter nulo de terminación, de la cadena indicada por lpStringValue. La aplicación no puede especificar 0 o ningún número negativo distinto de -1 para este parámetro. La aplicación especifica -1 si la cadena de búsqueda termina en null y la función debe calcular el tamaño automáticamente.

[out, optional] pcchFound

Puntero a un búfer que contiene la longitud de la cadena que encuentra la función. La cadena puede ser más larga o más corta que la cadena de búsqueda. Si la función no encuentra la cadena de búsqueda, este parámetro no se modifica.

La función puede recuperar NULL en este parámetro. En este caso, la función no indica si la longitud de la cadena encontrada difiere de la longitud de la cadena de origen.

Tenga en cuenta que el valor de pcchFound suele ser idéntico al valor proporcionado en cchValue, pero puede diferir en los casos siguientes:

El valor proporcionado en cchValue es negativo.
Las cadenas son equivalentes, pero tienen longitudes diferentes. Por ejemplo, "A" más "Anillo combinado" (U+0041 U+030A) es equivalente al "Anillo A" (U+00c5).

[in, optional] lpVersionInformation

Reservados; debe ser NULL.

[in, optional] lpReserved

Reservados; debe ser NULL.

[in, optional] sortHandle

Reservados; debe ser 0.

Valor devuelto

Devuelve un índice basado en 0 en la cadena de origen indicada por lpStringSource si se ejecuta correctamente. En combinación con el valor de pcchFound, este índice proporciona la ubicación exacta de toda la cadena encontrada en la cadena de origen. Un valor devuelto de 0 es un índice sin errores en la cadena de origen y la cadena coincidente se encuentra en la cadena de origen en el desplazamiento 0.

La función devuelve -1 si no se realiza correctamente. Para obtener información de error extendida, la aplicación puede llamar a GetLastError, que puede devolver uno de los siguientes códigos de error:

ERROR_INVALID_FLAGS. Los valores proporcionados para las marcas no eran válidos.
ERROR_INVALID_PARAMETER. Cualquiera de los valores de parámetro no era válido.
ERROR_SUCCESS. La acción se completó correctamente, pero no produjo ningún resultado.

Comentarios

Esta función proporciona una variedad de opciones de búsqueda, como la dirección de búsqueda, el filtrado de equivalencia de caracteres y el filtrado específico de la configuración regional. Tenga en cuenta que la equivalencia depende de la configuración regional y las marcas especificadas en la llamada a la función. Las marcas de filtrado pueden modificar los resultados de la búsqueda. Por ejemplo, las posibles coincidencias aumentan cuando la función omite las marcas diacríticas o mayúsculas de minúsculas al realizar la búsqueda.

De forma predeterminada, esta función asigna el "i" en minúsculas a la "I" mayúscula, incluso cuando el parámetro Locale especifica Turco (Turquía) o Azerbaiyano (Azerbaiyán). Para invalidar este comportamiento para turco o azerbaiyano, la aplicación debe especificar NORM_LINGUISTIC_CASING. Si se especifica esta marca para la configuración regional correcta, "ı" (I sin puntos en minúsculas) es la forma minúscula de "I" (I sin puntos en mayúsculas) y "i" (punto en minúscula I) es la forma minúscula de "ı" (punto en mayúsculaS I).

Para muchos scripts (en particular alfabetos latinos), NORM_IGNORENONSPACE coincide con LINGUISTIC_IGNOREDIACRITIC y NORM_IGNORECASE coincide con LINGUISTIC_IGNORECASE, con las siguientes excepciones:

NORM_IGNORENONSPACE omite cualquier distinción secundaria, si es o no un diacrítico. Los scripts para los idiomas coreano, japonés, chino, indic y otros usan esta distinción con fines distintos de los diacríticos. LINGUISTIC_IGNOREDIACRITIC omite solo los diacríticos reales, en lugar de simplemente ignorar el segundo peso de ordenación.
NORM_IGNORECASE omite cualquier distinción terciaria, independientemente de si es o no un caso lingüístico. Por ejemplo, en scripts arábigos e indices, esta marca distingue las formas alternativas de un carácter. Sin embargo, las diferencias no corresponden al caso lingüístico. LINGUISTIC_IGNORECASE omite solo mayúsculas y minúsculas lingüísticas reales, en lugar de omitir el tercer peso de ordenación.

A diferencia de otras funciones de la API nlS, que devuelven 0 para error, esta función devuelve -1 si se produce un error. Si se ejecuta correctamente, devuelve un índice basado en 0. El uso de este índice ayuda a la función a evitar errores desactivados y saturaciones de búfer de un solo carácter.

Esta función es una de las pocas funciones NLS que llama a SetLastError incluso cuando se realiza correctamente. Realiza esta llamada para borrar el último error de un subproceso cuando no coincide con la cadena de búsqueda. Esto borra el valor devuelto por GetLastError.

A partir de Windows 8: Si la aplicación pasa etiquetas de idioma a esta función desde el espacio de nombres Windows.Globalization , primero debe convertir las etiquetas mediante una llamada a ResolveLocaleName.

Requisitos


Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winnls.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll