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