sal.h

C语言库函数的原型,有用的拿去

// 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 );