Add a .gitattributes with "* text=auto" so that new lines are
[pdfium.git] / core / src / fxge / Microsoft SDK / include / specstrings.h
1 /***************************************************************\
2 *                                                               *
3 * SpecStrings.h - markers for documenting the semantics of APIs *
4 *                                                               *
5 * Version 1.0                                                   *
6 *                                                               *
7 * Copyright (c) Microsoft Corporation. All rights reserved.     *
8 *                                                               *
9 \***************************************************************/
10
11 // @@BEGIN_DDKSPLIT
12
13 // -------------------------------------------------------------------------------
14 // Introduction
15 //
16 // SpecStrings.h provides a set of annotations to describe how a function uses its
17 // parameters - the assumptions it makes about them, and the guarantees it makes
18 // upon finishing.
19 //
20 // Annotations may be placed before either a function parameter's type or its return
21 // type, and describe the function's behavior regarding the parameter or return value.
22 // There are two classes of annotations: buffer annotations and advanced annotations.
23 // Buffer annotations describe how functions use their pointer parameters, and
24 // advanced annotations either describe complex/unusual buffer behavior, or provide
25 // additional information about a parameter that is not otherwise expressible.
26 //
27 // -------------------------------------------------------------------------------
28 // Buffer Annotations
29 //
30 // The most important annotations in SpecStrings.h provide a consistent way to annotate
31 // buffer parameters or return values for a function. Each of these annotations describes
32 // a single buffer (which could be a string, a fixed-length or variable-length array,
33 // or just a pointer) that the function interacts with: where it is, how large it is,
34 // how much is initialized, and what the function does with it.
35 //
36 // The appropriate macro for a given buffer can be constructed using the table below.
37 // Just pick the appropriate values from each category, and combine them together
38 // with a leading underscore. Some combinations of values do not make sense as buffer
39 // annotations. Only meaningful annotations can be added to your code; for a list of
40 // these, see the buffer annotation definitions section.
41 //
42 // Only a single buffer annotation should be used for each parameter.
43 //
44 // |------------|------------|---------|--------|----------|---------------|
45 // |   Level    |   Usage    |  Size   | Output | Optional |  Parameters   |
46 // |------------|------------|---------|--------|----------|---------------|
47 // | <>         | <>         | <>      | <>     | <>       | <>            |
48 // | _deref     | _in        | _ecount | _full  | _opt     | (size)        |
49 // | _deref_opt | _out       | _bcount | _part  |          | (size,length) |
50 // |            | _inout     |         |        |          |               |
51 // |            |            |         |        |          |               |
52 // |------------|------------|---------|--------|----------|---------------|
53 //
54 // Level: Describes the buffer pointer's level of indirection from the parameter or
55 //          return value 'p'.
56 //
57 // <>         : p is the buffer pointer.
58 // _deref     : *p is the buffer pointer. p must not be NULL.
59 // _deref_opt : *p may be the buffer pointer. p may be NULL, in which case the rest of
60 //                the annotation is ignored.
61 //
62 // Usage: Describes how the function uses the buffer.
63 //
64 // <>     : The buffer is not accessed. If used on the return value or with _deref, the
65 //            function will provide the buffer, and it will be uninitialized at exit.
66 //            Otherwise, the caller must provide the buffer. This should only be used
67 //            for alloc and free functions.
68 // _in    : The function will only read from the buffer. The caller must provide the
69 //            buffer and initialize it.
70 // _out   : The function will only write to the buffer. If used on the return value or
71 //            with _deref, the function will provide the buffer and initialize it.
72 //            Otherwise, the caller must provide the buffer, and the function will
73 //            initialize it.
74 // _inout : The function may freely read from and write to the buffer. The caller must
75 //            provide the buffer and initialize it. If used with _deref, the buffer may
76 //            be reallocated by the function.
77 //
78 // Size: Describes the total size of the buffer. This may be less than the space actually
79 //         allocated for the buffer, in which case it describes the accessible amount.
80 //
81 // <>      : No buffer size is given. If the type specifies the buffer size (such as
82 //             with LPSTR and LPWSTR), that amount is used. Otherwise, the buffer is one
83 //             element long. Must be used with _in, _out, or _inout.
84 // _ecount : The buffer size is an explicit element count.
85 // _bcount : The buffer size is an explicit byte count.
86 //
87 // Output: Describes how much of the buffer will be initialized by the function. For
88 //           _inout buffers, this also describes how much is initialized at entry. Omit this
89 //           category for _in buffers; they must be fully initialized by the caller.
90 //
91 // <>    : The type specifies how much is initialized. For instance, a function initializing
92 //           an LPWSTR must NULL-terminate the string.
93 // _full : The function initializes the entire buffer.
94 // _part : The function initializes part of the buffer, and explicitly indicates how much.
95 //
96 // Optional: Describes if the buffer itself is optional.
97 //
98 // <>   : The pointer to the buffer must not be NULL.
99 // _opt : The pointer to the buffer might be NULL. It will be checked before being dereferenced.
100 //
101 // Parameters: Gives explicit counts for the size and length of the buffer.
102 //
103 // <>            : There is no explicit count. Use when neither _ecount nor _bcount is used.
104 // (size)        : Only the buffer's total size is given. Use with _ecount or _bcount but not _part.
105 // (size,length) : The buffer's total size and initialized length are given. Use with _ecount_part
106 //                   and _bcount_part.
107 //
108 // -------------------------------------------------------------------------------
109 // Buffer Annotation Examples
110 //
111 // LWSTDAPI_(BOOL) StrToIntExA(
112 //     LPCSTR pszString,                    // No annotation required, const implies __in.
113 //     DWORD dwFlags,
114 //     __out int *piRet                     // A pointer whose dereference will be filled in.
115 // );
116 //
117 // void MyPaintingFunction(
118 //     __in HWND hwndControl,               // An initialized read-only parameter.
119 //     __in_opt HDC hdcOptional,            // An initialized read-only parameter that might be NULL.
120 //     __inout IPropertyStore *ppsStore     // An initialized parameter that may be freely used
121 //                                          //   and modified.
122 // );
123 //
124 // LWSTDAPI_(BOOL) PathCompactPathExA(
125 //     __out_ecount(cchMax) LPSTR pszOut,   // A string buffer with cch elements that will
126 //                                          //   be NULL terminated on exit.
127 //     LPCSTR pszSrc,                       // No annotation required, const implies __in.
128 //     UINT cchMax,
129 //     DWORD dwFlags
130 // );
131 //
132 // HRESULT SHLocalAllocBytes(
133 //     size_t cb,
134 //     __deref_bcount(cb) T **ppv           // A pointer whose dereference will be set to an
135 //                                          //   uninitialized buffer with cb bytes.
136 // );
137 //
138 // __inout_bcount_full(cb) : A buffer with cb elements that is fully initialized at
139 //     entry and exit, and may be written to by this function.
140 //
141 // __out_ecount_part(count, *countOut) : A buffer with count elements that will be
142 //     partially initialized by this function. The function indicates how much it
143 //     initialized by setting *countOut.
144 //
145 // -------------------------------------------------------------------------------
146 // Advanced Annotations
147 //
148 // Advanced annotations describe behavior that is not expressible with the regular
149 // buffer macros. These may be used either to annotate buffer parameters that involve
150 // complex or conditional behavior, or to enrich existing annotations with additional
151 // information.
152 //
153 // __success(expr) f :
154 //     <expr> indicates whether function f succeeded or not. If <expr> is true at exit,
155 //     all the function's guarantees (as given by other annotations) must hold. If <expr>
156 //     is false at exit, the caller should not expect any of the function's guarantees
157 //     to hold. If not used, the function must always satisfy its guarantees. Added
158 //     automatically to functions that indicate success in standard ways, such as by
159 //     returning an HRESULT.
160 //
161 // __out_awcount(expr, size) p :
162 //     Pointer p is a buffer whose size may be given in either bytes or elements. If
163 //     <expr> is true, this acts like __out_bcount. If <expr> is false, this acts
164 //     like __out_ecount. This should only be used to annotate old APIs.
165 //
166 // __in_awcount(expr, size) p :
167 //     Pointer p is a buffer whose size may be given in either bytes or elements. If
168 //     <expr> is true, this acts like __in_bcount. If <expr> is false, this acts
169 //     like __in_ecount. This should only be used to annotate old APIs.
170 //
171 // __nullterminated p :
172 //     Pointer p is a buffer that may be read or written up to and including the first
173 //     NULL character or pointer. May be used on typedefs, which marks valid (properly
174 //     initialized) instances of that type as being NULL-terminated.
175 //
176 // __nullnullterminated p :
177 //     Pointer p is a buffer that may be read or written up to and including the first
178 //     sequence of two NULL characters or pointers. May be used on typedefs, which marks
179 //     valid instances of that type as being double-NULL terminated.
180 //
181 // __reserved v :
182 //     Value v must be 0/NULL, reserved for future use.
183 //
184 // __checkReturn v :
185 //     Return value v must not be ignored by callers of this function.
186 //
187 // __typefix(ctype) v :
188 //     Value v should be treated as an instance of ctype, rather than its declared type.
189 //
190 // __override f :
191 //     Specify C#-style 'override' behaviour for overriding virtual methods.
192 //
193 // __callback f :
194 //     Function f can be used as a function pointer.
195 //
196 // __format_string p :
197 //     Pointer p is a string that contains % markers in the style of printf.
198 //
199 // __blocksOn(resource) f :
200 //     Function f blocks on the resource 'resource'.
201 //
202 // __fallthrough :
203 //     Annotates switch statement labels where fall-through is desired, to distinguish
204 //     from forgotten break statements.
205 //
206 // -------------------------------------------------------------------------------
207 // Advanced Annotation Examples
208 //
209 // __success(return == TRUE) LWSTDAPI_(BOOL) 
210 // PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) :
211 //     pszBuf is only guaranteed to be NULL-terminated when TRUE is returned.
212 //
213 // typedef __nullterminated WCHAR* LPWSTR : Initialized LPWSTRs are NULL-terminated strings.
214 //
215 // __out_ecount(cch) __typefix(LPWSTR) void *psz : psz is a buffer parameter which will be
216 //     a NULL-terminated WCHAR string at exit, and which initially contains cch WCHARs.
217 //
218 // -------------------------------------------------------------------------------
219
220 // @@END_DDKSPLIT
221
222 #if _MSC_VER > 1000
223 #pragma once
224 #endif  // #if _MSC_VER > 1000
225
226 #define __specstrings
227
228 #ifdef  __cplusplus
229 #ifndef __nothrow
230 # define __nothrow __declspec(nothrow)
231 #endif
232 extern "C" {
233 #else
234 #ifndef __nothrow
235 # define __nothrow
236 #endif
237 #endif  // #ifdef __cplusplus
238
239 // @@BEGIN_DDKSPLIT
240
241 // -------------------------------------------------------------------------------
242 // Helper Macro Definitions
243 //
244 // These express behavior common to many of the high-level annotations.
245 // DO NOT USE THESE IN YOUR CODE.
246 // -------------------------------------------------------------------------------
247
248 // The helper annotations are only understood by the compiler version used by various
249 // defect detection tools. When the regular compiler is running, they are defined into
250 // nothing, and do not affect the compiled code.
251 #if (_MSC_VER >= 1000) && !defined(MIDL_PASS) && defined(_PREFAST_)
252
253     // In the primitive __declspec("SAL_*") annotations "SAL" stands for Standard
254     // Annotation Language.  These __declspec("SAL_*") annotations are the
255     // primitives the compiler understands and all high-level SpecString MACROs
256     // will decompose into these primivates.
257
258     #define SPECSTRINGIZE( x ) #x
259
260     //
261     // __null p
262     // __notnull p
263     // __maybenull p
264     //
265     // Annotates a pointer p. States that pointer p is null. Commonly used
266     // in the negated form __notnull or the possibly null form __maybenull.
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     #define __readonly              __declspec("SAL_readonly")
285     #define __notreadonly           __declspec("SAL_notreadonly")
286     #define __maybereadonly         __declspec("SAL_maybereadonly")
287
288     //
289     // __valid v
290     // __notvalid v
291     // __maybevalid v
292     //
293     // Annotates any value v. States that the value satisfies all properties of
294     // valid values of its type. For example, for a string buffer, valid means
295     // that the buffer pointer is either NULL or points to a NULL-terminated string.
296     //
297     #define __valid                 __declspec("SAL_valid")
298     #define __notvalid              __declspec("SAL_notvalid")
299     #define __maybevalid            __declspec("SAL_maybevalid")
300
301     //
302     // __readableTo(extent) p
303     //
304     // Annotates a buffer pointer p.  If the buffer can be read, extent describes
305     // how much of the buffer is readable. For a reader of the buffer, this is
306     // an explicit permission to read up to that amount, rather than a restriction to
307     // read only up to it.
308     //
309     #define __readableTo(extent)    __declspec("SAL_readableTo("SPECSTRINGIZE(extent)")")
310
311     //
312     // __elem_readableTo(size)
313     //
314     // Annotates a buffer pointer p as being readable to size elements.
315     //
316     #define __elem_readableTo(size)   __declspec("SAL_readableTo(elementCount("SPECSTRINGIZE(size)"))")
317     
318     //
319     // __byte_readableTo(size)
320     //
321     // Annotates a buffer pointer p as being readable to size bytes.
322     //
323     #define __byte_readableTo(size)   __declspec("SAL_readableTo(byteCount("SPECSTRINGIZE(size)"))")
324     
325     //
326     // __writableTo(extent) p
327     //
328     // Annotates a buffer pointer p. If the buffer can be modified, extent
329     // describes how much of the buffer is writable (usually the allocation
330     // size). For a writer of the buffer, this is an explicit permission to
331     // write up to that amount, rather than a restriction to write only up to it.
332     //
333     #define __writableTo(size)   __declspec("SAL_writableTo("SPECSTRINGIZE(size)")")
334
335     //
336     // __elem_writableTo(size)
337     //
338     // Annotates a buffer pointer p as being writable to size elements.
339     //
340     #define __elem_writableTo(size)   __declspec("SAL_writableTo(elementCount("SPECSTRINGIZE(size)"))")
341     
342     //
343     // __byte_writableTo(size)
344     //
345     // Annotates a buffer pointer p as being writable to size bytes.
346     //
347     #define __byte_writableTo(size)   __declspec("SAL_writableTo(byteCount("SPECSTRINGIZE(size)"))")
348
349     //
350     // __deref p
351     //
352     // Annotates a pointer p. The next annotation applies one dereference down
353     // in the type. If readableTo(p, size) then the next annotation applies to
354     // all elements *(p+i) for which i satisfies the size. If p is a pointer
355     // to a struct, the next annotation applies to all fields of the struct.
356     //
357     #define __deref                 __declspec("SAL_deref")
358     
359     //
360     // __pre __next_annotation
361     //
362     // The next annotation applies in the precondition state
363     //
364     #define __pre                   __declspec("SAL_pre")
365     
366     //
367     // __post __next_annotation
368     //
369     // The next annotation applies in the postcondition state
370     //
371     #define __post                  __declspec("SAL_post")
372     
373     //
374     // __precond(<expr>)
375     //
376     // When <expr> is true, the next annotation applies in the precondition state
377     // (currently not enabled)
378     //
379     #define __precond(expr)         __pre
380
381     //
382     // __postcond(<expr>)
383     //
384     // When <expr> is true, the next annotation applies in the postcondition state
385     // (currently not enabled)
386     //
387     #define __postcond(expr)        __post
388
389     //
390     // __exceptthat
391     //
392     // Given a set of annotations Q containing __exceptthat maybeP, the effect of
393     // the except clause is to erase any P or notP annotations (explicit or
394     // implied) within Q at the same level of dereferencing that the except
395     // clause appears, and to replace it with maybeP.
396     //
397     //  Example 1: __valid __exceptthat __maybenull on a pointer p means that the
398     //             pointer may be null, and is otherwise valid, thus overriding
399     //             the implicit notnull annotation implied by __valid on
400     //             pointers.
401     //
402     //  Example 2: __valid __deref __exceptthat __maybenull on an int **p means
403     //             that p is not null (implied by valid), but the elements
404     //             pointed to by p could be null, and are otherwise valid. 
405     //
406     #define __exceptthat                __declspec("SAL_except")
407
408     //
409     // _refparam
410     //
411     // Added to all out parameter macros to indicate that they are all reference
412     // parameters.
413     //
414     #define __refparam                  __deref __notreadonly
415
416     //
417     // __inner_*
418     //
419     // Helper macros that directly correspond to certain high-level annotations.
420     //
421     //
422
423     // Macros to classify the entrypoints and indicate their category.
424     //
425     //
426     // Pre-defined control point categories include: RPC, LPC, DeviceDriver, UserToKernel, ISAPI, COM.
427     //
428     #define __inner_control_entrypoint(category) __declspec("SAL_entrypoint(controlEntry, "SPECSTRINGIZE(category)")")
429
430     //
431     // Pre-defined data entry point categories include: Registry, File, Network.
432     //
433     #define __inner_data_entrypoint(category)    __declspec("SAL_entrypoint(dataEntry, "SPECSTRINGIZE(category)")")
434
435     #define __inner_success(expr)               __declspec("SAL_success("SPECSTRINGIZE(expr)")")
436     #define __inner_checkReturn                 __declspec("SAL_checkReturn")
437     #define __inner_typefix(ctype)              __declspec("SAL_typefix("SPECSTRINGIZE(ctype)")")
438     #define __inner_override                    __declspec("__override")
439     #define __inner_callback                    __declspec("__callback")
440     #define __inner_blocksOn(resource)          __declspec("SAL_blocksOn("SPECSTRINGIZE(resource)")")
441     #define __inner_fallthrough_dec             __inline __nothrow void __FallThrough() {}
442     #define __inner_fallthrough                 __FallThrough();
443
444 #else
445
446 // @@END_DDKSPLIT
447
448 #ifndef __null
449     #define __null
450 #endif
451 #ifndef __notnull
452     #define __notnull
453 #endif
454 #ifndef __maybenull
455     #define __maybenull
456 #endif
457 #ifndef __readonly
458     #define __readonly
459 #endif
460 #ifndef __notreadonly
461     #define __notreadonly
462 #endif
463 #ifndef __maybereadonly
464     #define __maybereadonly
465 #endif
466 #ifndef __valid
467     #define __valid
468 #endif
469 #ifndef __notvalid
470     #define __notvalid
471 #endif
472 #ifndef __maybevalid
473     #define __maybevalid
474 #endif
475 #ifndef __readableTo
476     #define __readableTo(extent)
477 #endif
478 #ifndef __elem_readableTo
479     #define __elem_readableTo(size)
480 #endif
481 #ifndef __byte_readableTo
482     #define __byte_readableTo(size)
483 #endif
484 #ifndef __writableTo
485     #define __writableTo(size)
486 #endif
487 #ifndef __elem_writableTo
488     #define __elem_writableTo(size)
489 #endif
490 #ifndef __byte_writableTo
491     #define __byte_writableTo(size)
492 #endif
493 #ifndef __deref
494     #define __deref
495 #endif
496 #ifndef __pre
497     #define __pre
498 #endif
499 #ifndef __post
500     #define __post
501 #endif
502 #ifndef __precond
503     #define __precond(expr)
504 #endif
505 #ifndef __postcond
506     #define __postcond(expr)
507 #endif
508 #ifndef __exceptthat
509     #define __exceptthat
510 #endif
511 #ifndef __inner_success
512     #define __inner_success(expr)
513 #endif
514 #ifndef __inner_checkReturn
515     #define __inner_checkReturn
516 #endif
517 #ifndef __inner_typefix
518     #define __inner_typefix(ctype)
519 #endif
520 #ifndef __inner_override
521     #define __inner_override
522 #endif
523 #ifndef __inner_callback
524     #define __inner_callback
525 #endif
526 #ifndef __inner_blocksOn
527     #define __inner_blocksOn(resource)
528 #endif
529 #ifndef __inner_fallthrough_dec
530     #define __inner_fallthrough_dec
531 #endif
532 #ifndef __inner_fallthrough
533     #define __inner_fallthrough
534 #endif
535 #ifndef __refparam
536     #define __refparam
537 #endif
538 #ifndef __inner_control_entrypoint
539     #define __inner_control_entrypoint(category)
540 #endif
541 #ifndef __inner_data_entrypoint
542     #define __inner_data_entrypoint(category)
543 #endif
544 // @@BEGIN_DDKSPLIT
545 #endif // #if (_MSC_VER >= 1000) && !defined(MIDL_PASS) && defined(_PREFAST_)
546 // -------------------------------------------------------------------------------
547 // Buffer Annotation Definitions
548 //
549 // Any of these may be used to directly annotate functions, but only one should
550 // be used for each parameter. To determine which annotation to use for a given
551 // buffer, use the table in the buffer annotations section.
552 // -------------------------------------------------------------------------------
553 // @@END_DDKSPLIT
554
555 #ifndef __ecount
556 #define __ecount(size)                                          __notnull __elem_writableTo(size)
557 #endif
558 #ifndef __bcount
559 #define __bcount(size)                                          __notnull __byte_writableTo(size)
560 #endif
561 #ifndef __in
562 #define __in                                                    __pre __valid __pre __deref __readonly
563 #endif
564 #ifndef __in_ecount
565 #define __in_ecount(size)                                       __in __pre __elem_readableTo(size)
566 #endif
567 #ifndef __in_bcount
568 #define __in_bcount(size)                                       __in __pre __byte_readableTo(size)
569 #endif
570 #ifndef __out
571 #define __out                                                   __ecount(1) __post __valid __refparam
572 #endif
573 #ifndef __out_ecount
574 #define __out_ecount(size)                                      __ecount(size) __post __valid __refparam
575 #endif
576 #ifndef __out_bcount
577 #define __out_bcount(size)                                      __bcount(size) __post __valid __refparam
578 #endif
579 #ifndef __out_ecount_part
580 #define __out_ecount_part(size,length)                          __out_ecount(size) __post __elem_readableTo(length)
581 #endif
582 #ifndef __out_bcount_part
583 #define __out_bcount_part(size,length)                          __out_bcount(size) __post __byte_readableTo(length)
584 #endif
585 #ifndef __out_ecount_full
586 #define __out_ecount_full(size)                                 __out_ecount_part(size,size)
587 #endif
588 #ifndef __out_bcount_full
589 #define __out_bcount_full(size)                                 __out_bcount_part(size,size)
590 #endif
591 #ifndef __inout
592 #define __inout                                                 __pre __valid __post __valid __refparam
593 #endif
594 #ifndef __inout_ecount
595 #define __inout_ecount(size)                                    __out_ecount(size) __pre __valid
596 #endif
597 #ifndef __inout_bcount
598 #define __inout_bcount(size)                                    __out_bcount(size) __pre __valid
599 #endif
600 #ifndef __inout_ecount_part
601 #define __inout_ecount_part(size,length)                        __out_ecount_part(size,length) __pre __valid __pre __elem_readableTo(length)
602 #endif
603 #ifndef __inout_bcount_part
604 #define __inout_bcount_part(size,length)                        __out_bcount_part(size,length) __pre __valid __pre __byte_readableTo(length)
605 #endif
606 #ifndef __inout_ecount_full
607 #define __inout_ecount_full(size)                               __inout_ecount_part(size,size)
608 #endif
609 #ifndef __inout_bcount_full
610 #define __inout_bcount_full(size)                               __inout_bcount_part(size,size)
611 #endif
612
613 #ifndef __ecount_opt
614 #define __ecount_opt(size)                                      __ecount(size)                              __exceptthat __maybenull
615 #endif
616 #ifndef __bcount_opt
617 #define __bcount_opt(size)                                      __bcount(size)                              __exceptthat __maybenull
618 #endif
619 #ifndef __in_opt
620 #define __in_opt                                                __in                                        __exceptthat __maybenull
621 #endif
622 #ifndef __in_ecount_opt
623 #define __in_ecount_opt(size)                                   __in_ecount(size)                           __exceptthat __maybenull
624 #endif
625 #ifndef __in_bcount_opt
626 #define __in_bcount_opt(size)                                   __in_bcount(size)                           __exceptthat __maybenull
627 #endif
628 #ifndef __out_opt
629 #define __out_opt                                               __out                                       __exceptthat __maybenull
630 #endif
631 #ifndef __out_ecount_opt
632 #define __out_ecount_opt(size)                                  __out_ecount(size)                          __exceptthat __maybenull
633 #endif
634 #ifndef __out_bcount_opt
635 #define __out_bcount_opt(size)                                  __out_bcount(size)                          __exceptthat __maybenull
636 #endif
637 #ifndef __out_ecount_part_opt
638 #define __out_ecount_part_opt(size,length)                      __out_ecount_part(size,length)              __exceptthat __maybenull
639 #endif
640 #ifndef __out_bcount_part_opt
641 #define __out_bcount_part_opt(size,length)                      __out_bcount_part(size,length)              __exceptthat __maybenull
642 #endif
643 #ifndef __out_ecount_full_opt
644 #define __out_ecount_full_opt(size)                             __out_ecount_full(size)                     __exceptthat __maybenull
645 #endif
646 #ifndef __out_bcount_full_opt
647 #define __out_bcount_full_opt(size)                             __out_bcount_full(size)                     __exceptthat __maybenull
648 #endif
649 #ifndef __inout_opt
650 #define __inout_opt                                             __inout                                     __exceptthat __maybenull
651 #endif
652 #ifndef __inout_ecount_opt
653 #define __inout_ecount_opt(size)                                __inout_ecount(size)                        __exceptthat __maybenull
654 #endif
655 #ifndef __inout_bcount_opt
656 #define __inout_bcount_opt(size)                                __inout_bcount(size)                        __exceptthat __maybenull
657 #endif
658 #ifndef __inout_ecount_part_opt
659 #define __inout_ecount_part_opt(size,length)                    __inout_ecount_part(size,length)            __exceptthat __maybenull
660 #endif
661 #ifndef __inout_bcount_part_opt
662 #define __inout_bcount_part_opt(size,length)                    __inout_bcount_part(size,length)            __exceptthat __maybenull
663 #endif
664 #ifndef __inout_ecount_full_opt
665 #define __inout_ecount_full_opt(size)                           __inout_ecount_full(size)                   __exceptthat __maybenull
666 #endif
667 #ifndef __inout_bcount_full_opt
668 #define __inout_bcount_full_opt(size)                           __inout_bcount_full(size)                   __exceptthat __maybenull
669 #endif
670
671 #ifndef __deref_ecount
672 #define __deref_ecount(size)                                    __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __elem_writableTo(size)
673 #endif
674 #ifndef __deref_bcount
675 #define __deref_bcount(size)                                    __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __byte_writableTo(size)
676 #endif
677 #ifndef __deref_in
678 #define __deref_in                                              __in __pre __deref __deref __readonly
679 #endif
680 #ifndef __deref_in_ecount
681 #define __deref_in_ecount(size)                                 __deref_in __pre __deref __elem_readableTo(size)
682 #endif
683 #ifndef __deref_in_bcount
684 #define __deref_in_bcount(size)                                 __deref_in __pre __deref __byte_readableTo(size)
685 #endif
686 #ifndef __deref_out
687 #define __deref_out                                             __deref_ecount(1) __post __deref __valid __refparam
688 #endif
689 #ifndef __deref_out_ecount
690 #define __deref_out_ecount(size)                                __deref_ecount(size) __post __deref __valid __refparam
691 #endif
692 #ifndef __deref_out_bcount
693 #define __deref_out_bcount(size)                                __deref_bcount(size) __post __deref __valid __refparam
694 #endif
695 #ifndef __deref_out_ecount_part
696 #define __deref_out_ecount_part(size,length)                    __deref_out_ecount(size) __post __deref __elem_readableTo(length)
697 #endif
698 #ifndef __deref_out_bcount_part
699 #define __deref_out_bcount_part(size,length)                    __deref_out_bcount(size) __post __deref __byte_readableTo(length)
700 #endif
701 #ifndef __deref_out_ecount_full
702 #define __deref_out_ecount_full(size)                           __deref_out_ecount_part(size,size)
703 #endif
704 #ifndef __deref_out_bcount_full
705 #define __deref_out_bcount_full(size)                           __deref_out_bcount_part(size,size)
706 #endif
707 #ifndef __deref_inout
708 #define __deref_inout                                           __notnull __elem_readableTo(1) __pre __deref __valid __post __deref __valid __refparam
709 #endif
710 #ifndef __deref_inout_ecount
711 #define __deref_inout_ecount(size)                              __deref_inout __pre __deref __elem_writableTo(size) __post __deref __elem_writableTo(size)
712 #endif
713 #ifndef __deref_inout_bcount
714 #define __deref_inout_bcount(size)                              __deref_inout __pre __deref __byte_writableTo(size) __post __deref __byte_writableTo(size)
715 #endif
716 #ifndef __deref_inout_ecount_part
717 #define __deref_inout_ecount_part(size,length)                  __deref_inout_ecount(size) __pre __deref __elem_readableTo(length) __post __deref __elem_readableTo(length)
718 #endif
719 #ifndef __deref_inout_bcount_part
720 #define __deref_inout_bcount_part(size,length)                  __deref_inout_bcount(size) __pre __deref __byte_readableTo(length) __post __deref __byte_readableTo(length)
721 #endif
722 #ifndef __deref_inout_ecount_full
723 #define __deref_inout_ecount_full(size)                         __deref_inout_ecount_part(size,size)
724 #endif
725 #ifndef __deref_inout_bcount_full
726 #define __deref_inout_bcount_full(size)                         __deref_inout_bcount_part(size,size)
727 #endif
728
729 #ifndef __deref_ecount_opt
730 #define __deref_ecount_opt(size)                                __deref_ecount(size)                        __post __deref __exceptthat __maybenull
731 #endif
732 #ifndef __deref_bcount_opt
733 #define __deref_bcount_opt(size)                                __deref_bcount(size)                        __post __deref __exceptthat __maybenull
734 #endif
735 #ifndef __deref_in_opt
736 #define __deref_in_opt                                          __deref_in                                  __pre __deref __exceptthat __maybenull
737 #endif
738 #ifndef __deref_in_ecount_opt
739 #define __deref_in_ecount_opt(size)                             __deref_in_ecount(size)                     __pre __deref __exceptthat __maybenull
740 #endif
741 #ifndef __deref_in_bcount_opt
742 #define __deref_in_bcount_opt(size)                             __deref_in_bcount(size)                     __pre __deref __exceptthat __maybenull
743 #endif
744 #ifndef __deref_out_opt
745 #define __deref_out_opt                                         __deref_out                                 __post __deref __exceptthat __maybenull
746 #endif
747 #ifndef __deref_out_ecount_opt
748 #define __deref_out_ecount_opt(size)                            __deref_out_ecount(size)                    __post __deref __exceptthat __maybenull
749 #endif
750 #ifndef __deref_out_bcount_opt
751 #define __deref_out_bcount_opt(size)                            __deref_out_bcount(size)                    __post __deref __exceptthat __maybenull
752 #endif
753 #ifndef __deref_out_ecount_part_opt
754 #define __deref_out_ecount_part_opt(size,length)                __deref_out_ecount_part(size,length)        __post __deref __exceptthat __maybenull
755 #endif
756 #ifndef __deref_out_bcount_part_opt
757 #define __deref_out_bcount_part_opt(size,length)                __deref_out_bcount_part(size,length)        __post __deref __exceptthat __maybenull
758 #endif
759 #ifndef __deref_out_ecount_full_opt
760 #define __deref_out_ecount_full_opt(size)                       __deref_out_ecount_full(size)               __post __deref __exceptthat __maybenull
761 #endif
762 #ifndef __deref_out_bcount_full_opt
763 #define __deref_out_bcount_full_opt(size)                       __deref_out_bcount_full(size)               __post __deref __exceptthat __maybenull
764 #endif
765 #ifndef __deref_inout_opt
766 #define __deref_inout_opt                                       __deref_inout                               __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
767 #endif
768 #ifndef __deref_inout_ecount_opt
769 #define __deref_inout_ecount_opt(size)                          __deref_inout_ecount(size)                  __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
770 #endif
771 #ifndef __deref_inout_bcount_opt
772 #define __deref_inout_bcount_opt(size)                          __deref_inout_bcount(size)                  __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
773 #endif
774 #ifndef __deref_inout_ecount_part_opt
775 #define __deref_inout_ecount_part_opt(size,length)              __deref_inout_ecount_part(size,length)      __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
776 #endif
777 #ifndef __deref_inout_bcount_part_opt
778 #define __deref_inout_bcount_part_opt(size,length)              __deref_inout_bcount_part(size,length)      __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
779 #endif
780 #ifndef __deref_inout_ecount_full_opt
781 #define __deref_inout_ecount_full_opt(size)                     __deref_inout_ecount_full(size)             __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
782 #endif
783 #ifndef __deref_inout_bcount_full_opt
784 #define __deref_inout_bcount_full_opt(size)                     __deref_inout_bcount_full(size)             __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
785 #endif
786
787 #ifndef __deref_opt_ecount
788 #define __deref_opt_ecount(size)                                __deref_ecount(size)                        __exceptthat __maybenull
789 #endif
790 #ifndef __deref_opt_bcount
791 #define __deref_opt_bcount(size)                                __deref_bcount(size)                        __exceptthat __maybenull
792 #endif
793 #ifndef __deref_opt_in
794 #define __deref_opt_in                                          __deref_in                                  __exceptthat __maybenull
795 #endif
796 #ifndef __deref_opt_in_ecount
797 #define __deref_opt_in_ecount(size)                             __deref_in_ecount(size)                     __exceptthat __maybenull
798 #endif
799 #ifndef __deref_opt_in_bcount
800 #define __deref_opt_in_bcount(size)                             __deref_in_bcount(size)                     __exceptthat __maybenull
801 #endif
802 #ifndef __deref_opt_out
803 #define __deref_opt_out                                         __deref_out                                 __exceptthat __maybenull
804 #endif
805 #ifndef __deref_opt_out_ecount
806 #define __deref_opt_out_ecount(size)                            __deref_out_ecount(size)                    __exceptthat __maybenull
807 #endif
808 #ifndef __deref_opt_out_bcount
809 #define __deref_opt_out_bcount(size)                            __deref_out_bcount(size)                    __exceptthat __maybenull
810 #endif
811 #ifndef __deref_opt_out_ecount_part
812 #define __deref_opt_out_ecount_part(size,length)                __deref_out_ecount_part(size,length)        __exceptthat __maybenull
813 #endif
814 #ifndef __deref_opt_out_bcount_part
815 #define __deref_opt_out_bcount_part(size,length)                __deref_out_bcount_part(size,length)        __exceptthat __maybenull
816 #endif
817 #ifndef __deref_opt_out_ecount_full
818 #define __deref_opt_out_ecount_full(size)                       __deref_out_ecount_full(size)               __exceptthat __maybenull
819 #endif
820 #ifndef __deref_opt_out_bcount_full
821 #define __deref_opt_out_bcount_full(size)                       __deref_out_bcount_full(size)               __exceptthat __maybenull
822 #endif
823 #ifndef __deref_opt_inout
824 #define __deref_opt_inout                                       __deref_inout                               __exceptthat __maybenull
825 #endif
826 #ifndef __deref_opt_inout_ecount
827 #define __deref_opt_inout_ecount(size)                          __deref_inout_ecount(size)                  __exceptthat __maybenull
828 #endif
829 #ifndef __deref_opt_inout_bcount
830 #define __deref_opt_inout_bcount(size)                          __deref_inout_bcount(size)                  __exceptthat __maybenull
831 #endif
832 #ifndef __deref_opt_inout_ecount_part
833 #define __deref_opt_inout_ecount_part(size,length)              __deref_inout_ecount_part(size,length)      __exceptthat __maybenull
834 #endif
835 #ifndef __deref_opt_inout_bcount_part
836 #define __deref_opt_inout_bcount_part(size,length)              __deref_inout_bcount_part(size,length)      __exceptthat __maybenull
837 #endif
838 #ifndef __deref_opt_inout_ecount_full
839 #define __deref_opt_inout_ecount_full(size)                     __deref_inout_ecount_full(size)             __exceptthat __maybenull
840 #endif
841 #ifndef __deref_opt_inout_bcount_full
842 #define __deref_opt_inout_bcount_full(size)                     __deref_inout_bcount_full(size)             __exceptthat __maybenull
843 #endif
844
845 #ifndef __deref_opt_ecount_opt
846 #define __deref_opt_ecount_opt(size)                            __deref_ecount_opt(size)                    __exceptthat __maybenull
847 #endif
848 #ifndef __deref_opt_bcount_opt
849 #define __deref_opt_bcount_opt(size)                            __deref_bcount_opt(size)                    __exceptthat __maybenull
850 #endif
851 #ifndef __deref_opt_in_opt
852 #define __deref_opt_in_opt                                      __deref_in_opt                              __exceptthat __maybenull
853 #endif
854 #ifndef __deref_opt_in_ecount_opt
855 #define __deref_opt_in_ecount_opt(size)                         __deref_in_ecount_opt(size)                 __exceptthat __maybenull
856 #endif
857 #ifndef __deref_opt_in_bcount_opt
858 #define __deref_opt_in_bcount_opt(size)                         __deref_in_bcount_opt(size)                 __exceptthat __maybenull
859 #endif
860 #ifndef __deref_opt_out_opt
861 #define __deref_opt_out_opt                                     __deref_out_opt                             __exceptthat __maybenull
862 #endif
863 #ifndef __deref_opt_out_ecount_opt
864 #define __deref_opt_out_ecount_opt(size)                        __deref_out_ecount_opt(size)                __exceptthat __maybenull
865 #endif
866 #ifndef __deref_opt_out_bcount_opt
867 #define __deref_opt_out_bcount_opt(size)                        __deref_out_bcount_opt(size)                __exceptthat __maybenull
868 #endif
869 #ifndef __deref_opt_out_ecount_part_opt
870 #define __deref_opt_out_ecount_part_opt(size,length)            __deref_out_ecount_part_opt(size,length)    __exceptthat __maybenull
871 #endif
872 #ifndef __deref_opt_out_bcount_part_opt
873 #define __deref_opt_out_bcount_part_opt(size,length)            __deref_out_bcount_part_opt(size,length)    __exceptthat __maybenull
874 #endif
875 #ifndef __deref_opt_out_ecount_full_opt
876 #define __deref_opt_out_ecount_full_opt(size)                   __deref_out_ecount_full_opt(size)           __exceptthat __maybenull
877 #endif
878 #ifndef __deref_opt_out_bcount_full_opt
879 #define __deref_opt_out_bcount_full_opt(size)                   __deref_out_bcount_full_opt(size)           __exceptthat __maybenull
880 #endif
881 #ifndef __deref_opt_inout_opt
882 #define __deref_opt_inout_opt                                   __deref_inout_opt                           __exceptthat __maybenull
883 #endif
884 #ifndef __deref_opt_inout_ecount_opt
885 #define __deref_opt_inout_ecount_opt(size)                      __deref_inout_ecount_opt(size)              __exceptthat __maybenull
886 #endif
887 #ifndef __deref_opt_inout_bcount_opt
888 #define __deref_opt_inout_bcount_opt(size)                      __deref_inout_bcount_opt(size)              __exceptthat __maybenull
889 #endif
890 #ifndef __deref_opt_inout_ecount_part_opt
891 #define __deref_opt_inout_ecount_part_opt(size,length)          __deref_inout_ecount_part_opt(size,length)  __exceptthat __maybenull
892 #endif
893 #ifndef __deref_opt_inout_bcount_part_opt
894 #define __deref_opt_inout_bcount_part_opt(size,length)          __deref_inout_bcount_part_opt(size,length)  __exceptthat __maybenull
895 #endif
896 #ifndef __deref_opt_inout_ecount_full_opt
897 #define __deref_opt_inout_ecount_full_opt(size)                 __deref_inout_ecount_full_opt(size)         __exceptthat __maybenull
898 #endif
899 #ifndef __deref_opt_inout_bcount_full_opt
900 #define __deref_opt_inout_bcount_full_opt(size)                 __deref_inout_bcount_full_opt(size)         __exceptthat __maybenull
901 #endif
902
903 // @@BEGIN_DDKSPLIT
904 // -------------------------------------------------------------------------------
905 // Advanced Annotation Definitions
906 //
907 // Any of these may be used to directly annotate functions, and may be used in
908 // combination with each other or with regular buffer macros. For an explanation
909 // of each annotation, see the advanced annotations section.
910 // -------------------------------------------------------------------------------
911 // @@END_DDKSPLIT
912
913 #ifndef __out_awcount
914 #define __out_awcount(expr,size)            __pre __notnull \
915                                             __precond(expr) __byte_writableTo(size) \
916                                             __precond(!(expr)) __byte_writableTo((size)*2) \
917                                             __post __valid __refparam
918 #endif
919 #ifndef __in_awcount
920 #define __in_awcount(expr,size)             __pre __valid \
921                                             __pre __deref __readonly \
922                                             __precond(expr) __byte_readableTo(size) \
923                                             __precond(!(expr)) __elem_readableTo(size)
924 #endif
925 #ifndef __success
926 #define __success(expr)                     __inner_success(expr)
927 #endif
928 #ifndef __nullterminated
929 #define __nullterminated                    __readableTo(sentinel(0))
930 #endif
931 #ifndef __nullnullterminated
932 #define __nullnullterminated
933 #endif
934 #ifndef __reserved
935 #define __reserved                          __pre __null
936 #endif
937 #ifndef __checkReturn
938 #define __checkReturn                       __inner_checkReturn
939 #endif
940 #ifndef __typefix
941 #define __typefix(ctype)                    __inner_typefix(ctype)
942 #endif
943 #ifndef __override
944 #define __override                          __inner_override
945 #endif
946 #ifndef __callback
947 #define __callback                          __inner_callback
948 #endif
949 #ifndef __format_string
950 #define __format_string
951 #endif
952 #ifndef __blocksOn
953 #define __blocksOn(resource)                __inner_blocksOn(resource)
954 #endif
955 #ifndef __control_entrypoint
956 #define __control_entrypoint(category)      __inner_control_entrypoint(category)
957 #endif
958 #ifndef __data_entrypoint
959 #define __data_entrypoint(category)         __inner_data_entrypoint(category)
960 #endif
961
962 #ifndef __fallthrough
963     __inner_fallthrough_dec
964     #define __fallthrough __inner_fallthrough
965 #endif
966
967 // -------------------------------------------------------------------------------
968 // Deprecated Annotation Definitions
969 //
970 // These should be removed from existing code.
971 // -------------------------------------------------------------------------------
972
973 // #define __opt                               __exceptthat __maybenull
974
975 #ifdef  __cplusplus
976 }
977 #endif
978