ReactOS  0.4.15-dev-3017-g1d9542d
specstrings.h
Go to the documentation of this file.
1 /*
2  * PROJECT: ReactOS PSDK
3  * LICENSE: MIT (https://spdx.org/licenses/MIT)
4  * PURPOSE: Support for markers for documenting the semantics of APIs
5  * COPYRIGHT: Microsoft Corporation.
6  * SOURCE: https://github.com/microsoft/ChakraCore/blob/master/pal/inc/rt/specstrings.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 //
15 #ifndef SPECSTRINGS_H
16 #define SPECSTRINGS_H
17 
18 /***
19 *specstrings.h - support for markers for documenting the semantics of APIs
20 *
21 
22 *
23 * [Public]
24 ****/
25 
26 /*************************************************************************
27 * See specstrings_strict.h for documentation of all user visible macros.
28 *************************************************************************/
29 
30 #if _MSC_VER
31 #pragma once
32 #endif
33 
34 #if !defined(_SAL_VERSION_SAL2)
35 
36  #if defined(__BUILDMACHINE__) || defined(_USE_SAL2_ONLY)
37  #define _SAL_VERSION_SAL2(_A) SAL_2_Clean_Violation_using ## _A
38  #else
39  #define _SAL_VERSION_SAL2(_A)
40  #endif
41 
42  #ifdef _USE_SAL2_ONLY
43  #define _SAL2_STRICT
44  #define _SAL_VERSION_CHECK(_A) _SAL_VERSION_SAL2(_A)
45  #else
46  #define _SAL_VERSION_CHECK(_A)
47  #endif
48 
49  #ifndef SAL_VERSION_CHECK
50  #define SAL_VERSION_CHECK(_A) _SAL_VERSION_CHECK(_A)
51  #define SAL_VERSION_SAL2(_A) _SAL_VERSION_SAL2(_A)
52  #endif
53 
54 #endif
55 
56 #include <sal.h>
57 
58 #ifndef __SAL_H_FULL_VER
59 #define __SAL_H_FULL_VER 140050727
60 #endif
61 
62 #ifdef __cplusplus
63 extern "C" {
64 #endif
65 
66 /* version specific fixes to bring sal.h upto date */
67 #if __SAL_H_FULL_VER <= 140050727
68 
69 #if !defined(__midl) && defined(_PREFAST_) && _MSC_VER >= 1000 // [
70 
71 /* Missing from RTM sal.h */
72 #define __inner_bound _SA_annotes0(SAL_bound)
73 #define __inner_range(lb,ub) _SA_annotes2(SAL_range,lb,ub)
74 #define __inner_assume_bound_dec __inline __nothrow void __AssumeBoundInt(_Post_ __inner_bound int i) {i;}
75 #define __inner_assume_bound(i) __AssumeBoundInt(i);
76 #define __inner_allocator _SA_annotes0(SAL_allocator)
77 
78 #define __static_context(ctx, annotes) \
79  _SA_annotes1(SAL_context,ctx) _Group_(__nop_impl(annotes))
80 
81 #define __failure(x) __static_context(SAL_return_convention, \
82  _SA_annotes1(SAL_failure,x))
83 
84 __ANNOTATION(SAL_valueUndefined());
85 #define __valueUndefined _SA_annotes0(SAL_valueUndefined)
86 
87 enum __SAL_failureKind{__failureUnspecified = 0, __failureUndefined = 1};
88 
89 __ANNOTATION(SAL_failureDefault(enum __SAL_failureKind));
90 #define __failureDefault(kind) __static_context(SAL_return_convention, \
91  _SA_annotes1(SAL_failureDefault,kind))
92 
93 #else // ][
94 
95 #define __inner_bound
96 #define __inner_range(lb,ub)
97 #define __inner_assume_bound_dec
98 #define __inner_assume_bound(i)
99 #define __inner_allocator
100 
101 #define __static_context(ctx, annotes)
102 #define __failure(x)
103 #define __valueUndefined
104 #define __failureDefault(x)
105 
106 #endif // ]
107 
108 #define __xcount(size) __notnull __inexpressible_writableTo(size)
109 #define __in_xcount(size) __in _Pre_ __inexpressible_readableTo(size)
110 #define __out_xcount(size) __xcount(size) _Post_ __valid __refparam
111 #define __out_xcount_part(size,length) __out_xcount(size) _Post_ __inexpressible_readableTo(length)
112 #define __out_xcount_full(size) __out_xcount_part(size,size)
113 #define __inout_xcount(size) __out_xcount(size) _Pre_ __valid
114 #define __inout_xcount_part(size,length) __out_xcount_part(size,length) _Pre_ __valid _Pre_ __inexpressible_readableTo(length)
115 #define __inout_xcount_full(size) __inout_xcount_part(size,size)
116 #define __xcount_opt(size) __xcount(size) __exceptthat __maybenull
117 #define __in_xcount_opt(size) __in_xcount(size) __exceptthat __maybenull
118 #define __out_xcount_opt(size) __out_xcount(size) __exceptthat __maybenull
119 #define __out_xcount_part_opt(size,length) __out_xcount_part(size,length) __exceptthat __maybenull
120 #define __out_xcount_full_opt(size) __out_xcount_full(size) __exceptthat __maybenull
121 #define __inout_xcount_opt(size) __inout_xcount(size) __exceptthat __maybenull
122 #define __inout_xcount_part_opt(size,length) __inout_xcount_part(size,length) __exceptthat __maybenull
123 #define __inout_xcount_full_opt(size) __inout_xcount_full(size) __exceptthat __maybenull
124 #define __deref_xcount(size) __ecount(1) _Post_ __elem_readableTo(1) _Post_ __deref __notnull _Post_ __deref __inexpressible_writableTo(size)
125 #define __deref_in __in _Pre_ __deref __deref __readonly
126 #define __deref_in_ecount(size) __deref_in _Pre_ __deref __elem_readableTo(size)
127 #define __deref_in_bcount(size) __deref_in _Pre_ __deref __byte_readableTo(size)
128 #define __deref_in_xcount(size) __deref_in _Pre_ __deref __inexpressible_readableTo(size)
129 #define __deref_out_xcount(size) __deref_xcount(size) _Post_ __deref __valid __refparam
130 #define __deref_out_xcount_part(size,length) __deref_out_xcount(size) _Post_ __deref __inexpressible_readableTo(length)
131 #define __deref_out_xcount_full(size) __deref_out_xcount_part(size,size)
132 #define __deref_out_xcount(size) __deref_xcount(size) _Post_ __deref __valid __refparam
133 #define __inout_xcount_opt(size) __inout_xcount(size) __exceptthat __maybenull
134 #define __inout_xcount_part_opt(size,length) __inout_xcount_part(size,length) __exceptthat __maybenull
135 #define __inout_xcount_full_opt(size) __inout_xcount_full(size) __exceptthat __maybenull
136 #define __deref_xcount(size) __ecount(1) _Post_ __elem_readableTo(1) _Post_ __deref __notnull _Post_ __deref __inexpressible_writableTo(size)
137 #define __deref_in __in _Pre_ __deref __deref __readonly
138 #define __deref_in_ecount(size) __deref_in _Pre_ __deref __elem_readableTo(size)
139 #define __deref_in_bcount(size) __deref_in _Pre_ __deref __byte_readableTo(size)
140 #define __deref_in_xcount(size) __deref_in _Pre_ __deref __inexpressible_readableTo(size)
141 #define __deref_out_xcount(size) __deref_xcount(size) _Post_ __deref __valid __refparam
142 #define __deref_out_xcount_part(size,length) __deref_out_xcount(size) _Post_ __deref __inexpressible_readableTo(length)
143 #define __deref_out_xcount_full(size) __deref_out_xcount_part(size,size)
144 #define __deref_out_xcount(size) __deref_xcount(size) _Post_ __deref __valid __refparam
145 #define __deref_inout_xcount(size) __deref_inout _Pre_ __deref __inexpressible_writableTo(size) _Post_ __deref __inexpressible_writableTo(size)
146 #define __deref_inout_xcount_part(size,length) __deref_inout_xcount(size) _Pre_ __deref __inexpressible_readableTo(length) _Post_ __deref __inexpressible_readableTo(length)
147 #define __deref_inout_xcount_full(size) __deref_inout_xcount_part(size,size)
148 #define __deref_xcount_opt(size) __deref_xcount(size) _Post_ __deref __exceptthat __maybenull
149 #define __deref_in_opt __deref_in _Pre_ __deref __exceptthat __maybenull
150 #define __deref_in_opt_out __deref_inout _Pre_ __deref __exceptthat __maybenull _Post_ __deref __notnull
151 #define __deref_in_ecount_opt(size) __deref_in_ecount(size) _Pre_ __deref __exceptthat __maybenull
152 #define __deref_in_bcount_opt(size) __deref_in_bcount(size) _Pre_ __deref __exceptthat __maybenull
153 #define __deref_in_xcount_opt(size) __deref_in_xcount(size) _Pre_ __deref __exceptthat __maybenull
154 #define __deref_out_xcount_opt(size) __deref_out_xcount(size) _Post_ __deref __exceptthat __maybenull
155 #define __deref_out_xcount_part_opt(size,length) __deref_out_xcount_part(size,length) _Post_ __deref __exceptthat __maybenull
156 #define __deref_out_xcount_full_opt(size) __deref_out_xcount_full(size) _Post_ __deref __exceptthat __maybenull
157 #define __deref_inout_xcount_opt(size) __deref_inout_xcount(size) _Pre_ __deref __exceptthat __maybenull _Post_ __deref __exceptthat __maybenull
158 #define __deref_inout_xcount_part_opt(size,length) __deref_inout_xcount_part(size,length) _Pre_ __deref __exceptthat __maybenull _Post_ __deref __exceptthat __maybenull
159 #define __deref_inout_xcount_full_opt(size) __deref_inout_xcount_full(size) _Pre_ __deref __exceptthat __maybenull _Post_ __deref __exceptthat __maybenull
160 #define __deref_opt_xcount(size) __deref_xcount(size) __exceptthat __maybenull
161 #define __deref_opt_in __deref_in __exceptthat __maybenull
162 #define __deref_opt_in_ecount(size) __deref_in_ecount(size) __exceptthat __maybenull
163 #define __deref_opt_in_bcount(size) __deref_in_bcount(size) __exceptthat __maybenull
164 #define __deref_opt_in_xcount(size) __deref_in_xcount(size) __exceptthat __maybenull
165 #define __deref_opt_out_xcount(size) __deref_out_xcount(size) __exceptthat __maybenull
166 #define __deref_opt_out_xcount_part(size,length) __deref_out_xcount_part(size,length) __exceptthat __maybenull
167 #define __deref_opt_out_xcount_full(size) __deref_out_xcount_full(size) __exceptthat __maybenull
168 #define __deref_opt_inout_xcount(size) __deref_inout_xcount(size) __exceptthat __maybenull
169 #define __deref_opt_inout_xcount_part(size,length) __deref_inout_xcount_part(size,length) __exceptthat __maybenull
170 #define __deref_opt_inout_xcount_full(size) __deref_inout_xcount_full(size) __exceptthat __maybenull
171 #define __deref_opt_xcount_opt(size) __deref_xcount_opt(size) __exceptthat __maybenull
172 #define __deref_opt_in_opt __deref_in_opt __exceptthat __maybenull
173 #define __deref_opt_in_ecount_opt(size) __deref_in_ecount_opt(size) __exceptthat __maybenull
174 #define __deref_opt_in_bcount_opt(size) __deref_in_bcount_opt(size) __exceptthat __maybenull
175 #define __deref_opt_in_xcount_opt(size) __deref_in_xcount_opt(size) __exceptthat __maybenull
176 #define __deref_opt_out_xcount_opt(size) __deref_out_xcount_opt(size) __exceptthat __maybenull
177 #define __deref_opt_out_xcount_part_opt(size,length) __deref_out_xcount_part_opt(size,length) __exceptthat __maybenull
178 #define __deref_opt_out_xcount_full_opt(size) __deref_out_xcount_full_opt(size) __exceptthat __maybenull
179 #define __deref_opt_inout_xcount_opt(size) __deref_inout_xcount_opt(size) __exceptthat __maybenull
180 #define __deref_opt_inout_xcount_part_opt(size,length) __deref_inout_xcount_part_opt(size,length) __exceptthat __maybenull
181 #define __deref_opt_inout_xcount_full_opt(size) __deref_inout_xcount_full_opt(size) __exceptthat __maybenull
182 
183 #define __deref_in_ecount_iterator(size, incr) __inout _Pre_ __deref __elem_readableTo(size) __deref_out_range(==, _Old_(*_Curr_) + incr)
184 #define __deref_out_ecount_iterator(size, incr) __inout _Pre_ __deref __elem_writableTo(size) __deref_out_range(==, _Old_(*_Curr_) + incr)
185 #define __deref_inout_ecount_iterator(size, incr) __inout _Pre_ __deref __elem_readableTo(size) _Pre_ __deref __elem_writableTo(size) __deref_out_range(==, _Old_(*_Curr_) + incr)
186 
187 #define __post_bcount(size) _Post_ __byte_writableTo(size)
188 #define __post_ecount(size) _Post_ __elem_writableTo(size)
189 
190 #define __deref_realloc_bcount(insize, outsize) __inout _Pre_ __deref __byte_readableTo(insize) _Post_ __deref __byte_writableTo(outsize)
191 
192 /* __in_ecount_or_z(c) specifies semantics like strncmp, where a string
193  * parameter is either null terminated, or valid up to c elements.
194  */
195 #define __in_ecount_or_z(c) _When_(_String_length_(_Curr_) < (c), __in_z) \
196  _When_(_String_length_(_Curr_) >= (c), __in_ecount(c))
197 
198 
199 /* Provide default definition to be overridden when needed */
200 #define __post_nullnullterminated
201 
202 /* Must protect redfinitions of macros to workaround rc.exe issues. */
203 #ifndef RC_INVOKED
204 
205 #undef __nullnullterminated
206 #define __nullnullterminated __inexpressible_readableTo("string terminated by two nulls") __nullterminated
207 
208 #undef __post_nullnullterminated
209 #define __post_nullnullterminated _Post_ __inexpressible_readableTo("string terminated by two nulls") _Post_ __nullterminated
210 
211 #endif
212 #endif //__SAL_H_FULL_VER <= 140050727
213 
214 /************************************************************************
215  New extensions to sal.h follow here.
216 *************************************************************************/
217 
218 #if (_MSC_VER >= 1000) && !defined(__midl) && defined(_PREFAST_)
219 
220 #define __file_parser(typ) _SA_annotes2(SAL_file_parser,"function",typ)
221 #define __file_parser_class(typ) _SA_annotes2(SAL_file_parser,"class",typ)
222 #define __file_parser_library(typ) extern int _SA_annotes2(SAL_file_parser, "library", typ) __iSALFileParserLibrary##typ;
223 #define __source_code_content(typ) extern int _SA_annotes1(SAL_source_code_content, typ) __iSAL_Source_Code_Content##typ;
224 #define __class_code_content(typ) _SA_annotes1(SAL_class_code_content, typ)
225 #define __analysis_assert(e) __assume(e)
226 #define __analysis_hint(hint) _SA_annotes1(SAL_analysisHint, hint)
227 // For "breakpoint": doesn't return as far as analysis is concerned.
228 #define __analysis_noreturn __declspec(noreturn)
229 /* Internal defintions */
230 #define __inner_data_source(src_raw) _SA_annotes1(SAL_untrusted_data_source,src_raw)
231 #define __inner_this_data_source(src_raw) _SA_annotes1(SAL_untrusted_data_source_this,src_raw)
232 #define __inner_out_validated(typ_raw) _Post_ _SA_annotes1(SAL_validated,typ_raw)
233 #define __inner_this_out_validated(typ_raw) _SA_annotes1(SAL_validated_this,typ_raw)
234 #define __inner_assume_validated_dec __inline __nothrow void __AssumeValidated(__inner_out_validated("BY_DESIGN") const void *p) {p;}
235 #define __inner_assume_validated(p) __AssumeValidated(p)
236 #define __inner_transfer(formal) _SA_annotes1(SAL_transfer_adt_property_from,formal)
237 #define __inner_encoded _SA_annotes0(SAL_encoded)
238 
239 #if defined(_MSC_EXTENSIONS) || defined(_PREFAST_) || defined(OACR)
240 #define __inner_adt_prop(adt,prop) _SA_annotes2(SAL_adt, adt,prop)
241 #define __inner_adt_add_prop(adt,prop) _SA_annotes2(SAL_add_adt_property,adt,prop)
242 #define __inner_adt_remove_prop(adt,prop) _SA_annotes2(SAL_remove_adt_property,adt,prop)
243 #define __inner_adt_transfer_prop(arg) _SA_annotes1(SAL_transfer_adt_property_from,arg)
244 #define __inner_adt_type_props(typ) _SA_annotes1(SAL_post_type,typ)
245 #define __inner_volatile _SA_annotes0(SAL_volatile)
246 #define __inner_nonvolatile _SA_annotes0(SAL_nonvolatile)
247 #define __inner_possibly_notnullterminated _SA_annotes1(SAL_nullTerminated,__maybe)
248 #define __inner_analysis_assume_nullterminated_dec __inline __nothrow void __AnalysisAssumeNullterminated(_Post_ __nullterminated void *p) {*(char*)p=0;}
249 #define __inner_analysis_assume_nullterminated(x) __AnalysisAssumeNullterminated(x);
250 #endif
251 
252 #else
253 
254 #define __file_parser(typ)
255 #define __file_parser_class(typ)
256 #define __file_parser_library(typ)
257 #define __source_code_content(typ)
258 #define __class_code_content(typ)
259 #define __analysis_assert(e)
260 #define __analysis_hint(hint)
261 #ifndef __clang__
262 #define __analysis_noreturn
263 #else
264 #define __analysis_noreturn __attribute__((analyzer_noreturn))
265 #endif
266 /* Internal defintions */
267 #define __inner_data_source(src_raw)
268 #define __inner_this_data_source(src_raw)
269 #define __inner_out_validated(typ_raw)
270 #define __inner_this_out_validated(typ_raw)
271 #define __inner_assume_validated_dec
272 #define __inner_assume_validated(p)
273 #define __inner_transfer(formal)
274 #define __inner_encoded
275 #define __inner_adt_prop(adt,prop)
276 #define __inner_adt_add_prop(adt,prop)
277 #define __inner_adt_remove_prop(adt,prop)
278 #define __inner_adt_transfer_prop(arg)
279 #define __inner_adt_type_props(typ)
280 #define __inner_volatile
281 #define __inner_nonvolatile
282 #define __inner_possibly_notnullterminated
283 #define __inner_analysis_assume_nullterminated_dec
284 #define __inner_analysis_assume_nullterminated(x)
285 
286 #endif // #if (_MSC_VER >= 1000) && !defined(__midl) && defined(_PREFAST_)
287 
288 #define __field_ecount(size) __notnull __elem_writableTo(size)
289 #define __field_bcount(size) __notnull __byte_writableTo(size)
290 #define __field_xcount(size) __notnull __inexpressible_writableTo(size)
291 
292 #define __field_ecount_opt(size) __maybenull __elem_writableTo(size)
293 #define __field_bcount_opt(size) __maybenull __byte_writableTo(size)
294 #define __field_xcount_opt(size) __maybenull __inexpressible_writableTo(size)
295 
296 #define __field_ecount_part(size,init) __notnull __elem_writableTo(size) __elem_readableTo(init)
297 #define __field_bcount_part(size,init) __notnull __byte_writableTo(size) __byte_readableTo(init)
298 #define __field_xcount_part(size,init) __notnull __inexpressible_writableTo(size) __inexpressible_readableTo(init)
299 
300 #define __field_ecount_part_opt(size,init) __maybenull __elem_writableTo(size) __elem_readableTo(init)
301 #define __field_bcount_part_opt(size,init) __maybenull __byte_writableTo(size) __byte_readableTo(init)
302 #define __field_xcount_part_opt(size,init) __maybenull __inexpressible_writableTo(size) __inexpressible_readableTo(init)
303 
304 #define __field_ecount_full(size) __field_ecount_part(size,size)
305 #define __field_bcount_full(size) __field_bcount_part(size,size)
306 #define __field_xcount_full(size) __field_xcount_part(size,size)
307 
308 #define __field_ecount_full_opt(size) __field_ecount_part_opt(size,size)
309 #define __field_bcount_full_opt(size) __field_bcount_part_opt(size,size)
310 #define __field_xcount_full_opt(size) __field_xcount_part_opt(size,size)
311 
312 #define __field_nullterminated __nullterminated
313 
314 #define __struct_bcount(size) __byte_writableTo(size)
315 #define __struct_xcount(size) __inexpressible_writableTo(size)
316 
317 #define __out_awcount(expr,size) _Pre_ __notnull \
318  __byte_writableTo((expr) ? (size) : (size) * 2) \
319  _Post_ __valid __refparam
320 #define __in_awcount(expr,size) _Pre_ __valid \
321  _Pre_ _Notref_ __deref __readonly \
322  __byte_readableTo((expr) ? (size) : (size) * 2)
323 #define __post_invalid _Post_ __notvalid
324 /* integer related macros */
325 #define __allocator __inner_allocator
326 #ifndef PAL_STDCPP_COMPAT
327 #define __deallocate(kind) _Pre_ __notnull __post_invalid
328 #define __deallocate_opt(kind) _Pre_ __maybenull __post_invalid
329 #endif
330 #define __bound __inner_bound
331 #define __range(lb,ub) __inner_range(lb,ub)
332 #define __in_bound _Pre_ __inner_bound
333 #define __out_bound _Post_ __inner_bound
334 #define __deref_out_bound _Post_ __deref __inner_bound
335 #define __in_range(lb,ub) _Pre_ __inner_range(lb,ub)
336 #define __out_range(lb,ub) _Post_ __inner_range(lb,ub)
337 #define __deref_in_range(lb,ub) _Pre_ __deref __inner_range(lb,ub)
338 #define __deref_out_range(lb,ub) _Post_ __deref __inner_range(lb,ub)
339 #define __deref_inout_range(lb,ub) __deref_in_range(lb,ub) __deref_out_range(lb,ub)
340 #define __field_range(lb,ub) __range(lb,ub)
341 #define __field_data_source(src_sym) __inner_data_source(#src_sym)
342 
343 #define __range_max(a,b) __range(==, a > b ? a : b)
344 #define __range_min(a,b) __range(==, a < b ? a : b)
345 
346 
347 /* Penetration review macros */
348 #define __in_data_source(src_sym) _Pre_ __inner_data_source(#src_sym)
349 #define __out_data_source(src_sym) _Post_ __inner_data_source(#src_sym)
350 #define __out_validated(typ_sym) __inner_out_validated(#typ_sym)
351 #define __this_out_data_source(src_sym) __inner_this_data_source(#src_sym)
352 #define __this_out_validated(typ_sym) __inner_this_out_validated(#typ_sym)
353 #define __transfer(formal) _Post_ __inner_transfer(formal)
354 #define __rpc_entry __inner_control_entrypoint(RPC)
355 #define __kernel_entry __inner_control_entrypoint(UserToKernel)
356 #define __gdi_entry __inner_control_entrypoint(GDI)
357 #define __encoded_pointer __inner_encoded
358 #define __encoded_array __inner_encoded
359 #define __field_encoded_pointer __inner_encoded
360 #define __field_encoded_array __inner_encoded
361 #if defined(_MSC_EXTENSIONS) || defined(_PREFAST_) || defined(OACR)
362 #define __type_has_adt_prop(adt,prop) __inner_adt_prop(adt,prop)
363 #define __out_has_adt_prop(adt,prop) _Post_ __inner_adt_add_prop(adt,prop)
364 #define __out_not_has_adt_prop(adt,prop) _Post_ __inner_adt_remove_prop(adt,prop)
365 #define __out_transfer_adt_prop(arg) _Post_ __inner_adt_transfer_prop(arg)
366 #define __out_has_type_adt_props(typ) _Post_ __inner_adt_type_props(typ)
367 
368 /* useful PFD related macros */
369 #define __possibly_notnullterminated __inner_possibly_notnullterminated
370 
371 /* Windows Internal */
372 #define __volatile __inner_volatile
373 #define __nonvolatile __inner_nonvolatile
374 #else
375 #define __out_has_type_adt_props(typ) /* nothing */
376 #endif
377 #define __deref_volatile __deref __volatile
378 #define __deref_nonvolatile __deref __nonvolatile
379 
380 /* declare stub functions for macros */
384 #define __analysis_assume_nullterminated(x) __inner_analysis_assume_nullterminated(x)
385 #define __assume_validated(p) __inner_assume_validated(p)
386 #define __assume_bound(i) __inner_assume_bound(i)
387 
388 
389 /**************************************************************************
390 * SAL 2 extensions for Windows-specific APIs.
391 ***************************************************************************/
392 
393 // Annotation for parameters that are not used in any way by the function.
394 // Unlike _Reserved_, an _Unreferenced_parameter_ pointer need not be NULL.
395 #ifndef _Unreferenced_parameter_
396 #define _Unreferenced_parameter_ _Const_
397 #endif
398 
399 // Pointer parameters that are freed by the function, and thus the pointed-to
400 // memory should not be used after return.
401 #ifndef _Frees_ptr_
402 #define _Frees_ptr_ _Pre_notnull_ _Post_ptr_invalid_
403 #endif
404 #ifndef _Frees_ptr_opt_
405 #define _Frees_ptr_opt_ _Pre_maybenull_ _Post_ptr_invalid_
406 #endif
407 
408 // NLS APIs allow strings to be specified either by an element count or
409 // null termination. Unlike _In_reads_or_z_, this is not whichever comes
410 // first, but based on whether the size is negative or not.
411 #define _In_NLS_string_(size) _When_((size) < 0, _In_z_) \
412  _When_((size) >= 0, _In_reads_(size))
413 
414 
415 // Minifilter CompletionContext parameters on the pre-operation callback
416 // default to NULL. For return type FLT_PREOP_SUCCESS_WITH_CALLBACK or
417 // FLT_PREOP_SYNCHRONIZE, it may be set to NULL or a valid pointer. For all
418 // other returns, it must be NULL.
419 #define _Flt_CompletionContext_Outptr_ \
420  _Outptr_result_maybenull_ _Pre_valid_ \
421  _At_(*_Curr_, _Pre_null_ \
422  _When_(return != FLT_PREOP_SUCCESS_WITH_CALLBACK && return != FLT_PREOP_SYNCHRONIZE, _Post_null_))
423 
424 // Minifilter ConnectionCookie parameters on the port connect notify callback
425 // default to NULL. On successful return, it may be set to NULL or non-NULL,
426 // but it must be NULL on failure.
427 #define _Flt_ConnectionCookie_Outptr_ \
428  _Outptr_result_maybenull_ _Pre_valid_ \
429  _At_(*_Curr_, _Pre_null_ _On_failure_(_Post_null_))
430 
431 
432 //
433 // A common pattern is to pass an "_Inout_ PCHAR* ppBuf" of size "_Inout_ DWORD* pSize"
434 // to a function that writes to **pBuf, incrementing *ppBuf to point to one
435 // past the last written byte. Thus the length of the write is
436 // (*ppBuf - Old(*ppBuf)). The size of the remaining unwritten capacity
437 // is written to *pSize.
438 //
439 // This pattern is frequently used when progressively filling a
440 // large buffer in chunks
441 // (e.g. when reading from a network interface in a driver).
442 //
443 // It is expected that these supplementary annotations would be used inside an
444 // _At_, like so:
445 //
446 // _At_(*ppBuf, _Writes_and_advances_ptr_(*pBufSize))
447 // HRESULT WriteChunkOfData(_Inout_ PCHAR* ppBuf, _Inout_ DWORD* pBufSize);
448 //
449 #ifndef _Writes_and_advances_ptr_
450 #define _Writes_and_advances_ptr_(size) \
451  _At_((void*)_Curr_, _Inout_) \
452  _At_(_Curr_, \
453  _Pre_writable_size_(size) \
454  _Post_writable_size_(size) \
455  _Post_satisfies_(_Curr_ - _Old_(_Curr_) == size)) \
456  _At_(_Old_(_Curr_), \
457  _Post_readable_size_(_Old_(size) - size))
458 #endif
459 
460 #ifndef _Writes_bytes_and_advances_ptr_
461 #define _Writes_bytes_and_advances_ptr_(size) \
462  _At_((void*)_Curr_, _Inout_) \
463  _At_(_Curr_, \
464  _Pre_writable_byte_size_(size) \
465  _Post_writable_byte_size_(size) \
466  _Post_satisfies_(((char*)_Curr_) - ((void*)_Old_(_Curr_)) == size)) \
467  _At_(_Old_(_Curr_), \
468  _Post_readable_byte_size_(_Old_(size) - size))
469 #endif
470 
471 //
472 // Gets the current error code (as returned by GetLastError()), and stores
473 // in _Curr_ as a postcondition. This is currently approximated by assuming
474 // that GetLastError() always returns a failed error code. This is not a
475 // completely accurate approximation, but reasonable.
476 //
477 #define _Post_equals_last_error_ _Post_satisfies_(_Curr_ != 0)
478 
479 #ifdef __cplusplus
480 }
481 #endif
482 
483 #ifdef _PREFIX_
484 /**************************************************************************
485 * Defintion of __pfx_assume and __pfx_assert. Thse should be the only
486 * defintions of these functions.
487 ***************************************************************************/
488 #if __cplusplus
489 extern "C" void __pfx_assert(bool, const char *);
490 extern "C" void __pfx_assume(bool, const char *);
491 #else
492 void __pfx_assert(int, const char *);
493 void __pfx_assume(int, const char *);
494 #endif
495 /**************************************************************************
496 * Redefintion of __analysis_assume and __analysis_assert for PREFIX build
497 **************************************************************************/
498 #undef __analysis_assume
499 #undef __analysis_assert
500 #define __analysis_assume(e) (__pfx_assume(e,"pfx_assume"),__assume(e));
501 #define __analysis_assert(e) (__pfx_assert(e,"pfx_assert"),__assume(e));
502 #endif /* ifdef _PREFIX_ */
503 
504 /**************************************************************************
505 * This include should always be the last thing in this file.
506 * Must avoid redfinitions of macros to workaround rc.exe issues.
507 ***************************************************************************/
508 #if !(defined(RC_INVOKED) || defined(SORTPP_PASS))
509 #include <specstrings_strict.h>
510 #endif /* if !(defined(RC_INVOKED) || defined(SORTPP_PASS)) */
511 
512 /*
513  If no SAL 2 appears to have been defined (_Outptr_ is a representative choice)
514  then we must be operating in a downlevel build environment (such as VS10).
515  We also test against the compiler version to identify a downlevel environment,
516  as VS11 is the minimum required for SAL 2 support.
517 
518  If we are operating in a downlevel build environment (such as VS10)
519  we need to undefine the following symbols before including driverspecs.h
520  or we will end up referencing SAL 2 implementation symbols and cause
521  build failures.
522 */
523 #if (!defined(_Outptr_) || _MSC_VER <= 1600) && !( defined( MIDL_PASS ) || defined(__midl) || defined(RC_INVOKED) ) /*IFSTRIP=IGN*/
524 #undef __ANNOTATION
525 #define __ANNOTATION(fun) /* fun */
526 #undef __PRIMOP
527 #define __PRIMOP(type, fun)
528 #endif /* !defined(_Outptr_) || _MSC_VER <= 1600 */
529 
530 // ROTOR doesn't need driverspecs.h
531 // #include <driverspecs.h>
532 
533 /*
534  If no SAL 2 appears to have been defined (_Outptr_ is a representative choice)
535  then we must be operating in a downlevel build environment (such as VS10).
536  We also test against the compiler version to identify a downlevel environment,
537  as VS11 is the minimum required for SAL 2 support.
538 
539  If we are in a downlevel environment, we can go ahead and include no_sal2.h
540  to make all of SAL 2 no-ops to ensure no build failures.
541 */
542 #if (!defined(_Outptr_) /* || _MSC_VER <= 1600 */) && !( defined( MIDL_PASS ) || defined(__midl) || defined(RC_INVOKED) ) && !( defined( _SDV_ ) ) /*IFSTRIP=IGN*/
543 #include <no_sal2.h>
544 #endif /* !defined(_Outptr_) || _MSC_VER <= 1600 */
545 
546 #endif /* #ifndef SPECSTRINGS_H */
547 
548 
#define __inner_analysis_assume_nullterminated_dec
Definition: specstrings.h:283
#define __inner_assume_validated_dec
Definition: specstrings.h:271
#define __ANNOTATION(fun)
Definition: specstrings.h:525
#define __inner_assume_bound_dec
Definition: specstrings.h:97