次の方法で共有

関数パラメーターおよび戻り値の注釈設定

  • [アーティクル]

ここでは、バッファー内の構造体とクラスおよびほとんどの種類に単純な機能のスカラー パラメーターのコメントの一般的な使用方法、およびポインターについて説明します。この記事では、コメントの一般的な使用パターンを示します。関数に関連する追加コメントでは、関数の動作に注釈を付けるを参照してください。

ポインターのパラメーター

次の表にコメントを記述する場合は、ポインター パラメーターが指定されている場合、アナライザーは、ポインターが null の場合にエラーを報告します。これは、ポインターが指すすべてのデータ項目に適用されます。

注釈

説明

_In_

スカラーなど、構造体、構造体へのポインターである入力パラメーターを指定します。明示的には、スカラーで使用される場合があります。パラメーターは、前の状態で有効である必要があり、変更されません。

_Out_

スカラーなど、構造体、構造体へのポインターである出力パラメーターを指定します。例の値を返すことができないオブジェクト値渡しスカラーこれには適用されません。パラメーターは、前の状態で有効である必要はよろしくなかったり後の状態で有効である必要があります。

_Inout_

関数によって変更されるパラメーターを指定します。前の状態と後置状態の両方で有効である必要がありますが、の呼び出し前後に異なる値を持つことを前提としています。変更可能な値に適用する必要があります。

_In_z_

入力として使用される NULL で終わる文字列へのポインター。文字列には、前の状態で有効である必要があります。既に正しいコメントがある PSTRのバリアントに適しています。

_Inout_z_

変更される NULL で終わる文字配列へのポインター。これには、値が変化すると仮定した後に有効にする必要があります。null の実行元の null 終端文字までの要素しかアクセスできないことがあります。

_In_reads_(s)

_In_reads_bytes_(s)

関数によって読み取られる配列へのポインター。配列は有効である必要があるサイズの s 内の要素です。

_bytes_ のバリアントではなく要素のサイズをバイト単位で指定します。サイズが要素として表現できない場合にのみ機能を使用します。たとえば、char の文字列は wchar_t を使用しても同様の関数が _bytes_ 場合にのみのバリエーションを使用します。

_In_reads_z_(s)

null で終わるできる既知のサイズを持つ配列へのポインター。null 値が存在しない場合、null 終端記号または s までの要素は、状態で有効な終端なります。サイズがバイト単位でしている場合は、要素のサイズによってスケール s。

_In_reads_or_z_(s)

null で終わるか、既知のサイズを持つ配列へのポインター、または両方。null 値が存在しない場合、null 終端記号または s までの要素は、状態で有効な終端なります。サイズがバイト単位でしている場合は、要素のサイズによってスケール s。(strn ファミリのために使用)。

_Out_writes_(s)

_Out_writes_bytes_(s)

s の要素 (resp の配列へのポインター。関数によって作成されたバイト単位)。配列要素は前の状態で有効でなく、POST 状態で有効な要素数は指定されていません。パラメーターの場合はコメントの後の状態で適用されます入力します。次に例を示します。

typedef _Null_terminated_ wchar_t *PWSTR;
void MyStringCopy(_Out_writes_ (size) PWSTR p1,
   _In_ size_t size,
   _In_ PWSTR p2);

この例では、呼び出し元は p1に size の要素のバッファーを提供します。MyStringCopy は、要素の一部を有効にします。さらに重要な、PWSTR の _Null_terminated_ のコメントは p1 後で状態が null で終わることを意味します。このように、有効な要素の数は、正しく定義されていますが、特定の要素の計算は必要ではありません。

_bytes_ のバリアントではなく要素のサイズをバイト単位で指定します。サイズが要素として表現できない場合にのみ機能を使用します。たとえば、char の文字列は wchar_t を使用しても同様の関数が _bytes_ 場合にのみのバリエーションを使用します。

_Out_writes_z_(s)

s 要素の配列へのポインター。要素は、状態で有効である必要はありません。後で状態は、要素は終端文字を指定する null で現在有効になります。サイズがバイト単位でしている場合は、要素のサイズによってスケール s。

_Inout_updates_(s)

_Inout_updates_bytes_(s)

両方で関数に読み取って記述された配列へのポインター。これは、サイズの s の要素、前の状態と後置状態で有効です。

_bytes_ のバリアントではなく要素のサイズをバイト単位で指定します。サイズが要素として表現できない場合にのみ機能を使用します。たとえば、char の文字列は wchar_t を使用しても同様の関数が _bytes_ 場合にのみのバリエーションを使用します。

_Inout_updates_z_(s)

null で終わるできる既知のサイズを持つ配列へのポインター。要素は、の終端 null で事前条件と後置状態の両方で現在有効になります。後の状態の値は、前の状態の値と異なる;推論されます これは、null 終端文字の位置が含まれています。サイズがバイト単位でしている場合は、要素のサイズによってスケール s。

_Out_writes_to_(s,c)

_Out_writes_bytes_to_(s,c)

_Out_writes_all_(s)

_Out_writes_bytes_all_(s)

s 要素の配列へのポインター。要素は、状態で有効である必要はありません。後で、c状態までの要素-番目の要素は有効である必要があります。サイズがバイト単位でしている場合は、要素のサイズによってスケール s と c は、次のように定義されている _bytes_ のバリエーションを使用します:

   _Out_writes_to_(_Old_(s), _Old_(s))
   _Out_writes_bytes_to_(_Old_(s), _Old_(s))

つまり、前の状態 s までバッファーにある要素は、後の状態で使用できます。次に例を示します。

void *memcpy(_Out_writes_bytes_all_(s) char *p1,
   _In_reads_bytes_(s) char *p2,
   _In_ int s);
void * wordcpy(_Out_writes_all_(s) DWORD *p1, 
   _In_reads_(s) DWORD *p2,
   _In_ int s);

_Inout_updates_to_(s,c)

_Inout_updates_bytes_to_(s,c)

両方関数によって読み取られ、記述された配列へのポインター。ここでは、前の状態で有効である必要が c の要素は後の状態で有効である必要があります s のサイズの要素です。

_bytes_ のバリアントではなく要素のサイズをバイト単位で指定します。サイズが要素として表現できない場合にのみ機能を使用します。たとえば、char の文字列は wchar_t を使用しても同様の関数が _bytes_ 場合にのみのバリエーションを使用します。

_Inout_updates_all_(s)

_Inout_updates_bytes_all_(s)

両方のサイズ s の要素の関数によって読み取られ、記述された配列へのポインター。と等価で定義された:

   _Inout_updates_to_(_Old_(s), _Old_(s))
   _Inout_updates_bytes_to_(_Old_(s), _Old_(s))

つまり、前の状態 s までバッファーにある要素は、状態と後置状態で有効です。

_bytes_ のバリアントではなく要素のサイズをバイト単位で指定します。サイズが要素として表現できない場合にのみ機能を使用します。たとえば、char の文字列は wchar_t を使用しても同様の関数が _bytes_ 場合にのみのバリエーションを使用します。

_In_reads_to_ptr_(p)

式 p – _Curr_ (つまり、_Curr_減算 p) が適切な言語標準で定義された配列へのポインター。p 前の要素は、状態で有効である必要があります。

_In_reads_to_ptr_z_(p)

式 p – _Curr_ (つまり、_Curr_減算 p) が適切な言語の標準で定義される null で終わる配列へのポインター。p 前の要素は、状態で有効である必要があります。

_Out_writes_to_ptr_(p)

式 p – _Curr_ (つまり、_Curr_減算 p) が適切な言語標準で定義された配列へのポインター。p 前の要素は、状態で有効でなく、POST 状態で有効である必要があります。

_Out_writes_to_ptr_z_(p)

式 p – _Curr_ (つまり、_Curr_減算 p) が適切な言語の標準で定義される null で終わる配列へのポインター。p 前の要素は、状態で有効でなく、POST 状態で有効である必要があります。

省略可能なポインター パラメーター

ポインター パラメーターのコメントは _opt_が含まれる場合、パラメーターが null である可能性があることを示します。それ以外の場合、コメントは _opt_を含まないバージョンと同じを実行します。ポインター パラメーターのコメントの _opt_ のバリアントの一覧を次に示します。:

_In_opt_

_Out_opt_

_Inout_opt_

_In_opt_z_

_Inout_opt_z_

_In_reads_opt_

_In_reads_bytes_opt_

_In_reads_opt_z_

_Out_writes_opt_

_Out_writes_opt_z_

_Inout_updates_opt_

_Inout_updates_bytes_opt_

_Inout_updates_opt_z_

_Out_writes_to_opt_

_Out_writes_bytes_to_opt_

_Out_writes_all_opt_

_Out_writes_bytes_all_opt_

_Inout_updates_to_opt_

_Inout_updates_bytes_to_opt_

_Inout_updates_all_opt_

_Inout_updates_bytes_all_opt_

_In_reads_to_ptr_opt_

_In_reads_to_ptr_opt_z_

_Out_writes_to_ptr_opt_

_Out_writes_to_ptr_opt_z_

出力のポインター パラメーター

出力のポインターをパラメーターと特殊な表記がパラメーターの位置に null ness を区別するように要求します。

注釈

説明

_Outptr_

パラメーターは null 以外である位置に後で状態を null にすることはできず、有効である必要があります。

_Outptr_opt_

null にする位置に後で状態を null にすることはできず、有効である必要があります。

_Outptr_result_maybenull_

パラメーターは null 以外である位置、POST 状態に null を指定できます。

_Outptr_opt_result_maybenull_

パラメーターは null の可能性が位置、POST 状態に null を指定できます。

次の表では、にコメントの意味を修飾するためには追加の部分文字列はコメントの名前に挿入されます。さまざまな部分文字列は _z、_COM_、_buffer_、_bytebuffer_と _to_です。

重要 : 重要

注釈が使用するインターフェイスが COM、これらのコメントの COM フォームを使用します。他の型のインターフェイスを持つ COM のコメントは使用しないでください。

注釈

説明

_Outptr_result_z_

_Outptr_opt_result_z_

_Outptr_result_maybenull_z_

_Ouptr_opt_result_maybenull_z_

返されたポインターに _Null_terminated_ のコメントがあります。

_COM_Outptr_

_COM_Outptr_opt_

_COM_Outptr_result_maybenull_

_COM_Outptr_opt_result_maybenull_

したがって、返されたポインターが null であること、返されたポインターに COM 規則があり、_On_failure_ POST 要求を行います。

_Outptr_result_buffer_(s)

_Outptr_result_bytebuffer_(s)

_Outptr_opt_result_buffer_(s)

_Outptr_opt_result_bytebuffer_(s)

サイズの s の要素またはバイトの有効な返されたバッファーへのポインターのポインター。

_Outptr_result_buffer_to_(s, c)

_Outptr_result_bytebuffer_to_(s, c)

_Outptr_opt_result_buffer_to_(s,c)

_Outptr_opt_result_bytebuffer_to_(s,c)

最初の c が有効であるバイトまたは s の要素のサイズのバッファーを指す返されたポインターのポインター。

特定のインターフェイスの規則は出力パラメーターが失敗で無効になっていると仮定します。明示的に COM を除き、次の表に、フォーム コードお勧めします。COM コードでは、前のセクションで示した対応する COM の形式を使用します。

注釈

説明

_Result_nullonfailure_

他のコメントを変更します。結果は無効にするには、関数が失敗した場合に設定されます。

_Result_zeroonfailure_

他のコメントを変更します。結果は、関数が失敗した場合はゼロに設定されます。

_Outptr_result_nullonfailure_

関数が失敗した場合は、関数が成功した場合は有効なバッファーを指す返されたポインターの位置、または null。ここでは、省略可能なパラメーターがあります。

_Outptr_opt_result_nullonfailure_

関数が失敗した場合は、関数が成功した場合は有効なバッファーを指す返されたポインターの位置、または null。ここでは、省略可能なパラメーターに対してです。

_Outref_result_nullonfailure_

関数が失敗した場合は、関数が成功した場合は有効なバッファーを指す返されたポインターの位置、または null。ここでは、参照パラメーター用です。

出力参照パラメーター

参照パラメーターのは一般的に、出力パラメーター用です。パラメーター例の単純な出力参照のため、int&—_Out_ は、正しいセマンティクスを提供します。ただし _Outptr_ int ** が正しいセマンティクスを提供しないように、出力値を int *&例—同等のポインターのコメントのポインターである場合。簡単にポインター型の出力パラメーター参照セマンティクスを表現するには、次の複合コメントの使用:

注釈

説明

_Outref_

結果は後の状態で有効である必要があり、null にすることはできません。

_Outref_result_maybenull_

結果は後の状態で有効である必要があります。後で状態が null である可能性があります。

_Outref_result_buffer_(s)

結果は後の状態で有効である必要があり、null にすることはできません。サイズの s の要素の有効なバッファーへのポインター。

_Outref_result_bytebuffer_(s)

結果は後の状態で有効である必要があり、null にすることはできません。サイズの s バイトの有効なバッファーへのポインター。

_Outref_result_buffer_to_(s, c)

結果は後の状態で有効である必要があり、null にすることはできません。最初の c が有効である s の要素のバッファーへのポインター。

_Outref_result_bytebuffer_to_(s, c)

結果は後の状態で有効である必要があり、null にすることはできません。最初の c が有効である s バイトのバッファーへのポインター。

_Outref_result_buffer_all_(s)

結果は後の状態で有効である必要があり、null にすることはできません。サイズの s の有効な要素の有効なバッファーへのポインター。

_Outref_result_bytebuffer_all_(s)

結果は後の状態で有効である必要があり、null にすることはできません。有効な要素に s バイトの有効なバッファーへのポインター。

_Outref_result_buffer_maybenull_(s)

結果は後の状態で有効である必要があります。後で状態が null である可能性があります。サイズの s の要素の有効なバッファーへのポインター。

_Outref_result_bytebuffer_maybenull_(s)

結果は後の状態で有効である必要があります。後で状態が null である可能性があります。サイズの s バイトの有効なバッファーへのポインター。

_Outref_result_buffer_to_maybenull_(s, c)

結果は後の状態で有効である必要があります。後で状態が null である可能性があります。最初の c が有効である s の要素のバッファーへのポインター。

_Outref_result_bytebuffer_to_maybenull_(s,c)

結果は後の状態で有効である必要があります。後の状態で null である可能性があります。最初の c が有効である s バイトのバッファーへのポインター。

_Outref_result_buffer_all_maybenull_(s)

結果は後の状態で有効である必要があります。後の状態で null である可能性があります。サイズの s の有効な要素の有効なバッファーへのポインター。

_Outref_result_bytebuffer_all_maybenull_(s)

結果は後の状態で有効である必要があります。後の状態で null である可能性があります。有効な要素に s バイトの有効なバッファーへのポインター。

戻り値

関数の戻り値は _Out_ のパラメーターに似ていますが、逆参照のレベルにあり、結果へのポインターの概念を考慮する必要はありません。次のコメントでは、戻り値は構造体へ注釈先オブジェクトのスカラー、ポインター、またはバッファーへのポインターです。これらのコメントに _Out_ の対応するコメントと同じセマンティクスがあります。

_Ret_z_

_Ret_writes_(s)

_Ret_writes_bytes_(s)

_Ret_writes_z_(s)

_Ret_writes_to_(s,c)

_Ret_writes_maybenull_(s)

_Ret_writes_to_maybenull_(s)

_Ret_writes_maybenull_z_(s)

_Ret_maybenull_

_Ret_maybenull_z_

_Ret_null_

_Ret_notnull_

_Ret_writes_bytes_to_

_Ret_writes_bytes_maybenull_

_Ret_writes_bytes_to_maybenull_

そのほかのコメント

注釈

説明

_In_range_(low, hi)

_Out_range_(low, hi)

_Ret_range_(low, hi)

_Deref_in_range_(low, hi)

_Deref_out_range_(low, hi)

_Deref_inout_range_(low, hi)

_Field_range_(low, hi)

パラメーター、フィールド、または結果は low から hiでスコープ内に (包括) です。適切な状態前または後の状態の状態とともに指定されたオブジェクトに適用される _Satisfies_(_Curr_ >= low && _Curr_ <= hi) に相当します。

重要 : 重要
名前が" および "" の "含まれていますが、_In_ のセマンティクスと _Out_ は、これらのコメントには適用されません。

_Pre_equal_to_(expr)

_Post_equal_to_(expr)

注釈付きの値は、exprです。適切な状態前または後の状態の状態とともに指定されたオブジェクトに適用される _Satisfies_(_Curr_ == expr) に相当します。

_Struct_size_bytes_(size)

構造体またはクラスの申告に適用されます。その型の有効なオブジェクトが宣言された型よりも大きい場合があります sizeで指定されたバイト数とことを示します。次に例を示します。

typedef _Struct_size_bytes_(nSize)
struct MyStruct {
   size_t nSize;
   ...
};

型 MyStruct * のパラメーター pM バイトのバッファー サイズは次のように記述するために取得されます:

   min(pM->nSize, sizeof(MyStruct))

関連リソース

コード分析のチームのブログ

参照

関連項目

関数の動作に注釈を付ける

構造体とクラスに注釈を付ける

ロック動作に注釈を付ける

注釈を適用するタイミングと場所の指定

組み込み関数

ベスト プラクティスと例 (SAL)

概念

SAL について

その他の技術情報

SAL 注釈を使って C/C++ のコード障害を減らす方法