Поделиться через

Аннотирование поведения функции

  • Статья

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

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

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

Номер Description
_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, оно переопределит встроенное примечание.

Номер Description
_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_. Дополнительные сведения см. в разделе "Указание времени и места применения заметки".

См. также