Заметки к заголовкам
[В этом разделе описываются заметки, поддерживаемые в заголовках 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
);