NormalizeString 함수(winnls.h)

아티클
08/27/2023

유니코드 4.0 TR#15에 따라 텍스트 문자열의 문자를 정규화합니다. 자세한 내용은 유니코드 정규화를 사용하여 문자열 표시를 참조하세요.

구문

int NormalizeString(
  [in]            NORM_FORM NormForm,
  [in]            LPCWSTR   lpSrcString,
  [in]            int       cwSrcLength,
  [out, optional] LPWSTR    lpDstString,
  [in]            int       cwDstLength
);

매개 변수

[in] NormForm

사용할 정규화 양식입니다. NORM_FORM 표준 유니코드 정규화 양식을 지정합니다.

[in] lpSrcString

정규화되지 않은 소스 문자열에 대한 포인터입니다.

[in] cwSrcLength

원본 문자열을 포함하는 버퍼의 길이(문자)입니다. 함수가 문자열을 null로 종료한다고 가정하고 길이를 자동으로 계산해야 하는 경우 애플리케이션은 이 매개 변수를 -1로 설정할 수 있습니다.

[out, optional] lpDstString

함수가 대상 문자열을 검색하는 버퍼에 대한 포인터입니다. 또는 cwDstLength가 0으로 설정된 경우 이 매개 변수에는 NULL이 포함됩니다.

참고 입력 문자열 길이가 종료 null 문자 없이 명시적으로 지정된 경우 함수는 문자열을 null로 종료하지 않습니다. 출력 문자열을 null로 종료하려면 애플리케이션에서 -1을 지정하거나 입력 문자열의 종료 null 문자를 명시적으로 계산해야 합니다.

[in] cwDstLength

대상 문자열을 포함하는 버퍼의 길이(문자)입니다. 또는 애플리케이션에서 이 매개 변수를 0으로 설정하여 대상 버퍼에 필요한 크기를 반환하도록 함수를 요청할 수 있습니다.

반환 값

대상 버퍼에서 정규화된 문자열의 길이를 반환합니다. cwDstLength가 0으로 설정된 경우 함수는 실제 변환을 수행하는 데 필요한 예상 버퍼 길이를 반환합니다.

입력 버퍼의 문자열이 null로 종료되거나 cwSrcLength 가 -1이면 대상 버퍼에 기록된 문자열이 null로 종료되고 반환된 문자열 길이에 종료 null 문자가 포함됩니다.

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

ERROR_INSUFFICIENT_BUFFER. 제공된 버퍼 크기가 충분히 크지 않거나 NULL로 잘못 설정되었습니다.
ERROR_INVALID_PARAMETER. 매개 변수 값이 잘못되었습니다.
ERROR_NO_UNICODE_TRANSLATION. 문자열에서 잘못된 유니코드가 발견되었습니다. 반환 값은 입력 문자열에서 오류 위치의 인덱스 음수입니다.
ERROR_SUCCESS. 작업이 성공적으로 완료되었지만 결과가 생성되지 않았습니다.

설명

일부 유니코드 문자에는 결합 및/또는 복합 유니코드 문자 집합으로 구성된 여러 개의 동등한 이진 표현이 있습니다. 유니코드 표준은 문자에 해당하는 이진 표현이 제공되면 하나의 이진 표현을 반환하는 정규화라는 프로세스를 정의합니다. 정규화는 유니코드 정규화를 사용하여 문자열을 나타내는 데 설명된 대로 다른 규칙을 준수하는 정규화 양식이라는 여러 알고리즘을 사용하여 수행할 수 있습니다. Win32 및 .NET Framework 현재 유니코드 표준 부속서 #15: 유니코드 정규화 양식에 정의된 대로 C, D, KC 및 KD 정규화 형식을 지원합니다. 정규화된 문자열은 일반적으로 서수 비교를 사용하여 평가됩니다.

다음 코드는 버퍼 길이 예상 사용 방법을 보여 줍니다.

const int maxIterations = 10;
LPWSTR strResult = NULL;
HANDLE hHeap = GetProcessHeap();

int iSizeEstimated = NormalizeString(form, strInput, -1, NULL, 0);
for (int i = 0; i < maxIterations; i++)
{
    if (strResult)
        HeapFree(hHeap, 0, strResult);
    strResult = (LPWSTR)HeapAlloc(hHeap, 0, iSizeEstimated * sizeof (WCHAR));
    iSizeEstimated = NormalizeString(form, strInput, -1, strResult, iSizeEstimated);
 
    if (iSizeEstimated > 0)
        break; // success 
 
    if (iSizeEstimated <= 0)
    {
        DWORD dwError = GetLastError();
        if (dwError != ERROR_INSUFFICIENT_BUFFER) break; // Real error, not buffer error 
 
        // New guess is negative of the return value. 
        iSizeEstimated = -iSizeEstimated;
    }
}

Windows XP, Windows Server 2003:

더 이상 지원되지 않습니다.

필수 헤더 파일 및 DLL은 더 이상 다운로드할 수 없는 Microsoft IDN(Internationalized Domain Name) 완화 API의 일부입니다.

예제

이 함수의 사용을 보여 주는 예제는 NLS: 유니코드 정규화 샘플에서 찾을 수 있습니다.

요구 사항


지원되는 최소 클라이언트	Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	winnls.h(Windows.h 포함)
DLL	Normaliz.dll
재배포 가능 파일	MICROSOFT IDN(Internationalized Domain Name) 완화 API onWindows XP with SP2 이상, 또는Windows Server 2003 with SP1