RtlUTF8StringToUnicodeString 関数 (ntifs.h)

RtlUTF8StringToUnicodeString ルーチンは、指定した UTF-8 文字列を Unicode 文字列に変換します。

構文

NTSYSAPI NTSTATUS RtlUTF8StringToUnicodeString(
  PUNICODE_STRING DestinationString,
  PUTF8_STRING    SourceString,
  BOOLEAN         AllocateDestinationString
);

パラメーター

DestinationString

変換された出力 Unicode 文字列が格納されているバッファーへのポインター。 DestinationString->MaximumLength フィールドは、AllocateDestinationString TRUE の場合にのみ設定されます。

SourceString

Unicode に変換する UTF-8 ソース文字列へのポインター。

AllocateDestinationString

ブール値。 TRUE に設定すると、RtlUTF8StringToUnicodeString 、宛先文字列のバッファー領域が割り当てられます。 DestinationString->Buffer のストレージのみが、この API によって割り当てられます。 RtlUTF8StringToUnicodeString がバッファー割り当てを行う場合、呼び出し元は RtlFreeUnicodeStringを使用してバッファー割り当てを解除する必要があります。

戻り値

この関数は、変換が成功したときにSTATUS_SUCCESSを返します。 考えられるエラーまたは警告コードは次のとおりです。

コード	形容
STATUS_INVALID_PARAMETERX	エラー: パラメーター値の 1 つが無効です。
STATUS_NO_MEMORY	エラー: RtlUTF8StringToUnicodeString がバッファー領域を割り当てませんでした。
STATUS_BUFFER_OVERFLOW	警告: DestinationString->Buffer 変換された文字列は、宛先バッファーの領域が不足しているために切り捨てられます。
STATUS_SOME_NOT_MAPPED	警告: 呼び出しは成功しましたが、1 つ以上の入力文字が無効であり、UTF-8 に変換される前に Unicode 置換文字 U+FFFD によって変換されました。

備考

Unicode 出力文字列は、UTF-8 入力文字列が null で終わる場合にのみ null で終了します。

RtlUTF8StringToUnicodeString では、Unicode サロゲート ペアがサポートされます。 ただし、後に末尾の単語値が続かないサロゲート先頭の単語値、または先頭の単語値の前にない末尾の単語値は、有効な文字として認識されず、Unicode 置換文字 U+FFFD に置き換えられます。

RtlUTF8StringToUnicodeString は、ソース バッファーの末尾または宛先バッファーの末尾のいずれか早い方に達するまで、入力文字列を出力文字列に変換し続けます。 このルーチンは、入力文字列内の null 文字を出力文字列内の null 文字に変換します。 入力文字列に終端の null 文字が含まれているが、null 文字がソース バッファーの末尾にない場合、ルーチンは、使用可能なバッファー領域の末尾に到達するまで、終端の null 文字を超え続けます。

RtlUnicodeStringToUTF8String ルーチンは、Unicode 文字列を UTF-8 文字列に変換します。

RtlUTF8StringToUnicodeString および RtlUnicodeStringToUTF8Stringルーチンをして、UTF-8 形式と Unicode 形式の間で有効なテキスト文字列の無損失変換を実行できます。 ただし、任意のデータ値を持つ文字列は、サロゲート ペアをエンコードするための Unicode 規則に違反する可能性があり、入力文字列内の無効な値に含まれている情報は失われ、結果の出力文字列から回復することはできません。

必要条件

要件	価値
サポートされる最小クライアント	Windows 10 バージョン 2004
ターゲット プラットフォーム の	万国
ヘッダー	ntifs.h (Ntifs.h、Wdm.h、Ntifs.h を含む)
ライブラリ	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

関連項目

RtlFreeUnicodeStringの

RtlUnicodeStringToUTF8Stringの