ヘッダー注釈

  • [アーティクル]

[このトピックでは、Windows 7 を通じて Windows ヘッダーでサポートされる注釈について説明します。 Windows 8用に開発している場合は、「SAL 注釈」で説明されている注釈を使用する必要があります。

ヘッダー注釈は、関数がそのパラメーターと戻り値を使用する方法を記述します。 これらの注釈は、Windows API を正しく呼び出すのに役立つ多くの Windows ヘッダー ファイルに追加されています。 Visual Studio 2005 以降で使用可能なコード分析を有効にすると、注釈で説明されている使用法に従ってこれらの関数を呼び出していない場合、コンパイラによってレベル 6000 の警告が生成されます。 これらの注釈を独自のコードに追加して、正しく呼び出されるようにすることもできます。 Visual Studio でコード分析を有効にするには、Visual Studio のバージョンに関するドキュメントを参照してください。

これらの注釈は Specstrings.h で定義されています。 これらは、標準注釈言語 (SAL) の一部であるプリミティブに基づいて構築され、 を使用して _declspec("SAL_*")実装されます。

注釈には、バッファー注釈と高度な注釈の 2 つのクラスがあります。

バッファー注釈

バッファー注釈は、関数がポインターを使用する方法を説明し、バッファー オーバーランを検出するために使用できます。 各パラメーターでは、0 個または 1 個のバッファー注釈を使用できます。 バッファー注釈は、先頭のアンダースコアと、次のセクションで説明するコンポーネントで構成されます。

バッファー サイズ 説明
(サイズ)
 バッファーの合計サイズを指定します。 _bcountと_ecountで使用します。は、_partで使用しないでください。 この値は、アクセス可能な領域です。割り当てられた領域より小さい場合があります。
(サイズ、長さ)
 バッファーの合計サイズと初期化された長さを指定します。 _bcount_partと_ecount_partと共に使用します。 合計サイズは、割り当てられた領域よりも小さい場合があります。
バッファー サイズの単位 説明
_bcount
 バッファー サイズはバイト単位です。
_ecount
 バッファー サイズは要素内にあります。
Direction 説明
_インチ
 関数はバッファーから読み取ります。 呼び出し元はバッファーを提供し、それを初期化します。
_Inout
 関数は、バッファーからの読み取りとバッファーへの書き込みの両方を行います。 呼び出し元はバッファーを提供し、それを初期化します。 _derefと共に使用する場合、バッファーは 関数によって再割り当てされる可能性があります。
_乙
 関数はバッファーに書き込みます。 戻り値または _deref で使用する場合、関数はバッファーを提供して初期化します。 それ以外の場合、呼び出し元はバッファーを提供し、関数はそれを初期化します。
間接 説明
_deref
 パラメーターを逆参照してバッファー ポインターを取得します。 このパラメーターは NULL にすることはできません。
_deref_opt
 パラメーターを逆参照してバッファー ポインターを取得します。 このパラメーターは、NULL でもかまいません。
初期化 説明
_完全
 関数はバッファー全体を初期化します。 出力バッファーでのみ使用します。
_一部
 関数はバッファーの一部を初期化し、その量を明示的に示します。 出力バッファーでのみ使用します。
必須または省略可能なバッファー 説明
_選ぶ
 このパラメーターは、NULL でもかまいません。

次の例は、 GetModuleFileName 関数の注釈を示しています。 hModule パラメーターは、省略可能な入力パラメーターです。 lpFilename パラメーターは出力パラメーターです。そのサイズは nSize パラメーターで指定され、その長さは null 終端文字を含みます。 nSize パラメーターは入力パラメーターです。

DWORD
WINAPI
GetModuleFileName(
    __in_opt HMODULE hModule,
    __out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
    __in DWORD nSize
    );

Specstrings.h で定義されている注釈を次に示します。 上の表の情報を使用して、その意味を解釈します。

__bcount(size)
__bcount_opt(size)
__deref_bcount(size)
__deref_bcount_opt(size)
__deref_ecount(size)
__deref_ecount_opt(size)
__deref_in
__deref_in_bcount(size)
__deref_in_bcount_opt(size)
__deref_in_ecount(size)
__deref_in_ecount_opt(size)
__deref_in_opt
__deref_inout
__deref_inout_bcount(size)
__deref_inout_bcount_full(size)
__deref_inout_bcount_full_opt(size)
__deref_inout_bcount_opt(size)
__deref_inout_bcount_part(サイズ,長さ)
__deref_inout_bcount_part_opt(サイズ,長さ)
__deref_inout_ecount(size)
__deref_inout_ecount_full(size)
__deref_inout_ecount_full_opt(size)
__deref_inout_ecount_opt(size)
__deref_inout_ecount_part(size,length)
__deref_inout_ecount_part_opt(サイズ,長さ)
__deref_inout_opt
__deref_opt_bcount(size)
__deref_opt_bcount_opt(size)
__deref_opt_ecount(size)
__deref_opt_ecount_opt(size)
__deref_opt_in
__deref_opt_in_bcount(size)
__deref_opt_in_bcount_opt(size)
__deref_opt_in_ecount(size)
__deref_opt_in_ecount_opt(size)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount(size)
__deref_opt_inout_bcount_full(size)
__deref_opt_inout_bcount_full_opt(size)
__deref_opt_inout_bcount_opt(size)
__deref_opt_inout_bcount_part(size,length)
__deref_opt_inout_bcount_part_opt(サイズ,長さ)
__deref_opt_inout_ecount(size)
__deref_opt_inout_ecount_full(size)
__deref_opt_inout_ecount_full_opt(size)
__deref_opt_inout_ecount_opt(size)
__deref_opt_inout_ecount_part(size,length)
__deref_opt_inout_ecount_part_opt(サイズ,長さ)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount(size)
__deref_opt_out_bcount_full(size)
__deref_opt_out_bcount_full_opt(size)
__deref_opt_out_bcount_opt(size)
__deref_opt_out_bcount_part(size,length)
__deref_opt_out_bcount_part_opt(サイズ,長さ)
__deref_opt_out_ecount(size)
__deref_opt_out_ecount_full(size)
__deref_opt_out_ecount_full_opt(size)
__deref_opt_out_ecount_opt(size)
__deref_opt_out_ecount_part(サイズ,長さ)
__deref_opt_out_ecount_part_opt(サイズ,長さ)
__deref_opt_out_opt
__deref_out
__deref_out_bcount(size)
__deref_out_bcount_full(size)
__deref_out_bcount_full_opt(size)
__deref_out_bcount_opt(size)
__deref_out_bcount_part(サイズ,長さ)
__deref_out_bcount_part_opt(サイズ,長さ)
__deref_out_ecount(size)
__deref_out_ecount_full(size)
__deref_out_ecount_full_opt(size)
__deref_out_ecount_opt(size)
__deref_out_ecount_part(サイズ,長さ)
__deref_out_ecount_part_opt(サイズ,長さ)
__deref_out_opt
__ecount(size)
__ecount_opt(size)
__インチ
__in_bcount(size)
__in_bcount_opt(size)
__in_ecount(size)
__in_ecount_opt(size)
__in_opt
__Inout
__inout_bcount(size)
__inout_bcount_full(size)
__inout_bcount_full_opt(size)
__inout_bcount_opt(size)
__inout_bcount_part(サイズ,長さ)
__inout_bcount_part_opt(サイズ,長さ)
__inout_ecount(size)
__inout_ecount_full(size)
__inout_ecount_full_opt(size)
__inout_ecount_opt(size)
__inout_ecount_part(サイズ,長さ)
__inout_ecount_part_opt(サイズ,長さ)
__inout_opt
__乙
__out_bcount(size)
__out_bcount_full(size)
__out_bcount_full_opt(size)
__out_bcount_opt(size)
__out_bcount_part(サイズ,長さ)
__out_bcount_part_opt(size,length)
__out_ecount(サイズ)
__out_ecount_full(size)
__out_ecount_full_opt(size)
__out_ecount_opt(size)
__out_ecount_part(サイズ,長さ)
__out_ecount_part_opt(サイズ,長さ)
__out_opt

高度な注釈

高度な注釈は、パラメーターまたは戻り値に関する追加情報を提供します。 各パラメーターまたは戻り値では、0 個または 1 つの高度な注釈を使用できます。

注釈 説明
__blocksOn(resource)
 関数は、指定されたリソースをブロックします。
__コールバック
 関数は、関数ポインターとして使用できます。
__checkReturn
 呼び出し元は戻り値をチェックする必要があります。
__format_string
 パラメーターは、printf スタイルの % マーカーを含む文字列です。
__in_awcount(expr,size)
 式が終了時に true の場合、入力バッファーのサイズはバイト単位で指定されます。 式が false の場合、サイズは要素で指定されます。
__nullnullterminated
 バッファーには、2 つの null 文字またはポインターの最初のシーケンスまでアクセスできます。
__nullterminated
 バッファーには、最初の null 文字またはポインターまでアクセスできます。
__out_awcount(expr,size)
 式が終了時に true の場合、出力バッファーのサイズはバイト単位で指定されます。 式が false の場合、サイズは要素で指定されます。
__オーバーライド
 仮想メソッドの C#スタイルのオーバーライド動作を指定します。
__予約
 パラメーターは将来使用するために予約されており、0 または NULL である必要があります。
__success(expr)
 式が終了時に true の場合、呼び出し元は他の注釈で指定されたすべての保証に依存できます。 式が false の場合、呼び出し元は保証に依存できません。 この注釈は、 HRESULT 値を返す関数に自動的に追加されます。
__typefix(ctype)
 パラメーターは、宣言された型ではなく、指定した型として扱います。

次の例では、 DeleteTimerQueueTimer、 FreeEnvironmentStrings、 UnhandledExceptionFilter 関数のバッファーと高度な注釈を示します。

__checkReturn
BOOL
WINAPI
DeleteTimerQueueTimer(
    __in_opt HANDLE TimerQueue,
    __in     HANDLE Timer,
    __in_opt HANDLE CompletionEvent
    );

BOOL
WINAPI
FreeEnvironmentStrings(
    __in __nullnullterminated LPTCH
    );

__callback
LONG
WINAPI
UnhandledExceptionFilter(
    __in struct _EXCEPTION_POINTERS *ExceptionInfo
    );

SAL 注釈

チュートリアル: C/C++ コードの欠陥の分析