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 つ以上の入力文字が無効で、Unicode 置換文字 U+FFFD によって変換されてから UTF-8 に変換されました。

注釈

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
対象プラットフォーム ユニバーサル
Header ntifs.h (Ntifs.h、Wdm.h、Ntifs.h を含む)
Library NtosKrnl.lib
[DLL] NtosKrnl.exe
IRQL PASSIVE_LEVEL

こちらもご覧ください

RtlFreeUnicodeString

RtlUnicodeStringToUTF8String