RtlUnicodeToUTF8N 함수(ntifs.h)

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

구문

NTSYSAPI NTSTATUS RtlUnicodeToUTF8N(
  [out] PCHAR  UTF8StringDestination,
  [in]  ULONG  UTF8StringMaxByteCount,
  [out] PULONG UTF8StringActualByteCount,
  [in]  PCWCH  UnicodeStringSource,
  [in]  ULONG  UnicodeStringByteCount
);

매개 변수

[out] UTF8StringDestination

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

[in] UTF8StringMaxByteCount

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

[out] UTF8StringActualByteCount

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

[in] UnicodeStringSource

유니코드 소스 문자열에 대한 포인터입니다.

[in] UnicodeStringByteCount

UnicodeStringSource 매개 변수가 가리키는 유니코드 소스 문자열의 바이트 수를 지정합니다.

반환 값

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

반환 코드	설명
STATUS_BUFFER_TOO_SMALL	UTF8StringMaxByteCount 매개 변수는 전체 출력 문자열을 포함하기에는 너무 작은 버퍼 크기를 지정합니다.
STATUS_INVALID_PARAMETER	UTF8StringDestination 및 UTF8StringActualByteCount 매개 변수는 모두 NULL입니다.
STATUS_INVALID_PARAMETER_4	UnicodeStringSource 매개 변수는 NULL입니다.
STATUS_INVALID_PARAMETER_5	UnicodeStringByteCount 는 WCHAR(sizeof)의 정수 배수가 아닙니다.

설명

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

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

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

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

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

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

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

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 7
대상 플랫폼	유니버설
헤더	ntifs.h(Ntifs.h, Wdm.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

추가 정보

RtlUTF8ToUnicodeN