RtlUTF8ToUnicodeN 함수(wdm.h)

  • 아티클

RtlUTF8ToUnicodeN 루틴은 UTF-8 문자열을 유니코드 문자열로 변환합니다.

구문

NTSYSAPI NTSTATUS RtlUTF8ToUnicodeN(
  [out, optional] PWSTR  UnicodeStringDestination,
  [in]            ULONG  UnicodeStringMaxByteCount,
  [out]           PULONG UnicodeStringActualByteCount,
  [in]            PCCH   UTF8StringSource,
  [in]            ULONG  UTF8StringByteCount
);

매개 변수

[out, optional] UnicodeStringDestination

루틴이 유니코드 출력 문자열을 작성하는 호출자가 할당한 대상 버퍼에 대한 포인터입니다. 이 매개 변수가 NULL인 경우 루틴은 출력 버퍼의 필요한 크기를 *UnicodeStringActualByteCount에 씁니다.

[in] UnicodeStringMaxByteCount

UnicodeStringDestination이 가리키는 버퍼에 루틴이 쓸 수 있는 최대 바이트 수를 지정합니다. UnicodeStringDestination = NULL인 경우 UnicodeStringMaxByteCount = 0을 설정합니다.

[out] UnicodeStringActualByteCount

루틴이 UnicodeStringDestination 이 가리키는 버퍼에 쓴 실제 바이트 수를 쓰는 위치에 대한 포인터입니다. UnicodeStringDestination이 NULL이 아닌 경우 이 개수는 UnicodeStringMaxByteCount 값을 초과하지 않습니다. UnicodeStringDestination이 NULL인 경우 이 개수는 전체 출력 문자열을 포함하는 데 필요한 바이트 수입니다.

[in] UTF8StringSource

UTF-8 원본 문자열에 대한 포인터입니다.

[in] UTF8StringByteCount

UTF8StringSource 매개 변수가 가리키는 UTF-8 원본 문자열의 바이트 수를 지정합니다.

반환 값

RtlUTF8ToUnicodeN 은 호출이 성공하고 입력 문자열의 모든 UTF-8 문자 코드가 출력 문자열의 해당 유니코드 문자 코드로 변환된 경우 STATUS_SUCCESS 반환합니다. 호출이 성공했지만 하나 이상의 입력 문자가 유효하지 않고 유니코드 대체 문자인 U+FFFD로 변환된 경우 STATUS_SOME_NOT_MAPPED 반환합니다. 가능한 오류 반환 값에는 다음과 같은 오류 코드가 포함됩니다.

반환 코드 설명
STATUS_BUFFER_TOO_SMALL
 UnicodeStringMaxByteCount 매개 변수는 전체 출력 문자열을 포함하기에는 너무 작은 버퍼 크기를 지정합니다.
STATUS_INVALID_PARAMETER
 UnicodeStringDestination 및 UnicodeStringActualByteCount 매개 변수는 모두 NULL입니다.
STATUS_INVALID_PARAMETER_4
 UTF8StringSource 매개 변수는 NULL입니다.

설명

유니코드 출력 문자열은 UTF-8 입력 문자열이 null로 종료된 경우에만 null로 종료됩니다.

UnicodeStringMaxByteCount 매개 변수가 전체 출력 문자열을 포함하기에는 너무 작은 버퍼 크기를 지정하면 루틴은 STATUS_BUFFER_TOO_SMALL 반환합니다. 이 경우 루틴은 버퍼에 맞는 만큼 유니코드 문자를 쓰고 *UnicodeStringActualByteCount 값은 루틴이 버퍼에 쓴 유효한 바이트 수를 지정합니다. 출력 버퍼에 포함된 부분 문자열에는 종료 null 문자가 포함되지 않을 수 있습니다.

RtlUTF8ToUnicodeN을 처음 호출하여 필요한 출력 버퍼 크기를 가져온 다음 RtlUTF8ToUnicodeN을 다시 호출하여 유니코드 출력 문자열을 가져올 수 있습니다. 초기 호출에서 UnicodeStringDestination = NULL 및 UnicodeStringMaxByteCount = 0을 설정하고 루틴은 필요한 버퍼 크기를 *UnicodeStringActualByteCount에 씁니다. 다음으로 필요한 크기의 버퍼를 할당하고 RtlUTF8ToUnicodeN 을 두 번째로 호출하여 유니코드 출력 문자열을 가져옵니다.

RtlUTF8ToUnicodeN 은 유니코드 서로게이트 쌍을 지원합니다. 그러나 뒤에 오는 단어 값이나 선행 단어 값 앞에 있지 않은 후행 단어 값이 뒤에 오는 서로게이트 선행 단어 값은 유효한 문자로 인식되지 않으며 유니코드 대체 문자인 U+FFFD로 대체됩니다.

RtlUTF8ToUnicodeN 은 먼저 발생하는 원본 버퍼의 끝 또는 대상 버퍼의 끝에 도달할 때까지 입력 문자열을 출력 문자열로 계속 변환합니다. 루틴은 입력 문자열의 null 문자를 출력 문자열의 null 문자로 변환합니다. 입력 문자열에 종료 null 문자가 포함되어 있지만 null 문자가 원본 버퍼의 끝에 없는 경우 루틴은 사용 가능한 버퍼 공간의 끝에 도달할 때까지 종료되는 null 문자를 지나 계속 진행합니다.

RtlUnicodeToUTF8N 루틴은 유니코드 문자열을 UTF-8 문자열로 변환합니다.

RtlUTF8ToUnicode 및 RtlUnicodeToUTF8N 루틴을 사용하여 UTF-8과 유니코드 형식 간에 유효한 텍스트 문자열을 무손실로 변환할 수 있습니다. 그러나 임의의 데이터 값이 있는 문자열은 서로게이트 쌍을 인코딩하기 위한 유니코드 규칙을 위반할 수 있으며 입력 문자열의 잘못된 값에 포함된 모든 정보는 손실되어 결과 출력 문자열에서 복구할 수 없습니다.

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows 7 및 이후 버전의 Windows에서 사용할 수 있습니다.
대상 플랫폼 유니버설
헤더 wdm.h(Ntifs.h, Wdm.h, Ntifs.h 포함)
라이브러리 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

추가 정보

RtlUnicodeToUTF8N