Заметки заголовка
[В этом разделе описываются заметки, поддерживаемые заголовками 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 |
Размер буфера находится в элементах. |
| Направление | Описание |
|---|---|
|
_in |
Функция считывает из буфера. Вызывающий объект предоставляет буфер и инициализирует его. |
|
_inout |
Функция считывает данные и записывается в буфер. Вызывающий объект предоставляет буфер и инициализирует его. При использовании с _deref буфер может быть перераспределирован функцией. |
|
_out |
Функция записывается в буфер. Если используется для возвращаемого значения или с _deref, функция предоставляет буфер и инициализирует его. В противном случае вызывающий объект предоставляет буфер и инициализирует его. |
| Косвенность | Описание |
|---|---|
|
_deref |
Расшифровка параметра для получения указателя буфера. Этот параметр может не быть null. |
|
_deref_opt |
Расшифровка параметра для получения указателя буфера. Этот параметр может быть NULL. |
| Инициализация | Описание |
|---|---|
|
_full |
Функция инициализирует весь буфер. Используйте только с выходными буферами. |
|
_part |
Функция инициализирует часть буфера и явно указывает, сколько. Используйте только с выходными буферами. |
| Обязательный или необязательный буфер | Описание |
|---|---|
|
_opt |
Этот параметр может быть 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_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
Дополнительные заметки
Дополнительные заметки предоставляют дополнительные сведения о параметре или возвращаемом значении. Каждый параметр или возвращаемое значение может использовать ноль или одну расширенную заметку.
| Аннотация | Описание |
|---|---|
|
__blocksOn(ресурса) |
Блоки функций указанного ресурса. |
|
__callback |
Функцию можно использовать в качестве указателя функции. |
|
__checkReturn |
Вызывающие должны проверить возвращаемое значение. |
|
__format_string |
Параметр — это строка, содержащая маркеры стиля печати %. |
|
__in_awcount(экспр,размер) |
Если выражение имеет значение true при выходе, размер входного буфера указывается в байтах. Если выражение равно false, размер указывается в элементах. |
|
__nullnullterminated |
К буферу можно получить доступ до первой последовательности двух null символов или указателей. |
|
__nullterminated |
К буферу можно получить доступ до первого null символа или указателя. |
|
__out_awcount(экспр,размер) |
Если выражение имеет значение true при выходе, размер выходного буфера указывается в байтах. Если выражение равно false, размер указывается в элементах. |
|
__override |
Указывает поведение переопределения в стиле C#для виртуальных методов. |
|
__reserved |
Параметр зарезервирован для дальнейшего использования и должен быть равен нулю или 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
);