FindNLSStringEx 함수(winnls.h)

아티클
08/27/2023

이름으로 지정된 로캘의 다른 유니코드 문자열에서 유니코드 문자열(와이드 문자) 또는 해당 문자열을 찾습니다.

주의 이진 표현이 매우 다른 문자열은 동일하게 비교할 수 있으므로 이 함수는 특정 보안 문제를 제기할 수 있습니다. 자세한 내용은 보안 고려 사항: 국가별 기능에서 비교 함수에 대한 설명을 참조하세요.

구문

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
);

매개 변수

[in, optional] lpLocaleName

로캘 이름 또는 다음 미리 정의된 값 중 하나에 대한 포인터입니다.

[in] dwFindNLSStringFlags

찾기 작업의 세부 정보를 지정하는 플래그입니다. 이러한 플래그는 상호 배타적이며 FIND_FROMSTART 기본값입니다. 애플리케이션은 다음 표에 정의된 필터링 플래그를 사용하여 찾기 플래그 중 하나만 지정할 수 있습니다. 애플리케이션에서 플래그를 지정하지 않으면 함수는 지정된 로캘에 대한 기본 비교를 사용합니다. 애플리케이션에서 정렬 처리에서 설명한 대로 이진 비교 모드는 없습니다.

값	의미
FIND_FROMSTART	문자열의 첫 번째 문자부터 시작하여 문자열을 검색합니다.
FIND_FROMEND	문자열의 마지막 문자부터 시작하여 역방향으로 문자열을 검색합니다.
FIND_STARTSWITH	lpStringValue로 지정된 값이 lpStringSource로 표시된 원본 문자열의 첫 번째 값인지 확인하도록 테스트합니다.
FIND_ENDSWITH	lpStringValue로 지정된 값이 lpStringSource로 표시된 원본 문자열의 마지막 값인지 확인하도록 테스트합니다.

애플리케이션은 찾기 플래그와 함께 아래에 정의된 필터링 플래그를 사용할 수 있습니다.

값	의미
LINGUISTIC_IGNORECASE	검색에서 대/소문자를 언어적으로 적절하게 무시합니다. 자세한 내용은 주의 섹션을 참조하세요.
LINGUISTIC_IGNOREDIACRITIC	언어적으로 적절한 분음 부호를 무시합니다. 자세한 내용은 주의 섹션을 참조하세요. 참고 이 플래그는 분해된 문자와 함께 사용될 때 항상 예측 가능한 결과를 생성하지는 않습니다. 즉, 기본 문자와 하나 이상의 비스페이스 문자가 각각 고유한 코드 포인트 값을 갖는 문자입니다.
NORM_IGNORECASE	검색에서 대/소문자를 무시합니다. 자세한 내용은 주의 섹션을 참조하세요.
NORM_IGNOREKANATYPE	히라가나와 가타카나 문자를 구분하지 마십시오. 해당 히라가나와 가타카나 문자는 동일하게 비교합니다.
NORM_IGNORENONSPACE	간격이 없는 문자를 무시합니다. 자세한 내용은 주의 섹션을 참조하세요.
NORM_IGNORESYMBOLS	기호 및 문장 부호를 무시합니다.
NORM_IGNOREWIDTH	반자 문자와 전체 너비 문자의 차이를 무시합니다(예: C a t == cat). 전체 너비 형식은 중국어 및 일본어 스크립트에서 사용되는 서식 구분입니다.
NORM_LINGUISTIC_CASING	파일 시스템 규칙(기본값) 대신 대/소문자 구분에 언어 규칙을 사용합니다. 자세한 내용은 주의 섹션을 참조하세요.

[in] lpStringSource

함수가 lpStringValue로 지정된 문자열을 검색하는 원본 문자열에 대한 포인터입니다.

[in] cchSource

lpStringSource로 표시된 문자열의 종료 null 문자를 제외한 문자의 크기입니다. 애플리케이션은 이 매개 변수에 대해 0 또는 -1 이외의 음수를 지정할 수 없습니다. 애플리케이션은 소스 문자열이 null로 종료되고 함수가 크기를 자동으로 계산해야 하는 경우 -1을 지정합니다.

[in] lpStringValue

함수가 원본 문자열에서 검색하는 검색 문자열에 대한 포인터입니다.

[in] cchValue

lpStringValue로 표시된 문자열의 종료 null 문자를 제외한 문자의 크기입니다. 애플리케이션은 이 매개 변수에 대해 0 또는 -1 이외의 음수를 지정할 수 없습니다. 검색 문자열이 null로 종료되고 함수가 크기를 자동으로 계산해야 하는 경우 애플리케이션은 -1을 지정합니다.

[out, optional] pcchFound

함수가 찾은 문자열의 길이를 포함하는 버퍼에 대한 포인터입니다. 문자열은 검색 문자열보다 길거나 짧을 수 있습니다. 함수가 검색 문자열을 찾지 못하면 이 매개 변수는 수정되지 않습니다.

함수는 이 매개 변수에서 NULL 을 검색할 수 있습니다. 이 경우 함수는 찾은 문자열의 길이가 원본 문자열의 길이와 다른지 표시하지 않습니다.

pcchFound의 값은 cchValue에 제공된 값과 동일한 경우가 많지만 다음과 같은 경우에 다를 수 있습니다.

cchValue에 제공된 값은 음수입니다.
문자열은 동일하지만 길이가 다릅니다. 예를 들어 "A" 및 "결합 링"(U+0041 U+030A)은 "A 링"(U+00c5)과 동일합니다.

[in, optional] lpVersionInformation

예약; 은 NULL이어야 합니다.

[in, optional] lpReserved

예약; 은 NULL이어야 합니다.

[in, optional] sortHandle

예약되었습니다. 0이어야 합니다.

반환 값

성공하면 lpStringSource 가 나타내는 원본 문자열에 0 기반 인덱스 를 반환합니다. pcchFound의 값과 함께 이 인덱스 는 원본 문자열에서 찾은 전체 문자열의 정확한 위치를 제공합니다. 반환 값 0은 원본 문자열에 대한 오류 없는 인덱스이며 일치하는 문자열은 오프셋 0의 원본 문자열에 있습니다.

함수가 성공하지 못하면 -1을 반환합니다. 확장된 오류 정보를 가져오기 위해 애플리케이션은 다음 오류 코드 중 하나를 반환할 수 있는 GetLastError를 호출할 수 있습니다.

ERROR_INVALID_FLAGS. 플래그에 제공된 값이 잘못되었습니다.
ERROR_INVALID_PARAMETER. 매개 변수 값이 잘못되었습니다.
ERROR_SUCCESS. 작업이 성공적으로 완료되었지만 결과가 생성되지 않았습니다.

설명

이 함수는 검색 방향, 문자 동등성 필터링 및 로캘별 필터링을 비롯한 다양한 검색 옵션을 제공합니다. 동등성은 함수 호출에 지정된 로캘 및 플래그에 따라 달라집니다. 필터링 플래그는 검색 결과를 변경할 수 있습니다. 예를 들어 검색을 수행할 때 함수가 대/소문자 또는 분음 부호를 무시하면 잠재적 일치 항목이 증가합니다.

기본적으로 이 함수는 로 캘 매개 변수가 터키어(터키) 또는 아제르바이잔어(아제르바이잔)를 지정하는 경우에도 소문자 "i"를 대문자 "I"에 매핑합니다. 터키어 또는 아제르바이잔어에 대해 이 동작을 재정의하려면 애플리케이션에서 NORM_LINGUISTIC_CASING 지정해야 합니다. 이 플래그가 올바른 로캘에 대해 지정된 경우 "ı"(소문자 점 없는 I)는 "I"(대문자 점 없는 I)의 소문자 형식이고 "i"(소문자 점선 I)는 소문자 형식인 "ı"(대문자 점선 I)입니다.

많은 스크립트(특히 라틴어 스크립트)의 경우 NORM_IGNORENONSPACE LINGUISTIC_IGNOREDIACRITIC 일치하고 NORM_IGNORECASE 다음과 같은 예외를 제외하고 LINGUISTIC_IGNORECASE 일치합니다.

NORM_IGNORENONSPACE 분음 부호인지 여부에 관계없이 보조 구분을 무시합니다. 한국어, 일본어, 중국어, 인덱스 언어 등에 대한 스크립트는 분음 부호 이외의 목적으로 이러한 구분을 사용합니다. LINGUISTIC_IGNOREDIACRITIC 단순히 두 번째 정렬 가중치를 무시하는 대신 실제 분음 부호만 무시합니다.
NORM_IGNORECASE 실제로 언어적 사례인지 여부에 관계없이 3차 구분을 무시합니다. 예를 들어 아랍어 및 인딕 스크립트에서 이 플래그는 문자의 대체 형식을 구분합니다. 그러나 차이점은 언어 사례에 해당하지 않습니다. LINGUISTIC_IGNORECASE 세 번째 정렬 가중치를 무시하는 대신 실제 언어 대/소문자만 무시합니다.

실패에 대해 0을 반환하는 다른 NLS API 함수와 달리 이 함수는 실패하면 -1을 반환합니다. 성공하면 0 기반 인덱스가 반환됩니다. 이 인덱스를 사용하면 함수가 일회용 오류 및 1자 버퍼 오버런을 방지할 수 있습니다.

이 함수는 성공한 경우에도 SetLastError 를 호출하는 몇 안 되는 NLS 함수 중 하나입니다. 검색 문자열과 일치하지 않을 때 스레드의 마지막 오류를 지우기 위해 이 호출을 수행합니다. 그러면 GetLastError에서 반환된 값이 지워지게 됩니다.

Windows 8부터: 앱이 Windows.Globalization 네임스페이스에서 이 함수에 언어 태그를 전달하는 경우 먼저 ResolveLocaleName을 호출하여 태그를 변환해야 합니다.

요구 사항


지원되는 최소 클라이언트	Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	winnls.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll