[This topic describes the annotations supported in the Windows headers through Windows 7. If you are developing for Windows 8, you should use the annotations described in SAL Annotations.]]
Header annotations describe how a function uses its parameters and return value. These annotations have been added to many of the Windows header files to help you ensure that you are calling the Windows API correctly. If you enable code analysis, which is available starting with the Visual Studio 2005, the compiler will produce level 6000 warnings if you are not calling these functions per the usage described through the annotations. You can also add these annotations in your own code to ensure that it is being called correctly. To enable code analysis in Visual Studio, see the documentation for your version of Visual Studio.
These annotations are defined in Specstrings.h. They are built on primitives that are part of the Standard Annotation Language (SAL) and implemented using _declspec("SAL_*").
There are two classes of annotations: buffer annotations and advanced annotations.
Buffer Annotations
Buffer annotations describe how functions use their pointers and can be used to detect buffer overruns. Each parameter may use zero or one buffer annotation. A buffer annotation is constructed with a leading underscore and the components described in the following sections.
| Buffer size | Description |
|---|---|
| (size) |
Specifies the total size of the buffer. Use with _bcount and _ecount; do not use with _part. This value is the accessible space; it may be less than the allocated space. |
| (size,length) |
Specifies the total size and initialized length of the buffer. Use with _bcount_part and _ecount_part. The total size may be less than the allocated space. |
| Buffer size units | Description |
|---|---|
| _bcount |
The buffer size is in bytes. |
| _ecount |
The buffer size is in elements. |
| Direction | Description |
|---|---|
| _in |
The function reads from the buffer. The caller provides the buffer and initializes it. |
| _inout |
The function both reads from and writes to buffer. The caller provides the buffer and initializes it. If used with _deref, the buffer may be reallocated by the function. |
| _out |
The function writes to the buffer. If used on the return value or with _deref, the function provides the buffer and initializes it. Otherwise, the caller provides the buffer and the function initializes it. |
| Indirection | Description |
|---|---|
| _deref |
Dereference the parameter to obtain the buffer pointer. This parameter may not be NULL. |
| _deref_opt |
Dereference the parameter to obtain the buffer pointer. This parameter can be NULL. |
| Initialization | Description |
|---|---|
| _full |
The function initializes the entire buffer. Use only with output buffers. |
| _part |
The function initializes part of the buffer, and explicitly indicates how much. Use only with output buffers. |
| Required or optional buffer | Description |
|---|---|
| _opt |
This parameter can be NULL. |
The following example shows the annotations for the GetModuleFileName function. The hModule parameter is an optional input parameter . ThelpFilename parameter is an output parameter; its size in characters is specified by the nSize parameter and its length includes the null-terminating character. The nSize parameter is an input parameter.
DWORD
WINAPI
GetModuleFileName(
__in_opt HMODULE hModule,
__out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
__in DWORD nSize
);
The following are the annotations defined in Specstrings.h. Use the information in the tables above to interpret their meaning.
- __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
- __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
- __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
Advanced Annotations
Advanced annotations provide additional information about the parameter or return value. Each parameter or return value may use zero or one advanced annotation.
| Annotation | Description |
|---|---|
| __blocksOn(resource) |
The functions blocks on the specified resource. |
| __callback |
The function can be used as a function pointer. |
| __checkReturn |
Callers must check the return value. |
| __format_string |
The parameter is a string that contains printf-style % markers. |
| __in_awcount(expr,size) |
If the expression is true at exit, the size of the input buffer is specified in bytes. If the expression is false, the size is specified in elements. |
| __nullnullterminated |
The buffer may be accessed up to and including the first sequence of two null characters or pointers. |
| __nullterminated |
The buffer may be accessed up to and including the first null character or pointer. |
| __out_awcount(expr,size) |
If the expression is true at exit, the size of the output buffer is specified in bytes. If the expression is false, the size is specified in elements. |
| __override |
Specifies C#-style override behavior for virtual methods. |
| __reserved |
The parameter is reserved for future use and must be zero or NULL. |
| __success(expr) |
If the expression is true at exit, the caller can rely on all guarantees specified by other annotations. If the expression is false, the caller cannot rely on the guarantees. This annotation is automatically added to functions that return anHRESULT value. |
| __typefix(ctype) |
Treat the parameter as the specified type rather than its declared type. |
The following examples show the buffer and advanced annotations for the DeleteTimerQueueTimer, FreeEnvironmentStrings, andUnhandledExceptionFilter functions.
C++
__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 特性，为 SAL 语法参考，并给出其使用的示例。具体的使用方法点开链接直接看。
-
了解 SAL
提供演示核心 SAL 注释的信息和示例。
-
对函数参数和返回值进行批注
列出和函数参数的 SAL 注释。
-
对函数行为进行批注
列出函数和函数操作的 SAL 注释。
-
批注结构和类
列出结构和类的 SAL 注释。
-
对锁定行为进行批注
介绍如何使用锁机制的 SAL 注释。
-
指定何时以及在何处应用批注
列出指定条件或其他 SAL 注释范围（放置）的 SAL 注释。
-
内部函数
列出内部 SAL 注释。
-
最佳做法和示例 (SAL)
提供演示如何使用 SAL 注释的示例。 同时解释常见缺陷。
Team Blog 代码分析
原文链接：
Header Annotation
使用 SAL 批注以减少 C/C++ 代码缺陷