diff options
Diffstat (limited to 'core/src/fxge/Microsoft SDK/include/specstrings.h')
| -rw-r--r-- | core/src/fxge/Microsoft SDK/include/specstrings.h | 978 |
1 files changed, 978 insertions, 0 deletions
diff --git a/core/src/fxge/Microsoft SDK/include/specstrings.h b/core/src/fxge/Microsoft SDK/include/specstrings.h new file mode 100644 index 0000000000..00cdd332ec --- /dev/null +++ b/core/src/fxge/Microsoft SDK/include/specstrings.h @@ -0,0 +1,978 @@ +/***************************************************************\
+* *
+* 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
+
|