specstrings.h revision ee451cb395940862dad63c85adfe8f2fd55e864c
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 232extern "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