What is the purpose of __in __out __in_opt __allowed(), how do they work? Should I use similar constructs in my own code?
https://stackoverflow.com/questions/4239809
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianQuestion
Some of these Preprocessor definitions are in the WinMain function and other windows library functions. What is their purpose? How do they work? and is it good practice to write them into your implementations or function calls?
My initial research suggests they're simply set up equlivalent to:
#define __in
#define __out
#define __in_opt
Meaning they get replaced with nothing on the Preprocessor pass. Are they just a documentation method, without any functionality?
If so, I can see the advantage to documenting the code in line like this. With something like doxygen you need to write out the parameter names twice. So this could in theory help reduce duplication, and maintain consistency...
I have no theory for how __allowed() is supposed to work.
Solution
They are SAL annotations in the Source-code Annotation Language. Microsoft tooling depends on it. The MSDN Library article is here. A good example is Code Analysis. Another quite unrelated tool, but empowered by these annotations is the Pinvoke Interop Assistant.
OTHER TIPS
SAL annotations are useful for two things:
- Static analysis through PREfast (compile with /analyze)
- Human readers can look at the annotations and figure out how a function should be called, and quickly determine the input/output parameters.
The macros do in fact expand to various declspec expressions when your code is compiled with analysis on. I use these annotations all the time in my code.
They're used in a Microsoft semantic analysis tool as code markups. Unless you plan on using this tool yourself, there's little purpose in using them.
These Microsoft macros generally expand to nothing, and are meant as hints to the reader.
However, last time I checked e.g. the hinting on the MessageBox arguments was completely wrong, hinting that first, second and third argument had useful defaults (when you specify 0), while in reality it's first and fourth argument that have useful defaults. Maybe also the title argument which defaults to "Error", but I've never found that useful. So, it's just a Microsoft thing, hints that you cannot and should not rely on, just misleading visual clutter.
Cheers & hth.,
