RtlStringCbCopyNW 函式 (ntstrsafe.h)

RtlStringCbCopyNW 和 RtlStringCbCopyNA 函式會將位元組計數位符串複製到緩衝區，同時限制複製字元串的大小。

語法

NTSTRSAFEDDI RtlStringCbCopyNW(
  [out] NTSTRSAFE_PWSTR pszDest,
  [in]  size_t          cbDest,
  [in]  STRSAFE_PCNZWCH pszSrc,
        size_t          cbToCopy
);

參數

[out] pszDest

接收所複製字串之呼叫端所提供緩衝區的指標。 pszSrc 的字串最多為 cbSrc 位元組，會複製到 pszDest 的緩衝區，並以 Null 字元終止。

[in] cbDest

目的地緩衝區的大小，以位元組為單位。 緩衝區必須夠大，字串和終止 Null 字元。

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

對於 ANSI 字串，最大位元組數目會NTSTRSAFE_MAX_CCH * sizeof (char) 。

[in] pszSrc

呼叫端提供的 Null 終止字串指標。

cbToCopy

要從 pszSrc 複製到 pszDest 的最大位元元組數目。

傳回值

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

傳回碼	Description
STATUS_SUCCESS	此 成功 狀態表示源數據已存在、字串複製而不截斷，且結果目的地緩衝區為 Null 終止。
STATUS_BUFFER_OVERFLOW	此 警告 狀態表示複製作業因目的地緩衝區空間不足而未完成。 目的地緩衝區包含已複製字串的截斷版本。
STATUS_INVALID_PARAMETER	這個 錯誤 狀態表示函式收到無效的輸入參數。 如需詳細資訊，請參閱下列段落。 當下列情況時，函式會傳回STATUS_INVALID_PARAMETER值： cbDest 中的值大於緩衝區大小上限。 目的地緩衝區已滿。 NULL 指標存在。 目的地緩衝區的長度為零，但存在非零長度的來源字串。

備註

應該使用 RtlStringCbCopyNW 和 RtlStringCbCopyNA ，而不是 strncpy。 不過，這些函式的行為不同。 如果 cbSrc 大於 pszSrc 中的位元元組數目，RtlStringCbCopyN 函式與 strncpy 不同，在複製 cbSrc 位元組之前，請勿以 Null 字元填滿 pszDest。

RtlStringCbCopyN 會從來源字串複製指定的位元元組數目。 目的地緩衝區的大小是以位元組為單位提供給函式，以確保 RtlStringCbCopyN 不會寫入超過這個緩衝區的結尾。

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

字串資料類型	字串常值	函式
WCHAR	L“string”	RtlStringCbCopyNW
char	"字串"	RtlStringCbCopyNA

 

如果 pszSrc 和 pszDest 指向重疊字串，則函式的行為未定義。

pszSrc 和 pszDest 都不能是 NULL。 如果您需要處理 NULL 字串指標值，請參閱 RtlStringCbCopyNEx。

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

規格需求

需求	值
最低支援的用戶端	在 Windows XP 中使用 Service Pack 1 (SP1) 和更新版本的 Windows。
目標平台	桌面
標頭	ntstrsafe.h (包含 Ntstrsafe.h)
程式庫	Ntstrsafe.lib
IRQL	如果正在操作的字串一律位於記憶體中，則為任何 ，否則PASSIVE_LEVEL

另請參閱

RtlStringCbCopy

RtlStringCbCopyNEx

RtlStringCchCopyN