SAL： the Microsoft Source Code Annotation Language.
SAL： the Microsoft Source Code Annotation Language.
微软代码注解语言。你可以用sal.h中的宏定义来注释函数的参数和返回值来描述他们的行为。
曾经在Java中使用过注解，现在C++中也有注解了。
sal.h - markers for documenting the semantics of APIs
sal.h provides a set of annotations to describe how a function uses itsparameters
C++中提供了一系列注解，来描述函数怎样来使用他的参数。
The macros are defined in 3 layers, plus the structural set:
_In_/_Out_/_Ret_ Layer: ---------------------- This layer provides the highest abstraction and its macros should be used in most cases. These macros typically start with: _In_ : input parameter to a function, unmodified by called function _Out_ : output parameter, written to by called function, pointed-to location not expected to be initialized prior to call _Outptr_ : like _Out_ when returned variable is a pointer type (so param is pointer-to-pointer type). Called function provides/allocated space. _Outref_ : like _Outptr_, except param is reference-to-pointer type. _Inout_ : inout parameter, read from and potentially modified by called function. _Ret_ : for return values _Field_ : class/struct field invariants For common usage, this class of SAL provides the most concise annotations. Note that _In_/_Out_/_Inout_/_Outptr_ annotations are designed to be used with a parameter target. Using them with _At_ to specify non-parameter targets may yield unexpected results. This layer also includes a number of other properties that can be specified to extend the ability of code analysis, most notably: -- Designating parameters as format strings for printf/scanf/scanf_s -- Requesting stricter type checking for C enum parameters
上面: 本层提供最高的抽象并且他的宏可应用于大多数场合。他们的宏都以_In_, _Out_ , _Inout开头
_Pre_/_Post_ Layer: ------------------ The macros of this layer only should be used when there is no suitable macro in the _In_/_Out_ layer. Its macros start with _Pre_ or _Post_. This layer provides the most flexibility for annotations.
上面:当_In_\_Out层没有适当的宏时才被使用，有很强的灵活性，他们的宏都以_Pre_, _Post_, _Ret_,_Deref_pre_ _Deref_post_ , _Deref_ret_开头
_Pre_在函数调用前需要知道参数条件的时候
_Post_在函数调用后需要知道的参数条件
_Ret_ 函数调用后返回的参数条件
_Deref_pre_ 对于被间接引用的指针数组参数在函数调用前的条件
_Deref_post_ 对于被间接引用的指针数组参数在函数调用后的条件
_Deref_ret
_Pre_post在函数调用前或后的条件
_Deref_prepost
Implementation Abstraction Layer: -------------------------------- Macros from this layer should never be used directly. The layer only exists to hide the implementation of the annotation macros.
上面:本层从不被直接使用，隐藏注释宏的实现
Structural Layer: ---------------- These annotations, like _At_ and _When_, are used with annotations from any of the other layers as modifiers, indicating exactly when and where the annotations apply.
上面:结构层，明确指定什么时候，在什么地方注解应用。
Common syntactic conventions: 常见的语法约定
----------------------------
Usage:
-----
_In_, _Out_, _Inout_, _Pre_, _Post_, are for formal parameters（常规参数）.
_Ret_, _Deref_ret_ must be used for return values.
Nullness:
--------
If the parameter can be NULL as a precondition to the function, the
annotation contains _opt. If the macro does not contain '_opt' the
parameter cannot be NULL.
If an out/inout parameter returns a null pointer as a postcondition, this is
indicated by _Ret_maybenull_ or _result_maybenull_. If the macro is not
of this form, then the result will not be NULL as a postcondition.
_Outptr_ - output value is not NULL
_Outptr_result_maybenull_ - output value might be NULL
String Type:
-----------
_z: NullTerminated string
for _In_ parameters the buffer must have the specified stringtype before the call
for _Out_ parameters the buffer must have the specified stringtype after the call
for _Inout_ parameters both conditions apply
Extent Syntax:
-------------
Buffer sizes are expressed as element counts, unless the macro explicitly
contains _byte_ or _bytes_. Some annotations specify two buffer sizes, in
which case the second is used to indicate how much of the buffer is valid
as a postcondition. This table outlines the precondition buffer allocation
size, precondition number of valid elements, postcondition allocation size,
and postcondition number of valid elements for representative buffer size
For the _Outptr_ annotations, the buffer in question is at one level of
dereference. The called function is responsible for supplying the buffer.
Success and failure:
-------------------
The SAL concept of success allows functions to define expressions that can
be tested by the caller, which if it evaluates to non-zero, indicates the
function succeeded, which means that its postconditions are guaranteed to
hold. Otherwise, if the expression evaluates to zero, the function is
considered to have failed, and the postconditions are not guaranteed.
The success criteria can be specified with the _Success_(expr) annotation:
_Success_(return != FALSE) BOOL
PathCanonicalizeA(_Out_writes_(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) :
pszBuf is only guaranteed to be NULL-terminated when TRUE is returned,
and FALSE indiates failure. In common practice, callers check for zero
vs. non-zero returns, so it is preferable to express the success
criteria in terms of zero/non-zero, not checked for exactly TRUE.
Functions can specify that some postconditions will still hold, even when
the function fails, using _On_failure_(anno-list), or postconditions that
hold regardless of success or failure using _Always_(anno-list).
The annotation _Return_type_success_(expr) may be used with a typedef to
give a default _Success_ criteria to all functions returning that type.
This is the case for common Windows API status types, including
HRESULT and NTSTATUS. This may be overridden on a per-function basis by
specifying a _Success_ annotation locally.