参考MSDN(http://msdn.microsoft.com/en-us/library/aa383701.aspx)
Header annotation 表示一个函数怎样使用它的参数和返回值。
在编译器的命令行中增加 /analyze 开关可以进行代码分析,当你在函数中使用违反注解定义的语法规则时编译器可以进行提示。
有两种注解:缓冲区注解和高级注解
缓冲区注解
缓冲区注解表示函数怎样使用它的指针并能检测到缓冲区溢出,每个参数可有0或1个缓冲区注解。一个缓冲区注解由一个前导下划线和以下描述的组件组成。
缓冲区大小 | |
(size) | 指定缓冲区的总的大小,与_bcount 和 _ecount 一同使用;不要与_part 同时使用。这个值表示可访问的空间大小,它可能小于分配的空间。 |
(size,length) | 指定缓冲区的总的大小和初始分配空间的大小,与_bcount_part 和 _ecount_part 一同使用。这个值可能小于分配的空间。 |
缓冲区尺寸的单位 | |
_bcount | 缓冲区大小以字节计 |
_ecount | 缓冲区大小以元素计 |
方向 | |
_in | 函数从缓冲区读,调用者提供缓冲区并初始化。 |
_inout | 函数从缓冲区读写,调用者提供缓冲区并初始化。如果同 _deref 一起使用,缓冲区可能由函数重新分配空间。 |
_out | 函数向缓冲区写数据。如果用于返回值或与 _deref 一起使用,函数提供缓冲区并初始化,否则,调用者提供缓冲区由函数初始化。 |
间接 | |
_deref | 解除参数的引用以获得缓冲区指针。这个参数不能为空。 |
_deref_opt | 解除参数的引用以获得缓冲区指针。这个参数可以为空。 |
初始化 | |
_full | 函数初始化整个的缓冲区,仅用于输出缓冲区。 |
_part | 函数初始化缓冲区的一部分,并明确指出这部分的大小,仅用于输出缓冲区。 |
必须的或可选的 | |
_opt | 这个参数可以为空。 |
高级注解
高级注解提供了有关函数参数或返回值的附加信息,每一个参数或返回值可以带有0个或一个高级注解。
注解 | |
_blocksOn(resource) | 函数会阻塞特定资源的访问 |
_callback | 函数可被用于一个函数指针 |
_checkReturn | 调用者必须检查返回值 |
_format_string | 参数是一个包含“%”标记的打印风格的字符串 |
_in_awcount(expr,size) | 在退出时,如果表达式结果为真,输入缓冲区大小以字节计;否则输入缓冲区大小以元素计。 |
_nullnullterminated | 缓冲区可以访问到包括两空字符或指针的第一个序列。 |
_nullterminated | 缓冲区可以访问到并包含第一个空字符或指针 |
_out_awcount(expr,size) | 在退出时,如果表达式结果为真,输出缓冲区大小以字节计;否则输出缓冲区大小以元素计。 |
_override | 对于虚拟方法指定了C#风格的重写行为。 |
_reserved | 参数为将来保留必须为0或空 |
_success(expr) | 如果表达式是真,在退出时,调用者可以依靠其他注释指定的所有保证。否则不可依靠。此注解会自动添加到返回一个HRESULT值的函数。 |
_typefix(ctype) | 参数被视为一个特定的类型,而不是它声明的类型 |