Windows SDK parameter annotations

Question

I am wondering if its important to use the the annotations when doing Windows development in C++? For instance,

#include <windows.h>
int WINAPI WinMain(
    __in HINSTANCE hInstance,
    __in HINSTANCE hPrevInstance,
    __in LPSTR lpCmdLine,
    __in int nCmdShow
){
    return 0;
}

This can be written as:

#include <windows.h>
int WinMain(
    HINSTANCE hInstance,
    HINSTANCE hPrevInstance,
    LPSTR lpCmdLine,
    int nCmdShow
){
    return 0;
}

What am I losing by not using them? I am having a difficult time figuring out what these are for, there doesn't seem to be any guides written for mortals around.

Answer 1

You must be working from an older version of the SDK. Version 7.0 declares the arguments like this:

WinMain (
    __in HINSTANCE hInstance,
    __in_opt HINSTANCE hPrevInstance,
    __in LPSTR lpCmdLine,
    __in int nShowCmd
    );

Note the __in_opt annotation, it marks the argument as optional, indicating that passing NULL is acceptable. These are an early version of SAL annotations, an acronym for Source code Annotation Language. There's an MSDN article for them, it however documents the syntax that's used in the C/C++ library #include files. Not quite sure why the SDK group doesn't use the same, they tend to be a bit slow to catch up.

Short from making the declarations more readable, removing the ambiguity of C declarations, the annotations are also useful to tools. Good examples are the Code Analyzer that's built into the higher SKUs for VS2008 and VS2010 (it catches programming bugs). And the P/Invoke Interop Assistant, a tool that generates C# or VB.NET p/invoke declarations using a dbase that was generates from the annotated SDK header files. The annotations are essential to generate good C# declarations.

You can use these annotations in your own code as well, it will automatically be verified by the Code Analyzer if you do. Do use the modern syntax as documented in the MSDN article. I think the required sal.h header gets pulled in on just about any source file that #includes CRT headers.

Answer 2

Annotations are tokens that you add to your source code (such as __in, __out, and __inout) that provide developers and the static analysis tools with additional information about a function and its parameters, and their intended purpose. Annotations are like comments that you add to your code and are ignored by the compiler but are used by the static analysis tools. The use of annotations helps improve developer effectiveness, helps improve the accuracy of the results from static analysis, and allows the tools to better determine whether a particular bug exists.

Source: http://msdn.microsoft.com/en-us/library/ff550230%28VS.85%29.aspx

About the WINAPI thing see http://unixwiz.net/techtips/win32-callconv.html

Answer 3

IIRC, the __in and __out keywords are #defined to nothing. They're there solely to clarify the purpose of each parameter. __in parameters are designed to be read by the function but not modified, while __out parameters are designed to be modified by the function to communicate back some return code.

You can think of __in as the C++ idea of "pass by const reference" or "pass by value" and __out as "pass by non-const reference." That's not literally what it means, but it has the same connotation.