StringCbGetsExA 関数 (strsafe.h)

  • [アーティクル]

改行文字 ('\n') まで、stdin から 1 行のテキストを取得します。 テキスト行がコピー先バッファーにコピーされ、改行文字が null 文字に置き換えられます。 コピー先バッファーのサイズは、 関数に提供され、このバッファーの末尾を越えて書き込まれないことを確認します。

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

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

StringCbGetsEx は fgets に代わるものではありません。改行文字を終端の null 文字に置き換えることはありません。

構文

STRSAFEAPI StringCbGetsExA(
  [out]           STRSAFE_LPSTR pszDest,
  [in]            size_t        cbDest,
  [out, optional] STRSAFE_LPSTR *ppszDestEnd,
  [out, optional] size_t        *pcbRemaining,
  [in]            DWORD         dwFlags
);

パラメーター

[out] pszDest

種類: LPTSTR

入力を受信する宛先バッファー。

[in] cbDest

種類: size_t

コピー先バッファーのサイズ (バイト単位)。 関数を成功させるには、この値を より sizeof(TCHAR) 大きくする必要があります。 許容される最大バイト数は です STRSAFE_MAX_CCH * sizeof(TCHAR)。 cbDest が小さすぎてテキスト全体を保持できる場合、データは切り捨てられます。

[out, optional] ppszDestEnd

種類: LPTSTR*

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

[out, optional] pcbRemaining

種類: size_t*

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

[in] dwFlags

型: DWORD

次の値の 1 つ以上。

値 意味
STRSAFE_FILL_BEHIND_NULL
0x00000200
 関数が成功した場合、終了 null 文字の後に pszDest の初期化されていない部分を埋めるために dwFlags (0) の下位バイトが使用されます。
STRSAFE_IGNORE_NULLS
0x00000100
 NULL 文字列ポインターを空の文字列 (TEXT("")) のように扱います。 このフラグは、 lstrcpy などの関数をエミュレートする場合に便利です。
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
 STRSAFE_NULL_ON_FAILUREの場合と同様に、関数が失敗した場合、pszDest は空の文字列 (TEXT("")) に設定されます。 STRSAFE_E_INSUFFICIENT_BUFFERエラーが発生した場合は、切り捨てられた文字列が上書きされます。

戻り値

種類: HRESULT

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

リターン コード 説明
S_OK
 データは stdin から読み取られ、 pszDest でバッファーにコピーされ、バッファーは null で終了しました。
STRSAFE_E_END_OF_FILE
 エラーまたはファイルの終了条件を示します。 feof または ferror を使用して、どれが発生したかを判断します。
STRSAFE_E_INVALID_PARAMETER
 cbDest の値が許容される最大値より大きいか、無効なフラグが渡されました。
STRSAFE_E_INSUFFICIENT_BUFFER
 cbDest の値は 1 以下です。
 

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

注釈

StringCbGetsEx は、コード内で適切なバッファー処理を行うための追加の処理を提供します。 バッファー処理の不十分さは、バッファー オーバーランを伴う多くのセキュリティの問題に関係しています。 StringCbGetsEx は 、常に 0 以外の長さの宛先バッファーを null で終了します。

STRSAFE_IGNORE_NULLS フラグを指定しない限り、pszDest の値は NULL にしないでください。 ただし、 NULL 値が無視されても、領域が不足しているためにエラーが返される可能性があります。

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

文字列型 (String) リテラル文字列 機能
char "string" StringCbGetsExA
TCHAR TEXT("string") StringCbGetsEx
Wchar L"string" StringCbGetsExW
 

注意

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

要件

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

関連項目

参照

StringCbGets

StringCchGetsEx