RtlUnicodeToUTF8N 関数 (wdm.h)

RtlUnicodeToUTF8N ルーチンは、Unicode 文字列を 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

Unicode ソース文字列へのポインター。

[in] UnicodeStringByteCount

UnicodeStringSource パラメーターが指す Unicode ソース文字列のバイト数を指定します。

戻り値

RtlUnicodeToUTF8N は、呼び出しが成功し、入力文字列内のすべての Unicode 文字コードが出力文字列内の対応する UTF-8 文字コードに変換された場合に、STATUS_SUCCESSを返します。 呼び出しが成功したが、1 つ以上の入力文字が無効で、UTF-8 に変換される前に Unicode 置換文字 U+FFFD に置き換えられた場合は、STATUS_SOME_NOT_MAPPEDが返されます。 考えられるエラー戻り値には、次のエラー コードが含まれます。

注釈

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

UTF8StringMaxByteCount パラメーターで、出力文字列全体を格納するには小さすぎるバッファー サイズが指定されている場合、ルーチンはSTATUS_BUFFER_TOO_SMALLを返します。 この場合、ルーチンはバッファーに収まるのと同じ数の UTF-8 文字を書き込み、*UTF8StringActualByteCount 値はルーチンがバッファーに書き込んだ有効なバイト数を指定します。 出力バッファーに含まれる部分的な文字列には、終端の null 文字が含まれていない可能性があります。

RtlUnicodeToUTF8N を最初に呼び出して必要な出力バッファー サイズを取得し、RtlUnicodeToUTF8N をもう一度呼び出して Unicode 出力文字列を取得できます。 最初の呼び出しで 、UTF8StringDestination = NULL と UTF8StringMaxByteCount = 0 を設定すると、ルーチンは必要なバッファー サイズを *UTF8StringActualByteCount に書き込みます。 次に、必要なサイズのバッファーを割り当て、 RtlUnicodeToUTF8N を 2 回目に呼び出して UTF-8 出力文字列を取得します。

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

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

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

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

要件

こちらもご覧ください

RtlUTF8ToUnicodeN