/***
*sal.h - markers for documenting the semantics of APIs
*
*       Copyright (c) Microsoft Corporation. All rights reserved.
*
*Purpose:
*       sal.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.
*
*       [Public]
*
****/

#pragma once
/*==========================================================================

   The macros are defined in 3 layers:

   _In_\_Out_ Layer:
   ----------------
   This layer provides the highest abstraction and its macros should be used
   in most cases. Its macros start with _In_, _Out_ or _Inout_. For the
   typical case they provide the most concise annotations.

   _Pre_\_Post_ Layer:
   ------------------
   The macros of this layer only should be used when there is no suitable macro
   in the _In_\_Out_ layer. Its macros start with _Pre_, _Post_, _Ret_,
   _Deref_pre_ _Deref_post_ and _Deref_ret_. This layer provides the most
   flexibility for annotations.

   Implementation Abstraction Layer:
   --------------------------------
   Macros from this layer should never be used directly. The layer only exists
   to hide the implementation of the annotation macros.


   Annotation Syntax:
   |--------------|----------|----------------|-----------------------------|
   |   Usage      | Nullness | ZeroTerminated |  Extent                     |
   |--------------|----------|----------------|-----------------------------|
   | _In_         | <>       | <>             | <>                          |
   | _Out_        | opt_     | z_             | [byte]cap_[c_|x_]( size )   |
   | _Inout_      |          |                | [byte]count_[c_|x_]( size ) |
   | _Deref_out_  |          |                | ptrdiff_cap_( ptr )         |
   |--------------|          |                | ptrdiff_count_( ptr )       |
   | _Ret_        |          |                |                             |
   | _Deref_ret_  |          |                |                             |
   |--------------|          |                |                             |
   | _Pre_        |          |                |                             |
   | _Post_       |          |                |                             |
   | _Deref_pre_  |          |                |                             |
   | _Deref_post_ |          |                |                             |
   |--------------|----------|----------------|-----------------------------|

   Usage:
   -----
   _In_, _Out_, _Inout_, _Pre_, _Post_, _Deref_pre_, _Deref_post_ are for
   formal parameters.
   _Ret_, _Deref_ret_ must be used for return values.

   Nullness:
   --------
   If the pointer can be NULL the annotation contains _opt. If the macro
   does not contain '_opt' the pointer may not be NULL.

   String Type:
   -----------
   _z: NullTerminated string
   for _In_ parameters the buffer must have the specified stringtype before the call
   for _Out_ parameters the buffer must have the specified stringtype after the call
   for _Inout_ parameters both conditions apply

   Extent Syntax:
   |------|---------------|---------------|
   | Unit | Writ\Readable | Argument Type |
   |------|---------------|---------------|
   |  <>  | cap_          | <>            |
   | byte | count_        | c_            |
   |      |               | x_            |
   |------|---------------|---------------|

   'cap' (capacity) describes the writable size of the buffer and is typically used
   with _Out_. The default unit is elements. Use 'bytecap' if the size is given in bytes
   'count' describes the readable size of the buffer and is typically used with _In_.
   The default unit is elements. Use 'bytecount' if the size is given in bytes.

   Argument syntax for cap_, bytecap_, count_, bytecount_:
   (<parameter>|return)[+n]  e.g. cch, return, cb+2

   If the buffer size is a constant expression use the c_ postfix.
   E.g. cap_c_(20), count_c_(MAX_PATH), bytecount_c_(16)

   If the buffer size is given by a limiting pointer use the ptrdiff_ versions
   of the macros.

   If the buffer size is neither a parameter nor a constant expression use the x_
   postfix. e.g. bytecount_x_(num*size) x_ annotations accept any arbitrary string.
   No analysis can be done for x_ annotations but they at least tell the tool that
   the buffer has some sort of extent description. x_ annotations might be supported
   by future compiler versions.

============================================================================*/

#define __ATTR_SAL

#ifdef _PREFAST_
// choose attribute or __declspec implementation
#ifndef _USE_DECLSPECS_FOR_SAL
#define _USE_DECLSPECS_FOR_SAL 0
#endif  /* _USE_DECLSPECS_FOR_SAL */

#if _USE_DECLSPECS_FOR_SAL
#undef _USE_ATTRIBUTES_FOR_SAL
#define _USE_ATTRIBUTES_FOR_SAL 0
#elif !defined (_USE_ATTRIBUTES_FOR_SAL)
#if _MSC_VER >= 1400 
#define _USE_ATTRIBUTES_FOR_SAL 1
#else  /* _MSC_VER >= 1400  */
#define _USE_ATTRIBUTES_FOR_SAL 0
#endif  /* _MSC_VER >= 1400  */
#endif  /* !defined (_USE_ATTRIBUTES_FOR_SAL) */


#if !_USE_DECLSPECS_FOR_SAL
#if !_USE_ATTRIBUTES_FOR_SAL
#if _MSC_VER >= 1400 
#undef _USE_ATTRIBUTES_FOR_SAL
#define _USE_ATTRIBUTES_FOR_SAL 1
#else  /* _MSC_VER >= 1400  */
#undef _USE_DECLSPECS_FOR_SAL
#define _USE_DECLSPECS_FOR_SAL  1
#endif  /* _MSC_VER >= 1400  */
#endif  /* !_USE_ATTRIBUTES_FOR_SAL */
#endif  /* !_USE_DECLSPECS_FOR_SAL */

#endif  /* _PREFAST_ */

// Disable expansion of SAL macros in non-Prefast mode to
// improve compiler throughput.
#ifndef _USE_DECLSPECS_FOR_SAL
#define _USE_DECLSPECS_FOR_SAL 0
#endif  /* _USE_DECLSPECS_FOR_SAL */
#ifndef _USE_ATTRIBUTES_FOR_SAL
#define _USE_ATTRIBUTES_FOR_SAL 0
#endif  /* _USE_ATTRIBUTES_FOR_SAL */

// safeguard for MIDL and RC builds
#if _USE_DECLSPECS_FOR_SAL && (defined (MIDL_PASS) || defined (__midl) || defined (RC_INVOKED) || !defined (_PREFAST_))
#undef _USE_DECLSPECS_FOR_SAL
#define _USE_DECLSPECS_FOR_SAL 0
#endif  /* _USE_DECLSPECS_FOR_SAL && (defined (MIDL_PASS) || defined (__midl) || defined (RC_INVOKED) || !defined (_PREFAST_)) */
#if _USE_ATTRIBUTES_FOR_SAL && (!defined (_MSC_EXTENSIONS) || defined (MIDL_PASS) || defined (__midl) || defined (RC_INVOKED))
#undef _USE_ATTRIBUTES_FOR_SAL
#define _USE_ATTRIBUTES_FOR_SAL 0
#endif  /* _USE_ATTRIBUTES_FOR_SAL && (!defined (_MSC_EXTENSIONS) || defined (MIDL_PASS) || defined (__midl) || defined (RC_INVOKED)) */

#if defined (_MSC_EXTENSIONS) && !defined (MIDL_PASS) && !defined (__midl) && !defined (RC_INVOKED)
#include "codeanalysis\sourceannotations.h"
#endif  /* defined (_MSC_EXTENSIONS) && !defined (MIDL_PASS) && !defined (__midl) && !defined (RC_INVOKED) */

//============================================================================
//   _In_\_Out_ Layer:
//============================================================================

// 'in' parameters --------------------------

// input pointer parameter
// e.g. void SetPoint( _In_ const POINT* pPT );
#define _In_                           _Pre1_impl_(_$notnull) _Deref_pre2_impl_(_$valid, _$readaccess)
#define _In_opt_                       _Pre_opt_valid_ _Deref_pre_readonly_

// nullterminated 'in' parameters.
// e.g. void CopyStr( _In_z_ const char* szFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo );
#define _In_z_                         _Pre_z_      _Deref_pre_readonly_
#define _In_opt_z_                     _Pre_opt_z_  _Deref_pre_readonly_

// 'input' buffers with given size

// e.g. void SetCharRange( _In_count_(cch) const char* rgch, size_t cch )
// valid buffer extent described by another parameter
#define _In_count_(size)              _Pre_count_(size)         _Deref_pre_readonly_
#define _In_opt_count_(size)          _Pre_opt_count_(size)     _Deref_pre_readonly_
#define _In_bytecount_(size)          _Pre_bytecount_(size)     _Deref_pre_readonly_
#define _In_opt_bytecount_(size)      _Pre_opt_bytecount_(size) _Deref_pre_readonly_

// valid buffer extent described by a constant extression
#define _In_count_c_(size)            _Pre_count_c_(size)         _Deref_pre_readonly_
#define _In_opt_count_c_(size)        _Pre_opt_count_c_(size)     _Deref_pre_readonly_
#define _In_bytecount_c_(size)        _Pre_bytecount_c_(size)     _Deref_pre_readonly_
#define _In_opt_bytecount_c_(size)    _Pre_opt_bytecount_c_(size) _Deref_pre_readonly_

// nullterminated  'input' buffers with given size

// e.g. void SetCharRange( _In_count_(cch) const char* rgch, size_t cch )
// nullterminated valid buffer extent described by another parameter
#define _In_z_count_(size)              _Pre_z_ _Pre_count_(size)         _Deref_pre_readonly_
#define _In_opt_z_count_(size)          _Pre_opt_z_ _Pre_opt_count_(size)     _Deref_pre_readonly_
#define _In_z_bytecount_(size)          _Pre_z_ _Pre_bytecount_(size)     _Deref_pre_readonly_
#define _In_opt_z_bytecount_(size)      _Pre_opt_z_ _Pre_opt_bytecount_(size) _Deref_pre_readonly_

// nullterminated valid buffer extent described by a constant extression
#define _In_z_count_c_(size)            _Pre_z_ _Pre_count_c_(size)         _Deref_pre_readonly_
#define _In_opt_z_count_c_(size)        _Pre_opt_z_ _Pre_opt_count_c_(size)     _Deref_pre_readonly_