RtlUTF8ToUnicodeN 関数 (ntifs.h)

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

構文

NTSYSAPI NTSTATUS RtlUTF8ToUnicodeN(
  [out, optional] PWSTR  UnicodeStringDestination,
  [in]            ULONG  UnicodeStringMaxByteCount,
  [out]           PULONG UnicodeStringActualByteCount,
  [in]            PCCH   UTF8StringSource,
  [in]            ULONG  UTF8StringByteCount
);

パラメーター

[out, optional] UnicodeStringDestination

ルーチンが Unicode 出力文字列を書き込む呼び出し元によって割り当てられた宛先バッファーへのポインター。 このパラメーターが NULL の場合、ルーチンは出力バッファーの必要なサイズを *UnicodeStringActualByteCount に書き込みます。

[in] UnicodeStringMaxByteCount

UnicodeStringDestination が指すバッファーにルーチンが書き込むことができる最大バイト数を指定します。 UnicodeStringDestination = NULL の場合は、UnicodeStringMaxByteCount = 0 を設定します。

[out] UnicodeStringActualByteCount

ルーチンが UnicodeStringDestination が指すバッファーに書き込んだ実際のバイト数をルーチンが書き込む位置へのポインター。 UnicodeStringDestination が NULL 以外の場合、このカウントが UnicodeStringMaxByteCount の値を超えることはありません。 UnicodeStringDestination が NULL の場合、このカウントは出力文字列全体を格納するために必要なバイト数です。

[in] UTF8StringSource

UTF-8 ソース文字列へのポインター。

[in] UTF8StringByteCount

UTF8StringSource パラメーターが指す UTF-8 ソース文字列のバイト数を指定します。

戻り値

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

リターン コード	説明
STATUS_BUFFER_TOO_SMALL	UnicodeStringMaxByteCount パラメーターは、出力文字列全体を格納するには小さすぎるバッファー サイズを指定します。
STATUS_INVALID_PARAMETER	UnicodeStringDestination パラメーターと UnicodeStringActualByteCount パラメーターはどちらも NULL です。
STATUS_INVALID_PARAMETER_4	UTF8StringSource パラメーターは NULL です。

注釈

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

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

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

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

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

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

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

要件

要件	値
サポートされている最小のクライアント	Windows 7
対象プラットフォーム	ユニバーサル
Header	ntifs.h (Ntifs.h、Wdm.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

こちらもご覧ください

RtlUnicodeToUTF8N