|
|
|
| 1 |
|
/*** |
| 2 |
|
*sal.h - markers for documenting the semantics of APIs |
| 3 |
|
* |
| 4 |
|
* Copyright (c) Microsoft Corporation. All rights reserved. |
| 5 |
|
* |
| 6 |
|
*Purpose: |
| 7 |
|
* sal.h provides a set of annotations to describe how a function uses its |
| 8 |
|
* parameters - the assumptions it makes about them, and the guarantees it makes |
| 9 |
|
* upon finishing. |
| 10 |
|
* |
| 11 |
|
* [Public] |
| 12 |
|
* |
| 13 |
|
****/ |
| 14 |
|
|
| 15 |
|
#pragma once |
| 16 |
|
/*========================================================================== |
| 17 |
|
|
| 18 |
|
The macros are defined in 3 layers: |
| 19 |
|
|
| 20 |
|
_In_\_Out_ Layer: |
| 21 |
|
---------------- |
| 22 |
|
This layer provides the highest abstraction and its macros should be used |
| 23 |
|
in most cases. Its macros start with _In_, _Out_ or _Inout_. For the |
| 24 |
|
typical case they provide the most concise annotations. |
| 25 |
|
|
| 26 |
|
_Pre_\_Post_ Layer: |
| 27 |
|
------------------ |
| 28 |
|
The macros of this layer only should be used when there is no suitable macro |
| 29 |
|
in the _In_\_Out_ layer. Its macros start with _Pre_, _Post_, _Ret_, |
| 30 |
|
_Deref_pre_ _Deref_post_ and _Deref_ret_. This layer provides the most |
| 31 |
|
flexibility for annotations. |
| 32 |
|
|
| 33 |
|
Implementation Abstraction Layer: |
| 34 |
|
-------------------------------- |
| 35 |
|
Macros from this layer should never be used directly. The layer only exists |
| 36 |
|
to hide the implementation of the annotation macros. |
| 37 |
|
|
| 38 |
|
|
| 39 |
|
Annotation Syntax: |
| 40 |
|
|--------------|----------|----------------|-----------------------------| |
| 41 |
|
| Usage | Nullness | ZeroTerminated | Extent | |
| 42 |
|
|--------------|----------|----------------|-----------------------------| |
| 43 |
|
| _In_ | <> | <> | <> | |
| 44 |
|
| _Out_ | opt_ | z_ | [byte]cap_[c_|x_]( size ) | |
| 45 |
|
| _Inout_ | | | [byte]count_[c_|x_]( size ) | |
| 46 |
|
| _Deref_out_ | | | ptrdiff_cap_( ptr ) | |
| 47 |
|
|--------------| | | ptrdiff_count_( ptr ) | |
| 48 |
|
| _Ret_ | | | | |
| 49 |
|
| _Deref_ret_ | | | | |
| 50 |
|
|--------------| | | | |
| 51 |
|
| _Pre_ | | | | |
| 52 |
|
| _Post_ | | | | |
| 53 |
|
| _Deref_pre_ | | | | |
| 54 |
|
| _Deref_post_ | | | | |
| 55 |
|
|--------------|----------|----------------|-----------------------------| |
| 56 |
|
|
| 57 |
|
Usage: |
| 58 |
|
----- |
| 59 |
|
_In_, _Out_, _Inout_, _Pre_, _Post_, _Deref_pre_, _Deref_post_ are for |
| 60 |
|
formal parameters. |
| 61 |
|
_Ret_, _Deref_ret_ must be used for return values. |
| 62 |
|
|
| 63 |
|
Nullness: |
| 64 |
|
-------- |
| 65 |
|
If the pointer can be NULL the annotation contains _opt. If the macro |
| 66 |
|
does not contain '_opt' the pointer may not be NULL. |
| 67 |
|
|
| 68 |
|
String Type: |
| 69 |
|
----------- |
| 70 |
|
_z: NullTerminated string |
| 71 |
|
for _In_ parameters the buffer must have the specified stringtype before the call |
| 72 |
|
for _Out_ parameters the buffer must have the specified stringtype after the call |
| 73 |
|
for _Inout_ parameters both conditions apply |
| 74 |
|
|
| 75 |
|
Extent Syntax: |
| 76 |
|
|------|---------------|---------------| |
| 77 |
|
| Unit | Writ\Readable | Argument Type | |
| 78 |
|
|------|---------------|---------------| |
| 79 |
|
| <> | cap_ | <> | |
| 80 |
|
| byte | count_ | c_ | |
| 81 |
|
| | | x_ | |
| 82 |
|
|------|---------------|---------------| |
| 83 |
|
|
| 84 |
|
'cap' (capacity) describes the writable size of the buffer and is typically used |
| 85 |
|
with _Out_. The default unit is elements. Use 'bytecap' if the size is given in bytes |
| 86 |
|
'count' describes the readable size of the buffer and is typically used with _In_. |
| 87 |
|
The default unit is elements. Use 'bytecount' if the size is given in bytes. |
| 88 |
|
|
| 89 |
|
Argument syntax for cap_, bytecap_, count_, bytecount_: |
| 90 |
|
(<parameter>|return)[+n] e.g. cch, return, cb+2 |
| 91 |
|
|
| 92 |
|
If the buffer size is a constant expression use the c_ postfix. |
| 93 |
|
E.g. cap_c_(20), count_c_(MAX_PATH), bytecount_c_(16) |
| 94 |
|
|
| 95 |
|
If the buffer size is given by a limiting pointer use the ptrdiff_ versions |
| 96 |
|
of the macros. |
| 97 |
|
|
| 98 |
|
If the buffer size is neither a parameter nor a constant expression use the x_ |
| 99 |
|
postfix. e.g. bytecount_x_(num*size) x_ annotations accept any arbitrary string. |
| 100 |
|
No analysis can be done for x_ annotations but they at least tell the tool that |
| 101 |
|
the buffer has some sort of extent description. x_ annotations might be supported |
| 102 |
|
by future compiler versions. |
| 103 |
|
|
| 104 |
|
============================================================================*/ |
| 105 |
|
|
| 106 |
|
#define __ATTR_SAL |
| 107 |
|
|
| 108 |
|
// choose attribute or __declspec implementation |
| 109 |
|
#ifndef _USE_DECLSPECS_FOR_SAL |
| 110 |
|
#define _USE_DECLSPECS_FOR_SAL 0 |
| 111 |
|
#endif |
| 112 |
|
|
| 113 |
|
#if _USE_DECLSPECS_FOR_SAL |
| 114 |
|
#undef _USE_ATTRIBUTES_FOR_SAL |
| 115 |
|
#define _USE_ATTRIBUTES_FOR_SAL 0 |
| 116 |
|
#elif !defined(_USE_ATTRIBUTES_FOR_SAL) |
| 117 |
|
#if _MSC_VER >= 1400 |
| 118 |
|
#define _USE_ATTRIBUTES_FOR_SAL 1 |
| 119 |
|
#else |
| 120 |
|
#define _USE_ATTRIBUTES_FOR_SAL 0 |
| 121 |
|
#endif |
| 122 |
|
#endif |
| 123 |
|
|
| 124 |
|
#ifdef _PREFAST_ |
| 125 |
|
|
| 126 |
|
#if !_USE_DECLSPECS_FOR_SAL |
| 127 |
|
#if !_USE_ATTRIBUTES_FOR_SAL |
| 128 |
|
#if _MSC_VER >= 1400 |
| 129 |
|
#undef _USE_ATTRIBUTES_FOR_SAL |
| 130 |
|
#define _USE_ATTRIBUTES_FOR_SAL 1 |
| 131 |
|
#else |
| 132 |
|
#undef _USE_DECLSPECS_FOR_SAL |
| 133 |
|
#define _USE_DECLSPECS_FOR_SAL 1 |
| 134 |
|
#endif |
| 135 |
|
#endif |
| 136 |
|
#endif |
| 137 |
|
|
| 138 |
|
#endif // #ifdef _PREFAST |
| 139 |
|
|
| 140 |
|
// safeguard for MIDL and RC builds |
| 141 |
|
#if _USE_DECLSPECS_FOR_SAL && ( defined( MIDL_PASS ) || defined(__midl) || defined(RC_INVOKED) || !defined(_PREFAST_) ) |
| 142 |
|
#undef _USE_DECLSPECS_FOR_SAL |
| 143 |
|
#define _USE_DECLSPECS_FOR_SAL 0 |
| 144 |
|
#endif |
| 145 |
|
#if _USE_ATTRIBUTES_FOR_SAL && ( !defined(_MSC_EXTENSIONS) || defined( MIDL_PASS ) || defined(__midl) || defined(RC_INVOKED) ) |
| 146 |
|
#undef _USE_ATTRIBUTES_FOR_SAL |
| 147 |
|
#define _USE_ATTRIBUTES_FOR_SAL 0 |
| 148 |
|
#endif |
| 149 |
|
|
| 150 |
|
//============================================================================ |
| 151 |
|
// _In_\_Out_ Layer: |
| 152 |
|
//============================================================================ |
| 153 |
|
|
| 154 |
|
// 'in' parameters -------------------------- |
| 155 |
|
|
| 156 |
|
// input pointer parameter |
| 157 |
|
// e.g. void SetPoint( _In_ const POINT* pPT ); |
| 158 |
|
#define _In_ _Pre1_impl_(_$notnull) _Deref_pre2_impl_(_$valid, _$readaccess) |
| 159 |
|
#define _In_opt_ _Pre_opt_valid_ _Deref_pre_readonly_ |
| 160 |
|
|
| 161 |
|
// nullterminated 'in' parameters. |
| 162 |
|
// e.g. void CopyStr( _In_z_ const char* szFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo ); |
| 163 |
|
#define _In_z_ _Pre_z_ _Deref_pre_readonly_ |
| 164 |
|
#define _In_opt_z_ _Pre_opt_z_ _Deref_pre_readonly_ |
| 165 |
|
|
| 166 |
|
// 'input' buffers with given size |
| 167 |
|
|
| 168 |
|
// e.g. void SetCharRange( _In_count_(cch) const char* rgch, size_t cch ) |
| 169 |
|
// valid buffer extent described by another parameter |
| 170 |
|
#define _In_count_(size) _Pre_count_(size) _Deref_pre_readonly_ |
| 171 |
|
#define _In_opt_count_(size) _Pre_opt_count_(size) _Deref_pre_readonly_ |
| 172 |
|
#define _In_bytecount_(size) _Pre_bytecount_(size) _Deref_pre_readonly_ |
| 173 |
|
#define _In_opt_bytecount_(size) _Pre_opt_bytecount_(size) _Deref_pre_readonly_ |
| 174 |
|
|
| 175 |
|
// valid buffer extent described by a constant extression |
| 176 |
|
#define _In_count_c_(size) _Pre_count_c_(size) _Deref_pre_readonly_ |
| 177 |
|
#define _In_opt_count_c_(size) _Pre_opt_count_c_(size) _Deref_pre_readonly_ |
| 178 |
|
#define _In_bytecount_c_(size) _Pre_bytecount_c_(size) _Deref_pre_readonly_ |
| 179 |
|
#define _In_opt_bytecount_c_(size) _Pre_opt_bytecount_c_(size) _Deref_pre_readonly_ |
| 180 |
|
|
| 181 |
|
// nullterminated 'input' buffers with given size |
| 182 |
|
|
| 183 |
|
// e.g. void SetCharRange( _In_count_(cch) const char* rgch, size_t cch ) |
| 184 |
|
// nullterminated valid buffer extent described by another parameter |
| 185 |
|
#define _In_z_count_(size) _Pre_z_ _Pre_count_(size) _Deref_pre_readonly_ |
| 186 |
|
#define _In_opt_z_count_(size) _Pre_opt_z_ _Pre_opt_count_(size) _Deref_pre_readonly_ |
| 187 |
|
#define _In_z_bytecount_(size) _Pre_z_ _Pre_bytecount_(size) _Deref_pre_readonly_ |
| 188 |
|
#define _In_opt_z_bytecount_(size) _Pre_opt_z_ _Pre_opt_bytecount_(size) _Deref_pre_readonly_ |
| 189 |
|
|
| 190 |
|
// nullterminated valid buffer extent described by a constant extression |
| 191 |
|
#define _In_z_count_c_(size) _Pre_z_ _Pre_count_c_(size) _Deref_pre_readonly_ |
| 192 |
|
#define _In_opt_z_count_c_(size) _Pre_opt_z_ _Pre_opt_count_c_(size) _Deref_pre_readonly_ |
| 193 |
|
#define _In_z_bytecount_c_(size) _Pre_z_ _Pre_bytecount_c_(size) _Deref_pre_readonly_ |
| 194 |
|
#define _In_opt_z_bytecount_c_(size) _Pre_opt_z_ _Pre_opt_bytecount_c_(size) _Deref_pre_readonly_ |
| 195 |
|
|
| 196 |
|
// buffer capacity is described by another pointer |
| 197 |
|
// e.g. void Foo( _In_ptrdiff_count_(pchMax) const char* pch, const char* pchMax ) { while pch < pchMax ) pch++; } |
| 198 |
|
#define _In_ptrdiff_count_(size) _Pre_ptrdiff_count_(size) _Deref_pre_readonly_ |
| 199 |
|
#define _In_opt_ptrdiff_count_(size) _Pre_opt_ptrdiff_count_(size) _Deref_pre_readonly_ |
| 200 |
|
|
| 201 |
|
// 'x' version for complex expressions that are not supported by the current compiler version |
| 202 |
|
// e.g. void Set3ColMatrix( _In_count_x_(3*cRows) const Elem* matrix, int cRows ); |
| 203 |
|
#define _In_count_x_(size) _Pre_count_x_(size) _Deref_pre_readonly_ |
| 204 |
|
#define _In_opt_count_x_(size) _Pre_opt_count_x_(size) _Deref_pre_readonly_ |
| 205 |
|
#define _In_bytecount_x_(size) _Pre_bytecount_x_(size) _Deref_pre_readonly_ |
| 206 |
|
#define _In_opt_bytecount_x_(size) _Pre_opt_bytecount_x_(size) _Deref_pre_readonly_ |
| 207 |
|
|
| 208 |
|
// 'out' parameters -------------------------- |
| 209 |
|
|
| 210 |
|
// output pointer parameter |
| 211 |
|
// e.g. void GetPoint( _Out_ POINT* pPT ); |
| 212 |
|
#define _Out_ _Pre_cap_c_(1) _Pre_invalid_ |
| 213 |
|
#define _Out_opt_ _Pre_opt_cap_c_(1) _Pre_invalid_ |
| 214 |
|
|
| 215 |
|
// 'out' with buffer size |
| 216 |
|
// e.g. void GetIndeces( _Out_cap_(cIndeces) int* rgIndeces, size_t cIndices ); |
| 217 |
|
// buffer capacity is described by another parameter |
| 218 |
|
#define _Out_cap_(size) _Pre_cap_(size) _Pre_invalid_ |
| 219 |
|
#define _Out_opt_cap_(size) _Pre_opt_cap_(size) _Pre_invalid_ |
| 220 |
|
#define _Out_bytecap_(size) _Pre_bytecap_(size) _Pre_invalid_ |
| 221 |
|
#define _Out_opt_bytecap_(size) _Pre_opt_bytecap_(size) _Pre_invalid_ |
| 222 |
|
|
| 223 |
|
// buffer capacity is described by a constant expression |
| 224 |
|
#define _Out_cap_c_(size) _Pre_cap_c_(size) _Pre_invalid_ |
| 225 |
|
#define _Out_opt_cap_c_(size) _Pre_opt_cap_c_(size) _Pre_invalid_ |
| 226 |
|
#define _Out_bytecap_c_(size) _Pre_bytecap_c_(size) _Pre_invalid_ |
| 227 |
|
#define _Out_opt_bytecap_c_(size) _Pre_opt_bytecap_c_(size) _Pre_invalid_ |
| 228 |
|
|
| 229 |
|
// buffer capacity is described by another parameter multiplied by a constant expression |
| 230 |
|
#define _Out_cap_m_(mult,size) _Pre_cap_m_(mult,size) _Pre_invalid_ |
| 231 |
|
#define _Out_opt_cap_m_(mult,size) _Pre_opt_cap_m_(mult,size) _Pre_invalid_ |
| 232 |
|
#define _Out_z_cap_m_(mult,size) _Pre_cap_m_(mult,size) _Pre_invalid_ _Post_z_ |
| 233 |
|
#define _Out_opt_z_cap_m_(mult,size) _Pre_opt_cap_m_(mult,size) _Pre_invalid_ _Post_z_ |
| 234 |
|
|
| 235 |
|
// buffer capacity is described by another pointer |
| 236 |
|
// e.g. void Foo( _Out_ptrdiff_cap_(pchMax) char* pch, const char* pchMax ) { while pch < pchMax ) pch++; } |
| 237 |
|
#define _Out_ptrdiff_cap_(size) _Pre_ptrdiff_cap_(size) _Pre_invalid_ |
| 238 |
|
#define _Out_opt_ptrdiff_cap_(size) _Pre_opt_ptrdiff_cap_(size) _Pre_invalid_ |
| 239 |
|
|
| 240 |
|
// buffer capacity is described by a complex expression |
| 241 |
|
#define _Out_cap_x_(size) _Pre_cap_x_(size) _Pre_invalid_ |
| 242 |
|
#define _Out_opt_cap_x_(size) _Pre_opt_cap_x_(size) _Pre_invalid_ |
| 243 |
|
#define _Out_bytecap_x_(size) _Pre_bytecap_x_(size) _Pre_invalid_ |
| 244 |
|
#define _Out_opt_bytecap_x_(size) _Pre_opt_bytecap_x_(size) _Pre_invalid_ |
| 245 |
|
|
| 246 |
|
// a zero terminated string is filled into a buffer of given capacity |
| 247 |
|
// e.g. void CopyStr( _In_z_ const char* szFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo ); |
| 248 |
|
// buffer capacity is described by another parameter |
| 249 |
|
#define _Out_z_cap_(size) _Pre_cap_(size) _Pre_invalid_ _Post_z_ |
| 250 |
|
#define _Out_opt_z_cap_(size) _Pre_opt_cap_(size) _Pre_invalid_ _Post_z_ |
| 251 |
|
#define _Out_z_bytecap_(size) _Pre_bytecap_(size) _Pre_invalid_ _Post_z_ |
| 252 |
|
#define _Out_opt_z_bytecap_(size) _Pre_opt_bytecap_(size) _Pre_invalid_ _Post_z_ |
| 253 |
|
|
| 254 |
|
// buffer capacity is described by a constant expression |
| 255 |
|
#define _Out_z_cap_c_(size) _Pre_cap_c_(size) _Pre_invalid_ _Post_z_ |
| 256 |
|
#define _Out_opt_z_cap_c_(size) _Pre_opt_cap_c_(size) _Pre_invalid_ _Post_z_ |
| 257 |
|
#define _Out_z_bytecap_c_(size) _Pre_bytecap_c_(size) _Pre_invalid_ _Post_z_ |
| 258 |
|
#define _Out_opt_z_bytecap_c_(size) _Pre_opt_bytecap_c_(size) _Pre_invalid_ _Post_z_ |
| 259 |
|
|
| 260 |
|
// buffer capacity is described by a complex expression |
| 261 |
|
#define _Out_z_cap_x_(size) _Pre_cap_x_(size) _Pre_invalid_ _Post_z_ |
| 262 |
|
#define _Out_opt_z_cap_x_(size) _Pre_opt_cap_x_(size) _Pre_invalid_ _Post_z_ |
| 263 |
|
#define _Out_z_bytecap_x_(size) _Pre_bytecap_x_(size) _Pre_invalid_ _Post_z_ |
| 264 |
|
#define _Out_opt_z_bytecap_x_(size) _Pre_opt_bytecap_x_(size) _Pre_invalid_ _Post_z_ |
| 265 |
|
|
| 266 |
|
// a zero terminated string is filled into a buffer of given capacity |
| 267 |
|
// 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 ); |
| 268 |
|
#define _Out_cap_post_count_(cap,count) _Pre_cap_(cap) _Pre_invalid_ _Post_count_(count) |
| 269 |
|
#define _Out_opt_cap_post_count_(cap,count) _Pre_opt_cap_(cap) _Pre_invalid_ _Post_count_(count) |
| 270 |
|
#define _Out_bytecap_post_bytecount_(cap,count) _Pre_bytecap_(cap) _Pre_invalid_ _Post_bytecount_(count) |
| 271 |
|
#define _Out_opt_bytecap_post_bytecount_(cap,count) _Pre_opt_bytecap_(cap) _Pre_invalid_ _Post_bytecount_(count) |
| 272 |
|
|
| 273 |
|
// a zero terminated string is filled into a buffer of given capacity |
| 274 |
|
// e.g. size_t CopyStr( _In_z_ const char* szFrom, _Out_z_cap_post_count_(cchTo,return+1) char* szTo, size_t cchTo ); |
| 275 |
|
#define _Out_z_cap_post_count_(cap,count) _Pre_cap_(cap) _Pre_invalid_ _Post_z_count_(count) |
| 276 |
|
#define _Out_opt_z_cap_post_count_(cap,count) _Pre_opt_cap_(cap) _Pre_invalid_ _Post_z_count_(count) |
| 277 |
|
#define _Out_z_bytecap_post_bytecount_(cap,count) _Pre_bytecap_(cap) _Pre_invalid_ _Post_z_bytecount_(count) |
| 278 |
|
#define _Out_opt_z_bytecap_post_bytecount_(cap,count) _Pre_opt_bytecap_(cap) _Pre_invalid_ _Post_z_bytecount_(count) |
| 279 |
|
|
| 280 |
|
// only use with dereferenced arguments e.g. '*pcch' |
| 281 |
|
#define _Out_capcount_(capcount) _Pre_cap_(capcount) _Pre_invalid_ _Post_count_(capcount) |
| 282 |
|
#define _Out_opt_capcount_(capcount) _Pre_opt_cap_(capcount) _Pre_invalid_ _Post_count_(capcount) |
| 283 |
|
#define _Out_bytecapcount_(capcount) _Pre_bytecap_(capcount) _Pre_invalid_ _Post_bytecount_(capcount) |
| 284 |
|
#define _Out_opt_bytecapcount_(capcount) _Pre_opt_bytecap_(capcount) _Pre_invalid_ _Post_bytecount_(capcount) |
| 285 |
|
|
| 286 |
|
#define _Out_capcount_x_(capcount) _Pre_cap_x_(capcount) _Pre_invalid_ _Post_count_x_(capcount) |
| 287 |
|
#define _Out_opt_capcount_x_(capcount) _Pre_opt_cap_x_(capcount) _Pre_invalid_ _Post_count_x_(capcount) |
| 288 |
|
#define _Out_bytecapcount_x_(capcount) _Pre_bytecap_x_(capcount) _Pre_invalid_ _Post_bytecount_x_(capcount) |
| 289 |
|
#define _Out_opt_bytecapcount_x_(capcount) _Pre_opt_bytecap_x_(capcount) _Pre_invalid_ _Post_bytecount_x_(capcount) |
| 290 |
|
|
| 291 |
|
// e.g. GetString( _Out_z_capcount_(*pLen+1) char* sz, size_t* pLen ); |
| 292 |
|
#define _Out_z_capcount_(capcount) _Pre_cap_(capcount) _Pre_invalid_ _Post_z_count_(capcount) |
| 293 |
|
#define _Out_opt_z_capcount_(capcount) _Pre_opt_cap_(capcount) _Pre_invalid_ _Post_z_count_(capcount) |
| 294 |
|
#define _Out_z_bytecapcount_(capcount) _Pre_bytecap_(capcount) _Pre_invalid_ _Post_z_bytecount_(capcount) |
| 295 |
|
#define _Out_opt_z_bytecapcount_(capcount) _Pre_opt_bytecap_(capcount) _Pre_invalid_ _Post_z_bytecount_(capcount) |
| 296 |
|
|
| 297 |
|
// inout parameters ---------------------------- |
| 298 |
|
|
| 299 |
|
// inout pointer parameter |
| 300 |
|
// e.g. void ModifyPoint( _Inout_ POINT* pPT ); |
| 301 |
|
#define _Inout_ _Prepost_valid_ |
| 302 |
|
#define _Inout_opt_ _Prepost_opt_valid_ |
| 303 |
|
|
| 304 |
|
// string buffers |
| 305 |
|
// e.g. void toupper( _Inout_z_ char* sz ); |
| 306 |
|
#define _Inout_z_ _Prepost_z_ |
| 307 |
|
#define _Inout_opt_z_ _Prepost_opt_z_ |
| 308 |
|
|
| 309 |
|
// 'inout' buffers with initialized elements before and after the call |
| 310 |
|
// e.g. void ModifyIndices( _Inout_count_(cIndices) int* rgIndeces, size_t cIndices ); |
| 311 |
|
#define _Inout_count_(size) _Prepost_count_(size) |
| 312 |
|
#define _Inout_opt_count_(size) _Prepost_opt_count_(size) |
| 313 |
|
#define _Inout_bytecount_(size) _Prepost_bytecount_(size) |
| 314 |
|
#define _Inout_opt_bytecount_(size) _Prepost_opt_bytecount_(size) |
| 315 |
|
|
| 316 |
|
#define _Inout_count_c_(size) _Prepost_count_c_(size) |
| 317 |
|
#define _Inout_opt_count_c_(size) _Prepost_opt_count_c_(size) |
| 318 |
|
#define _Inout_bytecount_c_(size) _Prepost_bytecount_c_(size) |
| 319 |
|
#define _Inout_opt_bytecount_c_(size) _Prepost_opt_bytecount_c_(size) |
| 320 |
|
|
| 321 |
|
// nullterminated 'inout' buffers with initialized elements before and after the call |
| 322 |
|
// e.g. void ModifyIndices( _Inout_count_(cIndices) int* rgIndeces, size_t cIndices ); |
| 323 |
|
#define _Inout_z_count_(size) _Prepost_z_ _Prepost_count_(size) |
| 324 |
|
#define _Inout_opt_z_count_(size) _Prepost_z_ _Prepost_opt_count_(size) |
| 325 |
|
#define _Inout_z_bytecount_(size) _Prepost_z_ _Prepost_bytecount_(size) |
| 326 |
|
#define _Inout_opt_z_bytecount_(size) _Prepost_z_ _Prepost_opt_bytecount_(size) |
| 327 |
|
|
| 328 |
|
#define _Inout_z_count_c_(size) _Prepost_z_ _Prepost_count_c_(size) |
| 329 |
|
#define _Inout_opt_z_count_c_(size) _Prepost_z_ _Prepost_opt_count_c_(size) |
| 330 |
|
#define _Inout_z_bytecount_c_(size) _Prepost_z_ _Prepost_bytecount_c_(size) |
| 331 |
|
#define _Inout_opt_z_bytecount_c_(size) _Prepost_z_ _Prepost_opt_bytecount_c_(size) |
| 332 |
|
|
| 333 |
|
#define _Inout_ptrdiff_count_(size) _Pre_ptrdiff_count_(size) |
| 334 |
|
#define _Inout_opt_ptrdiff_count_(size) _Pre_opt_ptrdiff_count_(size) |
| 335 |
|
|
| 336 |
|
#define _Inout_count_x_(size) _Prepost_count_x_(size) |
| 881 |
|
|
| 882 |
|
#define _Deref_prepost_cap_x_(size) _Deref_pre_cap_x_(size) _Deref_post_cap_x_(size) |
| 883 |
|
#define _Deref_prepost_opt_cap_x_(size) _Deref_pre_opt_cap_x_(size) _Deref_post_opt_cap_x_(size) |
| 884 |
|
#define _Deref_prepost_bytecap_x_(size) _Deref_pre_bytecap_x_(size) _Deref_post_bytecap_x_(size) |
| 885 |
|
#define _Deref_prepost_opt_bytecap_x_(size) _Deref_pre_opt_bytecap_x_(size) _Deref_post_opt_bytecap_x_(size) |
| 886 |
|
|
| 887 |
|
#define _Deref_prepost_z_cap_(size) _Deref_pre_z_cap_(size) _Deref_post_z_cap_(size) |
| 888 |
|
#define _Deref_prepost_opt_z_cap_(size) _Deref_pre_opt_z_cap_(size) _Deref_post_opt_z_cap_(size) |
| 889 |
|
#define _Deref_prepost_z_bytecap_(size) _Deref_pre_z_bytecap_(size) _Deref_post_z_bytecap_(size) |
| 890 |
|
#define _Deref_prepost_opt_z_bytecap_(size) _Deref_pre_opt_z_bytecap_(size) _Deref_post_opt_z_bytecap_(size) |
| 891 |
|
|
| 892 |
|
#define _Deref_prepost_valid_cap_(size) _Deref_pre_valid_cap_(size) _Deref_post_valid_cap_(size) |
| 893 |
|
#define _Deref_prepost_opt_valid_cap_(size) _Deref_pre_opt_valid_cap_(size) _Deref_post_opt_valid_cap_(size) |
| 894 |
|
#define _Deref_prepost_valid_bytecap_(size) _Deref_pre_valid_bytecap_(size) _Deref_post_valid_bytecap_(size) |
| 895 |
|
#define _Deref_prepost_opt_valid_bytecap_(size) _Deref_pre_opt_valid_bytecap_(size) _Deref_post_opt_valid_bytecap_(size) |
| 896 |
|
|
| 897 |
|
#define _Deref_prepost_valid_cap_x_(size) _Deref_pre_valid_cap_x_(size) _Deref_post_valid_cap_x_(size) |
| 898 |
|
#define _Deref_prepost_opt_valid_cap_x_(size) _Deref_pre_opt_valid_cap_x_(size) _Deref_post_opt_valid_cap_x_(size) |
| 899 |
|
#define _Deref_prepost_valid_bytecap_x_(size) _Deref_pre_valid_bytecap_x_(size) _Deref_post_valid_bytecap_x_(size) |
| 900 |
|
#define _Deref_prepost_opt_valid_bytecap_x_(size) _Deref_pre_opt_valid_bytecap_x_(size) _Deref_post_opt_valid_bytecap_x_(size) |
| 901 |
|
|
| 902 |
|
#define _Deref_prepost_count_(size) _Deref_pre_count_(size) _Deref_post_count_(size) |
| 903 |
|
#define _Deref_prepost_opt_count_(size) _Deref_pre_opt_count_(size) _Deref_post_opt_count_(size) |
| 904 |
|
#define _Deref_prepost_bytecount_(size) _Deref_pre_bytecount_(size) _Deref_post_bytecount_(size) |
| 905 |
|
#define _Deref_prepost_opt_bytecount_(size) _Deref_pre_opt_bytecount_(size) _Deref_post_opt_bytecount_(size) |
| 906 |
|
|
| 907 |
|
#define _Deref_prepost_count_x_(size) _Deref_pre_count_x_(size) _Deref_post_count_x_(size) |
| 908 |
|
#define _Deref_prepost_opt_count_x_(size) _Deref_pre_opt_count_x_(size) _Deref_post_opt_count_x_(size) |
| 909 |
|
#define _Deref_prepost_bytecount_x_(size) _Deref_pre_bytecount_x_(size) _Deref_post_bytecount_x_(size) |
| 910 |
|
#define _Deref_prepost_opt_bytecount_x_(size) _Deref_pre_opt_bytecount_x_(size) _Deref_post_opt_bytecount_x_(size) |
| 911 |
|
|
| 912 |
|
#define _Deref_prepost_valid_ _Deref_pre_valid_ _Deref_post_valid_ |
| 913 |
|
#define _Deref_prepost_opt_valid_ _Deref_pre_opt_valid_ _Deref_post_opt_valid_ |
| 914 |
|
|
| 915 |
|
// |
| 916 |
|
// _Deref_<miscellaneous> |
| 917 |
|
// |
| 918 |
|
// used with references to arrays |
| 919 |
|
|
| 920 |
|
#define _Deref_out_z_cap_c_(size) _Deref_pre_cap_c_(size) _Deref_pre_invalid_ _Deref_post_z_ |
| 921 |
|
#define _Deref_inout_z_cap_c_(size) _Deref_pre_z_cap_c_(size) _Deref_post_z_ |
| 922 |
|
#define _Deref_out_z_bytecap_c_(size) _Deref_pre_bytecap_c_(size) _Deref_pre_invalid_ _Deref_post_z_ |
| 923 |
|
#define _Deref_inout_z_bytecap_c_(size) _Deref_pre_z_bytecap_c_(size) _Deref_post_z_ |
| 924 |
|
#define _Deref_inout_z_ _Deref_prepost_z_ |
| 925 |
|
|
| 926 |
|
//============================================================================ |
| 927 |
|
// Implementation Layer: |
| 928 |
|
//============================================================================ |
| 929 |
|
|
| 930 |
|
#if _USE_ATTRIBUTES_FOR_SAL |
| 931 |
|
|
| 932 |
|
#include "codeanalysis\sourceannotations.h" |
| 933 |
|
|
| 934 |
|
#define _Check_return_impl_ [returnvalue:SA_Post(MustCheck=SA_Yes)] |
| 935 |
|
|
| 936 |
|
#define _Success_impl_(expr) [SA_Success(Condition=#expr)] |
| 937 |
|
|
| 938 |
|
#define _Printf_format_string_impl_ [SA_FormatString(Style="printf")] |
| 939 |
|
#define _Scanf_format_string_impl_ [SA_FormatString(Style="scanf")] |
| 940 |
|
#define _Scanf_s_format_string_impl_ [SA_FormatString(Style="scanf_s")] |
| 941 |
|
|
| 942 |
|
#define _In_bound_impl_ [SA_PreBound(Deref=0)] |
| 943 |
|
#define _Out_bound_impl_ [SA_PostBound(Deref=0)] |
| 944 |
|
#define _Ret_bound_impl_ [returnvalue:SA_PostBound(Deref=0)] |
| 945 |
|
#define _Deref_in_bound_impl_ [SA_PreBound(Deref=1)] |
| 946 |
|
#define _Deref_out_bound_impl_ [SA_PostBound(Deref=1)] |
| 947 |
|
#define _Deref_ret_bound_impl_ [returnvalue:SA_PostBound(Deref=1)] |
| 948 |
|
|
| 949 |
|
#define _In_range_impl_(min,max) [SA_PreRange(MinVal=#min,MaxVal=#max)] |
| 950 |
|
#define _Out_range_impl_(min,max) [SA_PostRange(MinVal=#min,MaxVal=#max)] |
| 951 |
|
#define _Ret_range_impl_(min,max) [returnvalue:SA_PostRange(MinVal=#min,MaxVal=#max)] |
| 952 |
|
#define _Deref_in_range_impl_(min,max) [SA_PreRange(Deref=1,MinVal=#min,MaxVal=#max)] |
| 953 |
|
#define _Deref_out_range_impl_(min,max) [SA_PostRange(Deref=1,MinVal=#min,MaxVal=#max)] |
| 954 |
|
#define _Deref_ret_range_impl_(min,max) [returnvalue:SA_PostRange(Deref=1,MinVal=#min,MaxVal=#max)] |
| 955 |
|
|
| 956 |
|
#define _$valid Valid=SA_Yes |
| 957 |
|
#define _$maybevalid Valid=SA_Maybe |
| 958 |
|
#define _$notvalid Valid=SA_No |
| 959 |
|
|
| 960 |
|
#define _$null Null=SA_Yes |
| 961 |
|
#define _$maybenull Null=SA_Maybe |
| 962 |
|
#define _$notnull Null=SA_No |
| 963 |
|
|
| 964 |
|
#define _$zterm NullTerminated=SA_Yes |
| 965 |
|
#define _$maybezterm NullTerminated=SA_Maybe |
| 966 |
|
#define _$notzterm NullTerminated=SA_No |
| 967 |
|
|
| 968 |
|
#define _$readaccess Access=SA_Read |
| 969 |
|
#define _$writeaccess Access=SA_Write |
| 970 |
|
|
| 971 |
|
#define _$cap(size) WritableElements=#size |
| 972 |
|
#define _$cap_c(size) WritableElementsConst=size |
| 973 |
|
#define _$cap_for(param) WritableElementsLength=#param |
| 974 |
|
#define _$cap_x(size) WritableElements="\n@"#size |
| 975 |
|
|
| 976 |
|
#define _$bytecap(size) WritableBytes=#size |
| 977 |
|
#define _$bytecap_c(size) WritableBytesConst=size |
| 978 |
|
#define _$bytecap_x(size) WritableBytes="\n@"#size |
| 979 |
|
|
| 980 |
|
#define _$mult(mult,size) ElementSizeConst=mult,_$cap(size) |
| 981 |
|
|
| 982 |
|
#define _$count(size) ValidElements=#size |
| 983 |
|
#define _$count_c(size) ValidElementsConst=size |
| 984 |
|
#define _$count_x(size) ValidElements="\n@"#size |
| 985 |
|
|
| 986 |
|
#define _$bytecount(size) ValidBytes=#size |
| 987 |
|
#define _$bytecount_c(size) ValidBytesConst=size |
| 988 |
|
#define _$bytecount_x(size) ValidBytes="\n@"#size |
| 989 |
|
|
| 990 |
|
#define _Pre1_impl_(p1) [SA_Pre(p1)] |
| 991 |
|
#define _Pre2_impl_(p1,p2) [SA_Pre(p1,p2)] |
| 992 |
|
#define _Pre3_impl_(p1,p2,p3) [SA_Pre(p1,p2,p3)] |
| 993 |
|
|
| 994 |
|
#define _Post1_impl_(p1) [SA_Post(p1)] |
| 995 |
|
#define _Post2_impl_(p1,p2) [SA_Post(p1,p2)] |
| 996 |
|
#define _Post3_impl_(p1,p2,p3) [SA_Post(p1,p2,p3)] |
| 997 |
|
|
| 998 |
|
#define _Ret1_impl_(p1) [returnvalue:SA_Post(p1)] |
| 999 |
|
#define _Ret2_impl_(p1,p2) [returnvalue:SA_Post(p1,p2)] |
| 1000 |
|
#define _Ret3_impl_(p1,p2,p3) [returnvalue:SA_Post(p1,p2,p3)] |
| 1001 |
|
|
| 1002 |
|
#define _Deref_pre1_impl_(p1) [SA_Pre(Deref=1,p1)] |
| 1003 |
|
#define _Deref_pre2_impl_(p1,p2) [SA_Pre(Deref=1,p1,p2)] |
| 1004 |
|
#define _Deref_pre3_impl_(p1,p2,p3) [SA_Pre(Deref=1,p1,p2,p3)] |
| 1005 |
|
|
| 1006 |
|
#define _Deref_post1_impl_(p1) [SA_Post(Deref=1,p1)] |
| 1007 |
|
#define _Deref_post2_impl_(p1,p2) [SA_Post(Deref=1,p1,p2)] |
| 1008 |
|
#define _Deref_post3_impl_(p1,p2,p3) [SA_Post(Deref=1,p1,p2,p3)] |
| 1009 |
|
|
| 1010 |
|
#define _Deref_ret1_impl_(p1) [returnvalue:SA_Post(Deref=1,p1)] |
| 1011 |
|
#define _Deref_ret2_impl_(p1,p2) [returnvalue:SA_Post(Deref=1,p1,p2)] |
| 1012 |
|
#define _Deref_ret3_impl_(p1,p2,p3) [returnvalue:SA_Post(Deref=1,p1,p2,p3)] |
| 1013 |
|
|
| 1014 |
|
#define _Deref2_pre1_impl_(p1) [SA_Pre(Deref=2,p1)] |
| 1015 |
|
#define _Deref2_post1_impl_(p1) [SA_Post(Deref=2,p1)] |
| 1016 |
|
#define _Deref2_ret1_impl_(p1) [returnvalue:SA_Post(Deref=2,p1)] |
| 1017 |
|
|
| 1018 |
|
#elif _USE_DECLSPECS_FOR_SAL |
| 1019 |
|
|
| 1020 |
|
#define _$SPECSTRIZE( x ) #x |
| 1021 |
|
|
| 1022 |
|
#define _Check_return_impl_ __declspec("SAL_checkReturn") |
| 1023 |
|
|
| 1024 |
|
#define _Success_impl_(expr) __declspec("SAL_success("_$SPECSTRIZE(expr)")") |
| 1025 |
|
|
| 1026 |
|
#define _Printf_format_string_impl_ |
| 1027 |
|
#define _Scanf_format_string_impl_ |
| 1028 |
|
#define _Scanf_s_format_string_impl_ |
| 1029 |
|
|
| 1030 |
|
#define _In_bound_impl_ _$pre _$bound |
| 1031 |
|
#define _Out_bound_impl_ _$post _$bound |
| 1032 |
|
#define _Ret_bound_impl_ _$post _$bound |
| 1033 |
|
#define _Deref_in_bound_impl_ _$derefpre _$bound |
| 1034 |
|
#define _Deref_out_bound_impl_ _$derefpost _$bound |
| 1035 |
|
#define _Deref_ret_bound_impl_ _$derefpost bound |
| 1036 |
|
|
| 1037 |
|
#define _In_range_impl_(min,max) _$pre _$range(min,max) |
| 1038 |
|
#define _Out_range_impl_(min,max) _$post _$range(min,max) |
| 1039 |
|
#define _Ret_range_impl_(min,max) _$post _$range(min,max) |
| 1040 |
|
#define _Deref_in_range_impl_(min,max) _$derefpre _$range(min,max) |
| 1041 |
|
#define _Deref_out_range_impl_(min,max) _$derefpost _$range(min,max) |
| 1042 |
|
#define _Deref_ret_range_impl_(min,max) _$derefpost _$range(min,max) |
| 1043 |
|
|
| 1044 |
|
#define _$valid __declspec("SAL_valid") |
| 1045 |
|
#define _$maybevalid __declspec("SAL_maybevalid") |
| 1046 |
|
#define _$notvalid __declspec("SAL_notvalid") |
| 1047 |
|
|
| 1048 |
|
#define _$null __declspec("SAL_null") |
| 1049 |
|
#define _$maybenull __declspec("SAL_maybenull") |
| 1050 |
|
#define _$notnull __declspec("SAL_notnull") |
| 1051 |
|
|
| 1052 |
|
#define _$zterm __declspec("SAL_readableTo(sentinel(0))") |
| 1053 |
|
#define _$maybezterm |
| 1054 |
|
#define _$notzterm |
| 1055 |
|
|
| 1056 |
|
#define _$readaccess __declspec("SAL_readonly") |
| 1057 |
|
#define _$writeaccess __declspec("SAL_notreadonly") |
| 1058 |
|
|
| 1059 |
|
#define _$cap(size) __declspec("SAL_writableTo(elementCount("_$SPECSTRIZE(size)"))") |
| 1060 |
|
#define _$cap_c(size) __declspec("SAL_writableTo(elementCount("_$SPECSTRIZE(size)"))") |
| 1061 |
|
#define _$cap_for(param) __declspec("SAL_writableTo(needsCountFor("_$SPECSTRIZE(param)"))") |
| 1062 |
|
#define _$cap_x(size) __declspec("SAL_writableTo(inexpressibleCount('"_$SPECSTRIZE(size)"'))") |
| 1063 |
|
|
| 1064 |
|
#define _$bytecap(size) __declspec("SAL_writableTo(byteCount("_$SPECSTRIZE(size)"))") |
| 1065 |
|
#define _$bytecap_c(size) __declspec("SAL_writableTo(byteCount("_$SPECSTRIZE(size)"))") |
| 1066 |
|
#define _$bytecap_x(size) __declspec("SAL_writableTo(inexpressibleCount('"_$SPECSTRIZE(size)"'))") |
| 1067 |
|
|
| 1068 |
|
#define _$mult(mult,size) __declspec("SAL_writableTo(inexpressibleCount("_$SPECSTRIZE(mult)"*"_$SPECSTRIZE(size)"))") |
| 1069 |
|
|
| 1070 |
|
#define _$count(size) __declspec("SAL_readableTo(elementCount("_$SPECSTRIZE(size)"))") |
| 1071 |
|
#define _$count_c(size) __declspec("SAL_readableTo(elementCount("_$SPECSTRIZE(size)"))") |
| 1072 |
|
#define _$count_x(size) __declspec("SAL_readableTo(inexpressibleCount('"_$SPECSTRIZE(size)"'))") |
| 1073 |
|
|
| 1074 |
|
#define _$bytecount(size) __declspec("SAL_readableTo(byteCount("_$SPECSTRIZE(size)"))") |
| 1075 |
|
#define _$bytecount_c(size) __declspec("SAL_readableTo(byteCount("_$SPECSTRIZE(size)"))") |
| 1076 |
|
#define _$bytecount_x(size) __declspec("SAL_readableTo(inexpressibleCount('"_$SPECSTRIZE(size)"'))") |
| 1077 |
|
|
| 1078 |
|
#define _$pre __declspec("SAL_pre") |
| 1079 |
|
#define _$post __declspec("SAL_post") |
| 1080 |
|
#define _$deref_pre __declspec("SAL_pre") __declspec("SAL_deref") |
| 1081 |
|
#define _$deref_post __declspec("SAL_post") __declspec("SAL_deref") |
| 1082 |
|
|
| 1083 |
|
#define _$bound __declspec("SAL_bound") |
| 1084 |
|
#define _$range(min,max) __declspec("SAL_range("_$SPECSTRIZE(min)","_$SPECSTRIZE(max)")") |
| 1085 |
|
|
| 1086 |
|
#define _Pre1_impl_(p1) _$pre p1 |
| 1087 |
|
#define _Pre2_impl_(p1,p2) _$pre p1 _$pre p2 |
| 1088 |
|
#define _Pre3_impl_(p1,p2,p3) _$pre p1 _$pre p2 _$pre p3 |
| 1089 |
|
|
| 1090 |
|
#define _Post1_impl_(p1) _$post p1 |
| 1091 |
|
#define _Post2_impl_(p1,p2) _$post p1 _$post p2 |
| 1092 |
|
#define _Post3_impl_(p1,p2,p3) _$post p1 _$post p2 _$post p3 |
| 1093 |
|
|
| 1094 |
|
#define _Ret1_impl_(p1) _$post p1 |
| 1095 |
|
#define _Ret2_impl_(p1,p2) _$post p1 _$post p2 |
| 1096 |
|
#define _Ret3_impl_(p1,p2,p3) _$post p1 _$post p2 _$post p3 |
| 1097 |
|
|
| 1098 |
|
#define _Deref_pre1_impl_(p1) _$deref_pre p1 |
| 1099 |
|
#define _Deref_pre2_impl_(p1,p2) _$deref_pre p1 _$deref_pre p2 |
| 1100 |
|
#define _Deref_pre3_impl_(p1,p2,p3) _$deref_pre p1 _$deref_pre p2 _$deref_pre p3 |
| 1101 |
|
|
| 1102 |
|
#define _Deref_post1_impl_(p1) _$deref_post p1 |
| 1103 |
|
#define _Deref_post2_impl_(p1,p2) _$deref_post p1 _$deref_post p2 |
| 1104 |
|
#define _Deref_post3_impl_(p1,p2,p3) _$deref_post p1 _$deref_post p2 _$deref_post p3 |
| 1105 |
|
|
| 1106 |
|
#define _Deref_ret1_impl_(p1) _$deref_post p1 |
| 1107 |
|
#define _Deref_ret2_impl_(p1,p2) _$deref_post p1 _$deref_post p2 |
| 1108 |
|
#define _Deref_ret3_impl_(p1,p2,p3) _$deref_post p1 _$deref_post p2 _$deref_post p3 |
| 1109 |
|
|
| 1110 |
|
#define _Deref2_pre1_impl_(p1) _$deref_pre __declspec("SAL_deref") p1 |
| 1111 |
|
#define _Deref2_post1_impl_(p1) _$deref_post __declspec("SAL_deref") p1 |
| 1112 |
|
#define _Deref2_ret1_impl_(p1) _$deref_post __declspec("SAL_deref") p1 |
| 1113 |
|
|
| 1114 |
|
#elif defined(_MSC_EXTENSIONS) && !defined( MIDL_PASS ) && !defined(__midl) && !defined(RC_INVOKED) && defined(_PFT_VER) && _MSC_VER >= 1400 |
| 1115 |
|
|
| 1116 |
|
// minimum attribute expansion for foreground build |
| 1117 |
|
|
| 1118 |
|
#pragma push_macro( "SA" ) |
| 1119 |
|
#pragma push_macro( "REPEATABLE" ) |
| 1120 |
|
|
| 1121 |
|
#ifdef __cplusplus |
| 1122 |
|
#define SA( id ) id |
| 1123 |
|
#define REPEATABLE [repeatable] |
| 1124 |
|
#else // !__cplusplus |
| 1125 |
|
#define SA( id ) SA_##id |
| 1126 |
|
#define REPEATABLE |
| 1127 |
|
#endif // !__cplusplus |
| 1128 |
|
|
| 1129 |
|
REPEATABLE |
| 1130 |
|
[source_annotation_attribute( SA( Parameter ) )] |
| 1131 |
|
struct _$P |
| 1132 |
|
{ |
| 1133 |
|
#ifdef __cplusplus |
| 1134 |
|
_$P(); |
| 1135 |
|
#endif |
| 1136 |
|
int _$d; |
| 1137 |
|
}; |
| 1138 |
|
typedef struct _$P _$P; |
| 1139 |
|
|
| 1140 |
|
REPEATABLE |
| 1141 |
|
[source_annotation_attribute( SA( ReturnValue ) )] |
| 1142 |
|
struct _$R |
| 1143 |
|
{ |
| 1144 |
|
#ifdef __cplusplus |
| 1145 |
|
_$R(); |
| 1146 |
|
#endif |
| 1147 |
|
int _$d; |
| 1148 |
|
}; |
| 1149 |
|
typedef struct _$R _$R; |
| 1150 |
|
|
| 1151 |
|
[source_annotation_attribute( SA( Method ) )] |
| 1152 |
|
struct _$M |
| 1153 |
|
{ |
| 1154 |
|
#ifdef __cplusplus |
| 1155 |
|
_$M(); |
| 1156 |
|
#endif |
| 1157 |
|
int _$d; |
| 1158 |
|
}; |
| 1159 |
|
typedef struct _$M _$M; |
| 1160 |
|
|
| 1161 |
|
#pragma pop_macro( "REPEATABLE" ) |
| 1162 |
|
#pragma pop_macro( "SA" ) |
| 1163 |
|
|
| 1164 |
|
#define _Check_return_impl_ [returnvalue:_$R(_$d=0)] |
| 1165 |
|
|
| 1166 |
|
#define _Success_impl_(expr) [_$M(_$d=0)] |
| 1167 |
|
|
| 1168 |
|
#define _Printf_format_string_impl_ [_$P(_$d=0)] |
| 1169 |
|
#define _Scanf_format_string_impl_ [_$P(_$d=0)] |
| 1170 |
|
#define _Scanf_s_format_string_impl_ [_$P(_$d=0)] |
| 1171 |
|
|
| 1172 |
|
#define _In_bound_impl_ [_$P(_$d=0)] |
| 1173 |
|
#define _Out_bound_impl_ [_$P(_$d=0)] |
| 1174 |
|
#define _Ret_bound_impl_ [returnvalue:_$R(_$d=0)] |
| 1175 |
|
#define _Deref_in_bound_impl_ [_$P(_$d=0)] |
| 1176 |
|
#define _Deref_out_bound_impl_ [_$P(_$d=0)] |
| 1177 |
|
#define _Deref_ret_bound_impl_ [returnvalue:_$R(_$d=0)] |
| 1178 |
|
|
| 1179 |
|
#define _In_range_impl_(min,max) [_$P(_$d=0)] |
| 1180 |
|
#define _Out_range_impl_(min,max) [_$P(_$d=0)] |
| 1181 |
|
#define _Ret_range_impl_(min,max) [returnvalue:_$R(_$d=0)] |
| 1182 |
|
#define _Deref_in_range_impl_(min,max) [_$P(_$d=0)] |
| 1183 |
|
#define _Deref_out_range_impl_(min,max) [_$P(_$d=0)] |
| 1184 |
|
#define _Deref_ret_range_impl_(min,max) [returnvalue:_$R(_$d=0)] |
| 1185 |
|
|
| 1186 |
|
#define _Pre1_impl_(p1) [_$P(_$d=0)] |
| 1187 |
|
#define _Pre2_impl_(p1,p2) [_$P(_$d=0)] |
| 1188 |
|
#define _Pre3_impl_(p1,p2,p3) [_$P(_$d=0)] |
| 1189 |
|
|
| 1190 |
|
#define _Post1_impl_(p1) [_$P(_$d=0)] |
| 1191 |
|
#define _Post2_impl_(p1,p2) [_$P(_$d=0)] |
| 1192 |
|
#define _Post3_impl_(p1,p2,p3) [_$P(_$d=0)] |
| 1193 |
|
|
| 1194 |
|
#define _Ret1_impl_(p1) [returnvalue:_$R(_$d=0)] |
| 1195 |
|
#define _Ret2_impl_(p1,p2) [returnvalue:_$R(_$d=0)] |
| 1196 |
|
#define _Ret3_impl_(p1,p2,p3) [returnvalue:_$R(_$d=0)] |
| 1197 |
|
|
| 1198 |
|
#define _Deref_pre1_impl_(p1) [_$P(_$d=0)] |
| 1199 |
|
#define _Deref_pre2_impl_(p1,p2) [_$P(_$d=0)] |
| 1200 |
|
#define _Deref_pre3_impl_(p1,p2,p3) [_$P(_$d=0)] |
| 1201 |
|
|
| 1202 |
|
#define _Deref_post1_impl_(p1) [_$P(_$d=0)] |
| 1203 |
|
#define _Deref_post2_impl_(p1,p2) [_$P(_$d=0)] |
| 1204 |
|
#define _Deref_post3_impl_(p1,p2,p3) [_$P(_$d=0)] |
| 1426 |
|
initialized) instances of that type as being NULL-terminated. |
| 1427 |
|
|
| 1428 |
|
__nullnullterminated p : |
| 1429 |
|
Pointer p is a buffer that may be read or written up to and including the first |
| 1430 |
|
sequence of two NULL characters or pointers. May be used on typedefs, which marks |
| 1431 |
|
valid instances of that type as being double-NULL terminated. |
| 1432 |
|
|
| 1433 |
|
__reserved v : |
| 1434 |
|
Value v must be 0/NULL, reserved for future use. |
| 1435 |
|
|
| 1436 |
|
__checkReturn v : |
| 1437 |
|
Return value v must not be ignored by callers of this function. |
| 1438 |
|
|
| 1439 |
|
__typefix(ctype) v : |
| 1440 |
|
Value v should be treated as an instance of ctype, rather than its declared type. |
| 1441 |
|
|
| 1442 |
|
__override f : |
| 1443 |
|
Specify C#-style 'override' behaviour for overriding virtual methods. |
| 1444 |
|
|
| 1445 |
|
__callback f : |
| 1446 |
|
Function f can be used as a function pointer. |
| 1447 |
|
|
| 1448 |
|
__format_string p : |
| 1449 |
|
Pointer p is a string that contains % markers in the style of printf. |
| 1450 |
|
|
| 1451 |
|
__blocksOn(resource) f : |
| 1452 |
|
Function f blocks on the resource 'resource'. |
| 1453 |
|
|
| 1454 |
|
__fallthrough : |
| 1455 |
|
Annotates switch statement labels where fall-through is desired, to distinguish |
| 1456 |
|
from forgotten break statements. |
| 1457 |
|
|
| 1458 |
|
------------------------------------------------------------------------------- |
| 1459 |
|
Advanced Annotation Examples |
| 1460 |
|
|
| 1461 |
|
__success(return == TRUE) LWSTDAPI_(BOOL) |
| 1462 |
|
PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) : |
| 1463 |
|
pszBuf is only guaranteed to be NULL-terminated when TRUE is returned. |
| 1464 |
|
|
| 1465 |
|
typedef __nullterminated WCHAR* LPWSTR : Initialized LPWSTRs are NULL-terminated strings. |
| 1466 |
|
|
| 1467 |
|
__out_ecount(cch) __typefix(LPWSTR) void *psz : psz is a buffer parameter which will be |
| 1468 |
|
a NULL-terminated WCHAR string at exit, and which initially contains cch WCHARs. |
| 1469 |
|
|
| 1470 |
|
------------------------------------------------------------------------------- |
| 1471 |
|
*/ |
| 1472 |
|
|
| 1473 |
|
#define __specstrings |
| 1474 |
|
|
| 1475 |
|
#ifdef __cplusplus |
| 1476 |
|
#ifndef __nothrow |
| 1477 |
|
# define __nothrow __declspec(nothrow) |
| 1478 |
|
#endif |
| 1479 |
|
extern "C" { |
| 1480 |
|
#else |
| 1481 |
|
#ifndef __nothrow |
| 1482 |
|
# define __nothrow |
| 1483 |
|
#endif |
| 1484 |
|
#endif /* #ifdef __cplusplus */ |
| 1485 |
|
|
| 1486 |
|
|
| 1487 |
|
/* |
| 1488 |
|
------------------------------------------------------------------------------- |
| 1489 |
|
Helper Macro Definitions |
| 1490 |
|
|
| 1491 |
|
These express behavior common to many of the high-level annotations. |
| 1492 |
|
DO NOT USE THESE IN YOUR CODE. |
| 1493 |
|
------------------------------------------------------------------------------- |
| 1494 |
|
*/ |
| 1495 |
|
|
| 1496 |
|
/* |
| 1497 |
|
The helper annotations are only understood by the compiler version used by various |
| 1498 |
|
defect detection tools. When the regular compiler is running, they are defined into |
| 1499 |
|
nothing, and do not affect the compiled code. |
| 1500 |
|
*/ |
| 1501 |
|
|
| 1502 |
|
#if !defined(__midl) && defined(_PREFAST_) |
| 1503 |
|
|
| 1504 |
|
/* |
| 1505 |
|
In the primitive __declspec("SAL_*") annotations "SAL" stands for Standard |
| 1506 |
|
Annotation Language. These __declspec("SAL_*") annotations are the |
| 1507 |
|
primitives the compiler understands and all high-level SpecString MACROs |
| 1508 |
|
will decompose into these primivates. |
| 1509 |
|
*/ |
| 1510 |
|
|
| 1511 |
|
#define SPECSTRINGIZE( x ) #x |
| 1512 |
|
|
| 1513 |
|
/* |
| 1514 |
|
__null p |
| 1515 |
|
__notnull p |
| 1516 |
|
__maybenull p |
| 1517 |
|
|
| 1518 |
|
Annotates a pointer p. States that pointer p is null. Commonly used |
| 1519 |
|
in the negated form __notnull or the possibly null form __maybenull. |
| 1520 |
|
*/ |
| 1521 |
|
|
| 1522 |
|
#define __null __declspec("SAL_null") |
| 1523 |
|
#define __notnull __declspec("SAL_notnull") |
| 1524 |
|
#define __maybenull __declspec("SAL_maybenull") |
| 1525 |
|
|
| 1526 |
|
/* |
| 1527 |
|
__readonly l |
| 1528 |
|
__notreadonly l |
| 1529 |
|
__mabyereadonly l |
| 1530 |
|
|
| 1531 |
|
Annotates a location l. States that location l is not modified after |
| 1532 |
|
this point. If the annotation is placed on the precondition state of |
| 1533 |
|
a function, the restriction only applies until the postcondition state |
| 1534 |
|
of the function. __maybereadonly states that the annotated location |
| 1535 |
|
may be modified, whereas __notreadonly states that a location must be |
| 1536 |
|
modified. |
| 1537 |
|
*/ |
| 1538 |
|
|
| 1539 |
|
#define __readonly __declspec("SAL_readonly") |
| 1540 |
|
#define __notreadonly __declspec("SAL_notreadonly") |
| 1541 |
|
#define __maybereadonly __declspec("SAL_maybereadonly") |
| 1542 |
|
|
| 1543 |
|
/* |
| 1544 |
|
__valid v |
| 1545 |
|
__notvalid v |
| 1546 |
|
__maybevalid v |
| 1547 |
|
|
| 1548 |
|
Annotates any value v. States that the value satisfies all properties of |
| 1549 |
|
valid values of its type. For example, for a string buffer, valid means |
| 1550 |
|
that the buffer pointer is either NULL or points to a NULL-terminated string. |
| 1551 |
|
*/ |
| 1552 |
|
|
| 1917 |
|
#define __deref_opt_out_ecount_opt(size) __deref_out_ecount_opt(size) __exceptthat __maybenull |
| 1918 |
|
#define __deref_opt_out_bcount_opt(size) __deref_out_bcount_opt(size) __exceptthat __maybenull |
| 1919 |
|
#define __deref_opt_out_ecount_part_opt(size,length) __deref_out_ecount_part_opt(size,length) __exceptthat __maybenull |
| 1920 |
|
#define __deref_opt_out_bcount_part_opt(size,length) __deref_out_bcount_part_opt(size,length) __exceptthat __maybenull |
| 1921 |
|
#define __deref_opt_out_ecount_full_opt(size) __deref_out_ecount_full_opt(size) __exceptthat __maybenull |
| 1922 |
|
#define __deref_opt_out_bcount_full_opt(size) __deref_out_bcount_full_opt(size) __exceptthat __maybenull |
| 1923 |
|
#define __deref_opt_out_z_opt __post __deref __valid __refparam __exceptthat __maybenull __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull __post __deref __nullterminated |
| 1924 |
|
#define __deref_opt_out_ecount_z_opt(size) __deref_opt_out_ecount_opt(size) __post __deref __nullterminated |
| 1925 |
|
#define __deref_opt_out_bcount_z_opt(size) __deref_opt_out_bcount_opt(size) __post __deref __nullterminated |
| 1926 |
|
#define __deref_opt_out_nz_opt __deref_opt_out_opt |
| 1927 |
|
#define __deref_opt_out_ecount_nz_opt(size) __deref_opt_out_ecount_opt(size) |
| 1928 |
|
#define __deref_opt_out_bcount_nz_opt(size) __deref_opt_out_bcount_opt(size) |
| 1929 |
|
#define __deref_opt_inout_opt __deref_inout_opt __exceptthat __maybenull |
| 1930 |
|
#define __deref_opt_inout_ecount_opt(size) __deref_inout_ecount_opt(size) __exceptthat __maybenull |
| 1931 |
|
#define __deref_opt_inout_bcount_opt(size) __deref_inout_bcount_opt(size) __exceptthat __maybenull |
| 1932 |
|
#define __deref_opt_inout_ecount_part_opt(size,length) __deref_inout_ecount_part_opt(size,length) __exceptthat __maybenull |
| 1933 |
|
#define __deref_opt_inout_bcount_part_opt(size,length) __deref_inout_bcount_part_opt(size,length) __exceptthat __maybenull |
| 1934 |
|
#define __deref_opt_inout_ecount_full_opt(size) __deref_inout_ecount_full_opt(size) __exceptthat __maybenull |
| 1935 |
|
#define __deref_opt_inout_bcount_full_opt(size) __deref_inout_bcount_full_opt(size) __exceptthat __maybenull |
| 1936 |
|
#define __deref_opt_inout_z_opt __deref_opt_inout_opt __pre __deref __nullterminated __post __deref __nullterminated |
| 1937 |
|
#define __deref_opt_inout_ecount_z_opt(size) __deref_opt_inout_ecount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated |
| 1938 |
|
#define __deref_opt_inout_bcount_z_opt(size) __deref_opt_inout_bcount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated |
| 1939 |
|
#define __deref_opt_inout_nz_opt __deref_opt_inout_opt |
| 1940 |
|
#define __deref_opt_inout_ecount_nz_opt(size) __deref_opt_inout_ecount_opt(size) |
| 1941 |
|
#define __deref_opt_inout_bcount_nz_opt(size) __deref_opt_inout_bcount_opt(size) |
| 1942 |
|
|
| 1943 |
|
/* |
| 1944 |
|
------------------------------------------------------------------------------- |
| 1945 |
|
Advanced Annotation Definitions |
| 1946 |
|
|
| 1947 |
|
Any of these may be used to directly annotate functions, and may be used in |
| 1948 |
|
combination with each other or with regular buffer macros. For an explanation |
| 1949 |
|
of each annotation, see the advanced annotations section. |
| 1950 |
|
------------------------------------------------------------------------------- |
| 1951 |
|
*/ |
| 1952 |
|
|
| 1953 |
|
#define __success(expr) __inner_success(expr) |
| 1954 |
|
#define __nullterminated __readableTo(sentinel(0)) |
| 1955 |
|
#define __nullnullterminated |
| 1956 |
|
#define __reserved __pre __null |
| 1957 |
|
#define __checkReturn __inner_checkReturn |
| 1958 |
|
#define __typefix(ctype) __inner_typefix(ctype) |
| 1959 |
|
#define __override __inner_override |
| 1960 |
|
#define __callback __inner_callback |
| 1961 |
|
#define __format_string |
| 1962 |
|
#define __blocksOn(resource) __inner_blocksOn(resource) |
| 1963 |
|
#define __control_entrypoint(category) __inner_control_entrypoint(category) |
| 1964 |
|
#define __data_entrypoint(category) __inner_data_entrypoint(category) |
| 1965 |
|
|
| 1966 |
|
#ifndef __fallthrough |
| 1967 |
|
__inner_fallthrough_dec |
| 1968 |
|
#define __fallthrough __inner_fallthrough |
| 1969 |
|
#endif |
| 1970 |
|
|
| 1971 |
|
#ifndef __analysis_assume |
| 1972 |
|
#ifdef _PREFAST_ |
| 1973 |
|
#define __analysis_assume(expr) __assume(expr) |
| 1974 |
|
#else |
| 1975 |
|
#define __analysis_assume(expr) |
| 1976 |
|
#endif |
| 1977 |
|
#endif |
| 1978 |
|
|
| 1979 |
|
#ifdef __cplusplus |
| 1980 |
|
} |
| 1981 |
|
#endif |
| 1982 |
|
|
| 1983 |
|
|
| 1984 |
|
|
|
|
|