Windows via C/C++ 学习（3）Header annotation 头注解

参考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)	参数被视为一个特定的类型，而不是它声明的类型