다음을 통해 공유


IdnToAscii 함수(winnls.h)

IDN(국제화된 도메인 이름) 또는 다른 국제화된 레이블을 Punycode 전송 인코딩 구문의 이름을 나타내는 ASCII 문자열의 유니코드(와이드 문자) 표현으로 변환합니다.

주의 이 함수는 IDN을 Punycode로 변환 하기 위한 RFC 3490: IDNA(애플리케이션의 도메인 이름 국제화) 표준 알고리즘을 구현합니다. 표준에는 몇 가지 보안 문제가 도입되었습니다. 한 가지 문제는 다른 스크립트의 특정 문자를 나타내는 문자 모양이 유사하거나 동일하게 나타날 수 있다는 것입니다. 예를 들어 많은 글꼴에서 키릴 자모 소문자 A("а")는 라틴어 소문자 A("a")와 구별할 수 없습니다. "example.com" 및 "exа mple.com"는 이름에 라틴어 소문자 A가 있고 다른 하나는 키릴 자모 소문자 A인 두 개의 서로 다른 도메인 이름임을 시각적으로 알 수 있는 방법이 없습니다. IDN 관련 보안 문제에 대한 자세한 내용은 IDN(Internationalized Domain Names) 처리를 참조하세요.

 

구문

int IdnToAscii(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpUnicodeCharStr,
  [in]            int     cchUnicodeChar,
  [out, optional] LPWSTR  lpASCIICharStr,
  [in]            int     cchASCIIChar
);

매개 변수

[in] dwFlags

변환 옵션을 지정하는 플래그입니다. 다음 표에서 가능한 값을 나열합니다.

의미
IDN_ALLOW_UNASSIGNED
참고 애플리케이션은 비교 작업과 같이 일반 조회에 쿼리 문자열을 사용하는 경우 이 값을 설정할 수 있습니다. 그러나 애플리케이션은 스토리지에 대해 준비 중인 문자열인 저장된 문자열에 대해 이 값을 설정해서는 안 됩니다.
 
할당되지 않은 코드 포인트를 입력 문자열에 포함할 수 있습니다. 기본값은 할당되지 않은 코드 포인트를 허용하지 않고 ERROR_INVALID_NAME 확장 오류 코드로 실패하는 것입니다.

이 플래그를 사용하면 함수가 IDN에서 현재 합법적이지 않지만 이후 버전의 IDNA 표준에서 합법적일 수 있는 문자를 처리할 수 있습니다. 애플리케이션이 할당되지 않은 코드 포인트를 Punycode로 인코딩하는 경우 결과 도메인 이름은 불법이어야 합니다. IDNA의 이후 버전에서 이러한 이름을 합법적으로 만들거나 애플리케이션이 불법 문자를 필터링하여 법적 도메인 이름을 만들려고 시도하는 경우 보안이 손상될 수 있습니다. 자세한 내용은 IDN(Internationalized Domain Names) 처리를 참조하세요.

IDN_USE_STD3_ASCII_RULES
STD3 이름에 허용되지 않는 ASCII 문자를 필터링합니다. 입력 유니코드 문자열에 허용되는 유일한 ASCII 문자는 문자, 숫자 및 하이픈-빼기입니다. 문자열은 하이픈-빼기로 시작하거나 끝낼 수 없습니다. 입력 유니코드 문자열에 도메인 이름에서 발생할 수 없는 "[", "]" 또는 "/"와 같은 ASCII 문자가 포함되어 있으면 함수가 실패합니다.
참고 일부 로컬 네트워크에서는 컴퓨터 이름에서 이러한 문자 중 일부를 허용할 수 있습니다.
 

입력 유니코드 문자열에 컨트롤 문자(U+0001~U+0020) 또는 "delete" 문자(U+007F)가 포함되어 있으면 함수가 실패합니다. 두 경우 모두 이 플래그는 유니코드 문자열에서 허용되는 비 ASCII 문자에 영향을 주지 않습니다.

IDN_EMAIL_ADDRESS
Windows 8 시작: 메일 주소의 로컬 부분(예: <local>@microsoft.com)에 EAI 알고리즘 대체를 사용하도록 설정합니다. 기본값은 전자 메일 주소에 잘못된 주소 또는 구문이 있는 경우 이 함수가 실패하는 것입니다.

애플리케이션은 가능한 경우 Email EAI(Address Internationalization)에서 검색 가능한 대체 주소를 반환할 수 있도록 이 플래그를 설정할 수 있습니다. 자세한 내용은 IETF Email 주소 국제화(eai) 헌장을 참조하세요.

IDN_RAW_PUNYCODE
Windows 8 시작: Punycode의 유효성 검사 및 매핑을 사용하지 않도록 설정합니다.

[in] lpUnicodeCharStr

IDN 또는 다른 국제화된 레이블을 나타내는 유니코드 문자열에 대한 포인터입니다.

[in] cchUnicodeChar

lpUnicodeCharStr로 표시된 입력 유니코드 문자열의 문자 수입니다.

[out, optional] lpASCIICharStr

ASCII 문자 집합의 문자로만 구성된 유니코드 문자열을 수신하는 버퍼에 대한 포인터입니다. 이 함수에서 반환될 때 버퍼에는 punycode 아래의 lpUnicodeCharStr 에 제공된 문자열에 해당하는 ASCII 문자열이 포함됩니다. 또는 cchASCIIChar가 0으로 설정된 경우 함수는 이 매개 변수에 대해 NULL을 검색할 수 있습니다. 이 경우 함수는 이 버퍼에 필요한 크기를 반환합니다.

[in] cchASCIIChar

lpASCIICharStr로 표시된 버퍼의 크기입니다. 애플리케이션은 매개 변수를 0으로 설정하여 lpASCIICharStr에서 NULL을 검색할 수 있습니다.

반환 값

성공하면 lpASCIICharStr 에서 검색된 문자 수를 반환합니다. 검색된 문자열은 입력 유니코드 문자열이 null로 종료된 경우에만 null로 종료됩니다.

함수가 성공하고 cchASCIIChar 값이 0이면 함수는 입력 버퍼의 일부인 경우 종료 null 문자를 포함하여 필요한 크기를 문자로 반환합니다.

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

  • ERROR_INSUFFICIENT_BUFFER. 제공된 버퍼 크기가 충분히 크지 않거나 NULL로 잘못 설정되었습니다.
  • ERROR_INVALID_FLAGS. 플래그에 제공된 값이 잘못되었습니다.
  • ERROR_INVALID_NAME. 함수에 잘못된 이름이 제공되었습니다. 이 오류 코드는 모든 구문 오류를 catch합니다.
  • ERROR_INVALID_PARAMETER. 매개 변수 값이 잘못되었습니다.
  • ERROR_NO_UNICODE_TRANSLATION. 문자열에서 잘못된 유니코드가 발견되었습니다.

설명

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

입력 문자열에 컨트롤 문자(U+0001~U+0020) 또는 "delete" 문자(U+007F)가 포함된 경우 함수는 항상 실패합니다. U+0000 문자는 종료 null 문자로만 표시할 수 있으므로 U+0000이 입력 문자열의 다른 위치에 나타나면 함수가 항상 실패합니다.

Windows XP, Windows Server 2003:

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

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

요구 사항

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

추가 정보

IDN(Internationalized Domain Names) 처리

IdnToNameprepUnicode

IdnToUnicode

국가 언어 지원

국가 언어 지원 함수