StringCchCopyNExA 関数 (strsafe.h)

  • [アーティクル]

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

StringCchCopyNEx は、宛先文字列の末尾へのポインターと、その文字列で使用されていない文字数を返すことで 、StringCchCopyN の機能を追加します。 フラグは、追加のコントロールのために関数に渡すこともできます。

StringCchCopyNEx は、次の関数の代わりです。

構文

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

パラメーター

[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 にコピーする最大文字数。

[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
 関数が成功した場合、 dwFlags (0) の下位バイトを使用して、終端の null 文字の後に pszDest の初期化されていない部分を埋めます。
STRSAFE_IGNORE_NULLS
0x00000100
 NULL 文字列ポインターを空の文字列のように処理します (TEXT(""))。
STRSAFE_FILL_ON_FAILURE
0x00000400
 関数が失敗した場合、 dwFlags (0) の下位バイトが pszDest バッファー全体を埋めるために使用され、バッファーは null で終了します。 STRSAFE_E_INSUFFICIENT_BUFFERエラーが発生した場合、返された切り捨てられた文字列は上書きされます。
STRSAFE_NULL_ON_FAILURE
0x00000800
 関数が失敗した場合、 pszDest は空の文字列 (TEXT(")) に設定されます。 STRSAFE_E_INSUFFICIENT_BUFFERエラーが発生した場合、切り捨てられた文字列は上書きされます。
STRSAFE_NO_TRUNCATION
0x00001000
 STRSAFE_NULL_ON_FAILUREの場合と同様に、関数が失敗した場合、pszDest は空の文字列 (TEXT(")) に設定されます。 STRSAFE_E_INSUFFICIENT_BUFFERエラーが発生した場合、切り捨てられた文字列は上書きされます。

戻り値

型: HRESULT

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

リターン コード 説明
S_OK
 ソース データが存在し、切り捨てなしで完全にコピーされ、結果のコピー先バッファーは null で終了します。
STRSAFE_E_INVALID_PARAMETER
 pszDest または pszSrc がSTRSAFE_MAX_CCHより大きいか、コピーするソース データがある場合、または無効なフラグが渡された場合、pszDest は NULL です。
STRSAFE_E_INSUFFICIENT_BUFFER
 バッファー領域が不足しているため、コピー操作が失敗しました。 dwFlags の値によっては、ターゲット バッファーに、目的の結果の切り捨てられた null 終端バージョンが含まれている場合があります。 切り捨てが許容される状況では、必ずしも失敗状態と見なされない場合があります。
 

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

注釈

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

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

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

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

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

文字列型 (String) リテラル文字列 機能
char "string" StringCchCopyNExA
TCHAR TEXT("string") StringCchCopyNEx
Wchar L"string" StringCchCopyNExW
 

注意

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

要件

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

関連項目

参照

StringCbCopyNEx

StringCchCopyN