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