ocrm.bsky.social
the game where you go into mines and start crafting! but for consoles (forked directly from smartcmd's github)
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#pragma once
16/*==========================================================================
17
18 The macros are defined in 3 layers:
19
20 _In_\_Out_ Layer:
21 ----------------
22 This layer provides the highest abstraction and its macros should be used
23 in most cases. Its macros start with _In_, _Out_ or _Inout_. For the
24 typical case they provide the most concise annotations.
25
26 _Pre_\_Post_ Layer:
27 ------------------
28 The macros of this layer only should be used when there is no suitable macro
29 in the _In_\_Out_ layer. Its macros start with _Pre_, _Post_, _Ret_,
30 _Deref_pre_ _Deref_post_ and _Deref_ret_. This layer provides the most
31 flexibility for annotations.
32
33 Implementation Abstraction Layer:
34 --------------------------------
35 Macros from this layer should never be used directly. The layer only exists
36 to hide the implementation of the annotation macros.
37
38
39 Annotation Syntax:
40 |--------------|----------|----------------|-----------------------------|
41 | Usage | Nullness | ZeroTerminated | Extent |
42 |--------------|----------|----------------|-----------------------------|
43 | _In_ | <> | <> | <> |
44 | _Out_ | opt_ | z_ | [byte]cap_[c_|x_]( size ) |
45 | _Inout_ | | | [byte]count_[c_|x_]( size ) |
46 | _Deref_out_ | | | ptrdiff_cap_( ptr ) |
47 |--------------| | | ptrdiff_count_( ptr ) |
48 | _Ret_ | | | |
49 | _Deref_ret_ | | | |
50 |--------------| | | |
51 | _Pre_ | | | |
52 | _Post_ | | | |
53 | _Deref_pre_ | | | |
54 | _Deref_post_ | | | |
55 |--------------|----------|----------------|-----------------------------|
56
57 Usage:
58 -----
59 _In_, _Out_, _Inout_, _Pre_, _Post_, _Deref_pre_, _Deref_post_ are for
60 formal parameters.
61 _Ret_, _Deref_ret_ must be used for return values.
62
63 Nullness:
64 --------
65 If the pointer can be NULL the annotation contains _opt. If the macro
66 does not contain '_opt' the pointer may not be NULL.
67
68 String Type:
69 -----------
70 _z: NullTerminated string
71 for _In_ parameters the buffer must have the specified stringtype before the call
72 for _Out_ parameters the buffer must have the specified stringtype after the call
73 for _Inout_ parameters both conditions apply
74
75 Extent Syntax:
76 |------|---------------|---------------|
77 | Unit | Writ\Readable | Argument Type |
78 |------|---------------|---------------|
79 | <> | cap_ | <> |
80 | byte | count_ | c_ |
81 | | | x_ |
82 |------|---------------|---------------|
83
84 'cap' (capacity) describes the writable size of the buffer and is typically used
85 with _Out_. The default unit is elements. Use 'bytecap' if the size is given in bytes
86 'count' describes the readable size of the buffer and is typically used with _In_.
87 The default unit is elements. Use 'bytecount' if the size is given in bytes.
88
89 Argument syntax for cap_, bytecap_, count_, bytecount_:
90 (<parameter>|return)[+n] e.g. cch, return, cb+2
91
92 If the buffer size is a constant expression use the c_ postfix.
93 E.g. cap_c_(20), count_c_(MAX_PATH), bytecount_c_(16)
94
95 If the buffer size is given by a limiting pointer use the ptrdiff_ versions
96 of the macros.
97
98 If the buffer size is neither a parameter nor a constant expression use the x_
99 postfix. e.g. bytecount_x_(num*size) x_ annotations accept any arbitrary string.
100 No analysis can be done for x_ annotations but they at least tell the tool that
101 the buffer has some sort of extent description. x_ annotations might be supported
102 by future compiler versions.
103
104============================================================================*/
105
106#define __ATTR_SAL
107
108#ifdef _PREFAST_
109// choose attribute or __declspec implementation
110#ifndef _USE_DECLSPECS_FOR_SAL
111#define _USE_DECLSPECS_FOR_SAL 0
112#endif
113
114#if _USE_DECLSPECS_FOR_SAL
115#undef _USE_ATTRIBUTES_FOR_SAL
116#define _USE_ATTRIBUTES_FOR_SAL 0
117#elif !defined(_USE_ATTRIBUTES_FOR_SAL)
118#if _MSC_VER >= 1500
119#define _USE_ATTRIBUTES_FOR_SAL 1
120#else
121#define _USE_ATTRIBUTES_FOR_SAL 0
122#endif // if _MSC_VER >= 1400
123#endif // if _USE_DECLSPECS_FOR_SAL
124
125
126#if !_USE_DECLSPECS_FOR_SAL
127#if !_USE_ATTRIBUTES_FOR_SAL
128#if _MSC_VER >= 1500
129#undef _USE_ATTRIBUTES_FOR_SAL
130#define _USE_ATTRIBUTES_FOR_SAL 1
131#else
132#undef _USE_DECLSPECS_FOR_SAL
133#define _USE_DECLSPECS_FOR_SAL 1
134#endif // _MSC_VER >= 1400
135#endif // !_USE_ATTRIBUTES_FOR_SAL
136#endif // !_USE_DECLSPECS_FOR_SAL
137
138#endif // #ifdef _PREFAST_
139
140// Disable expansion of SAL macros in non-Prefast mode to
141// improve compiler throughput.
142#ifndef _USE_DECLSPECS_FOR_SAL
143#define _USE_DECLSPECS_FOR_SAL 0
144#endif
145#ifndef _USE_ATTRIBUTES_FOR_SAL
146#define _USE_ATTRIBUTES_FOR_SAL 0
147#endif
148
149// safeguard for MIDL and RC builds
150#if _USE_DECLSPECS_FOR_SAL && ( defined( MIDL_PASS ) || defined(__midl) || defined(RC_INVOKED) || !defined(_PREFAST_) )
151#undef _USE_DECLSPECS_FOR_SAL
152#define _USE_DECLSPECS_FOR_SAL 0
153#endif
154#if _USE_ATTRIBUTES_FOR_SAL && ( !defined(_MSC_EXTENSIONS) || defined( MIDL_PASS ) || defined(__midl) || defined(RC_INVOKED) )
155#undef _USE_ATTRIBUTES_FOR_SAL
156#define _USE_ATTRIBUTES_FOR_SAL 0
157#endif
158
159#if defined(_MSC_EXTENSIONS) && !defined( MIDL_PASS ) && !defined(__midl) && !defined(RC_INVOKED)
160#include "codeanalysis\sourceannotations.h"
161#endif
162
163//============================================================================
164// _In_\_Out_ Layer:
165//============================================================================
166
167// 'in' parameters --------------------------
168
169// input pointer parameter
170// e.g. void SetPoint( _In_ const POINT* pPT );
171#define _In_ _Pre1_impl_(_$notnull) _Deref_pre2_impl_(_$valid, _$readaccess)
172#define _In_opt_ _Pre_opt_valid_ _Deref_pre_readonly_
173
174// nullterminated 'in' parameters.
175// e.g. void CopyStr( _In_z_ const char* szFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo );
176#define _In_z_ _Pre_z_ _Deref_pre_readonly_
177#define _In_opt_z_ _Pre_opt_z_ _Deref_pre_readonly_
178
179// 'input' buffers with given size
180
181// e.g. void SetCharRange( _In_count_(cch) const char* rgch, size_t cch )
182// valid buffer extent described by another parameter
183#define _In_count_(size) _Pre_count_(size) _Deref_pre_readonly_
184#define _In_opt_count_(size) _Pre_opt_count_(size) _Deref_pre_readonly_
185#define _In_bytecount_(size) _Pre_bytecount_(size) _Deref_pre_readonly_
186#define _In_opt_bytecount_(size) _Pre_opt_bytecount_(size) _Deref_pre_readonly_
187
188// valid buffer extent described by a constant extression
189#define _In_count_c_(size) _Pre_count_c_(size) _Deref_pre_readonly_
190#define _In_opt_count_c_(size) _Pre_opt_count_c_(size) _Deref_pre_readonly_
191#define _In_bytecount_c_(size) _Pre_bytecount_c_(size) _Deref_pre_readonly_
192#define _In_opt_bytecount_c_(size) _Pre_opt_bytecount_c_(size) _Deref_pre_readonly_
193
194// nullterminated 'input' buffers with given size
195
196// e.g. void SetCharRange( _In_count_(cch) const char* rgch, size_t cch )
197// nullterminated valid buffer extent described by another parameter
198#define _In_z_count_(size) _Pre_z_ _Pre_count_(size) _Deref_pre_readonly_
199#define _In_opt_z_count_(size) _Pre_opt_z_ _Pre_opt_count_(size) _Deref_pre_readonly_
200#define _In_z_bytecount_(size) _Pre_z_ _Pre_bytecount_(size) _Deref_pre_readonly_
201#define _In_opt_z_bytecount_(size) _Pre_opt_z_ _Pre_opt_bytecount_(size) _Deref_pre_readonly_
202
203// nullterminated valid buffer extent described by a constant extression
204#define _In_z_count_c_(size) _Pre_z_ _Pre_count_c_(size) _Deref_pre_readonly_
205#define _In_opt_z_count_c_(size) _Pre_opt_z_ _Pre_opt_count_c_(size) _Deref_pre_readonly_
206#define _In_z_bytecount_c_(size) _Pre_z_ _Pre_bytecount_c_(size) _Deref_pre_readonly_
207#define _In_opt_z_bytecount_c_(size) _Pre_opt_z_ _Pre_opt_bytecount_c_(size) _Deref_pre_readonly_
208
209// buffer capacity is described by another pointer
210// e.g. void Foo( _In_ptrdiff_count_(pchMax) const char* pch, const char* pchMax ) { while pch < pchMax ) pch++; }
211#define _In_ptrdiff_count_(size) _Pre_ptrdiff_count_(size) _Deref_pre_readonly_
212#define _In_opt_ptrdiff_count_(size) _Pre_opt_ptrdiff_count_(size) _Deref_pre_readonly_
213
214// 'x' version for complex expressions that are not supported by the current compiler version
215// e.g. void Set3ColMatrix( _In_count_x_(3*cRows) const Elem* matrix, int cRows );
216#define _In_count_x_(size) _Pre_count_x_(size) _Deref_pre_readonly_
217#define _In_opt_count_x_(size) _Pre_opt_count_x_(size) _Deref_pre_readonly_
218#define _In_bytecount_x_(size) _Pre_bytecount_x_(size) _Deref_pre_readonly_
219#define _In_opt_bytecount_x_(size) _Pre_opt_bytecount_x_(size) _Deref_pre_readonly_
220
221// 'out' parameters --------------------------
222
223// output pointer parameter
224// e.g. void GetPoint( _Out_ POINT* pPT );
225#define _Out_ _Pre_cap_c_(1) _Pre_invalid_
226#define _Out_opt_ _Pre_opt_cap_c_(1) _Pre_invalid_
227
228// 'out' with buffer size
229// e.g. void GetIndeces( _Out_cap_(cIndeces) int* rgIndeces, size_t cIndices );
230// buffer capacity is described by another parameter
231#define _Out_cap_(size) _Pre_cap_(size) _Pre_invalid_
232#define _Out_opt_cap_(size) _Pre_opt_cap_(size) _Pre_invalid_
233#define _Out_bytecap_(size) _Pre_bytecap_(size) _Pre_invalid_
234#define _Out_opt_bytecap_(size) _Pre_opt_bytecap_(size) _Pre_invalid_
235
236// buffer capacity is described by a constant expression
237#define _Out_cap_c_(size) _Pre_cap_c_(size) _Pre_invalid_
238#define _Out_opt_cap_c_(size) _Pre_opt_cap_c_(size) _Pre_invalid_
239#define _Out_bytecap_c_(size) _Pre_bytecap_c_(size) _Pre_invalid_
240#define _Out_opt_bytecap_c_(size) _Pre_opt_bytecap_c_(size) _Pre_invalid_
241
242// buffer capacity is described by another parameter multiplied by a constant expression
243#define _Out_cap_m_(mult,size) _Pre_cap_m_(mult,size) _Pre_invalid_
244#define _Out_opt_cap_m_(mult,size) _Pre_opt_cap_m_(mult,size) _Pre_invalid_
245#define _Out_z_cap_m_(mult,size) _Pre_cap_m_(mult,size) _Pre_invalid_ _Post_z_
246#define _Out_opt_z_cap_m_(mult,size) _Pre_opt_cap_m_(mult,size) _Pre_invalid_ _Post_z_
247
248// buffer capacity is described by another pointer
249// e.g. void Foo( _Out_ptrdiff_cap_(pchMax) char* pch, const char* pchMax ) { while pch < pchMax ) pch++; }
250#define _Out_ptrdiff_cap_(size) _Pre_ptrdiff_cap_(size) _Pre_invalid_
251#define _Out_opt_ptrdiff_cap_(size) _Pre_opt_ptrdiff_cap_(size) _Pre_invalid_
252
253// buffer capacity is described by a complex expression
254#define _Out_cap_x_(size) _Pre_cap_x_(size) _Pre_invalid_
255#define _Out_opt_cap_x_(size) _Pre_opt_cap_x_(size) _Pre_invalid_
256#define _Out_bytecap_x_(size) _Pre_bytecap_x_(size) _Pre_invalid_
257#define _Out_opt_bytecap_x_(size) _Pre_opt_bytecap_x_(size) _Pre_invalid_
258
259// a zero terminated string is filled into a buffer of given capacity
260// e.g. void CopyStr( _In_z_ const char* szFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo );
261// buffer capacity is described by another parameter
262#define _Out_z_cap_(size) _Pre_cap_(size) _Pre_invalid_ _Post_z_
263#define _Out_opt_z_cap_(size) _Pre_opt_cap_(size) _Pre_invalid_ _Post_z_
264#define _Out_z_bytecap_(size) _Pre_bytecap_(size) _Pre_invalid_ _Post_z_
265#define _Out_opt_z_bytecap_(size) _Pre_opt_bytecap_(size) _Pre_invalid_ _Post_z_
266
267// buffer capacity is described by a constant expression
268#define _Out_z_cap_c_(size) _Pre_cap_c_(size) _Pre_invalid_ _Post_z_
269#define _Out_opt_z_cap_c_(size) _Pre_opt_cap_c_(size) _Pre_invalid_ _Post_z_
270#define _Out_z_bytecap_c_(size) _Pre_bytecap_c_(size) _Pre_invalid_ _Post_z_
271#define _Out_opt_z_bytecap_c_(size) _Pre_opt_bytecap_c_(size) _Pre_invalid_ _Post_z_
272
273// buffer capacity is described by a complex expression
274#define _Out_z_cap_x_(size) _Pre_cap_x_(size) _Pre_invalid_ _Post_z_
275#define _Out_opt_z_cap_x_(size) _Pre_opt_cap_x_(size) _Pre_invalid_ _Post_z_
276#define _Out_z_bytecap_x_(size) _Pre_bytecap_x_(size) _Pre_invalid_ _Post_z_
277#define _Out_opt_z_bytecap_x_(size) _Pre_opt_bytecap_x_(size) _Pre_invalid_ _Post_z_
278
279// a zero terminated string is filled into a buffer of given capacity
280// e.g. size_t CopyCharRange( _In_count_(cchFrom) const char* rgchFrom, size_t cchFrom, _Out_cap_post_count_(cchTo,return)) char* rgchTo, size_t cchTo );
281#define _Out_cap_post_count_(cap,count) _Pre_cap_(cap) _Pre_invalid_ _Post_count_(count)
282#define _Out_opt_cap_post_count_(cap,count) _Pre_opt_cap_(cap) _Pre_invalid_ _Post_count_(count)
283#define _Out_bytecap_post_bytecount_(cap,count) _Pre_bytecap_(cap) _Pre_invalid_ _Post_bytecount_(count)
284#define _Out_opt_bytecap_post_bytecount_(cap,count) _Pre_opt_bytecap_(cap) _Pre_invalid_ _Post_bytecount_(count)
285
286// a zero terminated string is filled into a buffer of given capacity
287// e.g. size_t CopyStr( _In_z_ const char* szFrom, _Out_z_cap_post_count_(cchTo,return+1) char* szTo, size_t cchTo );
288#define _Out_z_cap_post_count_(cap,count) _Pre_cap_(cap) _Pre_invalid_ _Post_z_count_(count)
289#define _Out_opt_z_cap_post_count_(cap,count) _Pre_opt_cap_(cap) _Pre_invalid_ _Post_z_count_(count)
290#define _Out_z_bytecap_post_bytecount_(cap,count) _Pre_bytecap_(cap) _Pre_invalid_ _Post_z_bytecount_(count)
291#define _Out_opt_z_bytecap_post_bytecount_(cap,count) _Pre_opt_bytecap_(cap) _Pre_invalid_ _Post_z_bytecount_(count)
292
293// only use with dereferenced arguments e.g. '*pcch'
294#define _Out_capcount_(capcount) _Pre_cap_(capcount) _Pre_invalid_ _Post_count_(capcount)
295#define _Out_opt_capcount_(capcount) _Pre_opt_cap_(capcount) _Pre_invalid_ _Post_count_(capcount)
296#define _Out_bytecapcount_(capcount) _Pre_bytecap_(capcount) _Pre_invalid_ _Post_bytecount_(capcount)
297#define _Out_opt_bytecapcount_(capcount) _Pre_opt_bytecap_(capcount) _Pre_invalid_ _Post_bytecount_(capcount)
298
299#define _Out_capcount_x_(capcount) _Pre_cap_x_(capcount) _Pre_invalid_ _Post_count_x_(capcount)
300#define _Out_opt_capcount_x_(capcount) _Pre_opt_cap_x_(capcount) _Pre_invalid_ _Post_count_x_(capcount)
301#define _Out_bytecapcount_x_(capcount) _Pre_bytecap_x_(capcount) _Pre_invalid_ _Post_bytecount_x_(capcount)
302#define _Out_opt_bytecapcount_x_(capcount) _Pre_opt_bytecap_x_(capcount) _Pre_invalid_ _Post_bytecount_x_(capcount)
303
304// e.g. GetString( _Out_z_capcount_(*pLen+1) char* sz, size_t* pLen );
305#define _Out_z_capcount_(capcount) _Pre_cap_(capcount) _Pre_invalid_ _Post_z_count_(capcount)
306#define _Out_opt_z_capcount_(capcount) _Pre_opt_cap_(capcount) _Pre_invalid_ _Post_z_count_(capcount)
307#define _Out_z_bytecapcount_(capcount) _Pre_bytecap_(capcount) _Pre_invalid_ _Post_z_bytecount_(capcount)
308#define _Out_opt_z_bytecapcount_(capcount) _Pre_opt_bytecap_(capcount) _Pre_invalid_ _Post_z_bytecount_(capcount)
309
310// inout parameters ----------------------------
311
312// inout pointer parameter
313// e.g. void ModifyPoint( _Inout_ POINT* pPT );
314#define _Inout_ _Prepost_valid_
315#define _Inout_opt_ _Prepost_opt_valid_
316
317// string buffers
318// e.g. void toupper( _Inout_z_ char* sz );
319#define _Inout_z_ _Prepost_z_
320#define _Inout_opt_z_ _Prepost_opt_z_
321
322// 'inout' buffers with initialized elements before and after the call
323// e.g. void ModifyIndices( _Inout_count_(cIndices) int* rgIndeces, size_t cIndices );
324#define _Inout_count_(size) _Prepost_count_(size)
325#define _Inout_opt_count_(size) _Prepost_opt_count_(size)
326#define _Inout_bytecount_(size) _Prepost_bytecount_(size)
327#define _Inout_opt_bytecount_(size) _Prepost_opt_bytecount_(size)
328
329#define _Inout_count_c_(size) _Prepost_count_c_(size)
330#define _Inout_opt_count_c_(size) _Prepost_opt_count_c_(size)
331#define _Inout_bytecount_c_(size) _Prepost_bytecount_c_(size)
332#define _Inout_opt_bytecount_c_(size) _Prepost_opt_bytecount_c_(size)
333
334// nullterminated 'inout' buffers with initialized elements before and after the call
335// e.g. void ModifyIndices( _Inout_count_(cIndices) int* rgIndeces, size_t cIndices );
336#define _Inout_z_count_(size) _Prepost_z_ _Prepost_count_(size)
337#define _Inout_opt_z_count_(size) _Prepost_z_ _Prepost_opt_count_(size)
338#define _Inout_z_bytecount_(size) _Prepost_z_ _Prepost_bytecount_(size)
339#define _Inout_opt_z_bytecount_(size) _Prepost_z_ _Prepost_opt_bytecount_(size)
340
341#define _Inout_z_count_c_(size) _Prepost_z_ _Prepost_count_c_(size)
342#define _Inout_opt_z_count_c_(size) _Prepost_z_ _Prepost_opt_count_c_(size)
343#define _Inout_z_bytecount_c_(size) _Prepost_z_ _Prepost_bytecount_c_(size)
344#define _Inout_opt_z_bytecount_c_(size) _Prepost_z_ _Prepost_opt_bytecount_c_(size)
345
346#define _Inout_ptrdiff_count_(size) _Pre_ptrdiff_count_(size)
347#define _Inout_opt_ptrdiff_count_(size) _Pre_opt_ptrdiff_count_(size)
348
349#define _Inout_count_x_(size) _Prepost_count_x_(size)
350#define _Inout_opt_count_x_(size) _Prepost_opt_count_x_(size)
351#define _Inout_bytecount_x_(size) _Prepost_bytecount_x_(size)
352#define _Inout_opt_bytecount_x_(size) _Prepost_opt_bytecount_x_(size)
353
354// e.g. void AppendToLPSTR( _In_ LPCSTR szFrom, _Inout_cap_(cchTo) LPSTR* szTo, size_t cchTo );
355#define _Inout_cap_(size) _Pre_valid_cap_(size) _Post_valid_
356#define _Inout_opt_cap_(size) _Pre_opt_valid_cap_(size) _Post_valid_
357#define _Inout_bytecap_(size) _Pre_valid_bytecap_(size) _Post_valid_
358#define _Inout_opt_bytecap_(size) _Pre_opt_valid_bytecap_(size) _Post_valid_
359
360#define _Inout_cap_c_(size) _Pre_valid_cap_c_(size) _Post_valid_
361#define _Inout_opt_cap_c_(size) _Pre_opt_valid_cap_c_(size) _Post_valid_
362#define _Inout_bytecap_c_(size) _Pre_valid_bytecap_c_(size) _Post_valid_
363#define _Inout_opt_bytecap_c_(size) _Pre_opt_valid_bytecap_c_(size) _Post_valid_
364
365#define _Inout_cap_x_(size) _Pre_valid_cap_x_(size) _Post_valid_
366#define _Inout_opt_cap_x_(size) _Pre_opt_valid_cap_x_(size) _Post_valid_
367#define _Inout_bytecap_x_(size) _Pre_valid_bytecap_x_(size) _Post_valid_
368#define _Inout_opt_bytecap_x_(size) _Pre_opt_valid_bytecap_x_(size) _Post_valid_
369
370// inout string buffers with writable size
371// e.g. void AppendStr( _In_z_ const char* szFrom, _Inout_z_cap_(cchTo) char* szTo, size_t cchTo );
372#define _Inout_z_cap_(size) _Pre_z_cap_(size) _Post_z_
373#define _Inout_opt_z_cap_(size) _Pre_opt_z_cap_(size) _Post_z_
374#define _Inout_z_bytecap_(size) _Pre_z_bytecap_(size) _Post_z_
375#define _Inout_opt_z_bytecap_(size) _Pre_opt_z_bytecap_(size) _Post_z_
376
377#define _Inout_z_cap_c_(size) _Pre_z_cap_c_(size) _Post_z_
378#define _Inout_opt_z_cap_c_(size) _Pre_opt_z_cap_c_(size) _Post_z_
379#define _Inout_z_bytecap_c_(size) _Pre_z_bytecap_c_(size) _Post_z_
380#define _Inout_opt_z_bytecap_c_(size) _Pre_opt_z_bytecap_c_(size) _Post_z_
381
382#define _Inout_z_cap_x_(size) _Pre_z_cap_x_(size) _Post_z_
383#define _Inout_opt_z_cap_x_(size) _Pre_opt_z_cap_x_(size) _Post_z_
384#define _Inout_z_bytecap_x_(size) _Pre_z_bytecap_x_(size) _Post_z_
385#define _Inout_opt_z_bytecap_x_(size) _Pre_opt_z_bytecap_x_(size) _Post_z_
386
387// return values -------------------------------
388
389// returning pointers to valid objects
390#define _Ret_ _Ret_valid_
391#define _Ret_opt_ _Ret_opt_valid_
392
393// More _Ret_ annotations are defined below
394
395// Pointer to pointers -------------------------
396
397// e.g. HRESULT HrCreatePoint( _Deref_out_opt_ POINT** ppPT );
398#define _Deref_out_ _Out_ _Deref_pre_invalid_ _Deref_post_valid_
399#define _Deref_out_opt_ _Out_ _Deref_pre_invalid_ _Deref_post_opt_valid_
400#define _Deref_opt_out_ _Out_opt_ _Deref_pre_invalid_ _Deref_post_valid_
401#define _Deref_opt_out_opt_ _Out_opt_ _Deref_pre_invalid_ _Deref_post_opt_valid_
402
403// e.g. void CloneString( _In_z_ const wchar_t* wzFrom, _Deref_out_z_ wchar_t** pWzTo );
404#define _Deref_out_z_ _Out_ _Deref_pre_invalid_ _Deref_post_z_
405#define _Deref_out_opt_z_ _Out_ _Deref_pre_invalid_ _Deref_post_opt_z_
406#define _Deref_opt_out_z_ _Out_opt_ _Deref_pre_invalid_ _Deref_post_z_
407#define _Deref_opt_out_opt_z_ _Out_opt_ _Deref_pre_invalid_ _Deref_post_opt_z_
408
409// More _Deref_ annotations are defined below
410
411// Other annotations
412
413// Check the return value of a function e.g. _Check_return_ ErrorCode Foo();
414#define _Check_return_ _Check_return_impl_
415
416// e.g. MyPrintF( _Printf_format_string_ const wchar_t* wzFormat, ... );
417#define _Printf_format_string_ _Printf_format_string_impl_
418#define _Scanf_format_string_ _Scanf_format_string_impl_
419#define _Scanf_s_format_string_ _Scanf_s_format_string_impl_
420#define _FormatMessage_format_string_
421
422// <expr> indicates whether post conditions apply
423#define _Success_(expr) _Success_impl_(expr)
424
425// annotations to express 'boundedness' of integral value parameter
426#define _In_bound_ _In_bound_impl_
427#define _Out_bound_ _Out_bound_impl_
428#define _Ret_bound_ _Ret_bound_impl_
429#define _Deref_in_bound_ _Deref_in_bound_impl_
430#define _Deref_out_bound_ _Deref_out_bound_impl_
431#define _Deref_inout_bound_ _Deref_in_bound_ _Deref_out_bound_
432#define _Deref_ret_bound_ _Deref_ret_bound_impl_
433
434// annotations to express upper and lower bounds of integral value parameter
435#define _In_range_(lb,ub) _In_range_impl_(lb,ub)
436#define _Out_range_(lb,ub) _Out_range_impl_(lb,ub)
437#define _Ret_range_(lb,ub) _Ret_range_impl_(lb,ub)
438#define _Deref_in_range_(lb,ub) _Deref_in_range_impl_(lb,ub)
439#define _Deref_out_range_(lb,ub) _Deref_out_range_impl_(lb,ub)
440#define _Deref_ret_range_(lb,ub) _Deref_ret_range_impl_(lb,ub)
441
442//============================================================================
443// _Pre_\_Post_ Layer:
444//============================================================================
445
446//
447// _Pre_ annotation ---
448//
449// describing conditions that must be met before the call of the function
450
451// e.g. int strlen( _Pre_z_ const char* sz );
452// buffer is a zero terminated string
453#define _Pre_z_ _Pre2_impl_(_$notnull, _$zterm) _Deref_pre1_impl_(_$valid)
454#define _Pre_opt_z_ _Pre2_impl_(_$maybenull,_$zterm) _Deref_pre1_impl_(_$valid)
455
456// e.g. void FreeMemory( _Pre_bytecap_(cb) _Post_ptr_invalid_ void* pv, size_t cb );
457// buffer capacity described by another parameter
458#define _Pre_cap_(size) _Pre2_impl_(_$notnull, _$cap(size))
459#define _Pre_opt_cap_(size) _Pre2_impl_(_$maybenull,_$cap(size))
460#define _Pre_bytecap_(size) _Pre2_impl_(_$notnull, _$bytecap(size))
461#define _Pre_opt_bytecap_(size) _Pre2_impl_(_$maybenull,_$bytecap(size))
462
463// buffer capacity described by a constant expression
464#define _Pre_cap_c_(size) _Pre2_impl_(_$notnull, _$cap_c(size))
465#define _Pre_opt_cap_c_(size) _Pre2_impl_(_$maybenull,_$cap_c(size))
466#define _Pre_bytecap_c_(size) _Pre2_impl_(_$notnull, _$bytecap_c(size))
467#define _Pre_opt_bytecap_c_(size) _Pre2_impl_(_$maybenull,_$bytecap_c(size))
468
469// buffer capacity is described by another parameter multiplied by a constant expression
470#define _Pre_cap_m_(mult,size) _Pre2_impl_(_$notnull, _$mult(mult,size))
471#define _Pre_opt_cap_m_(mult,size) _Pre2_impl_(_$maybenull,_$mult(mult,size))
472
473// buffer capacity described by size of other buffer, only used by dangerous legacy APIs
474// e.g. int strcpy(_Pre_cap_for_(src) char* dst, const char* src);
475#define _Pre_cap_for_(param) _Pre2_impl_(_$notnull, _$cap_for(param))
476#define _Pre_opt_cap_for_(param) _Pre2_impl_(_$maybenull,_$cap_for(param))
477
478// buffer capacity described by a complex condition
479#define _Pre_cap_x_(size) _Pre2_impl_(_$notnull, _$cap_x(size))
480#define _Pre_opt_cap_x_(size) _Pre2_impl_(_$maybenull,_$cap_x(size))
481#define _Pre_bytecap_x_(size) _Pre2_impl_(_$notnull, _$bytecap_x(size))
482#define _Pre_opt_bytecap_x_(size) _Pre2_impl_(_$maybenull,_$bytecap_x(size))
483
484// buffer capacity described by the difference to another pointer parameter
485#define _Pre_ptrdiff_cap_(ptr) _Pre2_impl_(_$notnull, _$cap_x(__ptrdiff(ptr)))
486#define _Pre_opt_ptrdiff_cap_(ptr) _Pre2_impl_(_$maybenull,_$cap_x(__ptrdiff(ptr)))
487
488// e.g. void AppendStr( _Pre_z_ const char* szFrom, _Pre_z_cap_(cchTo) _Post_z_ char* szTo, size_t cchTo );
489#define _Pre_z_cap_(size) _Pre3_impl_(_$notnull, _$zterm,_$cap(size)) _Deref_pre1_impl_(_$valid)
490#define _Pre_opt_z_cap_(size) _Pre3_impl_(_$maybenull,_$zterm,_$cap(size)) _Deref_pre1_impl_(_$valid)
491#define _Pre_z_bytecap_(size) _Pre3_impl_(_$notnull, _$zterm,_$bytecap(size)) _Deref_pre1_impl_(_$valid)
492#define _Pre_opt_z_bytecap_(size) _Pre3_impl_(_$maybenull,_$zterm,_$bytecap(size)) _Deref_pre1_impl_(_$valid)
493
494#define _Pre_z_cap_c_(size) _Pre3_impl_(_$notnull, _$zterm,_$cap_c(size)) _Deref_pre1_impl_(_$valid)
495#define _Pre_opt_z_cap_c_(size) _Pre3_impl_(_$maybenull,_$zterm,_$cap_c(size)) _Deref_pre1_impl_(_$valid)
496#define _Pre_z_bytecap_c_(size) _Pre3_impl_(_$notnull, _$zterm,_$bytecap_c(size)) _Deref_pre1_impl_(_$valid)
497#define _Pre_opt_z_bytecap_c_(size) _Pre3_impl_(_$maybenull,_$zterm,_$bytecap_c(size)) _Deref_pre1_impl_(_$valid)
498
499#define _Pre_z_cap_x_(size) _Pre3_impl_(_$notnull, _$zterm,_$cap_x(size)) _Deref_pre1_impl_(_$valid)
500#define _Pre_opt_z_cap_x_(size) _Pre3_impl_(_$maybenull,_$zterm,_$cap_x(size)) _Deref_pre1_impl_(_$valid)
501#define _Pre_z_bytecap_x_(size) _Pre3_impl_(_$notnull, _$zterm,_$bytecap_x(size)) _Deref_pre1_impl_(_$valid)
502#define _Pre_opt_z_bytecap_x_(size) _Pre3_impl_(_$maybenull,_$zterm,_$bytecap_x(size)) _Deref_pre1_impl_(_$valid)
503
504// known capacity and valid but unknown readable extent
505#define _Pre_valid_cap_(size) _Pre2_impl_(_$notnull, _$cap(size)) _Deref_pre1_impl_(_$valid)
506#define _Pre_opt_valid_cap_(size) _Pre2_impl_(_$maybenull,_$cap(size)) _Deref_pre1_impl_(_$valid)
507#define _Pre_valid_bytecap_(size) _Pre2_impl_(_$notnull, _$bytecap(size)) _Deref_pre1_impl_(_$valid)
508#define _Pre_opt_valid_bytecap_(size) _Pre2_impl_(_$maybenull,_$bytecap(size)) _Deref_pre1_impl_(_$valid)
509
510#define _Pre_valid_cap_c_(size) _Pre2_impl_(_$notnull, _$cap_c(size)) _Deref_pre1_impl_(_$valid)
511#define _Pre_opt_valid_cap_c_(size) _Pre2_impl_(_$maybenull,_$cap_c(size)) _Deref_pre1_impl_(_$valid)
512#define _Pre_valid_bytecap_c_(size) _Pre2_impl_(_$notnull, _$bytecap_c(size)) _Deref_pre1_impl_(_$valid)
513#define _Pre_opt_valid_bytecap_c_(size) _Pre2_impl_(_$maybenull,_$bytecap_c(size)) _Deref_pre1_impl_(_$valid)
514
515#define _Pre_valid_cap_x_(size) _Pre2_impl_(_$notnull, _$cap_x(size)) _Deref_pre1_impl_(_$valid)
516#define _Pre_opt_valid_cap_x_(size) _Pre2_impl_(_$maybenull,_$cap_x(size)) _Deref_pre1_impl_(_$valid)
517#define _Pre_valid_bytecap_x_(size) _Pre2_impl_(_$notnull, _$bytecap_x(size)) _Deref_pre1_impl_(_$valid)
518#define _Pre_opt_valid_bytecap_x_(size) _Pre2_impl_(_$maybenull,_$bytecap_x(size)) _Deref_pre1_impl_(_$valid)
519
520// e.g. void AppendCharRange( _Pre_count_(cchFrom) const char* rgFrom, size_t cchFrom, _Out_z_cap_(cchTo) char* szTo, size_t cchTo );
521// Valid buffer extent described by another parameter
522#define _Pre_count_(size) _Pre2_impl_(_$notnull, _$count(size)) _Deref_pre1_impl_(_$valid)
523#define _Pre_opt_count_(size) _Pre2_impl_(_$maybenull,_$count(size)) _Deref_pre1_impl_(_$valid)
524#define _Pre_bytecount_(size) _Pre2_impl_(_$notnull, _$bytecount(size)) _Deref_pre1_impl_(_$valid)
525#define _Pre_opt_bytecount_(size) _Pre2_impl_(_$maybenull,_$bytecount(size)) _Deref_pre1_impl_(_$valid)
526
527// Valid buffer extent described by a constant expression
528#define _Pre_count_c_(size) _Pre2_impl_(_$notnull, _$count_c(size)) _Deref_pre1_impl_(_$valid)
529#define _Pre_opt_count_c_(size) _Pre2_impl_(_$maybenull,_$count_c(size)) _Deref_pre1_impl_(_$valid)
530#define _Pre_bytecount_c_(size) _Pre2_impl_(_$notnull, _$bytecount_c(size)) _Deref_pre1_impl_(_$valid)
531#define _Pre_opt_bytecount_c_(size) _Pre2_impl_(_$maybenull,_$bytecount_c(size)) _Deref_pre1_impl_(_$valid)
532
533// Valid buffer extent described by a complex expression
534#define _Pre_count_x_(size) _Pre2_impl_(_$notnull, _$count_x(size)) _Deref_pre1_impl_(_$valid)
535#define _Pre_opt_count_x_(size) _Pre2_impl_(_$maybenull,_$count_x(size)) _Deref_pre1_impl_(_$valid)
536#define _Pre_bytecount_x_(size) _Pre2_impl_(_$notnull, _$bytecount_x(size)) _Deref_pre1_impl_(_$valid)
537#define _Pre_opt_bytecount_x_(size) _Pre2_impl_(_$maybenull,_$bytecount_x(size)) _Deref_pre1_impl_(_$valid)
538
539// Valid buffer extent described by the difference to another pointer parameter
540#define _Pre_ptrdiff_count_(ptr) _Pre2_impl_(_$notnull, _$count_x(__ptrdiff(ptr))) _Deref_pre1_impl_(_$valid)
541#define _Pre_opt_ptrdiff_count_(ptr) _Pre2_impl_(_$maybenull,_$count_x(__ptrdiff(ptr))) _Deref_pre1_impl_(_$valid)
542
543// valid size unknown or indicated by type (e.g.:LPSTR)
544#define _Pre_valid_ _Pre1_impl_(_$notnull) _Deref_pre1_impl_(_$valid)
545#define _Pre_opt_valid_ _Pre1_impl_(_$maybenull) _Deref_pre1_impl_(_$valid)
546
547#define _Pre_invalid_ _Deref_pre1_impl_(_$notvalid)
548
549// used with allocated but not yet initialized objects
550#define _Pre_notnull_ _Pre1_impl_(_$notnull)
551#define _Pre_maybenull_ _Pre1_impl_(_$maybenull)
552#define _Pre_null_ _Pre1_impl_(_$null)
553
554// restrict access rights
555#define _Pre_readonly_ _Pre1_impl_(_$readaccess)
556#define _Pre_writeonly_ _Pre1_impl_(_$writeaccess)
557//
558// _Post_ annotations ---
559//
560// describing conditions that hold after the function call
561
562// void CopyStr( _In_z_ const char* szFrom, _Pre_cap_(cch) _Post_z_ char* szFrom, size_t cchFrom );
563// buffer will be a zero-terminated string after the call
564#define _Post_z_ _Post1_impl_(_$zterm) _Deref_post1_impl_(_$valid)
565
566// char * strncpy(_Out_cap_(_Count) _Post_maybez_ char * _Dest, _In_z_ const char * _Source, _In_ size_t _Count)
567// buffer maybe zero-terminated after the call
568#define _Post_maybez_ _Post1_impl_(_$maybezterm)
569
570// e.g. SIZE_T HeapSize( _In_ HANDLE hHeap, DWORD dwFlags, _Pre_notnull_ _Post_bytecap_(return) LPCVOID lpMem );
571#define _Post_cap_(size) _Post1_impl_(_$cap(size))
572#define _Post_bytecap_(size) _Post1_impl_(_$bytecap(size))
573
574// e.g. int strlen( _In_z_ _Post_count_(return+1) const char* sz );
575#define _Post_count_(size) _Post1_impl_(_$count(size)) _Deref_post1_impl_(_$valid)
576#define _Post_bytecount_(size) _Post1_impl_(_$bytecount(size)) _Deref_post1_impl_(_$valid)
577#define _Post_count_c_(size) _Post1_impl_(_$count_c(size)) _Deref_post1_impl_(_$valid)
578#define _Post_bytecount_c_(size) _Post1_impl_(_$bytecount_c(size)) _Deref_post1_impl_(_$valid)
579#define _Post_count_x_(size) _Post1_impl_(_$count_x(size)) _Deref_post1_impl_(_$valid)
580#define _Post_bytecount_x_(size) _Post1_impl_(_$bytecount_x(size)) _Deref_post1_impl_(_$valid)
581
582// e.g. size_t CopyStr( _In_z_ const char* szFrom, _Pre_cap_(cch) _Post_z_count_(return+1) char* szFrom, size_t cchFrom );
583#define _Post_z_count_(size) _Post2_impl_(_$zterm,_$count(size)) _Deref_post1_impl_(_$valid)
584#define _Post_z_bytecount_(size) _Post2_impl_(_$zterm,_$bytecount(size)) _Deref_post1_impl_(_$valid)
585#define _Post_z_count_c_(size) _Post2_impl_(_$zterm,_$count_c(size)) _Deref_post1_impl_(_$valid)
586#define _Post_z_bytecount_c_(size) _Post2_impl_(_$zterm,_$bytecount_c(size)) _Deref_post1_impl_(_$valid)
587#define _Post_z_count_x_(size) _Post2_impl_(_$zterm,_$count_x(size)) _Deref_post1_impl_(_$valid)
588#define _Post_z_bytecount_x_(size) _Post2_impl_(_$zterm,_$bytecount_x(size)) _Deref_post1_impl_(_$valid)
589
590// e.g. void free( _Post_ptr_invalid_ void* pv );
591#define _Post_ptr_invalid_ _Post1_impl_(_$notvalid)
592
593// e.g. HRESULT InitStruct( _Post_valid_ Struct* pobj );
594#define _Post_valid_ _Deref_post1_impl_(_$valid)
595#define _Post_invalid_ _Deref_post1_impl_(_$notvalid)
596
597// e.g. void ThrowExceptionIfNull( _Post_notnull_ const void* pv );
598#define _Post_notnull_ _Post1_impl_(_$notnull)
599
600//
601// _Ret_ annotations
602//
603// describing conditions that hold for return values after the call
604
605// e.g. _Ret_z_ CString::operator const wchar_t*() const throw();
606#define _Ret_z_ _Ret2_impl_(_$notnull, _$zterm) _Deref_ret1_impl_(_$valid)
607#define _Ret_opt_z_ _Ret2_impl_(_$maybenull,_$zterm) _Deref_ret1_impl_(_$valid)
608
609// e.g. _Ret_opt_bytecap_(cb) void* AllocateMemory( size_t cb );
610// Buffer capacity is described by another parameter
611#define _Ret_cap_(size) _Ret2_impl_(_$notnull, _$cap(size))
612#define _Ret_opt_cap_(size) _Ret2_impl_(_$maybenull,_$cap(size))
613#define _Ret_bytecap_(size) _Ret2_impl_(_$notnull, _$bytecap(size))
614#define _Ret_opt_bytecap_(size) _Ret2_impl_(_$maybenull,_$bytecap(size))
615
616// Buffer capacity is described by a constant expression
617#define _Ret_cap_c_(size) _Ret2_impl_(_$notnull, _$cap_c(size))
618#define _Ret_opt_cap_c_(size) _Ret2_impl_(_$maybenull,_$cap_c(size))
619#define _Ret_bytecap_c_(size) _Ret2_impl_(_$notnull, _$bytecap_c(size))
620#define _Ret_opt_bytecap_c_(size) _Ret2_impl_(_$maybenull,_$bytecap_c(size))
621
622// Buffer capacity is described by a complex condition
623#define _Ret_cap_x_(size) _Ret2_impl_(_$notnull, _$cap_x(size))
624#define _Ret_opt_cap_x_(size) _Ret2_impl_(_$maybenull,_$cap_x(size))
625#define _Ret_bytecap_x_(size) _Ret2_impl_(_$notnull, _$bytecap_x(size))
626#define _Ret_opt_bytecap_x_(size) _Ret2_impl_(_$maybenull,_$bytecap_x(size))
627
628// return value is nullterminated and capacity is given by another parameter
629#define _Ret_z_cap_(size) _Ret3_impl_(_$notnull, _$zterm,_$cap(size)) _Deref_ret1_impl_(_$valid)
630#define _Ret_opt_z_cap_(size) _Ret3_impl_(_$maybenull,_$zterm,_$cap(size)) _Deref_ret1_impl_(_$valid)
631#define _Ret_z_bytecap_(size) _Ret3_impl_(_$notnull, _$zterm,_$bytecap(size)) _Deref_ret1_impl_(_$valid)
632#define _Ret_opt_z_bytecap_(size) _Ret3_impl_(_$maybenull,_$zterm,_$bytecap(size)) _Deref_ret1_impl_(_$valid)
633
634// e.g. _Ret_opt_bytecount_(cb) void* AllocateZeroInitializedMemory( size_t cb );
635// Valid Buffer extent is described by another parameter
636#define _Ret_count_(size) _Ret2_impl_(_$notnull, _$count(size)) _Deref_ret1_impl_(_$valid)
637#define _Ret_opt_count_(size) _Ret2_impl_(_$maybenull,_$count(size)) _Deref_ret1_impl_(_$valid)
638#define _Ret_bytecount_(size) _Ret2_impl_(_$notnull, _$bytecount(size)) _Deref_ret1_impl_(_$valid)
639#define _Ret_opt_bytecount_(size) _Ret2_impl_(_$maybenull,_$bytecount(size)) _Deref_ret1_impl_(_$valid)
640
641// Valid Buffer extent is described by a constant expression
642#define _Ret_count_c_(size) _Ret2_impl_(_$notnull, _$count_c(size)) _Deref_ret1_impl_(_$valid)
643#define _Ret_opt_count_c_(size) _Ret2_impl_(_$maybenull,_$count_c(size)) _Deref_ret1_impl_(_$valid)
644#define _Ret_bytecount_c_(size) _Ret2_impl_(_$notnull, _$bytecount_c(size)) _Deref_ret1_impl_(_$valid)
645#define _Ret_opt_bytecount_c_(size) _Ret2_impl_(_$maybenull,_$bytecount_c(size)) _Deref_ret1_impl_(_$valid)
646
647// Valid Buffer extent is described by a complex expression
648#define _Ret_count_x_(size) _Ret2_impl_(_$notnull, _$count_x(size)) _Deref_ret1_impl_(_$valid)
649#define _Ret_opt_count_x_(size) _Ret2_impl_(_$maybenull,_$count_x(size)) _Deref_ret1_impl_(_$valid)
650#define _Ret_bytecount_x_(size) _Ret2_impl_(_$notnull, _$bytecount_x(size)) _Deref_ret1_impl_(_$valid)
651#define _Ret_opt_bytecount_x_(size) _Ret2_impl_(_$maybenull,_$bytecount_x(size)) _Deref_ret1_impl_(_$valid)
652
653// return value is nullterminated and length is given by another parameter
654#define _Ret_z_count_(size) _Ret3_impl_(_$notnull, _$zterm,_$count(size)) _Deref_ret1_impl_(_$valid)
655#define _Ret_opt_z_count_(size) _Ret3_impl_(_$maybenull,_$zterm,_$count(size)) _Deref_ret1_impl_(_$valid)
656#define _Ret_z_bytecount_(size) _Ret3_impl_(_$notnull, _$zterm,_$bytecount(size)) _Deref_ret1_impl_(_$valid)
657#define _Ret_opt_z_bytecount_(size) _Ret3_impl_(_$maybenull,_$zterm,_$bytecount(size)) _Deref_ret1_impl_(_$valid)
658
659// e.g. _Ret_opt_valid_ LPSTR void* CloneSTR( _Pre_valid_ LPSTR src );
660#define _Ret_valid_ _Ret1_impl_(_$notnull) _Deref_ret1_impl_(_$valid)
661#define _Ret_opt_valid_ _Ret1_impl_(_$maybenull) _Deref_ret1_impl_(_$valid)
662
663// used with allocated but not yet initialized objects
664#define _Ret_notnull_ _Ret1_impl_(_$notnull)
665#define _Ret_maybenull_ _Ret1_impl_(_$maybenull)
666#define _Ret_null_ _Ret1_impl_(_$null)
667
668//
669// _Deref_pre_ ---
670//
671// describing conditions for array elements of dereferenced pointer parameters that must be met before the call
672
673// e.g. void SaveStringArray( _In_count_(cStrings) _Deref_pre_z_ const wchar_t* const rgpwch[] );
674#define _Deref_pre_z_ _Deref_pre2_impl_(_$notnull, _$zterm) _Deref2_pre1_impl_(_$valid)
675#define _Deref_pre_opt_z_ _Deref_pre2_impl_(_$maybenull,_$zterm) _Deref2_pre1_impl_(_$valid)
676
677// e.g. void FillInArrayOfStr32( _In_count_(cStrings) _Deref_pre_cap_c_(32) _Deref_post_z_ wchar_t* const rgpwch[] );
678// buffer capacity is described by another parameter
679#define _Deref_pre_cap_(size) _Deref_pre2_impl_(_$notnull, _$cap(size))
680#define _Deref_pre_opt_cap_(size) _Deref_pre2_impl_(_$maybenull,_$cap(size))
681#define _Deref_pre_bytecap_(size) _Deref_pre2_impl_(_$notnull, _$bytecap(size))
682#define _Deref_pre_opt_bytecap_(size) _Deref_pre2_impl_(_$maybenull,_$bytecap(size))
683
684// buffer capacity is described by a constant expression
685#define _Deref_pre_cap_c_(size) _Deref_pre2_impl_(_$notnull, _$cap_c(size))
686#define _Deref_pre_opt_cap_c_(size) _Deref_pre2_impl_(_$maybenull,_$cap_c(size))
687#define _Deref_pre_bytecap_c_(size) _Deref_pre2_impl_(_$notnull, _$bytecap_c(size))
688#define _Deref_pre_opt_bytecap_c_(size) _Deref_pre2_impl_(_$maybenull,_$bytecap_c(size))
689
690// buffer capacity is described by a complex condition
691#define _Deref_pre_cap_x_(size) _Deref_pre2_impl_(_$notnull, _$cap_x(size))
692#define _Deref_pre_opt_cap_x_(size) _Deref_pre2_impl_(_$maybenull,_$cap_x(size))
693#define _Deref_pre_bytecap_x_(size) _Deref_pre2_impl_(_$notnull, _$bytecap_x(size))
694#define _Deref_pre_opt_bytecap_x_(size) _Deref_pre2_impl_(_$maybenull,_$bytecap_x(size))
695
696// convenience macros for nullterminated buffers with given capacity
697#define _Deref_pre_z_cap_(size) _Deref_pre3_impl_(_$notnull, _$zterm,_$cap(size)) _Deref2_pre1_impl_(_$valid)
698#define _Deref_pre_opt_z_cap_(size) _Deref_pre3_impl_(_$maybenull,_$zterm,_$cap(size)) _Deref2_pre1_impl_(_$valid)
699#define _Deref_pre_z_bytecap_(size) _Deref_pre3_impl_(_$notnull, _$zterm,_$bytecap(size)) _Deref2_pre1_impl_(_$valid)
700#define _Deref_pre_opt_z_bytecap_(size) _Deref_pre3_impl_(_$maybenull,_$zterm,_$bytecap(size)) _Deref2_pre1_impl_(_$valid)
701
702#define _Deref_pre_z_cap_c_(size) _Deref_pre3_impl_(_$notnull, _$zterm,_$cap_c(size)) _Deref2_pre1_impl_(_$valid)
703#define _Deref_pre_opt_z_cap_c_(size) _Deref_pre3_impl_(_$maybenull,_$zterm,_$cap_c(size)) _Deref2_pre1_impl_(_$valid)
704#define _Deref_pre_z_bytecap_c_(size) _Deref_pre3_impl_(_$notnull, _$zterm,_$bytecap_c(size)) _Deref2_pre1_impl_(_$valid)
705#define _Deref_pre_opt_z_bytecap_c_(size) _Deref_pre3_impl_(_$maybenull,_$zterm,_$bytecap_c(size)) _Deref2_pre1_impl_(_$valid)
706
707#define _Deref_pre_z_cap_x_(size) _Deref_pre3_impl_(_$notnull, _$zterm,_$cap_x(size)) _Deref2_pre1_impl_(_$valid)
708#define _Deref_pre_opt_z_cap_x_(size) _Deref_pre3_impl_(_$maybenull,_$zterm,_$cap_x(size)) _Deref2_pre1_impl_(_$valid)
709#define _Deref_pre_z_bytecap_x_(size) _Deref_pre3_impl_(_$notnull, _$zterm,_$bytecap_x(size)) _Deref2_pre1_impl_(_$valid)
710#define _Deref_pre_opt_z_bytecap_x_(size) _Deref_pre3_impl_(_$maybenull,_$zterm,_$bytecap_x(size)) _Deref2_pre1_impl_(_$valid)
711
712// known capacity and valid but unknown readable extent
713#define _Deref_pre_valid_cap_(size) _Deref_pre2_impl_(_$notnull, _$cap(size)) _Deref2_pre1_impl_(_$valid)
714#define _Deref_pre_opt_valid_cap_(size) _Deref_pre2_impl_(_$maybenull,_$cap(size)) _Deref2_pre1_impl_(_$valid)
715#define _Deref_pre_valid_bytecap_(size) _Deref_pre2_impl_(_$notnull, _$bytecap(size)) _Deref2_pre1_impl_(_$valid)
716#define _Deref_pre_opt_valid_bytecap_(size) _Deref_pre2_impl_(_$maybenull,_$bytecap(size)) _Deref2_pre1_impl_(_$valid)
717
718#define _Deref_pre_valid_cap_c_(size) _Deref_pre2_impl_(_$notnull, _$cap_c(size)) _Deref2_pre1_impl_(_$valid)
719#define _Deref_pre_opt_valid_cap_c_(size) _Deref_pre2_impl_(_$maybenull,_$cap_c(size)) _Deref2_pre1_impl_(_$valid)
720#define _Deref_pre_valid_bytecap_c_(size) _Deref_pre2_impl_(_$notnull, _$bytecap_c(size)) _Deref2_pre1_impl_(_$valid)
721#define _Deref_pre_opt_valid_bytecap_c_(size) _Deref_pre2_impl_(_$maybenull,_$bytecap_c(size)) _Deref2_pre1_impl_(_$valid)
722
723#define _Deref_pre_valid_cap_x_(size) _Deref_pre2_impl_(_$notnull, _$cap_x(size)) _Deref2_pre1_impl_(_$valid)
724#define _Deref_pre_opt_valid_cap_x_(size) _Deref_pre2_impl_(_$maybenull,_$cap_x(size)) _Deref2_pre1_impl_(_$valid)
725#define _Deref_pre_valid_bytecap_x_(size) _Deref_pre2_impl_(_$notnull, _$bytecap_x(size)) _Deref2_pre1_impl_(_$valid)
726#define _Deref_pre_opt_valid_bytecap_x_(size) _Deref_pre2_impl_(_$maybenull,_$bytecap_x(size)) _Deref2_pre1_impl_(_$valid)
727
728// e.g. void SaveMatrix( _In_count_(n) _Deref_pre_count_(n) const Elem** matrix, size_t n );
729// valid buffer extent is described by another parameter
730#define _Deref_pre_count_(size) _Deref_pre2_impl_(_$notnull, _$count(size)) _Deref2_pre1_impl_(_$valid)
731#define _Deref_pre_opt_count_(size) _Deref_pre2_impl_(_$maybenull,_$count(size)) _Deref2_pre1_impl_(_$valid)
732#define _Deref_pre_bytecount_(size) _Deref_pre2_impl_(_$notnull, _$bytecount(size)) _Deref2_pre1_impl_(_$valid)
733#define _Deref_pre_opt_bytecount_(size) _Deref_pre2_impl_(_$maybenull,_$bytecount(size)) _Deref2_pre1_impl_(_$valid)
734
735// valid buffer extent is described by a constant expression
736#define _Deref_pre_count_c_(size) _Deref_pre2_impl_(_$notnull, _$count_c(size)) _Deref2_pre1_impl_(_$valid)
737#define _Deref_pre_opt_count_c_(size) _Deref_pre2_impl_(_$maybenull,_$count_c(size)) _Deref2_pre1_impl_(_$valid)
738#define _Deref_pre_bytecount_c_(size) _Deref_pre2_impl_(_$notnull, _$bytecount_c(size)) _Deref2_pre1_impl_(_$valid)
739#define _Deref_pre_opt_bytecount_c_(size) _Deref_pre2_impl_(_$maybenull,_$bytecount_c(size)) _Deref2_pre1_impl_(_$valid)
740
741// valid buffer extent is described by a complex expression
742#define _Deref_pre_count_x_(size) _Deref_pre2_impl_(_$notnull, _$count_x(size)) _Deref2_pre1_impl_(_$valid)
743#define _Deref_pre_opt_count_x_(size) _Deref_pre2_impl_(_$maybenull,_$count_x(size)) _Deref2_pre1_impl_(_$valid)
744#define _Deref_pre_bytecount_x_(size) _Deref_pre2_impl_(_$notnull, _$bytecount_x(size)) _Deref2_pre1_impl_(_$valid)
745#define _Deref_pre_opt_bytecount_x_(size) _Deref_pre2_impl_(_$maybenull,_$bytecount_x(size)) _Deref2_pre1_impl_(_$valid)
746
747// e.g. void PrintStringArray( _In_count_(cElems) _Deref_pre_valid_ LPCSTR rgStr[], size_t cElems );
748#define _Deref_pre_valid_ _Deref_pre1_impl_(_$notnull) _Deref2_pre1_impl_(_$valid)
749#define _Deref_pre_opt_valid_ _Deref_pre1_impl_(_$maybenull) _Deref2_pre1_impl_(_$valid)
750#define _Deref_pre_invalid_ _Deref2_pre1_impl_(_$notvalid)
751
752#define _Deref_pre_notnull_ _Deref_pre1_impl_(_$notnull)
753#define _Deref_pre_maybenull_ _Deref_pre1_impl_(_$maybenull)
754#define _Deref_pre_null_ _Deref_pre1_impl_(_$null)
755
756// restrict access rights
757#define _Deref_pre_readonly_ _Deref_pre1_impl_(_$readaccess)
758#define _Deref_pre_writeonly_ _Deref_pre1_impl_(_$writeaccess)
759
760//
761// _Deref_post_ ---
762//
763// describing conditions for array elements or dereferenced pointer parameters that hold after the call
764
765// e.g. void CloneString( _In_z_ const Wchar_t* wzIn _Out_ _Deref_post_z_ wchar_t** pWzOut );
766#define _Deref_post_z_ _Deref_post2_impl_(_$notnull, _$zterm) _Deref2_post1_impl_(_$valid)
767#define _Deref_post_opt_z_ _Deref_post2_impl_(_$maybenull,_$zterm) _Deref2_post1_impl_(_$valid)
768
769// e.g. HRESULT HrAllocateMemory( size_t cb, _Out_ _Deref_post_bytecap_(cb) void** ppv );
770// buffer capacity is described by another parameter
771#define _Deref_post_cap_(size) _Deref_post2_impl_(_$notnull, _$cap(size))
772#define _Deref_post_opt_cap_(size) _Deref_post2_impl_(_$maybenull,_$cap(size))
773#define _Deref_post_bytecap_(size) _Deref_post2_impl_(_$notnull, _$bytecap(size))
774#define _Deref_post_opt_bytecap_(size) _Deref_post2_impl_(_$maybenull,_$bytecap(size))
775
776// buffer capacity is described by a constant expression
777#define _Deref_post_cap_c_(size) _Deref_post2_impl_(_$notnull, _$cap_z(size))
778#define _Deref_post_opt_cap_c_(size) _Deref_post2_impl_(_$maybenull,_$cap_z(size))
779#define _Deref_post_bytecap_c_(size) _Deref_post2_impl_(_$notnull, _$bytecap_z(size))
780#define _Deref_post_opt_bytecap_c_(size) _Deref_post2_impl_(_$maybenull,_$bytecap_z(size))
781
782// buffer capacity is described by a complex expression
783#define _Deref_post_cap_x_(size) _Deref_post2_impl_(_$notnull, _$cap_x(size))
784#define _Deref_post_opt_cap_x_(size) _Deref_post2_impl_(_$maybenull,_$cap_x(size))
785#define _Deref_post_bytecap_x_(size) _Deref_post2_impl_(_$notnull, _$bytecap_x(size))
786#define _Deref_post_opt_bytecap_x_(size) _Deref_post2_impl_(_$maybenull,_$bytecap_x(size))
787
788// convenience macros for nullterminated buffers with given capacity
789#define _Deref_post_z_cap_(size) _Deref_post3_impl_(_$notnull, _$zterm,_$cap(size)) _Deref2_post1_impl_(_$valid)
790#define _Deref_post_opt_z_cap_(size) _Deref_post3_impl_(_$maybenull,_$zterm,_$cap(size)) _Deref2_post1_impl_(_$valid)
791#define _Deref_post_z_bytecap_(size) _Deref_post3_impl_(_$notnull, _$zterm,_$bytecap(size)) _Deref2_post1_impl_(_$valid)
792#define _Deref_post_opt_z_bytecap_(size) _Deref_post3_impl_(_$maybenull,_$zterm,_$bytecap(size)) _Deref2_post1_impl_(_$valid)
793
794#define _Deref_post_z_cap_c_(size) _Deref_post3_impl_(_$notnull, _$zterm,_$cap_c(size)) _Deref2_post1_impl_(_$valid)
795#define _Deref_post_opt_z_cap_c_(size) _Deref_post3_impl_(_$maybenull,_$zterm,_$cap_c(size)) _Deref2_post1_impl_(_$valid)
796#define _Deref_post_z_bytecap_c_(size) _Deref_post3_impl_(_$notnull, _$zterm,_$bytecap_c(size)) _Deref2_post1_impl_(_$valid)
797#define _Deref_post_opt_z_bytecap_c_(size) _Deref_post3_impl_(_$maybenull,_$zterm,_$bytecap_c(size)) _Deref2_post1_impl_(_$valid)
798
799#define _Deref_post_z_cap_x_(size) _Deref_post3_impl_(_$notnull, _$zterm,_$cap_x(size)) _Deref2_post1_impl_(_$valid)
800#define _Deref_post_opt_z_cap_x_(size) _Deref_post3_impl_(_$maybenull,_$zterm,_$cap_x(size)) _Deref2_post1_impl_(_$valid)
801#define _Deref_post_z_bytecap_x_(size) _Deref_post3_impl_(_$notnull, _$zterm,_$bytecap_x(size)) _Deref2_post1_impl_(_$valid)
802#define _Deref_post_opt_z_bytecap_x_(size) _Deref_post3_impl_(_$maybenull,_$zterm,_$bytecap_x(size)) _Deref2_post1_impl_(_$valid)
803
804// known capacity and valid but unknown readable extent
805#define _Deref_post_valid_cap_(size) _Deref_post2_impl_(_$notnull, _$cap(size)) _Deref2_post1_impl_(_$valid)
806#define _Deref_post_opt_valid_cap_(size) _Deref_post2_impl_(_$maybenull,_$cap(size)) _Deref2_post1_impl_(_$valid)
807#define _Deref_post_valid_bytecap_(size) _Deref_post2_impl_(_$notnull, _$bytecap(size)) _Deref2_post1_impl_(_$valid)
808#define _Deref_post_opt_valid_bytecap_(size) _Deref_post2_impl_(_$maybenull,_$bytecap(size)) _Deref2_post1_impl_(_$valid)
809
810#define _Deref_post_valid_cap_c_(size) _Deref_post2_impl_(_$notnull, _$cap_c(size)) _Deref2_post1_impl_(_$valid)
811#define _Deref_post_opt_valid_cap_c_(size) _Deref_post2_impl_(_$maybenull,_$cap_c(size)) _Deref2_post1_impl_(_$valid)
812#define _Deref_post_valid_bytecap_c_(size) _Deref_post2_impl_(_$notnull, _$bytecap_c(size)) _Deref2_post1_impl_(_$valid)
813#define _Deref_post_opt_valid_bytecap_c_(size) _Deref_post2_impl_(_$maybenull,_$bytecap_c(size)) _Deref2_post1_impl_(_$valid)
814
815#define _Deref_post_valid_cap_x_(size) _Deref_post2_impl_(_$notnull, _$cap_x(size)) _Deref2_post1_impl_(_$valid)
816#define _Deref_post_opt_valid_cap_x_(size) _Deref_post2_impl_(_$maybenull,_$cap_x(size)) _Deref2_post1_impl_(_$valid)
817#define _Deref_post_valid_bytecap_x_(size) _Deref_post2_impl_(_$notnull, _$bytecap_x(size)) _Deref2_post1_impl_(_$valid)
818#define _Deref_post_opt_valid_bytecap_x_(size) _Deref_post2_impl_(_$maybenull,_$bytecap_x(size)) _Deref2_post1_impl_(_$valid)
819
820// e.g. HRESULT HrAllocateZeroInitializedMemory( size_t cb, _Out_ _Deref_post_bytecount_(cb) void** ppv );
821// valid buffer extent is described by another parameter
822#define _Deref_post_count_(size) _Deref_post2_impl_(_$notnull, _$count(size)) _Deref2_post1_impl_(_$valid)
823#define _Deref_post_opt_count_(size) _Deref_post2_impl_(_$maybenull,_$count(size)) _Deref2_post1_impl_(_$valid)
824#define _Deref_post_bytecount_(size) _Deref_post2_impl_(_$notnull, _$bytecount(size)) _Deref2_post1_impl_(_$valid)
825#define _Deref_post_opt_bytecount_(size) _Deref_post2_impl_(_$maybenull,_$bytecount(size)) _Deref2_post1_impl_(_$valid)
826
827// buffer capacity is described by a constant expression
828#define _Deref_post_count_c_(size) _Deref_post2_impl_(_$notnull, _$count_c(size)) _Deref2_post1_impl_(_$valid)
829#define _Deref_post_opt_count_c_(size) _Deref_post2_impl_(_$maybenull,_$count_c(size)) _Deref2_post1_impl_(_$valid)
830#define _Deref_post_bytecount_c_(size) _Deref_post2_impl_(_$notnull, _$bytecount_c(size)) _Deref2_post1_impl_(_$valid)
831#define _Deref_post_opt_bytecount_c_(size) _Deref_post2_impl_(_$maybenull,_$bytecount_c(size)) _Deref2_post1_impl_(_$valid)
832
833// buffer capacity is described by a complex expression
834#define _Deref_post_count_x_(size) _Deref_post2_impl_(_$notnull, _$count_x(size)) _Deref2_post1_impl_(_$valid)
835#define _Deref_post_opt_count_x_(size) _Deref_post2_impl_(_$maybenull,_$count_x(size)) _Deref2_post1_impl_(_$valid)
836#define _Deref_post_bytecount_x_(size) _Deref_post2_impl_(_$notnull, _$bytecount_x(size)) _Deref2_post1_impl_(_$valid)
837#define _Deref_post_opt_bytecount_x_(size) _Deref_post2_impl_(_$maybenull,_$bytecount_x(size)) _Deref2_post1_impl_(_$valid)
838
839// e.g. void GetStrings( _Out_count_(cElems) _Deref_post_valid_ LPSTR const rgStr[], size_t cElems );
840#define _Deref_post_valid_ _Deref_post1_impl_(_$notnull) _Deref2_post1_impl_(_$valid)
841#define _Deref_post_opt_valid_ _Deref_post1_impl_(_$maybenull) _Deref2_post1_impl_(_$valid)
842
843#define _Deref_post_notnull_ _Deref_post1_impl_(_$notnull)
844#define _Deref_post_maybenull_ _Deref_post1_impl_(_$maybenull)
845#define _Deref_post_null_ _Deref_post1_impl_(_$null)
846
847//
848// _Deref_ret_ ---
849//
850
851#define _Deref_ret_z_ _Deref_ret2_impl_(_$notnull, _$zterm)
852#define _Deref_ret_opt_z_ _Deref_ret2_impl_(_$maybenull,_$zterm)
853
854//
855// special _Deref_ ---
856//
857#define _Deref2_pre_readonly_ _Deref2_pre1_impl_(_$readaccess)
858
859// Convenience macros for more concise annotations
860
861//
862// _Pre_post ---
863//
864// describing conditions that hold before and after the function call
865
866#define _Prepost_z_ _Pre_z_ _Post_z_
867#define _Prepost_opt_z_ _Pre_opt_z_ _Post_z_
868
869#define _Prepost_count_(size) _Pre_count_(size) _Post_count_(size)
870#define _Prepost_opt_count_(size) _Pre_opt_count_(size) _Post_count_(size)
871#define _Prepost_bytecount_(size) _Pre_bytecount_(size) _Post_bytecount_(size)
872#define _Prepost_opt_bytecount_(size) _Pre_opt_bytecount_(size) _Post_bytecount_(size)
873#define _Prepost_count_c_(size) _Pre_count_c_(size) _Post_count_c_(size)
874#define _Prepost_opt_count_c_(size) _Pre_opt_count_c_(size) _Post_count_c_(size)
875#define _Prepost_bytecount_c_(size) _Pre_bytecount_c_(size) _Post_bytecount_c_(size)
876#define _Prepost_opt_bytecount_c_(size) _Pre_opt_bytecount_c_(size) _Post_bytecount_c_(size)
877#define _Prepost_count_x_(size) _Pre_count_x_(size) _Post_count_x_(size)
878#define _Prepost_opt_count_x_(size) _Pre_opt_count_x_(size) _Post_count_x_(size)
879#define _Prepost_bytecount_x_(size) _Pre_bytecount_x_(size) _Post_bytecount_x_(size)
880#define _Prepost_opt_bytecount_x_(size) _Pre_opt_bytecount_x_(size) _Post_bytecount_x_(size)
881
882#define _Prepost_valid_ _Pre_valid_ _Post_valid_
883#define _Prepost_opt_valid_ _Pre_opt_valid_ _Post_valid_
884
885//
886// _Deref_<both> ---
887//
888// short version for _Deref_pre_<ann> _Deref_post_<ann>
889// describing conditions for array elements or dereferenced pointer parameters that hold before and after the call
890
891#define _Deref_prepost_z_ _Deref_pre_z_ _Deref_post_z_
892#define _Deref_prepost_opt_z_ _Deref_pre_opt_z_ _Deref_post_opt_z_
893
894#define _Deref_prepost_cap_(size) _Deref_pre_cap_(size) _Deref_post_cap_(size)
895#define _Deref_prepost_opt_cap_(size) _Deref_pre_opt_cap_(size) _Deref_post_opt_cap_(size)
896#define _Deref_prepost_bytecap_(size) _Deref_pre_bytecap_(size) _Deref_post_bytecap_(size)
897#define _Deref_prepost_opt_bytecap_(size) _Deref_pre_opt_bytecap_(size) _Deref_post_opt_bytecap_(size)
898
899#define _Deref_prepost_cap_x_(size) _Deref_pre_cap_x_(size) _Deref_post_cap_x_(size)
900#define _Deref_prepost_opt_cap_x_(size) _Deref_pre_opt_cap_x_(size) _Deref_post_opt_cap_x_(size)
901#define _Deref_prepost_bytecap_x_(size) _Deref_pre_bytecap_x_(size) _Deref_post_bytecap_x_(size)
902#define _Deref_prepost_opt_bytecap_x_(size) _Deref_pre_opt_bytecap_x_(size) _Deref_post_opt_bytecap_x_(size)
903
904#define _Deref_prepost_z_cap_(size) _Deref_pre_z_cap_(size) _Deref_post_z_cap_(size)
905#define _Deref_prepost_opt_z_cap_(size) _Deref_pre_opt_z_cap_(size) _Deref_post_opt_z_cap_(size)
906#define _Deref_prepost_z_bytecap_(size) _Deref_pre_z_bytecap_(size) _Deref_post_z_bytecap_(size)
907#define _Deref_prepost_opt_z_bytecap_(size) _Deref_pre_opt_z_bytecap_(size) _Deref_post_opt_z_bytecap_(size)
908
909#define _Deref_prepost_valid_cap_(size) _Deref_pre_valid_cap_(size) _Deref_post_valid_cap_(size)
910#define _Deref_prepost_opt_valid_cap_(size) _Deref_pre_opt_valid_cap_(size) _Deref_post_opt_valid_cap_(size)
911#define _Deref_prepost_valid_bytecap_(size) _Deref_pre_valid_bytecap_(size) _Deref_post_valid_bytecap_(size)
912#define _Deref_prepost_opt_valid_bytecap_(size) _Deref_pre_opt_valid_bytecap_(size) _Deref_post_opt_valid_bytecap_(size)
913
914#define _Deref_prepost_valid_cap_x_(size) _Deref_pre_valid_cap_x_(size) _Deref_post_valid_cap_x_(size)
915#define _Deref_prepost_opt_valid_cap_x_(size) _Deref_pre_opt_valid_cap_x_(size) _Deref_post_opt_valid_cap_x_(size)
916#define _Deref_prepost_valid_bytecap_x_(size) _Deref_pre_valid_bytecap_x_(size) _Deref_post_valid_bytecap_x_(size)
917#define _Deref_prepost_opt_valid_bytecap_x_(size) _Deref_pre_opt_valid_bytecap_x_(size) _Deref_post_opt_valid_bytecap_x_(size)
918
919#define _Deref_prepost_count_(size) _Deref_pre_count_(size) _Deref_post_count_(size)
920#define _Deref_prepost_opt_count_(size) _Deref_pre_opt_count_(size) _Deref_post_opt_count_(size)
921#define _Deref_prepost_bytecount_(size) _Deref_pre_bytecount_(size) _Deref_post_bytecount_(size)
922#define _Deref_prepost_opt_bytecount_(size) _Deref_pre_opt_bytecount_(size) _Deref_post_opt_bytecount_(size)
923
924#define _Deref_prepost_count_x_(size) _Deref_pre_count_x_(size) _Deref_post_count_x_(size)
925#define _Deref_prepost_opt_count_x_(size) _Deref_pre_opt_count_x_(size) _Deref_post_opt_count_x_(size)
926#define _Deref_prepost_bytecount_x_(size) _Deref_pre_bytecount_x_(size) _Deref_post_bytecount_x_(size)
927#define _Deref_prepost_opt_bytecount_x_(size) _Deref_pre_opt_bytecount_x_(size) _Deref_post_opt_bytecount_x_(size)
928
929#define _Deref_prepost_valid_ _Deref_pre_valid_ _Deref_post_valid_
930#define _Deref_prepost_opt_valid_ _Deref_pre_opt_valid_ _Deref_post_opt_valid_
931
932//
933// _Deref_<miscellaneous>
934//
935// used with references to arrays
936
937#define _Deref_out_z_cap_c_(size) _Deref_pre_cap_c_(size) _Deref_pre_invalid_ _Deref_post_z_
938#define _Deref_inout_z_cap_c_(size) _Deref_pre_z_cap_c_(size) _Deref_post_z_
939#define _Deref_out_z_bytecap_c_(size) _Deref_pre_bytecap_c_(size) _Deref_pre_invalid_ _Deref_post_z_
940#define _Deref_inout_z_bytecap_c_(size) _Deref_pre_z_bytecap_c_(size) _Deref_post_z_
941#define _Deref_inout_z_ _Deref_prepost_z_
942
943//============================================================================
944// Implementation Layer:
945//============================================================================
946
947#if _USE_ATTRIBUTES_FOR_SAL
948
949#define _Check_return_impl_ [returnvalue:SA_Post(MustCheck=SA_Yes)]
950
951#define _Success_impl_(expr) [SA_Success(Condition=#expr)]
952
953#define _Printf_format_string_impl_ [SA_FormatString(Style="printf")]
954#define _Scanf_format_string_impl_ [SA_FormatString(Style="scanf")]
955#define _Scanf_s_format_string_impl_ [SA_FormatString(Style="scanf_s")]
956
957#define _In_bound_impl_ [SA_PreBound(Deref=0)]
958#define _Out_bound_impl_ [SA_PostBound(Deref=0)]
959#define _Ret_bound_impl_ [returnvalue:SA_PostBound(Deref=0)]
960#define _Deref_in_bound_impl_ [SA_PreBound(Deref=1)]
961#define _Deref_out_bound_impl_ [SA_PostBound(Deref=1)]
962#define _Deref_ret_bound_impl_ [returnvalue:SA_PostBound(Deref=1)]
963
964#define _In_range_impl_(min,max) [SA_PreRange(MinVal=#min,MaxVal=#max)]
965#define _Out_range_impl_(min,max) [SA_PostRange(MinVal=#min,MaxVal=#max)]
966#define _Ret_range_impl_(min,max) [returnvalue:SA_PostRange(MinVal=#min,MaxVal=#max)]
967#define _Deref_in_range_impl_(min,max) [SA_PreRange(Deref=1,MinVal=#min,MaxVal=#max)]
968#define _Deref_out_range_impl_(min,max) [SA_PostRange(Deref=1,MinVal=#min,MaxVal=#max)]
969#define _Deref_ret_range_impl_(min,max) [returnvalue:SA_PostRange(Deref=1,MinVal=#min,MaxVal=#max)]
970
971#define _$valid Valid=SA_Yes
972#define _$maybevalid Valid=SA_Maybe
973#define _$notvalid Valid=SA_No
974
975#define _$null Null=SA_Yes
976#define _$maybenull Null=SA_Maybe
977#define _$notnull Null=SA_No
978
979#define _$zterm NullTerminated=SA_Yes
980#define _$maybezterm NullTerminated=SA_Maybe
981#define _$notzterm NullTerminated=SA_No
982
983#define _$readaccess Access=SA_Read
984#define _$writeaccess Access=SA_Write
985
986#define _$cap(size) WritableElements=#size
987#define _$cap_c(size) WritableElementsConst=size
988#define _$cap_for(param) WritableElementsLength=#param
989#define _$cap_x(size) WritableElements="\n@"#size
990
991#define _$bytecap(size) WritableBytes=#size
992#define _$bytecap_c(size) WritableBytesConst=size
993#define _$bytecap_x(size) WritableBytes="\n@"#size
994
995#define _$mult(mult,size) ElementSizeConst=mult,_$cap(size)
996
997#define _$count(size) ValidElements=#size
998#define _$count_c(size) ValidElementsConst=size
999#define _$count_x(size) ValidElements="\n@"#size
1000
1001#define _$bytecount(size) ValidBytes=#size
1002#define _$bytecount_c(size) ValidBytesConst=size
1003#define _$bytecount_x(size) ValidBytes="\n@"#size
1004
1005#define _Pre1_impl_(p1) [SA_Pre(p1)]
1006#define _Pre2_impl_(p1,p2) [SA_Pre(p1,p2)]
1007#define _Pre3_impl_(p1,p2,p3) [SA_Pre(p1,p2,p3)]
1008
1009#define _Post1_impl_(p1) [SA_Post(p1)]
1010#define _Post2_impl_(p1,p2) [SA_Post(p1,p2)]
1011#define _Post3_impl_(p1,p2,p3) [SA_Post(p1,p2,p3)]
1012
1013#define _Ret1_impl_(p1) [returnvalue:SA_Post(p1)]
1014#define _Ret2_impl_(p1,p2) [returnvalue:SA_Post(p1,p2)]
1015#define _Ret3_impl_(p1,p2,p3) [returnvalue:SA_Post(p1,p2,p3)]
1016
1017#define _Deref_pre1_impl_(p1) [SA_Pre(Deref=1,p1)]
1018#define _Deref_pre2_impl_(p1,p2) [SA_Pre(Deref=1,p1,p2)]
1019#define _Deref_pre3_impl_(p1,p2,p3) [SA_Pre(Deref=1,p1,p2,p3)]
1020
1021#define _Deref_post1_impl_(p1) [SA_Post(Deref=1,p1)]
1022#define _Deref_post2_impl_(p1,p2) [SA_Post(Deref=1,p1,p2)]
1023#define _Deref_post3_impl_(p1,p2,p3) [SA_Post(Deref=1,p1,p2,p3)]
1024
1025#define _Deref_ret1_impl_(p1) [returnvalue:SA_Post(Deref=1,p1)]
1026#define _Deref_ret2_impl_(p1,p2) [returnvalue:SA_Post(Deref=1,p1,p2)]
1027#define _Deref_ret3_impl_(p1,p2,p3) [returnvalue:SA_Post(Deref=1,p1,p2,p3)]
1028
1029#define _Deref2_pre1_impl_(p1) [SA_Pre(Deref=2,p1)]
1030#define _Deref2_post1_impl_(p1) [SA_Post(Deref=2,p1)]
1031#define _Deref2_ret1_impl_(p1) [returnvalue:SA_Post(Deref=2,p1)]
1032
1033#elif _USE_DECLSPECS_FOR_SAL
1034
1035#define _$SPECSTRIZE( x ) #x
1036
1037#define _Check_return_impl_ __declspec("SAL_checkReturn")
1038
1039#define _Success_impl_(expr) __declspec("SAL_success("_$SPECSTRIZE(expr)")")
1040
1041#define _Printf_format_string_impl_
1042#define _Scanf_format_string_impl_
1043#define _Scanf_s_format_string_impl_
1044
1045#define _In_bound_impl_ _$pre _$bound
1046#define _Out_bound_impl_ _$post _$bound
1047#define _Ret_bound_impl_ _$post _$bound
1048#define _Deref_in_bound_impl_ _$derefpre _$bound
1049#define _Deref_out_bound_impl_ _$derefpost _$bound
1050#define _Deref_ret_bound_impl_ _$derefpost bound
1051
1052#define _In_range_impl_(min,max) _$pre _$range(min,max)
1053#define _Out_range_impl_(min,max) _$post _$range(min,max)
1054#define _Ret_range_impl_(min,max) _$post _$range(min,max)
1055#define _Deref_in_range_impl_(min,max) _$derefpre _$range(min,max)
1056#define _Deref_out_range_impl_(min,max) _$derefpost _$range(min,max)
1057#define _Deref_ret_range_impl_(min,max) _$derefpost _$range(min,max)
1058
1059#define _$valid __declspec("SAL_valid")
1060#define _$maybevalid __declspec("SAL_maybevalid")
1061#define _$notvalid __declspec("SAL_notvalid")
1062
1063#define _$null __declspec("SAL_null")
1064#define _$maybenull __declspec("SAL_maybenull")
1065#define _$notnull __declspec("SAL_notnull")
1066
1067#define _$zterm __declspec("SAL_readableTo(sentinel(0))")
1068#define _$maybezterm
1069#define _$notzterm
1070
1071#define _$readaccess __declspec("SAL_readonly")
1072#define _$writeaccess __declspec("SAL_notreadonly")
1073
1074#define _$cap(size) __declspec("SAL_writableTo(elementCount("_$SPECSTRIZE(size)"))")
1075#define _$cap_c(size) __declspec("SAL_writableTo(elementCount("_$SPECSTRIZE(size)"))")
1076#define _$cap_for(param) __declspec("SAL_writableTo(needsCountFor("_$SPECSTRIZE(param)"))")
1077#define _$cap_x(size) __declspec("SAL_writableTo(inexpressibleCount('"_$SPECSTRIZE(size)"'))")
1078
1079#define _$bytecap(size) __declspec("SAL_writableTo(byteCount("_$SPECSTRIZE(size)"))")
1080#define _$bytecap_c(size) __declspec("SAL_writableTo(byteCount("_$SPECSTRIZE(size)"))")
1081#define _$bytecap_x(size) __declspec("SAL_writableTo(inexpressibleCount('"_$SPECSTRIZE(size)"'))")
1082
1083#define _$mult(mult,size) __declspec("SAL_writableTo(inexpressibleCount("_$SPECSTRIZE(mult)"*"_$SPECSTRIZE(size)"))")
1084
1085#define _$count(size) __declspec("SAL_readableTo(elementCount("_$SPECSTRIZE(size)"))")
1086#define _$count_c(size) __declspec("SAL_readableTo(elementCount("_$SPECSTRIZE(size)"))")
1087#define _$count_x(size) __declspec("SAL_readableTo(inexpressibleCount('"_$SPECSTRIZE(size)"'))")
1088
1089#define _$bytecount(size) __declspec("SAL_readableTo(byteCount("_$SPECSTRIZE(size)"))")
1090#define _$bytecount_c(size) __declspec("SAL_readableTo(byteCount("_$SPECSTRIZE(size)"))")
1091#define _$bytecount_x(size) __declspec("SAL_readableTo(inexpressibleCount('"_$SPECSTRIZE(size)"'))")
1092
1093#define _$pre __declspec("SAL_pre")
1094#define _$post __declspec("SAL_post")
1095#define _$deref_pre __declspec("SAL_pre") __declspec("SAL_deref")
1096#define _$deref_post __declspec("SAL_post") __declspec("SAL_deref")
1097
1098#define _$bound __declspec("SAL_bound")
1099#define _$range(min,max) __declspec("SAL_range("_$SPECSTRIZE(min)","_$SPECSTRIZE(max)")")
1100
1101#define _Pre1_impl_(p1) _$pre p1
1102#define _Pre2_impl_(p1,p2) _$pre p1 _$pre p2
1103#define _Pre3_impl_(p1,p2,p3) _$pre p1 _$pre p2 _$pre p3
1104
1105#define _Post1_impl_(p1) _$post p1
1106#define _Post2_impl_(p1,p2) _$post p1 _$post p2
1107#define _Post3_impl_(p1,p2,p3) _$post p1 _$post p2 _$post p3
1108
1109#define _Ret1_impl_(p1) _$post p1
1110#define _Ret2_impl_(p1,p2) _$post p1 _$post p2
1111#define _Ret3_impl_(p1,p2,p3) _$post p1 _$post p2 _$post p3
1112
1113#define _Deref_pre1_impl_(p1) _$deref_pre p1
1114#define _Deref_pre2_impl_(p1,p2) _$deref_pre p1 _$deref_pre p2
1115#define _Deref_pre3_impl_(p1,p2,p3) _$deref_pre p1 _$deref_pre p2 _$deref_pre p3
1116
1117#define _Deref_post1_impl_(p1) _$deref_post p1
1118#define _Deref_post2_impl_(p1,p2) _$deref_post p1 _$deref_post p2
1119#define _Deref_post3_impl_(p1,p2,p3) _$deref_post p1 _$deref_post p2 _$deref_post p3
1120
1121#define _Deref_ret1_impl_(p1) _$deref_post p1
1122#define _Deref_ret2_impl_(p1,p2) _$deref_post p1 _$deref_post p2
1123#define _Deref_ret3_impl_(p1,p2,p3) _$deref_post p1 _$deref_post p2 _$deref_post p3
1124
1125#define _Deref2_pre1_impl_(p1) _$deref_pre __declspec("SAL_deref") p1
1126#define _Deref2_post1_impl_(p1) _$deref_post __declspec("SAL_deref") p1
1127#define _Deref2_ret1_impl_(p1) _$deref_post __declspec("SAL_deref") p1
1128
1129#elif defined(_MSC_EXTENSIONS) && !defined( MIDL_PASS ) && !defined(__midl) && !defined(RC_INVOKED) && defined(_PFT_VER) && _MSC_VER >= 1400
1130
1131// minimum attribute expansion for foreground build
1132
1133#pragma push_macro( "SA" )
1134#pragma push_macro( "REPEATABLE" )
1135
1136#ifdef __cplusplus
1137#define SA( id ) id
1138#define REPEATABLE [repeatable]
1139#else // !__cplusplus
1140#define SA( id ) SA_##id
1141#define REPEATABLE
1142#endif // !__cplusplus
1143
1144REPEATABLE
1145[source_annotation_attribute( SA( Parameter ) )]
1146struct _$P
1147{
1148#ifdef __cplusplus
1149 _$P();
1150#endif
1151 int _$d;
1152};
1153typedef struct _$P _$P;
1154
1155REPEATABLE
1156[source_annotation_attribute( SA( ReturnValue ) )]
1157struct _$R
1158{
1159#ifdef __cplusplus
1160 _$R();
1161#endif
1162 int _$d;
1163};
1164typedef struct _$R _$R;
1165
1166[source_annotation_attribute( SA( Method ) )]
1167struct _$M
1168{
1169#ifdef __cplusplus
1170 _$M();
1171#endif
1172 int _$d;
1173};
1174typedef struct _$M _$M;
1175
1176#pragma pop_macro( "REPEATABLE" )
1177#pragma pop_macro( "SA" )
1178
1179#define _Check_return_impl_ [returnvalue:_$R(_$d=0)]
1180
1181#define _Success_impl_(expr) [_$M(_$d=0)]
1182
1183#define _Printf_format_string_impl_ [_$P(_$d=0)]
1184#define _Scanf_format_string_impl_ [_$P(_$d=0)]
1185#define _Scanf_s_format_string_impl_ [_$P(_$d=0)]
1186
1187#define _In_bound_impl_ [_$P(_$d=0)]
1188#define _Out_bound_impl_ [_$P(_$d=0)]
1189#define _Ret_bound_impl_ [returnvalue:_$R(_$d=0)]
1190#define _Deref_in_bound_impl_ [_$P(_$d=0)]
1191#define _Deref_out_bound_impl_ [_$P(_$d=0)]
1192#define _Deref_ret_bound_impl_ [returnvalue:_$R(_$d=0)]
1193
1194#define _In_range_impl_(min,max) [_$P(_$d=0)]
1195#define _Out_range_impl_(min,max) [_$P(_$d=0)]
1196#define _Ret_range_impl_(min,max) [returnvalue:_$R(_$d=0)]
1197#define _Deref_in_range_impl_(min,max) [_$P(_$d=0)]
1198#define _Deref_out_range_impl_(min,max) [_$P(_$d=0)]
1199#define _Deref_ret_range_impl_(min,max) [returnvalue:_$R(_$d=0)]
1200
1201#define _Pre1_impl_(p1) [_$P(_$d=0)]
1202#define _Pre2_impl_(p1,p2) [_$P(_$d=0)]
1203#define _Pre3_impl_(p1,p2,p3) [_$P(_$d=0)]
1204
1205#define _Post1_impl_(p1) [_$P(_$d=0)]
1206#define _Post2_impl_(p1,p2) [_$P(_$d=0)]
1207#define _Post3_impl_(p1,p2,p3) [_$P(_$d=0)]
1208
1209#define _Ret1_impl_(p1) [returnvalue:_$R(_$d=0)]
1210#define _Ret2_impl_(p1,p2) [returnvalue:_$R(_$d=0)]
1211#define _Ret3_impl_(p1,p2,p3) [returnvalue:_$R(_$d=0)]
1212
1213#define _Deref_pre1_impl_(p1) [_$P(_$d=0)]
1214#define _Deref_pre2_impl_(p1,p2) [_$P(_$d=0)]
1215#define _Deref_pre3_impl_(p1,p2,p3) [_$P(_$d=0)]
1216
1217#define _Deref_post1_impl_(p1) [_$P(_$d=0)]
1218#define _Deref_post2_impl_(p1,p2) [_$P(_$d=0)]
1219#define _Deref_post3_impl_(p1,p2,p3) [_$P(_$d=0)]
1220
1221#define _Deref_ret1_impl_(p1) [returnvalue:_$R(_$d=0)]
1222#define _Deref_ret2_impl_(p1,p2) [returnvalue:_$R(_$d=0)]
1223#define _Deref_ret3_impl_(p1,p2,p3) [returnvalue:_$R(_$d=0)]
1224
1225#define _Deref2_pre1_impl_(p1) //[_$P(_$d=0)]
1226#define _Deref2_post1_impl_(p1) //[_$P(_$d=0)]
1227#define _Deref2_ret1_impl_(p1) //[_$P(_$d=0)]
1228
1229#else
1230
1231#define _Check_return_impl_
1232
1233#define _Success_impl_(expr)
1234
1235#define _Printf_format_string_impl_
1236#define _Scanf_format_string_impl_
1237#define _Scanf_s_format_string_impl_
1238
1239#define _In_bound_impl_
1240#define _Out_bound_impl_
1241#define _Ret_bound_impl_
1242#define _Deref_in_bound_impl_
1243#define _Deref_out_bound_impl_
1244#define _Deref_ret_bound_impl_
1245
1246#define _In_range_impl_(min,max)
1247#define _Out_range_impl_(min,max)
1248#define _Ret_range_impl_(min,max)
1249#define _Deref_in_range_impl_(min,max)
1250#define _Deref_out_range_impl_(min,max)
1251#define _Deref_ret_range_impl_(min,max)
1252
1253#define _Pre1_impl_(p1)
1254#define _Pre2_impl_(p1,p2)
1255#define _Pre3_impl_(p1,p2,p3)
1256
1257#define _Post1_impl_(p1)
1258#define _Post2_impl_(p1,p2)
1259#define _Post3_impl_(p1,p2,p3)
1260
1261#define _Ret1_impl_(p1)
1262#define _Ret2_impl_(p1,p2)
1263#define _Ret3_impl_(p1,p2,p3)
1264
1265#define _Deref_pre1_impl_(p1)
1266#define _Deref_pre2_impl_(p1,p2)
1267#define _Deref_pre3_impl_(p1,p2,p3)
1268
1269#define _Deref_post1_impl_(p1)
1270#define _Deref_post2_impl_(p1,p2)
1271#define _Deref_post3_impl_(p1,p2,p3)
1272
1273#define _Deref_ret1_impl_(p1)
1274#define _Deref_ret2_impl_(p1,p2)
1275#define _Deref_ret3_impl_(p1,p2,p3)
1276
1277#define _Deref2_pre1_impl_(p1)
1278#define _Deref2_post1_impl_(p1)
1279#define _Deref2_ret1_impl_(p1)
1280
1281#endif
1282
1283// This section contains the deprecated annotations
1284
1285/*
1286 -------------------------------------------------------------------------------
1287 Introduction
1288
1289 sal.h provides a set of annotations to describe how a function uses its
1290 parameters - the assumptions it makes about them, and the guarantees it makes
1291 upon finishing.
1292
1293 Annotations may be placed before either a function parameter's type or its return
1294 type, and describe the function's behavior regarding the parameter or return value.
1295 There are two classes of annotations: buffer annotations and advanced annotations.
1296 Buffer annotations describe how functions use their pointer parameters, and
1297 advanced annotations either describe complex/unusual buffer behavior, or provide
1298 additional information about a parameter that is not otherwise expressible.
1299
1300 -------------------------------------------------------------------------------
1301 Buffer Annotations
1302
1303 The most important annotations in sal.h provide a consistent way to annotate
1304 buffer parameters or return values for a function. Each of these annotations describes
1305 a single buffer (which could be a string, a fixed-length or variable-length array,
1306 or just a pointer) that the function interacts with: where it is, how large it is,
1307 how much is initialized, and what the function does with it.
1308
1309 The appropriate macro for a given buffer can be constructed using the table below.
1310 Just pick the appropriate values from each category, and combine them together
1311 with a leading underscore. Some combinations of values do not make sense as buffer
1312 annotations. Only meaningful annotations can be added to your code; for a list of
1313 these, see the buffer annotation definitions section.
1314
1315 Only a single buffer annotation should be used for each parameter.
1316
1317 |------------|------------|---------|--------|----------|----------|---------------|
1318 | Level | Usage | Size | Output | NullTerm | Optional | Parameters |
1319 |------------|------------|---------|--------|----------|----------|---------------|
1320 | <> | <> | <> | <> | _z | <> | <> |
1321 | _deref | _in | _ecount | _full | _nz | _opt | (size) |
1322 | _deref_opt | _out | _bcount | _part | | | (size,length) |
1323 | | _inout | | | | | |
1324 | | | | | | | |
1325 |------------|------------|---------|--------|----------|----------|---------------|
1326
1327 Level: Describes the buffer pointer's level of indirection from the parameter or
1328 return value 'p'.
1329
1330 <> : p is the buffer pointer.
1331 _deref : *p is the buffer pointer. p must not be NULL.
1332 _deref_opt : *p may be the buffer pointer. p may be NULL, in which case the rest of
1333 the annotation is ignored.
1334
1335 Usage: Describes how the function uses the buffer.
1336
1337 <> : The buffer is not accessed. If used on the return value or with _deref, the
1338 function will provide the buffer, and it will be uninitialized at exit.
1339 Otherwise, the caller must provide the buffer. This should only be used
1340 for alloc and free functions.
1341 _in : The function will only read from the buffer. The caller must provide the
1342 buffer and initialize it. Cannot be used with _deref.
1343 _out : The function will only write to the buffer. If used on the return value or
1344 with _deref, the function will provide the buffer and initialize it.
1345 Otherwise, the caller must provide the buffer, and the function will
1346 initialize it.
1347 _inout : The function may freely read from and write to the buffer. The caller must
1348 provide the buffer and initialize it. If used with _deref, the buffer may
1349 be reallocated by the function.
1350
1351 Size: Describes the total size of the buffer. This may be less than the space actually
1352 allocated for the buffer, in which case it describes the accessible amount.
1353
1354 <> : No buffer size is given. If the type specifies the buffer size (such as
1355 with LPSTR and LPWSTR), that amount is used. Otherwise, the buffer is one
1356 element long. Must be used with _in, _out, or _inout.
1357 _ecount : The buffer size is an explicit element count.
1358 _bcount : The buffer size is an explicit byte count.
1359
1360 Output: Describes how much of the buffer will be initialized by the function. For
1361 _inout buffers, this also describes how much is initialized at entry. Omit this
1362 category for _in buffers; they must be fully initialized by the caller.
1363
1364 <> : The type specifies how much is initialized. For instance, a function initializing
1365 an LPWSTR must NULL-terminate the string.
1366 _full : The function initializes the entire buffer.
1367 _part : The function initializes part of the buffer, and explicitly indicates how much.
1368
1369 NullTerm: States if the present of a '\0' marks the end of valid elements in the buffer.
1370 _z : A '\0' indicated the end of the buffer
1371 _nz : The buffer may not be null terminated and a '\0' does not indicate the end of the
1372 buffer.
1373 Optional: Describes if the buffer itself is optional.
1374
1375 <> : The pointer to the buffer must not be NULL.
1376 _opt : The pointer to the buffer might be NULL. It will be checked before being dereferenced.
1377
1378 Parameters: Gives explicit counts for the size and length of the buffer.
1379
1380 <> : There is no explicit count. Use when neither _ecount nor _bcount is used.
1381 (size) : Only the buffer's total size is given. Use with _ecount or _bcount but not _part.
1382 (size,length) : The buffer's total size and initialized length are given. Use with _ecount_part
1383 and _bcount_part.
1384
1385 -------------------------------------------------------------------------------
1386 Buffer Annotation Examples
1387
1388 LWSTDAPI_(BOOL) StrToIntExA(
1389 LPCSTR pszString, -- No annotation required, const implies __in.
1390 DWORD dwFlags,
1391 __out int *piRet -- A pointer whose dereference will be filled in.
1392 );
1393
1394 void MyPaintingFunction(
1395 __in HWND hwndControl, -- An initialized read-only parameter.
1396 __in_opt HDC hdcOptional, -- An initialized read-only parameter that might be NULL.
1397 __inout IPropertyStore *ppsStore -- An initialized parameter that may be freely used
1398 -- and modified.
1399 );
1400
1401 LWSTDAPI_(BOOL) PathCompactPathExA(
1402 __out_ecount(cchMax) LPSTR pszOut, -- A string buffer with cch elements that will
1403 -- be NULL terminated on exit.
1404 LPCSTR pszSrc, -- No annotation required, const implies __in.
1405 UINT cchMax,
1406 DWORD dwFlags
1407 );
1408
1409 HRESULT SHLocalAllocBytes(
1410 size_t cb,
1411 __deref_bcount(cb) T **ppv -- A pointer whose dereference will be set to an
1412 -- uninitialized buffer with cb bytes.
1413 );
1414
1415 __inout_bcount_full(cb) : A buffer with cb elements that is fully initialized at
1416 entry and exit, and may be written to by this function.
1417
1418 __out_ecount_part(count, *countOut) : A buffer with count elements that will be
1419 partially initialized by this function. The function indicates how much it
1420 initialized by setting *countOut.
1421
1422 -------------------------------------------------------------------------------
1423 Advanced Annotations
1424
1425 Advanced annotations describe behavior that is not expressible with the regular
1426 buffer macros. These may be used either to annotate buffer parameters that involve
1427 complex or conditional behavior, or to enrich existing annotations with additional
1428 information.
1429
1430 __success(expr) f :
1431 <expr> indicates whether function f succeeded or not. If <expr> is true at exit,
1432 all the function's guarantees (as given by other annotations) must hold. If <expr>
1433 is false at exit, the caller should not expect any of the function's guarantees
1434 to hold. If not used, the function must always satisfy its guarantees. Added
1435 automatically to functions that indicate success in standard ways, such as by
1436 returning an HRESULT.
1437
1438 __nullterminated p :
1439 Pointer p is a buffer that may be read or written up to and including the first
1440 NULL character or pointer. May be used on typedefs, which marks valid (properly
1441 initialized) instances of that type as being NULL-terminated.
1442
1443 __nullnullterminated p :
1444 Pointer p is a buffer that may be read or written up to and including the first
1445 sequence of two NULL characters or pointers. May be used on typedefs, which marks
1446 valid instances of that type as being double-NULL terminated.
1447
1448 __reserved v :
1449 Value v must be 0/NULL, reserved for future use.
1450
1451 __checkReturn v :
1452 Return value v must not be ignored by callers of this function.
1453
1454 __typefix(ctype) v :
1455 Value v should be treated as an instance of ctype, rather than its declared type.
1456
1457 __override f :
1458 Specify C#-style 'override' behaviour for overriding virtual methods.
1459
1460 __callback f :
1461 Function f can be used as a function pointer.
1462
1463 __format_string p :
1464 Pointer p is a string that contains % markers in the style of printf.
1465
1466 __blocksOn(resource) f :
1467 Function f blocks on the resource 'resource'.
1468
1469 __fallthrough :
1470 Annotates switch statement labels where fall-through is desired, to distinguish
1471 from forgotten break statements.
1472
1473 -------------------------------------------------------------------------------
1474 Advanced Annotation Examples
1475
1476 __success(return == TRUE) LWSTDAPI_(BOOL)
1477 PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath) :
1478 pszBuf is only guaranteed to be NULL-terminated when TRUE is returned.
1479
1480 typedef __nullterminated WCHAR* LPWSTR : Initialized LPWSTRs are NULL-terminated strings.
1481
1482 __out_ecount(cch) __typefix(LPWSTR) void *psz : psz is a buffer parameter which will be
1483 a NULL-terminated WCHAR string at exit, and which initially contains cch WCHARs.
1484
1485 -------------------------------------------------------------------------------
1486*/
1487
1488#define __specstrings
1489
1490#ifdef __cplusplus
1491#ifndef __nothrow
1492# define __nothrow __declspec(nothrow)
1493#endif
1494extern "C" {
1495#else
1496#ifndef __nothrow
1497# define __nothrow
1498#endif
1499#endif /* #ifdef __cplusplus */
1500
1501
1502/*
1503 -------------------------------------------------------------------------------
1504 Helper Macro Definitions
1505
1506 These express behavior common to many of the high-level annotations.
1507 DO NOT USE THESE IN YOUR CODE.
1508 -------------------------------------------------------------------------------
1509*/
1510
1511/*
1512The helper annotations are only understood by the compiler version used by various
1513defect detection tools. When the regular compiler is running, they are defined into
1514nothing, and do not affect the compiled code.
1515*/
1516
1517#if !defined(__midl) && defined(_PREFAST_)
1518
1519 /*
1520 In the primitive __declspec("SAL_*") annotations "SAL" stands for Standard
1521 Annotation Language. These __declspec("SAL_*") annotations are the
1522 primitives the compiler understands and all high-level SpecString MACROs
1523 will decompose into these primivates.
1524 */
1525
1526 #define SPECSTRINGIZE( x ) #x
1527
1528 /*
1529 __null p
1530 __notnull p
1531 __maybenull p
1532
1533 Annotates a pointer p. States that pointer p is null. Commonly used
1534 in the negated form __notnull or the possibly null form __maybenull.
1535 */
1536
1537 #define __null __declspec("SAL_null")
1538 #define __notnull __declspec("SAL_notnull")
1539 #define __maybenull __declspec("SAL_maybenull")
1540
1541 /*
1542 __readonly l
1543 __notreadonly l
1544 __mabyereadonly l
1545
1546 Annotates a location l. States that location l is not modified after
1547 this point. If the annotation is placed on the precondition state of
1548 a function, the restriction only applies until the postcondition state
1549 of the function. __maybereadonly states that the annotated location
1550 may be modified, whereas __notreadonly states that a location must be
1551 modified.
1552 */
1553
1554 #define __readonly __declspec("SAL_readonly")
1555 #define __notreadonly __declspec("SAL_notreadonly")
1556 #define __maybereadonly __declspec("SAL_maybereadonly")
1557
1558 /*
1559 __valid v
1560 __notvalid v
1561 __maybevalid v
1562
1563 Annotates any value v. States that the value satisfies all properties of
1564 valid values of its type. For example, for a string buffer, valid means
1565 that the buffer pointer is either NULL or points to a NULL-terminated string.
1566 */
1567
1568 #define __valid __declspec("SAL_valid")
1569 #define __notvalid __declspec("SAL_notvalid")
1570 #define __maybevalid __declspec("SAL_maybevalid")
1571
1572 /*
1573 __readableTo(extent) p
1574
1575 Annotates a buffer pointer p. If the buffer can be read, extent describes
1576 how much of the buffer is readable. For a reader of the buffer, this is
1577 an explicit permission to read up to that amount, rather than a restriction to
1578 read only up to it.
1579 */
1580
1581 #define __readableTo(extent) __declspec("SAL_readableTo("SPECSTRINGIZE(extent)")")
1582
1583 /*
1584
1585 __elem_readableTo(size)
1586
1587 Annotates a buffer pointer p as being readable to size elements.
1588 */
1589
1590 #define __elem_readableTo(size) __declspec("SAL_readableTo(elementCount("SPECSTRINGIZE(size)"))")
1591
1592 /*
1593 __byte_readableTo(size)
1594
1595 Annotates a buffer pointer p as being readable to size bytes.
1596 */
1597 #define __byte_readableTo(size) __declspec("SAL_readableTo(byteCount("SPECSTRINGIZE(size)"))")
1598
1599 /*
1600 __writableTo(extent) p
1601
1602 Annotates a buffer pointer p. If the buffer can be modified, extent
1603 describes how much of the buffer is writable (usually the allocation
1604 size). For a writer of the buffer, this is an explicit permission to
1605 write up to that amount, rather than a restriction to write only up to it.
1606 */
1607 #define __writableTo(size) __declspec("SAL_writableTo("SPECSTRINGIZE(size)")")
1608
1609 /*
1610 __elem_writableTo(size)
1611
1612 Annotates a buffer pointer p as being writable to size elements.
1613 */
1614 #define __elem_writableTo(size) __declspec("SAL_writableTo(elementCount("SPECSTRINGIZE(size)"))")
1615
1616 /*
1617 __byte_writableTo(size)
1618
1619 Annotates a buffer pointer p as being writable to size bytes.
1620 */
1621 #define __byte_writableTo(size) __declspec("SAL_writableTo(byteCount("SPECSTRINGIZE(size)"))")
1622
1623 /*
1624 __deref p
1625
1626 Annotates a pointer p. The next annotation applies one dereference down
1627 in the type. If readableTo(p, size) then the next annotation applies to
1628 all elements *(p+i) for which i satisfies the size. If p is a pointer
1629 to a struct, the next annotation applies to all fields of the struct.
1630 */
1631 #define __deref __declspec("SAL_deref")
1632
1633 /*
1634 __pre __next_annotation
1635
1636 The next annotation applies in the precondition state
1637 */
1638 #define __pre __declspec("SAL_pre")
1639
1640 /*
1641 __post __next_annotation
1642
1643 The next annotation applies in the postcondition state
1644 */
1645 #define __post __declspec("SAL_post")
1646
1647 /*
1648 __precond(<expr>)
1649
1650 When <expr> is true, the next annotation applies in the precondition state
1651 (currently not enabled)
1652 */
1653 #define __precond(expr) __pre
1654
1655 /*
1656 __postcond(<expr>)
1657
1658 When <expr> is true, the next annotation applies in the postcondition state
1659 (currently not enabled)
1660 */
1661 #define __postcond(expr) __post
1662
1663 /*
1664 __exceptthat
1665
1666 Given a set of annotations Q containing __exceptthat maybeP, the effect of
1667 the except clause is to erase any P or notP annotations (explicit or
1668 implied) within Q at the same level of dereferencing that the except
1669 clause appears, and to replace it with maybeP.
1670
1671 Example 1: __valid __exceptthat __maybenull on a pointer p means that the
1672 pointer may be null, and is otherwise valid, thus overriding
1673 the implicit notnull annotation implied by __valid on
1674 pointers.
1675
1676 Example 2: __valid __deref __exceptthat __maybenull on an int **p means
1677 that p is not null (implied by valid), but the elements
1678 pointed to by p could be null, and are otherwise valid.
1679 */
1680 #define __exceptthat __declspec("SAL_except")
1681 #define __execeptthat __exceptthat
1682
1683 /*
1684 _refparam
1685
1686 Added to all out parameter macros to indicate that they are all reference
1687 parameters.
1688 */
1689 #define __refparam __deref __notreadonly
1690
1691 /*
1692 __inner_*
1693
1694 Helper macros that directly correspond to certain high-level annotations.
1695
1696 */
1697
1698 /*
1699 Macros to classify the entrypoints and indicate their category.
1700
1701 Pre-defined control point categories include: RPC, LPC, DeviceDriver, UserToKernel, ISAPI, COM.
1702
1703 */
1704 #define __inner_control_entrypoint(category) __declspec("SAL_entrypoint(controlEntry, "SPECSTRINGIZE(category)")")
1705
1706 /*
1707 Pre-defined data entry point categories include: Registry, File, Network.
1708 */
1709 #define __inner_data_entrypoint(category) __declspec("SAL_entrypoint(dataEntry, "SPECSTRINGIZE(category)")")
1710
1711 #define __inner_success(expr) __declspec("SAL_success("SPECSTRINGIZE(expr)")")
1712 #define __inner_checkReturn __declspec("SAL_checkReturn")
1713 #define __inner_typefix(ctype) __declspec("SAL_typefix("SPECSTRINGIZE(ctype)")")
1714 #define __inner_override __declspec("__override")
1715 #define __inner_callback __declspec("__callback")
1716 #define __inner_blocksOn(resource) __declspec("SAL_blocksOn("SPECSTRINGIZE(resource)")")
1717 #define __inner_fallthrough_dec __inline __nothrow void __FallThrough() {}
1718 #define __inner_fallthrough __FallThrough();
1719
1720#else
1721 #define __null
1722 #define __notnull
1723 #define __maybenull
1724 #define __readonly
1725 #define __notreadonly
1726 #define __maybereadonly
1727 #define __valid
1728 #define __notvalid
1729 #define __maybevalid
1730 #define __readableTo(extent)
1731 #define __elem_readableTo(size)
1732 #define __byte_readableTo(size)
1733 #define __writableTo(size)
1734 #define __elem_writableTo(size)
1735 #define __byte_writableTo(size)
1736 #define __deref
1737 #define __pre
1738 #define __post
1739 #define __precond(expr)
1740 #define __postcond(expr)
1741 #define __exceptthat
1742 #define __execeptthat
1743 #define __inner_success(expr)
1744 #define __inner_checkReturn
1745 #define __inner_typefix(ctype)
1746 #define __inner_override
1747 #define __inner_callback
1748 #define __inner_blocksOn(resource)
1749 #define __inner_fallthrough_dec
1750 #define __inner_fallthrough
1751 #define __refparam
1752 #define __inner_control_entrypoint(category)
1753 #define __inner_data_entrypoint(category)
1754#endif /* #if !defined(__midl) && defined(_PREFAST_) */
1755
1756/*
1757-------------------------------------------------------------------------------
1758Buffer Annotation Definitions
1759
1760Any of these may be used to directly annotate functions, but only one should
1761be used for each parameter. To determine which annotation to use for a given
1762buffer, use the table in the buffer annotations section.
1763-------------------------------------------------------------------------------
1764*/
1765
1766#define __ecount(size) __notnull __elem_writableTo(size)
1767#define __bcount(size) __notnull __byte_writableTo(size)
1768#define __in __pre __valid __pre __deref __readonly
1769#define __in_ecount(size) __in __pre __elem_readableTo(size)
1770#define __in_bcount(size) __in __pre __byte_readableTo(size)
1771#define __in_z __in __pre __nullterminated
1772#define __in_ecount_z(size) __in_ecount(size) __pre __nullterminated
1773#define __in_bcount_z(size) __in_bcount(size) __pre __nullterminated
1774#define __in_nz __in
1775#define __in_ecount_nz(size) __in_ecount(size)
1776#define __in_bcount_nz(size) __in_bcount(size)
1777#define __out __ecount(1) __post __valid __refparam
1778#define __out_ecount(size) __ecount(size) __post __valid __refparam
1779#define __out_bcount(size) __bcount(size) __post __valid __refparam
1780#define __out_ecount_part(size,length) __out_ecount(size) __post __elem_readableTo(length)
1781#define __out_bcount_part(size,length) __out_bcount(size) __post __byte_readableTo(length)
1782#define __out_ecount_full(size) __out_ecount_part(size,size)
1783#define __out_bcount_full(size) __out_bcount_part(size,size)
1784#define __out_z __post __valid __refparam __post __nullterminated
1785#define __out_z_opt __post __valid __refparam __post __nullterminated __exceptthat __maybenull
1786#define __out_ecount_z(size) __ecount(size) __post __valid __refparam __post __nullterminated
1787#define __out_bcount_z(size) __bcount(size) __post __valid __refparam __post __nullterminated
1788#define __out_ecount_part_z(size,length) __out_ecount_part(size,length) __post __nullterminated
1789#define __out_bcount_part_z(size,length) __out_bcount_part(size,length) __post __nullterminated
1790#define __out_ecount_full_z(size) __out_ecount_full(size) __post __nullterminated
1791#define __out_bcount_full_z(size) __out_bcount_full(size) __post __nullterminated
1792#define __out_nz __post __valid __refparam __post
1793#define __out_nz_opt __post __valid __refparam __post __exceptthat __maybenull
1794#define __out_ecount_nz(size) __ecount(size) __post __valid __refparam
1795#define __out_bcount_nz(size) __bcount(size) __post __valid __refparam
1796#define __inout __pre __valid __post __valid __refparam
1797#define __inout_ecount(size) __out_ecount(size) __pre __valid
1798#define __inout_bcount(size) __out_bcount(size) __pre __valid
1799#define __inout_ecount_part(size,length) __out_ecount_part(size,length) __pre __valid __pre __elem_readableTo(length)
1800#define __inout_bcount_part(size,length) __out_bcount_part(size,length) __pre __valid __pre __byte_readableTo(length)
1801#define __inout_ecount_full(size) __inout_ecount_part(size,size)
1802#define __inout_bcount_full(size) __inout_bcount_part(size,size)
1803#define __inout_z __inout __pre __nullterminated __post __nullterminated
1804#define __inout_ecount_z(size) __inout_ecount(size) __pre __nullterminated __post __nullterminated
1805#define __inout_bcount_z(size) __inout_bcount(size) __pre __nullterminated __post __nullterminated
1806#define __inout_nz __inout
1807#define __inout_ecount_nz(size) __inout_ecount(size)
1808#define __inout_bcount_nz(size) __inout_bcount(size)
1809#define __ecount_opt(size) __ecount(size) __exceptthat __maybenull
1810#define __bcount_opt(size) __bcount(size) __exceptthat __maybenull
1811#define __in_opt __in __exceptthat __maybenull
1812#define __in_ecount_opt(size) __in_ecount(size) __exceptthat __maybenull
1813#define __in_bcount_opt(size) __in_bcount(size) __exceptthat __maybenull
1814#define __in_z_opt __in_opt __pre __nullterminated
1815#define __in_ecount_z_opt(size) __in_ecount_opt(size) __pre __nullterminated
1816#define __in_bcount_z_opt(size) __in_bcount_opt(size) __pre __nullterminated
1817#define __in_nz_opt __in_opt
1818#define __in_ecount_nz_opt(size) __in_ecount_opt(size)
1819#define __in_bcount_nz_opt(size) __in_bcount_opt(size)
1820#define __out_opt __out __exceptthat __maybenull
1821#define __out_ecount_opt(size) __out_ecount(size) __exceptthat __maybenull
1822#define __out_bcount_opt(size) __out_bcount(size) __exceptthat __maybenull
1823#define __out_ecount_part_opt(size,length) __out_ecount_part(size,length) __exceptthat __maybenull
1824#define __out_bcount_part_opt(size,length) __out_bcount_part(size,length) __exceptthat __maybenull
1825#define __out_ecount_full_opt(size) __out_ecount_full(size) __exceptthat __maybenull
1826#define __out_bcount_full_opt(size) __out_bcount_full(size) __exceptthat __maybenull
1827#define __out_ecount_z_opt(size) __out_ecount_opt(size) __post __nullterminated
1828#define __out_bcount_z_opt(size) __out_bcount_opt(size) __post __nullterminated
1829#define __out_ecount_part_z_opt(size,length) __out_ecount_part_opt(size,length) __post __nullterminated
1830#define __out_bcount_part_z_opt(size,length) __out_bcount_part_opt(size,length) __post __nullterminated
1831#define __out_ecount_full_z_opt(size) __out_ecount_full_opt(size) __post __nullterminated
1832#define __out_bcount_full_z_opt(size) __out_bcount_full_opt(size) __post __nullterminated
1833#define __out_ecount_nz_opt(size) __out_ecount_opt(size) __post __nullterminated
1834#define __out_bcount_nz_opt(size) __out_bcount_opt(size) __post __nullterminated
1835#define __inout_opt __inout __exceptthat __maybenull
1836#define __inout_ecount_opt(size) __inout_ecount(size) __exceptthat __maybenull
1837#define __inout_bcount_opt(size) __inout_bcount(size) __exceptthat __maybenull
1838#define __inout_ecount_part_opt(size,length) __inout_ecount_part(size,length) __exceptthat __maybenull
1839#define __inout_bcount_part_opt(size,length) __inout_bcount_part(size,length) __exceptthat __maybenull
1840#define __inout_ecount_full_opt(size) __inout_ecount_full(size) __exceptthat __maybenull
1841#define __inout_bcount_full_opt(size) __inout_bcount_full(size) __exceptthat __maybenull
1842#define __inout_z_opt __inout_opt __pre __nullterminated __post __nullterminated
1843#define __inout_ecount_z_opt(size) __inout_ecount_opt(size) __pre __nullterminated __post __nullterminated
1844#define __inout_ecount_z_opt(size) __inout_ecount_opt(size) __pre __nullterminated __post __nullterminated
1845#define __inout_bcount_z_opt(size) __inout_bcount_opt(size)
1846#define __inout_nz_opt __inout_opt
1847#define __inout_ecount_nz_opt(size) __inout_ecount_opt(size)
1848#define __inout_bcount_nz_opt(size) __inout_bcount_opt(size)
1849#define __deref_ecount(size) __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __elem_writableTo(size)
1850#define __deref_bcount(size) __ecount(1) __post __elem_readableTo(1) __post __deref __notnull __post __deref __byte_writableTo(size)
1851#define __deref_out __deref_ecount(1) __post __deref __valid __refparam
1852#define __deref_out_ecount(size) __deref_ecount(size) __post __deref __valid __refparam
1853#define __deref_out_bcount(size) __deref_bcount(size) __post __deref __valid __refparam
1854#define __deref_out_ecount_part(size,length) __deref_out_ecount(size) __post __deref __elem_readableTo(length)
1855#define __deref_out_bcount_part(size,length) __deref_out_bcount(size) __post __deref __byte_readableTo(length)
1856#define __deref_out_ecount_full(size) __deref_out_ecount_part(size,size)
1857#define __deref_out_bcount_full(size) __deref_out_bcount_part(size,size)
1858#define __deref_out_z __post __deref __valid __refparam __post __deref __nullterminated
1859#define __deref_out_ecount_z(size) __deref_out_ecount(size) __post __deref __nullterminated
1860#define __deref_out_bcount_z(size) __deref_out_ecount(size) __post __deref __nullterminated
1861#define __deref_out_nz __deref_out
1862#define __deref_out_ecount_nz(size) __deref_out_ecount(size)
1863#define __deref_out_bcount_nz(size) __deref_out_ecount(size)
1864#define __deref_inout __notnull __elem_readableTo(1) __pre __deref __valid __post __deref __valid __refparam
1865#define __deref_inout_z __deref_inout __pre __deref __nullterminated __post __deref __nullterminated
1866#define __deref_inout_ecount(size) __deref_inout __pre __deref __elem_writableTo(size) __post __deref __elem_writableTo(size)
1867#define __deref_inout_bcount(size) __deref_inout __pre __deref __byte_writableTo(size) __post __deref __byte_writableTo(size)
1868#define __deref_inout_ecount_part(size,length) __deref_inout_ecount(size) __pre __deref __elem_readableTo(length) __post __deref __elem_readableTo(length)
1869#define __deref_inout_bcount_part(size,length) __deref_inout_bcount(size) __pre __deref __byte_readableTo(length) __post __deref __byte_readableTo(length)
1870#define __deref_inout_ecount_full(size) __deref_inout_ecount_part(size,size)
1871#define __deref_inout_bcount_full(size) __deref_inout_bcount_part(size,size)
1872#define __deref_inout_z __deref_inout __pre __deref __nullterminated __post __deref __nullterminated
1873#define __deref_inout_ecount_z(size) __deref_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated
1874#define __deref_inout_bcount_z(size) __deref_inout_bcount(size) __pre __deref __nullterminated __post __deref __nullterminated
1875#define __deref_inout_nz __deref_inout
1876#define __deref_inout_ecount_nz(size) __deref_inout_ecount(size)
1877#define __deref_inout_bcount_nz(size) __deref_inout_ecount(size)
1878#define __deref_ecount_opt(size) __deref_ecount(size) __post __deref __exceptthat __maybenull
1879#define __deref_bcount_opt(size) __deref_bcount(size) __post __deref __exceptthat __maybenull
1880#define __deref_out_opt __deref_out __post __deref __exceptthat __maybenull
1881#define __deref_out_ecount_opt(size) __deref_out_ecount(size) __post __deref __exceptthat __maybenull
1882#define __deref_out_bcount_opt(size) __deref_out_bcount(size) __post __deref __exceptthat __maybenull
1883#define __deref_out_ecount_part_opt(size,length) __deref_out_ecount_part(size,length) __post __deref __exceptthat __maybenull
1884#define __deref_out_bcount_part_opt(size,length) __deref_out_bcount_part(size,length) __post __deref __exceptthat __maybenull
1885#define __deref_out_ecount_full_opt(size) __deref_out_ecount_full(size) __post __deref __exceptthat __maybenull
1886#define __deref_out_bcount_full_opt(size) __deref_out_bcount_full(size) __post __deref __exceptthat __maybenull
1887#define __deref_out_z_opt __post __deref __valid __refparam __execeptthat __maybenull __post __deref __nullterminated
1888#define __deref_out_ecount_z_opt(size) __deref_out_ecount_opt(size) __post __deref __nullterminated
1889#define __deref_out_bcount_z_opt(size) __deref_out_bcount_opt(size) __post __deref __nullterminated
1890#define __deref_out_nz_opt __deref_out_opt
1891#define __deref_out_ecount_nz_opt(size) __deref_out_ecount_opt(size)
1892#define __deref_out_bcount_nz_opt(size) __deref_out_bcount_opt(size)
1893#define __deref_inout_opt __deref_inout __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
1894#define __deref_inout_ecount_opt(size) __deref_inout_ecount(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
1895#define __deref_inout_bcount_opt(size) __deref_inout_bcount(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
1896#define __deref_inout_ecount_part_opt(size,length) __deref_inout_ecount_part(size,length) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
1897#define __deref_inout_bcount_part_opt(size,length) __deref_inout_bcount_part(size,length) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
1898#define __deref_inout_ecount_full_opt(size) __deref_inout_ecount_full(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
1899#define __deref_inout_bcount_full_opt(size) __deref_inout_bcount_full(size) __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull
1900#define __deref_inout_z_opt __deref_inout_opt __pre __deref __nullterminated __post __deref __nullterminated
1901#define __deref_inout_ecount_z_opt(size) __deref_inout_ecount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated
1902#define __deref_inout_bcount_z_opt(size) __deref_inout_bcount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated
1903#define __deref_inout_nz_opt __deref_inout_opt
1904#define __deref_inout_ecount_nz_opt(size) __deref_inout_ecount_opt(size)
1905#define __deref_inout_bcount_nz_opt(size) __deref_inout_bcount_opt(size)
1906#define __deref_opt_ecount(size) __deref_ecount(size) __exceptthat __maybenull
1907#define __deref_opt_bcount(size) __deref_bcount(size) __exceptthat __maybenull
1908#define __deref_opt_out __deref_out __exceptthat __maybenull
1909#define __deref_opt_out_z __deref_opt_out __post __deref __nullterminated
1910#define __deref_opt_out_ecount(size) __deref_out_ecount(size) __exceptthat __maybenull
1911#define __deref_opt_out_bcount(size) __deref_out_bcount(size) __exceptthat __maybenull
1912#define __deref_opt_out_ecount_part(size,length) __deref_out_ecount_part(size,length) __exceptthat __maybenull
1913#define __deref_opt_out_bcount_part(size,length) __deref_out_bcount_part(size,length) __exceptthat __maybenull
1914#define __deref_opt_out_ecount_full(size) __deref_out_ecount_full(size) __exceptthat __maybenull
1915#define __deref_opt_out_bcount_full(size) __deref_out_bcount_full(size) __exceptthat __maybenull
1916#define __deref_opt_inout __deref_inout __exceptthat __maybenull
1917#define __deref_opt_inout_ecount(size) __deref_inout_ecount(size) __exceptthat __maybenull
1918#define __deref_opt_inout_bcount(size) __deref_inout_bcount(size) __exceptthat __maybenull
1919#define __deref_opt_inout_ecount_part(size,length) __deref_inout_ecount_part(size,length) __exceptthat __maybenull
1920#define __deref_opt_inout_bcount_part(size,length) __deref_inout_bcount_part(size,length) __exceptthat __maybenull
1921#define __deref_opt_inout_ecount_full(size) __deref_inout_ecount_full(size) __exceptthat __maybenull
1922#define __deref_opt_inout_bcount_full(size) __deref_inout_bcount_full(size) __exceptthat __maybenull
1923#define __deref_opt_inout_z __deref_opt_inout __pre __deref __nullterminated __post __deref __nullterminated
1924#define __deref_opt_inout_ecount_z(size) __deref_opt_inout_ecount(size) __pre __deref __nullterminated __post __deref __nullterminated
1925#define __deref_opt_inout_bcount_z(size) __deref_opt_inout_bcount(size) __pre __deref __nullterminated __post __deref __nullterminated
1926#define __deref_opt_inout_nz __deref_opt_inout
1927#define __deref_opt_inout_ecount_nz(size) __deref_opt_inout_ecount(size)
1928#define __deref_opt_inout_bcount_nz(size) __deref_opt_inout_bcount(size)
1929#define __deref_opt_ecount_opt(size) __deref_ecount_opt(size) __exceptthat __maybenull
1930#define __deref_opt_bcount_opt(size) __deref_bcount_opt(size) __exceptthat __maybenull
1931#define __deref_opt_out_opt __deref_out_opt __exceptthat __maybenull
1932#define __deref_opt_out_ecount_opt(size) __deref_out_ecount_opt(size) __exceptthat __maybenull
1933#define __deref_opt_out_bcount_opt(size) __deref_out_bcount_opt(size) __exceptthat __maybenull
1934#define __deref_opt_out_ecount_part_opt(size,length) __deref_out_ecount_part_opt(size,length) __exceptthat __maybenull
1935#define __deref_opt_out_bcount_part_opt(size,length) __deref_out_bcount_part_opt(size,length) __exceptthat __maybenull
1936#define __deref_opt_out_ecount_full_opt(size) __deref_out_ecount_full_opt(size) __exceptthat __maybenull
1937#define __deref_opt_out_bcount_full_opt(size) __deref_out_bcount_full_opt(size) __exceptthat __maybenull
1938#define __deref_opt_out_z_opt __post __deref __valid __refparam __exceptthat __maybenull __pre __deref __exceptthat __maybenull __post __deref __exceptthat __maybenull __post __deref __nullterminated
1939#define __deref_opt_out_ecount_z_opt(size) __deref_opt_out_ecount_opt(size) __post __deref __nullterminated
1940#define __deref_opt_out_bcount_z_opt(size) __deref_opt_out_bcount_opt(size) __post __deref __nullterminated
1941#define __deref_opt_out_nz_opt __deref_opt_out_opt
1942#define __deref_opt_out_ecount_nz_opt(size) __deref_opt_out_ecount_opt(size)
1943#define __deref_opt_out_bcount_nz_opt(size) __deref_opt_out_bcount_opt(size)
1944#define __deref_opt_inout_opt __deref_inout_opt __exceptthat __maybenull
1945#define __deref_opt_inout_ecount_opt(size) __deref_inout_ecount_opt(size) __exceptthat __maybenull
1946#define __deref_opt_inout_bcount_opt(size) __deref_inout_bcount_opt(size) __exceptthat __maybenull
1947#define __deref_opt_inout_ecount_part_opt(size,length) __deref_inout_ecount_part_opt(size,length) __exceptthat __maybenull
1948#define __deref_opt_inout_bcount_part_opt(size,length) __deref_inout_bcount_part_opt(size,length) __exceptthat __maybenull
1949#define __deref_opt_inout_ecount_full_opt(size) __deref_inout_ecount_full_opt(size) __exceptthat __maybenull
1950#define __deref_opt_inout_bcount_full_opt(size) __deref_inout_bcount_full_opt(size) __exceptthat __maybenull
1951#define __deref_opt_inout_z_opt __deref_opt_inout_opt __pre __deref __nullterminated __post __deref __nullterminated
1952#define __deref_opt_inout_ecount_z_opt(size) __deref_opt_inout_ecount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated
1953#define __deref_opt_inout_bcount_z_opt(size) __deref_opt_inout_bcount_opt(size) __pre __deref __nullterminated __post __deref __nullterminated
1954#define __deref_opt_inout_nz_opt __deref_opt_inout_opt
1955#define __deref_opt_inout_ecount_nz_opt(size) __deref_opt_inout_ecount_opt(size)
1956#define __deref_opt_inout_bcount_nz_opt(size) __deref_opt_inout_bcount_opt(size)
1957
1958/*
1959-------------------------------------------------------------------------------
1960Advanced Annotation Definitions
1961
1962Any of these may be used to directly annotate functions, and may be used in
1963combination with each other or with regular buffer macros. For an explanation
1964of each annotation, see the advanced annotations section.
1965-------------------------------------------------------------------------------
1966*/
1967
1968#define __success(expr) __inner_success(expr)
1969#define __nullterminated __readableTo(sentinel(0))
1970#define __nullnullterminated
1971#define __reserved __pre __null
1972#define __checkReturn __inner_checkReturn
1973#define __typefix(ctype) __inner_typefix(ctype)
1974#define __override __inner_override
1975#define __callback __inner_callback
1976#define __format_string
1977#define __blocksOn(resource) __inner_blocksOn(resource)
1978#define __control_entrypoint(category) __inner_control_entrypoint(category)
1979#define __data_entrypoint(category) __inner_data_entrypoint(category)
1980
1981#ifndef __fallthrough
1982 __inner_fallthrough_dec
1983 #define __fallthrough __inner_fallthrough
1984#endif
1985
1986#ifndef __analysis_assume
1987#ifdef _PREFAST_
1988#define __analysis_assume(expr) __assume(expr)
1989#else
1990#define __analysis_assume(expr)
1991#endif
1992#endif
1993
1994#ifdef __cplusplus
1995}
1996#endif
1997
1998