ヘッダー注釈
[このトピックでは、Windows 7 を通じて Windows ヘッダーでサポートされる注釈について説明します。 Windows 8 用に開発している場合は、「SAL Annotations」で説明されている注釈を使用する必要があります。
ヘッダー注釈は、関数がパラメーターと戻り値を使用する方法を記述します。 これらの注釈は、Windows API を正しく呼び出していることを確認するために、多くの Windows ヘッダー ファイルに追加されています。 Visual Studio 2005 以降で使用可能なコード分析を有効にすると、注釈で説明されている使用法に従ってこれらの関数を呼び出さない場合、コンパイラによってレベル 6000 の警告が生成されます。 これらの注釈を独自のコードに追加して、正しく呼び出されるようにすることもできます。 Visual Studio でコード分析を有効にするには、Visual Studio のバージョンのドキュメントを参照してください。
これらの注釈は Specstrings.h で定義されています。 これらは、標準注釈言語 (SAL) の一部であるプリミティブに基づいて構築され、_declspec("SAL_*")
を使用して実装されます。
注釈には、バッファー注釈と高度な注釈の 2 つのクラスがあります。
バッファー注釈
バッファー注釈は、関数がポインターを使用する方法を記述し、バッファー オーバーランを検出するために使用できます。 各パラメーターでは、0 個または 1 個のバッファー注釈を使用できます。 バッファー注釈は、先頭にアンダースコアと、次のセクションで説明するコンポーネントで構成されます。
バッファー サイズ | 形容 |
---|---|
(サイズ) |
バッファーの合計サイズを指定します。 _bcountと_ecountで使用する。_partでは使用しないでください。 この値は、アクセス可能な領域です。割り当てられた領域より小さい場合があります。 |
(size,length) |
バッファーの合計サイズと初期化された長さを指定します。 _bcount_partと_ecount_partで使用します。 合計サイズは、割り当てられた領域より小さい場合があります。 |
バッファー サイズの単位 | 形容 |
---|---|
_bcount |
バッファー サイズはバイト単位です。 |
_ecount |
バッファー サイズは要素単位です。 |
方向 | 形容 |
---|---|
_in |
関数はバッファーから読み取ります。 呼び出し元はバッファーを提供し、それを初期化します。 |
_inout |
この関数は、バッファーからの読み取りとバッファーへの書き込みの両方を行います。 呼び出し元はバッファーを提供し、それを初期化します。 _derefと共に使用する場合、バッファーは関数によって再割り当てされる可能性があります。 |
_out |
関数はバッファーに書き込みます。 戻り値または_derefで使用する場合、関数はバッファーを提供して初期化します。 それ以外の場合、呼び出し元はバッファーを提供し、関数はそれを初期化します。 |
間接 | 形容 |
---|---|
_deref |
パラメーターを逆参照してバッファー ポインターを取得します。 このパラメーターは NULL できません。 |
_deref_opt |
パラメーターを逆参照してバッファー ポインターを取得します。 このパラメーターは NULL できます。 |
初期化 | 形容 |
---|---|
_full |
この関数はバッファー全体を初期化します。 出力バッファーでのみ使用します。 |
_part |
この関数はバッファーの一部を初期化し、その量を明示的に示します。 出力バッファーでのみ使用します。 |
必須または省略可能なバッファー | 形容 |
---|---|
_opt |
このパラメーターは NULL できます。 |
次の例は、GetModuleFileName 関数の注釈を示しています。 hModule パラメーターは省略可能な入力パラメーターです。 lpFilename パラメーターは出力パラメーターです。そのサイズは、nSize パラメーターで指定され、その長さは null -terminating 文字含まれます。 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(size,length)
__deref_inout_bcount_part_opt(size,length)
__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(size,length)
__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(size,length)
__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(size,length)
__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(size,length)
__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(size,length)
__deref_opt_out_ecount_part_opt(size,length)
__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(size,length)
__deref_out_bcount_part_opt(size,length)
__deref_out_ecount(size)
__deref_out_ecount_full(size)
__deref_out_ecount_full_opt(size)
__deref_out_ecount_opt(size)
__deref_out_ecount_part(size,length)
__deref_out_ecount_part_opt(size,length)
__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(size,length)
__inout_bcount_part_opt(size,length)
__inout_ecount(size)
__inout_ecount_full(size)
__inout_ecount_full_opt(size)
__inout_ecount_opt(size)
__inout_ecount_part(size,length)
__inout_ecount_part_opt(size,length)
__inout_opt
__アウト
__out_bcount(size)
__out_bcount_full(size)
__out_bcount_full_opt(size)
__out_bcount_opt(size)
__out_bcount_part(size,length)
__out_bcount_part_opt(size,length)
__out_ecount(size)
__out_ecount_full(size)
__out_ecount_full_opt(size)
__out_ecount_opt(size)
__out_ecount_part(size,length)
__out_ecount_part_opt(size,length)
__out_opt
高度な注釈
高度な注釈は、パラメーターまたは戻り値に関する追加情報を提供します。 各パラメーターまたは戻り値には、0 個または 1 つの高度な注釈を使用できます。
注釈 | 形容 |
---|---|
__blocksOn(resource) |
関数は、指定されたリソースをブロックします。 |
__callback |
関数は、関数ポインターとして使用できます。 |
__checkReturn |
呼び出し元は戻り値を確認する必要があります。 |
__format_string |
このパラメーターは、printf スタイルの % マーカーを含む文字列です。 |
__in_awcount(expr,size) |
終了時に式が true の場合、入力バッファーのサイズはバイト単位で指定されます。 式が false の場合、サイズは要素で指定されます。 |
__nullnullterminated |
バッファーには、2 つの null 文字またはポインターの最初のシーケンスまでアクセスできます。 |
__nullterminated |
バッファーには、最初の null 文字またはポインターまでアクセスできます。 |
__out_awcount(expr,size) |
終了時に式が true の場合、出力バッファーのサイズはバイト単位で指定されます。 式が false の場合、サイズは要素で指定されます。 |
__override |
仮想メソッドの C#スタイルのオーバーライド動作を指定します。 |
__reserved |
このパラメーターは将来使用するために予約されており、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
);