Share via

標頭批註

  • 發行項

[本主題描述 Windows 標頭透過 Windows 7 支援的批註。 如果您要開發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。
初始化 描述
_全
 函式會初始化整個緩衝區。 僅搭配輸出緩衝區使用。
_部分
 函式會初始化緩衝區的一部分，並明確指出多少。 僅搭配輸出緩衝區使用。
必要或選擇性緩衝區 描述
_選擇
 此參數可以是 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 (大小)
__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
__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
__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

進階注釋

進階注釋提供有關參數或傳回值的其他資訊。 每個參數或傳回值都可以使用零或一個進階注釋。

Annotation 描述
__blocksOn (資源)
函式會封鎖指定資源上的 。
__回檔
 函式可作為函式指標。
__checkReturn
 呼叫端必須檢查傳回值。
__format_string
 參數是包含 printf 樣式 % 標記的字串。
__in_awcount (expr，size)
如果運算式在結束時為 true，則會以位元組為單位指定輸入緩衝區的大小。 如果運算式為 false，則會在元素中指定大小。
__nullnullterminated
 緩衝區最多可以存取，並包含兩個 Null 字元或指標的第一個序列。
__nullterminated
 緩衝區最多可以存取，包括第一個 Null 字元或指標。
__out_awcount (expr，size)
如果運算式在結束時為 true，輸出緩衝區的大小會以位元組為單位指定。 如果運算式為 false，則會在元素中指定大小。
__覆蓋
 指定虛擬方法的 C#樣式覆寫行為。
__保留
 參數會保留供日後使用，而且必須是零或 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++ 程式碼的缺失