sal.h provides a set of annotations to describe how a function uses its parameters, for example, the assumptions it makes about them and the guarantees it makes on finishing. The header file <sal.h> defines the annotations.
You can put an annotation before either the type of a function parameter or its return type, and use the annotation to describe the behavior of the function regarding the parameter or the return value. There are two classes of annotations: buffer annotations and advanced annotations. A buffer annotation describes how a function uses its pointer parameter, and an advanced annotation either describes complex or unusual buffer behavior, or provides additional information about a parameter that is not otherwise expressible.
你可以用sal.h中的宏定义来注释函数的参数和返回值来描述他们的行为。
两种注释宏:缓冲注释和高级注释(buffer annotations and advanced annotations)
buffer annotations ：描述函数如何使用他的指针参数
advanced annotations：描述复杂的或非常规的缓冲行为，或提供额外的参数信息
The macros are defined in 3 layers:
1.
_In_\_Out_ Layer: 本层提供最高的抽象并且他的宏可应用于大多数场合。他们的宏都以_In_, _Out_ , _Inout开头
------------------------------------------------------------------
This layer provides the highest abstraction and its macros should be used
in most cases. Its macros start with _In_, _Out_ or _Inout_. For the
typical case they provide the most concise annotations.
2.
_Pre_\_Post_ Layer: 当_In_\_Out层没有适当的宏时才被使用，有很强的灵活性，他们的宏都以_Pre_, _Post_, _Ret_,_Deref_pre_ _Deref_post_ , _Deref_ret_开头
_Pre_在函数调用前需要知道参数条件的时候
_Post_在函数调用后需要知道的参数条件
_Ret_ 函数调用后返回的参数条件
_Deref_pre_ 对于被间接引用的指针数组参数在函数调用前的条件
_Deref_post_ 对于被间接引用的指针数组参数在函数调用后的条件
_Deref_ret
_Pre_post在函数调用前或后的条件
_Deref_prepost
------------------------------------------------------------------
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_, _Post_, _Ret_, _Deref_pre_ _Deref_post_ and _Deref_ret_. This layer provides the most
flexibility for annotations.
3.
Implementation Abstraction Layer:本层从不被直接使用，隐藏注释宏的实现
------------------------------------------------------------------
Macros from this layer should never be used directly. The layer only exists
to hide the implementation of the annotation macros.
Usage:
-----
_In_, _Out_, _Inout_, _Pre_, _Post_, _Deref_pre_, _Deref_post_ are for formal parameters.对参数使用
_Ret_, _Deref_ret_ must be used for return values.对返回值使用
Nullness:
--------
If the pointer can be NULL the annotation contains _opt. If the macro does not contain '_opt' the pointer may not be NULL.
如果指针可以为NULL，则注释宏包含_opt
String Type:
-----------
_z: NullTerminated string NULL结尾的字符串
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
'cap' (capacity) describes the writable size of the buffer and is typically used with _Out_. cap表述缓冲区可写的大小，一般用_Out
The default unit is elements. Use 'bytecap' if the size is given in bytes. 如果大小是以字节为单位，则用bytecap
'count' describes the readable size of the buffer and is typically used with _In_. count描述缓冲区的可读大小，一般用_In_.
The default unit is elements. Use 'bytecount' if the size is given in bytes. 以字节为单位， 'bytecount'
Argument syntax for cap_, bytecap_, count_, bytecount_:
(<parameter>|return)[+n] e.g. cch, return, cb+2
If the buffer size is a constant expression use the c_ postfix. 若缓冲区大小是常量表达式，则加c_后缀
E.g. cap_c_(20), count_c_(MAX_PATH), bytecount_c_(16)
If the buffer size is given by a limiting pointer use the ptrdiff_ versions of the macros. 指针有限制则加ptrdiff_
If the buffer size is neither a parameter nor a constant expression use the x_ postfix.
e.g. bytecount_x_(num*size) x_ annotations accept any arbitrary string.
No analysis can be done for x_ annotations but they at least tell the tool that the buffer has some sort of extent description. x_ annotations might be supported
by future compiler versions.
//============================================================================ // _In_\_Out_ Layer: //============================================================================ // 'in' parameters -------------------------- // input pointer parameter // e.g. void SetPoint( _In_ const POINT* pPT ); #define _In_ _Pre1_impl_(_$notnull) _Deref_pre2_impl_(_$valid, _$readaccess) #define _In_opt_ _Pre_opt_valid_ _Deref_pre_readonly_ // nullterminated 'in' parameters. // e.g. void CopyStr( _In_z_ const char* szFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo ); #define _In_z_ _Pre_z_ _Deref_pre_readonly_ #define _In_opt_z_ _Pre_opt_z_ _Deref_pre_readonly_ // 'input' buffers with given size // e.g. void SetCharRange( _In_count_(cch) const char* rgch, size_t cch ) // valid buffer extent described by another parameter #define _In_count_(size) _Pre_count_(size) _Deref_pre_readonly_ #define _In_opt_count_(size) _Pre_opt_count_(size) _Deref_pre_readonly_ #define _In_bytecount_(size) _Pre_bytecount_(size) _Deref_pre_readonly_ #define _In_opt_bytecount_(size) _Pre_opt_bytecount_(size) _Deref_pre_readonly_ // valid buffer extent described by a constant extression #define _In_count_c_(size) _Pre_count_c_(size) _Deref_pre_readonly_ #define _In_opt_count_c_(size) _Pre_opt_count_c_(size) _Deref_pre_readonly_ #define _In_bytecount_c_(size) _Pre_bytecount_c_(size) _Deref_pre_readonly_ #define _In_opt_bytecount_c_(size) _Pre_opt_bytecount_c_(size) _Deref_pre_readonly_ // nullterminated 'input' buffers with given size // e.g. void SetCharRange( _In_count_(cch) const char* rgch, size_t cch ) // nullterminated valid buffer extent described by another parameter #define _In_z_count_(size) _Pre_z_ _Pre_count_(size) _Deref_pre_readonly_ #define _In_opt_z_count_(size) _Pre_opt_z_ _Pre_opt_count_(size) _Deref_pre_readonly_ #define _In_z_bytecount_(size) _Pre_z_ _Pre_bytecount_(size) _Deref_pre_readonly_ #define _In_opt_z_bytecount_(size) _Pre_opt_z_ _Pre_opt_bytecount_(size) _Deref_pre_readonly_ // nullterminated valid buffer extent described by a constant extression #define _In_z_count_c_(size) _Pre_z_ _Pre_count_c_(size) _Deref_pre_readonly_ #define _In_opt_z_count_c_(size) _Pre_opt_z_ _Pre_opt_count_c_(size) _Deref_pre_readonly_ #define _In_z_bytecount_c_(size) _Pre_z_ _Pre_bytecount_c_(size) _Deref_pre_readonly_ #define _In_opt_z_bytecount_c_(size) _Pre_opt_z_ _Pre_opt_bytecount_c_(size) _Deref_pre_readonly_ // buffer capacity is described by another pointer // e.g. void Foo( _In_ptrdiff_count_(pchMax) const char* pch, const char* pchMax ) { while pch < pchMax ) pch++; } #define _In_ptrdiff_count_(size) _Pre_ptrdiff_count_(size) _Deref_pre_readonly_ #define _In_opt_ptrdiff_count_(size) _Pre_opt_ptrdiff_count_(size) _Deref_pre_readonly_ // 'x' version for complex expressions that are not supported by the current compiler version // e.g. void Set3ColMatrix( _In_count_x_(3*cRows) const Elem* matrix, int cRows ); #define _In_count_x_(size) _Pre_count_x_(size) _Deref_pre_readonly_ #define _In_opt_count_x_(size) _Pre_opt_count_x_(size) _Deref_pre_readonly_ #define _In_bytecount_x_(size) _Pre_bytecount_x_(size) _Deref_pre_readonly_ #define _In_opt_bytecount_x_(size) _Pre_opt_bytecount_x_(size) _Deref_pre_readonly_ // 'out' parameters -------------------------- // output pointer parameter // e.g. void GetPoint( _Out_ POINT* pPT ); #define _Out_ _Pre_cap_c_(1) _Pre_invalid_ #define _Out_opt_ _Pre_opt_cap_c_(1) _Pre_invalid_ // 'out' with buffer size // e.g. void GetIndeces( _Out_cap_(cIndeces) int* rgIndeces, size_t cIndices ); // buffer capacity is described by another parameter #define _Out_cap_(size) _Pre_cap_(size) _Pre_invalid_ #define _Out_opt_cap_(size) _Pre_opt_cap_(size) _Pre_invalid_ #define _Out_bytecap_(size) _Pre_bytecap_(size) _Pre_invalid_ #define _Out_opt_bytecap_(size) _Pre_opt_bytecap_(size) _Pre_invalid_ // buffer capacity is described by a constant expression #define _Out_cap_c_(size) _Pre_cap_c_(size) _Pre_invalid_ #define _Out_opt_cap_c_(size) _Pre_opt_cap_c_(size) _Pre_invalid_ #define _Out_bytecap_c_(size) _Pre_bytecap_c_(size) _Pre_invalid_ #define _Out_opt_bytecap_c_(size) _Pre_opt_bytecap_c_(size) _Pre_invalid_ // buffer capacity is described by another parameter multiplied by a constant expression #define _Out_cap_m_(mult,size) _Pre_cap_m_(mult,size) _Pre_invalid_ #define _Out_opt_cap_m_(mult,size) _Pre_opt_cap_m_(mult,size) _Pre_invalid_ #define _Out_z_cap_m_(mult,size) _Pre_cap_m_(mult,size) _Pre_invalid_ _Post_z_ #define _Out_opt_z_cap_m_(mult,size) _Pre_opt_cap_m_(mult,size) _Pre_invalid_ _Post_z_ // buffer capacity is described by another pointer // e.g. void Foo( _Out_ptrdiff_cap_(pchMax) char* pch, const char* pchMax ) { while pch < pchMax ) pch++; } #define _Out_ptrdiff_cap_(size) _Pre_ptrdiff_cap_(size) _Pre_invalid_ #define _Out_opt_ptrdiff_cap_(size) _Pre_opt_ptrdiff_cap_(size) _Pre_invalid_ // buffer capacity is described by a complex expression #define _Out_cap_x_(size) _Pre_cap_x_(size) _Pre_invalid_ #define _Out_opt_cap_x_(size) _Pre_opt_cap_x_(size) _Pre_invalid_ #define _Out_bytecap_x_(size) _Pre_bytecap_x_(size) _Pre_invalid_ #define _Out_opt_bytecap_x_(size) _Pre_opt_bytecap_x_(size) _Pre_invalid_ // a zero terminated string is filled into a buffer of given capacity // e.g. void CopyStr( _In_z_ const char* szFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo ); // buffer capacity is described by another parameter #define _Out_z_cap_(size) _Pre_cap_(size) _Pre_invalid_ _Post_z_ #define _Out_opt_z_cap_(size) _Pre_opt_cap_(size) _Pre_invalid_ _Post_z_ #define _Out_z_bytecap_(size) _Pre_bytecap_(size) _Pre_invalid_ _Post_z_ #define _Out_opt_z_bytecap_(size) _Pre_opt_bytecap_(size) _Pre_invalid_ _Post_z_ // buffer capacity is described by a constant expression #define _Out_z_cap_c_(size) _Pre_cap_c_(size) _Pre_invalid_ _Post_z_ #define _Out_opt_z_cap_c_(size) _Pre_opt_cap_c_(size) _Pre_invalid_ _Post_z_ #define _Out_z_bytecap_c_(size) _Pre_bytecap_c_(size) _Pre_invalid_ _Post_z_ #define _Out_opt_z_bytecap_c_(size) _Pre_opt_bytecap_c_(size) _Pre_invalid_ _Post_z_ // buffer capacity is described by a complex expression #define _Out_z_cap_x_(size) _Pre_cap_x_(size) _Pre_invalid_ _Post_z_ #define _Out_opt_z_cap_x_(size) _Pre_opt_cap_x_(size) _Pre_invalid_ _Post_z_ #define _Out_z_bytecap_x_(size) _Pre_bytecap_x_(size) _Pre_invalid_ _Post_z_ #define _Out_opt_z_bytecap_x_(size) _Pre_opt_bytecap_x_(size) _Pre_invalid_ _Post_z_ // a zero terminated string is filled into a buffer of given capacity // e.g. size_t CopyCharRange( _In_count_(cchFrom) const char* rgchFrom, size_t cchFrom, _Out_cap_post_count_(cchTo,return)) char* rgchTo, size_t cchTo ); #define _Out_cap_post_count_(cap,count) _Pre_cap_(cap) _Pre_invalid_ _Post_count_(count) #define _Out_opt_cap_post_count_(cap,count) _Pre_opt_cap_(cap) _Pre_invalid_ _Post_count_(count) #define _Out_bytecap_post_bytecount_(cap,count) _Pre_bytecap_(cap) _Pre_invalid_ _Post_bytecount_(count) #define _Out_opt_bytecap_post_bytecount_(cap,count) _Pre_opt_bytecap_(cap) _Pre_invalid_ _Post_bytecount_(count) // a zero terminated string is filled into a buffer of given capacity // e.g. size_t CopyStr( _In_z_ const char* szFrom, _Out_z_cap_post_count_(cchTo,return+1) char* szTo, size_t cchTo ); #define _Out_z_cap_post_count_(cap,count) _Pre_cap_(cap) _Pre_invalid_ _Post_z_count_(count) #define _Out_opt_z_cap_post_count_(cap,count) _Pre_opt_cap_(cap) _Pre_invalid_ _Post_z_count_(count) #define _Out_z_bytecap_post_bytecount_(cap,count) _Pre_bytecap_(cap) _Pre_invalid_ _Post_z_bytecount_(count) #define _Out_opt_z_bytecap_post_bytecount_(cap,count) _Pre_opt_bytecap_(cap) _Pre_invalid_ _Post_z_bytecount_(count) // only use with dereferenced arguments e.g. '*pcch' #define _Out_capcount_(capcount) _Pre_cap_(capcount) _Pre_invalid_ _Post_count_(capcount) #define _Out_opt_capcount_(capcount) _Pre_opt_cap_(capcount) _Pre_invalid_ _Post_count_(capcount) #define _Out_bytecapcount_(capcount) _Pre_bytecap_(capcount) _Pre_invalid_ _Post_bytecount_(capcount) #define _Out_opt_bytecapcount_(capcount) _Pre_opt_bytecap_(capcount) _Pre_invalid_ _Post_bytecount_(capcount) #define _Out_capcount_x_(capcount) _Pre_cap_x_(capcount) _Pre_invalid_ _Post_count_x_(capcount) #define _Out_opt_capcount_x_(capcount) _Pre_opt_cap_x_(capcount) _Pre_invalid_ _Post_count_x_(capcount) #define _Out_bytecapcount_x_(capcount) _Pre_bytecap_x_(capcount) _Pre_invalid_ _Post_bytecount_x_(capcount) #define _Out_opt_bytecapcount_x_(capcount) _Pre_opt_bytecap_x_(capcount) _Pre_invalid_ _Post_bytecount_x_(capcount) // e.g. GetString( _Out_z_capcount_(*pLen+1) char* sz, size_t* pLen ); #define _Out_z_capcount_(capcount) _Pre_cap_(capcount) _Pre_invalid_ _Post_z_count_(capcount) #define _Out_opt_z_capcount_(capcount) _Pre_opt_cap_(capcount) _Pre_invalid_ _Post_z_count_(capcount) #define _Out_z_bytecapcount_(capcount) _Pre_bytecap_(capcount) _Pre_invalid_ _Post_z_bytecount_(capcount) #define _Out_opt_z_bytecapcount_(capcount) _Pre_opt_bytecap_(capcount) _Pre_invalid_ _Post_z_bytecount_(capcount) // inout parameters ---------------------------- // inout pointer parameter // e.g. void ModifyPoint( _Inout_ POINT* pPT ); #define _Inout_ _Prepost_valid_ #define _Inout_opt_ _Prepost_opt_valid_ // string buffers // e.g. void toupper( _Inout_z_ char* sz ); #define _Inout_z_ _Prepost_z_ #define _Inout_opt_z_ _Prepost_opt_z_ // 'inout' buffers with initialized elements before and after the call // e.g. void ModifyIndices( _Inout_count_(cIndices) int* rgIndeces, size_t cIndices ); #define _Inout_count_(size) _Prepost_count_(size) #define _Inout_opt_count_(size) _Prepost_opt_count_(size) #define _Inout_bytecount_(size) _Prepost_bytecount_(size) #define _Inout_opt_bytecount_(size) _Prepost_opt_bytecount_(size) #define _Inout_count_c_(size) _Prepost_count_c_(size) #define _Inout_opt_count_c_(size) _Prepost_opt_count_c_(size) #define _Inout_bytecount_c_(size) _Prepost_bytecount_c_(size) #define _Inout_opt_bytecount_c_(size) _Prepost_opt_bytecount_c_(size) // nullterminated 'inout' buffers with initialized elements before and after the call // e.g. void ModifyIndices( _Inout_count_(cIndices) int* rgIndeces, size_t cIndices ); #define _Inout_z_count_(size) _Prepost_z_ _Prepost_count_(size) #define _Inout_opt_z_count_(size) _Prepost_z_ _Prepost_opt_count_(size) #define _Inout_z_bytecount_(size) _Prepost_z_ _Prepost_bytecount_(size) #define _Inout_opt_z_bytecount_(size) _Prepost_z_ _Prepost_opt_bytecount_(size) #define _Inout_z_count_c_(size) _Prepost_z_ _Prepost_count_c_(size) #define _Inout_opt_z_count_c_(size) _Prepost_z_ _Prepost_opt_count_c_(size) #define _Inout_z_bytecount_c_(size) _Prepost_z_ _Prepost_bytecount_c_(size) #define _Inout_opt_z_bytecount_c_(size) _Prepost_z_ _Prepost_opt_bytecount_c_(size) #define _Inout_ptrdiff_count_(size) _Pre_ptrdiff_count_(size) #define _Inout_opt_ptrdiff_count_(size) _Pre_opt_ptrdiff_count_(size) #define _Inout_count_x_(size) _Prepost_count_x_(size) #define _Inout_opt_count_x_(size) _Prepost_opt_count_x_(size) #define _Inout_bytecount_x_(size) _Prepost_bytecount_x_(size) #define _Inout_opt_bytecount_x_(size) _Prepost_opt_bytecount_x_(size) // e.g. void AppendToLPSTR( _In_ LPCSTR szFrom, _Inout_cap_(cchTo) LPSTR* szTo, size_t cchTo ); #define _Inout_cap_(size) _Pre_valid_cap_(size) _Post_valid_ #define _Inout_opt_cap_(size) _Pre_opt_valid_cap_(size) _Post_valid_ #define _Inout_bytecap_(size) _Pre_valid_bytecap_(size) _Post_valid_ #define _Inout_opt_bytecap_(size) _Pre_opt_valid_bytecap_(size) _Post_valid_ #define _Inout_cap_c_(size) _Pre_valid_cap_c_(size) _Post_valid_ #define _Inout_opt_cap_c_(size) _Pre_opt_valid_cap_c_(size) _Post_valid_ #define _Inout_bytecap_c_(size) _Pre_valid_bytecap_c_(size) _Post_valid_ #define _Inout_opt_bytecap_c_(size) _Pre_opt_valid_bytecap_c_(size) _Post_valid_ #define _Inout_cap_x_(size) _Pre_valid_cap_x_(size) _Post_valid_ #define _Inout_opt_cap_x_(size) _Pre_opt_valid_cap_x_(size) _Post_valid_ #define _Inout_bytecap_x_(size) _Pre_valid_bytecap_x_(size) _Post_valid_ #define _Inout_opt_bytecap_x_(size) _Pre_opt_valid_bytecap_x_(size) _Post_valid_ // inout string buffers with writable size // e.g. void AppendStr( _In_z_ const char* szFrom, _Inout_z_cap_(cchTo) char* szTo, size_t cchTo ); #define _Inout_z_cap_(size) _Pre_z_cap_(size) _Post_z_ #define _Inout_opt_z_cap_(size) _Pre_opt_z_cap_(size) _Post_z_ #define _Inout_z_bytecap_(size) _Pre_z_bytecap_(size) _Post_z_ #define _Inout_opt_z_bytecap_(size) _Pre_opt_z_bytecap_(size) _Post_z_ #define _Inout_z_cap_c_(size) _Pre_z_cap_c_(size) _Post_z_ #define _Inout_opt_z_cap_c_(size) _Pre_opt_z_cap_c_(size) _Post_z_ #define _Inout_z_bytecap_c_(size) _Pre_z_bytecap_c_(size) _Post_z_ #define _Inout_opt_z_bytecap_c_(size) _Pre_opt_z_bytecap_c_(size) _Post_z_ #define _Inout_z_cap_x_(size) _Pre_z_cap_x_(size) _Post_z_ #define _Inout_opt_z_cap_x_(size) _Pre_opt_z_cap_x_(size) _Post_z_ #define _Inout_z_bytecap_x_(size) _Pre_z_bytecap_x_(size) _Post_z_ #define _Inout_opt_z_bytecap_x_(size) _Pre_opt_z_bytecap_x_(size) _Post_z_ // return values ------------------------------- // returning pointers to valid objects #define _Ret_ _Ret_valid_ #define _Ret_opt_ _Ret_opt_valid_ // More _Ret_ annotations are defined below // Pointer to pointers ------------------------- // e.g. HRESULT HrCreatePoint( _Deref_out_opt_ POINT** ppPT ); #define _Deref_out_ _Out_ _Deref_pre_invalid_ _Deref_post_valid_ #define _Deref_out_opt_ _Out_ _Deref_pre_invalid_ _Deref_post_opt_valid_ #define _Deref_opt_out_ _Out_opt_ _Deref_pre_invalid_ _Deref_post_valid_ #define _Deref_opt_out_opt_ _Out_opt_ _Deref_pre_invalid_ _Deref_post_opt_valid_ // e.g. void CloneString( _In_z_ const wchar_t* wzFrom, _Deref_out_z_ wchar_t** pWzTo ); #define _Deref_out_z_ _Out_ _Deref_pre_invalid_ _Deref_post_z_ #define _Deref_out_opt_z_ _Out_ _Deref_pre_invalid_ _Deref_post_opt_z_ #define _Deref_opt_out_z_ _Out_opt_ _Deref_pre_invalid_ _Deref_post_z_ #define _Deref_opt_out_opt_z_ _Out_opt_ _Deref_pre_invalid_ _Deref_post_opt_z_ // More _Deref_ annotations are defined below // Other annotations // Check the return value of a function e.g. _Check_return_ ErrorCode Foo(); #define _Check_return_ _Check_return_impl_ // e.g. MyPrintF( _Printf_format_string_ const wchar_t* wzFormat, ... ); #define _Printf_format_string_ _Printf_format_string_impl_ #define _Scanf_format_string_ _Scanf_format_string_impl_ #define _Scanf_s_format_string_ _Scanf_s_format_string_impl_ // <expr> indicates whether post conditions apply #define _Success_(expr) _Success_impl_(expr) // annotations to express 'boundedness' of integral value parameter #define _In_bound_ _In_bound_impl_ #define _Out_bound_ _Out_bound_impl_ #define _Ret_bound_ _Ret_bound_impl_ #define _Deref_in_bound_ _Deref_in_bound_impl_ #define _Deref_out_bound_ _Deref_out_bound_impl_ #define _Deref_inout_bound_ _Deref_in_bound_ _Deref_out_bound_ #define _Deref_ret_bound_ _Deref_ret_bound_impl_ // annotations to express upper and lower bounds of integral value parameter #define _In_range_(lb,ub) _In_range_impl_(lb,ub) #define _Out_range_(lb,ub) _Out_range_impl_(lb,ub) #define _Ret_range_(lb,ub) _Ret_range_impl_(lb,ub) #define _Deref_in_range_(lb,ub) _Deref_in_range_impl_(lb,ub) #define _Deref_out_range_(lb,ub) _Deref_out_range_impl_(lb,ub) #define _Deref_ret_range_(lb,ub) _Deref_ret_range_impl_(lb,ub) //============================================================================ // _Pre_\_Post_ Layer: //============================================================================ // // _Pre_ annotation --- // // describing conditions that must be met before the call of the function // e.g. int strlen( _Pre_z_ const char* sz ); // buffer is a zero terminated string #define _Pre_z_ _Pre2_impl_(_$notnull, _$zterm) _Deref_pre1_impl_(_$valid) #define _Pre_opt_z_ _Pre2_impl_(_$maybenull,_$zterm) _Deref_pre1_impl_(_$valid) // e.g. void FreeMemory( _Pre_bytecap_(cb) _Post_invalid_ void* pv, size_t cb ); // buffer capacity described by another parameter #define _Pre_cap_(size) _Pre2_impl_(_$notnull, _$cap(size)) #define _Pre_opt_cap_(size) _Pre2_impl_(_$maybenull,_$cap(size)) #define _Pre_bytecap_(size) _Pre2_impl_(_$notnull, _$bytecap(size)) #define _Pre_opt_bytecap_(size) _Pre2_impl_(_$maybenull,_$bytecap(size)) // buffer capacity described by a constant expression #define _Pre_cap_c_(size) _Pre2_impl_(_$notnull, _$cap_c(size)) #define _Pre_opt_cap_c_(size) _Pre2_impl_(_$maybenull,_$cap_c(size)) #define _Pre_bytecap_c_(size) _Pre2_impl_(_$notnull, _$bytecap_c(size)) #define _Pre_opt_bytecap_c_(size) _Pre2_impl_(_$maybenull,_$bytecap_c(size)) // buffer capacity is described by another parameter multiplied by a constant expression #define _Pre_cap_m_(mult,size) _Pre2_impl_(_$notnull, _$mult(mult,size)) #define _Pre_opt_cap_m_(mult,size) _Pre2_impl_(_$maybenull,_$mult(mult,size)) // buffer capacity described by size of other buffer, only used by dangerous legacy APIs // e.g. int strcpy(_Pre_cap_for_(src) char* dst, const char* src); #define _Pre_cap_for_(param) _Pre2_impl_(_$notnull, _$cap_for(param)) #define _Pre_opt_cap_for_(param) _Pre2_impl_(_$maybenull,_$cap_for(param)) // buffer capacity described by a complex condition #define _Pre_cap_x_(size) _Pre2_impl_(_$notnull, _$cap_x(size)) #define _Pre_opt_cap_x_(size) _Pre2_impl_(_$maybenull,_$cap_x(size)) #define _Pre_bytecap_x_(size) _Pre2_impl_(_$notnull, _$bytecap_x(size)) #define _Pre_opt_bytecap_x_(size) _Pre2_impl_(_$maybenull,_$bytecap_x(size)) // buffer capacity described by the difference to another pointer parameter #define _Pre_ptrdiff_cap_(ptr) _Pre2_impl_(_$notnull, _$cap_x(__ptrdiff(ptr))) #define _Pre_opt_ptrdiff_cap_(ptr) _Pre2_impl_(_$maybenull,_$cap_x(__ptrdiff(ptr))) // e.g. void AppendStr( _Pre_z_ const char* szFrom, _Pre_z_cap_(cchTo) _Post_z_ char* szTo, size_t cchTo ); #define _Pre_z_cap_(size) _Pre3_impl_(_$notnull, _$zterm,_$cap(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_z_cap_(size) _Pre3_impl_(_$maybenull,_$zterm,_$cap(size)) _Deref_pre1_impl_(_$valid) #define _Pre_z_bytecap_(size) _Pre3_impl_(_$notnull, _$zterm,_$bytecap(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_z_bytecap_(size) _Pre3_impl_(_$maybenull,_$zterm,_$bytecap(size)) _Deref_pre1_impl_(_$valid) #define _Pre_z_cap_c_(size) _Pre3_impl_(_$notnull, _$zterm,_$cap_c(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_z_cap_c_(size) _Pre3_impl_(_$maybenull,_$zterm,_$cap_c(size)) _Deref_pre1_impl_(_$valid) #define _Pre_z_bytecap_c_(size) _Pre3_impl_(_$notnull, _$zterm,_$bytecap_c(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_z_bytecap_c_(size) _Pre3_impl_(_$maybenull,_$zterm,_$bytecap_c(size)) _Deref_pre1_impl_(_$valid) #define _Pre_z_cap_x_(size) _Pre3_impl_(_$notnull, _$zterm,_$cap_x(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_z_cap_x_(size) _Pre3_impl_(_$maybenull,_$zterm,_$cap_x(size)) _Deref_pre1_impl_(_$valid) #define _Pre_z_bytecap_x_(size) _Pre3_impl_(_$notnull, _$zterm,_$bytecap_x(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_z_bytecap_x_(size) _Pre3_impl_(_$maybenull,_$zterm,_$bytecap_x(size)) _Deref_pre1_impl_(_$valid) // known capacity and valid but unknown readable extent #define _Pre_valid_cap_(size) _Pre2_impl_(_$notnull, _$cap(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_valid_cap_(size) _Pre2_impl_(_$maybenull,_$cap(size)) _Deref_pre1_impl_(_$valid) #define _Pre_valid_bytecap_(size) _Pre2_impl_(_$notnull, _$bytecap(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_valid_bytecap_(size) _Pre2_impl_(_$maybenull,_$bytecap(size)) _Deref_pre1_impl_(_$valid) #define _Pre_valid_cap_c_(size) _Pre2_impl_(_$notnull, _$cap_c(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_valid_cap_c_(size) _Pre2_impl_(_$maybenull,_$cap_c(size)) _Deref_pre1_impl_(_$valid) #define _Pre_valid_bytecap_c_(size) _Pre2_impl_(_$notnull, _$bytecap_c(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_valid_bytecap_c_(size) _Pre2_impl_(_$maybenull,_$bytecap_c(size)) _Deref_pre1_impl_(_$valid) #define _Pre_valid_cap_x_(size) _Pre2_impl_(_$notnull, _$cap_x(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_valid_cap_x_(size) _Pre2_impl_(_$maybenull,_$cap_x(size)) _Deref_pre1_impl_(_$valid) #define _Pre_valid_bytecap_x_(size) _Pre2_impl_(_$notnull, _$bytecap_x(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_valid_bytecap_x_(size) _Pre2_impl_(_$maybenull,_$bytecap_x(size)) _Deref_pre1_impl_(_$valid) // e.g. void AppendCharRange( _Pre_count_(cchFrom) const char* rgFrom, size_t cchFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo ); // Valid buffer extent described by another parameter #define _Pre_count_(size) _Pre2_impl_(_$notnull, _$count(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_count_(size) _Pre2_impl_(_$maybenull,_$count(size)) _Deref_pre1_impl_(_$valid) #define _Pre_bytecount_(size) _Pre2_impl_(_$notnull, _$bytecount(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_bytecount_(size) _Pre2_impl_(_$maybenull,_$bytecount(size)) _Deref_pre1_impl_(_$valid) // Valid buffer extent described by a constant expression #define _Pre_count_c_(size) _Pre2_impl_(_$notnull, _$count_c(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_count_c_(size) _Pre2_impl_(_$maybenull,_$count_c(size)) _Deref_pre1_impl_(_$valid) #define _Pre_bytecount_c_(size) _Pre2_impl_(_$notnull, _$bytecount_c(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_bytecount_c_(size) _Pre2_impl_(_$maybenull,_$bytecount_c(size)) _Deref_pre1_impl_(_$valid) // Valid buffer extent described by a complex expression #define _Pre_count_x_(size) _Pre2_impl_(_$notnull, _$count_x(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_count_x_(size) _Pre2_impl_(_$maybenull,_$count_x(size)) _Deref_pre1_impl_(_$valid) #define _Pre_bytecount_x_(size) _Pre2_impl_(_$notnull, _$bytecount_x(size)) _Deref_pre1_impl_(_$valid) #define _Pre_opt_bytecount_x_(size) _Pre2_impl_(_$maybenull,_$bytecount_x(size)) _Deref_pre1_impl_(_$valid) // Valid buffer extent described by the difference to another pointer parameter #define _Pre_ptrdiff_count_(ptr) _Pre2_impl_(_$notnull, _$count_x(__ptrdiff(ptr))) _Deref_pre1_impl_(_$valid) #define _Pre_opt_ptrdiff_count_(ptr) _Pre2_impl_(_$maybenull,_$count_x(__ptrdiff(ptr))) _Deref_pre1_impl_(_$valid) // valid size unknown or indicated by type (e.g.:LPSTR) #define _Pre_valid_ _Pre1_impl_(_$notnull) _Deref_pre1_impl_(_$valid) #define _Pre_opt_valid_ _Pre1_impl_(_$maybenull) _Deref_pre1_impl_(_$valid) #define _Pre_invalid_ _Deref_pre1_impl_(_$notvalid) // used with allocated but not yet initialized objects #define _Pre_notnull_ _Pre1_impl_(_$notnull) #define _Pre_maybenull_ _Pre1_impl_(_$maybenull) #define _Pre_null_ _Pre1_impl_(_$null) // restrict access rights #define _Pre_readonly_ _Pre1_impl_(_$readaccess) #define _Pre_writeonly_ _Pre1_impl_(_$writeaccess) // // _Post_ annotations --- // // describing conditions that hold after the function call // void CopyStr( _In_z_ const char* szFrom, _Pre_cap_(cch) _Post_z_ char* szFrom, size_t cchFrom ); // buffer will be a zero-terminated string after the call #define _Post_z_ _Post1_impl_(_$zterm) _Deref_post1_impl_(_$valid) // char * strncpy(_Out_cap_(_Count) _Post_maybez_ char * _Dest, _In_z_ const char * _Source, _In_ size_t _Count) // buffer maybe zero-terminated after the call #define _Post_maybez_ _Post1_impl_(_$maybezterm) // e.g. SIZE_T HeapSize( _In_ HANDLE hHeap, DWORD dwFlags, _Pre_notnull_ _Post_bytecap_(return) LPCVOID lpMem ); #define _Post_cap_(size) _Post1_impl_(_$cap(size)) #define _Post_bytecap_(size) _Post1_impl_(_$bytecap(size)) // e.g. int strlen( _In_z_ _Post_count_(return+1) const char* sz ); #define _Post_count_(size) _Post1_impl_(_$count(size)) _Deref_post1_impl_(_$valid) #define _Post_bytecount_(size) _Post1_impl_(_$bytecount(size)) _Deref_post1_impl_(_$valid) #define _Post_count_c_(size) _Post1_impl_(_$count_c(size)) _Deref_post1_impl_(_$valid) #define _Post_bytecount_c_(size) _Post1_impl_(_$bytecount_c(size)) _Deref_post1_impl_(_$valid) #define _Post_count_x_(size) _Post1_impl_(_$count_x(size)) _Deref_post1_impl_(_$valid) #define _Post_bytecount_x_(size) _Post1_impl_(_$bytecount_x(size)) _Deref_post1_impl_(_$valid) // e.g. size_t CopyStr( _In_z_ const char* szFrom, _Pre_cap_(cch) _Post_z_count_(return+1) char* szFrom, size_t cchFrom ); #define _Post_z_count_(size) _Post2_impl_(_$zterm,_$count(size)) _Deref_post1_impl_(_$valid) #define _Post_z_bytecount_(size) _Post2_impl_(_$zterm,_$bytecount(size)) _Deref_post1_impl_(_$valid) #define _Post_z_count_c_(size) _Post2_impl_(_$zterm,_$count_c(size)) _Deref_post1_impl_(_$valid) #define _Post_z_bytecount_c_(size) _Post2_impl_(_$zterm,_$bytecount_c(size)) _Deref_post1_impl_(_$valid) #define _Post_z_count_x_(size) _Post2_impl_(_$zterm,_$count_x(size)) _Deref_post1_impl_(_$valid) #define _Post_z_bytecount_x_(size) _Post2_impl_(_$zterm,_$bytecount_x(size)) _Deref_post1_impl_(_$valid) // e.g. void free( _Post_invalid_ void* pv ); #define _Post_valid_ _Deref_post1_impl_(_$valid) #define _Post_invalid_ _Deref_post1_impl_(_$notvalid) // e.g. void ThrowExceptionIfNull( _Post_notnull_ const void* pv ); #define _Post_notnull_ _Post1_impl_(_$notnull) // // _Ret_ annotations // // describing conditions that hold for return values after the call // e.g. _Ret_z_ CString::operator const wchar_t*() const throw(); #define _Ret_z_ _Ret2_impl_(_$notnull, _$zterm) _Deref_ret1_impl_(_$valid) #define _Ret_opt_z_ _Ret2_impl_(_$maybenull,_$zterm) _Deref_ret1_impl_(_$valid) // e.g. _Ret_opt_bytecap_(cb) void* AllocateMemory( size_t cb ); // Buffer capacity is described by another parameter #define _Ret_cap_(size) _Ret2_impl_(_$notnull, _$cap(size)) #define _Ret_opt_cap_(size) _Ret2_impl_(_$maybenull,_$cap(size)) #define _Ret_bytecap_(size) _Ret2_impl_(_$notnull, _$bytecap(size)) #define _Ret_opt_bytecap_(size) _Ret2_impl_(_$maybenull,_$bytecap(size)) // Buffer capacity is described by a constant expression #define _Ret_cap_c_(size) _Ret2_impl_(_$notnull, _$cap_c(size)) #define _Ret_opt_cap_c_(size) _Ret2_impl_(_$maybenull,_$cap_c(size)) #define _Ret_bytecap_c_(size) _Ret2_impl_(_$notnull, _$bytecap_c(size)) #define _Ret_opt_bytecap_c_(size) _Ret2_impl_(_$maybenull,_$bytecap_c(size)) // Buffer capacity is described by a complex condition #define _Ret_cap_x_(size) _Ret2_impl_(_$notnull, _$cap_x(size)) #define _Ret_opt_cap_x_(size) _Ret2_impl_(_$maybenull,_$cap_x(size)) #define _Ret_bytecap_x_(size) _Ret2_impl_(_$notnull, _$bytecap_x(size)) #define _Ret_opt_bytecap_x_(size) _Ret2_impl_(_$maybenull,_$bytecap_x(size)) // return value is nullterminated and capacity is given by another parameter #define _Ret_z_cap_(size) _Ret3_impl_(_$notnull, _$zterm,_$cap(size)) _Deref_ret1_impl_(_$valid) #define _Ret_opt_z_cap_(size) _Ret3_impl_(_$maybenull,_$zterm,_$cap(size)) _Deref_ret1_impl_(_$valid) #define _Ret_z_bytecap_(size) _Ret3_impl_(_$notnull, _$zterm,_$bytecap(size)) _Deref_ret1_impl_(_$valid) #define _Ret_opt_z_bytecap_(size) _Ret3_impl_(_$maybenull,_$zterm,_$bytecap(size)) _Deref_ret1_impl_(_$valid) // e.g. _Ret_opt_bytecount_(cb) void* AllocateZeroInitializedMemory( size_t cb ); // Valid Buffer extent is described by another parameter #define _Ret_count_(size) _Ret2_impl_(_$notnull, _$count(size)) _Deref_ret1_impl_(_$valid) #define _Ret_opt_count_(size) _Ret2_impl_(_$maybenull,_$count(size)) _Deref_ret1_impl_(_$valid) #define _Ret_bytecount_(size) _Ret2_impl_(_$notnull, _$bytecount(size)) _Deref_ret1_impl_(_$valid) #define _Ret_opt_bytecount_(size) _Ret2_impl_(_$maybenull,_$bytecount(size)) _Deref_ret1_impl_(_$valid) // Valid Buffer extent is described by a constant expression #define _Ret_count_c_(size) _Ret2_impl_(_$notnull, _$count_c(size)) _Deref_ret1_impl_(_$valid) #define _Ret_opt_count_c_(size) _Ret2_impl_(_$maybenull,_$count_c(size)) _Deref_ret1_impl_(_$valid) #define _Ret_bytecount_c_(size) _Ret2_impl_(_$notnull, _$bytecount_c(size)) _Deref_ret1_impl_(_$valid) #define _Ret_opt_bytecount_c_(size) _Ret2_impl_(_$maybenull,_$bytecount_c(size)) _Deref_ret1_impl_(_$valid) // Valid Buffer extent is described by a complex expression #define _Ret_count_x_(size) _Ret2_impl_(_$notnull, _$count_x(size)) _Deref_ret1_impl_(_$valid) #define _Ret_opt_count_x_(size) _Ret2_impl_(_$maybenull,_$count_x(size)) _Deref_ret1_impl_(_$valid) #define _Ret_bytecount_x_(size) _Ret2_impl_(_$notnull, _$bytecount_x(size)) _Deref_ret1_impl_(_$valid) #define _Ret_opt_bytecount_x_(size) _Ret2_impl_(_$maybenull,_$bytecount_x(size)) _Deref_ret1_impl_(_$valid) // return value is nullterminated and length is given by another parameter #define _Ret_z_count_(size) _Ret3_impl_(_$notnull, _$zterm,_$count(size)) _Deref_ret1_impl_(_$valid) #define _Ret_opt_z_count_(size) _Ret3_impl_(_$maybenull,_$zterm,_$count(size)) _Deref_ret1_impl_(_$valid) #define _Ret_z_bytecount_(size) _Ret3_impl_(_$notnull, _$zterm,_$bytecount(size)) _Deref_ret1_impl_(_$valid) #define _Ret_opt_z_bytecount_(size) _Ret3_impl_(_$maybenull,_$zterm,_$bytecount(size)) _Deref_ret1_impl_(_$valid) // e.g. _Ret_opt_valid_ LPSTR void* CloneSTR( _Pre_valid_ LPSTR src ); #define _Ret_valid_ _Ret1_impl_(_$notnull) _Deref_ret1_impl_(_$valid) #define _Ret_opt_valid_ _Ret1_impl_(_$maybenull) _Deref_ret1_impl_(_$valid) // used with allocated but not yet initialized objects #define _Ret_notnull_ _Ret1_impl_(_$notnull) #define _Ret_maybenull_ _Ret1_impl_(_$maybenull) #define _Ret_null_ _Ret1_impl_(_$null) // // _Deref_pre_ --- // // describing conditions for array elements of dereferenced pointer parameters that must be met before the call // e.g. void SaveStringArray( _In_count_(cStrings) _Deref_pre_z_ const wchar_t* const rgpwch[] ); #define _Deref_pre_z_ _Deref_pre2_impl_(_$notnull, _$zterm) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_z_ _Deref_pre2_impl_(_$maybenull,_$zterm) _Deref2_pre1_impl_(_$valid) // e.g. void FillInArrayOfStr32( _In_count_(cStrings) _Deref_pre_cap_c_(32) _Deref_post_z_ wchar_t* const rgpwch[] ); // buffer capacity is described by another parameter #define _Deref_pre_cap_(size) _Deref_pre2_impl_(_$notnull, _$cap(size)) #define _Deref_pre_opt_cap_(size) _Deref_pre2_impl_(_$maybenull,_$cap(size)) #define _Deref_pre_bytecap_(size) _Deref_pre2_impl_(_$notnull, _$bytecap(size)) #define _Deref_pre_opt_bytecap_(size) _Deref_pre2_impl_(_$maybenull,_$bytecap(size)) // buffer capacity is described by a constant expression #define _Deref_pre_cap_c_(size) _Deref_pre2_impl_(_$notnull, _$cap_c(size)) #define _Deref_pre_opt_cap_c_(size) _Deref_pre2_impl_(_$maybenull,_$cap_c(size)) #define _Deref_pre_bytecap_c_(size) _Deref_pre2_impl_(_$notnull, _$bytecap_c(size)) #define _Deref_pre_opt_bytecap_c_(size) _Deref_pre2_impl_(_$maybenull,_$bytecap_c(size)) // buffer capacity is described by a complex condition #define _Deref_pre_cap_x_(size) _Deref_pre2_impl_(_$notnull, _$cap_x(size)) #define _Deref_pre_opt_cap_x_(size) _Deref_pre2_impl_(_$maybenull,_$cap_x(size)) #define _Deref_pre_bytecap_x_(size) _Deref_pre2_impl_(_$notnull, _$bytecap_x(size)) #define _Deref_pre_opt_bytecap_x_(size) _Deref_pre2_impl_(_$maybenull,_$bytecap_x(size)) // convenience macros for nullterminated buffers with given capacity #define _Deref_pre_z_cap_(size) _Deref_pre3_impl_(_$notnull, _$zterm,_$cap(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_z_cap_(size) _Deref_pre3_impl_(_$maybenull,_$zterm,_$cap(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_z_bytecap_(size) _Deref_pre3_impl_(_$notnull, _$zterm,_$bytecap(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_z_bytecap_(size) _Deref_pre3_impl_(_$maybenull,_$zterm,_$bytecap(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_z_cap_c_(size) _Deref_pre3_impl_(_$notnull, _$zterm,_$cap_c(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_z_cap_c_(size) _Deref_pre3_impl_(_$maybenull,_$zterm,_$cap_c(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_z_bytecap_c_(size) _Deref_pre3_impl_(_$notnull, _$zterm,_$bytecap_c(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_z_bytecap_c_(size) _Deref_pre3_impl_(_$maybenull,_$zterm,_$bytecap_c(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_z_cap_x_(size) _Deref_pre3_impl_(_$notnull, _$zterm,_$cap_x(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_z_cap_x_(size) _Deref_pre3_impl_(_$maybenull,_$zterm,_$cap_x(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_z_bytecap_x_(size) _Deref_pre3_impl_(_$notnull, _$zterm,_$bytecap_x(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_z_bytecap_x_(size) _Deref_pre3_impl_(_$maybenull,_$zterm,_$bytecap_x(size)) _Deref2_pre1_impl_(_$valid) // known capacity and valid but unknown readable extent #define _Deref_pre_valid_cap_(size) _Deref_pre2_impl_(_$notnull, _$cap(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_valid_cap_(size) _Deref_pre2_impl_(_$maybenull,_$cap(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_valid_bytecap_(size) _Deref_pre2_impl_(_$notnull, _$bytecap(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_valid_bytecap_(size) _Deref_pre2_impl_(_$maybenull,_$bytecap(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_valid_cap_c_(size) _Deref_pre2_impl_(_$notnull, _$cap_c(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_valid_cap_c_(size) _Deref_pre2_impl_(_$maybenull,_$cap_c(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_valid_bytecap_c_(size) _Deref_pre2_impl_(_$notnull, _$bytecap_c(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_valid_bytecap_c_(size) _Deref_pre2_impl_(_$maybenull,_$bytecap_c(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_valid_cap_x_(size) _Deref_pre2_impl_(_$notnull, _$cap_x(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_valid_cap_x_(size) _Deref_pre2_impl_(_$maybenull,_$cap_x(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_valid_bytecap_x_(size) _Deref_pre2_impl_(_$notnull, _$bytecap_x(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_valid_bytecap_x_(size) _Deref_pre2_impl_(_$maybenull,_$bytecap_x(size)) _Deref2_pre1_impl_(_$valid) // e.g. void SaveMatrix( _In_count_(n) _Deref_pre_count_(n) const Elem** matrix, size_t n ); // valid buffer extent is described by another parameter #define _Deref_pre_count_(size) _Deref_pre2_impl_(_$notnull, _$count(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_count_(size) _Deref_pre2_impl_(_$maybenull,_$count(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_bytecount_(size) _Deref_pre2_impl_(_$notnull, _$bytecount(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_bytecount_(size) _Deref_pre2_impl_(_$maybenull,_$bytecount(size)) _Deref2_pre1_impl_(_$valid) // valid buffer extent is described by a constant expression #define _Deref_pre_count_c_(size) _Deref_pre2_impl_(_$notnull, _$count_c(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_count_c_(size) _Deref_pre2_impl_(_$maybenull,_$count_c(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_bytecount_c_(size) _Deref_pre2_impl_(_$notnull, _$bytecount_c(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_bytecount_c_(size) _Deref_pre2_impl_(_$maybenull,_$bytecount_c(size)) _Deref2_pre1_impl_(_$valid) // valid buffer extent is described by a complex expression #define _Deref_pre_count_x_(size) _Deref_pre2_impl_(_$notnull, _$count_x(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_count_x_(size) _Deref_pre2_impl_(_$maybenull,_$count_x(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_bytecount_x_(size) _Deref_pre2_impl_(_$notnull, _$bytecount_x(size)) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_bytecount_x_(size) _Deref_pre2_impl_(_$maybenull,_$bytecount_x(size)) _Deref2_pre1_impl_(_$valid) // e.g. void PrintStringArray( _In_count_(cElems) _Deref_pre_valid_ LPCSTR rgStr[], size_t cElems ); #define _Deref_pre_valid_ _Deref_pre1_impl_(_$notnull) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_opt_valid_ _Deref_pre1_impl_(_$maybenull) _Deref2_pre1_impl_(_$valid) #define _Deref_pre_invalid_ _Deref2_pre1_impl_(_$notvalid) #define _Deref_pre_notnull_ _Deref_pre1_impl_(_$notnull) #define _Deref_pre_maybenull_ _Deref_pre1_impl_(_$maybenull) #define _Deref_pre_null_ _Deref_pre1_impl_(_$null) // restrict access rights #define _Deref_pre_readonly_ _Deref_pre1_impl_(_$readaccess) #define _Deref_pre_writeonly_ _Deref_pre1_impl_(_$writeaccess) // // _Deref_post_ --- // // describing conditions for array elements or dereferenced pointer parameters that hold after the call // e.g. void CloneString( _In_z_ const Wchar_t* wzIn _Out_ _Deref_post_z_ wchar_t** pWzOut ); #define _Deref_post_z_ _Deref_post2_impl_(_$notnull, _$zterm) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_z_ _Deref_post2_impl_(_$maybenull,_$zterm) _Deref2_post1_impl_(_$valid) // e.g. HRESULT HrAllocateMemory( size_t cb, _Out_ _Deref_post_bytecap_(cb) void** ppv ); // buffer capacity is described by another parameter #define _Deref_post_cap_(size) _Deref_post2_impl_(_$notnull, _$cap(size)) #define _Deref_post_opt_cap_(size) _Deref_post2_impl_(_$maybenull,_$cap(size)) #define _Deref_post_bytecap_(size) _Deref_post2_impl_(_$notnull, _$bytecap(size)) #define _Deref_post_opt_bytecap_(size) _Deref_post2_impl_(_$maybenull,_$bytecap(size)) // buffer capacity is described by a constant expression #define _Deref_post_cap_c_(size) _Deref_post2_impl_(_$notnull, _$cap_z(size)) #define _Deref_post_opt_cap_c_(size) _Deref_post2_impl_(_$maybenull,_$cap_z(size)) #define _Deref_post_bytecap_c_(size) _Deref_post2_impl_(_$notnull, _$bytecap_z(size)) #define _Deref_post_opt_bytecap_c_(size) _Deref_post2_impl_(_$maybenull,_$bytecap_z(size)) // buffer capacity is described by a complex expression #define _Deref_post_cap_x_(size) _Deref_post2_impl_(_$notnull, _$cap_x(size)) #define _Deref_post_opt_cap_x_(size) _Deref_post2_impl_(_$maybenull,_$cap_x(size)) #define _Deref_post_bytecap_x_(size) _Deref_post2_impl_(_$notnull, _$bytecap_x(size)) #define _Deref_post_opt_bytecap_x_(size) _Deref_post2_impl_(_$maybenull,_$bytecap_x(size)) // convenience macros for nullterminated buffers with given capacity #define _Deref_post_z_cap_(size) _Deref_post3_impl_(_$notnull, _$zterm,_$cap(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_z_cap_(size) _Deref_post3_impl_(_$maybenull,_$zterm,_$cap(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_z_bytecap_(size) _Deref_post3_impl_(_$notnull, _$zterm,_$bytecap(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_z_bytecap_(size) _Deref_post3_impl_(_$maybenull,_$zterm,_$bytecap(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_z_cap_c_(size) _Deref_post3_impl_(_$notnull, _$zterm,_$cap_c(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_z_cap_c_(size) _Deref_post3_impl_(_$maybenull,_$zterm,_$cap_c(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_z_bytecap_c_(size) _Deref_post3_impl_(_$notnull, _$zterm,_$bytecap_c(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_z_bytecap_c_(size) _Deref_post3_impl_(_$maybenull,_$zterm,_$bytecap_c(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_z_cap_x_(size) _Deref_post3_impl_(_$notnull, _$zterm,_$cap_x(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_z_cap_x_(size) _Deref_post3_impl_(_$maybenull,_$zterm,_$cap_x(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_z_bytecap_x_(size) _Deref_post3_impl_(_$notnull, _$zterm,_$bytecap_x(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_z_bytecap_x_(size) _Deref_post3_impl_(_$maybenull,_$zterm,_$bytecap_x(size)) _Deref2_post1_impl_(_$valid) // known capacity and valid but unknown readable extent #define _Deref_post_valid_cap_(size) _Deref_post2_impl_(_$notnull, _$cap(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_valid_cap_(size) _Deref_post2_impl_(_$maybenull,_$cap(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_valid_bytecap_(size) _Deref_post2_impl_(_$notnull, _$bytecap(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_valid_bytecap_(size) _Deref_post2_impl_(_$maybenull,_$bytecap(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_valid_cap_c_(size) _Deref_post2_impl_(_$notnull, _$cap_c(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_valid_cap_c_(size) _Deref_post2_impl_(_$maybenull,_$cap_c(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_valid_bytecap_c_(size) _Deref_post2_impl_(_$notnull, _$bytecap_c(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_valid_bytecap_c_(size) _Deref_post2_impl_(_$maybenull,_$bytecap_c(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_valid_cap_x_(size) _Deref_post2_impl_(_$notnull, _$cap_x(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_valid_cap_x_(size) _Deref_post2_impl_(_$maybenull,_$cap_x(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_valid_bytecap_x_(size) _Deref_post2_impl_(_$notnull, _$bytecap_x(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_valid_bytecap_x_(size) _Deref_post2_impl_(_$maybenull,_$bytecap_x(size)) _Deref2_post1_impl_(_$valid) // e.g. HRESULT HrAllocateZeroInitializedMemory( size_t cb, _Out_ _Deref_post_bytecount_(cb) void** ppv ); // valid buffer extent is described by another parameter #define _Deref_post_count_(size) _Deref_post2_impl_(_$notnull, _$count(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_count_(size) _Deref_post2_impl_(_$maybenull,_$count(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_bytecount_(size) _Deref_post2_impl_(_$notnull, _$bytecount(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_bytecount_(size) _Deref_post2_impl_(_$maybenull,_$bytecount(size)) _Deref2_post1_impl_(_$valid) // buffer capacity is described by a constant expression #define _Deref_post_count_c_(size) _Deref_post2_impl_(_$notnull, _$count_c(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_count_c_(size) _Deref_post2_impl_(_$maybenull,_$count_c(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_bytecount_c_(size) _Deref_post2_impl_(_$notnull, _$bytecount_c(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_bytecount_c_(size) _Deref_post2_impl_(_$maybenull,_$bytecount_c(size)) _Deref2_post1_impl_(_$valid) // buffer capacity is described by a complex expression #define _Deref_post_count_x_(size) _Deref_post2_impl_(_$notnull, _$count_x(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_count_x_(size) _Deref_post2_impl_(_$maybenull,_$count_x(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_bytecount_x_(size) _Deref_post2_impl_(_$notnull, _$bytecount_x(size)) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_bytecount_x_(size) _Deref_post2_impl_(_$maybenull,_$bytecount_x(size)) _Deref2_post1_impl_(_$valid) // e.g. void GetStrings( _Out_count_(cElems) _Deref_post_valid_ LPSTR const rgStr[], size_t cElems ); #define _Deref_post_valid_ _Deref_post1_impl_(_$notnull) _Deref2_post1_impl_(_$valid) #define _Deref_post_opt_valid_ _Deref_post1_impl_(_$maybenull) _Deref2_post1_impl_(_$valid) #define _Deref_post_notnull_ _Deref_post1_impl_(_$notnull) #define _Deref_post_maybenull_ _Deref_post1_impl_(_$maybenull) #define _Deref_post_null_ _Deref_post1_impl_(_$null) // // _Deref_ret_ --- // #define _Deref_ret_z_ _Deref_ret2_impl_(_$notnull, _$zterm) #define _Deref_ret_opt_z_ _Deref_ret2_impl_(_$maybenull,_$zterm) // // special _Deref_ --- // #define _Deref2_pre_readonly_ _Deref2_pre1_impl_(_$readaccess) // Convenience macros for more concise annotations // // _Pre_post --- // // describing conditions that hold before and after the function call #define _Prepost_z_ _Pre_z_ _Post_z_ #define _Prepost_opt_z_ _Pre_opt_z_ _Post_z_ #define _Prepost_count_(size) _Pre_count_(size) _Post_count_(size) #define _Prepost_opt_count_(size) _Pre_opt_count_(size) _Post_count_(size) #define _Prepost_bytecount_(size) _Pre_bytecount_(size) _Post_bytecount_(size) #define _Prepost_opt_bytecount_(size) _Pre_opt_bytecount_(size) _Post_bytecount_(size) #define _Prepost_count_c_(size) _Pre_count_c_(size) _Post_count_c_(size) #define _Prepost_opt_count_c_(size) _Pre_opt_count_c_(size) _Post_count_c_(size) #define _Prepost_bytecount_c_(size) _Pre_bytecount_c_(size) _Post_bytecount_c_(size) #define _Prepost_opt_bytecount_c_(size) _Pre_opt_bytecount_c_(size) _Post_bytecount_c_(size) #define _Prepost_count_x_(size) _Pre_count_x_(size) _Post_count_x_(size) #define _Prepost_opt_count_x_(size) _Pre_opt_count_x_(size) _Post_count_x_(size) #define _Prepost_bytecount_x_(size) _Pre_bytecount_x_(size) _Post_bytecount_x_(size) #define _Prepost_opt_bytecount_x_(size) _Pre_opt_bytecount_x_(size) _Post_bytecount_x_(size) #define _Prepost_valid_ _Pre_valid_ _Post_valid_ #define _Prepost_opt_valid_ _Pre_opt_valid_ _Post_valid_ // // _Deref_<both> --- // // short version for _Deref_pre_<ann> _Deref_post_<ann> // describing conditions for array elements or dereferenced pointer parameters that hold before and after the call #define _Deref_prepost_z_ _Deref_pre_z_ _Deref_post_z_ #define _Deref_prepost_opt_z_ _Deref_pre_opt_z_ _Deref_post_opt_z_ #define _Deref_prepost_cap_(size) _Deref_pre_cap_(size) _Deref_post_cap_(size) #define _Deref_prepost_opt_cap_(size) _Deref_pre_opt_cap_(size) _Deref_post_opt_cap_(size) #define _Deref_prepost_bytecap_(size) _Deref_pre_bytecap_(size) _Deref_post_bytecap_(size) #define _Deref_prepost_opt_bytecap_(size) _Deref_pre_opt_bytecap_(size) _Deref_post_opt_bytecap_(size) #define _Deref_prepost_cap_x_(size) _Deref_pre_cap_x_(size) _Deref_post_cap_x_(size) #define _Deref_prepost_opt_cap_x_(size) _Deref_pre_opt_cap_x_(size) _Deref_post_opt_cap_x_(size) #define _Deref_prepost_bytecap_x_(size) _Deref_pre_bytecap_x_(size) _Deref_post_bytecap_x_(size) #define _Deref_prepost_opt_bytecap_x_(size) _Deref_pre_opt_bytecap_x_(size) _Deref_post_opt_bytecap_x_(size) #define _Deref_prepost_z_cap_(size) _Deref_pre_z_cap_(size) _Deref_post_z_cap_(size) #define _Deref_prepost_opt_z_cap_(size) _Deref_pre_opt_z_cap_(size) _Deref_post_opt_z_cap_(size) #define _Deref_prepost_z_bytecap_(size) _Deref_pre_z_bytecap_(size) _Deref_post_z_bytecap_(size) #define _Deref_prepost_opt_z_bytecap_(size) _Deref_pre_opt_z_bytecap_(size) _Deref_post_opt_z_bytecap_(size) #define _Deref_prepost_valid_cap_(size) _Deref_pre_valid_cap_(size) _Deref_post_valid_cap_(size) #define _Deref_prepost_opt_valid_cap_(size) _Deref_pre_opt_valid_cap_(size) _Deref_post_opt_valid_cap_(size) #define _Deref_prepost_valid_bytecap_(size) _Deref_pre_valid_bytecap_(size) _Deref_post_valid_bytecap_(size) #define _Deref_prepost_opt_valid_bytecap_(size) _Deref_pre_opt_valid_bytecap_(size) _Deref_post_opt_valid_bytecap_(size) #define _Deref_prepost_valid_cap_x_(size) _Deref_pre_valid_cap_x_(size) _Deref_post_valid_cap_x_(size) #define _Deref_prepost_opt_valid_cap_x_(size) _Deref_pre_opt_valid_cap_x_(size) _Deref_post_opt_valid_cap_x_(size) #define _Deref_prepost_valid_bytecap_x_(size) _Deref_pre_valid_bytecap_x_(size) _Deref_post_valid_bytecap_x_(size) #define _Deref_prepost_opt_valid_bytecap_x_(size) _Deref_pre_opt_valid_bytecap_x_(size) _Deref_post_opt_valid_bytecap_x_(size) #define _Deref_prepost_count_(size) _Deref_pre_count_(size) _Deref_post_count_(size) #define _Deref_prepost_opt_count_(size) _Deref_pre_opt_count_(size) _Deref_post_opt_count_(size) #define _Deref_prepost_bytecount_(size) _Deref_pre_bytecount_(size) _Deref_post_bytecount_(size) #define _Deref_prepost_opt_bytecount_(size) _Deref_pre_opt_bytecount_(size) _Deref_post_opt_bytecount_(size) #define _Deref_prepost_count_x_(size) _Deref_pre_count_x_(size) _Deref_post_count_x_(size) #define _Deref_prepost_opt_count_x_(size) _Deref_pre_opt_count_x_(size) _Deref_post_opt_count_x_(size) #define _Deref_prepost_bytecount_x_(size) _Deref_pre_bytecount_x_(size) _Deref_post_bytecount_x_(size) #define _Deref_prepost_opt_bytecount_x_(size) _Deref_pre_opt_bytecount_x_(size) _Deref_post_opt_bytecount_x_(size) #define _Deref_prepost_valid_ _Deref_pre_valid_ _Deref_post_valid_ #define _Deref_prepost_opt_valid_ _Deref_pre_opt_valid_ _Deref_post_opt_valid_ // // _Deref_<miscellaneous> // // used with references to arrays #define _Deref_out_z_cap_c_(size) _Deref_pre_cap_c_(size) _Deref_pre_invalid_ _Deref_post_z_ #define _Deref_inout_z_cap_c_(size) _Deref_pre_z_cap_c_(size) _Deref_post_z_ #define _Deref_out_z_bytecap_c_(size) _Deref_pre_bytecap_c_(size) _Deref_pre_invalid_ _Deref_post_z_ #define _Deref_inout_z_bytecap_c_(size) _Deref_pre_z_bytecap_c_(size) _Deref_post_z_ #define _Deref_inout_z_ _Deref_prepost_z_
-------------------------------------------------------------------------------
Buffer Annotations
The most important annotations in sal.h provide a consistent way to annotate
buffer parameters or return values for a function. Each of these annotations describes
a single buffer (which could be a string, a fixed-length or variable-length array,
or just a pointer) that the function interacts with: where it is, how large it is,
how much is initialized, and what the function does with it.
The appropriate macro for a given buffer can be constructed using the table below.
Just pick the appropriate values from each category, and combine them together
with a leading underscore. Some combinations of values do not make sense as buffer
annotations. Only meaningful annotations can be added to your code; for a list of
these, see the buffer annotation definitions section.
Only a single buffer annotation should be used for each parameter.
Level: Describes the buffer pointer's level of indirection from the parameter or
return value 'p'.
<> : p is the buffer pointer.
_deref : *p is the buffer pointer. p must not be NULL.
_deref_opt : *p may be the buffer pointer. p may be NULL, in which case the rest of
the annotation is ignored.
Usage: Describes how the function uses the buffer.
<> : The buffer is not accessed. If used on the return value or with _deref, the
function will provide the buffer, and it will be uninitialized at exit.
Otherwise, the caller must provide the buffer. This should only be used
for alloc and free functions.
_in : The function will only read from the buffer. The caller must provide the
buffer and initialize it. Cannot be used with _deref.
_out : The function will only write to the buffer. If used on the return value or
with _deref, the function will provide the buffer and initialize it.
Otherwise, the caller must provide the buffer, and the function will
initialize it.
_inout : The function may freely read from and write to the buffer. The caller must
provide the buffer and initialize it. If used with _deref, the buffer may
be reallocated by the function.
Size: Describes the total size of the buffer. This may be less than the space actually
allocated for the buffer, in which case it describes the accessible amount.
<> : No buffer size is given. If the type specifies the buffer size (such as
with LPSTR and LPWSTR), that amount is used. Otherwise, the buffer is one
element long. Must be used with _in, _out, or _inout.
_ecount : The buffer size is an explicit element count.
_bcount : The buffer size is an explicit byte count.
Output: Describes how much of the buffer will be initialized by the function. For
_inout buffers, this also describes how much is initialized at entry. Omit this
category for _in buffers; they must be fully initialized by the caller.
<> : The type specifies how much is initialized. For instance, a function initializing
an LPWSTR must NULL-terminate the string.
_full : The function initializes the entire buffer.
_part : The function initializes part of the buffer, and explicitly indicates how much.
NullTerm: States if the present of a '\0' marks the end of valid elements in the buffer.
_z : A '\0' indicated the end of the buffer
_nz : The buffer may not be null terminated and a '\0' does not indicate the end of the
buffer.
Optional: Describes if the buffer itself is optional.
<> : The pointer to the buffer must not be NULL.
_opt : The pointer to the buffer might be NULL. It will be checked before being dereferenced.
Parameters: Gives explicit counts for the size and length of the buffer.
<> : There is no explicit count. Use when neither _ecount nor _bcount is used.
(size) : Only the buffer's total size is given. Use with _ecount or _bcount but not _part.
(size,length) : The buffer's total size and initialized length are given. Use with _ecount_part
and _bcount_part.
-------------------------------------------------------------------------------
Buffer Annotation Examples
LWSTDAPI_(BOOL) StrToIntExA(
LPCSTR pszString, -- No annotation required, const implies __in.
DWORD dwFlags,
__out int *piRet -- A pointer whose dereference will be filled in.
);
void MyPaintingFunction(
__in HWND hwndControl, -- An initialized read-only parameter.
__in_opt HDC hdcOptional, -- An initialized read-only parameter that might be NULL.
__inout IPropertyStore *ppsStore -- An initialized parameter that may be freely used
-- and modified.
);
LWSTDAPI_(BOOL) PathCompactPathExA(
__out_ecount(cchMax) LPSTR pszOut, -- A string buffer with cch elements that will
-- be NULL terminated on exit.
LPCSTR pszSrc, -- No annotation required, const implies __in.
UINT cchMax,
DWORD dwFlags
);
HRESULT SHLocalAllocBytes(
size_t cb,
__deref_bcount(cb) T **ppv -- A pointer whose dereference will be set to an
-- uninitialized buffer with cb bytes.
);
__inout_bcount_full(cb) : A buffer with cb elements that is fully initialized at
entry and exit, and may be written to by this function.
__out_ecount_part(count, *countOut) : A buffer with count elements that will be
partially initialized by this function. The function indicates how much it
initialized by setting *countOut.
-------------------------------------------------------------------------------
Advanced Annotations
Advanced annotations describe behavior that is not expressible with the regular
buffer macros. These may be used either to annotate buffer parameters that involve
complex or conditional behavior, or to enrich existing annotations with additional
information.
__success(expr) f :
<expr> indicates whether function f succeeded or not. If <expr> is true at exit,
all the function's guarantees (as given by other annotations) must hold. If <expr>
is false at exit, the caller should not expect any of the function's guarantees
to hold. If not used, the function must always satisfy its guarantees. Added
automatically to functions that indicate success in standard ways, such as by
returning an HRESULT.
__nullterminated p :
Pointer p is a buffer that may be read or written up to and including the first
NULL character or pointer. May be used on typedefs, which marks valid (properly
initialized) instances of that type as being NULL-terminated.
__nullnullterminated p :
Pointer p is a buffer that may be read or written up to and including the first
sequence of two NULL characters or pointers. May be used on typedefs, which marks
valid instances of that type as being double-NULL terminated.
__reserved v :
Value v must be 0/NULL, reserved for future use.
__checkReturn v :
Return value v must not be ignored by callers of this function.
__typefix(ctype) v :
Value v should be treated as an instance of ctype, rather than its declared type.
__override f :
Specify C#-style 'override' behaviour for overriding virtual methods.
__callback f :
Function f can be used as a function pointer.
__format_string p :
Pointer p is a string that contains % markers in the style of printf.
__blocksOn(resource) f :
Function f blocks on the resource 'resource'.
__fallthrough :
Annotates switch statement labels where fall-through is desired, to distinguish
from forgotten break statements.
-------------------------------------------------------------------------------
Advanced Annotation Examples
__success(return == TRUE) LWSTDAPI_(BOOL)
PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) :
pszBuf is only guaranteed to be NULL-terminated when TRUE is returned.
typedef __nullterminated WCHAR* LPWSTR : Initialized LPWSTRs are NULL-terminated strings.
__out_ecount(cch) __typefix(LPWSTR) void *psz : psz is a buffer parameter which will be
a NULL-terminated WCHAR string at exit, and which initially contains cch WCHARs.
1081
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
