Заметки к заголовкам

  • Статья

[В этом разделе описываются заметки, поддерживаемые в заголовках Windows до Windows 7. При разработке для Windows 8 следует использовать заметки, описанные в статье Заметки SAL.]

Заметки заголовка описывают, как функция использует свои параметры и возвращаемое значение. Эти заметки были добавлены во многие файлы заголовков Windows, чтобы обеспечить правильный вызов API Windows. Если включить анализ кода, доступный начиная с Visual Studio 2005, компилятор выдаст предупреждения уровня 6000, если вы не вызываете эти функции в отношении использования, описанного в заметках. Вы также можете добавить эти заметки в собственный код, чтобы убедиться, что он вызывается правильно. Чтобы включить анализ кода в Visual Studio, ознакомьтесь с документацией по вашей версии Visual Studio.

Эти заметки определяются в Specstrings.h. Они основаны на примитивах, которые являются частью стандартного языка заметок (SAL) и реализуются с помощью _declspec("SAL_*").

Существует два класса заметок: заметки буфера и расширенные заметки.

Заметки буфера

Заметки буфера описывают, как функции используют свои указатели и могут использоваться для обнаружения переполнения буфера. Каждый параметр может использовать ноль или одну заметку буфера. Заметка буфера создается с символом подчеркивания в начале и компонентами, описанными в следующих разделах.

Размер буфера Описание
(размер)
 Указывает общий размер буфера. Использовать с _bcount и _ecount; не использовать с _part. Это значение является доступным пространством; оно может быть меньше выделенного пространства.
(размер, длина)
 Указывает общий размер и инициализированную длину буфера. Используйте с _bcount_part и _ecount_part. Общий размер может быть меньше выделенного пространства.
Единицы размера буфера Описание
_bcount
 Размер буфера — в байтах.
_ecount
 Размер буфера — в элементах .
Направление Описание
_В
 Функция считывает данные из буфера. Вызывающий объект предоставляет буфер и инициализирует его.
_Inout
 Функция считывает данные из буфера и записывает их в буфер. Вызывающий объект предоставляет буфер и инициализирует его. При использовании с _deref буфер может быть перераспределен функцией.
_out
 Функция записывает данные в буфер. Если используется для возвращаемого значения или с _deref, функция предоставляет буфер и инициализирует его. В противном случае вызывающий объект предоставляет буфер, а функция инициализирует его.
Косвенное обращение Описание
_deref
 Разыменуйте параметр, чтобы получить указатель буфера. Этот параметр может не иметь значение NULL.
_deref_opt
 Разыменуйте параметр, чтобы получить указатель буфера. Этот параметр может принимать значение NULL.
Инициализация Описание
_Полный
 Функция инициализирует весь буфер. Используйте только с буферами вывода.
_Часть
 Функция инициализирует часть буфера и явно указывает, сколько. Используйте только с буферами вывода.
Обязательный или необязательный буфер Описание
_Выбрать
 Этот параметр может принимать значение NULL.

В следующем примере показаны заметки для функции GetModuleFileName . Параметр hModule является необязательным входным параметром . Параметр lpFilename является выходным параметром; Его размер в символах задается параметром nSize , а его длина включает завершающий символ null. Параметр nSize является входным параметром.

DWORD
WINAPI
GetModuleFileName(
    __in_opt HMODULE hModule,
    __out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
    __in DWORD nSize
    );

Ниже приведены заметки, определенные в Specstrings.h. Используйте сведения в таблицах выше, чтобы интерпретировать их значение.

__bcount(размер)
__bcount_opt(размер)
__deref_bcount(размер)
__deref_bcount_opt(размер)
__deref_ecount(размер)
__deref_ecount_opt(размер)
__deref_in
__deref_in_bcount(размер)
__deref_in_bcount_opt(размер)
__deref_in_ecount(размер)
__deref_in_ecount_opt(размер)
__deref_in_opt
__deref_inout
__deref_inout_bcount(размер)
__deref_inout_bcount_full(размер)
__deref_inout_bcount_full_opt(размер)
__deref_inout_bcount_opt(размер)
__deref_inout_bcount_part(размер,длина)
__deref_inout_bcount_part_opt(размер,длина)
__deref_inout_ecount(размер)
__deref_inout_ecount_full(размер)
__deref_inout_ecount_full_opt(размер)
__deref_inout_ecount_opt(размер)
__deref_inout_ecount_part(размер,длина)
__deref_inout_ecount_part_opt(размер,длина)
__deref_inout_opt
__deref_opt_bcount(размер)
__deref_opt_bcount_opt(размер)
__deref_opt_ecount(размер)
__deref_opt_ecount_opt(размер)
__deref_opt_in
__deref_opt_in_bcount(размер)
__deref_opt_in_bcount_opt(размер)
__deref_opt_in_ecount(размер)
__deref_opt_in_ecount_opt(размер)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount(размер)
__deref_opt_inout_bcount_full(размер)
__deref_opt_inout_bcount_full_opt(размер)
__deref_opt_inout_bcount_opt(размер)
__deref_opt_inout_bcount_part(размер,длина)
__deref_opt_inout_bcount_part_opt(размер,длина)
__deref_opt_inout_ecount(размер)
__deref_opt_inout_ecount_full(размер)
__deref_opt_inout_ecount_full_opt(размер)
__deref_opt_inout_ecount_opt(размер)
__deref_opt_inout_ecount_part(размер,длина)
__deref_opt_inout_ecount_part_opt(размер,длина)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount(размер)
__deref_opt_out_bcount_full(размер)
__deref_opt_out_bcount_full_opt(размер)
__deref_opt_out_bcount_opt(размер)
__deref_opt_out_bcount_part(размер,длина)
__deref_opt_out_bcount_part_opt(размер,длина)
__deref_opt_out_ecount(размер)
__deref_opt_out_ecount_full(размер)
__deref_opt_out_ecount_full_opt(размер)
__deref_opt_out_ecount_opt(размер)
__deref_opt_out_ecount_part(размер,длина)
__deref_opt_out_ecount_part_opt(размер,длина)
__deref_opt_out_opt
__deref_out
__deref_out_bcount(размер)
__deref_out_bcount_full(размер)
__deref_out_bcount_full_opt(размер)
__deref_out_bcount_opt(размер)
__deref_out_bcount_part(размер,длина)
__deref_out_bcount_part_opt(размер,длина)
__deref_out_ecount(размер)
__deref_out_ecount_full(размер)
__deref_out_ecount_full_opt(размер)
__deref_out_ecount_opt(размер)
__deref_out_ecount_part(размер,длина)
__deref_out_ecount_part_opt(размер,длина)
__deref_out_opt
__ecount(размер)
__ecount_opt(размер)
__В
__in_bcount(размер)
__in_bcount_opt(размер)
__in_ecount(размер)
__in_ecount_opt(размер)
__in_opt
__Inout
__inout_bcount(размер)
__inout_bcount_full(размер)
__inout_bcount_full_opt(размер)
__inout_bcount_opt(размер)
__inout_bcount_part(размер,длина)
__inout_bcount_part_opt(размер,длина)
__inout_ecount(размер)
__inout_ecount_full(размер)
__inout_ecount_full_opt(размер)
__inout_ecount_opt(размер)
__inout_ecount_part(размер,длина)
__inout_ecount_part_opt(размер,длина)
__inout_opt
__out
__out_bcount(размер)
__out_bcount_full(размер)
__out_bcount_full_opt(размер)
__out_bcount_opt(размер)
__out_bcount_part(размер,длина)
__out_bcount_part_opt(размер,длина)
__out_ecount(размер)
__out_ecount_full(размер)
__out_ecount_full_opt(размер)
__out_ecount_opt(размер)
__out_ecount_part(размер,длина)
__out_ecount_part_opt(размер,длина)
__out_opt

Дополнительные заметки

Дополнительные заметки предоставляют дополнительные сведения о параметре или возвращаемом значении. Каждый параметр или возвращаемое значение может использовать ноль или одну расширенную заметку.

Annotation Описание
__blocksOn(ресурс)
 Функции блокируются для указанного ресурса.
__Обратного вызова
 Функцию можно использовать в качестве указателя функции.
__checkReturn
 Вызывающие должны проверка возвращаемое значение.
__format_string
 Параметр — это строка, содержащая маркеры % в стиле printf.
__in_awcount(expr,size)
 Если выражение имеет значение true при выходе, размер входного буфера указывается в байтах. Если выражение имеет значение false, размер указывается в элементах .
__nullnullterminated
 К буферу можно обращаться вплоть до первой последовательности двух символов NULL или указателей.
__nullterminated
 К буферу можно обращаться вплоть до первого символа NULL или указателя включительно.
__out_awcount(expr,size)
 Если выражение имеет значение true при выходе, размер выходного буфера указывается в байтах. Если выражение имеет значение false, размер указывается в элементах .
__Переопределить
 Задает поведение переопределения в стиле C# для виртуальных методов.
__Защищены
 Параметр зарезервирован для использования в будущем и должен иметь значение 0 или NULL.
__success(expr)
 Если выражение имеет значение true при выходе, вызывающий объект может полагаться на все гарантии, указанные в других заметках. Если выражение имеет значение false, вызывающий объект не может полагаться на гарантии. Эта заметка автоматически добавляется в функции, возвращающие значение HRESULT .
__typefix(ctype)
 Рассматривайте параметр как указанный тип, а не объявленный тип.

В следующих примерах показаны буферные и расширенные заметки для функций DeleteTimerQueueTimer, FreeEnvironmentStrings и UnhandledExceptionFilter .

__checkReturn
BOOL
WINAPI
DeleteTimerQueueTimer(
    __in_opt HANDLE TimerQueue,
    __in     HANDLE Timer,
    __in_opt HANDLE CompletionEvent
    );

BOOL
WINAPI
FreeEnvironmentStrings(
    __in __nullnullterminated LPTCH
    );

__callback
LONG
WINAPI
UnhandledExceptionFilter(
    __in struct _EXCEPTION_POINTERS *ExceptionInfo
    );

Заметки SAL

Пошаговое руководство. Проверка кода C/C++ на наличие дефектов