Add a .gitattributes with "* text=auto" so that new lines are
[pdfium.git] / core / src / fxge / Microsoft SDK / include / sal.h
1 /***
2 *sal.h - markers for documenting the semantics of APIs
3 *
4 *       Copyright (c) Microsoft Corporation. All rights reserved.
5 *
6 *Purpose:
7 *       sal.h provides a set of annotations to describe how a function uses its
8 *       parameters - the assumptions it makes about them, and the guarantees it makes
9 *       upon finishing.
10 *
11 *       [Public]
12 *
13 ****/
14
15 /* 
16  -------------------------------------------------------------------------------
17  Introduction
18
19  sal.h provides a set of annotations to describe how a function uses its
20  parameters - the assumptions it makes about them, and the guarantees it makes
21  upon finishing.
22
23  Annotations may be placed before either a function parameter's type or its return
24  type, and describe the function's behavior regarding the parameter or return value.
25  There are two classes of annotations: buffer annotations and advanced annotations.
26  Buffer annotations describe how functions use their pointer parameters, and
27  advanced annotations either describe complex/unusual buffer behavior, or provide
28  additional information about a parameter that is not otherwise expressible.
29
30  -------------------------------------------------------------------------------
31  Buffer Annotations
32
33  The most important annotations in sal.h provide a consistent way to annotate
34  buffer parameters or return values for a function. Each of these annotations describes
35  a single buffer (which could be a string, a fixed-length or variable-length array,
36  or just a pointer) that the function interacts with: where it is, how large it is,
37  how much is initialized, and what the function does with it.
38
39  The appropriate macro for a given buffer can be constructed using the table below.
40  Just pick the appropriate values from each category, and combine them together
41  with a leading underscore. Some combinations of values do not make sense as buffer
42  annotations. Only meaningful annotations can be added to your code; for a list of
43  these, see the buffer annotation definitions section.
44
45  Only a single buffer annotation should be used for each parameter.
46
47  |------------|------------|---------|--------|----------|----------|---------------|
48  |   Level    |   Usage    |  Size   | Output | NullTerm | Optional |  Parameters   |
49  |------------|------------|---------|--------|----------|----------|---------------|
50  | <>         | <>         | <>      | <>     | _z       | <>       | <>            |
51  | _deref     | _in        | _ecount | _full  | _nz      | _opt     | (size)        |
52  | _deref_opt | _out       | _bcount | _part  |          |          | (size,length) |
53  |            | _inout     |         |        |          |          |               |
54  |            |            |         |        |          |          |               |
55  |------------|------------|---------|--------|----------|----------|---------------|
56
57  Level: Describes the buffer pointer's level of indirection from the parameter or
58           return value 'p'.
59
60  <>         : p is the buffer pointer.
61  _deref     : *p is the buffer pointer. p must not be NULL.
62  _deref_opt : *p may be the buffer pointer. p may be NULL, in which case the rest of
63                 the annotation is ignored.
64
65  Usage: Describes how the function uses the buffer.
66
67  <>     : The buffer is not accessed. If used on the return value or with _deref, the
68             function will provide the buffer, and it will be uninitialized at exit.
69             Otherwise, the caller must provide the buffer. This should only be used
70             for alloc and free functions.
71  _in    : The function will only read from the buffer. The caller must provide the
72             buffer and initialize it. Cannot be used with _deref.
73  _out   : The function will only write to the buffer. If used on the return value or
74             with _deref, the function will provide the buffer and initialize it.
75             Otherwise, the caller must provide the buffer, and the function will
76             initialize it.
77  _inout : The function may freely read from and write to the buffer. The caller must
78             provide the buffer and initialize it. If used with _deref, the buffer may
79             be reallocated by the function.
80
81  Size: Describes the total size of the buffer. This may be less than the space actually
82          allocated for the buffer, in which case it describes the accessible amount.
83
84  <>      : No buffer size is given. If the type specifies the buffer size (such as
85              with LPSTR and LPWSTR), that amount is used. Otherwise, the buffer is one
86              element long. Must be used with _in, _out, or _inout.
87  _ecount : The buffer size is an explicit element count.
88  _bcount : The buffer size is an explicit byte count.
89
90  Output: Describes how much of the buffer will be initialized by the function. For
91            _inout buffers, this also describes how much is initialized at entry. Omit this
92            category for _in buffers; they must be fully initialized by the caller.
93
94  <>    : The type specifies how much is initialized. For instance, a function initializing
95            an LPWSTR must NULL-terminate the string.
96  _full : The function initializes the entire buffer.
97  _part : The function initializes part of the buffer, and explicitly indicates how much.
98
99  NullTerm: States if the present of a '\0' marks the end of valid elements in the buffer.
100  _z    : A '\0' indicated the end of the buffer
101  _nz     : The buffer may not be null terminated and a '\0' does not indicate the end of the
102           buffer.
103  Optional: Describes if the buffer itself is optional.
104
105  <>   : The pointer to the buffer must not be NULL.
106  _opt : The pointer to the buffer might be NULL. It will be checked before being dereferenced.
107
108  Parameters: Gives explicit counts for the size and length of the buffer.
109
110  <>            : There is no explicit count. Use when neither _ecount nor _bcount is used.
111  (size)        : Only the buffer's total size is given. Use with _ecount or _bcount but not _part.
112  (size,length) : The buffer's total size and initialized length are given. Use with _ecount_part
113                    and _bcount_part.
114
115  -------------------------------------------------------------------------------
116  Buffer Annotation Examples
117
118  LWSTDAPI_(BOOL) StrToIntExA(
119      LPCSTR pszString,                    -- No annotation required, const implies __in.
120      DWORD dwFlags,
121      __out int *piRet                     -- A pointer whose dereference will be filled in.
122  );
123
124  void MyPaintingFunction(
125      __in HWND hwndControl,               -- An initialized read-only parameter.
126      __in_opt HDC hdcOptional,            -- An initialized read-only parameter that might be NULL.
127      __inout IPropertyStore *ppsStore     -- An initialized parameter that may be freely used
128                                           --   and modified.
129  );
130
131  LWSTDAPI_(BOOL) PathCompactPathExA(
132      __out_ecount(cchMax) LPSTR pszOut,   -- A string buffer with cch elements that will
133                                           --   be NULL terminated on exit.
134      LPCSTR pszSrc,                       -- No annotation required, const implies __in.
135      UINT cchMax,
136      DWORD dwFlags
137  );
138
139  HRESULT SHLocalAllocBytes(
140      size_t cb,
141      __deref_bcount(cb) T **ppv           -- A pointer whose dereference will be set to an
142                                           --   uninitialized buffer with cb bytes.
143  );
144
145  __inout_bcount_full(cb) : A buffer with cb elements that is fully initialized at
146      entry and exit, and may be written to by this function.
147
148  __out_ecount_part(count, *countOut) : A buffer with count elements that will be
149      partially initialized by this function. The function indicates how much it
150      initialized by setting *countOut.
151
152  -------------------------------------------------------------------------------
153  Advanced Annotations
154
155  Advanced annotations describe behavior that is not expressible with the regular
156  buffer macros. These may be used either to annotate buffer parameters that involve
157  complex or conditional behavior, or to enrich existing annotations with additional
158  information.
159
160  __success(expr) f :
161      <expr> indicates whether function f succeeded or not. If <expr> is true at exit,
162      all the function's guarantees (as given by other annotations) must hold. If <expr>
163      is false at exit, the caller should not expect any of the function's guarantees
164      to hold. If not used, the function must always satisfy its guarantees. Added
165      automatically to functions that indicate success in standard ways, such as by
166      returning an HRESULT.
167
168  __nullterminated p :
169      Pointer p is a buffer that may be read or written up to and including the first
170      NULL character or pointer. May be used on typedefs, which marks valid (properly
171      initialized) instances of that type as being NULL-terminated.
172
173  __nullnullterminated p :
174      Pointer p is a buffer that may be read or written up to and including the first
175      sequence of two NULL characters or pointers. May be used on typedefs, which marks
176      valid instances of that type as being double-NULL terminated.
177
178  __reserved v :
179      Value v must be 0/NULL, reserved for future use.
180
181  __checkReturn v :
182      Return value v must not be ignored by callers of this function.
183
184  __typefix(ctype) v :
185      Value v should be treated as an instance of ctype, rather than its declared type.
186
187  __override f :
188      Specify C#-style 'override' behaviour for overriding virtual methods.
189
190  __callback f :
191      Function f can be used as a function pointer.
192
193  __format_string p :
194      Pointer p is a string that contains % markers in the style of printf.
195
196  __blocksOn(resource) f :
197      Function f blocks on the resource 'resource'.
198
199  __fallthrough :
200      Annotates switch statement labels where fall-through is desired, to distinguish
201      from forgotten break statements.
202
203  -------------------------------------------------------------------------------
204  Advanced Annotation Examples
205
206  __success(return == TRUE) LWSTDAPI_(BOOL) 
207  PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) :
208      pszBuf is only guaranteed to be NULL-terminated when TRUE is returned.
209
210  typedef __nullterminated WCHAR* LPWSTR : Initialized LPWSTRs are NULL-terminated strings.
211
212  __out_ecount(cch) __typefix(LPWSTR) void *psz : psz is a buffer parameter which will be
213      a NULL-terminated WCHAR string at exit, and which initially contains cch WCHARs.
214
215  -------------------------------------------------------------------------------
216 */
217
218 #pragma once
219
220 #define __specstrings
221
222 #ifdef  __cplusplus
223 #ifndef __nothrow
224 # define __nothrow __declspec(nothrow)
225 #endif
226 extern "C" {
227 #else
228 #ifndef __nothrow
229 # define __nothrow
230 #endif
231 #endif  /* #ifdef __cplusplus */
232
233 /*
234  -------------------------------------------------------------------------------
235  Helper Macro Definitions
236
237  These express behavior common to many of the high-level annotations.
238  DO NOT USE THESE IN YOUR CODE.
239  -------------------------------------------------------------------------------
240 */
241
242 /*
243 The helper annotations are only understood by the compiler version used by various
244 defect detection tools. When the regular compiler is running, they are defined into
245 nothing, and do not affect the compiled code.
246 */
247
248 #if !defined(__midl) && defined(_PREFAST_) 
249
250     /*
251      In the primitive __declspec("SAL_*") annotations "SAL" stands for Standard
252      Annotation Language.  These __declspec("SAL_*") annotations are the
253      primitives the compiler understands and all high-level SpecString MACROs
254      will decompose into these primivates.
255     */
256
257     #define SPECSTRINGIZE( x ) #x
258
259     /*
260      __null p
261      __notnull p
262      __maybenull p
263     
264      Annotates a pointer p. States that pointer p is null. Commonly used
265      in the negated form __notnull or the possibly null form __maybenull.
266     */
267
268     #define __null                  __declspec("SAL_null")
269     #define __notnull               __declspec("SAL_notnull")
270     #define __maybenull             __declspec("SAL_maybenull")
271
272     /*
273      __readonly l
274      __notreadonly l
275      __mabyereadonly l
276     
277      Annotates a location l. States that location l is not modified after
278      this point.  If the annotation is placed on the precondition state of
279      a function, the restriction only applies until the postcondition state
280      of the function.  __maybereadonly states that the annotated location
281      may be modified, whereas __notreadonly states that a location must be
282      modified.
283     */
284
285     #define __readonly              __declspec("SAL_readonly")
286     #define __notreadonly           __declspec("SAL_notreadonly")
287     #define __maybereadonly         __declspec("SAL_maybereadonly")
288
289     /*
290      __valid v
291      __notvalid v
292      __maybevalid v
293     
294      Annotates any value v. States that the value satisfies all properties of
295      valid values of its type. For example, for a string buffer, valid means
296      that the buffer pointer is either NULL or points to a NULL-terminated string.
297     */
298
299     #define __valid                 __declspec("SAL_valid")
300     #define __notvalid              __declspec("SAL_notvalid")
301     #define __maybevalid            __declspec("SAL_maybevalid")
302
303     /*
304      __readableTo(extent) p
305     
306      Annotates a buffer pointer p.  If the buffer can be read, extent describes
307      how much of the buffer is readable. For a reader of the buffer, this is
308      an explicit permission to read up to that amount, rather than a restriction to
309      read only up to it.
310     */
311
312     #define __readableTo(extent)    __declspec("SAL_readableTo("SPECSTRINGIZE(extent)")")
313
314     /*
315     
316      __elem_readableTo(size)
317     
318      Annotates a buffer pointer p as being readable to size elements.
319     */
320
321     #define __elem_readableTo(size)   __declspec("SAL_readableTo(elementCount("SPECSTRINGIZE(size)"))")
322     
323     /*
324      __byte_readableTo(size)
325     
326      Annotates a buffer pointer p as being readable to size bytes.
327     */
328     #define __byte_readableTo(size)   __declspec("SAL_readableTo(byteCount("SPECSTRINGIZE(size)"))")
329     
330     /*
331      __writableTo(extent) p
332     
333      Annotates a buffer pointer p. If the buffer can be modified, extent
334      describes how much of the buffer is writable (usually the allocation
335      size). For a writer of the buffer, this is an explicit permission to
336      write up to that amount, rather than a restriction to write only up to it.
337     */
338     #define __writableTo(size)   __declspec("SAL_writableTo("SPECSTRINGIZE(size)")")
339
340     /*
341      __elem_writableTo(size)
342     
343      Annotates a buffer pointer p as being writable to size elements.
344     */
345     #define __elem_writableTo(size)   __declspec("SAL_writableTo(elementCount("SPECSTRINGIZE(size)"))")
346     
347     /*
348      __byte_writableTo(size)
349     
350      Annotates a buffer pointer p as being writable to size bytes.
351     */
352     #define __byte_writableTo(size)   __declspec("SAL_writableTo(byteCount("SPECSTRINGIZE(size)"))")
353
354     /*
355      __deref p
356     
357      Annotates a pointer p. The next annotation applies one dereference down
358      in the type. If readableTo(p, size) then the next annotation applies to
359      all elements *(p+i) for which i satisfies the size. If p is a pointer
360      to a struct, the next annotation applies to all fields of the struct.
361     */
362     #define __deref                 __declspec("SAL_deref")
363     
364     /*
365      __pre __next_annotation
366     
367      The next annotation applies in the precondition state
368     */
369     #define __pre                   __declspec("SAL_pre")
370     
371     /*
372      __post __next_annotation
373     
374      The next annotation applies in the postcondition state
375     */
376     #define __post                  __declspec("SAL_post")
377     
378     /*
379      __precond(<expr>)
380     
381      When <expr> is true, the next annotation applies in the precondition state
382      (currently not enabled)
383     */
384     #define __precond(expr)         __pre
385
386     /*
387      __postcond(<expr>)
388     
389      When <expr> is true, the next annotation applies in the postcondition state
390      (currently not enabled)
391     */
392     #define __postcond(expr)        __post
393
394     /*
395      __exceptthat
396     
397      Given a set of annotations Q containing __exceptthat maybeP, the effect of
398      the except clause is to erase any P or notP annotations (explicit or
399      implied) within Q at the same level of dereferencing that the except
400      clause appears, and to replace it with maybeP.
401     
402       Example 1: __valid __exceptthat __maybenull on a pointer p means that the
403                  pointer may be null, and is otherwise valid, thus overriding
404                  the implicit notnull annotation implied by __valid on
405                  pointers.
406     
407       Example 2: __valid __deref __exceptthat __maybenull on an int **p means
408                  that p is not null (implied by valid), but the elements
409                  pointed to by p could be null, and are otherwise valid. 
410     */
411     #define __exceptthat                __declspec("SAL_except")
412     #define __execeptthat               __exceptthat
413  
414     /*
415      _refparam
416     
417      Added to all out parameter macros to indicate that they are all reference
418      parameters.
419     */
420     #define __refparam                  __deref __notreadonly
421
422     /*
423      __inner_*
424     
425      Helper macros that directly correspond to certain high-level annotations.
426     
427     */
428
429     /*
430      Macros to classify the entrypoints and indicate their category.
431     
432      Pre-defined control point categories include: RPC, LPC, DeviceDriver, UserToKernel, ISAPI, COM.
433     
434     */
435     #define __inner_control_entrypoint(category) __declspec("SAL_entrypoint(controlEntry, "SPECSTRINGIZE(category)")")
436
437     /*
438      Pre-defined data entry point categories include: Registry, File, Network.
439     */
440     #define __inner_data_entrypoint(category)    __declspec("SAL_entrypoint(dataEntry, "SPECSTRINGIZE(category)")")
441
442     #define __inner_success(expr)               __declspec("SAL_success("SPECSTRINGIZE(expr)")")
443     #define __inner_checkReturn                 __declspec("SAL_checkReturn")
444     #define __inner_typefix(ctype)              __declspec("SAL_typefix("SPECSTRINGIZE(ctype)")")
445     #define __inner_override                    __declspec("__override")
446     #define __inner_callback                    __declspec("__callback")
447     #define __inner_blocksOn(resource)          __declspec("SAL_blocksOn("SPECSTRINGIZE(resource)")")
448     #define __inner_fallthrough_dec             __inline __nothrow void __FallThrough() {}
449     #define __inner_fallthrough                 __FallThrough();
450
451 #else
452     #define __null
453     #define __notnull
454     #define __maybenull
455     #define __readonly
456     #define __notreadonly
457     #define __maybereadonly
458     #define __valid
459     #define __notvalid
460     #define __maybevalid
461     #define __readableTo(extent)
462     #define __elem_readableTo(size)
463     #define __byte_readableTo(size)
464     #define __writableTo(size)
465     #define __elem_writableTo(size)
466     #define __byte_writableTo(size)
467     #define __deref
468     #define __pre
469     #define __post
470     #define __precond(expr)
471     #define __postcond(expr)
472     #define __exceptthat
473     #define __execeptthat
474     #define __inner_success(expr)
475     #define __inner_checkReturn
476     #define __inner_typefix(ctype)
477     #define __inner_override
478     #define __inner_callback
479     #define __inner_blocksOn(resource)
480     #define __inner_fallthrough_dec
481     #define __inner_fallthrough
482     #define __refparam
483     #define __inner_control_entrypoint(category)
484     #define __inner_data_entrypoint(category)
485 #endif /* #if !defined(__midl) && defined(_PREFAST_) */
486
487 /* 
488 -------------------------------------------------------------------------------
489 Buffer Annotation Definitions
490
491 Any of these may be used to directly annotate functions, but only one should
492 be used for each parameter. To determine which annotation to use for a given
493 buffer, use the table in the buffer annotations section.
494 -------------------------------------------------------------------------------
495 */
496
497 #define __ecount(size)                                          __notnull __elem_writableTo(size)
498 #define __bcount(size)                                          __notnull __byte_writableTo(size)
499 #define __in                                                    __pre __valid __pre __deref __readonly
500 #define __in_ecount(size)                                       __in __pre __elem_readableTo(size)
501 #define __in_bcount(size)                                       __in __pre __byte_readableTo(size)
502 #define __in_z                                                  __in __pre __nullterminated
503 #define __in_ecount_z(size)                                     __in_ecount(size) __pre __nullterminated
504 #define __in_bcount_z(size)                                     __in_bcount(size) __pre __nullterminated
505 #define __in_nz                                                 __in
506 #define __in_ecount_nz(size)                                    __in_ecount(size)
507 #define __in_bcount_nz(size)                                    __in_bcount(size)
508 #define __out                                                   __ecount(1) __post __valid __refparam
509 #define __out_ecount(size)                                      __ecount(size) __post __valid __refparam
510 #define __out_bcount(size)                                      __bcount(size) __post __valid __refparam
511 #define __out_ecount_part(size,length)                          __out_ecount(size) __post __elem_readableTo(length)
512 #define __out_bcount_part(size,length)                          __out_bcount(size) __post __byte_readableTo(length)
513 #define __out_ecount_full(size)                                 __out_ecount_part(size,size)
514 #define __out_bcount_full(size)                                 __out_bcount_part(size,size)
515 #define __out_z                                                 __post __valid __refparam __post __nullterminated
516 #define __out_z_opt                                             __post __valid __refparam __post __nullterminated __exceptthat __maybenull
517 #define __out_ecount_z(size)                                    __ecount(size) __post __valid __refparam __post __nullterminated
518 #define __out_bcount_z(size)                                    __bcount(size) __post __valid __refparam __post __nullterminated
519 #define __out_ecount_part_z(size,length)                        __out_ecount_part(size,length) __post __nullterminated
520 #define __out_bcount_part_z(size,length)                        __out_bcount_part(size,length) __post __nullterminated
521 #define __out_ecount_full_z(size)                               __out_ecount_full(size) __post __nullterminated
522 #define __out_bcount_full_z(size)                               __out_bcount_full(size) __post __nullterminated
523 #define __out_nz                                                __post __valid __refparam __post
524 #define __out_nz_opt                                            __post __valid __refparam __post __exceptthat __maybenull
525 #define __out_ecount_nz(size)                                   __ecount(size) __post __valid __refparam
526 #define __out_bcount_nz(size)                                   __bcount(size) __post __valid __refparam
527 #define __inout                                                 __pre __valid __post __valid __refparam
528 #define __inout_ecount(size)                                    __out_ecount(size) __pre __valid
529 #define __inout_bcount(size)                                    __out_bcount(size) __pre __valid
530 #define __inout_ecount_part(size,length)                        __out_ecount_part(size,length) __pre __valid __pre __elem_readableTo(length)
531 #define __inout_bcount_part(size,length)                        __out_bcount_part(size,length) __pre __valid __pre __byte_readableTo(length)
532 #define __inout_ecount_full(size)                               __inout_ecount_part(size,size)
533 #define __inout_bcount_full(size)                               __inout_bcount_part(size,size)
534 #define __inout_z                                               __inout __pre __nullterminated __post __nullterminated
535 #define __inout_ecount_z(size)                                  __inout_ecount(size) __pre __nullterminated __post __nullterminated
536 #define __inout_bcount_z(size)                                  __inout_bcount(size) __pre __nullterminated __post __nullterminated
537 #define __inout_nz                                              __inout
538 #define __inout_ecount_nz(size)                                 __inout_ecount(size) 
539 #define __inout_bcount_nz(size)                                 __inout_bcount(size) 
540 #define __ecount_opt(size)                                      __ecount(size)                              __exceptthat __maybenull
541 #define __bcount_opt(size)                                      __bcount(size)                              __exceptthat __maybenull
542 #define __in_opt                                                __in                                        __exceptthat __maybenull
543 #define __in_ecount_opt(size)                                   __in_ecount(size)                           __exceptthat __maybenull
544 #define __in_bcount_opt(size)                                   __in_bcount(size)                           __exceptthat __maybenull
545 #define __in_z_opt                                              __in_opt __pre __nullterminated 
546 #define __in_ecount_z_opt(size)                                 __in_ecount_opt(size) __pre __nullterminated 
547 #define __in_bcount_z_opt(size)                                 __in_bcount_opt(size) __pre __nullterminated
548 #define __in_nz_opt                                             __in_opt                                     
549 #define __in_ecount_nz_opt(size)                                __in_ecount_opt(size)                         
550 #define __in_bcount_nz_opt(size)                                __in_bcount_opt(size)                         
551 #define __out_opt                                               __out                                       __exceptthat __maybenull
552 #define __out_ecount_opt(size)                                  __out_ecount(size)                          __exceptthat __maybenull
553 #define __out_bcount_opt(size)                                  __out_bcount(size)                          __exceptthat __maybenull
554 #define __out_ecount_part_opt(size,length)                      __out_ecount_part(size,length)              __exceptthat __maybenull
555 #define __out_bcount_part_opt(size,length)                      __out_bcount_part(size,length)              __exceptthat __maybenull
556 #define __out_ecount_full_opt(size)                             __out_ecount_full(size)                     __exceptthat __maybenull
557 #define __out_bcount_full_opt(size)                             __out_bcount_full(size)                     __exceptthat __maybenull
558 #define __out_ecount_z_opt(size)                                __out_ecount_opt(size) __post __nullterminated
559 #define __out_bcount_z_opt(size)                                __out_bcount_opt(size) __post __nullterminated
560 #define __out_ecount_part_z_opt(size,length)                    __out_ecount_part_opt(size,length) __post __nullterminated
561 #define __out_bcount_part_z_opt(size,length)                    __out_bcount_part_opt(size,length) __post __nullterminated
562 #define __out_ecount_full_z_opt(size)                           __out_ecount_full_opt(size) __post __nullterminated
563 #define __out_bcount_full_z_opt(size)                           __out_bcount_full_opt(size) __post __nullterminated
564 #define __out_ecount_nz_opt(size)                               __out_ecount_opt(size) __post __nullterminated                       
565 #define __out_bcount_nz_opt(size)                               __out_bcount_opt(size) __post __nullterminated                        
566 #define __inout_opt                                             __inout                                     __exceptthat __maybenull
567 #define __inout_ecount_opt(size)                                __inout_ecount(size)                        __exceptthat __maybenull
568 #define __inout_bcount_opt(size)                                __inout_bcount(size)                        __exceptthat __maybenull
569 #define __inout_ecount_part_opt(size,length)                    __inout_ecount_part(size,length)            __exceptthat __maybenull
570 #define __inout_bcount_part_opt(size,length)                    __inout_bcount_part(size,length)            __exceptthat __maybenull
571 #define __inout_ecount_full_opt(size)                           __inout_ecount_full(size)                   __exceptthat __maybenull
572 #define __inout_bcount_full_opt(size)                           __inout_bcount_full(size)                   __exceptthat __maybenull
573 #define __inout_z_opt                                           __inout_opt __pre __nullterminated __post __nullterminated
574 #define __inout_ecount_z_opt(size)                              __inout_ecount_opt(size) __pre __nullterminated __post __nullterminated
575 #define __inout_ecount_z_opt(size)                              __inout_ecount_opt(size) __pre __nullterminated __post __nullterminated
576 #define __inout_bcount_z_opt(size)                              __inout_bcount_opt(size) 
577 #define __inout_nz_opt                                          __inout_opt
578 #define __inout_ecount_nz_opt(size)                             __inout_ecount_opt(size)
579 #define __inout_bcount_nz_opt(size)                             __inout_bcount_opt(size)
580 #define __deref_ecount(size)                                    __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __elem_writableTo(size)
581 #define __deref_bcount(size)                                    __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __byte_writableTo(size)
582 #define __deref_out                                             __deref_ecount(1) __post __deref __valid __refparam
583 #define __deref_out_ecount(size)                                __deref_ecount(size) __post __deref __valid __refparam
584 #define __deref_out_bcount(size)                                __deref_bcount(size) __post __deref __valid __refparam
585 #define __deref_out_ecount_part(size,length)                    __deref_out_ecount(size) __post __deref __elem_readableTo(length)
586 #define __deref_out_bcount_part(size,length)                    __deref_out_bcount(size) __post __deref __byte_readableTo(length)
587 #define __deref_out_ecount_full(size)                           __deref_out_ecount_part(size,size)
588 #define __deref_out_bcount_full(size)                           __deref_out_bcount_part(size,size)
589 #define __deref_out_z                                           __post __deref __valid __refparam __post __deref __nullterminated
590 #define __deref_out_ecount_z(size)                              __deref_out_ecount(size) __post __deref __nullterminated  
591 #define __deref_out_bcount_z(size)                              __deref_out_ecount(size) __post __deref __nullterminated  
592 #define __deref_out_nz                                          __deref_out
593 #define __deref_out_ecount_nz(size)                             __deref_out_ecount(size)   
594 #define __deref_out_bcount_nz(size)                             __deref_out_ecount(size)   
595 #define __deref_inout                                           __notnull __elem_readableTo(1) __pre __deref __valid __post __deref __valid __refparam
596 #define __deref_inout_z                                         __deref_inout __pre __deref __nullterminated __post __deref __nullterminated
597 #define __deref_inout_ecount(size)                              __deref_inout __pre __deref __elem_writableTo(size) __post __deref __elem_writableTo(size)
598 #define __deref_inout_bcount(size)                              __deref_inout __pre __deref __byte_writableTo(size) __post __deref __byte_writableTo(size)
599 #define __deref_inout_ecount_part(size,length)                  __deref_inout_ecount(size) __pre __deref __elem_readableTo(length) __post __deref __elem_readableTo(length)
600 #define __deref_inout_bcount_part(size,length)                  __deref_inout_bcount(size) __pre __deref __byte_readableTo(length) __post __deref __byte_readableTo(length)
601 #define __deref_inout_ecount_full(size)                         __deref_inout_ecount_part(size,size)
602 #define __deref_inout_bcount_full(size)                         __deref_inout_bcount_part(size,size)
603 #define __deref_inout_z                                         __deref_inout __pre __deref __nullterminated __post __deref __nullterminated
604 #define __deref_inout_ecount_z(size)                            __deref_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated   
605 #define __deref_inout_bcount_z(size)                            __deref_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated  
606 #define __deref_inout_nz                                        __deref_inout
607 #define __deref_inout_ecount_nz(size)                           __deref_inout_ecount(size)   
608 #define __deref_inout_bcount_nz(size)                           __deref_inout_ecount(size)   
609 #define __deref_ecount_opt(size)                                __deref_ecount(size)                        __post __deref __exceptthat __maybenull
610 #define __deref_bcount_opt(size)                                __deref_bcount(size)                        __post __deref __exceptthat __maybenull
611 #define __deref_out_opt                                         __deref_out                                 __post __deref __exceptthat __maybenull
612 #define __deref_out_ecount_opt(size)                            __deref_out_ecount(size)                    __post __deref __exceptthat __maybenull
613 #define __deref_out_bcount_opt(size)                            __deref_out_bcount(size)                    __post __deref __exceptthat __maybenull
614 #define __deref_out_ecount_part_opt(size,length)                __deref_out_ecount_part(size,length)        __post __deref __exceptthat __maybenull
615 #define __deref_out_bcount_part_opt(size,length)                __deref_out_bcount_part(size,length)        __post __deref __exceptthat __maybenull
616 #define __deref_out_ecount_full_opt(size)                       __deref_out_ecount_full(size)               __post __deref __exceptthat __maybenull
617 #define __deref_out_bcount_full_opt(size)                       __deref_out_bcount_full(size)               __post __deref __exceptthat __maybenull
618 #define __deref_out_z_opt                                       __post __deref __valid __refparam __execeptthat __maybenull __post __deref __nullterminated
619 #define __deref_out_ecount_z_opt(size)                          __deref_out_ecount_opt(size) __post __deref __nullterminated
620 #define __deref_out_bcount_z_opt(size)                          __deref_out_bcount_opt(size) __post __deref __nullterminated
621 #define __deref_out_nz_opt                                      __deref_out_opt
622 #define __deref_out_ecount_nz_opt(size)                         __deref_out_ecount_opt(size)
623 #define __deref_out_bcount_nz_opt(size)                         __deref_out_bcount_opt(size)
624 #define __deref_inout_opt                                       __deref_inout                               __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
625 #define __deref_inout_ecount_opt(size)                          __deref_inout_ecount(size)                  __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
626 #define __deref_inout_bcount_opt(size)                          __deref_inout_bcount(size)                  __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
627 #define __deref_inout_ecount_part_opt(size,length)              __deref_inout_ecount_part(size,length)      __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
628 #define __deref_inout_bcount_part_opt(size,length)              __deref_inout_bcount_part(size,length)      __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
629 #define __deref_inout_ecount_full_opt(size)                     __deref_inout_ecount_full(size)             __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
630 #define __deref_inout_bcount_full_opt(size)                     __deref_inout_bcount_full(size)             __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
631 #define __deref_inout_z_opt                                     __deref_inout_opt __pre __deref __nullterminated __post __deref __nullterminated
632 #define __deref_inout_ecount_z_opt(size)                        __deref_inout_ecount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated
633 #define __deref_inout_bcount_z_opt(size)                        __deref_inout_bcount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated
634 #define __deref_inout_nz_opt                                    __deref_inout_opt 
635 #define __deref_inout_ecount_nz_opt(size)                       __deref_inout_ecount_opt(size)
636 #define __deref_inout_bcount_nz_opt(size)                       __deref_inout_bcount_opt(size)
637 #define __deref_opt_ecount(size)                                __deref_ecount(size)                        __exceptthat __maybenull
638 #define __deref_opt_bcount(size)                                __deref_bcount(size)                        __exceptthat __maybenull
639 #define __deref_opt_out                                         __deref_out                                 __exceptthat __maybenull
640 #define __deref_opt_out_z                                       __deref_opt_out __post __deref __nullterminated
641 #define __deref_opt_out_ecount(size)                            __deref_out_ecount(size)                    __exceptthat __maybenull
642 #define __deref_opt_out_bcount(size)                            __deref_out_bcount(size)                    __exceptthat __maybenull
643 #define __deref_opt_out_ecount_part(size,length)                __deref_out_ecount_part(size,length)        __exceptthat __maybenull
644 #define __deref_opt_out_bcount_part(size,length)                __deref_out_bcount_part(size,length)        __exceptthat __maybenull
645 #define __deref_opt_out_ecount_full(size)                       __deref_out_ecount_full(size)               __exceptthat __maybenull
646 #define __deref_opt_out_bcount_full(size)                       __deref_out_bcount_full(size)               __exceptthat __maybenull
647 #define __deref_opt_inout                                       __deref_inout                               __exceptthat __maybenull
648 #define __deref_opt_inout_ecount(size)                          __deref_inout_ecount(size)                  __exceptthat __maybenull
649 #define __deref_opt_inout_bcount(size)                          __deref_inout_bcount(size)                  __exceptthat __maybenull
650 #define __deref_opt_inout_ecount_part(size,length)              __deref_inout_ecount_part(size,length)      __exceptthat __maybenull
651 #define __deref_opt_inout_bcount_part(size,length)              __deref_inout_bcount_part(size,length)      __exceptthat __maybenull
652 #define __deref_opt_inout_ecount_full(size)                     __deref_inout_ecount_full(size)             __exceptthat __maybenull
653 #define __deref_opt_inout_bcount_full(size)                     __deref_inout_bcount_full(size)             __exceptthat __maybenull
654 #define __deref_opt_inout_z                                     __deref_opt_inout __pre __deref __nullterminated __post __deref __nullterminated
655 #define __deref_opt_inout_ecount_z(size)                        __deref_opt_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated
656 #define __deref_opt_inout_bcount_z(size)                        __deref_opt_inout_bcount(size) __pre __deref __nullterminated __post __deref __nullterminated
657 #define __deref_opt_inout_nz                                    __deref_opt_inout
658 #define __deref_opt_inout_ecount_nz(size)                       __deref_opt_inout_ecount(size)
659 #define __deref_opt_inout_bcount_nz(size)                       __deref_opt_inout_bcount(size)
660 #define __deref_opt_ecount_opt(size)                            __deref_ecount_opt(size)                    __exceptthat __maybenull
661 #define __deref_opt_bcount_opt(size)                            __deref_bcount_opt(size)                    __exceptthat __maybenull
662 #define __deref_opt_out_opt                                     __deref_out_opt                             __exceptthat __maybenull
663 #define __deref_opt_out_ecount_opt(size)                        __deref_out_ecount_opt(size)                __exceptthat __maybenull
664 #define __deref_opt_out_bcount_opt(size)                        __deref_out_bcount_opt(size)                __exceptthat __maybenull
665 #define __deref_opt_out_ecount_part_opt(size,length)            __deref_out_ecount_part_opt(size,length)    __exceptthat __maybenull
666 #define __deref_opt_out_bcount_part_opt(size,length)            __deref_out_bcount_part_opt(size,length)    __exceptthat __maybenull
667 #define __deref_opt_out_ecount_full_opt(size)                   __deref_out_ecount_full_opt(size)           __exceptthat __maybenull
668 #define __deref_opt_out_bcount_full_opt(size)                   __deref_out_bcount_full_opt(size)           __exceptthat __maybenull
669 #define __deref_opt_out_z_opt                                   __post __deref __valid __refparam __exceptthat __maybenull __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull __post __deref __nullterminated
670 #define __deref_opt_out_ecount_z_opt(size)                      __deref_opt_out_ecount_opt(size) __post __deref __nullterminated
671 #define __deref_opt_out_bcount_z_opt(size)                      __deref_opt_out_bcount_opt(size) __post __deref __nullterminated
672 #define __deref_opt_out_nz_opt                                  __deref_opt_out_opt
673 #define __deref_opt_out_ecount_nz_opt(size)                     __deref_opt_out_ecount_opt(size)    
674 #define __deref_opt_out_bcount_nz_opt(size)                     __deref_opt_out_bcount_opt(size)    
675 #define __deref_opt_inout_opt                                   __deref_inout_opt                           __exceptthat __maybenull
676 #define __deref_opt_inout_ecount_opt(size)                      __deref_inout_ecount_opt(size)              __exceptthat __maybenull
677 #define __deref_opt_inout_bcount_opt(size)                      __deref_inout_bcount_opt(size)              __exceptthat __maybenull
678 #define __deref_opt_inout_ecount_part_opt(size,length)          __deref_inout_ecount_part_opt(size,length)  __exceptthat __maybenull
679 #define __deref_opt_inout_bcount_part_opt(size,length)          __deref_inout_bcount_part_opt(size,length)  __exceptthat __maybenull
680 #define __deref_opt_inout_ecount_full_opt(size)                 __deref_inout_ecount_full_opt(size)         __exceptthat __maybenull
681 #define __deref_opt_inout_bcount_full_opt(size)                 __deref_inout_bcount_full_opt(size)         __exceptthat __maybenull
682 #define __deref_opt_inout_z_opt                                 __deref_opt_inout_opt  __pre __deref __nullterminated __post __deref __nullterminated             
683 #define __deref_opt_inout_ecount_z_opt(size)                    __deref_opt_inout_ecount_opt(size)  __pre __deref __nullterminated __post __deref __nullterminated
684 #define __deref_opt_inout_bcount_z_opt(size)                    __deref_opt_inout_bcount_opt(size)  __pre __deref __nullterminated __post __deref __nullterminated
685 #define __deref_opt_inout_nz_opt                                __deref_opt_inout_opt               
686 #define __deref_opt_inout_ecount_nz_opt(size)                   __deref_opt_inout_ecount_opt(size)  
687 #define __deref_opt_inout_bcount_nz_opt(size)                   __deref_opt_inout_bcount_opt(size)  
688
689 /*
690 -------------------------------------------------------------------------------
691 Advanced Annotation Definitions
692
693 Any of these may be used to directly annotate functions, and may be used in
694 combination with each other or with regular buffer macros. For an explanation
695 of each annotation, see the advanced annotations section.
696 -------------------------------------------------------------------------------
697 */
698
699 #define __success(expr)                     __inner_success(expr)
700 #define __nullterminated                    __readableTo(sentinel(0))
701 #define __nullnullterminated
702 #define __reserved                          __pre __null
703 #define __checkReturn                       __inner_checkReturn
704 #define __typefix(ctype)                    __inner_typefix(ctype)
705 #define __override                          __inner_override
706 #define __callback                          __inner_callback
707 #define __format_string
708 #define __blocksOn(resource)                __inner_blocksOn(resource)
709 #define __control_entrypoint(category)      __inner_control_entrypoint(category)
710 #define __data_entrypoint(category)         __inner_data_entrypoint(category)
711
712 #ifndef __fallthrough
713     __inner_fallthrough_dec
714     #define __fallthrough __inner_fallthrough
715 #endif
716
717 #ifndef __analysis_assume
718 #ifdef _PREFAST_
719 #define __analysis_assume(expr) __assume(expr)
720 #else
721 #define __analysis_assume(expr) 
722 #endif
723 #endif
724
725 #ifdef  __cplusplus
726 }
727 #endif
728
729