StringCchCopyNA 関数 (strsafe.h)

  • [アーティクル]

指定した文字数を 1 つの文字列から別の文字列にコピーします。 StringCchCopyN がこのバッファーの末尾を超えて書き込まれないように、コピー先バッファーのサイズが関数に提供されます。

StringCchCopyN は、次の関数に代わる関数です。

構文

STRSAFEAPI StringCchCopyNA(
  [out] STRSAFE_LPSTR  pszDest,
  [in]  size_t         cchDest,
  [in]  STRSAFE_PCNZCH pszSrc,
  [in]  size_t         cchToCopy
);

パラメーター

[out] pszDest

種類: LPTSTR

コピーされた文字を受け取る宛先バッファー。

[in] cchDest

種類: size_t

pszDest のサイズ (文字単位)。 この値は、コピーされた文字 ( pszSrc の長さ、 または cchSrc の値のいずれか小さい方) を保持するのに十分な大きさに加えて、終端の null 文字を考慮するために 1 を加える必要があります。 使用できる最大文字数は STRSAFE_MAX_CCH。

[in] pszSrc

型: LPCTSTR

ソース文字列。 この文字列は、 cchSrc 文字または null ターミネータのいずれか早い方まで読み取り可能である必要があります。

[in] cchToCopy

種類: size_t

pszSrc から pszDest にコピーする最大文字数。

戻り値

種類: HRESULT

この関数は、次のいずれかの値を返すことができます。 SUCCEEDED マクロと FAILED マクロを使用して、この関数の戻り値をテストすることを強くお勧めします。

リターン コード 説明
S_OK
 ソース データが存在し、文字は切り捨てず に pszSrc からコピーされ、結果の宛先バッファーは null で終わる。
STRSAFE_E_INVALID_PARAMETER
 cchDest の値が STRSAFE_MAX_CCH より大きいか、宛先バッファーが既にいっぱいです。
STRSAFE_E_INSUFFICIENT_BUFFER
 バッファー領域が不足しているため、コピー操作が失敗しました。 変換先バッファーには、意図した結果の、null で終わる切り捨てられたバージョンが含まれています。 切り捨てが許容される状況では、これは必ずしもエラー状態と見なされない場合があります。
 

この関数は、置き換える関数とは異なり、 HRESULT 値を返します。

解説

StringCchCopyN は、コード内で適切なバッファー処理を行うための追加の処理を提供します。 バッファー処理の不十分さは、バッファー オーバーランを伴う多くのセキュリティの問題に関係しています。 StringCchCopyN は 常に null 終了し、操作中にソース文字列の内容が変更された場合でも、有効な宛先バッファーをオーバーフローすることはありません。

このルーチンは strncpy の代わりとして使用されますが、動作には違いがあります。 cchSrc が pszSrc の文字数より大きい場合、stringCchCopyN は strncpy とは異なり、cchSrc 文字がコピーされるまで pszDest を null 文字で埋め続けられません。

pszSrc と pszDest が指す文字列が重複している場合、動作は未定義です。

pszSrc も pszDest も NULL にすることはできません。 null 文字列ポインター値の処理が必要な場合は、「 StringCchCopyNEx 」を参照してください。

StringCchCopyN は、その汎用的な形式またはより具体的な形式で使用できます。 次の表に示すように、文字列のデータ型によって、使用する必要があるこの関数の形式が決まります。

文字列型 (String) リテラル文字列 機能
char "string" StringCchCopyNA
TCHAR TEXT("string") StringCchCopyN
Wchar L"string" StringCchCopyNW
 

注意

strsafe.h ヘッダーは、StringCchCopyN をエイリアスとして定義します。このエイリアスは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

   
サポートされている最小のクライアント WINDOWS XP と SP2 [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows Server 2003 SP1 [デスクトップ アプリ |UWP アプリ]
対象プラットフォーム Windows
ヘッダー strsafe.h

関連項目

参照

StringCbCopyN

StringCchCopy

StringCchCopyNEx