Alien-FreeImage
view release on metacpan or search on metacpan
src/Source/LibJXR/common/include/wmspecstrings_strict.h view on Meta::CPAN
//*@@@+++@@@@******************************************************************
//
// Copyright © Microsoft Corp.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:
//
// • Redistributions of source code must retain the above copyright notice,
// this list of conditions and the following disclaimer.
// • Redistributions in binary form must reproduce the above copyright notice,
// this list of conditions and the following disclaimer in the documentation
// and/or other materials provided with the distribution.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
//
//*@@@---@@@@******************************************************************
/*************************************************************************
* This file documents all the macros approved for use in windows source
* code. It includes some experimental macros which should only be used by
* experts.
*
* DO NOT include this file directly. This file is include after
* specstrings.h. So we can undefine every possible old definition including
* private internal macros people should not be using, as well as macros from
* sal.h. Macros are redefined here in a way to cause syntax errors when used
* incorrectly during a normal build when specstrings.h is included and
* __SPECSTRINGS_STRICT_LEVEL is defined.
*
* There are several levels of strictness, each level includes the behavior of
* all previous levels.
*
* 0 - Disable strict checking
* 1 - Break on unapproved macros and misuse of statement
* macros such as __fallthrough (default)
* 2 - Deprecated some old macros that should not be used
* 3 - Use VS 2005 Source Annotation to make sure every macro
* is used in the right context. For example placing __in on a return
* parameter will result in an error.
************************************************************************/
#ifndef __SPECSTRINGS_STRICT_LEVEL
#define __SPECSTRINGS_STRICT_LEVEL 1
#endif
/************************************************************************
* 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 must be placed before a function parameter's type or its return
* type. There are two basic classes of common 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 | | | | |
* | | | | | | |
* |------------|------------|---------|--------|----------|---------------|
*
* Note: "<>" represents the empty string.
src/Source/LibJXR/common/include/wmspecstrings_strict.h view on Meta::CPAN
* exact range can't be specified at compile time. __in_range should be
* used if the range can be explicitly stated.
*
* __out_bound int i : Postcondition that integer i must be bound, but the
* exact range can't be specified at compile time. __out_range should be
* used if the range can be explicitly stated.
*
* __deref_out_bound int pi : Postcondition that integer *pi must be bound,
* but the exact range can't be specified at compile time.
* __deref_out_range should be used if the range can be explicitly stated.
*
* __assume_bound(expr); : Assume that the expression is bound to some known
* range. This can be used to suppress integer overflow warnings on integral
* expressions that are known to be bound due to reasons not explicit in the
* code. Use as a statement in the body of a function.
*
* __allocator void f(): Function allocates memory using an integral size
* argument
*
* ----------------------------------------------------------------------------
* 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.
*
* // Initialized LPWSTRs are null-terminated strings.
* typedef __nullterminated WCHAR* LPWSTR;
*
* __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.
*
************************************************************************/
#define __success(expr) __allowed(on_function_or_typedecl)
#define __out_awcount(expr,size) __allowed(on_parameter)
#define __in_awcount(expr,size) __allowed(on_parameter)
#define __nullterminated __allowed(on_typedecl)
#define __nullnullterminated __allowed(on_typedecl)
#define __reserved __allowed(on_parameter)
#define __checkReturn __allowed(on_function)
#define __typefix(ctype) __allowed(on_parameter_or_return)
#define __override __allowed(on_function)
#define __callback __allowed(on_function)
#define __format_string __allowed(on_parameter_or_return)
#define __blocksOn(resource) __allowed(on_function)
#define __fallthrough __allowed(as_statement)
#define __range(lb,ub) __allowed(on_return)
#define __in_range(lb,ub) __allowed(on_parameter)
#define __out_range(lb,ub) __allowed(on_parameter)
#define __deref_in_range(lb,ub) __allowed(on_parameter)
#define __deref_out_range(lb,ub) __allowed(on_parameter)
#define __field_range(lb,ub) __allowed(on_field)
#define __bound __allowed(on_return)
#define __in_bound __allowed(on_parameter)
#define __out_bound __allowed(on_parameter)
#define __deref_out_bound __allowed(on_parameter)
#define __assume_bound(i) __allowed(as_statement_with_arg(i))
#define __allocator __allowed(on_function)
/***************************************************************************
* Expert Macros
***************************************************************************/
#define __null __allowed(on_typedecl)
#define __notnull __allowed(on_typedecl)
#define __maybenull __allowed(on_typedecl)
#define __exceptthat __allowed(on_typedecl)
/***************************************************************************
* Macros to classify fields of structures.
* Structure Annotations
*
* The buffer annotations are a convenient way of describing
* relationships between buffers and their size on a function by
* function basis. Very often struct or class data members have similar
* invariants, which can be expressed directly on the type.
*
* Similar to our buffer annotations we can summarize all the various
* structure annotations by one choosing an element from each column of
* this table to build a composite annotation.
*
* +--------------------------------------------------+
* | Selector | Units | Size/Init | Optional |
* |----------+---------+------------------+----------|
* | __field | _ecount | (size) | empty |
* |----------+---------+------------------+----------|
* | __struct | _bcount | _full(size) | _opt |
* |----------+---------+------------------+----------|
* | | _xcount | _part(size,init) | |
* +--------------------------------------------------+
*
* Note that empty represents the empty string. Sometime arguments need
* to be "floated" to the left to give us a valid annotation name. For
* example the naive combination __field_ecount(size)_opt is actually
* written as __field_ecount_opt(size). Not all possible combinations
* are currently supported or sensible. See specstrings_strict.h for
* the currently supported set. Those that are supported are documented
* below.
*
*Summary of Elements
*
* Selector
*
* __field
* The annotation should only be placed in front
* of data members of structures and classes. The
* data members are pointers to a block of data.
* The annotations describe properties about the
* size of the block of data. This can be used for
*
* __struct
* The annotation should only be placed at the
* beginning of the definition of a structure or
* class. These annotations are used when a struct
* or class is used as a "header" that is
* allocated inline with a block of data and there
* is no apparent field that represents the tail
* end of the structure.
*
* Units
*
* _ecount
* All size and initialization values are in terms
* of elements of the appropriate type
*
* _bcount
* All size and initialization values are in terms
* of raw byte sizes.
*
* _xcount
src/Source/LibJXR/common/include/wmspecstrings_strict.h view on Meta::CPAN
* void WriteBuf(__in FILE *fp,__in struct *buf_s b) {
* fwrite(b->buf,b->sz,sizeof(char),fp);
* }
* void ReadBuf(__in FILE *fp,__inout struct *buf_s b) {
* fread(b->buf,b->sz,sizeof(char),fp);
* }
*
*
*
* // Inline Allocated Buffer
* struct buf_s {
* int sz;
* __field_bcount(sz)
* char buf[1];
* };
* void WriteBuf(__in FILE *fp,__in struct *buf_s b) {
* fwrite(&(b->buf),b->sz,sizeof(char),fp);
* }
* void ReadBuf(__in FILE *fp,__inout struct *buf_s b) {
* fread(&(b->buf),b->sz,sizeof(char),fp);
* }
*
*
*
* // Embedded Header Structure
* __struct_bcount(sz)
* struct buf_s {
* int sz;
* };
* void WriteBuf(__in FILE *fp,__in struct *buf_s b) {
* fwrite(&b,b->sz,sizeof(char),fp);
* }
* void ReadBuf(__in FILE *fp,__inout struct *buf_s b) {
* fread(&b,b->sz,sizeof(char),fp);
* }
*
*
****************************************************************************/
#define __field_ecount(size) __allowed(on_field)
#define __field_bcount(size) __allowed(on_field)
#define __field_xcount(size) __allowed(on_field)
#define __field_ecount_opt(size) __allowed(on_field)
#define __field_bcount_opt(size) __allowed(on_field)
#define __field_xcount_opt(size) __allowed(on_field)
#define __field_ecount_part(size,init) __allowed(on_field)
#define __field_bcount_part(size,init) __allowed(on_field)
#define __field_xcount_part(size,init) __allowed(on_field)
#define __field_ecount_part_opt(size,init) __allowed(on_field)
#define __field_bcount_part_opt(size,init) __allowed(on_field)
#define __field_xcount_part_opt(size,init) __allowed(on_field)
#define __field_ecount_full(size) __allowed(on_field)
#define __field_bcount_full(size) __allowed(on_field)
#define __field_xcount_full(size) __allowed(on_field)
#define __field_ecount_full_opt(size) __allowed(on_field)
#define __field_bcount_full_opt(size) __allowed(on_field)
#define __field_xcount_full_opt(size) __allowed(on_field)
#define __struct_bcount(size) __allowed(on_struct)
#define __struct_xcount(size) __allowed(on_struct)
/***************************************************************************
* Macros to classify the entrypoints and indicate their category.
*
* Pre-defined control point categories include: RPC, KERNEL, GDI.
*
* Pre-defined control point macros include:
* __rpc_entry, __kernel_entry, __gdi_entry.
***************************************************************************/
#define __control_entrypoint(category) __allowed(on_function)
#define __rpc_entry __allowed(on_function)
#define __kernel_entry __allowed(on_function)
#define __gdi_entry __allowed(on_function)
/***************************************************************************
* Macros to track untrusted data and their validation. The list of untrusted
* sources include:
*
* FILE - File reading stream or API
* NETWORK - Socket readers
* INTERNET - WinInet and WinHttp readers
* USER_REGISTRY - HKCU portions of the registry
* USER_MODE - Parameters to kernel entry points
* RPC - Parameters to RPC entry points
* DRIVER - Device driver
***************************************************************************/
#define __in_data_source(src_sym) __allowed(on_parameter)
#define __out_data_source(src_sym) __allowed(on_parameter)
#define __field_data_source(src_sym) __allowed(on_field)
#define __this_out_data_source(src_syn) __allowed(on_function)
/**************************************************************************
* Macros to tag file parsing code. Predefined formats include:
* PNG - Portable Network Graphics
* JPEG - Joint Photographic Experts Group
* BMP - Bitmap
* RC_BMP - Resource bitmap
* WMF - Windows Metafile
* EMF - Windows Enhanced Metafile
* GIF - Graphics Interchange Format
* MIME_TYPE - MIME type from header tokens
* MAIL_MONIKER - MAIL information refered by URL moniker
* HTML - HyperText Markup Language
* WMPHOTO - Windows media photo
* OE_VCARD - Outlook Express virtual card
* OE_CONTACT - Outlook Express contact
* MIDI - Musical Instrument Digital Interface
* LDIF - LDAP Data Interchange Format
* AVI - Audio Visual Interchange
* ACM - Audio Compression Manager
**************************************************************************/
#define __out_validated(filetype_sym) __allowed(on_parameter)
#define __this_out_validated(filetype_sym) __allowed(on_function)
#define __file_parser(filetype_sym) __allowed(on_function)
#define __file_parser_class(filetype_sym) __allowed(on_struct)
#define __file_parser_library(filetype_sym) __allowed(as_global_decl)
/***************************************************************************
* Macros to track the code content in the file. The type of code
* contents currently tracked:
*
* NDIS_DRIVER - NDIS Device driver
***************************************************************************/
#define __source_code_content(codetype_sym) __allowed(as_global_decl)
/***************************************************************************
* Macros to track the code content in the class. The type of code
* contents currently tracked:
*
* DCOM - Class implementing DCOM
***************************************************************************/
#define __class_code_content(codetype_sym) __allowed(on_struct)
/*************************************************************************
* Macros to tag encoded function pointers
**************************************************************************/
#define __encoded_pointer
#define __encoded_array
#define __field_encoded_pointer __allowed(on_field)
#define __field_encoded_array __allowed(on_field)
#define __transfer(formal) __allowed(on_parameter_or_return)
#define __assume_validated(exp) __allowed(as_statement_with_arg(exp))
/*************************************************************************
* __analysis_assume(expr) : Expert macro use only when directed. Use this to
* tell static analysis tools like PREfix and PREfast about a non-coded
* assumption that you wish the tools to assume. The assumption will be
* understood by those tools. By default there is no dynamic checking or
* static checking of the assumption in any build.
*
* To obtain dynamic checking wrap this macro in your local version of a debug
* assert.
* Please do not put function calls in the expression because this is not
* supported by all tools:
* __analysis_assume(GetObject () != NULL); // DO NOT DO THIS
*
*************************************************************************/
#define __analysis_assume(expr) __allowed(as_statement_with_arg(expr))
#define __analysis_assert(expr) __allowed(as_statement_with_arg(expr))
/*************************************************************************
* __analysis_hint(hint_sym) : Expert macro use only when
* directed. Use this to influence certain analysis heuristics
* used by the tools. These hints do not describe the semantics
* of functions but simply direct the tools to act in a certain
* way.
*
* Current hints that are supported are:
*
* INLINE - inline this function during analysis overrides any
* default heuristics
* NOINLINE - do not inline this function during analysis overrides
* and default heuristics
*************************************************************************/
#define __analysis_hint(hint) __allowed(on_function)
/*************************************************************************
* Macros to encode abstract properties of values. Used by SALadt.h
*************************************************************************/
#define __type_has_adt_prop(adt,prop) __allowed(on_typdecl)
#define __out_has_adt_prop(adt,prop) __allowed(on_parameter)
#define __out_not_has_adt_prop(adt,prop) __allowed(on_parameter)
#define __out_transfer_adt_prop(arg) __allowed(on_parameter)
#define __out_has_type_adt_props(typ) __allowed(on_parameter)
#define __assume_ValidCompNameA(expr) __allowed(as_statement_with_arg(expr))
#define __assume_ValidCompNameW(expr) __allowed(as_statement_with_arg(expr))
/*************************************************************************
* Macros used by Prefast for Drivers
*
* __possibly_notnulltermiated :
*
* Used for return values of parameters or functions that do not
* guarantee nullterimination in all cases.
*
*************************************************************************/
#define __possibly_notnulltermiated __allowed(on_parameter_or_return)
/*************************************************************************
* Advanced macros
*
* __volatile
* The __volatile annotation identifies a global variable or
* structure field that:
* 1) is not declared volatile;
* 2) is accessed concurrently by multiple threads.
*
* The __deref_volatile annotation identifies a global variable
* or structure field that stores a pointer to some data that:
* 1) is not declared volatile;
* 2) is accessed concurrently by multiple threads.
*
* Prefast uses these annotations to find patterns of code that
* may result in unexpected re-fetching of the global variable
* into a local variable.
*
* We also provide two complimentary annotations __nonvolatile
* and __deref_nonvolatile that could be used to suppress Prefast
*
* re-fetching warnings on variables that are known either:
* 1) not to be in danger of being re-fetched or,
* 2) not to lead to incorrect results if they are re-fetched
*
*************************************************************************/
#define __volatile __allowed(on_global_or_field)
#define __deref_volatile __allowed(on_global_or_field)
#define __nonvolatile __allowed(on_global_or_field)
#define __deref_nonvolatile __allowed(on_global_or_field)
/*************************************************************************
* Macros deprecated with strict level greater then 1.
**************************************************************************/
#if (__SPECSTRINGS_STRICT_LEVEL > 1)
/* Must come before macro defintions */
#pragma deprecated(__in_nz)
#pragma deprecated(__in_ecount_nz)
#pragma deprecated(__in_bcount_nz)
#pragma deprecated(__out_nz)
#pragma deprecated(__out_nz_opt)
#pragma deprecated(__out_ecount_nz)
#pragma deprecated(__out_bcount_nz)
#pragma deprecated(__inout_nz)
#pragma deprecated(__inout_ecount_nz)
#pragma deprecated(__inout_bcount_nz)
#pragma deprecated(__in_nz_opt)
#pragma deprecated(__in_ecount_nz_opt)
#pragma deprecated(__in_bcount_nz_opt)
#pragma deprecated(__out_ecount_nz_opt)
#pragma deprecated(__out_bcount_nz_opt)
#pragma deprecated(__inout_nz_opt)
#pragma deprecated(__inout_ecount_nz_opt)
#pragma deprecated(__inout_bcount_nz_opt)
#pragma deprecated(__deref_out_nz)
#pragma deprecated(__deref_out_ecount_nz)
#pragma deprecated(__deref_out_bcount_nz)
#pragma deprecated(__deref_inout_nz)
#pragma deprecated(__deref_inout_ecount_nz)
#pragma deprecated(__deref_inout_bcount_nz)
#pragma deprecated(__deref_out_nz_opt)
#pragma deprecated(__deref_out_ecount_nz_opt)
#pragma deprecated(__deref_out_bcount_nz_opt)
#pragma deprecated(__deref_inout_nz_opt)
#pragma deprecated(__deref_inout_ecount_nz_opt)
#pragma deprecated(__deref_inout_bcount_nz_opt)
#pragma deprecated(__deref_opt_inout_nz)
#pragma deprecated(__deref_opt_inout_ecount_nz)
#pragma deprecated(__deref_opt_inout_bcount_nz)
#pragma deprecated(__deref_opt_out_nz_opt)
#pragma deprecated(__deref_opt_out_ecount_nz_opt)
#pragma deprecated(__deref_opt_out_bcount_nz_opt)
#pragma deprecated(__deref_opt_inout_nz_opt)
#pragma deprecated(__deref_opt_inout_ecount_nz_opt)
#pragma deprecated(__deref_opt_inout_bcount_nz_opt)
#pragma deprecated(__deref)
#pragma deprecated(__pre)
#pragma deprecated(__post)
#pragma deprecated(__readableTo)
#pragma deprecated(__writableTo)
#pragma deprecated(__maybevalid)
#pragma deprecated(__data_entrypoint)
#pragma deprecated(__inexpressible_readableTo)
#pragma deprecated(__readonly)
#pragma deprecated(__byte_writableTo)
#pragma deprecated(__byte_readableTo)
#pragma deprecated(__elem_readableTo)
#pragma deprecated(__elem_writableTo)
#pragma deprecated(__valid)
#pragma deprecated(__notvalid)
#pragma deprecated(__refparam)
#pragma deprecated(__precond)
#endif
( run in 0.291 second using v1.01-cache-2.11-cpan-0bd6704ced7 )