Anotaciones de parámetros de Windows SDK

Question

Me pregunto si es importante utilizar las anotaciones al hacer el desarrollo de Windows en C++. Por ejemplo,

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

Esto se puede escribir como:

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

Lo que estoy perdiendo por no usarlos? Estoy teniendo dificultades para descubrir para qué sirven, no parece haber guías escritas para los mortales.

Answer 1

Debe estar trabajando desde una versión anterior del SDK. Versión 7.0 declara los argumentos de esta manera:

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

Nota __in_opt la anotación, que marca el argumento como opcional, lo que indica que pasa NULL es aceptable. Estas son una versión temprana de las anotaciones SAL, un acrónimo para el Idioma de anotación del Código fuente. Hay un MSDN article para ellos, pero documenta la sintaxis que se usa en la biblioteca C/C++ #include archivos. No estoy seguro de por qué el grupo de SDK no usa el mismo, tienden a ser un poco lentos para ponerse al día.

Corto de hacer las declaraciones más legibles, eliminando la ambigüedad de las declaraciones C, las anotaciones también son útiles para las herramientas. Buenos ejemplos son el Analizador de código que está integrado en los SKU más altos para VS2008 y VS2010 (detecta errores de programación). Y el asistente P/Invoke Interop Assistant, una herramienta que genera declaraciones p/invoke de C# o VB.NET utilizando un dbase que se generó a partir de los archivos de encabezado del SDK anotado. Las anotaciones son esenciales para generar buenas declaraciones de C#.

También puede utilizar estas anotaciones en su propio código, que será verificado automáticamente por Code Analyser si lo hace. Utilice la sintaxis moderna tal como se documenta en el artículo de MSDN. Creo que el encabezado sal.h requerido se obtiene en casi cualquier archivo fuente que # incluya encabezados CRT.

Answer 2

anotaciones son fichas que se agregan a su código fuente (como __in, __out y __inout) que proporcionan a los desarrolladores y las herramientas de análisis estático con información adicional acerca de una función y sus parámetros, y su finalidad prevista. Las anotaciones son como comentarios que agrega a su código y el compilador los ignora, pero las herramientas de análisis estático los utilizan. El uso de anotaciones ayuda a mejorar la efectividad del desarrollador, ayuda a mejorar la precisión de los resultados del análisis estático y permite que las herramientas determinen mejor si existe una falla en particular.

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

Sobre la cosa WINAPI ver http://unixwiz.net/techtips/win32-callconv.html

Answer 3

IIRC, los __in y __out palabras clave son #define d para nada. Están allí solo para aclarar el propósito de cada parámetro. Los parámetros __in están diseñados para ser leídos por la función pero no modificados, mientras que los parámetros __out están diseñados para ser modificados por la función para comunicar algún código de retorno.

que se pueda imaginar __in como el C++ idea de "pasar por const de referencia" o "paso por valor" y __out como "el paso por referencia no const." Eso no es literalmente lo que significa, pero tiene la misma connotación.