RtlStringCchCopyNW 関数 (ntstrsafe.h)

RtlStringCchCopyNW 関数と RtlStringCchCopyNA 関数は、コピーした文字列のサイズを制限しながら、文字数をカウントした文字列をバッファーにコピーします。

構文

NTSTRSAFEDDI RtlStringCchCopyNW(
  [out] NTSTRSAFE_PWSTR pszDest,
  [in]  size_t          cchDest,
  [in]  STRSAFE_PCNZWCH pszSrc,
        size_t          cchToCopy
);

パラメーター

[out] pszDest

コピーされた文字列を受け取る呼び出し元が指定したバッファーへのポインター。 pszSrc の文字列 (cchSrc 文字まで) は pszDest のバッファーにコピーされ、null 文字で終了します。

[in] cchDest

変換先バッファーのサイズ (文字数)。 使用できる最大文字数はNTSTRSAFE_MAX_CCH。

[in] pszSrc

呼び出し元が指定した null で終わる文字列へのポインター。

cchToCopy

pszSrc から pszDest によって提供されるバッファーにコピーする最大文字数。

戻り値

関数は、次の表に示す NTSTATUS 値のいずれかを返します。 NTSTATUS 値をテストする方法については、「 NTSTATUS 値の使用」を参照してください。

リターン コード 説明
STATUS_SUCCESS
この 成功 状態は、ソース データが存在し、文字列が切り捨てられずにコピーされ、結果の宛先バッファーが null で終了したことを意味します。
STATUS_BUFFER_OVERFLOW
この 警告 状態は、コピー先バッファーの領域が不足しているため、コピー操作が完了しなかったことを意味します。 コピー先バッファーには、コピーされた文字列の切り捨てられたバージョンが含まれています。
STATUS_INVALID_PARAMETER
この エラー 状態は、関数が無効な入力パラメーターを受信したことを意味します。 詳細については、次の段落を参照してください。

関数は、次の場合にSTATUS_INVALID_PARAMETER値を返します。

  • cchDest の値が最大バッファー サイズを超えています。
  • 宛先バッファーは既にいっぱいでした。
  • NULL ポインターが存在しました。
  • コピー先バッファーの長さが 0 ですが、0 以外の長さのソース文字列が存在しました。

注釈

strncpy の代わりに RtlStringCchCopyNWRtlStringCchCopyNA を使用する必要があります。

関数は、ソース文字列から特定の数の文字をコピーします。 RtlStringCchCopyNWRtlStringCchCopyNA は、関数がバッファーの末尾を超えて書き込まれないようにするために、コピー先バッファーのサイズを文字単位で受け取ります。

これらの関数の動作は 、strncpy とは異なる点に注意してください。 cchSrcpszSrcRtlStringCchCopyNWRtlStringCchCopyNA (strncpy とは異なり) の文字数よりも大きい場合は、cchSrc 文字がコピーされるまで pszDest を null 文字で埋め続けないでください。

RtlStringCchCopyNW を使用して Unicode 文字列を処理し、RtlStringCchCopyNA を使用して ANSI 文字列を処理します。 次の表に示すように、使用するフォームはデータによって異なります。

文字列データ型 文字列リテラル 機能
WCHAR L"string" RtlStringCchCopyNW
char "string" RtlStringCchCopyNA
 

pszSrcpszDest が重複する文字列を指している場合、関数の動作は未定義です。

pszSrcpszDestNULL にすることはできません。 NULL 文字列ポインター値を処理する必要がある場合は、RtlStringCchCopyNEx を使用します

安全な文字列関数の詳細については、「安全な文字列関数の 使用」を参照してください。

要件

要件
サポートされている最小のクライアント Service Pack 1 (SP1) 以降のバージョンの Windows XP で使用できます。
対象プラットフォーム デスクトップ
Header ntstrsafe.h (Ntstrsafe.h を含む)
Library Ntstrsafe.lib
IRQL 操作される文字列が常にメモリ内に存在する場合は 、それ以外の場合は PASSIVE_LEVEL

こちらもご覧ください

RtlStringCbCopyN

RtlStringCchCopy

RtlStringCchCopyNEx