| /***************************************************************\ |
| * * |
| * 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 |
| |
