RtlStringCbVPrintfW 函式 (ntstrsafe.h)

RtlStringCbVPrintfWRtlStringCbVPrintfA函式會建立位元組計數的文字字串,其格式是以所提供的格式資訊為基礎。

語法

NTSTRSAFEDDI RtlStringCbVPrintfW(
  [out] NTSTRSAFE_PWSTR  pszDest,
  [in]  size_t           cbDest,
  [in]  NTSTRSAFE_PCWSTR pszFormat,
  [in]  va_list          argList
);

參數

[out] pszDest

呼叫端提供的緩衝區指標,接收格式化、以 Null 結束的字串。 函式會從 pszFormat 提供的格式化字串和 argList所提供的引數建立此字串。

[in] cbDest

目的地緩衝區的大小,以位元組為單位。 緩衝區必須夠大,才能包含格式化字串加上終止的 Null 字元。

針對 Unicode 字串,最大位元組數目會NTSTRSAFE_MAX_CCH * sizeof (WCHAR) 。

若為 ANSI 字串,最大位元組數會NTSTRSAFE_MAX_CCH * sizeof (char) 。

[in] pszFormat

包含 printf樣式 格式指示詞之 Null 終止文字字串的指標。

[in] argList

va_list型別引數清單。 引數清單中所包含的引數將會使用 pszFormat所提供的格式字串來解譯。

傳回值

此函式會傳回下表所列的其中一個 NTSTATUS 值。 如需如何測試 NTSTATUS 值的詳細資訊,請參閱 使用 NTSTATUS 值

傳回碼 描述
STATUS_SUCCESS
成功 狀態表示來源資料已存在、已建立輸出字串而不截斷,且結果目的地緩衝區為 Null 終止。
STATUS_BUFFER_OVERFLOW
警告 狀態表示作業因目的地緩衝區空間不足而未完成。 目的地緩衝區包含已建立字串的截斷版本。
STATUS_INVALID_PARAMETER
這個 錯誤 狀態表示函式收到不正確輸入參數。 如需詳細資訊,請參閱下列段落。

當下列情況時,函式會傳回STATUS_INVALID_PARAMETER值:

  • cbDest中的值大於緩衝區大小上限。
  • 目的地緩衝區已滿。
  • Null指標存在。
  • 目的地緩衝區長度為零,但存在非零長度的來源字串。

備註

應該使用 RtlStringCbVPrintfWRtlStringCbVPrintfA ,而不是下列函式:

  • vsprintf
  • vswprintf
  • _vsnprintf
  • _vsnwprintf
所有這些函式都會接受格式字串,以及 va_list型別引數清單中的一組引數,並傳回格式化字串。 目的地緩衝區的大小會以位元組為單位提供給 RtlStringCbVPrintfWRtlStringCbVPrintfA ,以確保它們不會寫入緩衝區結尾。

如需va_list型別引數清單的詳細資訊,請參閱Microsoft Windows SDK檔。

使用 RtlStringCbVPrintfW 來處理 Unicode 字串和 RtlStringCbVPrintfA 來處理 ANSI 字串。 您所使用的表單取決於您的資料,如下表所示。

字串資料類型 字串常值 函式
WCHAR L「string」 RtlStringCbVPrintfW
char "字串" RtlStringCbVPrintfA
 

如果 pszDestpszFormat 指向重迭字串,或如果有任何引數字串重迭,則函式的行為未定義。

pszFormatpszDest都不應該是Null。 如果您需要處理 Null 字串指標值,請使用 RtlStringCbVPrintfEx

如需安全字串函式的詳細資訊,請參閱 使用安全字串函式

規格需求

   
最低支援的用戶端 從 Windows XP 搭配 Service Pack 1 (SP1) 開始提供。
目標平臺 桌面
標頭 ntstrsafe.h (包含 Ntstrsafe.h)
程式庫 Ntstrsafe.lib
IRQL PASSIVE_LEVEL

另請參閱

RtlStringCbPrintf

RtlStringCbVPrintfEx

RtlStringCchVPrintf