RtlUTF8ToUnicodeN 関数

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

構文

NTSTATUS WINAPI RtlUTF8ToUnicodeN(
  _Out_     PWSTR  UnicodeStringDestination,
  _In_      ULONG  UnicodeStringMaxByteCount,
  _Out_opt_ PULONG UnicodeStringActualByteCount,
  _In_      PCCH   UTF8StringSource,
  _In_      ULONG  UTF8StringByteCount
);

パラメーター

UnicodeStringDestination [out]

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

UnicodeStringMaxByteCount [in]

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

UnicodeStringActualByteCount [out, optional]

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

UTF8StringSource [in]

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

UTF8StringByteCount [in]

UTF8StringSource の文字列のサイズ (バイト単位)。

戻り値

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

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

 

解説

UnicodeStringActualByteCount は省略可能であり、NULL にすることもできますが、呼び出し元は、変換が成功したかどうかを判断するために受信した長さを使用できるため、そのストレージを提供する必要があります。

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

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

RtlUTF8ToUnicodeN は、 UnicodeStringDestination ポインターと UTF8StringSource ポインターが同等でない限り、ソース文字列を変更しません。 返された Unicode 文字列は null で終わるものではありません。

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

要件

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

関連項目

RtlUnicodeToUTF8N