標頭批註
[本主題描述透過 Windows 7 在 Windows 標頭中支援的批註。 如果您要針對 Windows 8 進行開發，您應該使用 SAL 註釋中所述的批註。]
標頭批註描述函式如何使用其參數和傳回值。 這些批注已新增至許多 Windows 頭檔，以協助您確定您已正確呼叫 Windows API。 如果您啟用從 Visual Studio 2005 開始可用的程式代碼分析，如果您未根據註釋所述的使用方式呼叫這些函式，編譯程式將會產生層級 6000 警告。 您也可以在自己的程式代碼中新增這些批注，以確保呼叫正確。 若要在 Visual Studio 中啟用程式代碼分析，請參閱 Visual Studio 版本的檔。
這些批注定義於Specstrings.h中。 它們是建置在標準批註語言 （SAL） 的基本類型上，並使用 _declspec("SAL_*")實作。
註釋有兩個類別：緩衝區批註和進階批註。
緩衝區批注
緩衝區批注描述函式如何使用其指標，並可用來偵測緩衝區滿溢。 每個參數都可能會使用零或一個緩衝區批注。 緩衝區批註是使用前置底線和下列各節中所述的元件所建構。
| 緩衝區大小 | 描述 |
|---|---|
|
（大小） |
指定緩衝區的總大小。 搭配_bcount和_ecount使用;請勿搭配_part使用。 這個值是可存取的空間;它可能小於配置的空間。 |
|
（大小，長度） |
指定緩衝區的大小總計和初始化長度。 搭配 _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（大小）
__bcount_opt（大小）
__deref_bcount（大小）
__deref_bcount_opt（大小）
__deref_ecount（大小）
__deref_ecount_opt（大小）
__deref_in
__deref_in_bcount（大小）
__deref_in_bcount_opt（大小）
__deref_in_ecount（大小）
__deref_in_ecount_opt（大小）
__deref_in_opt
__deref_inout
__deref_inout_bcount（大小）
__deref_inout_bcount_full（大小）
__deref_inout_bcount_full_opt（大小）
__deref_inout_bcount_opt（大小）
__deref_inout_bcount_part（大小，長度）
__deref_inout_bcount_part_opt（大小，長度）
__deref_inout_ecount（大小）
__deref_inout_ecount_full（大小）
__deref_inout_ecount_full_opt（大小）
__deref_inout_ecount_opt（大小）
__deref_inout_ecount_part（大小，長度）
__deref_inout_ecount_part_opt（大小，長度）
__deref_inout_opt
__deref_opt_bcount（大小）
__deref_opt_bcount_opt（大小）
__deref_opt_ecount（大小）
__deref_opt_ecount_opt（大小）
__deref_opt_in
__deref_opt_in_bcount（大小）
__deref_opt_in_bcount_opt（大小）
__deref_opt_in_ecount（大小）
__deref_opt_in_ecount_opt（大小）
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount（大小）
__deref_opt_inout_bcount_full（大小）
__deref_opt_inout_bcount_full_opt（大小）
__deref_opt_inout_bcount_opt（大小）
__deref_opt_inout_bcount_part（大小，長度）
__deref_opt_inout_bcount_part_opt（大小，長度）
__deref_opt_inout_ecount（大小）
__deref_opt_inout_ecount_full（大小）
__deref_opt_inout_ecount_full_opt（大小）
__deref_opt_inout_ecount_opt（大小）
__deref_opt_inout_ecount_part（大小，長度）
__deref_opt_inout_ecount_part_opt（大小，長度）
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount（大小）
__deref_opt_out_bcount_full（大小）
__deref_opt_out_bcount_full_opt（大小）
__deref_opt_out_bcount_opt（大小）
__deref_opt_out_bcount_part（大小，長度）
__deref_opt_out_bcount_part_opt（大小，長度）
__deref_opt_out_ecount（大小）
__deref_opt_out_ecount_full（大小）
__deref_opt_out_ecount_full_opt（大小）
__deref_opt_out_ecount_opt（大小）
__deref_opt_out_ecount_part（大小，長度）
__deref_opt_out_ecount_part_opt（大小，長度）
__deref_opt_out_opt
__deref_out
__deref_out_bcount（大小）
__deref_out_bcount_full（大小）
__deref_out_bcount_full_opt（大小）
__deref_out_bcount_opt（大小）
__deref_out_bcount_part（大小，長度）
__deref_out_bcount_part_opt（大小，長度）
__deref_out_ecount（大小）
__deref_out_ecount_full（大小）
__deref_out_ecount_full_opt（大小）
__deref_out_ecount_opt（大小）
__deref_out_ecount_part（大小，長度）
__deref_out_ecount_part_opt（大小，長度）
__deref_out_opt
__ecount（大小）
__ecount_opt（大小）
__在
__in_bcount（大小）
__in_bcount_opt（大小）
__in_ecount（大小）
__in_ecount_opt（大小）
__in_opt
__inout
__inout_bcount（大小）
__inout_bcount_full（大小）
__inout_bcount_full_opt（大小）
__inout_bcount_opt（大小）
__inout_bcount_part（大小，長度）
__inout_bcount_part_opt（大小，長度）
__inout_ecount（大小）
__inout_ecount_full（大小）
__inout_ecount_full_opt（大小）
__inout_ecount_opt（大小）
__inout_ecount_part（大小，長度）
__inout_ecount_part_opt（大小，長度）
__inout_opt
__外
__out_bcount（大小）
__out_bcount_full（大小）
__out_bcount_full_opt（大小）
__out_bcount_opt（大小）
__out_bcount_part（大小，長度）
__out_bcount_part_opt（大小，長度）
__out_ecount（大小）
__out_ecount_full（大小）
__out_ecount_full_opt（大小）
__out_ecount_opt（大小）
__out_ecount_part（大小，長度）
__out_ecount_part_opt（大小，長度）
__out_opt
進階註釋
進階註釋提供參數或傳回值的其他資訊。 每個參數或傳回值都可能會使用零或一個進階註釋。
| 註解 | 描述 |
|---|---|
|
__blocksOn（資源） |
函式會封鎖指定資源上的 。 |
|
__callback |
函式可以當做函式指標使用。 |
|
__checkReturn |
呼叫端必須檢查傳回值。 |
|
__format_string |
參數是包含 printf 樣式 % 標記的字串。 |
|
__in_awcount（expr，大小） |
如果表達式在結束時為 true，輸入緩衝區的大小會以位元組為單位指定。 如果表達式為 false，則會在元素中指定大小。 |
|
__nullnullterminated |
最多可以存取緩衝區，並包含兩個 null 字元或指標的第一個序列。 |
|
__nullterminated |
最多可以存取緩衝區，包括第一個 null 字元或指標。 |
|
__out_awcount（expr，大小） |
如果表達式在結束時為 true，輸出緩衝區的大小會以位元組為單位指定。 如果表達式為 false，則會在元素中指定大小。 |
|
__override |
指定虛擬方法的 C#樣式覆寫行為。 |
|
__reserved |
參數保留供日後使用，而且必須是零或 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
);