Аннотации параметров Windows SDK

Question

Мне интересно, важно ли использовать аннотации при разработке Windows на C ++?Например,

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

Это можно записать как:

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

Что я теряю, не используя их?Мне трудно понять, для чего они нужны, похоже, что для смертных не написано никаких руководств.

Answer 1

Вы должны работать с более старой версией SDK. Версия 7.0 объявляет аргументы так:

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

Обратите внимание на аннотацию __in_opt, она помечает аргумент как необязательный, указывая, что передача значения NULL является приемлемой. Это ранняя версия аннотаций SAL, аббревиатура от языка аннотаций исходного кода. Для них есть статья MSDN , однако она документирует синтаксис, который используется в файлах #include библиотеки C / C ++. Не совсем уверен, почему группа SDK не использует то же самое, они, как правило, немного медленные, чтобы наверстать упущенное.

За исключением возможности сделать объявления более читабельными, устранить неоднозначность объявлений C, аннотации также полезны для инструментов. Хорошим примером является Code Analyzer, встроенный в более высокие SKU для VS2008 и VS2010 (он улавливает ошибки программирования). И P / Invoke Interop Assistant, инструмент, который генерирует объявления C / или VB.NET p / invoke с использованием базы данных dbase, созданной из аннотированных заголовочных файлов SDK. Аннотации необходимы для создания хороших объявлений C #.

Вы также можете использовать эти аннотации в своем собственном коде, он будет автоматически проверен анализатором кода, если вы это сделаете. Используйте современный синтаксис, описанный в статье MSDN. Я думаю, что необходимый заголовок sal.h добавляется практически к любому исходному файлу, который включает в себя заголовки CRT.

Answer 2

IIRC, ключевые слова __in и __out равны #define d. Они там только для того, чтобы уточнить назначение каждого параметра. __in параметры предназначены для чтения функцией, но не изменяются, в то время как __out параметры предназначены для изменения функцией для передачи некоторого кода возврата.

Вы можете думать о __in как о идее C ++ «передать по const ссылке» или «передать по значению», а __out - как «передать по не const ссылке». Это не буквально, но это имеет то же значение.

Answer 3

Аннотации - это токены, добавляемые в исходный код (например, __in, __out и __inout), которые предоставляют разработчикам и инструментам статического анализа дополнительную информацию о функции, ее параметрах и их назначении.Аннотации похожи на комментарии, которые вы добавляете в свой код и игнорируются компилятором, но используются инструментами статического анализа.Использование аннотаций помогает повысить эффективность работы разработчиков, помогает повысить точность результатов статического анализа и позволяет инструментам лучше определить, существует ли конкретная ошибка.

Источник: http://msdn.microsoft.com/en-us/library/ff550230%28VS.85%29.aspx

О предмете WINAPI см. http://unixwiz.net/techtips/win32-callconv.html