Поведение функции с заметками

  • Статья

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

Заметки к функциям

Следующие примечания применяются к функции в целом и описывают, как она работает и что должно выполняться.

Annotation Описание
_Called_from_function_class_(name) Не является автономной; это предикат, который должен использоваться с примечанием _When_. Дополнительные сведения см. в разделе Указание времени и места применения заметки.

Параметр name является произвольной строкой, которая также отображается в _Function_class_ заметке в объявлении некоторых функций. _Called_from_function_class_ возвращает ненулевое значение, если анализируемая функция аннотирована с помощью _Function_class_ , которая имеет то же значение name; в противном случае возвращается ноль.
_Check_return_ Примечает возвращаемое значение и указывает, что вызывающий объект должен проверить его. Средство проверки выдает ошибку, если функция вызывается в пустом контексте.
_Function_class_(name) Параметр name является произвольной строкой, указанной пользователем. Он существует в пространстве имен, отличном от других пространств имен. Функция, указатель на функцию или, что наиболее полезно, тип указателя на функцию могут быть обозначены как принадлежащие к одному или нескольким классам функции.
_Raises_SEH_exception_ Добавляет примечание к функции, которая всегда вызывает исключение структурированного обработчика исключений (SEH), при условии _When_ и _On_failure_. Дополнительные сведения см. в разделе Указание времени и места применения заметки.
_Maybe_raises_SEH_exception_ Добавляет примечание к функции, которая может при необходимости вызывать SЕH исключение, при условии _When_ и _On_failure_.
_Must_inspect_result_ Примечает любое выходное значение, включая возвращаемое значение, параметры и глобальные значения. Анализатор выдает ошибку, если значение в объекте, к которому добавлено примечание, далее не проверяется. "Проверка" инспектирует, используется ли он в условном выражении, присвоен ли он параметру вывода или глобальному параметру или передается ли он как параметр. Для возвращаемых значений _Must_inspect_result_ подразумевает _Check_return_.
_Use_decl_annotations_ Может использоваться в определении функции (также называемом телом функции) вместо списка заметок в заголовке. При _Use_decl_annotations_ использовании заметки, которые отображаются в область заголовке для той же функции, используются так, как если бы они также присутствовали в определении, которое содержит заметку_Use_decl_annotations_.

Заметки об успешном и неудачном выполнении

Функция может завершиться ошибкой. Когда это происходит, ее результаты могут быть неполными или могут отличаться от результатов в том случае, когда функция завершается успешно. Примечания в следующем списке предоставляют способы указания расширения функциональности при сбое. Чтобы использовать эти примечания, необходимо включить их для определения успешного завершения, поэтому требуется примечание _Success_. Следует заметить, что NTSTATUS и HRESULT уже содержат примечание _Success_, встроенное в них; однако, если указать собственное примечание _Success_ на NTSTATUS или HRESULT, оно переопределит встроенное примечание.

Annotation Описание
_Always_(anno_list) Эквивалентно anno_list _On_failure_(anno_list); примечания в anno_list применяются вне зависимости от того, завершилась функция успехом или нет.
_On_failure_(anno_list) Может использоваться только когда _Success_ также используется для добавления заметок к функции явно или неявно через _Return_type_success_ на typedef. Если примечание _On_failure_ присутствует в параметре функции или возвращаемом значении, каждое примечание в anno_list (anno) ведет себя так, как если бы оно было закодировано как _When_(!expr, anno), где expr является параметром для обязательного примечания _Success_. Это означает, что неявное приложение _Success_ ко всем постусловиям неприменимо для _On_failure_.
_Return_type_success_(expr) Может применяться к typedef. Указывает, что все функции, которые возвращают этот тип и явно не имеют _Success_, аннотированы, как если бы они имели _Success_(expr). _Return_type_success_ не может быть использован в функции или typedef указателя функции.
_Success_(expr) expr является выражением, которое предоставляет rvalue. Если примечание _Success_ присутствует в объявлении или определении функции, каждое примечание (anno) на функции и в постусловии ведет себя так, как если бы оно было закодировано как _When_(expr, anno). Примечание _Success_ может быть использовано только для функции, не для ее параметров или типа возвращаемого значения. На функции может быть не более одного примечания _Success_ и оно не может быть в _When_, _At_ или _Group_. Дополнительные сведения см. в разделе Указание времени и места применения заметки.

См. также раздел