xref: /external/pdfium/core/src/fxge/Microsoft SDK/include/specstrings.h

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