From 3f3b45cc74b0499912409f766a595945dbbfc4c5 Mon Sep 17 00:00:00 2001 From: John Abd-El-Malek Date: Fri, 23 May 2014 17:28:10 -0700 Subject: Convert all line endings to LF. --- core/src/fxge/Microsoft SDK/include/sal.h | 1458 ++++++++++++++--------------- 1 file changed, 729 insertions(+), 729 deletions(-) (limited to 'core/src/fxge/Microsoft SDK/include/sal.h') diff --git a/core/src/fxge/Microsoft SDK/include/sal.h b/core/src/fxge/Microsoft SDK/include/sal.h index 136996974a..07234950cd 100644 --- a/core/src/fxge/Microsoft SDK/include/sal.h +++ b/core/src/fxge/Microsoft SDK/include/sal.h @@ -1,729 +1,729 @@ -/*** -*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] -* -****/ - -/* - ------------------------------------------------------------------------------- - Introduction - - 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. - - 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 sal.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 | NullTerm | Optional | Parameters | - |------------|------------|---------|--------|----------|----------|---------------| - | <> | <> | <> | <> | _z | <> | <> | - | _deref | _in | _ecount | _full | _nz | _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. Cannot be used with _deref. - _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. - - NullTerm: States if the present of a '\0' marks the end of valid elements in the buffer. - _z : A '\0' indicated the end of the buffer - _nz : The buffer may not be null terminated and a '\0' does not indicate the end of the - buffer. - 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 : - indicates whether function f succeeded or not. If is true at exit, - all the function's guarantees (as given by other annotations) must hold. If - 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. - - __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. - - ------------------------------------------------------------------------------- -*/ - -#pragma once - -#define __specstrings - -#ifdef __cplusplus -#ifndef __nothrow -# define __nothrow __declspec(nothrow) -#endif -extern "C" { -#else -#ifndef __nothrow -# define __nothrow -#endif -#endif /* #ifdef __cplusplus */ - -/* - ------------------------------------------------------------------------------- - 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 !defined(__midl) && 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() - - When is true, the next annotation applies in the precondition state - (currently not enabled) - */ - #define __precond(expr) __pre - - /* - __postcond() - - When 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") - #define __execeptthat __exceptthat - - /* - _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 - #define __null - #define __notnull - #define __maybenull - #define __readonly - #define __notreadonly - #define __maybereadonly - #define __valid - #define __notvalid - #define __maybevalid - #define __readableTo(extent) - #define __elem_readableTo(size) - #define __byte_readableTo(size) - #define __writableTo(size) - #define __elem_writableTo(size) - #define __byte_writableTo(size) - #define __deref - #define __pre - #define __post - #define __precond(expr) - #define __postcond(expr) - #define __exceptthat - #define __execeptthat - #define __inner_success(expr) - #define __inner_checkReturn - #define __inner_typefix(ctype) - #define __inner_override - #define __inner_callback - #define __inner_blocksOn(resource) - #define __inner_fallthrough_dec - #define __inner_fallthrough - #define __refparam - #define __inner_control_entrypoint(category) - #define __inner_data_entrypoint(category) -#endif /* #if !defined(__midl) && 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. -------------------------------------------------------------------------------- -*/ - -#define __ecount(size) __notnull __elem_writableTo(size) -#define __bcount(size) __notnull __byte_writableTo(size) -#define __in __pre __valid __pre __deref __readonly -#define __in_ecount(size) __in __pre __elem_readableTo(size) -#define __in_bcount(size) __in __pre __byte_readableTo(size) -#define __in_z __in __pre __nullterminated -#define __in_ecount_z(size) __in_ecount(size) __pre __nullterminated -#define __in_bcount_z(size) __in_bcount(size) __pre __nullterminated -#define __in_nz __in -#define __in_ecount_nz(size) __in_ecount(size) -#define __in_bcount_nz(size) __in_bcount(size) -#define __out __ecount(1) __post __valid __refparam -#define __out_ecount(size) __ecount(size) __post __valid __refparam -#define __out_bcount(size) __bcount(size) __post __valid __refparam -#define __out_ecount_part(size,length) __out_ecount(size) __post __elem_readableTo(length) -#define __out_bcount_part(size,length) __out_bcount(size) __post __byte_readableTo(length) -#define __out_ecount_full(size) __out_ecount_part(size,size) -#define __out_bcount_full(size) __out_bcount_part(size,size) -#define __out_z __post __valid __refparam __post __nullterminated -#define __out_z_opt __post __valid __refparam __post __nullterminated __exceptthat __maybenull -#define __out_ecount_z(size) __ecount(size) __post __valid __refparam __post __nullterminated -#define __out_bcount_z(size) __bcount(size) __post __valid __refparam __post __nullterminated -#define __out_ecount_part_z(size,length) __out_ecount_part(size,length) __post __nullterminated -#define __out_bcount_part_z(size,length) __out_bcount_part(size,length) __post __nullterminated -#define __out_ecount_full_z(size) __out_ecount_full(size) __post __nullterminated -#define __out_bcount_full_z(size) __out_bcount_full(size) __post __nullterminated -#define __out_nz __post __valid __refparam __post -#define __out_nz_opt __post __valid __refparam __post __exceptthat __maybenull -#define __out_ecount_nz(size) __ecount(size) __post __valid __refparam -#define __out_bcount_nz(size) __bcount(size) __post __valid __refparam -#define __inout __pre __valid __post __valid __refparam -#define __inout_ecount(size) __out_ecount(size) __pre __valid -#define __inout_bcount(size) __out_bcount(size) __pre __valid -#define __inout_ecount_part(size,length) __out_ecount_part(size,length) __pre __valid __pre __elem_readableTo(length) -#define __inout_bcount_part(size,length) __out_bcount_part(size,length) __pre __valid __pre __byte_readableTo(length) -#define __inout_ecount_full(size) __inout_ecount_part(size,size) -#define __inout_bcount_full(size) __inout_bcount_part(size,size) -#define __inout_z __inout __pre __nullterminated __post __nullterminated -#define __inout_ecount_z(size) __inout_ecount(size) __pre __nullterminated __post __nullterminated -#define __inout_bcount_z(size) __inout_bcount(size) __pre __nullterminated __post __nullterminated -#define __inout_nz __inout -#define __inout_ecount_nz(size) __inout_ecount(size) -#define __inout_bcount_nz(size) __inout_bcount(size) -#define __ecount_opt(size) __ecount(size) __exceptthat __maybenull -#define __bcount_opt(size) __bcount(size) __exceptthat __maybenull -#define __in_opt __in __exceptthat __maybenull -#define __in_ecount_opt(size) __in_ecount(size) __exceptthat __maybenull -#define __in_bcount_opt(size) __in_bcount(size) __exceptthat __maybenull -#define __in_z_opt __in_opt __pre __nullterminated -#define __in_ecount_z_opt(size) __in_ecount_opt(size) __pre __nullterminated -#define __in_bcount_z_opt(size) __in_bcount_opt(size) __pre __nullterminated -#define __in_nz_opt __in_opt -#define __in_ecount_nz_opt(size) __in_ecount_opt(size) -#define __in_bcount_nz_opt(size) __in_bcount_opt(size) -#define __out_opt __out __exceptthat __maybenull -#define __out_ecount_opt(size) __out_ecount(size) __exceptthat __maybenull -#define __out_bcount_opt(size) __out_bcount(size) __exceptthat __maybenull -#define __out_ecount_part_opt(size,length) __out_ecount_part(size,length) __exceptthat __maybenull -#define __out_bcount_part_opt(size,length) __out_bcount_part(size,length) __exceptthat __maybenull -#define __out_ecount_full_opt(size) __out_ecount_full(size) __exceptthat __maybenull -#define __out_bcount_full_opt(size) __out_bcount_full(size) __exceptthat __maybenull -#define __out_ecount_z_opt(size) __out_ecount_opt(size) __post __nullterminated -#define __out_bcount_z_opt(size) __out_bcount_opt(size) __post __nullterminated -#define __out_ecount_part_z_opt(size,length) __out_ecount_part_opt(size,length) __post __nullterminated -#define __out_bcount_part_z_opt(size,length) __out_bcount_part_opt(size,length) __post __nullterminated -#define __out_ecount_full_z_opt(size) __out_ecount_full_opt(size) __post __nullterminated -#define __out_bcount_full_z_opt(size) __out_bcount_full_opt(size) __post __nullterminated -#define __out_ecount_nz_opt(size) __out_ecount_opt(size) __post __nullterminated -#define __out_bcount_nz_opt(size) __out_bcount_opt(size) __post __nullterminated -#define __inout_opt __inout __exceptthat __maybenull -#define __inout_ecount_opt(size) __inout_ecount(size) __exceptthat __maybenull -#define __inout_bcount_opt(size) __inout_bcount(size) __exceptthat __maybenull -#define __inout_ecount_part_opt(size,length) __inout_ecount_part(size,length) __exceptthat __maybenull -#define __inout_bcount_part_opt(size,length) __inout_bcount_part(size,length) __exceptthat __maybenull -#define __inout_ecount_full_opt(size) __inout_ecount_full(size) __exceptthat __maybenull -#define __inout_bcount_full_opt(size) __inout_bcount_full(size) __exceptthat __maybenull -#define __inout_z_opt __inout_opt __pre __nullterminated __post __nullterminated -#define __inout_ecount_z_opt(size) __inout_ecount_opt(size) __pre __nullterminated __post __nullterminated -#define __inout_ecount_z_opt(size) __inout_ecount_opt(size) __pre __nullterminated __post __nullterminated -#define __inout_bcount_z_opt(size) __inout_bcount_opt(size) -#define __inout_nz_opt __inout_opt -#define __inout_ecount_nz_opt(size) __inout_ecount_opt(size) -#define __inout_bcount_nz_opt(size) __inout_bcount_opt(size) -#define __deref_ecount(size) __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __elem_writableTo(size) -#define __deref_bcount(size) __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __byte_writableTo(size) -#define __deref_out __deref_ecount(1) __post __deref __valid __refparam -#define __deref_out_ecount(size) __deref_ecount(size) __post __deref __valid __refparam -#define __deref_out_bcount(size) __deref_bcount(size) __post __deref __valid __refparam -#define __deref_out_ecount_part(size,length) __deref_out_ecount(size) __post __deref __elem_readableTo(length) -#define __deref_out_bcount_part(size,length) __deref_out_bcount(size) __post __deref __byte_readableTo(length) -#define __deref_out_ecount_full(size) __deref_out_ecount_part(size,size) -#define __deref_out_bcount_full(size) __deref_out_bcount_part(size,size) -#define __deref_out_z __post __deref __valid __refparam __post __deref __nullterminated -#define __deref_out_ecount_z(size) __deref_out_ecount(size) __post __deref __nullterminated -#define __deref_out_bcount_z(size) __deref_out_ecount(size) __post __deref __nullterminated -#define __deref_out_nz __deref_out -#define __deref_out_ecount_nz(size) __deref_out_ecount(size) -#define __deref_out_bcount_nz(size) __deref_out_ecount(size) -#define __deref_inout __notnull __elem_readableTo(1) __pre __deref __valid __post __deref __valid __refparam -#define __deref_inout_z __deref_inout __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_inout_ecount(size) __deref_inout __pre __deref __elem_writableTo(size) __post __deref __elem_writableTo(size) -#define __deref_inout_bcount(size) __deref_inout __pre __deref __byte_writableTo(size) __post __deref __byte_writableTo(size) -#define __deref_inout_ecount_part(size,length) __deref_inout_ecount(size) __pre __deref __elem_readableTo(length) __post __deref __elem_readableTo(length) -#define __deref_inout_bcount_part(size,length) __deref_inout_bcount(size) __pre __deref __byte_readableTo(length) __post __deref __byte_readableTo(length) -#define __deref_inout_ecount_full(size) __deref_inout_ecount_part(size,size) -#define __deref_inout_bcount_full(size) __deref_inout_bcount_part(size,size) -#define __deref_inout_z __deref_inout __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_inout_ecount_z(size) __deref_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_inout_bcount_z(size) __deref_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_inout_nz __deref_inout -#define __deref_inout_ecount_nz(size) __deref_inout_ecount(size) -#define __deref_inout_bcount_nz(size) __deref_inout_ecount(size) -#define __deref_ecount_opt(size) __deref_ecount(size) __post __deref __exceptthat __maybenull -#define __deref_bcount_opt(size) __deref_bcount(size) __post __deref __exceptthat __maybenull -#define __deref_out_opt __deref_out __post __deref __exceptthat __maybenull -#define __deref_out_ecount_opt(size) __deref_out_ecount(size) __post __deref __exceptthat __maybenull -#define __deref_out_bcount_opt(size) __deref_out_bcount(size) __post __deref __exceptthat __maybenull -#define __deref_out_ecount_part_opt(size,length) __deref_out_ecount_part(size,length) __post __deref __exceptthat __maybenull -#define __deref_out_bcount_part_opt(size,length) __deref_out_bcount_part(size,length) __post __deref __exceptthat __maybenull -#define __deref_out_ecount_full_opt(size) __deref_out_ecount_full(size) __post __deref __exceptthat __maybenull -#define __deref_out_bcount_full_opt(size) __deref_out_bcount_full(size) __post __deref __exceptthat __maybenull -#define __deref_out_z_opt __post __deref __valid __refparam __execeptthat __maybenull __post __deref __nullterminated -#define __deref_out_ecount_z_opt(size) __deref_out_ecount_opt(size) __post __deref __nullterminated -#define __deref_out_bcount_z_opt(size) __deref_out_bcount_opt(size) __post __deref __nullterminated -#define __deref_out_nz_opt __deref_out_opt -#define __deref_out_ecount_nz_opt(size) __deref_out_ecount_opt(size) -#define __deref_out_bcount_nz_opt(size) __deref_out_bcount_opt(size) -#define __deref_inout_opt __deref_inout __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull -#define __deref_inout_ecount_opt(size) __deref_inout_ecount(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull -#define __deref_inout_bcount_opt(size) __deref_inout_bcount(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull -#define __deref_inout_ecount_part_opt(size,length) __deref_inout_ecount_part(size,length) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull -#define __deref_inout_bcount_part_opt(size,length) __deref_inout_bcount_part(size,length) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull -#define __deref_inout_ecount_full_opt(size) __deref_inout_ecount_full(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull -#define __deref_inout_bcount_full_opt(size) __deref_inout_bcount_full(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull -#define __deref_inout_z_opt __deref_inout_opt __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_inout_ecount_z_opt(size) __deref_inout_ecount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_inout_bcount_z_opt(size) __deref_inout_bcount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_inout_nz_opt __deref_inout_opt -#define __deref_inout_ecount_nz_opt(size) __deref_inout_ecount_opt(size) -#define __deref_inout_bcount_nz_opt(size) __deref_inout_bcount_opt(size) -#define __deref_opt_ecount(size) __deref_ecount(size) __exceptthat __maybenull -#define __deref_opt_bcount(size) __deref_bcount(size) __exceptthat __maybenull -#define __deref_opt_out __deref_out __exceptthat __maybenull -#define __deref_opt_out_z __deref_opt_out __post __deref __nullterminated -#define __deref_opt_out_ecount(size) __deref_out_ecount(size) __exceptthat __maybenull -#define __deref_opt_out_bcount(size) __deref_out_bcount(size) __exceptthat __maybenull -#define __deref_opt_out_ecount_part(size,length) __deref_out_ecount_part(size,length) __exceptthat __maybenull -#define __deref_opt_out_bcount_part(size,length) __deref_out_bcount_part(size,length) __exceptthat __maybenull -#define __deref_opt_out_ecount_full(size) __deref_out_ecount_full(size) __exceptthat __maybenull -#define __deref_opt_out_bcount_full(size) __deref_out_bcount_full(size) __exceptthat __maybenull -#define __deref_opt_inout __deref_inout __exceptthat __maybenull -#define __deref_opt_inout_ecount(size) __deref_inout_ecount(size) __exceptthat __maybenull -#define __deref_opt_inout_bcount(size) __deref_inout_bcount(size) __exceptthat __maybenull -#define __deref_opt_inout_ecount_part(size,length) __deref_inout_ecount_part(size,length) __exceptthat __maybenull -#define __deref_opt_inout_bcount_part(size,length) __deref_inout_bcount_part(size,length) __exceptthat __maybenull -#define __deref_opt_inout_ecount_full(size) __deref_inout_ecount_full(size) __exceptthat __maybenull -#define __deref_opt_inout_bcount_full(size) __deref_inout_bcount_full(size) __exceptthat __maybenull -#define __deref_opt_inout_z __deref_opt_inout __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_opt_inout_ecount_z(size) __deref_opt_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_opt_inout_bcount_z(size) __deref_opt_inout_bcount(size) __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_opt_inout_nz __deref_opt_inout -#define __deref_opt_inout_ecount_nz(size) __deref_opt_inout_ecount(size) -#define __deref_opt_inout_bcount_nz(size) __deref_opt_inout_bcount(size) -#define __deref_opt_ecount_opt(size) __deref_ecount_opt(size) __exceptthat __maybenull -#define __deref_opt_bcount_opt(size) __deref_bcount_opt(size) __exceptthat __maybenull -#define __deref_opt_out_opt __deref_out_opt __exceptthat __maybenull -#define __deref_opt_out_ecount_opt(size) __deref_out_ecount_opt(size) __exceptthat __maybenull -#define __deref_opt_out_bcount_opt(size) __deref_out_bcount_opt(size) __exceptthat __maybenull -#define __deref_opt_out_ecount_part_opt(size,length) __deref_out_ecount_part_opt(size,length) __exceptthat __maybenull -#define __deref_opt_out_bcount_part_opt(size,length) __deref_out_bcount_part_opt(size,length) __exceptthat __maybenull -#define __deref_opt_out_ecount_full_opt(size) __deref_out_ecount_full_opt(size) __exceptthat __maybenull -#define __deref_opt_out_bcount_full_opt(size) __deref_out_bcount_full_opt(size) __exceptthat __maybenull -#define __deref_opt_out_z_opt __post __deref __valid __refparam __exceptthat __maybenull __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull __post __deref __nullterminated -#define __deref_opt_out_ecount_z_opt(size) __deref_opt_out_ecount_opt(size) __post __deref __nullterminated -#define __deref_opt_out_bcount_z_opt(size) __deref_opt_out_bcount_opt(size) __post __deref __nullterminated -#define __deref_opt_out_nz_opt __deref_opt_out_opt -#define __deref_opt_out_ecount_nz_opt(size) __deref_opt_out_ecount_opt(size) -#define __deref_opt_out_bcount_nz_opt(size) __deref_opt_out_bcount_opt(size) -#define __deref_opt_inout_opt __deref_inout_opt __exceptthat __maybenull -#define __deref_opt_inout_ecount_opt(size) __deref_inout_ecount_opt(size) __exceptthat __maybenull -#define __deref_opt_inout_bcount_opt(size) __deref_inout_bcount_opt(size) __exceptthat __maybenull -#define __deref_opt_inout_ecount_part_opt(size,length) __deref_inout_ecount_part_opt(size,length) __exceptthat __maybenull -#define __deref_opt_inout_bcount_part_opt(size,length) __deref_inout_bcount_part_opt(size,length) __exceptthat __maybenull -#define __deref_opt_inout_ecount_full_opt(size) __deref_inout_ecount_full_opt(size) __exceptthat __maybenull -#define __deref_opt_inout_bcount_full_opt(size) __deref_inout_bcount_full_opt(size) __exceptthat __maybenull -#define __deref_opt_inout_z_opt __deref_opt_inout_opt __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_opt_inout_ecount_z_opt(size) __deref_opt_inout_ecount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_opt_inout_bcount_z_opt(size) __deref_opt_inout_bcount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated -#define __deref_opt_inout_nz_opt __deref_opt_inout_opt -#define __deref_opt_inout_ecount_nz_opt(size) __deref_opt_inout_ecount_opt(size) -#define __deref_opt_inout_bcount_nz_opt(size) __deref_opt_inout_bcount_opt(size) - -/* -------------------------------------------------------------------------------- -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. -------------------------------------------------------------------------------- -*/ - -#define __success(expr) __inner_success(expr) -#define __nullterminated __readableTo(sentinel(0)) -#define __nullnullterminated -#define __reserved __pre __null -#define __checkReturn __inner_checkReturn -#define __typefix(ctype) __inner_typefix(ctype) -#define __override __inner_override -#define __callback __inner_callback -#define __format_string -#define __blocksOn(resource) __inner_blocksOn(resource) -#define __control_entrypoint(category) __inner_control_entrypoint(category) -#define __data_entrypoint(category) __inner_data_entrypoint(category) - -#ifndef __fallthrough - __inner_fallthrough_dec - #define __fallthrough __inner_fallthrough -#endif - -#ifndef __analysis_assume -#ifdef _PREFAST_ -#define __analysis_assume(expr) __assume(expr) -#else -#define __analysis_assume(expr) -#endif -#endif - -#ifdef __cplusplus -} -#endif - - +/*** +*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] +* +****/ + +/* + ------------------------------------------------------------------------------- + Introduction + + 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. + + 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 sal.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 | NullTerm | Optional | Parameters | + |------------|------------|---------|--------|----------|----------|---------------| + | <> | <> | <> | <> | _z | <> | <> | + | _deref | _in | _ecount | _full | _nz | _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. Cannot be used with _deref. + _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. + + NullTerm: States if the present of a '\0' marks the end of valid elements in the buffer. + _z : A '\0' indicated the end of the buffer + _nz : The buffer may not be null terminated and a '\0' does not indicate the end of the + buffer. + 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 : + indicates whether function f succeeded or not. If is true at exit, + all the function's guarantees (as given by other annotations) must hold. If + 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. + + __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. + + ------------------------------------------------------------------------------- +*/ + +#pragma once + +#define __specstrings + +#ifdef __cplusplus +#ifndef __nothrow +# define __nothrow __declspec(nothrow) +#endif +extern "C" { +#else +#ifndef __nothrow +# define __nothrow +#endif +#endif /* #ifdef __cplusplus */ + +/* + ------------------------------------------------------------------------------- + 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 !defined(__midl) && 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() + + When is true, the next annotation applies in the precondition state + (currently not enabled) + */ + #define __precond(expr) __pre + + /* + __postcond() + + When 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") + #define __execeptthat __exceptthat + + /* + _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 + #define __null + #define __notnull + #define __maybenull + #define __readonly + #define __notreadonly + #define __maybereadonly + #define __valid + #define __notvalid + #define __maybevalid + #define __readableTo(extent) + #define __elem_readableTo(size) + #define __byte_readableTo(size) + #define __writableTo(size) + #define __elem_writableTo(size) + #define __byte_writableTo(size) + #define __deref + #define __pre + #define __post + #define __precond(expr) + #define __postcond(expr) + #define __exceptthat + #define __execeptthat + #define __inner_success(expr) + #define __inner_checkReturn + #define __inner_typefix(ctype) + #define __inner_override + #define __inner_callback + #define __inner_blocksOn(resource) + #define __inner_fallthrough_dec + #define __inner_fallthrough + #define __refparam + #define __inner_control_entrypoint(category) + #define __inner_data_entrypoint(category) +#endif /* #if !defined(__midl) && 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. +------------------------------------------------------------------------------- +*/ + +#define __ecount(size) __notnull __elem_writableTo(size) +#define __bcount(size) __notnull __byte_writableTo(size) +#define __in __pre __valid __pre __deref __readonly +#define __in_ecount(size) __in __pre __elem_readableTo(size) +#define __in_bcount(size) __in __pre __byte_readableTo(size) +#define __in_z __in __pre __nullterminated +#define __in_ecount_z(size) __in_ecount(size) __pre __nullterminated +#define __in_bcount_z(size) __in_bcount(size) __pre __nullterminated +#define __in_nz __in +#define __in_ecount_nz(size) __in_ecount(size) +#define __in_bcount_nz(size) __in_bcount(size) +#define __out __ecount(1) __post __valid __refparam +#define __out_ecount(size) __ecount(size) __post __valid __refparam +#define __out_bcount(size) __bcount(size) __post __valid __refparam +#define __out_ecount_part(size,length) __out_ecount(size) __post __elem_readableTo(length) +#define __out_bcount_part(size,length) __out_bcount(size) __post __byte_readableTo(length) +#define __out_ecount_full(size) __out_ecount_part(size,size) +#define __out_bcount_full(size) __out_bcount_part(size,size) +#define __out_z __post __valid __refparam __post __nullterminated +#define __out_z_opt __post __valid __refparam __post __nullterminated __exceptthat __maybenull +#define __out_ecount_z(size) __ecount(size) __post __valid __refparam __post __nullterminated +#define __out_bcount_z(size) __bcount(size) __post __valid __refparam __post __nullterminated +#define __out_ecount_part_z(size,length) __out_ecount_part(size,length) __post __nullterminated +#define __out_bcount_part_z(size,length) __out_bcount_part(size,length) __post __nullterminated +#define __out_ecount_full_z(size) __out_ecount_full(size) __post __nullterminated +#define __out_bcount_full_z(size) __out_bcount_full(size) __post __nullterminated +#define __out_nz __post __valid __refparam __post +#define __out_nz_opt __post __valid __refparam __post __exceptthat __maybenull +#define __out_ecount_nz(size) __ecount(size) __post __valid __refparam +#define __out_bcount_nz(size) __bcount(size) __post __valid __refparam +#define __inout __pre __valid __post __valid __refparam +#define __inout_ecount(size) __out_ecount(size) __pre __valid +#define __inout_bcount(size) __out_bcount(size) __pre __valid +#define __inout_ecount_part(size,length) __out_ecount_part(size,length) __pre __valid __pre __elem_readableTo(length) +#define __inout_bcount_part(size,length) __out_bcount_part(size,length) __pre __valid __pre __byte_readableTo(length) +#define __inout_ecount_full(size) __inout_ecount_part(size,size) +#define __inout_bcount_full(size) __inout_bcount_part(size,size) +#define __inout_z __inout __pre __nullterminated __post __nullterminated +#define __inout_ecount_z(size) __inout_ecount(size) __pre __nullterminated __post __nullterminated +#define __inout_bcount_z(size) __inout_bcount(size) __pre __nullterminated __post __nullterminated +#define __inout_nz __inout +#define __inout_ecount_nz(size) __inout_ecount(size) +#define __inout_bcount_nz(size) __inout_bcount(size) +#define __ecount_opt(size) __ecount(size) __exceptthat __maybenull +#define __bcount_opt(size) __bcount(size) __exceptthat __maybenull +#define __in_opt __in __exceptthat __maybenull +#define __in_ecount_opt(size) __in_ecount(size) __exceptthat __maybenull +#define __in_bcount_opt(size) __in_bcount(size) __exceptthat __maybenull +#define __in_z_opt __in_opt __pre __nullterminated +#define __in_ecount_z_opt(size) __in_ecount_opt(size) __pre __nullterminated +#define __in_bcount_z_opt(size) __in_bcount_opt(size) __pre __nullterminated +#define __in_nz_opt __in_opt +#define __in_ecount_nz_opt(size) __in_ecount_opt(size) +#define __in_bcount_nz_opt(size) __in_bcount_opt(size) +#define __out_opt __out __exceptthat __maybenull +#define __out_ecount_opt(size) __out_ecount(size) __exceptthat __maybenull +#define __out_bcount_opt(size) __out_bcount(size) __exceptthat __maybenull +#define __out_ecount_part_opt(size,length) __out_ecount_part(size,length) __exceptthat __maybenull +#define __out_bcount_part_opt(size,length) __out_bcount_part(size,length) __exceptthat __maybenull +#define __out_ecount_full_opt(size) __out_ecount_full(size) __exceptthat __maybenull +#define __out_bcount_full_opt(size) __out_bcount_full(size) __exceptthat __maybenull +#define __out_ecount_z_opt(size) __out_ecount_opt(size) __post __nullterminated +#define __out_bcount_z_opt(size) __out_bcount_opt(size) __post __nullterminated +#define __out_ecount_part_z_opt(size,length) __out_ecount_part_opt(size,length) __post __nullterminated +#define __out_bcount_part_z_opt(size,length) __out_bcount_part_opt(size,length) __post __nullterminated +#define __out_ecount_full_z_opt(size) __out_ecount_full_opt(size) __post __nullterminated +#define __out_bcount_full_z_opt(size) __out_bcount_full_opt(size) __post __nullterminated +#define __out_ecount_nz_opt(size) __out_ecount_opt(size) __post __nullterminated +#define __out_bcount_nz_opt(size) __out_bcount_opt(size) __post __nullterminated +#define __inout_opt __inout __exceptthat __maybenull +#define __inout_ecount_opt(size) __inout_ecount(size) __exceptthat __maybenull +#define __inout_bcount_opt(size) __inout_bcount(size) __exceptthat __maybenull +#define __inout_ecount_part_opt(size,length) __inout_ecount_part(size,length) __exceptthat __maybenull +#define __inout_bcount_part_opt(size,length) __inout_bcount_part(size,length) __exceptthat __maybenull +#define __inout_ecount_full_opt(size) __inout_ecount_full(size) __exceptthat __maybenull +#define __inout_bcount_full_opt(size) __inout_bcount_full(size) __exceptthat __maybenull +#define __inout_z_opt __inout_opt __pre __nullterminated __post __nullterminated +#define __inout_ecount_z_opt(size) __inout_ecount_opt(size) __pre __nullterminated __post __nullterminated +#define __inout_ecount_z_opt(size) __inout_ecount_opt(size) __pre __nullterminated __post __nullterminated +#define __inout_bcount_z_opt(size) __inout_bcount_opt(size) +#define __inout_nz_opt __inout_opt +#define __inout_ecount_nz_opt(size) __inout_ecount_opt(size) +#define __inout_bcount_nz_opt(size) __inout_bcount_opt(size) +#define __deref_ecount(size) __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __elem_writableTo(size) +#define __deref_bcount(size) __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __byte_writableTo(size) +#define __deref_out __deref_ecount(1) __post __deref __valid __refparam +#define __deref_out_ecount(size) __deref_ecount(size) __post __deref __valid __refparam +#define __deref_out_bcount(size) __deref_bcount(size) __post __deref __valid __refparam +#define __deref_out_ecount_part(size,length) __deref_out_ecount(size) __post __deref __elem_readableTo(length) +#define __deref_out_bcount_part(size,length) __deref_out_bcount(size) __post __deref __byte_readableTo(length) +#define __deref_out_ecount_full(size) __deref_out_ecount_part(size,size) +#define __deref_out_bcount_full(size) __deref_out_bcount_part(size,size) +#define __deref_out_z __post __deref __valid __refparam __post __deref __nullterminated +#define __deref_out_ecount_z(size) __deref_out_ecount(size) __post __deref __nullterminated +#define __deref_out_bcount_z(size) __deref_out_ecount(size) __post __deref __nullterminated +#define __deref_out_nz __deref_out +#define __deref_out_ecount_nz(size) __deref_out_ecount(size) +#define __deref_out_bcount_nz(size) __deref_out_ecount(size) +#define __deref_inout __notnull __elem_readableTo(1) __pre __deref __valid __post __deref __valid __refparam +#define __deref_inout_z __deref_inout __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_inout_ecount(size) __deref_inout __pre __deref __elem_writableTo(size) __post __deref __elem_writableTo(size) +#define __deref_inout_bcount(size) __deref_inout __pre __deref __byte_writableTo(size) __post __deref __byte_writableTo(size) +#define __deref_inout_ecount_part(size,length) __deref_inout_ecount(size) __pre __deref __elem_readableTo(length) __post __deref __elem_readableTo(length) +#define __deref_inout_bcount_part(size,length) __deref_inout_bcount(size) __pre __deref __byte_readableTo(length) __post __deref __byte_readableTo(length) +#define __deref_inout_ecount_full(size) __deref_inout_ecount_part(size,size) +#define __deref_inout_bcount_full(size) __deref_inout_bcount_part(size,size) +#define __deref_inout_z __deref_inout __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_inout_ecount_z(size) __deref_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_inout_bcount_z(size) __deref_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_inout_nz __deref_inout +#define __deref_inout_ecount_nz(size) __deref_inout_ecount(size) +#define __deref_inout_bcount_nz(size) __deref_inout_ecount(size) +#define __deref_ecount_opt(size) __deref_ecount(size) __post __deref __exceptthat __maybenull +#define __deref_bcount_opt(size) __deref_bcount(size) __post __deref __exceptthat __maybenull +#define __deref_out_opt __deref_out __post __deref __exceptthat __maybenull +#define __deref_out_ecount_opt(size) __deref_out_ecount(size) __post __deref __exceptthat __maybenull +#define __deref_out_bcount_opt(size) __deref_out_bcount(size) __post __deref __exceptthat __maybenull +#define __deref_out_ecount_part_opt(size,length) __deref_out_ecount_part(size,length) __post __deref __exceptthat __maybenull +#define __deref_out_bcount_part_opt(size,length) __deref_out_bcount_part(size,length) __post __deref __exceptthat __maybenull +#define __deref_out_ecount_full_opt(size) __deref_out_ecount_full(size) __post __deref __exceptthat __maybenull +#define __deref_out_bcount_full_opt(size) __deref_out_bcount_full(size) __post __deref __exceptthat __maybenull +#define __deref_out_z_opt __post __deref __valid __refparam __execeptthat __maybenull __post __deref __nullterminated +#define __deref_out_ecount_z_opt(size) __deref_out_ecount_opt(size) __post __deref __nullterminated +#define __deref_out_bcount_z_opt(size) __deref_out_bcount_opt(size) __post __deref __nullterminated +#define __deref_out_nz_opt __deref_out_opt +#define __deref_out_ecount_nz_opt(size) __deref_out_ecount_opt(size) +#define __deref_out_bcount_nz_opt(size) __deref_out_bcount_opt(size) +#define __deref_inout_opt __deref_inout __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull +#define __deref_inout_ecount_opt(size) __deref_inout_ecount(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull +#define __deref_inout_bcount_opt(size) __deref_inout_bcount(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull +#define __deref_inout_ecount_part_opt(size,length) __deref_inout_ecount_part(size,length) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull +#define __deref_inout_bcount_part_opt(size,length) __deref_inout_bcount_part(size,length) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull +#define __deref_inout_ecount_full_opt(size) __deref_inout_ecount_full(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull +#define __deref_inout_bcount_full_opt(size) __deref_inout_bcount_full(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull +#define __deref_inout_z_opt __deref_inout_opt __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_inout_ecount_z_opt(size) __deref_inout_ecount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_inout_bcount_z_opt(size) __deref_inout_bcount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_inout_nz_opt __deref_inout_opt +#define __deref_inout_ecount_nz_opt(size) __deref_inout_ecount_opt(size) +#define __deref_inout_bcount_nz_opt(size) __deref_inout_bcount_opt(size) +#define __deref_opt_ecount(size) __deref_ecount(size) __exceptthat __maybenull +#define __deref_opt_bcount(size) __deref_bcount(size) __exceptthat __maybenull +#define __deref_opt_out __deref_out __exceptthat __maybenull +#define __deref_opt_out_z __deref_opt_out __post __deref __nullterminated +#define __deref_opt_out_ecount(size) __deref_out_ecount(size) __exceptthat __maybenull +#define __deref_opt_out_bcount(size) __deref_out_bcount(size) __exceptthat __maybenull +#define __deref_opt_out_ecount_part(size,length) __deref_out_ecount_part(size,length) __exceptthat __maybenull +#define __deref_opt_out_bcount_part(size,length) __deref_out_bcount_part(size,length) __exceptthat __maybenull +#define __deref_opt_out_ecount_full(size) __deref_out_ecount_full(size) __exceptthat __maybenull +#define __deref_opt_out_bcount_full(size) __deref_out_bcount_full(size) __exceptthat __maybenull +#define __deref_opt_inout __deref_inout __exceptthat __maybenull +#define __deref_opt_inout_ecount(size) __deref_inout_ecount(size) __exceptthat __maybenull +#define __deref_opt_inout_bcount(size) __deref_inout_bcount(size) __exceptthat __maybenull +#define __deref_opt_inout_ecount_part(size,length) __deref_inout_ecount_part(size,length) __exceptthat __maybenull +#define __deref_opt_inout_bcount_part(size,length) __deref_inout_bcount_part(size,length) __exceptthat __maybenull +#define __deref_opt_inout_ecount_full(size) __deref_inout_ecount_full(size) __exceptthat __maybenull +#define __deref_opt_inout_bcount_full(size) __deref_inout_bcount_full(size) __exceptthat __maybenull +#define __deref_opt_inout_z __deref_opt_inout __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_opt_inout_ecount_z(size) __deref_opt_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_opt_inout_bcount_z(size) __deref_opt_inout_bcount(size) __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_opt_inout_nz __deref_opt_inout +#define __deref_opt_inout_ecount_nz(size) __deref_opt_inout_ecount(size) +#define __deref_opt_inout_bcount_nz(size) __deref_opt_inout_bcount(size) +#define __deref_opt_ecount_opt(size) __deref_ecount_opt(size) __exceptthat __maybenull +#define __deref_opt_bcount_opt(size) __deref_bcount_opt(size) __exceptthat __maybenull +#define __deref_opt_out_opt __deref_out_opt __exceptthat __maybenull +#define __deref_opt_out_ecount_opt(size) __deref_out_ecount_opt(size) __exceptthat __maybenull +#define __deref_opt_out_bcount_opt(size) __deref_out_bcount_opt(size) __exceptthat __maybenull +#define __deref_opt_out_ecount_part_opt(size,length) __deref_out_ecount_part_opt(size,length) __exceptthat __maybenull +#define __deref_opt_out_bcount_part_opt(size,length) __deref_out_bcount_part_opt(size,length) __exceptthat __maybenull +#define __deref_opt_out_ecount_full_opt(size) __deref_out_ecount_full_opt(size) __exceptthat __maybenull +#define __deref_opt_out_bcount_full_opt(size) __deref_out_bcount_full_opt(size) __exceptthat __maybenull +#define __deref_opt_out_z_opt __post __deref __valid __refparam __exceptthat __maybenull __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull __post __deref __nullterminated +#define __deref_opt_out_ecount_z_opt(size) __deref_opt_out_ecount_opt(size) __post __deref __nullterminated +#define __deref_opt_out_bcount_z_opt(size) __deref_opt_out_bcount_opt(size) __post __deref __nullterminated +#define __deref_opt_out_nz_opt __deref_opt_out_opt +#define __deref_opt_out_ecount_nz_opt(size) __deref_opt_out_ecount_opt(size) +#define __deref_opt_out_bcount_nz_opt(size) __deref_opt_out_bcount_opt(size) +#define __deref_opt_inout_opt __deref_inout_opt __exceptthat __maybenull +#define __deref_opt_inout_ecount_opt(size) __deref_inout_ecount_opt(size) __exceptthat __maybenull +#define __deref_opt_inout_bcount_opt(size) __deref_inout_bcount_opt(size) __exceptthat __maybenull +#define __deref_opt_inout_ecount_part_opt(size,length) __deref_inout_ecount_part_opt(size,length) __exceptthat __maybenull +#define __deref_opt_inout_bcount_part_opt(size,length) __deref_inout_bcount_part_opt(size,length) __exceptthat __maybenull +#define __deref_opt_inout_ecount_full_opt(size) __deref_inout_ecount_full_opt(size) __exceptthat __maybenull +#define __deref_opt_inout_bcount_full_opt(size) __deref_inout_bcount_full_opt(size) __exceptthat __maybenull +#define __deref_opt_inout_z_opt __deref_opt_inout_opt __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_opt_inout_ecount_z_opt(size) __deref_opt_inout_ecount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_opt_inout_bcount_z_opt(size) __deref_opt_inout_bcount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated +#define __deref_opt_inout_nz_opt __deref_opt_inout_opt +#define __deref_opt_inout_ecount_nz_opt(size) __deref_opt_inout_ecount_opt(size) +#define __deref_opt_inout_bcount_nz_opt(size) __deref_opt_inout_bcount_opt(size) + +/* +------------------------------------------------------------------------------- +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. +------------------------------------------------------------------------------- +*/ + +#define __success(expr) __inner_success(expr) +#define __nullterminated __readableTo(sentinel(0)) +#define __nullnullterminated +#define __reserved __pre __null +#define __checkReturn __inner_checkReturn +#define __typefix(ctype) __inner_typefix(ctype) +#define __override __inner_override +#define __callback __inner_callback +#define __format_string +#define __blocksOn(resource) __inner_blocksOn(resource) +#define __control_entrypoint(category) __inner_control_entrypoint(category) +#define __data_entrypoint(category) __inner_data_entrypoint(category) + +#ifndef __fallthrough + __inner_fallthrough_dec + #define __fallthrough __inner_fallthrough +#endif + +#ifndef __analysis_assume +#ifdef _PREFAST_ +#define __analysis_assume(expr) __assume(expr) +#else +#define __analysis_assume(expr) +#endif +#endif + +#ifdef __cplusplus +} +#endif + + -- cgit v1.2.3