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