1 /***************************************************************\ 2 * * 3 * SpecStrings.h - markers for documenting the semantics of APIs * 4 * * 5 * Version 1.0 * 6 * * 7 * Copyright (c) Microsoft Corporation. All rights reserved. * 8 * * 9 \***************************************************************/ 10 11 // @@BEGIN_DDKSPLIT 12 13 // ------------------------------------------------------------------------------- 14 // Introduction 15 // 16 // SpecStrings.h provides a set of annotations to describe how a function uses its 17 // parameters - the assumptions it makes about them, and the guarantees it makes 18 // upon finishing. 19 // 20 // Annotations may be placed before either a function parameter's type or its return 21 // type, and describe the function's behavior regarding the parameter or return value. 22 // There are two classes of annotations: buffer annotations and advanced annotations. 23 // Buffer annotations describe how functions use their pointer parameters, and 24 // advanced annotations either describe complex/unusual buffer behavior, or provide 25 // additional information about a parameter that is not otherwise expressible. 26 // 27 // ------------------------------------------------------------------------------- 28 // Buffer Annotations 29 // 30 // The most important annotations in SpecStrings.h provide a consistent way to annotate 31 // buffer parameters or return values for a function. Each of these annotations describes 32 // a single buffer (which could be a string, a fixed-length or variable-length array, 33 // or just a pointer) that the function interacts with: where it is, how large it is, 34 // how much is initialized, and what the function does with it. 35 // 36 // The appropriate macro for a given buffer can be constructed using the table below. 37 // Just pick the appropriate values from each category, and combine them together 38 // with a leading underscore. Some combinations of values do not make sense as buffer 39 // annotations. Only meaningful annotations can be added to your code; for a list of 40 // these, see the buffer annotation definitions section. 41 // 42 // Only a single buffer annotation should be used for each parameter. 43 // 44 // |------------|------------|---------|--------|----------|---------------| 45 // | Level | Usage | Size | Output | Optional | Parameters | 46 // |------------|------------|---------|--------|----------|---------------| 47 // | <> | <> | <> | <> | <> | <> | 48 // | _deref | _in | _ecount | _full | _opt | (size) | 49 // | _deref_opt | _out | _bcount | _part | | (size,length) | 50 // | | _inout | | | | | 51 // | | | | | | | 52 // |------------|------------|---------|--------|----------|---------------| 53 // 54 // Level: Describes the buffer pointer's level of indirection from the parameter or 55 // return value 'p'. 56 // 57 // <> : p is the buffer pointer. 58 // _deref : *p is the buffer pointer. p must not be NULL. 59 // _deref_opt : *p may be the buffer pointer. p may be NULL, in which case the rest of 60 // the annotation is ignored. 61 // 62 // Usage: Describes how the function uses the buffer. 63 // 64 // <> : The buffer is not accessed. If used on the return value or with _deref, the 65 // function will provide the buffer, and it will be uninitialized at exit. 66 // Otherwise, the caller must provide the buffer. This should only be used 67 // for alloc and free functions. 68 // _in : The function will only read from the buffer. The caller must provide the 69 // buffer and initialize it. 70 // _out : The function will only write to the buffer. If used on the return value or 71 // with _deref, the function will provide the buffer and initialize it. 72 // Otherwise, the caller must provide the buffer, and the function will 73 // initialize it. 74 // _inout : The function may freely read from and write to the buffer. The caller must 75 // provide the buffer and initialize it. If used with _deref, the buffer may 76 // be reallocated by the function. 77 // 78 // Size: Describes the total size of the buffer. This may be less than the space actually 79 // allocated for the buffer, in which case it describes the accessible amount. 80 // 81 // <> : No buffer size is given. If the type specifies the buffer size (such as 82 // with LPSTR and LPWSTR), that amount is used. Otherwise, the buffer is one 83 // element long. Must be used with _in, _out, or _inout. 84 // _ecount : The buffer size is an explicit element count. 85 // _bcount : The buffer size is an explicit byte count. 86 // 87 // Output: Describes how much of the buffer will be initialized by the function. For 88 // _inout buffers, this also describes how much is initialized at entry. Omit this 89 // category for _in buffers; they must be fully initialized by the caller. 90 // 91 // <> : The type specifies how much is initialized. For instance, a function initializing 92 // an LPWSTR must NULL-terminate the string. 93 // _full : The function initializes the entire buffer. 94 // _part : The function initializes part of the buffer, and explicitly indicates how much. 95 // 96 // Optional: Describes if the buffer itself is optional. 97 // 98 // <> : The pointer to the buffer must not be NULL. 99 // _opt : The pointer to the buffer might be NULL. It will be checked before being dereferenced. 100 // 101 // Parameters: Gives explicit counts for the size and length of the buffer. 102 // 103 // <> : There is no explicit count. Use when neither _ecount nor _bcount is used. 104 // (size) : Only the buffer's total size is given. Use with _ecount or _bcount but not _part. 105 // (size,length) : The buffer's total size and initialized length are given. Use with _ecount_part 106 // and _bcount_part. 107 // 108 // ------------------------------------------------------------------------------- 109 // Buffer Annotation Examples 110 // 111 // LWSTDAPI_(BOOL) StrToIntExA( 112 // LPCSTR pszString, // No annotation required, const implies __in. 113 // DWORD dwFlags, 114 // __out int *piRet // A pointer whose dereference will be filled in. 115 // ); 116 // 117 // void MyPaintingFunction( 118 // __in HWND hwndControl, // An initialized read-only parameter. 119 // __in_opt HDC hdcOptional, // An initialized read-only parameter that might be NULL. 120 // __inout IPropertyStore *ppsStore // An initialized parameter that may be freely used 121 // // and modified. 122 // ); 123 // 124 // LWSTDAPI_(BOOL) PathCompactPathExA( 125 // __out_ecount(cchMax) LPSTR pszOut, // A string buffer with cch elements that will 126 // // be NULL terminated on exit. 127 // LPCSTR pszSrc, // No annotation required, const implies __in. 128 // UINT cchMax, 129 // DWORD dwFlags 130 // ); 131 // 132 // HRESULT SHLocalAllocBytes( 133 // size_t cb, 134 // __deref_bcount(cb) T **ppv // A pointer whose dereference will be set to an 135 // // uninitialized buffer with cb bytes. 136 // ); 137 // 138 // __inout_bcount_full(cb) : A buffer with cb elements that is fully initialized at 139 // entry and exit, and may be written to by this function. 140 // 141 // __out_ecount_part(count, *countOut) : A buffer with count elements that will be 142 // partially initialized by this function. The function indicates how much it 143 // initialized by setting *countOut. 144 // 145 // ------------------------------------------------------------------------------- 146 // Advanced Annotations 147 // 148 // Advanced annotations describe behavior that is not expressible with the regular 149 // buffer macros. These may be used either to annotate buffer parameters that involve 150 // complex or conditional behavior, or to enrich existing annotations with additional 151 // information. 152 // 153 // __success(expr) f : 154 // <expr> indicates whether function f succeeded or not. If <expr> is true at exit, 155 // all the function's guarantees (as given by other annotations) must hold. If <expr> 156 // is false at exit, the caller should not expect any of the function's guarantees 157 // to hold. If not used, the function must always satisfy its guarantees. Added 158 // automatically to functions that indicate success in standard ways, such as by 159 // returning an HRESULT. 160 // 161 // __out_awcount(expr, size) p : 162 // Pointer p is a buffer whose size may be given in either bytes or elements. If 163 // <expr> is true, this acts like __out_bcount. If <expr> is false, this acts 164 // like __out_ecount. This should only be used to annotate old APIs. 165 // 166 // __in_awcount(expr, size) p : 167 // Pointer p is a buffer whose size may be given in either bytes or elements. If 168 // <expr> is true, this acts like __in_bcount. If <expr> is false, this acts 169 // like __in_ecount. This should only be used to annotate old APIs. 170 // 171 // __nullterminated p : 172 // Pointer p is a buffer that may be read or written up to and including the first 173 // NULL character or pointer. May be used on typedefs, which marks valid (properly 174 // initialized) instances of that type as being NULL-terminated. 175 // 176 // __nullnullterminated p : 177 // Pointer p is a buffer that may be read or written up to and including the first 178 // sequence of two NULL characters or pointers. May be used on typedefs, which marks 179 // valid instances of that type as being double-NULL terminated. 180 // 181 // __reserved v : 182 // Value v must be 0/NULL, reserved for future use. 183 // 184 // __checkReturn v : 185 // Return value v must not be ignored by callers of this function. 186 // 187 // __typefix(ctype) v : 188 // Value v should be treated as an instance of ctype, rather than its declared type. 189 // 190 // __override f : 191 // Specify C#-style 'override' behaviour for overriding virtual methods. 192 // 193 // __callback f : 194 // Function f can be used as a function pointer. 195 // 196 // __format_string p : 197 // Pointer p is a string that contains % markers in the style of printf. 198 // 199 // __blocksOn(resource) f : 200 // Function f blocks on the resource 'resource'. 201 // 202 // __fallthrough : 203 // Annotates switch statement labels where fall-through is desired, to distinguish 204 // from forgotten break statements. 205 // 206 // ------------------------------------------------------------------------------- 207 // Advanced Annotation Examples 208 // 209 // __success(return == TRUE) LWSTDAPI_(BOOL) 210 // PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) : 211 // pszBuf is only guaranteed to be NULL-terminated when TRUE is returned. 212 // 213 // typedef __nullterminated WCHAR* LPWSTR : Initialized LPWSTRs are NULL-terminated strings. 214 // 215 // __out_ecount(cch) __typefix(LPWSTR) void *psz : psz is a buffer parameter which will be 216 // a NULL-terminated WCHAR string at exit, and which initially contains cch WCHARs. 217 // 218 // ------------------------------------------------------------------------------- 219 220 // @@END_DDKSPLIT 221 222 #if _MSC_VER > 1000 223 #pragma once 224 #endif // #if _MSC_VER > 1000 225 226 #define __specstrings 227 228 #ifdef __cplusplus 229 #ifndef __nothrow 230 # define __nothrow __declspec(nothrow) 231 #endif 232 extern "C" { 233 #else 234 #ifndef __nothrow 235 # define __nothrow 236 #endif 237 #endif // #ifdef __cplusplus 238 239 // @@BEGIN_DDKSPLIT 240 241 // ------------------------------------------------------------------------------- 242 // Helper Macro Definitions 243 // 244 // These express behavior common to many of the high-level annotations. 245 // DO NOT USE THESE IN YOUR CODE. 246 // ------------------------------------------------------------------------------- 247 248 // The helper annotations are only understood by the compiler version used by various 249 // defect detection tools. When the regular compiler is running, they are defined into 250 // nothing, and do not affect the compiled code. 251 #if (_MSC_VER >= 1000) && !defined(MIDL_PASS) && defined(_PREFAST_) 252 253 // In the primitive __declspec("SAL_*") annotations "SAL" stands for Standard 254 // Annotation Language. These __declspec("SAL_*") annotations are the 255 // primitives the compiler understands and all high-level SpecString MACROs 256 // will decompose into these primivates. 257 258 #define SPECSTRINGIZE( x ) #x 259 260 // 261 // __null p 262 // __notnull p 263 // __maybenull p 264 // 265 // Annotates a pointer p. States that pointer p is null. Commonly used 266 // in the negated form __notnull or the possibly null form __maybenull. 267 // 268 #define __null __declspec("SAL_null") 269 #define __notnull __declspec("SAL_notnull") 270 #define __maybenull __declspec("SAL_maybenull") 271 272 // 273 // __readonly l 274 // __notreadonly l 275 // __mabyereadonly l 276 // 277 // Annotates a location l. States that location l is not modified after 278 // this point. If the annotation is placed on the precondition state of 279 // a function, the restriction only applies until the postcondition state 280 // of the function. __maybereadonly states that the annotated location 281 // may be modified, whereas __notreadonly states that a location must be 282 // modified. 283 // 284 #define __readonly __declspec("SAL_readonly") 285 #define __notreadonly __declspec("SAL_notreadonly") 286 #define __maybereadonly __declspec("SAL_maybereadonly") 287 288 // 289 // __valid v 290 // __notvalid v 291 // __maybevalid v 292 // 293 // Annotates any value v. States that the value satisfies all properties of 294 // valid values of its type. For example, for a string buffer, valid means 295 // that the buffer pointer is either NULL or points to a NULL-terminated string. 296 // 297 #define __valid __declspec("SAL_valid") 298 #define __notvalid __declspec("SAL_notvalid") 299 #define __maybevalid __declspec("SAL_maybevalid") 300 301 // 302 // __readableTo(extent) p 303 // 304 // Annotates a buffer pointer p. If the buffer can be read, extent describes 305 // how much of the buffer is readable. For a reader of the buffer, this is 306 // an explicit permission to read up to that amount, rather than a restriction to 307 // read only up to it. 308 // 309 #define __readableTo(extent) __declspec("SAL_readableTo("SPECSTRINGIZE(extent)")") 310 311 // 312 // __elem_readableTo(size) 313 // 314 // Annotates a buffer pointer p as being readable to size elements. 315 // 316 #define __elem_readableTo(size) __declspec("SAL_readableTo(elementCount("SPECSTRINGIZE(size)"))") 317 318 // 319 // __byte_readableTo(size) 320 // 321 // Annotates a buffer pointer p as being readable to size bytes. 322 // 323 #define __byte_readableTo(size) __declspec("SAL_readableTo(byteCount("SPECSTRINGIZE(size)"))") 324 325 // 326 // __writableTo(extent) p 327 // 328 // Annotates a buffer pointer p. If the buffer can be modified, extent 329 // describes how much of the buffer is writable (usually the allocation 330 // size). For a writer of the buffer, this is an explicit permission to 331 // write up to that amount, rather than a restriction to write only up to it. 332 // 333 #define __writableTo(size) __declspec("SAL_writableTo("SPECSTRINGIZE(size)")") 334 335 // 336 // __elem_writableTo(size) 337 // 338 // Annotates a buffer pointer p as being writable to size elements. 339 // 340 #define __elem_writableTo(size) __declspec("SAL_writableTo(elementCount("SPECSTRINGIZE(size)"))") 341 342 // 343 // __byte_writableTo(size) 344 // 345 // Annotates a buffer pointer p as being writable to size bytes. 346 // 347 #define __byte_writableTo(size) __declspec("SAL_writableTo(byteCount("SPECSTRINGIZE(size)"))") 348 349 // 350 // __deref p 351 // 352 // Annotates a pointer p. The next annotation applies one dereference down 353 // in the type. If readableTo(p, size) then the next annotation applies to 354 // all elements *(p+i) for which i satisfies the size. If p is a pointer 355 // to a struct, the next annotation applies to all fields of the struct. 356 // 357 #define __deref __declspec("SAL_deref") 358 359 // 360 // __pre __next_annotation 361 // 362 // The next annotation applies in the precondition state 363 // 364 #define __pre __declspec("SAL_pre") 365 366 // 367 // __post __next_annotation 368 // 369 // The next annotation applies in the postcondition state 370 // 371 #define __post __declspec("SAL_post") 372 373 // 374 // __precond(<expr>) 375 // 376 // When <expr> is true, the next annotation applies in the precondition state 377 // (currently not enabled) 378 // 379 #define __precond(expr) __pre 380 381 // 382 // __postcond(<expr>) 383 // 384 // When <expr> is true, the next annotation applies in the postcondition state 385 // (currently not enabled) 386 // 387 #define __postcond(expr) __post 388 389 // 390 // __exceptthat 391 // 392 // Given a set of annotations Q containing __exceptthat maybeP, the effect of 393 // the except clause is to erase any P or notP annotations (explicit or 394 // implied) within Q at the same level of dereferencing that the except 395 // clause appears, and to replace it with maybeP. 396 // 397 // Example 1: __valid __exceptthat __maybenull on a pointer p means that the 398 // pointer may be null, and is otherwise valid, thus overriding 399 // the implicit notnull annotation implied by __valid on 400 // pointers. 401 // 402 // Example 2: __valid __deref __exceptthat __maybenull on an int **p means 403 // that p is not null (implied by valid), but the elements 404 // pointed to by p could be null, and are otherwise valid. 405 // 406 #define __exceptthat __declspec("SAL_except") 407 408 // 409 // _refparam 410 // 411 // Added to all out parameter macros to indicate that they are all reference 412 // parameters. 413 // 414 #define __refparam __deref __notreadonly 415 416 // 417 // __inner_* 418 // 419 // Helper macros that directly correspond to certain high-level annotations. 420 // 421 // 422 423 // Macros to classify the entrypoints and indicate their category. 424 // 425 // 426 // Pre-defined control point categories include: RPC, LPC, DeviceDriver, UserToKernel, ISAPI, COM. 427 // 428 #define __inner_control_entrypoint(category) __declspec("SAL_entrypoint(controlEntry, "SPECSTRINGIZE(category)")") 429 430 // 431 // Pre-defined data entry point categories include: Registry, File, Network. 432 // 433 #define __inner_data_entrypoint(category) __declspec("SAL_entrypoint(dataEntry, "SPECSTRINGIZE(category)")") 434 435 #define __inner_success(expr) __declspec("SAL_success("SPECSTRINGIZE(expr)")") 436 #define __inner_checkReturn __declspec("SAL_checkReturn") 437 #define __inner_typefix(ctype) __declspec("SAL_typefix("SPECSTRINGIZE(ctype)")") 438 #define __inner_override __declspec("__override") 439 #define __inner_callback __declspec("__callback") 440 #define __inner_blocksOn(resource) __declspec("SAL_blocksOn("SPECSTRINGIZE(resource)")") 441 #define __inner_fallthrough_dec __inline __nothrow void __FallThrough() {} 442 #define __inner_fallthrough __FallThrough(); 443 444 #else 445 446 // @@END_DDKSPLIT 447 448 #ifndef __null 449 #define __null 450 #endif 451 #ifndef __notnull 452 #define __notnull 453 #endif 454 #ifndef __maybenull 455 #define __maybenull 456 #endif 457 #ifndef __readonly 458 #define __readonly 459 #endif 460 #ifndef __notreadonly 461 #define __notreadonly 462 #endif 463 #ifndef __maybereadonly 464 #define __maybereadonly 465 #endif 466 #ifndef __valid 467 #define __valid 468 #endif 469 #ifndef __notvalid 470 #define __notvalid 471 #endif 472 #ifndef __maybevalid 473 #define __maybevalid 474 #endif 475 #ifndef __readableTo 476 #define __readableTo(extent) 477 #endif 478 #ifndef __elem_readableTo 479 #define __elem_readableTo(size) 480 #endif 481 #ifndef __byte_readableTo 482 #define __byte_readableTo(size) 483 #endif 484 #ifndef __writableTo 485 #define __writableTo(size) 486 #endif 487 #ifndef __elem_writableTo 488 #define __elem_writableTo(size) 489 #endif 490 #ifndef __byte_writableTo 491 #define __byte_writableTo(size) 492 #endif 493 #ifndef __deref 494 #define __deref 495 #endif 496 #ifndef __pre 497 #define __pre 498 #endif 499 #ifndef __post 500 #define __post 501 #endif 502 #ifndef __precond 503 #define __precond(expr) 504 #endif 505 #ifndef __postcond 506 #define __postcond(expr) 507 #endif 508 #ifndef __exceptthat 509 #define __exceptthat 510 #endif 511 #ifndef __inner_success 512 #define __inner_success(expr) 513 #endif 514 #ifndef __inner_checkReturn 515 #define __inner_checkReturn 516 #endif 517 #ifndef __inner_typefix 518 #define __inner_typefix(ctype) 519 #endif 520 #ifndef __inner_override 521 #define __inner_override 522 #endif 523 #ifndef __inner_callback 524 #define __inner_callback 525 #endif 526 #ifndef __inner_blocksOn 527 #define __inner_blocksOn(resource) 528 #endif 529 #ifndef __inner_fallthrough_dec 530 #define __inner_fallthrough_dec 531 #endif 532 #ifndef __inner_fallthrough 533 #define __inner_fallthrough 534 #endif 535 #ifndef __refparam 536 #define __refparam 537 #endif 538 #ifndef __inner_control_entrypoint 539 #define __inner_control_entrypoint(category) 540 #endif 541 #ifndef __inner_data_entrypoint 542 #define __inner_data_entrypoint(category) 543 #endif 544 // @@BEGIN_DDKSPLIT 545 #endif // #if (_MSC_VER >= 1000) && !defined(MIDL_PASS) && defined(_PREFAST_) 546 // ------------------------------------------------------------------------------- 547 // Buffer Annotation Definitions 548 // 549 // Any of these may be used to directly annotate functions, but only one should 550 // be used for each parameter. To determine which annotation to use for a given 551 // buffer, use the table in the buffer annotations section. 552 // ------------------------------------------------------------------------------- 553 // @@END_DDKSPLIT 554 555 #ifndef __ecount 556 #define __ecount(size) __notnull __elem_writableTo(size) 557 #endif 558 #ifndef __bcount 559 #define __bcount(size) __notnull __byte_writableTo(size) 560 #endif 561 #ifndef __in 562 #define __in __pre __valid __pre __deref __readonly 563 #endif 564 #ifndef __in_ecount 565 #define __in_ecount(size) __in __pre __elem_readableTo(size) 566 #endif 567 #ifndef __in_bcount 568 #define __in_bcount(size) __in __pre __byte_readableTo(size) 569 #endif 570 #ifndef __out 571 #define __out __ecount(1) __post __valid __refparam 572 #endif 573 #ifndef __out_ecount 574 #define __out_ecount(size) __ecount(size) __post __valid __refparam 575 #endif 576 #ifndef __out_bcount 577 #define __out_bcount(size) __bcount(size) __post __valid __refparam 578 #endif 579 #ifndef __out_ecount_part 580 #define __out_ecount_part(size,length) __out_ecount(size) __post __elem_readableTo(length) 581 #endif 582 #ifndef __out_bcount_part 583 #define __out_bcount_part(size,length) __out_bcount(size) __post __byte_readableTo(length) 584 #endif 585 #ifndef __out_ecount_full 586 #define __out_ecount_full(size) __out_ecount_part(size,size) 587 #endif 588 #ifndef __out_bcount_full 589 #define __out_bcount_full(size) __out_bcount_part(size,size) 590 #endif 591 #ifndef __inout 592 #define __inout __pre __valid __post __valid __refparam 593 #endif 594 #ifndef __inout_ecount 595 #define __inout_ecount(size) __out_ecount(size) __pre __valid 596 #endif 597 #ifndef __inout_bcount 598 #define __inout_bcount(size) __out_bcount(size) __pre __valid 599 #endif 600 #ifndef __inout_ecount_part 601 #define __inout_ecount_part(size,length) __out_ecount_part(size,length) __pre __valid __pre __elem_readableTo(length) 602 #endif 603 #ifndef __inout_bcount_part 604 #define __inout_bcount_part(size,length) __out_bcount_part(size,length) __pre __valid __pre __byte_readableTo(length) 605 #endif 606 #ifndef __inout_ecount_full 607 #define __inout_ecount_full(size) __inout_ecount_part(size,size) 608 #endif 609 #ifndef __inout_bcount_full 610 #define __inout_bcount_full(size) __inout_bcount_part(size,size) 611 #endif 612 613 #ifndef __ecount_opt 614 #define __ecount_opt(size) __ecount(size) __exceptthat __maybenull 615 #endif 616 #ifndef __bcount_opt 617 #define __bcount_opt(size) __bcount(size) __exceptthat __maybenull 618 #endif 619 #ifndef __in_opt 620 #define __in_opt __in __exceptthat __maybenull 621 #endif 622 #ifndef __in_ecount_opt 623 #define __in_ecount_opt(size) __in_ecount(size) __exceptthat __maybenull 624 #endif 625 #ifndef __in_bcount_opt 626 #define __in_bcount_opt(size) __in_bcount(size) __exceptthat __maybenull 627 #endif 628 #ifndef __out_opt 629 #define __out_opt __out __exceptthat __maybenull 630 #endif 631 #ifndef __out_ecount_opt 632 #define __out_ecount_opt(size) __out_ecount(size) __exceptthat __maybenull 633 #endif 634 #ifndef __out_bcount_opt 635 #define __out_bcount_opt(size) __out_bcount(size) __exceptthat __maybenull 636 #endif 637 #ifndef __out_ecount_part_opt 638 #define __out_ecount_part_opt(size,length) __out_ecount_part(size,length) __exceptthat __maybenull 639 #endif 640 #ifndef __out_bcount_part_opt 641 #define __out_bcount_part_opt(size,length) __out_bcount_part(size,length) __exceptthat __maybenull 642 #endif 643 #ifndef __out_ecount_full_opt 644 #define __out_ecount_full_opt(size) __out_ecount_full(size) __exceptthat __maybenull 645 #endif 646 #ifndef __out_bcount_full_opt 647 #define __out_bcount_full_opt(size) __out_bcount_full(size) __exceptthat __maybenull 648 #endif 649 #ifndef __inout_opt 650 #define __inout_opt __inout __exceptthat __maybenull 651 #endif 652 #ifndef __inout_ecount_opt 653 #define __inout_ecount_opt(size) __inout_ecount(size) __exceptthat __maybenull 654 #endif 655 #ifndef __inout_bcount_opt 656 #define __inout_bcount_opt(size) __inout_bcount(size) __exceptthat __maybenull 657 #endif 658 #ifndef __inout_ecount_part_opt 659 #define __inout_ecount_part_opt(size,length) __inout_ecount_part(size,length) __exceptthat __maybenull 660 #endif 661 #ifndef __inout_bcount_part_opt 662 #define __inout_bcount_part_opt(size,length) __inout_bcount_part(size,length) __exceptthat __maybenull 663 #endif 664 #ifndef __inout_ecount_full_opt 665 #define __inout_ecount_full_opt(size) __inout_ecount_full(size) __exceptthat __maybenull 666 #endif 667 #ifndef __inout_bcount_full_opt 668 #define __inout_bcount_full_opt(size) __inout_bcount_full(size) __exceptthat __maybenull 669 #endif 670 671 #ifndef __deref_ecount 672 #define __deref_ecount(size) __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __elem_writableTo(size) 673 #endif 674 #ifndef __deref_bcount 675 #define __deref_bcount(size) __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __byte_writableTo(size) 676 #endif 677 #ifndef __deref_in 678 #define __deref_in __in __pre __deref __deref __readonly 679 #endif 680 #ifndef __deref_in_ecount 681 #define __deref_in_ecount(size) __deref_in __pre __deref __elem_readableTo(size) 682 #endif 683 #ifndef __deref_in_bcount 684 #define __deref_in_bcount(size) __deref_in __pre __deref __byte_readableTo(size) 685 #endif 686 #ifndef __deref_out 687 #define __deref_out __deref_ecount(1) __post __deref __valid __refparam 688 #endif 689 #ifndef __deref_out_ecount 690 #define __deref_out_ecount(size) __deref_ecount(size) __post __deref __valid __refparam 691 #endif 692 #ifndef __deref_out_bcount 693 #define __deref_out_bcount(size) __deref_bcount(size) __post __deref __valid __refparam 694 #endif 695 #ifndef __deref_out_ecount_part 696 #define __deref_out_ecount_part(size,length) __deref_out_ecount(size) __post __deref __elem_readableTo(length) 697 #endif 698 #ifndef __deref_out_bcount_part 699 #define __deref_out_bcount_part(size,length) __deref_out_bcount(size) __post __deref __byte_readableTo(length) 700 #endif 701 #ifndef __deref_out_ecount_full 702 #define __deref_out_ecount_full(size) __deref_out_ecount_part(size,size) 703 #endif 704 #ifndef __deref_out_bcount_full 705 #define __deref_out_bcount_full(size) __deref_out_bcount_part(size,size) 706 #endif 707 #ifndef __deref_inout 708 #define __deref_inout __notnull __elem_readableTo(1) __pre __deref __valid __post __deref __valid __refparam 709 #endif 710 #ifndef __deref_inout_ecount 711 #define __deref_inout_ecount(size) __deref_inout __pre __deref __elem_writableTo(size) __post __deref __elem_writableTo(size) 712 #endif 713 #ifndef __deref_inout_bcount 714 #define __deref_inout_bcount(size) __deref_inout __pre __deref __byte_writableTo(size) __post __deref __byte_writableTo(size) 715 #endif 716 #ifndef __deref_inout_ecount_part 717 #define __deref_inout_ecount_part(size,length) __deref_inout_ecount(size) __pre __deref __elem_readableTo(length) __post __deref __elem_readableTo(length) 718 #endif 719 #ifndef __deref_inout_bcount_part 720 #define __deref_inout_bcount_part(size,length) __deref_inout_bcount(size) __pre __deref __byte_readableTo(length) __post __deref __byte_readableTo(length) 721 #endif 722 #ifndef __deref_inout_ecount_full 723 #define __deref_inout_ecount_full(size) __deref_inout_ecount_part(size,size) 724 #endif 725 #ifndef __deref_inout_bcount_full 726 #define __deref_inout_bcount_full(size) __deref_inout_bcount_part(size,size) 727 #endif 728 729 #ifndef __deref_ecount_opt 730 #define __deref_ecount_opt(size) __deref_ecount(size) __post __deref __exceptthat __maybenull 731 #endif 732 #ifndef __deref_bcount_opt 733 #define __deref_bcount_opt(size) __deref_bcount(size) __post __deref __exceptthat __maybenull 734 #endif 735 #ifndef __deref_in_opt 736 #define __deref_in_opt __deref_in __pre __deref __exceptthat __maybenull 737 #endif 738 #ifndef __deref_in_ecount_opt 739 #define __deref_in_ecount_opt(size) __deref_in_ecount(size) __pre __deref __exceptthat __maybenull 740 #endif 741 #ifndef __deref_in_bcount_opt 742 #define __deref_in_bcount_opt(size) __deref_in_bcount(size) __pre __deref __exceptthat __maybenull 743 #endif 744 #ifndef __deref_out_opt 745 #define __deref_out_opt __deref_out __post __deref __exceptthat __maybenull 746 #endif 747 #ifndef __deref_out_ecount_opt 748 #define __deref_out_ecount_opt(size) __deref_out_ecount(size) __post __deref __exceptthat __maybenull 749 #endif 750 #ifndef __deref_out_bcount_opt 751 #define __deref_out_bcount_opt(size) __deref_out_bcount(size) __post __deref __exceptthat __maybenull 752 #endif 753 #ifndef __deref_out_ecount_part_opt 754 #define __deref_out_ecount_part_opt(size,length) __deref_out_ecount_part(size,length) __post __deref __exceptthat __maybenull 755 #endif 756 #ifndef __deref_out_bcount_part_opt 757 #define __deref_out_bcount_part_opt(size,length) __deref_out_bcount_part(size,length) __post __deref __exceptthat __maybenull 758 #endif 759 #ifndef __deref_out_ecount_full_opt 760 #define __deref_out_ecount_full_opt(size) __deref_out_ecount_full(size) __post __deref __exceptthat __maybenull 761 #endif 762 #ifndef __deref_out_bcount_full_opt 763 #define __deref_out_bcount_full_opt(size) __deref_out_bcount_full(size) __post __deref __exceptthat __maybenull 764 #endif 765 #ifndef __deref_inout_opt 766 #define __deref_inout_opt __deref_inout __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 767 #endif 768 #ifndef __deref_inout_ecount_opt 769 #define __deref_inout_ecount_opt(size) __deref_inout_ecount(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 770 #endif 771 #ifndef __deref_inout_bcount_opt 772 #define __deref_inout_bcount_opt(size) __deref_inout_bcount(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 773 #endif 774 #ifndef __deref_inout_ecount_part_opt 775 #define __deref_inout_ecount_part_opt(size,length) __deref_inout_ecount_part(size,length) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 776 #endif 777 #ifndef __deref_inout_bcount_part_opt 778 #define __deref_inout_bcount_part_opt(size,length) __deref_inout_bcount_part(size,length) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 779 #endif 780 #ifndef __deref_inout_ecount_full_opt 781 #define __deref_inout_ecount_full_opt(size) __deref_inout_ecount_full(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 782 #endif 783 #ifndef __deref_inout_bcount_full_opt 784 #define __deref_inout_bcount_full_opt(size) __deref_inout_bcount_full(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull 785 #endif 786 787 #ifndef __deref_opt_ecount 788 #define __deref_opt_ecount(size) __deref_ecount(size) __exceptthat __maybenull 789 #endif 790 #ifndef __deref_opt_bcount 791 #define __deref_opt_bcount(size) __deref_bcount(size) __exceptthat __maybenull 792 #endif 793 #ifndef __deref_opt_in 794 #define __deref_opt_in __deref_in __exceptthat __maybenull 795 #endif 796 #ifndef __deref_opt_in_ecount 797 #define __deref_opt_in_ecount(size) __deref_in_ecount(size) __exceptthat __maybenull 798 #endif 799 #ifndef __deref_opt_in_bcount 800 #define __deref_opt_in_bcount(size) __deref_in_bcount(size) __exceptthat __maybenull 801 #endif 802 #ifndef __deref_opt_out 803 #define __deref_opt_out __deref_out __exceptthat __maybenull 804 #endif 805 #ifndef __deref_opt_out_ecount 806 #define __deref_opt_out_ecount(size) __deref_out_ecount(size) __exceptthat __maybenull 807 #endif 808 #ifndef __deref_opt_out_bcount 809 #define __deref_opt_out_bcount(size) __deref_out_bcount(size) __exceptthat __maybenull 810 #endif 811 #ifndef __deref_opt_out_ecount_part 812 #define __deref_opt_out_ecount_part(size,length) __deref_out_ecount_part(size,length) __exceptthat __maybenull 813 #endif 814 #ifndef __deref_opt_out_bcount_part 815 #define __deref_opt_out_bcount_part(size,length) __deref_out_bcount_part(size,length) __exceptthat __maybenull 816 #endif 817 #ifndef __deref_opt_out_ecount_full 818 #define __deref_opt_out_ecount_full(size) __deref_out_ecount_full(size) __exceptthat __maybenull 819 #endif 820 #ifndef __deref_opt_out_bcount_full 821 #define __deref_opt_out_bcount_full(size) __deref_out_bcount_full(size) __exceptthat __maybenull 822 #endif 823 #ifndef __deref_opt_inout 824 #define __deref_opt_inout __deref_inout __exceptthat __maybenull 825 #endif 826 #ifndef __deref_opt_inout_ecount 827 #define __deref_opt_inout_ecount(size) __deref_inout_ecount(size) __exceptthat __maybenull 828 #endif 829 #ifndef __deref_opt_inout_bcount 830 #define __deref_opt_inout_bcount(size) __deref_inout_bcount(size) __exceptthat __maybenull 831 #endif 832 #ifndef __deref_opt_inout_ecount_part 833 #define __deref_opt_inout_ecount_part(size,length) __deref_inout_ecount_part(size,length) __exceptthat __maybenull 834 #endif 835 #ifndef __deref_opt_inout_bcount_part 836 #define __deref_opt_inout_bcount_part(size,length) __deref_inout_bcount_part(size,length) __exceptthat __maybenull 837 #endif 838 #ifndef __deref_opt_inout_ecount_full 839 #define __deref_opt_inout_ecount_full(size) __deref_inout_ecount_full(size) __exceptthat __maybenull 840 #endif 841 #ifndef __deref_opt_inout_bcount_full 842 #define __deref_opt_inout_bcount_full(size) __deref_inout_bcount_full(size) __exceptthat __maybenull 843 #endif 844 845 #ifndef __deref_opt_ecount_opt 846 #define __deref_opt_ecount_opt(size) __deref_ecount_opt(size) __exceptthat __maybenull 847 #endif 848 #ifndef __deref_opt_bcount_opt 849 #define __deref_opt_bcount_opt(size) __deref_bcount_opt(size) __exceptthat __maybenull 850 #endif 851 #ifndef __deref_opt_in_opt 852 #define __deref_opt_in_opt __deref_in_opt __exceptthat __maybenull 853 #endif 854 #ifndef __deref_opt_in_ecount_opt 855 #define __deref_opt_in_ecount_opt(size) __deref_in_ecount_opt(size) __exceptthat __maybenull 856 #endif 857 #ifndef __deref_opt_in_bcount_opt 858 #define __deref_opt_in_bcount_opt(size) __deref_in_bcount_opt(size) __exceptthat __maybenull 859 #endif 860 #ifndef __deref_opt_out_opt 861 #define __deref_opt_out_opt __deref_out_opt __exceptthat __maybenull 862 #endif 863 #ifndef __deref_opt_out_ecount_opt 864 #define __deref_opt_out_ecount_opt(size) __deref_out_ecount_opt(size) __exceptthat __maybenull 865 #endif 866 #ifndef __deref_opt_out_bcount_opt 867 #define __deref_opt_out_bcount_opt(size) __deref_out_bcount_opt(size) __exceptthat __maybenull 868 #endif 869 #ifndef __deref_opt_out_ecount_part_opt 870 #define __deref_opt_out_ecount_part_opt(size,length) __deref_out_ecount_part_opt(size,length) __exceptthat __maybenull 871 #endif 872 #ifndef __deref_opt_out_bcount_part_opt 873 #define __deref_opt_out_bcount_part_opt(size,length) __deref_out_bcount_part_opt(size,length) __exceptthat __maybenull 874 #endif 875 #ifndef __deref_opt_out_ecount_full_opt 876 #define __deref_opt_out_ecount_full_opt(size) __deref_out_ecount_full_opt(size) __exceptthat __maybenull 877 #endif 878 #ifndef __deref_opt_out_bcount_full_opt 879 #define __deref_opt_out_bcount_full_opt(size) __deref_out_bcount_full_opt(size) __exceptthat __maybenull 880 #endif 881 #ifndef __deref_opt_inout_opt 882 #define __deref_opt_inout_opt __deref_inout_opt __exceptthat __maybenull 883 #endif 884 #ifndef __deref_opt_inout_ecount_opt 885 #define __deref_opt_inout_ecount_opt(size) __deref_inout_ecount_opt(size) __exceptthat __maybenull 886 #endif 887 #ifndef __deref_opt_inout_bcount_opt 888 #define __deref_opt_inout_bcount_opt(size) __deref_inout_bcount_opt(size) __exceptthat __maybenull 889 #endif 890 #ifndef __deref_opt_inout_ecount_part_opt 891 #define __deref_opt_inout_ecount_part_opt(size,length) __deref_inout_ecount_part_opt(size,length) __exceptthat __maybenull 892 #endif 893 #ifndef __deref_opt_inout_bcount_part_opt 894 #define __deref_opt_inout_bcount_part_opt(size,length) __deref_inout_bcount_part_opt(size,length) __exceptthat __maybenull 895 #endif 896 #ifndef __deref_opt_inout_ecount_full_opt 897 #define __deref_opt_inout_ecount_full_opt(size) __deref_inout_ecount_full_opt(size) __exceptthat __maybenull 898 #endif 899 #ifndef __deref_opt_inout_bcount_full_opt 900 #define __deref_opt_inout_bcount_full_opt(size) __deref_inout_bcount_full_opt(size) __exceptthat __maybenull 901 #endif 902 903 // @@BEGIN_DDKSPLIT 904 // ------------------------------------------------------------------------------- 905 // Advanced Annotation Definitions 906 // 907 // Any of these may be used to directly annotate functions, and may be used in 908 // combination with each other or with regular buffer macros. For an explanation 909 // of each annotation, see the advanced annotations section. 910 // ------------------------------------------------------------------------------- 911 // @@END_DDKSPLIT 912 913 #ifndef __out_awcount 914 #define __out_awcount(expr,size) __pre __notnull \ 915 __precond(expr) __byte_writableTo(size) \ 916 __precond(!(expr)) __byte_writableTo((size)*2) \ 917 __post __valid __refparam 918 #endif 919 #ifndef __in_awcount 920 #define __in_awcount(expr,size) __pre __valid \ 921 __pre __deref __readonly \ 922 __precond(expr) __byte_readableTo(size) \ 923 __precond(!(expr)) __elem_readableTo(size) 924 #endif 925 #ifndef __success 926 #define __success(expr) __inner_success(expr) 927 #endif 928 #ifndef __nullterminated 929 #define __nullterminated __readableTo(sentinel(0)) 930 #endif 931 #ifndef __nullnullterminated 932 #define __nullnullterminated 933 #endif 934 #ifndef __reserved 935 #define __reserved __pre __null 936 #endif 937 #ifndef __checkReturn 938 #define __checkReturn __inner_checkReturn 939 #endif 940 #ifndef __typefix 941 #define __typefix(ctype) __inner_typefix(ctype) 942 #endif 943 #ifndef __override 944 #define __override __inner_override 945 #endif 946 #ifndef __callback 947 #define __callback __inner_callback 948 #endif 949 #ifndef __format_string 950 #define __format_string 951 #endif 952 #ifndef __blocksOn 953 #define __blocksOn(resource) __inner_blocksOn(resource) 954 #endif 955 #ifndef __control_entrypoint 956 #define __control_entrypoint(category) __inner_control_entrypoint(category) 957 #endif 958 #ifndef __data_entrypoint 959 #define __data_entrypoint(category) __inner_data_entrypoint(category) 960 #endif 961 962 #ifndef __fallthrough 963 __inner_fallthrough_dec 964 #define __fallthrough __inner_fallthrough 965 #endif 966 967 // ------------------------------------------------------------------------------- 968 // Deprecated Annotation Definitions 969 // 970 // These should be removed from existing code. 971 // ------------------------------------------------------------------------------- 972 973 // #define __opt __exceptthat __maybenull 974 975 #ifdef __cplusplus 976 } 977 #endif 978 979
