RtlUnicodeStringVPrintfEx 関数 (ntstrsafe.h)

[アーティクル]
08/07/2023

RtlUnicodeStringVPrintfEx 関数は、指定された書式設定情報に基づく書式設定を使用してテキスト文字列を作成し、その文字列をUNICODE_STRING構造体に格納します。

構文

NTSTRSAFEDDI RtlUnicodeStringVPrintfEx(
  [out]           PUNICODE_STRING  DestinationString,
  [out, optional] PUNICODE_STRING  RemainingString,
  [in]            DWORD            dwFlags,
  [in]            NTSTRSAFE_PCWSTR pszFormat,
  [in]            va_list          argList
);

パラメーター

[out] DestinationString

任意。書式設定された文字列を受け取る UNICODE_STRING 構造体へのポインター。 RtlUnicodeStringVPrintfEx は、 pszFormat が提供する書式設定文字列と関数の引数リストからこの文字列を作成します。文字列内の最大文字数はNTSTRSAFE_UNICODE_STRING_MAX_CCH。 DestinationString は NULL にできますが、 dwFlags でSTRSAFE_IGNORE_NULLSが設定されている場合にのみ使用できます。

[out, optional] RemainingString

省略可能。呼び出し元が、UNICODE_STRING構造体への NULL 以外のポインターを提供する場合、RtlUnicodeStringVPrintfE は、この構造体の Buffer メンバーを書式設定された文字列の末尾に設定し、構造体の Length メンバーを 0 に設定し、構造体の MaximumLength メンバーを宛先バッファーに残っているバイト数に設定します。 RemainingString は NULL にできますが、 dwFlags でSTRSAFE_IGNORE_NULLSが設定されている場合にのみ使用できます。

[in] dwFlags

1 つ以上のフラグと、必要に応じて塗りつぶしバイト。フラグは次のように定義されます。

STRSAFE_FILL_BEHIND

このフラグが設定され、関数が成功した場合、 dwFlags の下位バイトを使用して、文字列の最後の文字に続くコピー先バッファーの部分が埋まります。

STRSAFE_IGNORE_NULLS

このフラグが設定されている場合、ソースポインターまたは宛先ポインター、またはその両方を NULL にすることができます。 RtlUnicodeStringVPrintfEx は 、NULL ソースバッファーポインターを、コピー可能な空の文字列 (TEXT("")) のように扱います。 NULL 宛先バッファーポインターは、空でない文字列を受け取ることができません。

STRSAFE_FILL_ON_FAILURE

このフラグが設定され、関数が失敗した場合は、 dwFlags の下位バイトを使用して、宛先バッファー全体を埋めます。この操作により、既存のバッファーの内容が上書きされます。

STRSAFE_NULL_ON_FAILURE

このフラグが設定され、関数が失敗した場合、宛先バッファーは空の文字列 (TEXT("")) に設定されます。この操作により、既存のバッファーの内容が上書きされます。

STRSAFE_NO_TRUNCATION

このフラグが設定され、関数がSTATUS_BUFFER_OVERFLOWを返す場合、変換先バッファーの内容は変更されません。

STRSAFE_ZERO_LENGTH_ON_FAILURE

このフラグが設定され、関数がSTATUS_BUFFER_OVERFLOWを返す場合、変換先の文字列の長さは 0 バイトに設定されます。

[in] pszFormat

printf スタイルの書式設定ディレクティブを含む null で終わるテキスト文字列へのポインター。このポインターは NULL にできますが、 STRSAFE_IGNORE_NULLSが dwFlags で設定されている場合にのみ使用できます。

[in] argList

va_list型指定された引数リスト。この引数リストの引数は、 pszFormat が提供する書式設定文字列を使用して解釈されます。

戻り値

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

リターンコード	説明
STATUS_SUCCESS	この成功状態は、ソースデータが存在し、文字列が切り捨てられずに連結されたことを意味します。
STATUS_BUFFER_OVERFLOW	この警告状態は、コピー先バッファーの領域が不足しているため、コピー操作が完了しなかったことを意味します。 dwFlags でSTRSAFE_NO_TRUNCATIONが設定されている場合、宛先バッファーは変更されません。フラグが設定されていない場合、コピー先バッファーには、コピーされた文字列の切り捨てられたバージョンが含まれます。
STATUS_INVALID_PARAMETER	このエラー状態は、関数が無効な入力パラメーターを受信したことを意味します。詳細については、次の段落を参照してください。

RtlUnicodeStringVPrintfEx は、次のいずれかの場合にSTATUS_INVALID_PARAMETER値を返します。

UNICODE_STRING構造体の内容が無効です。
dwFlags で無効なフラグが指定されています。
宛先バッファーは既にいっぱいです。
バッファーポインターが NULL であり、 dwFlags でSTRSAFE_IGNORE_NULLS フラグが指定されていません。
宛先バッファーポインターは NULL ですが、バッファーサイズは 0 ではありません。
宛先バッファーポインターが NULL であるか、その長さが 0 ですが、0 以外の長さのソース文字列が存在します。

NTSTATUS 値をテストする方法については、「 NTSTATUS 値の使用」を参照してください。

注釈

RtlUnicodeStringVPrintfEx 関数は、コピー先バッファーのサイズを使用して、文字列の書式設定操作がバッファーの末尾を超えて書き込まれないことを確認します。既定では、関数は null 文字値 (つまり、ゼロ) で結果の文字列を終了しません。オプションとして、呼び出し元は、STRSAFE_FILL_BEHIND フラグと 0 のフィルバイト値を使用して、変換先バッファー全体を占有しない結果の文字列を null 終了できます。

RtlUnicodeStringVPrintfEx は、コピー先の文字列の末尾とその文字列で使用されていないバイト数を識別するUNICODE_STRING構造体を返すことによって、RtlUnicodeStringVPrintf 関数の機能を追加します。追加の制御のために 、RtlUnicodeStringVPrintfEx にフラグを渡すことができます。

書式指定文字列と変換先文字列が重複する場合、関数の動作は未定義です。

STRSAFE_IGNORE_NULLS フラグが dwFlags に設定されていない限り、pszFormat ポインターと DestinationString ポインターを NULL にすることはできません。 STRSAFE_IGNORE_NULLSが設定されている場合、これらのポインターの一方または両方を NULL にすることができます。 DestinationString ポインターが NULL の場合、pszFormat ポインターは NULL であるか、空の文字列を指す必要があります。

va_list型指定された引数リストの詳細については、Microsoft Windows SDKのドキュメントを参照してください。

安全な文字列関数の詳細については、「安全な文字列関数の使用」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows XP Service Pack 1 (SP1) 以降で使用できます。
対象プラットフォーム	デスクトップ
Header	ntstrsafe.h (Ntstrsafe.h を含む)
Library	Ntstrsafe.lib
IRQL	操作されている文字列が常にメモリ内に存在する場合は。それ以外の場合は PASSIVE_LEVEL