首先贴上一些外文资料,有更多兴趣的可以参考SAL注释的相关资料,以及sal.h头文件
// The helper annotations are only understood by the compiler version used by various // defect detection tools. When the regular compiler is running, they are defined into // nothing, and do not affect the compiled code.
They are simple #defines that expand to nothing, just to help document the function parameters: whether the caller must provide valid params (_In_) for the function to work; whether the caller can optionally provide default values (_In_opt_); whether the function will fill in the params on return (_Out_), or whether parameter both passes values in and receives values out (_Inout_).
SAL,全名Microsoft source code annotation language,是微软VC++ 2010及后续版本开始推出的一种是用宏定义语言,用来注释函数的参数和返回值,由于这些宏最终都被预处理器处理掉了,所以不会对源代码有任何影响。
这种注释可以一方面让使用者更加清楚API的使用方法,另一方面VS中的C++ 代码分析器也会依靠这种宏注释来分析代码
一般来说可以将其分为_in、_out、_inout_等类型,即输入参数、输出参数、既输入又输出参数
1._In_
sal.h头文件对其有注释
// Input parameters -------------------------- // _In_ - Annotations for parameters where data is passed into the function, but not modified. // _In_ by itself can be used with non-pointer types (although it is redundant).
翻译过来就是说输入参数数据被传递到函数,但是并不修改它,这个和我们平时接触到的const形参很像,函数可以读取指针指向的内容,但是我们不会修改内容(可读)。
需要注意的是In_本身应该是和指针类型形参搭配使用,但是也可以与非指针类型一起使用(尽管它是多余的)。
2._Out_
// Output parameters --------------------------
// _Out_ - Annotations for pointer or reference parameters where data passed back to the caller.
// These are mostly used where the pointer/reference is to a non-pointer type.
// _Outptr_/_Outref) (see below) are typically used to return pointers via parameters.
_out_指针或应用参数的注释,其中数据返回给调用者,即函数会往这个指针指向的地址写入一些数据,但对其指向的内容本身并不关心(可写)
3._inout_
// Inout parameters ----------------------------
// _Inout_ - Annotations for pointer or reference parameters where data is passed in and
// potentially modified.
// void ModifyPoint( _Inout_ POINT* pPT );
// void ModifyPointByRef( _Inout_ POINT& pPT );
就是常说的可读可写。
4.除了这几个基本的宏之外,参数宏还有各种不同的功能宏定义,比如:
感兴趣的同学可以自己使用自己需要的SAL宏。