/***************************************************************\ | |
* * | |
* SpecStrings.h - markers for documenting the semantics of APIs * | |
* * | |
* Version 1.0 * | |
* * | |
* Copyright (c) Microsoft Corporation. All rights reserved. * | |
* * | |
\***************************************************************/ | |
// @@BEGIN_DDKSPLIT | |
// ------------------------------------------------------------------------------- | |
// Introduction | |
// | |
// SpecStrings.h provides a set of annotations to describe how a function uses its | |
// parameters - the assumptions it makes about them, and the guarantees it makes | |
// upon finishing. | |
// | |
// Annotations may be placed before either a function parameter's type or its return | |
// type, and describe the function's behavior regarding the parameter or return value. | |
// There are two classes of annotations: buffer annotations and advanced annotations. | |
// Buffer annotations describe how functions use their pointer parameters, and | |
// advanced annotations either describe complex/unusual buffer behavior, or provide | |
// additional information about a parameter that is not otherwise expressible. | |
// | |
// ------------------------------------------------------------------------------- | |
// Buffer Annotations | |
// | |
// The most important annotations in SpecStrings.h provide a consistent way to annotate | |
// buffer parameters or return values for a function. Each of these annotations describes | |
// a single buffer (which could be a string, a fixed-length or variable-length array, | |
// or just a pointer) that the function interacts with: where it is, how large it is, | |
// how much is initialized, and what the function does with it. | |
// | |
// The appropriate macro for a given buffer can be constructed using the table below. | |
// Just pick the appropriate values from each category, and combine them together | |
// with a leading underscore. Some combinations of values do not make sense as buffer | |
// annotations. Only meaningful annotations can be added to your code; for a list of | |
// these, see the buffer annotation definitions section. | |
// | |
// Only a single buffer annotation should be used for each parameter. | |
// | |
// |------------|------------|---------|--------|----------|---------------| | |
// | Level | Usage | Size | Output | Optional | Parameters | | |
// |------------|------------|---------|--------|----------|---------------| | |
// | <> | <> | <> | <> | <> | <> | | |
// | _deref | _in | _ecount | _full | _opt | (size) | | |
// | _deref_opt | _out | _bcount | _part | | (size,length) | | |
// | | _inout | | | | | | |
// | | | | | | | | |
// |------------|------------|---------|--------|----------|---------------| | |
// | |
// Level: Describes the buffer pointer's level of indirection from the parameter or | |
// return value 'p'. | |
// | |
// <> : p is the buffer pointer. | |
// _deref : *p is the buffer pointer. p must not be NULL. | |
// _deref_opt : *p may be the buffer pointer. p may be NULL, in which case the rest of | |
// the annotation is ignored. | |
// | |
// Usage: Describes how the function uses the buffer. | |
// | |
// <> : The buffer is not accessed. If used on the return value or with _deref, the | |
// function will provide the buffer, and it will be uninitialized at exit. | |
// Otherwise, the caller must provide the buffer. This should only be used | |
// for alloc and free functions. | |
// _in : The function will only read from the buffer. The caller must provide the | |
// buffer and initialize it. | |
// _out : The function will only write to the buffer. If used on the return value or | |
// with _deref, the function will provide the buffer and initialize it. | |
// Otherwise, the caller must provide the buffer, and the function will | |
// initialize it. | |
// _inout : The function may freely read from and write to the buffer. The caller must | |
// provide the buffer and initialize it. If used with _deref, the buffer may | |
// be reallocated by the function. | |
// | |
// Size: Describes the total size of the buffer. This may be less than the space actually | |
// allocated for the buffer, in which case it describes the accessible amount. | |
// | |
// <> : No buffer size is given. If the type specifies the buffer size (such as | |
// with LPSTR and LPWSTR), that amount is used. Otherwise, the buffer is one | |
// element long. Must be used with _in, _out, or _inout. | |
// _ecount : The buffer size is an explicit element count. | |
// _bcount : The buffer size is an explicit byte count. | |
// | |
// Output: Describes how much of the buffer will be initialized by the function. For | |
// _inout buffers, this also describes how much is initialized at entry. Omit this | |
// category for _in buffers; they must be fully initialized by the caller. | |
// | |
// <> : The type specifies how much is initialized. For instance, a function initializing | |
// an LPWSTR must NULL-terminate the string. | |
// _full : The function initializes the entire buffer. | |
// _part : The function initializes part of the buffer, and explicitly indicates how much. | |
// | |
// Optional: Describes if the buffer itself is optional. | |
// | |
// <> : The pointer to the buffer must not be NULL. | |
// _opt : The pointer to the buffer might be NULL. It will be checked before being dereferenced. | |
// | |
// Parameters: Gives explicit counts for the size and length of the buffer. | |
// | |
// <> : There is no explicit count. Use when neither _ecount nor _bcount is used. | |
// (size) : Only the buffer's total size is given. Use with _ecount or _bcount but not _part. | |
// (size,length) : The buffer's total size and initialized length are given. Use with _ecount_part | |
// and _bcount_part. | |
// | |
// ------------------------------------------------------------------------------- | |
// Buffer Annotation Examples | |
// | |
// LWSTDAPI_(BOOL) StrToIntExA( | |
// LPCSTR pszString, // No annotation required, const implies __in. | |
// DWORD dwFlags, | |
// __out int *piRet // A pointer whose dereference will be filled in. | |
// ); | |
// | |
// void MyPaintingFunction( | |
// __in HWND hwndControl, // An initialized read-only parameter. | |
// __in_opt HDC hdcOptional, // An initialized read-only parameter that might be NULL. | |
// __inout IPropertyStore *ppsStore // An initialized parameter that may be freely used | |
// // and modified. | |
// ); | |
// | |
// LWSTDAPI_(BOOL) PathCompactPathExA( | |
// __out_ecount(cchMax) LPSTR pszOut, // A string buffer with cch elements that will | |
// // be NULL terminated on exit. | |
// LPCSTR pszSrc, // No annotation required, const implies __in. | |
// UINT cchMax, | |
// DWORD dwFlags | |
// ); | |
// | |
// HRESULT SHLocalAllocBytes( | |
// size_t cb, | |
// __deref_bcount(cb) T **ppv // A pointer whose dereference will be set to an | |
// // uninitialized buffer with cb bytes. | |
// ); | |
// | |
// __inout_bcount_full(cb) : A buffer with cb elements that is fully initialized at | |
// entry and exit, and may be written to by this function. | |
// | |
// __out_ecount_part(count, *countOut) : A buffer with count elements that will be | |
// partially initialized by this function. The function indicates how much it | |
// initialized by setting *countOut. | |
// | |
// ------------------------------------------------------------------------------- | |
// Advanced Annotations | |
// | |
// Advanced annotations describe behavior that is not expressible with the regular | |
// buffer macros. These may be used either to annotate buffer parameters that involve | |
// complex or conditional behavior, or to enrich existing annotations with additional | |
// information. | |
// | |
// __success(expr) f : | |
// <expr> indicates whether function f succeeded or not. If <expr> is true at exit, | |
// all the function's guarantees (as given by other annotations) must hold. If <expr> | |
// is false at exit, the caller should not expect any of the function's guarantees | |
// to hold. If not used, the function must always satisfy its guarantees. Added | |
// automatically to functions that indicate success in standard ways, such as by | |
// returning an HRESULT. | |
// | |
// __out_awcount(expr, size) p : | |
// Pointer p is a buffer whose size may be given in either bytes or elements. If | |
// <expr> is true, this acts like __out_bcount. If <expr> is false, this acts | |
// like __out_ecount. This should only be used to annotate old APIs. | |
// | |
// __in_awcount(expr, size) p : | |
// Pointer p is a buffer whose size may be given in either bytes or elements. If | |
// <expr> is true, this acts like __in_bcount. If <expr> is false, this acts | |
// like __in_ecount. This should only be used to annotate old APIs. | |
// | |
// __nullterminated p : | |
// Pointer p is a buffer that may be read or written up to and including the first | |
// NULL character or pointer. May be used on typedefs, which marks valid (properly | |
// initialized) instances of that type as being NULL-terminated. | |
// | |
// __nullnullterminated p : | |
// Pointer p is a buffer that may be read or written up to and including the first | |
// sequence of two NULL characters or pointers. May be used on typedefs, which marks | |
// valid instances of that type as being double-NULL terminated. | |
// | |
// __reserved v : | |
// Value v must be 0/NULL, reserved for future use. | |
// | |
// __checkReturn v : | |
// Return value v must not be ignored by callers of this function. | |
// | |
// __typefix(ctype) v : | |
// Value v should be treated as an instance of ctype, rather than its declared type. | |
// | |
// __override f : | |
// Specify C#-style 'override' behaviour for overriding virtual methods. | |
// | |
// __callback f : | |
// Function f can be used as a function pointer. | |
// | |
// __format_string p : | |
// Pointer p is a string that contains % markers in the style of printf. | |
// | |
// __blocksOn(resource) f : | |
// Function f blocks on the resource 'resource'. | |
// | |
// __fallthrough : | |
// Annotates switch statement labels where fall-through is desired, to distinguish | |
// from forgotten break statements. | |
// | |
// ------------------------------------------------------------------------------- | |
// Advanced Annotation Examples | |
// | |
// __success(return == TRUE) LWSTDAPI_(BOOL) | |
// PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) : | |
// pszBuf is only guaranteed to be NULL-terminated when TRUE is returned. | |
// | |
// typedef __nullterminated WCHAR* LPWSTR : Initialized LPWSTRs are NULL-terminated strings. | |
// | |
// __out_ecount(cch) __typefix(LPWSTR) void *psz : psz is a buffer parameter which will be | |
// a NULL-terminated WCHAR string at exit, and which initially contains cch WCHARs. | |
// | |
// ------------------------------------------------------------------------------- | |
// @@END_DDKSPLIT | |
#if _MSC_VER > 1000 | |
#pragma once | |
#endif // #if _MSC_VER > 1000 | |
#define __specstrings | |
#ifdef __cplusplus | |
#ifndef __nothrow | |
# define __nothrow __declspec(nothrow) | |
#endif | |
extern "C" { | |
#else | |
#ifndef __nothrow | |
# define __nothrow | |
#endif | |
#endif // #ifdef __cplusplus | |
// @@BEGIN_DDKSPLIT | |
// ------------------------------------------------------------------------------- | |
// Helper Macro Definitions | |
// | |
// These express behavior common to many of the high-level annotations. | |
// DO NOT USE THESE IN YOUR CODE. | |
// ------------------------------------------------------------------------------- | |
// The helper annotations are only understood by the compiler version used by various | |
// defect detection tools. When the regular compiler is running, they are defined into | |
// nothing, and do not affect the compiled code. | |
#if (_MSC_VER >= 1000) && !defined(MIDL_PASS) && defined(_PREFAST_) | |
// In the primitive __declspec("SAL_*") annotations "SAL" stands for Standard | |
// Annotation Language. These __declspec("SAL_*") annotations are the | |
// primitives the compiler understands and all high-level SpecString MACROs | |
// will decompose into these primivates. | |
#define SPECSTRINGIZE( x ) #x | |
// | |
// __null p | |
// __notnull p | |
// __maybenull p | |
// | |
// Annotates a pointer p. States that pointer p is null. Commonly used | |
// in the negated form __notnull or the possibly null form __maybenull. | |
// | |
#define __null __declspec("SAL_null") | |
#define __notnull __declspec("SAL_notnull") | |
#define __maybenull __declspec("SAL_maybenull") | |
// | |
// __readonly l | |
// __notreadonly l | |
// __mabyereadonly l | |
// | |
// Annotates a location l. States that location l is not modified after | |
// this point. If the annotation is placed on the precondition state of | |
// a function, the restriction only applies until the postcondition state | |
// of the function. __maybereadonly states that the annotated location | |
// may be modified, whereas __notreadonly states that a location must be | |
// modified. | |
// | |
#define __readonly __declspec("SAL_readonly") | |
#define __notreadonly __declspec("SAL_notreadonly") | |
#define __maybereadonly __declspec("SAL_maybereadonly") | |
// | |
// __valid v | |
// __notvalid v | |
// __maybevalid v | |
// | |
// Annotates any value v. States that the value satisfies all properties of | |
// valid values of its type. For example, for a string buffer, valid means | |
// that the buffer pointer is either NULL or points to a NULL-terminated string. | |
// | |
#define __valid __declspec("SAL_valid") | |
#define __notvalid __declspec("SAL_notvalid") | |
#define __maybevalid __declspec("SAL_maybevalid") | |
// | |
// __readableTo(extent) p | |
// | |
// Annotates a buffer pointer p. If the buffer can be read, extent describes | |
// how much of the buffer is readable. For a reader of the buffer, this is | |
// an explicit permission to read up to that amount, rather than a restriction to | |
// read only up to it. | |
// | |
#define __readableTo(extent) __declspec("SAL_readableTo("SPECSTRINGIZE(extent)")") | |
// | |
// __elem_readableTo(size) | |
// | |
// Annotates a buffer pointer p as being readable to size elements. | |
// | |
#define __elem_readableTo(size) __declspec("SAL_readableTo(elementCount("SPECSTRINGIZE(size)"))") | |
// | |
// __byte_readableTo(size) | |
// | |
// Annotates a buffer pointer p as being readable to size bytes. | |
// | |
#define __byte_readableTo(size) __declspec("SAL_readableTo(byteCount("SPECSTRINGIZE(size)"))") | |
// | |
// __writableTo(extent) p | |
// | |
// Annotates a buffer pointer p. If the buffer can be modified, extent | |
// describes how much of the buffer is writable (usually the allocation | |
// size). For a writer of the buffer, this is an explicit permission to | |
// write up to that amount, rather than a restriction to write only up to it. | |
// | |
#define __writableTo(size) __declspec("SAL_writableTo("SPECSTRINGIZE(size)")") | |
// | |
// __elem_writableTo(size) | |
// | |
// Annotates a buffer pointer p as being writable to size elements. | |
// | |
#define __elem_writableTo(size) __declspec("SAL_writableTo(elementCount("SPECSTRINGIZE(size)"))") | |
// | |
// __byte_writableTo(size) | |
// | |
// Annotates a buffer pointer p as being writable to size bytes. | |
// | |
#define __byte_writableTo(size) __declspec("SAL_writableTo(byteCount("SPECSTRINGIZE(size)"))") | |
// | |
// __deref p | |
// | |
// Annotates a pointer p. The next annotation applies one dereference down | |
// in the type. If readableTo(p, size) then the next annotation applies to | |
// all elements *(p+i) for which i satisfies the size. If p is a pointer | |
// to a struct, the next annotation applies to all fields of the struct. | |
// | |
#define __deref __declspec("SAL_deref") | |
// | |
// __pre __next_annotation | |
// | |
// The next annotation applies in the precondition state | |
// | |
#define __pre __declspec("SAL_pre") | |
// | |
// __post __next_annotation | |
// | |
// The next annotation applies in the postcondition state | |
// | |
#define __post __declspec("SAL_post") | |
// | |
// __precond(<expr>) | |
// | |
// When <expr> is true, the next annotation applies in the precondition state | |
// (currently not enabled) | |
// | |
#define __precond(expr) __pre | |
// | |
// __postcond(<expr>) | |
// | |
// When <expr> is true, the next annotation applies in the postcondition state | |
// (currently not enabled) | |
// | |
#define __postcond(expr) __post | |
// | |
// __exceptthat | |
// | |
// Given a set of annotations Q containing __exceptthat maybeP, the effect of | |
// the except clause is to erase any P or notP annotations (explicit or | |
// implied) within Q at the same level of dereferencing that the except | |
// clause appears, and to replace it with maybeP. | |
// | |
// Example 1: __valid __exceptthat __maybenull on a pointer p means that the | |
// pointer may be null, and is otherwise valid, thus overriding | |
// the implicit notnull annotation implied by __valid on | |
// pointers. | |
// | |
// Example 2: __valid __deref __exceptthat __maybenull on an int **p means | |
// that p is not null (implied by valid), but the elements | |
// pointed to by p could be null, and are otherwise valid. | |
// | |
#define __exceptthat __declspec("SAL_except") | |
// | |
// _refparam | |
// | |
// Added to all out parameter macros to indicate that they are all reference | |
// parameters. | |
// | |
#define __refparam __deref __notreadonly | |
// | |
// __inner_* | |
// | |
// Helper macros that directly correspond to certain high-level annotations. | |
// | |
// | |
// Macros to classify the entrypoints and indicate their category. | |
// | |
// | |
// Pre-defined control point categories include: RPC, LPC, DeviceDriver, UserToKernel, ISAPI, COM. | |
// | |
#define __inner_control_entrypoint(category) __declspec("SAL_entrypoint(controlEntry, "SPECSTRINGIZE(category)")") | |
// | |
// Pre-defined data entry point categories include: Registry, File, Network. | |
// | |
#define __inner_data_entrypoint(category) __declspec("SAL_entrypoint(dataEntry, "SPECSTRINGIZE(category)")") | |
#define __inner_success(expr) __declspec("SAL_success("SPECSTRINGIZE(expr)")") | |
#define __inner_checkReturn __declspec("SAL_checkReturn") | |
#define __inner_typefix(ctype) __declspec("SAL_typefix("SPECSTRINGIZE(ctype)")") | |
#define __inner_override __declspec("__override") | |
#define __inner_callback __declspec("__callback") | |
#define __inner_blocksOn(resource) __declspec("SAL_blocksOn("SPECSTRINGIZE(resource)")") | |
#define __inner_fallthrough_dec __inline __nothrow void __FallThrough() {} | |
#define __inner_fallthrough __FallThrough(); | |
#else | |
// @@END_DDKSPLIT | |
#ifndef __null | |
#define __null | |
#endif | |
#ifndef __notnull | |
#define __notnull | |
#endif | |
#ifndef __maybenull | |
#define __maybenull | |
#endif | |
#ifndef __readonly | |
#define __readonly | |
#endif | |
#ifndef __notreadonly | |
#define __notreadonly | |
#endif | |
#ifndef __maybereadonly | |
#define __maybereadonly | |
#endif | |
#ifndef __valid | |
#define __valid | |
#endif | |
#ifndef __notvalid | |
#define __notvalid | |
#endif | |
#ifndef __maybevalid | |
#define __maybevalid | |
#endif | |
#ifndef __readableTo | |
#define __readableTo(extent) | |
#endif | |
#ifndef __elem_readableTo | |
#define __elem_readableTo(size) | |
#endif | |
#ifndef __byte_readableTo | |
#define __byte_readableTo(size) | |
#endif | |
#ifndef __writableTo | |
#define __writableTo(size) | |
#endif | |
#ifndef __elem_writableTo | |
#define __elem_writableTo(size) | |
#endif | |
#ifndef __byte_writableTo | |
#define __byte_writableTo(size) | |
#endif | |
#ifndef __deref | |
#define __deref | |
#endif | |
#ifndef __pre | |
#define __pre | |
#endif | |
#ifndef __post | |
#define __post | |
#endif | |
#ifndef __precond | |
#define __precond(expr) | |
#endif | |
#ifndef __postcond | |
#define __postcond(expr) | |
#endif | |
#ifndef __exceptthat | |
#define __exceptthat | |
#endif | |
#ifndef __inner_success | |
#define __inner_success(expr) | |
#endif | |
#ifndef __inner_checkReturn | |
#define __inner_checkReturn | |
#endif | |
#ifndef __inner_typefix | |
#define __inner_typefix(ctype) | |
#endif | |
#ifndef __inner_override | |
#define __inner_override | |
#endif | |
#ifndef __inner_callback | |
#define __inner_callback | |
#endif | |
#ifndef __inner_blocksOn | |
#define __inner_blocksOn(resource) | |
#endif | |
#ifndef __inner_fallthrough_dec | |
#define __inner_fallthrough_dec | |
#endif | |
#ifndef __inner_fallthrough | |
#define __inner_fallthrough | |
#endif | |
#ifndef __refparam | |
#define __refparam | |
#endif | |
#ifndef __inner_control_entrypoint | |
#define __inner_control_entrypoint(category) | |
#endif | |
#ifndef __inner_data_entrypoint | |
#define __inner_data_entrypoint(category) | |
#endif | |
// @@BEGIN_DDKSPLIT | |
#endif // #if (_MSC_VER >= 1000) && !defined(MIDL_PASS) && defined(_PREFAST_) | |
// ------------------------------------------------------------------------------- | |
// Buffer Annotation Definitions | |
// | |
// Any of these may be used to directly annotate functions, but only one should | |
// be used for each parameter. To determine which annotation to use for a given | |
// buffer, use the table in the buffer annotations section. | |
// ------------------------------------------------------------------------------- | |
// @@END_DDKSPLIT | |
#ifndef __ecount | |
#define __ecount(size) __notnull __elem_writableTo(size) | |
#endif | |
#ifndef __bcount | |
#define __bcount(size) __notnull __byte_writableTo(size) | |
#endif | |
#ifndef __in | |
#define __in __pre __valid __pre __deref __readonly | |
#endif | |
#ifndef __in_ecount | |
#define __in_ecount(size) __in __pre __elem_readableTo(size) | |
#endif | |
#ifndef __in_bcount | |
#define __in_bcount(size) __in __pre __byte_readableTo(size) | |
#endif | |
#ifndef __out | |
#define __out __ecount(1) __post __valid __refparam | |
#endif | |
#ifndef __out_ecount | |
#define __out_ecount(size) __ecount(size) __post __valid __refparam | |
#endif | |
#ifndef __out_bcount | |
#define __out_bcount(size) __bcount(size) __post __valid __refparam | |
#endif | |
#ifndef __out_ecount_part | |
#define __out_ecount_part(size,length) __out_ecount(size) __post __elem_readableTo(length) | |
#endif | |
#ifndef __out_bcount_part | |
#define __out_bcount_part(size,length) __out_bcount(size) __post __byte_readableTo(length) | |
#endif | |
#ifndef __out_ecount_full | |
#define __out_ecount_full(size) __out_ecount_part(size,size) | |
#endif | |
#ifndef __out_bcount_full | |
#define __out_bcount_full(size) __out_bcount_part(size,size) | |
#endif | |
#ifndef __inout | |
#define __inout __pre __valid __post __valid __refparam | |
#endif | |
#ifndef __inout_ecount | |
#define __inout_ecount(size) __out_ecount(size) __pre __valid | |
#endif | |
#ifndef __inout_bcount | |
#define __inout_bcount(size) __out_bcount(size) __pre __valid | |
#endif | |
#ifndef __inout_ecount_part | |
#define __inout_ecount_part(size,length) __out_ecount_part(size,length) __pre __valid __pre __elem_readableTo(length) | |
#endif | |
#ifndef __inout_bcount_part | |
#define __inout_bcount_part(size,length) __out_bcount_part(size,length) __pre __valid __pre __byte_readableTo(length) | |
#endif | |
#ifndef __inout_ecount_full | |
#define __inout_ecount_full(size) __inout_ecount_part(size,size) | |
#endif | |
#ifndef __inout_bcount_full | |
#define __inout_bcount_full(size) __inout_bcount_part(size,size) | |
#endif | |
#ifndef __ecount_opt | |
#define __ecount_opt(size) __ecount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __bcount_opt | |
#define __bcount_opt(size) __bcount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __in_opt | |
#define __in_opt __in __exceptthat __maybenull | |
#endif | |
#ifndef __in_ecount_opt | |
#define __in_ecount_opt(size) __in_ecount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __in_bcount_opt | |
#define __in_bcount_opt(size) __in_bcount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __out_opt | |
#define __out_opt __out __exceptthat __maybenull | |
#endif | |
#ifndef __out_ecount_opt | |
#define __out_ecount_opt(size) __out_ecount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __out_bcount_opt | |
#define __out_bcount_opt(size) __out_bcount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __out_ecount_part_opt | |
#define __out_ecount_part_opt(size,length) __out_ecount_part(size,length) __exceptthat __maybenull | |
#endif | |
#ifndef __out_bcount_part_opt | |
#define __out_bcount_part_opt(size,length) __out_bcount_part(size,length) __exceptthat __maybenull | |
#endif | |
#ifndef __out_ecount_full_opt | |
#define __out_ecount_full_opt(size) __out_ecount_full(size) __exceptthat __maybenull | |
#endif | |
#ifndef __out_bcount_full_opt | |
#define __out_bcount_full_opt(size) __out_bcount_full(size) __exceptthat __maybenull | |
#endif | |
#ifndef __inout_opt | |
#define __inout_opt __inout __exceptthat __maybenull | |
#endif | |
#ifndef __inout_ecount_opt | |
#define __inout_ecount_opt(size) __inout_ecount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __inout_bcount_opt | |
#define __inout_bcount_opt(size) __inout_bcount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __inout_ecount_part_opt | |
#define __inout_ecount_part_opt(size,length) __inout_ecount_part(size,length) __exceptthat __maybenull | |
#endif | |
#ifndef __inout_bcount_part_opt | |
#define __inout_bcount_part_opt(size,length) __inout_bcount_part(size,length) __exceptthat __maybenull | |
#endif | |
#ifndef __inout_ecount_full_opt | |
#define __inout_ecount_full_opt(size) __inout_ecount_full(size) __exceptthat __maybenull | |
#endif | |
#ifndef __inout_bcount_full_opt | |
#define __inout_bcount_full_opt(size) __inout_bcount_full(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_ecount | |
#define __deref_ecount(size) __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __elem_writableTo(size) | |
#endif | |
#ifndef __deref_bcount | |
#define __deref_bcount(size) __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __byte_writableTo(size) | |
#endif | |
#ifndef __deref_in | |
#define __deref_in __in __pre __deref __deref __readonly | |
#endif | |
#ifndef __deref_in_ecount | |
#define __deref_in_ecount(size) __deref_in __pre __deref __elem_readableTo(size) | |
#endif | |
#ifndef __deref_in_bcount | |
#define __deref_in_bcount(size) __deref_in __pre __deref __byte_readableTo(size) | |
#endif | |
#ifndef __deref_out | |
#define __deref_out __deref_ecount(1) __post __deref __valid __refparam | |
#endif | |
#ifndef __deref_out_ecount | |
#define __deref_out_ecount(size) __deref_ecount(size) __post __deref __valid __refparam | |
#endif | |
#ifndef __deref_out_bcount | |
#define __deref_out_bcount(size) __deref_bcount(size) __post __deref __valid __refparam | |
#endif | |
#ifndef __deref_out_ecount_part | |
#define __deref_out_ecount_part(size,length) __deref_out_ecount(size) __post __deref __elem_readableTo(length) | |
#endif | |
#ifndef __deref_out_bcount_part | |
#define __deref_out_bcount_part(size,length) __deref_out_bcount(size) __post __deref __byte_readableTo(length) | |
#endif | |
#ifndef __deref_out_ecount_full | |
#define __deref_out_ecount_full(size) __deref_out_ecount_part(size,size) | |
#endif | |
#ifndef __deref_out_bcount_full | |
#define __deref_out_bcount_full(size) __deref_out_bcount_part(size,size) | |
#endif | |
#ifndef __deref_inout | |
#define __deref_inout __notnull __elem_readableTo(1) __pre __deref __valid __post __deref __valid __refparam | |
#endif | |
#ifndef __deref_inout_ecount | |
#define __deref_inout_ecount(size) __deref_inout __pre __deref __elem_writableTo(size) __post __deref __elem_writableTo(size) | |
#endif | |
#ifndef __deref_inout_bcount | |
#define __deref_inout_bcount(size) __deref_inout __pre __deref __byte_writableTo(size) __post __deref __byte_writableTo(size) | |
#endif | |
#ifndef __deref_inout_ecount_part | |
#define __deref_inout_ecount_part(size,length) __deref_inout_ecount(size) __pre __deref __elem_readableTo(length) __post __deref __elem_readableTo(length) | |
#endif | |
#ifndef __deref_inout_bcount_part | |
#define __deref_inout_bcount_part(size,length) __deref_inout_bcount(size) __pre __deref __byte_readableTo(length) __post __deref __byte_readableTo(length) | |
#endif | |
#ifndef __deref_inout_ecount_full | |
#define __deref_inout_ecount_full(size) __deref_inout_ecount_part(size,size) | |
#endif | |
#ifndef __deref_inout_bcount_full | |
#define __deref_inout_bcount_full(size) __deref_inout_bcount_part(size,size) | |
#endif | |
#ifndef __deref_ecount_opt | |
#define __deref_ecount_opt(size) __deref_ecount(size) __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_bcount_opt | |
#define __deref_bcount_opt(size) __deref_bcount(size) __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_in_opt | |
#define __deref_in_opt __deref_in __pre __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_in_ecount_opt | |
#define __deref_in_ecount_opt(size) __deref_in_ecount(size) __pre __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_in_bcount_opt | |
#define __deref_in_bcount_opt(size) __deref_in_bcount(size) __pre __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_out_opt | |
#define __deref_out_opt __deref_out __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_out_ecount_opt | |
#define __deref_out_ecount_opt(size) __deref_out_ecount(size) __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_out_bcount_opt | |
#define __deref_out_bcount_opt(size) __deref_out_bcount(size) __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_out_ecount_part_opt | |
#define __deref_out_ecount_part_opt(size,length) __deref_out_ecount_part(size,length) __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_out_bcount_part_opt | |
#define __deref_out_bcount_part_opt(size,length) __deref_out_bcount_part(size,length) __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_out_ecount_full_opt | |
#define __deref_out_ecount_full_opt(size) __deref_out_ecount_full(size) __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_out_bcount_full_opt | |
#define __deref_out_bcount_full_opt(size) __deref_out_bcount_full(size) __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_inout_opt | |
#define __deref_inout_opt __deref_inout __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_inout_ecount_opt | |
#define __deref_inout_ecount_opt(size) __deref_inout_ecount(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_inout_bcount_opt | |
#define __deref_inout_bcount_opt(size) __deref_inout_bcount(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_inout_ecount_part_opt | |
#define __deref_inout_ecount_part_opt(size,length) __deref_inout_ecount_part(size,length) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_inout_bcount_part_opt | |
#define __deref_inout_bcount_part_opt(size,length) __deref_inout_bcount_part(size,length) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_inout_ecount_full_opt | |
#define __deref_inout_ecount_full_opt(size) __deref_inout_ecount_full(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_inout_bcount_full_opt | |
#define __deref_inout_bcount_full_opt(size) __deref_inout_bcount_full(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_ecount | |
#define __deref_opt_ecount(size) __deref_ecount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_bcount | |
#define __deref_opt_bcount(size) __deref_bcount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_in | |
#define __deref_opt_in __deref_in __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_in_ecount | |
#define __deref_opt_in_ecount(size) __deref_in_ecount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_in_bcount | |
#define __deref_opt_in_bcount(size) __deref_in_bcount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out | |
#define __deref_opt_out __deref_out __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_ecount | |
#define __deref_opt_out_ecount(size) __deref_out_ecount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_bcount | |
#define __deref_opt_out_bcount(size) __deref_out_bcount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_ecount_part | |
#define __deref_opt_out_ecount_part(size,length) __deref_out_ecount_part(size,length) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_bcount_part | |
#define __deref_opt_out_bcount_part(size,length) __deref_out_bcount_part(size,length) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_ecount_full | |
#define __deref_opt_out_ecount_full(size) __deref_out_ecount_full(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_bcount_full | |
#define __deref_opt_out_bcount_full(size) __deref_out_bcount_full(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout | |
#define __deref_opt_inout __deref_inout __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_ecount | |
#define __deref_opt_inout_ecount(size) __deref_inout_ecount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_bcount | |
#define __deref_opt_inout_bcount(size) __deref_inout_bcount(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_ecount_part | |
#define __deref_opt_inout_ecount_part(size,length) __deref_inout_ecount_part(size,length) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_bcount_part | |
#define __deref_opt_inout_bcount_part(size,length) __deref_inout_bcount_part(size,length) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_ecount_full | |
#define __deref_opt_inout_ecount_full(size) __deref_inout_ecount_full(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_bcount_full | |
#define __deref_opt_inout_bcount_full(size) __deref_inout_bcount_full(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_ecount_opt | |
#define __deref_opt_ecount_opt(size) __deref_ecount_opt(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_bcount_opt | |
#define __deref_opt_bcount_opt(size) __deref_bcount_opt(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_in_opt | |
#define __deref_opt_in_opt __deref_in_opt __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_in_ecount_opt | |
#define __deref_opt_in_ecount_opt(size) __deref_in_ecount_opt(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_in_bcount_opt | |
#define __deref_opt_in_bcount_opt(size) __deref_in_bcount_opt(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_opt | |
#define __deref_opt_out_opt __deref_out_opt __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_ecount_opt | |
#define __deref_opt_out_ecount_opt(size) __deref_out_ecount_opt(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_bcount_opt | |
#define __deref_opt_out_bcount_opt(size) __deref_out_bcount_opt(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_ecount_part_opt | |
#define __deref_opt_out_ecount_part_opt(size,length) __deref_out_ecount_part_opt(size,length) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_bcount_part_opt | |
#define __deref_opt_out_bcount_part_opt(size,length) __deref_out_bcount_part_opt(size,length) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_ecount_full_opt | |
#define __deref_opt_out_ecount_full_opt(size) __deref_out_ecount_full_opt(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_out_bcount_full_opt | |
#define __deref_opt_out_bcount_full_opt(size) __deref_out_bcount_full_opt(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_opt | |
#define __deref_opt_inout_opt __deref_inout_opt __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_ecount_opt | |
#define __deref_opt_inout_ecount_opt(size) __deref_inout_ecount_opt(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_bcount_opt | |
#define __deref_opt_inout_bcount_opt(size) __deref_inout_bcount_opt(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_ecount_part_opt | |
#define __deref_opt_inout_ecount_part_opt(size,length) __deref_inout_ecount_part_opt(size,length) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_bcount_part_opt | |
#define __deref_opt_inout_bcount_part_opt(size,length) __deref_inout_bcount_part_opt(size,length) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_ecount_full_opt | |
#define __deref_opt_inout_ecount_full_opt(size) __deref_inout_ecount_full_opt(size) __exceptthat __maybenull | |
#endif | |
#ifndef __deref_opt_inout_bcount_full_opt | |
#define __deref_opt_inout_bcount_full_opt(size) __deref_inout_bcount_full_opt(size) __exceptthat __maybenull | |
#endif | |
// @@BEGIN_DDKSPLIT | |
// ------------------------------------------------------------------------------- | |
// Advanced Annotation Definitions | |
// | |
// Any of these may be used to directly annotate functions, and may be used in | |
// combination with each other or with regular buffer macros. For an explanation | |
// of each annotation, see the advanced annotations section. | |
// ------------------------------------------------------------------------------- | |
// @@END_DDKSPLIT | |
#ifndef __out_awcount | |
#define __out_awcount(expr,size) __pre __notnull \ | |
__precond(expr) __byte_writableTo(size) \ | |
__precond(!(expr)) __byte_writableTo((size)*2) \ | |
__post __valid __refparam | |
#endif | |
#ifndef __in_awcount | |
#define __in_awcount(expr,size) __pre __valid \ | |
__pre __deref __readonly \ | |
__precond(expr) __byte_readableTo(size) \ | |
__precond(!(expr)) __elem_readableTo(size) | |
#endif | |
#ifndef __success | |
#define __success(expr) __inner_success(expr) | |
#endif | |
#ifndef __nullterminated | |
#define __nullterminated __readableTo(sentinel(0)) | |
#endif | |
#ifndef __nullnullterminated | |
#define __nullnullterminated | |
#endif | |
#ifndef __reserved | |
#define __reserved __pre __null | |
#endif | |
#ifndef __checkReturn | |
#define __checkReturn __inner_checkReturn | |
#endif | |
#ifndef __typefix | |
#define __typefix(ctype) __inner_typefix(ctype) | |
#endif | |
#ifndef __override | |
#define __override __inner_override | |
#endif | |
#ifndef __callback | |
#define __callback __inner_callback | |
#endif | |
#ifndef __format_string | |
#define __format_string | |
#endif | |
#ifndef __blocksOn | |
#define __blocksOn(resource) __inner_blocksOn(resource) | |
#endif | |
#ifndef __control_entrypoint | |
#define __control_entrypoint(category) __inner_control_entrypoint(category) | |
#endif | |
#ifndef __data_entrypoint | |
#define __data_entrypoint(category) __inner_data_entrypoint(category) | |
#endif | |
#ifndef __fallthrough | |
__inner_fallthrough_dec | |
#define __fallthrough __inner_fallthrough | |
#endif | |
// ------------------------------------------------------------------------------- | |
// Deprecated Annotation Definitions | |
// | |
// These should be removed from existing code. | |
// ------------------------------------------------------------------------------- | |
// #define __opt __exceptthat __maybenull | |
#ifdef __cplusplus | |
} | |
#endif | |