|
|
|
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 |
|
|
|
|
|