RtlUnicodeToUTF8N 関数

8 ビット Unicode 変換形式 (UTF-8) コード ページを使用して、指定した Unicode 文字列を新しい文字列に変換します。

構文

NTSTATUS WINAPI RtlUnicodeToUTF8N(
  _Out_     PCHAR  UTF8StringDestination,
  _In_      ULONG  UTF8StringMaxByteCount,
  _Out_opt_ PULONG UTF8StringActualByteCount,
  _In_      PCWSTR UnicodeStringSource,
  _In_      ULONG  UnicodeStringByteCount
);

パラメーター

UTF8StringDestination [out]

変換された文字列を受け取る呼び出し元によって割り当てられたバッファーへのポインター。

UTF8StringMaxByteCount [in]

UTF8StringDestination に書き込まれる最大バイト数。 この値によって変換された文字列が切り捨てられる場合、 RtlUnicodeToUTF8N はエラー状態を返します。

UTF8StringActualByteCount [out, optional]

変換された文字列の長さ (バイト単位) を受け取る呼び出し元によって割り当てられた変数へのポインター。 このパラメーターは省略可能であり、 NULL にすることができます。 文字列が切り捨てられた場合、返される数値は、実際に切り捨てられた文字列数をカウントします。

UnicodeStringSource [in]

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

*UnicodeStringByteCount * [in]

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

戻り値

RtlUnicodeToUTF8N は 、次のいずれかの NTSTATUS 値を返します。

リターン コード	説明
STATUS_SUCCESS	Unicode 文字列が UTF-8 に変換されました。
STATUS_SOME_NOT_MAPPED	無効な入力文字が検出され、置き換えられました。 この状態は成功状態と見なされます。
STATUS_INVALID_PARAMETER	UTF8StringDestination と UTF8StringActualByteCount への両方のポインターが NULL でした。
STATUS_INVALID_PARAMETER_4	UnicodeStringSource が NULL でした。
STATUS_BUFFER_TOO_SMALL	UTF8StringDestination が切り捨てられました。

 

解説

UTF8StringActualByteCount は省略可能で NULL でもかまいませんが、受信した長さを使用して変換が成功したかどうかを判断できるため、呼び出し元はストレージを提供する必要があります。 このルーチンでは、ソース文字列は変更されません。 指定された UnicodeStringSource に NULL 終端文字が含まれ、指定された UTF8StringMaxByteCount で切り捨てが発生しなかった場合は、null で終わる UTF-8 文字列が返されます。

出力が切り捨てられ、無効な入力文字が検出された場合、関数はエラー STATUS_BUFFER_TOO_SMALL返します。

UTF8StringDestination が NULL に設定されている場合、関数は UTF8StringActualByteCount で切り捨てることなく、翻訳された文字列をホストするために必要なバイト数を返します。

RtlUnicodeToUTF8N の呼び出し元は、IRQL < DISPATCH_LEVELで実行されている必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows 7 [デスクトップ アプリのみ]
サポートされている最小のサーバー	Windows Server 2008 R2 [デスクトップ アプリのみ]
Header	Wdm.h
[DLL]	Ntdll.dll

関連項目

RtlUTF8ToUnicodeN