RtlUnicodeStringToUTF8String 함수(ntifs.h)

  • 아티클

RtlUnicodeStringToUTF8String 은 지정된 유니코드 문자열을 UTF-8 문자열로 변환합니다.

구문

NTSYSAPI NTSTATUS RtlUnicodeStringToUTF8String(
  PUTF8_STRING     DestinationString,
  PCUNICODE_STRING SourceString,
  BOOLEAN          AllocateDestinationString
);

매개 변수

DestinationString

변환된 출력 UTF-8 문자열이 배치되는 버퍼에 대한 포인터입니다. DestinationString-MaximumLength> 필드는 AllocateDestinationString이 TRUE인 경우에만 설정됩니다.

SourceString

UTF-8로 변환할 유니코드 문자열에 대한 포인터입니다.

AllocateDestinationString

부울 값을 지정합니다. TRUE를 설정하면 RtlUnicodeStringToUTF8String 이 대상 문자열에 대한 버퍼 공간을 할당합니다. DestinationString-Buffer>에 대한 스토리지만 이 API에 의해 할당됩니다. RtlUnicodeStringToUTF8String이 버퍼 할당을 수행하는 경우 호출자는 RtlFreeUTF8String을 사용하여 버퍼의 할당을 취소해야 합니다.

반환 값

이 함수는 변환에 성공하면 STATUS_SUCCESS 반환합니다. 가능한 오류 또는 경고 코드는 다음과 같습니다.

코드 Description
STATUS_INVALID_PARAMETERX 오류: 매개 변수 값 중 하나가 잘못되었습니다.
STATUS_NO_MEMORY 오류: RtlUnicodeStringToUTF8String 에서 버퍼 공간을 할당할 수 없습니다.
STATUS_BUFFER_OVERFLOW 경고: 대상 버퍼의 공간이 부족하여 DestinationString-Buffer>에서 변환된 문자열이 잘립니다.
STATUS_SOME_NOT_MAPPED 경고: 호출에 성공했지만 하나 이상의 입력 문자가 잘못되었으며 UTF-8로 변환되기 전에 유니코드 대체 문자인 U+FFFD로 대체되었습니다.

설명

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

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

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

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

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

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows 10, 버전 2004
머리글 ntifs.h

추가 정보

RtlFreeUTF8String

RtlUTF8StringToUnicodeString