RtlUnicodeStringToUTF8String 関数 (ntifs.h)

RtlUnicodeStringToUTF8String は、指定した Unicode 文字列を UTF-8 文字列に変換します。

構文

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

パラメーター

DestinationString

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

SourceString

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

AllocateDestinationString

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

戻り値

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

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

注釈

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

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

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

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

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

要件

要件	値
サポートされている最小のクライアント	Windows 10 バージョン 2004
Header	ntifs.h

こちらもご覧ください

RtlFreeUTF8String

RtlUTF8StringToUnicodeString