StringCchCatNExA 関数 (strsafe.h)

  • [アーティクル]

指定した文字数を 1 つの文字列から別の文字列に連結します。 コピー先バッファーのサイズは、 関数に提供され、このバッファーの末尾を越えて書き込まれないことを確認します。

StringCchCatNEx は、文字列の末尾へのポインターと、その文字列で使用されていない文字数を返すことによって 、StringCchCatN の機能を追加します。 フラグは、追加の制御のために 関数に渡すこともできます。

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

構文

STRSAFEAPI StringCchCatNExA(
  [in, out]       STRSAFE_LPSTR  pszDest,
  [in]            size_t         cchDest,
  [in]            STRSAFE_PCNZCH pszSrc,
  [in]            size_t         cchToAppend,
  [out, optional] STRSAFE_LPSTR  *ppszDestEnd,
  [out, optional] size_t         *pcchRemaining,
  [in]            DWORD          dwFlags
);

パラメーター

[in, out] pszDest

種類: LPTSTR

pszSrc と連結する文字列を格納し、結果の文字列全体を受け取る宛先バッファー。 pszSrc の文字列は、pszDest の文字列の末尾に追加されます。

[in] cchDest

種類: size_t

変換先バッファーのサイズ (文字単位)。 この値は、終了する null 文字を考慮するために 、pszSrc の長さと pszDest の長さに 1 を加えたものに等しい必要があります。 使用できる最大文字数は STRSAFE_MAX_CCH。

[in] pszSrc

型: LPCTSTR

pszDest の末尾に連結されるソース文字列。 この文字列は null で終わる必要があります。

[in] cchToAppend

種類: size_t

pszDest に追加する最大文字数。

[out, optional] ppszDestEnd

種類: LPTSTR*

pszDest の末尾へのポインターのアドレス。 ppszDestEnd が NULL 以外で、データが宛先バッファーに追加される場合、これは文字列の末尾にある終端の null 文字を指します。

[out, optional] pcchRemaining

種類: size_t*

pszDest の未使用文字の数 (終端の null 文字を含む)。 pcchRemaining が NULL の場合、カウントは保持されず、返されません。

[in] dwFlags

型: DWORD

次の値の 1 つ以上。

値 説明
STRSAFE_FILL_BEHIND_NULL
0x00000200
 関数が成功した場合、終了 null 文字の後に pszDest の初期化されていない部分を埋めるために dwFlags (0) の下位バイトが使用されます。
STRSAFE_IGNORE_NULLS
0x00000100
 NULL 文字列ポインターを空の文字列 (TEXT("")) のように扱います。
STRSAFE_FILL_ON_FAILURE
0x00000400
 関数が失敗した場合、pszDest バッファー全体を埋めるために dwFlags (0) の下位バイトが使用され、バッファーは null で終了します。 STRSAFE_E_INSUFFICIENT_BUFFERエラーが発生した場合、宛先バッファー内の既存の文字列または切り捨てられた文字列は上書きされます。
STRSAFE_NULL_ON_FAILURE
0x00000800
 関数が失敗した場合、 pszDest は空の文字列 (TEXT("")) に設定されます。 STRSAFE_E_INSUFFICIENT_BUFFERエラーが発生した場合、宛先バッファー内の既存の文字列または切り捨てられた文字列は上書きされます。
STRSAFE_NO_TRUNCATION
0x00001000
 関数が失敗した場合、 pszDest は変更されません。 元のコンテンツには何も追加されません。

戻り値

種類: HRESULT

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

リターン コード 説明
S_OK
 ソース データが存在し、文字列が切り捨てられずに連結され、結果の宛先バッファーは null で終わる。
STRSAFE_E_INVALID_PARAMETER
 cchDest の値がSTRSAFE_MAX_CCHより大きい、無効なフラグが渡された、または pszDest、cchDest、および pszSrc に追加するマテリアルのサイズとの間に不一致があります。
STRSAFE_E_INSUFFICIENT_BUFFER
 バッファー領域が不足しているため、コピー操作が失敗しました。 dwFlags の値によっては、ターゲット バッファーに、意図した結果の null で終わる切り捨てバージョンが含まれる場合があります。 切り捨てが許容される状況では、これは必ずしもエラー状態と見なされない場合があります。
 

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

解説

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

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

STRSAFE_IGNORE_NULLS フラグが指定されていない限り、pszSrc も pszDest も NULL にすることはできません。この場合、どちらも NULL である可能性があります。 ただし、 NULL 値が無視されても、領域が不足しているためにエラーが返される可能性があります。

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

文字列型 (String) リテラル文字列 機能
char "string" StringCchCatNExA
TCHAR TEXT("string") StringCchCatNEx
Wchar L"string" StringCchCatNExW
 

注意

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

要件

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

関連項目

参照

StringCbCatNEx

StringCchCatEx

StringCchCatN