次の方法で共有


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

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

ポインター パラメーター

次の表では、ポインター パラメーターが指定されている場合、アナライザーはポインターが NULL の場合、エラーが報告されます。これは、ポインターが指すデータ項目に適用されます。

注釈

説明

_In_

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

_Out_

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

_Inout_

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

_In_z_

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

_Inout_z_

変更する null で終わるな文字配列へのポインター。次に呼び出し、値が変化すると想定されての前後で有効である必要があります。移動された元の null 終端文字までの要素のみアクセスされる可能性があります。

_In_reads_(s)

_In_reads_bytes_(s)

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

_bytes_ のバリアントで要素の代わりにサイズをバイト単位で示します。このサイズが配列として表現できない場合にのみ機能を使用します。たとえば、char の文字列は wchar_t に似た機能を使用する場合にのみ _bytes_ のバリエーションを使用します。

_In_reads_z_(s)

null で終わる、既知のサイズが異なる配列へのポインター。空白が見つからなかった場合は NULL 終端記号または s までの要素は前の状態で有効な終端記号です。サイズがバイト単位でわかっている場合、要素のサイズによって s をスケーリングします。

_In_reads_or_z_(s)

null で終わるまたは既知のサイズが異なる配列へのポインター、または両方。空白が見つからなかった場合は NULL 終端記号または s までの要素は前の状態で有効な終端記号です。サイズがバイト単位でわかっている場合、要素のサイズによって s をスケーリングします。(strn ファミリに使用されます)。

_Out_writes_(s)

_Out_writes_bytes_(s)

s 要素 (resp の配列へのポインター。関数によって作成されたバイト)。配列要素は前の状態で有効でなくてもかまいません。後状態で有効な要素数は指定されていません。パラメーターの型の注釈が存在する場合、状態は後で適用されます。次に例を示します。

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まで要素- th 要素が有効である必要があります。サイズがバイト単位でわかっている場合、要素のサイズによって、スケール 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)

両方関数によって読み取られ、書き込まれる配列へのポインター。このプロパティは Pre 状態で有効である必要 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 直前の要素が前の状態で有効である必要はありませんが、後で状態で有効である必要があります。

_Out_writes_to_ptr_z_(p)

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

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

注釈は _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 かを区別するように要求します。

注釈

説明

_Outptr_

パラメーターが null であり尖先の場所は、状態で空白を使用できず、有効である必要があります。

_Outptr_opt_

null にする先の場所尖後に状態で空白を使用できず、有効である必要があります。

_Outptr_result_maybenull_

パラメーターが null であり尖先の場所に、状態は NULL にすることができます。

_Outptr_opt_result_maybenull_

パラメーターが NULL である場合があります尖先の場所に、状態は 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_ の後条件があります。

_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_

他の注釈を変更します。結果は NULL に関数が失敗した場合に設定されます。

_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 要素の enabled バッファーへのポインター。

_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 要素の enabled バッファーへのポインター。

_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_ はこれらの注釈に not を適用します。

_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++ のコード障害を減らす方法