ReactOS  0.4.15-dev-5615-gc3644fd
specstrings_strict.h
Go to the documentation of this file.
1 /*
2  * PROJECT: ReactOS PSDK
3  * LICENSE: MIT (https://spdx.org/licenses/MIT)
4  * PURPOSE: Documents all the macros approved for use in windows source
5  * COPYRIGHT: Microsoft Corporation.
6  * SOURCE: https://github.com/microsoft/ChakraCore/blob/master/pal/inc/rt/specstrings_strict.h
7  */
8 //
9 // Copyright (c) Microsoft. All rights reserved.
10 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
11 //
12 
13 /*************************************************************************
14 * This file documents all the macros approved for use in windows source
15 * code. It includes some experimental macros which should only be used by
16 * experts.
17 *
18 * DO NOT include this file directly. This file is include after
19 * specstrings.h. So we can undefine every possible old definition including
20 * private internal macros people should not be using, as well as macros from
21 * sal.h. Macros are redefined here in a way to cause syntax errors when used
22 * incorrectly during a normal build when specstrings.h is included and
23 * __SPECSTRINGS_STRICT_LEVEL is defined.
24 *
25 * There are several levels of strictness, each level includes the behavior of
26 * all previous levels.
27 *
28 * 0 - Disable strict checking
29 * 1 - Break on unapproved macros and misuse of statement
30 * macros such as __fallthrough (default)
31 * 2 - Deprecated some old macros that should not be used
32 * 3 - Use VS 2005 Source Annotation to make sure every macro
33 * is used in the right context. For example placing __in on a return
34 * parameter will result in an error.
35 *
36 
37 *
38 ************************************************************************/
39 #ifndef __SPECSTRINGS_STRICT_LEVEL
40 #define __SPECSTRINGS_STRICT_LEVEL 1
41 #endif
42 /************************************************************************
43 * Introduction
44 *
45 * specstrings.h provides a set of annotations to describe how a function uses
46 * its parameters - the assumptions it makes about them, and the guarantees it
47 * makes upon finishing.
48 *
49 * Annotations must be placed before a function parameter's type or its return
50 * type. There are two basic classes of common annotations buffer annotations
51 * and advanced annotations. Buffer annotations describe how functions use
52 * their pointer parameters, and advanced annotations either describe
53 * complex/unusual buffer behavior, or provide additional information about a
54 * parameter that is not otherwise expressible.
55 *
56 * Buffer Annotations
57 *
58 * The most important annotations in SpecStrings.h provide a consistent way to
59 * annotate buffer parameters or return values for a function. Each of these
60 * annotations describes a single buffer (which could be a string, a
61 * fixed-length or variable-length array, or just a pointer) that the function
62 * interacts with: where it is, how large it is, how much is initialized, and
63 * what the function does with it.
64 *
65 * The appropriate macro for a given buffer can be constructed using the table
66 * below. Just pick the appropriate values from each category, and combine
67 * them together with a leading underscore. Some combinations of values do not
68 * make sense as buffer annotations. Only meaningful annotations can be added
69 * to your code; for a list of these, see the buffer annotation definitions
70 * section.
71 *
72 * Only a single buffer annotation should be used for each parameter.
73 *
74 * |------------|------------|---------|--------|----------|---------------|
75 * | Level | Usage | Size | Output | Optional | Parameters |
76 * |------------|------------|---------|--------|----------|---------------|
77 * | <> | <> | <> | <> | <> | <> |
78 * | _deref | _in | _ecount | _full | _opt | (size) |
79 * | _deref_opt | _out | _bcount | _part | | (size,length) |
80 * | | _inout | | | | |
81 * | | | | | | |
82 * |------------|------------|---------|--------|----------|---------------|
83 *
84 * Note: "<>" represents the empty string.
85 *
86 * Level: Describes the buffer pointer's level of indirection from the
87 * parameter or return value 'p'.
88 *
89 * <> : p is the buffer pointer.
90 * _deref : *p is the buffer pointer. p must not be NULL.
91 * _deref_opt : *p may be the buffer pointer. p may be NULL, in which case the
92 * rest of the annotation is ignored.
93 *
94 * Usage: Describes how the function uses the buffer.
95 *
96 * <> : The buffer is not accessed. If used on the return value or with
97 * _deref, the function will provide the buffer, and it will be uninitialized
98 * at exit. Otherwise, the caller must provide the buffer. This should only
99 * be used for alloc and free functions.
100 *
101 * _in : The function will only read from the buffer. The caller must provide
102 * the buffer and initialize it.
103 *
104 * _out : The function will only write to the buffer. If used on the return
105 * value or with _deref, the function will provide the buffer and initialize
106 * it. Otherwise, the caller must provide the buffer, and the function will
107 * initialize it.
108 *
109 * _inout : The function may freely read from and write to the buffer. The
110 * caller must provide the buffer and initialize it. If used with _deref, the
111 * buffer may be reallocated by the function.
112 *
113 * Size: Describes the total size of the buffer. This may be less than the
114 * space actually allocated for the buffer, in which case it describes the
115 * accessible amount.
116 *
117 * <> : No buffer size is given. If the type specifies the buffer size (such
118 * as with LPSTR and LPWSTR), that amount is used. Otherwise, the buffer is
119 * one element long. Must be used with _in, _out, or _inout.
120 *
121 * _ecount : The buffer size is an explicit element count.
122 *
123 * _bcount : The buffer size is an explicit byte count.
124 *
125 * Output: Describes how much of the buffer will be initialized by the
126 * function. For _inout buffers, this also describes how much is initialized
127 * at entry. Omit this category for _in buffers; they must be fully
128 * initialized by the caller.
129 *
130 * <> : The type specifies how much is initialized. For instance, a function
131 * initializing an LPWSTR must NULL-terminate the string.
132 *
133 * _full : The function initializes the entire buffer.
134 *
135 * _part : The function initializes part of the buffer, and explicitly
136 * indicates how much.
137 *
138 * Optional: Describes if the buffer itself is optional.
139 *
140 * <> : The pointer to the buffer must not be NULL.
141 *
142 * _opt : The pointer to the buffer might be NULL. It will be checked before
143 * being dereferenced.
144 *
145 * Parameters: Gives explicit counts for the size and length of the buffer.
146 *
147 * <> : There is no explicit count. Use when neither _ecount nor _bcount is
148 * used.
149 *
150 * (size) : Only the buffer's total size is given. Use with _ecount or _bcount
151 * but not _part.
152 *
153 * (size,length) : The buffer's total size and initialized length are
154 * given. Use with _ecount_part and _bcount_part.
155 *
156 * ----------------------------------------------------------------------------
157 * Buffer Annotation Examples
158 *
159 * LWSTDAPI_(BOOL) StrToIntExA(
160 * LPCSTR pszString, // No annotation required, const implies __in.
161 * DWORD dwFlags,
162 * __out int *piRet // A pointer whose dereference will be filled in.
163 * );
164 *
165 * void MyPaintingFunction(
166 * __in HWND hwndControl, // An initialized read-only parameter.
167 * __in_opt HDC hdcOptional, // An initialized read-only parameter that
168 * // might be NULL.
169 * __inout IPropertyStore *ppsStore // An initialized parameter that
170 * // may be freely used and modified.
171 * );
172 *
173 * LWSTDAPI_(BOOL) PathCompactPathExA(
174 * __out_ecount(cchMax) LPSTR pszOut, // A string buffer with cch elements
175 * // that will be '\0' terminated
176 * // on exit.
177 * LPCSTR pszSrc, // No annotation required,
178 * // const implies __in.
179 * UINT cchMax,
180 * DWORD dwFlags
181 * );
182 *
183 * HRESULT SHLocalAllocBytes(
184 * size_t cb,
185 * __deref_bcount(cb) T **ppv // A pointer whose dereference will be set
186 * // to an uninitialized buffer with cb bytes.
187 * );
188 *
189 * __inout_bcount_full(cb) : A buffer with cb elements that is fully
190 * initialized at entry and exit, and may be written to by this function.
191 *
192 * __out_ecount_part(count, *countOut) : A buffer with count elements that
193 * will be partially initialized by this function. The function indicates how
194 * much it initialized by setting *countOut.
195 *
196 ************************************************************************/
197 
198 #if (_MSC_VER >= 1400) && !defined(__midl) && !defined(_PREFAST_) && (__SPECSTRINGS_STRICT_LEVEL > 0)
199 #pragma once
200 #include <specstrings_undef.h>
201 #define __ecount(size) _SAL_VERSION_CHECK(__ecount)
202 #define __bcount(size) _SAL_VERSION_CHECK(__bcount)
203 #define __xcount(size) _SAL_VERSION_CHECK(__xcount)
204 #define __in _SAL_VERSION_CHECK(__in)
205 #define __in_ecount(size) _SAL_VERSION_CHECK(__in_ecount)
206 #define __in_bcount(size) _SAL_VERSION_CHECK(__in_bcount)
207 #define __in_xcount(size) _SAL_VERSION_CHECK(__in_xcount)
208 #define __in_z _SAL_VERSION_CHECK(__in_z)
209 #define __in_ecount_z(size) _SAL_VERSION_CHECK(__in_ecount_z)
210 #define __in_bcount_z(size) _SAL_VERSION_CHECK(__in_bcount_z)
211 #define __out _SAL_VERSION_CHECK(__out)
212 #define __out_ecount(size) _SAL_VERSION_CHECK(__out_ecount)
213 #define __out_bcount(size) _SAL_VERSION_CHECK(__out_bcount)
214 #define __out_xcount(size) _SAL_VERSION_CHECK(__out_xcount)
215 #define __out_ecount_part(size,len) _SAL_VERSION_CHECK(__out_ecount_part)
216 #define __out_bcount_part(size,len) _SAL_VERSION_CHECK(__out_bcount_part)
217 #define __out_xcount_part(size,len) _SAL_VERSION_CHECK(__out_xcount_part)
218 #define __out_ecount_full(size) _SAL_VERSION_CHECK(__out_ecount_full)
219 #define __out_bcount_full(size) _SAL_VERSION_CHECK(__out_bcount_full)
220 #define __out_xcount_full(size) _SAL_VERSION_CHECK(__out_xcount_full)
221 #define __out_z _SAL_VERSION_CHECK(__out_z)
222 #define __out_ecount_z(size) _SAL_VERSION_CHECK(__out_ecount_z)
223 #define __out_bcount_z(size) _SAL_VERSION_CHECK(__out_bcount_z)
224 #define __inout _SAL_VERSION_CHECK(__inout)
225 #define __inout_ecount(size) _SAL_VERSION_CHECK(__inout_ecount)
226 #define __inout_bcount(size) _SAL_VERSION_CHECK(__inout_bcount)
227 #define __inout_xcount(size) _SAL_VERSION_CHECK(__inout_xcount)
228 #define __inout_ecount_part(size,len) _SAL_VERSION_CHECK(__inout_ecount_part)
229 #define __inout_bcount_part(size,len) _SAL_VERSION_CHECK(__inout_bcount_part)
230 #define __inout_xcount_part(size,len) _SAL_VERSION_CHECK(__inout_xcount_part)
231 #define __inout_ecount_full(size) _SAL_VERSION_CHECK(__inout_ecount_full)
232 #define __inout_bcount_full(size) _SAL_VERSION_CHECK(__inout_bcount_full)
233 #define __inout_xcount_full(size) _SAL_VERSION_CHECK(__inout_xcount_full)
234 #define __inout_z __allowed(on_parameter)
235 #define __inout_ecount_z(size) __allowed(on_parameter)
236 #define __inout_bcount_z(size) __allowed(on_parameter)
237 #define __ecount_opt(size) __allowed(on_parameter)
238 #define __bcount_opt(size) __allowed(on_parameter)
239 #define __xcount_opt(size) __allowed(on_parameter)
240 #define __in_opt _SAL_VERSION_CHECK(__in_opt)
241 #define __in_ecount_opt(size) _SAL_VERSION_CHECK(__in_ecount_opt)
242 #define __in_bcount_opt(size) _SAL_VERSION_CHECK(__in_bcount_opt)
243 #define __in_z_opt __allowed(on_parameter)
244 #define __in_ecount_z_opt(size) __allowed(on_parameter)
245 #define __in_bcount_z_opt(size) __allowed(on_parameter)
246 #define __in_xcount_opt(size) __allowed(on_parameter)
247 #define __out_opt _SAL_VERSION_CHECK(__out_opt)
248 #define __out_ecount_opt(size) _SAL_VERSION_CHECK(__out_ecount_opt)
249 #define __out_bcount_opt(size) _SAL_VERSION_CHECK(__out_bcount_opt)
250 #define __out_xcount_opt(size) __allowed(on_parameter)
251 #define __out_ecount_part_opt(size,len) __allowed(on_parameter)
252 #define __out_bcount_part_opt(size,len) __allowed(on_parameter)
253 #define __out_xcount_part_opt(size,len) __allowed(on_parameter)
254 #define __out_ecount_full_opt(size) __allowed(on_parameter)
255 #define __out_bcount_full_opt(size) __allowed(on_parameter)
256 #define __out_xcount_full_opt(size) __allowed(on_parameter)
257 #define __out_ecount_z_opt(size) __allowed(on_parameter)
258 #define __out_bcount_z_opt(size) __allowed(on_parameter)
259 #define __inout_opt _SAL_VERSION_CHECK(__inout_opt)
260 #define __inout_ecount_opt(size) _SAL_VERSION_CHECK(__inout_ecount_opt)
261 #define __inout_bcount_opt(size) _SAL_VERSION_CHECK(__inout_bcount_opt)
262 #define __inout_xcount_opt(size) _SAL_VERSION_CHECK(__inout_xcount_opt)
263 #define __inout_ecount_part_opt(size,len) _SAL_VERSION_CHECK(__inout_ecount_part_opt)
264 #define __inout_bcount_part_opt(size,len) _SAL_VERSION_CHECK(__inout_bcount_part_opt)
265 #define __inout_xcount_part_opt(size,len) _SAL_VERSION_CHECK(__inout_xcount_part_opt)
266 #define __inout_ecount_full_opt(size) _SAL_VERSION_CHECK(__inout_ecount_full_opt)
267 #define __inout_bcount_full_opt(size) _SAL_VERSION_CHECK(__inout_bcount_full_opt)
268 #define __inout_xcount_full_opt(size) _SAL_VERSION_CHECK(__inout_xcount_full_opt)
269 #define __inout_z_opt __allowed(on_parameter)
270 #define __inout_ecount_z_opt(size) __allowed(on_parameter)
271 #define __inout_ecount_z_opt(size) __allowed(on_parameter)
272 #define __inout_bcount_z_opt(size) __allowed(on_parameter)
273 #define __deref_ecount(size) __allowed(on_parameter)
274 #define __deref_bcount(size) __allowed(on_parameter)
275 #define __deref_xcount(size) __allowed(on_parameter)
276 #define __deref_in _SAL_VERSION_CHECK(__deref_in)
277 #define __deref_in_ecount(size) _SAL_VERSION_CHECK(__deref_in_ecount)
278 #define __deref_in_bcount(size) _SAL_VERSION_CHECK(__deref_in_bcount)
279 #define __deref_in_xcount(size) _SAL_VERSION_CHECK(__deref_in_xcount)
280 #define __deref_out _SAL_VERSION_CHECK(__deref_out)
281 #define __deref_out_ecount(size) _SAL_VERSION_CHECK(__deref_out_ecount)
282 #define __deref_out_bcount(size) _SAL_VERSION_CHECK(__deref_out_bcount)
283 #define __deref_out_xcount(size) _SAL_VERSION_CHECK(__deref_out_xcount)
284 #define __deref_out_ecount_part(size,len) _SAL_VERSION_CHECK(__deref_out_ecount_part)
285 #define __deref_out_bcount_part(size,len) _SAL_VERSION_CHECK(__deref_out_bcount_part)
286 #define __deref_out_xcount_part(size,len) _SAL_VERSION_CHECK(__deref_out_xcount_part)
287 #define __deref_out_ecount_full(size) _SAL_VERSION_CHECK(__deref_out_ecount_full)
288 #define __deref_out_bcount_full(size) _SAL_VERSION_CHECK(__deref_out_bcount_full)
289 #define __deref_out_xcount_full(size) _SAL_VERSION_CHECK(__deref_out_xcount_full)
290 #define __deref_out_z __allowed(on_parameter)
291 #define __deref_out_ecount_z(size) __allowed(on_parameter)
292 #define __deref_out_bcount_z(size) __allowed(on_parameter)
293 #define __deref_inout _SAL_VERSION_CHECK(__deref_inout)
294 #define __deref_inout_ecount(size) _SAL_VERSION_CHECK(__deref_inout_ecount)
295 #define __deref_inout_bcount(size) _SAL_VERSION_CHECK(__deref_inout_bcount)
296 #define __deref_inout_xcount(size) _SAL_VERSION_CHECK(__deref_inout_xcount)
297 #define __deref_inout_ecount_part(size,len) __allowed(on_parameter)
298 #define __deref_inout_bcount_part(size,len) __allowed(on_parameter)
299 #define __deref_inout_xcount_part(size,len) __allowed(on_parameter)
300 #define __deref_inout_ecount_full(size) __allowed(on_parameter)
301 #define __deref_inout_bcount_full(size) __allowed(on_parameter)
302 #define __deref_inout_xcount_full(size) __allowed(on_parameter)
303 #define __deref_inout_z __allowed(on_parameter)
304 #define __deref_inout_ecount_z(size) __allowed(on_parameter)
305 #define __deref_inout_bcount_z(size) __allowed(on_parameter)
306 #define __deref_ecount_opt(size) __allowed(on_parameter)
307 #define __deref_bcount_opt(size) __allowed(on_parameter)
308 #define __deref_xcount_opt(size) __allowed(on_parameter)
309 #define __deref_in_opt __allowed(on_parameter)
310 #define __deref_in_opt_out __allowed(on_parameter)
311 #define __deref_in_ecount_opt(size) __allowed(on_parameter)
312 #define __deref_in_bcount_opt(size) __allowed(on_parameter)
313 #define __deref_in_xcount_opt(size) __allowed(on_parameter)
314 #define __deref_out_opt _SAL_VERSION_CHECK(__deref_out_opt)
315 #define __deref_out_ecount_opt(size) _SAL_VERSION_CHECK(__deref_out_ecount_opt)
316 #define __deref_out_bcount_opt(size) _SAL_VERSION_CHECK(__deref_out_bcount_opt)
317 #define __deref_out_xcount_opt(size) _SAL_VERSION_CHECK(__deref_out_xcount_opt)
318 #define __deref_out_ecount_part_opt(size,len) _SAL_VERSION_CHECK(__deref_out_ecount_part_opt)
319 #define __deref_out_bcount_part_opt(size,len) _SAL_VERSION_CHECK(__deref_out_bcount_part_opt)
320 #define __deref_out_xcount_part_opt(size,len) _SAL_VERSION_CHECK(__deref_out_xcount_part_opt)
321 #define __deref_out_ecount_full_opt(size) _SAL_VERSION_CHECK(__deref_out_ecount_full_opt)
322 #define __deref_out_bcount_full_opt(size) _SAL_VERSION_CHECK(__deref_out_bcount_full_opt)
323 #define __deref_out_xcount_full_opt(size) _SAL_VERSION_CHECK(__deref_out_xcount_full_opt)
324 #define __deref_out_z_opt __allowed(on_parameter)
325 #define __deref_out_ecount_z_opt(size) __allowed(on_parameter)
326 #define __deref_out_bcount_z_opt(size) __allowed(on_parameter)
327 #define __deref_inout_opt __allowed(on_parameter)
328 #define __deref_inout_ecount_opt(size) __allowed(on_parameter)
329 #define __deref_inout_bcount_opt(size) __allowed(on_parameter)
330 #define __deref_inout_xcount_opt(size) __allowed(on_parameter)
331 #define __deref_inout_ecount_part_opt(size,len) __allowed(on_parameter)
332 #define __deref_inout_bcount_part_opt(size,len) __allowed(on_parameter)
333 #define __deref_inout_xcount_part_opt(size,len) __allowed(on_parameter)
334 #define __deref_inout_ecount_full_opt(size) __allowed(on_parameter)
335 #define __deref_inout_bcount_full_opt(size) __allowed(on_parameter)
336 #define __deref_inout_xcount_full_opt(size) __allowed(on_parameter)
337 #define __deref_inout_z_opt __allowed(on_parameter)
338 #define __deref_inout_ecount_z_opt(size) __allowed(on_parameter)
339 #define __deref_inout_bcount_z_opt(size) __allowed(on_parameter)
340 #define __deref_opt_ecount(size) __allowed(on_parameter)
341 #define __deref_opt_bcount(size) __allowed(on_parameter)
342 #define __deref_opt_xcount(size) __allowed(on_parameter)
343 #define __deref_opt_in __allowed(on_parameter)
344 #define __deref_opt_in_ecount(size) __allowed(on_parameter)
345 #define __deref_opt_in_bcount(size) __allowed(on_parameter)
346 #define __deref_opt_in_xcount(size) __allowed(on_parameter)
347 #define __deref_opt_out _SAL_VERSION_CHECK(__deref_opt_out)
348 #define __deref_opt_out_ecount(size) _SAL_VERSION_CHECK(__deref_opt_out_ecount)
349 #define __deref_opt_out_bcount(size) _SAL_VERSION_CHECK(__deref_opt_out_bcount)
350 #define __deref_opt_out_xcount(size) _SAL_VERSION_CHECK(__deref_opt_out_xcount)
351 #define __deref_opt_out_ecount_part(size,len) __allowed(on_parameter)
352 #define __deref_opt_out_bcount_part(size,len) __allowed(on_parameter)
353 #define __deref_opt_out_xcount_part(size,len) __allowed(on_parameter)
354 #define __deref_opt_out_ecount_full(size) __allowed(on_parameter)
355 #define __deref_opt_out_bcount_full(size) __allowed(on_parameter)
356 #define __deref_opt_out_xcount_full(size) __allowed(on_parameter)
357 #define __deref_opt_inout __allowed(on_parameter)
358 #define __deref_opt_inout_ecount(size) __allowed(on_parameter)
359 #define __deref_opt_inout_bcount(size) __allowed(on_parameter)
360 #define __deref_opt_inout_xcount(size) __allowed(on_parameter)
361 #define __deref_opt_inout_ecount_part(size,len) __allowed(on_parameter)
362 #define __deref_opt_inout_bcount_part(size,len) __allowed(on_parameter)
363 #define __deref_opt_inout_xcount_part(size,len) __allowed(on_parameter)
364 #define __deref_opt_inout_ecount_full(size) __allowed(on_parameter)
365 #define __deref_opt_inout_bcount_full(size) __allowed(on_parameter)
366 #define __deref_opt_inout_xcount_full(size) __allowed(on_parameter)
367 #define __deref_opt_inout_z __allowed(on_parameter)
368 #define __deref_opt_inout_ecount_z(size) __allowed(on_parameter)
369 #define __deref_opt_inout_bcount_z(size) __allowed(on_parameter)
370 #define __deref_opt_ecount_opt(size) __allowed(on_parameter)
371 #define __deref_opt_bcount_opt(size) __allowed(on_parameter)
372 #define __deref_opt_xcount_opt(size) __allowed(on_parameter)
373 #define __deref_opt_in_opt __allowed(on_parameter)
374 #define __deref_opt_in_ecount_opt(size) __allowed(on_parameter)
375 #define __deref_opt_in_bcount_opt(size) __allowed(on_parameter)
376 #define __deref_opt_in_xcount_opt(size) __allowed(on_parameter)
377 #define __deref_opt_out_opt __allowed(on_parameter)
378 #define __deref_opt_out_ecount_opt(size) __allowed(on_parameter)
379 #define __deref_opt_out_bcount_opt(size) __allowed(on_parameter)
380 #define __deref_opt_out_xcount_opt(size) __allowed(on_parameter)
381 #define __deref_opt_out_ecount_part_opt(size,len) __allowed(on_parameter)
382 #define __deref_opt_out_bcount_part_opt(size,len) __allowed(on_parameter)
383 #define __deref_opt_out_xcount_part_opt(size,len) __allowed(on_parameter)
384 #define __deref_opt_out_ecount_full_opt(size) __allowed(on_parameter)
385 #define __deref_opt_out_bcount_full_opt(size) __allowed(on_parameter)
386 #define __deref_opt_out_xcount_full_opt(size) __allowed(on_parameter)
387 #define __deref_opt_out_z_opt __allowed(on_parameter)
388 #define __deref_opt_out_ecount_z_opt(size) __allowed(on_parameter)
389 #define __deref_opt_out_bcount_z_opt(size) __allowed(on_parameter)
390 #define __deref_opt_inout_opt __allowed(on_parameter)
391 #define __deref_opt_inout_ecount_opt(size) __allowed(on_parameter)
392 #define __deref_opt_inout_bcount_opt(size) __allowed(on_parameter)
393 #define __deref_opt_inout_xcount_opt(size) __allowed(on_parameter)
394 #define __deref_opt_inout_ecount_part_opt(size,len) __allowed(on_parameter)
395 #define __deref_opt_inout_bcount_part_opt(size,len) __allowed(on_parameter)
396 #define __deref_opt_inout_xcount_part_opt(size,len) __allowed(on_parameter)
397 #define __deref_opt_inout_ecount_full_opt(size) __allowed(on_parameter)
398 #define __deref_opt_inout_bcount_full_opt(size) __allowed(on_parameter)
399 #define __deref_opt_inout_xcount_full_opt(size) __allowed(on_parameter)
400 #define __deref_opt_inout_z_opt __allowed(on_parameter)
401 #define __deref_opt_inout_ecount_z_opt(size) __allowed(on_parameter)
402 #define __deref_opt_inout_bcount_z_opt(size) __allowed(on_parameter)
403 #define __deref_in_ecount_iterator(size,incr) __allowed(on_parameter)
404 #define __deref_out_ecount_iterator(size,incr) __allowed(on_parameter)
405 #define __deref_inout_ecount_iterator(size,incr) __allowed(on_parameter)
406 #define __deref_realloc_bcount(insize,outsize) __allowed(on_parameter)
407 
408 /************************************************************************
409 * SAL 2 _Ouptr_ family of annotations
410 ************************************************************************/
411 
412 #define _Outptr_ __allowed(on_parameter)
413 #define _Outptr_result_maybenull_ __allowed(on_parameter)
414 #define _Outptr_opt_ __allowed(on_parameter)
415 #define _Outptr_opt_result_maybenull_ __allowed(on_parameter)
416 #define _Outptr_result_z_ __allowed(on_parameter)
417 #define _Outptr_opt_result_z_ __allowed(on_parameter)
418 #define _Outptr_result_maybenull_z_ __allowed(on_parameter)
419 #define _Outptr_opt_result_maybenull_z_ __allowed(on_parameter)
420 #define _Outptr_result_nullonfailure_ __allowed(on_parameter)
421 #define _Outptr_opt_result_nullonfailure_ __allowed(on_parameter)
422 #define _COM_Outptr_ __allowed(on_parameter)
423 #define _COM_Outptr_result_maybenull_ __allowed(on_parameter)
424 #define _COM_Outptr_opt_ __allowed(on_parameter)
425 #define _COM_Outptr_opt_result_maybenull_ __allowed(on_parameter)
426 #define _Outptr_result_buffer_(size) __allowed(on_parameter)
427 #define _Outptr_opt_result_buffer_(size) __allowed(on_parameter)
428 #define _Outptr_result_buffer_to_(size, count) __allowed(on_parameter)
429 #define _Outptr_opt_result_buffer_to_(size, count) __allowed(on_parameter)
430 #define _Outptr_result_buffer_all_(size) __allowed(on_parameter)
431 #define _Outptr_opt_result_buffer_all_(size) __allowed(on_parameter)
432 #define _Outptr_result_buffer_maybenull_(size) __allowed(on_parameter)
433 #define _Outptr_opt_result_buffer_maybenull_(size) __allowed(on_parameter)
434 #define _Outptr_result_buffer_to_maybenull_(size, count) __allowed(on_parameter)
435 #define _Outptr_opt_result_buffer_to_maybenull_(size, count) __allowed(on_parameter)
436 #define _Outptr_result_buffer_all_maybenull_(size) __allowed(on_parameter)
437 #define _Outptr_opt_result_buffer_all_maybenull_(size) __allowed(on_parameter)
438 #define _Outptr_result_bytebuffer_(size) __allowed(on_parameter)
439 #define _Outptr_opt_result_bytebuffer_(size) __allowed(on_parameter)
440 #define _Outptr_result_bytebuffer_to_(size, count) __allowed(on_parameter)
441 #define _Outptr_opt_result_bytebuffer_to_(size, count) __allowed(on_parameter)
442 #define _Outptr_result_bytebuffer_all_(size) __allowed(on_parameter)
443 #define _Outptr_opt_result_bytebuffer_all_(size) __allowed(on_parameter)
444 #define _Outptr_result_bytebuffer_maybenull_(size) __allowed(on_parameter)
445 #define _Outptr_opt_result_bytebuffer_maybenull_(size) __allowed(on_parameter)
446 #define _Outptr_result_bytebuffer_to_maybenull_(size, count) __allowed(on_parameter)
447 #define _Outptr_opt_result_bytebuffer_to_maybenull_(size, count) __allowed(on_parameter)
448 #define _Outptr_result_bytebuffer_all_maybenull_(size) __allowed(on_parameter)
449 #define _Outptr_opt_result_bytebuffer_all_maybenull_(size) __allowed(on_parameter)
450 
451 /************************************************************************
452 * Orcas SAL
453 ************************************************************************/
454 #define _Deref_out_ _SAL_VERSION_CHECK(_Deref_out_)
455 #define _Deref_out_opt_ _SAL_VERSION_CHECK(_Deref_out_opt_)
456 #define _Deref_opt_out_ _SAL_VERSION_CHECK(_Deref_opt_out_)
457 #define _Deref_opt_out_opt_ _SAL_VERSION_CHECK(_Deref_opt_out_opt_)
458 #define _In_count_(size) _SAL_VERSION_CHECK(_In_count_)
459 #define _In_opt_count_(size) _SAL_VERSION_CHECK(_In_opt_count_)
460 #define _In_bytecount_(size) _SAL_VERSION_CHECK(_In_bytecount_)
461 #define _In_opt_bytecount_(size) _SAL_VERSION_CHECK(_In_opt_bytecount_)
462 #define _Out_cap_(size) _SAL_VERSION_CHECK(_Out_cap_)
463 #define _Out_opt_cap_(size) _SAL_VERSION_CHECK(_Out_opt_cap_)
464 #define _Out_bytecap_(size) _SAL_VERSION_CHECK(_Out_bytecap_)
465 #define _Out_opt_bytecap_(size) _SAL_VERSION_CHECK(_Out_opt_bytecap_)
466 #define _Deref_post_count_(size) _SAL_VERSION_CHECK(_Deref_post_count_)
467 #define _Deref_post_opt_count_(size) _SAL_VERSION_CHECK(_Deref_post_opt_count_)
468 #define _Deref_post_bytecount_(size) _SAL_VERSION_CHECK(_Deref_post_bytecount_)
469 #define _Deref_post_opt_bytecount_(size) _SAL_VERSION_CHECK(_Deref_post_opt_bytecount_)
470 #define _Deref_post_cap_(size) _SAL_VERSION_CHECK(_Deref_post_cap_)
471 #define _Deref_post_opt_cap_(size) _SAL_VERSION_CHECK(_Deref_post_opt_cap_)
472 #define _Deref_post_bytecap_(size) _SAL_VERSION_CHECK(_Deref_post_bytecap_)
473 #define _Deref_post_opt_bytecap_(size) _SAL_VERSION_CHECK(_Deref_post_opt_bytecap_)
474 
475 /************************************************************************
476 * Advanced Annotations
477 *
478 * Advanced annotations describe behavior that is not expressible with the
479 * regular buffer macros. These may be used either to annotate buffer
480 * parameters that involve complex or conditional behavior, or to enrich
481 * existing annotations with additional information.
482 *
483 * _At_(expr, annotes) : annotation list annotes applies to target 'expr'
484 *
485 * _When_(expr, annotes) : annotation list annotes applies when 'expr' is true
486 *
487 * __success(expr) T f() : <expr> indicates whether function f succeeded or
488 * not. If <expr> is true at exit, all the function's guarantees (as given
489 * by other annotations) must hold. If <expr> is false at exit, the caller
490 * should not expect any of the function's guarantees to hold. If not used,
491 * the function must always satisfy its guarantees. Added automatically to
492 * functions that indicate success in standard ways, such as by returning an
493 * HRESULT.
494 *
495 * __out_awcount(expr, size) T *p : Pointer p is a buffer whose size may be
496 * given in either bytes or elements. If <expr> is true, this acts like
497 * __out_bcount. If <expr> is false, this acts like __out_ecount. This
498 * should only be used to annotate old APIs.
499 *
500 * __in_awcount(expr, size) T* p : Pointer p is a buffer whose size may be given
501 * in either bytes or elements. If <expr> is true, this acts like
502 * __in_bcount. If <expr> is false, this acts like __in_ecount. This should
503 * only be used to annotate old APIs.
504 *
505 * __nullterminated T* p : Pointer p is a buffer that may be read or written
506 * up to and including the first '\0' character or pointer. May be used on
507 * typedefs, which marks valid (properly initialized) instances of that type
508 * as being null-terminated.
509 *
510 * __nullnullterminated T* p : Pointer p is a buffer that may be read or
511 * written up to and including the first sequence of two '\0' characters or
512 * pointers. May be used on typedefs, which marks valid instances of that
513 * type as being double-null terminated.
514 *
515 * __reserved T v : Value v must be 0/NULL, reserved for future use.
516 *
517 * __checkReturn T f(); : Return value of f must not be ignored by callers
518 * of this function.
519 *
520 * __typefix(ctype) T v : Value v should be treated as an instance of ctype,
521 * rather than its declared type when considering validity.
522 *
523 * __override T f(); : Specify C#-style 'override' behaviour for overriding
524 * virtual methods.
525 *
526 * __callback T f(); : Function f can be used as a function pointer.
527 *
528 * __format_string T p : Pointer p is a string that contains % markers in
529 * the style of printf.
530 *
531 * __blocksOn(resource) f(); : Function f blocks on the resource 'resource'.
532 *
533 * __fallthrough : Annotates switch statement labels where fall-through is
534 * desired, to distinguish from forgotten break statements.
535 *
536 * __range(low_bnd, up_bnd) int f(): The return from the function "f" must
537 * be in the inclusive numeric range [low_bnd, up_bnd].
538 *
539 * __in_range(low_bnd, up_bnd) int i : Precondition that integer i must be
540 * in the inclusive numeric range [low_bnd, up_bnd].
541 *
542 * __out_range(low_bnd, up_bnd) int i : Postcondition that integer i must be
543 * in the inclusive numeric range [low_bnd, up_bnd].
544 *
545 * __deref_in_range(low_bnd, up_bnd) int* pi : Precondition that integer *pi
546 * must be in the inclusive numeric range [low_bnd, up_bnd].
547 *
548 * __deref_out_range(low_bnd, up_bnd) int* pi : Postcondition that integer
549 * *pi must be in the inclusive numeric range [low_bnd, up_bnd].
550 *
551 * __deref_inout_range(low_bnd, up_bnd) int* pi : Invariant that the integer
552 * *pi must be in the inclusive numeric range [low_bnd, up_bnd].
553 *
554 * The first argument of a range macro may also be a C relational operator
555 * (<,>,!=, ==, <=, >=).
556 *
557 * __range(rel_op, j) int f(): Postcondition that "f() rel_op j" must be
558 * true. Note that j may be a expression known only at runtime.
559 *
560 * __in_range(rel_op, j) int i : Precondition that "i rel_op j" must be
561 * true. Note that j may be a expression known only at runtime.
562 *
563 * __out_range(rel_op, j) int i : Postcondition that integer "i rel_op j"
564 * must be true. Note that j may be a expression known only at runtime.
565 *
566 * __deref_in_range(rel_op, j) int *pi : Precondition that "*pi rel_op j"
567 * must be true. Note that j may be a expression known only at runtime.
568 *
569 * __deref_out_range(rel_op, j) int *pi : Postcondition that "*pi rel_op j"
570 * must be true. Note that j may be a expression known only at runtime.
571 *
572 * __deref_inout_range(rel_op, j) int *pi : Invariant that "*pi rel_op j"
573 * must be true. Note that j may be a expression known only at runtime.
574 *
575 * __range_max(a, b) int f(): Postcondition f acts as 'max', returns larger
576 * of a and b. Note that a and b may be expressions known only at runtime.
577 *
578 * __range_min(a, b) int f(): Postcondition f acts as 'min', returns smaller
579 * of a and b. Note that a and b may be expressions known only at runtime.
580 *
581 * __in_bound int i : Precondition that integer i must be bound, but the
582 * exact range can't be specified at compile time. __in_range should be
583 * used if the range can be explicitly stated.
584 *
585 * __out_bound int i : Postcondition that integer i must be bound, but the
586 * exact range can't be specified at compile time. __out_range should be
587 * used if the range can be explicitly stated.
588 *
589 * __deref_out_bound int pi : Postcondition that integer *pi must be bound,
590 * but the exact range can't be specified at compile time.
591 * __deref_out_range should be used if the range can be explicitly stated.
592 *
593 * __assume_bound(expr); : Assume that the expression is bound to some known
594 * range. This can be used to suppress integer overflow warnings on integral
595 * expressions that are known to be bound due to reasons not explicit in the
596 * code. Use as a statement in the body of a function.
597 *
598 * __analysis_assume_nulltermianted(expr); : Assume that the expression is
599 * a null terminated buffer. Use this to suppress tool noise specific to
600 * nulltermination warnings, and capture deeper invariants tools can not
601 * discover.
602 *
603 * __allocator void f(): Function allocates memory using an integral size
604 * argument
605 *
606 * void myfree(__deallocate(Mem) void *p) : Memory is freed, no longer usable
607 * upon return, and p may not be null.
608 *
609 * void myfree(__deallocate_opt(Mem) void *p) : Memory is freed, no longer
610 * usable upon return, and p may be null.
611 *
612 * void free(__post_invalid void* x): Mark memory as untouchable when
613 * function returns.
614 *
615 * ----------------------------------------------------------------------------
616 * Advanced Annotation Examples
617 *
618 * __success(return == TRUE) LWSTDAPI_(BOOL)
619 * PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath);
620 * // pszBuf is only guaranteed to be null-terminated when TRUE is returned.
621 *
622 * // Initialized LPWSTRs are null-terminated strings.
623 * typedef __nullterminated WCHAR* LPWSTR;
624 *
625 * __out_ecount(cch) __typefix(LPWSTR) void *psz;
626 * // psz is a buffer parameter which will be a null-terminated WCHAR string
627 * // at exit, and which initially contains cch WCHARs.
628 *
629 ************************************************************************/
630 #define _At_(expr, annotes) __allowed(on_parameter_or_return)
631 #define _When_(expr, annotes) __allowed(on_parameter_or_return)
632 #define __success(expr) _SAL_VERSION_CHECK(__success)
633 #define __out_awcount(expr,size) __allowed(on_parameter)
634 #define __in_awcount(expr,size) __allowed(on_parameter)
635 #define __nullterminated _SAL_VERSION_CHECK(__nullterminated)
636 #define __nullnullterminated _SAL_VERSION_CHECK(__nullnullterminated)
637 #define __reserved _SAL_VERSION_CHECK(__reserved)
638 #define __checkReturn _SAL_VERSION_CHECK(__checkReturn)
639 #define __typefix(ctype) __allowed(on_parameter_or_return)
640 #define __override __allowed(on_function)
641 #define __callback __allowed(on_function)
642 #define __format_string __allowed(on_parameter_or_return)
643 #define __blocksOn(resource) __allowed(on_function)
644 #define __fallthrough __allowed(as_statement)
645 #define __range(lb,ub) __allowed(on_return)
646 #define __in_range(lb,ub) _SAL_VERSION_CHECK(__in_range)
647 #define __out_range(lb,ub) _SAL_VERSION_CHECK(__out_range)
648 #define __deref_in_range(lb,ub) __allowed(on_parameter)
649 #define __deref_out_range(lb,ub) _SAL_VERSION_CHECK(__deref_out_range)
650 #define __deref_inout_range(lb,ub) __allowed(on_parameter)
651 #define __field_range(lb,ub) _SAL_VERSION_CHECK(__field_range)
652 #define __range_max(a,b) __allowed(on_return)
653 #define __range_min(a,b) __allowed(on_return)
654 #define __bound __allowed(on_return)
655 #define __in_bound __allowed(on_parameter)
656 #define __out_bound __allowed(on_parameter)
657 #define __deref_out_bound __allowed(on_parameter)
658 #define __assume_bound(i) __allowed(as_statement_with_arg(i))
659 #define __analysis_assume_nullterminated(x) \
660  __allowed(as_statement_with_arg(x))
661 #define __allocator __allowed(on_function)
662 #define __deallocate(kind) __allowed(on_parameter)
663 #define __deallocate_opt(kind) __allowed(on_parameter)
664 #define __post_invalid __allowed(on_parameter_or_return)
665 #define __post_nullnullterminated \
666  __allowed(on_parameter_or_return)
667 /***************************************************************************
668 * Expert Macros
669 ***************************************************************************/
670 #define __null __allowed(on_typedecl)
671 #define __notnull __allowed(on_typedecl)
672 #define __maybenull __allowed(on_typedecl)
673 #define __exceptthat __allowed(on_typedecl)
674 /***************************************************************************
675 * Macros to classify fields of structures.
676 * Structure Annotations
677 *
678 * The buffer annotations are a convenient way of describing
679 * relationships between buffers and their size on a function by
680 * function basis. Very often struct or class data members have similar
681 * invariants, which can be expressed directly on the type.
682 *
683 * Similar to our buffer annotations we can summarize all the various
684 * structure annotations by one choosing an element from each column of
685 * this table to build a composite annotation.
686 *
687 * +--------------------------------------------------+
688 * | Selector | Units | Size/Init | Optional |
689 * |----------+---------+------------------+----------|
690 * | __field | _ecount | (size) | empty |
691 * |----------+---------+------------------+----------|
692 * | __struct | _bcount | _full(size) | _opt |
693 * |----------+---------+------------------+----------|
694 * | | _xcount | _part(size,init) | |
695 * +--------------------------------------------------+
696 *
697 * Note that empty represents the empty string. Sometime arguments need
698 * to be "floated" to the left to give us a valid annotation name. For
699 * example the naive combination __field_ecount(size)_opt is actually
700 * written as __field_ecount_opt(size). Not all possible combinations
701 * are currently supported or sensible. See specstrings_strict.h for
702 * the currently supported set. Those that are supported are documented
703 * below.
704 *
705 *Summary of Elements
706 *
707 * Selector
708 *
709 * __field
710 * The annotation should only be placed in front
711 * of data members of structures and classes. The
712 * data members are pointers to a block of data.
713 * The annotations describe properties about the
714 * size of the block of data. This can be used for
715 *
716 * __struct
717 * The annotation should only be placed at the
718 * beginning of the definition of a structure or
719 * class. These annotations are used when a struct
720 * or class is used as a "header" that is
721 * allocated inline with a block of data and there
722 * is no apparent field that represents the tail
723 * end of the structure.
724 *
725 * Units
726 *
727 * _ecount
728 * All size and initialization values are in terms
729 * of elements of the appropriate type
730 *
731 * _bcount
732 * All size and initialization values are in terms
733 * of raw byte sizes.
734 *
735 * _xcount
736 * The size or initialization values cannot be
737 * properly expressed as a simple byte or element
738 * count, and instead a place holder is used to
739 * document the relationship.
740 *
741 * Size/Init
742 * All the size/init expressions can contain references to
743 * other fields in the struct or class.
744 *
745 * (size)
746 * The size of the buffer is determined by the
747 * expression size. Unless, the type of the buffer
748 * provides more information nothing is know about
749 * how much of this data is initialized. For
750 * example, if the data member happens to be a
751 * string type such as LPSTR. It is assumed that
752 * the data is initialized to the first '\0'.
753 *
754 * _full(size)
755 * The size of the buffer is determined by the
756 * expression size and all the data in the buffer
757 * is guaranteed to be initialized.
758 *
759 * _part(size,init)
760 * The size of the buffer is determined by the
761 * expression size and all the data in the buffer
762 * is guaranteed to be initialized up to init
763 * elements or bytes.
764 *
765 * Optional
766 *
767 * empty
768 * The pointer to the block of memory is never
769 * NULL
770 *
771 * _opt
772 * The pointer to the block of memory is may be
773 * NULL
774 *
775 *
776 * // Basic Usage of Struct Annotations
777 * #include <stdio.h>
778 * #include <stdlib.h>
779 * struct buf_s {
780 * int sz;
781 * __field_bcount_full(sz)
782 * char *buf;
783 * };
784 * void InitBuf(__out struct *buf_s b,int sz) {
785 * b->buf = calloc(sz,sizeof(char));
786 * b->sz = sz;
787 * }
788 * void WriteBuf(__in FILE *fp,__in struct *buf_s b) {
789 * fwrite(b->buf,b->sz,sizeof(char),fp);
790 * }
791 * void ReadBuf(__in FILE *fp,__inout struct *buf_s b) {
792 * fread(b->buf,b->sz,sizeof(char),fp);
793 * }
794 *
795 *
796 *
797 * // Inline Allocated Buffer
798 * struct buf_s {
799 * int sz;
800 * __field_bcount(sz)
801 * char buf[1];
802 * };
803 * void WriteBuf(__in FILE *fp,__in struct *buf_s b) {
804 * fwrite(&(b->buf),b->sz,sizeof(char),fp);
805 * }
806 * void ReadBuf(__in FILE *fp,__inout struct *buf_s b) {
807 * fread(&(b->buf),b->sz,sizeof(char),fp);
808 * }
809 *
810 *
811 *
812 * // Embedded Header Structure
813 * __struct_bcount(sz)
814 * struct buf_s {
815 * int sz;
816 * };
817 * void WriteBuf(__in FILE *fp,__in struct *buf_s b) {
818 * fwrite(&b,b->sz,sizeof(char),fp);
819 * }
820 * void ReadBuf(__in FILE *fp,__inout struct *buf_s b) {
821 * fread(&b,b->sz,sizeof(char),fp);
822 * }
823 *
824 *
825 ****************************************************************************/
826 #define __field_ecount(size) _SAL_VERSION_CHECK(__field_ecount)
827 #define __field_bcount(size) _SAL_VERSION_CHECK(__field_bcount)
828 #define __field_xcount(size) __allowed(on_field)
829 #define __field_ecount_opt(size) __allowed(on_field)
830 #define __field_bcount_opt(size) __allowed(on_field)
831 #define __field_xcount_opt(size) __allowed(on_field)
832 #define __field_ecount_part(size,init) __allowed(on_field)
833 #define __field_bcount_part(size,init) __allowed(on_field)
834 #define __field_xcount_part(size,init) __allowed(on_field)
835 #define __field_ecount_part_opt(size,init) __allowed(on_field)
836 #define __field_bcount_part_opt(size,init) __allowed(on_field)
837 #define __field_xcount_part_opt(size,init) __allowed(on_field)
838 #define __field_ecount_full(size) __allowed(on_field)
839 #define __field_bcount_full(size) __allowed(on_field)
840 #define __field_xcount_full(size) __allowed(on_field)
841 #define __field_ecount_full_opt(size) __allowed(on_field)
842 #define __field_bcount_full_opt(size) __allowed(on_field)
843 #define __field_xcount_full_opt(size) __allowed(on_field)
844 #define __field_nullterminated __allowed(on_field)
845 #define __struct_bcount(size) __allowed(on_struct)
846 #define __struct_xcount(size) __allowed(on_struct)
847 
848 /***************************************************************************
849 * Macros to classify the entrypoints and indicate their category.
850 *
851 * Pre-defined control point categories include: RPC, KERNEL, GDI.
852 *
853 * Pre-defined control point macros include:
854 * __rpc_entry, __kernel_entry, __gdi_entry.
855 ***************************************************************************/
856 #define __control_entrypoint(category) __allowed(on_function)
857 #define __rpc_entry __allowed(on_function)
858 #define __kernel_entry __allowed(on_function)
859 #define __gdi_entry __allowed(on_function)
860 
861 /***************************************************************************
862 * Macros to track untrusted data and their validation. The list of untrusted
863 * sources include:
864 *
865 * FILE - File reading stream or API
866 * NETWORK - Socket readers
867 * INTERNET - WinInet and WinHttp readers
868 * USER_REGISTRY - HKCU portions of the registry
869 * USER_MODE - Parameters to kernel entry points
870 * RPC - Parameters to RPC entry points
871 * DRIVER - Device driver
872 ***************************************************************************/
873 #define __in_data_source(src_sym) __allowed(on_parameter)
874 #define __out_data_source(src_sym) __allowed(on_parameter)
875 #define __field_data_source(src_sym) __allowed(on_field)
876 #define __this_out_data_source(src_syn) __allowed(on_function)
877 
878 /**************************************************************************
879 * Macros to tag file parsing code. Predefined formats include:
880 * PNG - Portable Network Graphics
881 * JPEG - Joint Photographic Experts Group
882 * BMP - Bitmap
883 * RC_BMP - Resource bitmap
884 * WMF - Windows Metafile
885 * EMF - Windows Enhanced Metafile
886 * GIF - Graphics Interchange Format
887 * MIME_TYPE - MIME type from header tokens
888 * MAIL_MONIKER - MAIL information refered by URL moniker
889 * HTML - HyperText Markup Language
890 * WMPHOTO - Windows media photo
891 * OE_VCARD - Outlook Express virtual card
892 * OE_CONTACT - Outlook Express contact
893 * MIDI - Musical Instrument Digital Interface
894 * LDIF - LDAP Data Interchange Format
895 * AVI - Audio Visual Interchange
896 * ACM - Audio Compression Manager
897 **************************************************************************/
898 #define __out_validated(filetype_sym) __allowed(on_parameter)
899 #define __this_out_validated(filetype_sym) __allowed(on_function)
900 #define __file_parser(filetype_sym) __allowed(on_function)
901 #define __file_parser_class(filetype_sym) __allowed(on_struct)
902 #define __file_parser_library(filetype_sym) __allowed(as_global_decl)
903 
904 /***************************************************************************
905 * Macros to track the code content in the file. The type of code
906 * contents currently tracked:
907 *
908 * NDIS_DRIVER - NDIS Device driver
909 ***************************************************************************/
910 #define __source_code_content(codetype_sym) __allowed(as_global_decl)
911 
912 /***************************************************************************
913 * Macros to track the code content in the class. The type of code
914 * contents currently tracked:
915 *
916 * DCOM - Class implementing DCOM
917 ***************************************************************************/
918 #define __class_code_content(codetype_sym) __allowed(on_struct)
919 
920 /*************************************************************************
921 * Macros to tag encoded function pointers
922 **************************************************************************/
923 #define __encoded_pointer
924 #define __encoded_array
925 #define __field_encoded_pointer __allowed(on_field)
926 #define __field_encoded_array __allowed(on_field)
927 
928 #define __transfer(formal) __allowed(on_parameter_or_return)
929 #define __assume_validated(exp) __allowed(as_statement_with_arg(exp))
930 
931 /*************************************************************************
932 * __analysis_assume(expr) : Expert macro use only when directed. Use this to
933 * tell static analysis tools like PREfix and PREfast about a non-coded
934 * assumption that you wish the tools to assume. The assumption will be
935 * understood by those tools. By default there is no dynamic checking or
936 * static checking of the assumption in any build.
937 *
938 * To obtain dynamic checking wrap this macro in your local version of a debug
939 * assert.
940 * Please do not put function calls in the expression because this is not
941 * supported by all tools:
942 * __analysis_assume(GetObject () != NULL); // DO NOT DO THIS
943 *
944 *************************************************************************/
945 #define __analysis_assume(expr) __allowed(as_statement_with_arg(expr))
946 #define __analysis_assert(expr) __allowed(as_statement_with_arg(expr))
947 
948 /*************************************************************************
949 * __analysis_hint(hint_sym) : Expert macro use only when
950 * directed. Use this to influence certain analysis heuristics
951 * used by the tools. These hints do not describe the semantics
952 * of functions but simply direct the tools to act in a certain
953 * way.
954 *
955 * Current hints that are supported are:
956 *
957 * INLINE - inline this function during analysis overrides any
958 * default heuristics
959 * NOINLINE - do not inline this function during analysis overrides
960 * and default heuristics
961 *************************************************************************/
962 #define __analysis_hint(hint) __allowed(on_function)
963 
964 /*************************************************************************
965 * Macros to encode abstract properties of values. Used by SALadt.h
966 *************************************************************************/
967 #define __type_has_adt_prop(adt,prop) __allowed(on_typdecl)
968 #define __out_has_adt_prop(adt,prop) __allowed(on_parameter)
969 #define __out_not_has_adt_prop(adt,prop) __allowed(on_parameter)
970 #define __out_transfer_adt_prop(arg) __allowed(on_parameter)
971 #define __out_has_type_adt_props(typ) __allowed(on_parameter)
972 
973 /*************************************************************************
974 * Macros used by Prefast for Drivers
975 *
976 * __possibly_notnullterminated :
977 *
978 * Used for return values of parameters or functions that do not
979 * guarantee nulltermination in all cases.
980 *
981 *************************************************************************/
982 #define __possibly_notnullterminated __allowed(on_parameter_or_return)
983 
984 /*************************************************************************
985 * Advanced macros
986 *
987 * __volatile
988 * The __volatile annotation identifies a global variable or
989 * structure field that:
990 * 1) is not declared volatile;
991 * 2) is accessed concurrently by multiple threads.
992 *
993 * The __deref_volatile annotation identifies a global variable
994 * or structure field that stores a pointer to some data that:
995 * 1) is not declared volatile;
996 * 2) is accessed concurrently by multiple threads.
997 *
998 * Prefast uses these annotations to find patterns of code that
999 * may result in unexpected re-fetching of the global variable
1000 * into a local variable.
1001 *
1002 * We also provide two complimentary annotations __nonvolatile
1003 * and __deref_nonvolatile that could be used to suppress Prefast
1004 *
1005 * re-fetching warnings on variables that are known either:
1006 * 1) not to be in danger of being re-fetched or,
1007 * 2) not to lead to incorrect results if they are re-fetched
1008 *
1009 *************************************************************************/
1010 #define __volatile __allowed(on_global_or_field)
1011 #define __deref_volatile __allowed(on_global_or_field)
1012 #define __nonvolatile __allowed(on_global_or_field)
1013 #define __deref_nonvolatile __allowed(on_global_or_field)
1014 
1015 /*************************************************************************
1016 * Macros deprecated with strict level greater then 1.
1017 **************************************************************************/
1018 #if (__SPECSTRINGS_STRICT_LEVEL > 1)
1019 /* Must come before macro defintions */
1020 #pragma deprecated(__in_nz)
1021 #pragma deprecated(__in_ecount_nz)
1022 #pragma deprecated(__in_bcount_nz)
1023 #pragma deprecated(__out_nz)
1024 #pragma deprecated(__out_nz_opt)
1025 #pragma deprecated(__out_ecount_nz)
1026 #pragma deprecated(__out_bcount_nz)
1027 #pragma deprecated(__inout_nz)
1028 #pragma deprecated(__inout_ecount_nz)
1029 #pragma deprecated(__inout_bcount_nz)
1030 #pragma deprecated(__in_nz_opt)
1031 #pragma deprecated(__in_ecount_nz_opt)
1032 #pragma deprecated(__in_bcount_nz_opt)
1033 #pragma deprecated(__out_ecount_nz_opt)
1034 #pragma deprecated(__out_bcount_nz_opt)
1035 #pragma deprecated(__inout_nz_opt)
1036 #pragma deprecated(__inout_ecount_nz_opt)
1037 #pragma deprecated(__inout_bcount_nz_opt)
1038 #pragma deprecated(__deref_out_nz)
1039 #pragma deprecated(__deref_out_ecount_nz)
1040 #pragma deprecated(__deref_out_bcount_nz)
1041 #pragma deprecated(__deref_inout_nz)
1042 #pragma deprecated(__deref_inout_ecount_nz)
1043 #pragma deprecated(__deref_inout_bcount_nz)
1044 #pragma deprecated(__deref_out_nz_opt)
1045 #pragma deprecated(__deref_out_ecount_nz_opt)
1046 #pragma deprecated(__deref_out_bcount_nz_opt)
1047 #pragma deprecated(__deref_inout_nz_opt)
1048 #pragma deprecated(__deref_inout_ecount_nz_opt)
1049 #pragma deprecated(__deref_inout_bcount_nz_opt)
1050 #pragma deprecated(__deref_opt_inout_nz)
1051 #pragma deprecated(__deref_opt_inout_ecount_nz)
1052 #pragma deprecated(__deref_opt_inout_bcount_nz)
1053 #pragma deprecated(__deref_opt_out_nz_opt)
1054 #pragma deprecated(__deref_opt_out_ecount_nz_opt)
1055 #pragma deprecated(__deref_opt_out_bcount_nz_opt)
1056 #pragma deprecated(__deref_opt_inout_nz_opt)
1057 #pragma deprecated(__deref_opt_inout_ecount_nz_opt)
1058 #pragma deprecated(__deref_opt_inout_bcount_nz_opt)
1059 #pragma deprecated(__deref)
1060 #pragma deprecated(__pre)
1061 #pragma deprecated(__post)
1062 #pragma deprecated(__readableTo)
1063 #pragma deprecated(__writableTo)
1064 #pragma deprecated(__maybevalid)
1065 #pragma deprecated(__data_entrypoint)
1066 #pragma deprecated(__inexpressible_readableTo)
1067 #pragma deprecated(__readonly)
1068 #pragma deprecated(__byte_writableTo)
1069 #pragma deprecated(__byte_readableTo)
1070 #pragma deprecated(__elem_readableTo)
1071 #pragma deprecated(__elem_writableTo)
1072 #pragma deprecated(__valid)
1073 #pragma deprecated(__notvalid)
1074 #pragma deprecated(__refparam)
1075 #pragma deprecated(__precond)
1076 #endif
1077 /* Define soon to be deprecated macros to nops. */
1078 #define __in_nz
1079 #define __in_ecount_nz(size)
1080 #define __in_bcount_nz(size)
1081 #define __out_nz
1082 #define __out_nz_opt
1083 #define __out_ecount_nz(size)
1084 #define __out_bcount_nz(size)
1085 #define __inout_nz
1086 #define __inout_ecount_nz(size)
1087 #define __inout_bcount_nz(size)
1088 #define __in_nz_opt
1089 #define __in_ecount_nz_opt(size)
1090 #define __in_bcount_nz_opt(size)
1091 #define __out_ecount_nz_opt(size)
1092 #define __out_bcount_nz_opt(size)
1093 #define __inout_nz_opt
1094 #define __inout_ecount_nz_opt(size)
1095 #define __inout_bcount_nz_opt(size)
1096 #define __deref_out_nz
1097 #define __deref_out_ecount_nz(size)
1098 #define __deref_out_bcount_nz(size)
1099 #define __deref_inout_nz
1100 #define __deref_inout_ecount_nz(size)
1101 #define __deref_inout_bcount_nz(size)
1102 #define __deref_out_nz_opt
1103 #define __deref_out_ecount_nz_opt(size)
1104 #define __deref_out_bcount_nz_opt(size)
1105 #define __deref_inout_nz_opt
1106 #define __deref_inout_ecount_nz_opt(size)
1107 #define __deref_inout_bcount_nz_opt(size)
1108 #define __deref_opt_inout_nz
1109 #define __deref_opt_inout_ecount_nz(size)
1110 #define __deref_opt_inout_bcount_nz(size)
1111 #define __deref_opt_out_nz_opt
1112 #define __deref_opt_out_ecount_nz_opt(size)
1113 #define __deref_opt_out_bcount_nz_opt(size)
1114 #define __deref_opt_inout_nz_opt
1115 #define __deref_opt_inout_ecount_nz_opt(size)
1116 #define __deref_opt_inout_bcount_nz_opt(size)
1117 #define __deref
1118 #define __pre
1119 #define __post
1120 #define __readableTo(count)
1121 #define __writableTo(count)
1122 #define __maybevalid
1123 #define __inexpressible_readableTo(string)
1124 #define __data_entrypoint(category)
1125 #define __readonly
1126 #define __byte_writableTo(count)
1127 #define __byte_readableTo(count)
1128 #define __elem_readableTo(count)
1129 #define __elem_writableTo(count)
1130 #define __valid
1131 #define __notvalid
1132 #define __refparam
1133 #define __precond(condition)
1134 
1135 /*************************************************************************
1136 * Definitions to force a compile error when macros are used improperly.
1137 * Relies on VS 2005 source annotations.
1138 *************************************************************************/
1139 #if !defined(_MSC_EXTENSIONS) && !defined(_PREFAST_) && !defined(OACR)
1140 #define __allowed(p) /* nothing */
1141 #else
1142 #define __allowed(p) __$allowed_##p
1143 #define __$allowed_as_global_decl /* empty */
1144 #define __$allowed_as_statement_with_arg(x) \
1145  __pragma(warning(push)) __pragma(warning(disable : 4548)) \
1146  do {__noop(x);} while((0,0) __pragma(warning(pop)) )
1147 #define __$allowed_as_statement __$allowed_as_statement_with_arg(1)
1148 
1149 /**************************************************************************
1150 * This should go away. It's only for __success which we should split into.
1151 * __success and __typdecl_sucess
1152 ***************************************************************************/
1153 #define __$allowed_on_function_or_typedecl /* empty */
1154 #if (__SPECSTRINGS_STRICT_LEVEL == 1) || (__SPECSTRINGS_STRICT_LEVEL == 2)
1155 #define __$allowed_on_typedecl /* empty */
1156 #define __$allowed_on_return /* empty */
1157 #define __$allowed_on_parameter /* empty */
1158 #define __$allowed_on_function /* empty */
1159 #define __$allowed_on_struct /* empty */
1160 #define __$allowed_on_field /* empty */
1161 #define __$allowed_on_parameter_or_return /* empty */
1162 #define __$allowed_on_global_or_field /* empty */
1163 #elif __SPECSTRINGS_STRICT_LEVEL == 3
1164 #define __$allowed_on_typedecl /* empty */
1165 /* Define dummy source attributes. Still needs more testing */
1166 #define __$allowed_on_return [returnvalue: OnReturnOnly]
1167 #define __$allowed_on_parameter [OnParameterOnly]
1168 #define __$allowed_on_function [method: OnFunctionOnly]
1169 #define __$allowed_on_struct [OnStructOnly]
1170 #define __$allowed_on_field [OnFieldOnly]
1171 #define __$allowed_on_parameter_or_return [OnParameterOrReturnOnly]
1172 #define __$allowed_on_global_or_field /* empty */
1173 #pragma push_macro( "DECL_SA" )
1174 #pragma push_macro( "SA" )
1175 #ifdef __cplusplus
1176 #define SA(x) x
1177 #define DECL_SA(name,loc) \
1178  [repeatable] \
1179  [source_annotation_attribute( loc )] \
1180  struct name##Attribute { name##Attribute(); const char* ignored; };
1181 #else
1182 #define SA(x) SA_##x
1183 #define DECL_SA(name,loc) \
1184  [source_annotation_attribute( loc )] \
1185  struct name { const char* ignored; };\
1186  typedef struct name name;
1187 #endif /* #endif __cplusplus */
1188 DECL_SA(OnParameterOnly,SA(Parameter));
1189 DECL_SA(OnReturnOnly,SA(ReturnValue));
1190 DECL_SA(OnFunctionOnly,SA(Method));
1191 DECL_SA(OnStructOnly,SA(Struct));
1192 DECL_SA(OnFieldOnly,SA(Field));
1193 DECL_SA(OnParameterOrReturnOnly,SA(Parameter) | SA(ReturnValue));
1194 #pragma pop_macro( "SA" )
1195 #pragma pop_macro( "DECL_SA" )
1196 #endif
1197 #endif
1198 #endif
specstrings_undef.h
Parameter
_In_ PVOID Parameter
Definition: ldrtypes.h:241
ReturnValue
UINT32 void void ** ReturnValue
Definition: acevents.h:214