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 */ 381 __inner_assume_validated_dec 382 __inner_assume_bound_dec 383 __inner_analysis_assume_nullterminated_dec 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 549