批注函数行为

除批注函数参数和返回值外,还可以批注整个函数的属性。

功能批注

下列批注适用于整个函数,并描述了其行为或预期。

Annotation 说明
_Called_from_function_class_(name) 不是为了单独存在;相反,它是一个旨在与 _When_ 批注一起使用的谓词。 有关详细信息,请参阅指定何时和何处应用批注

name 参数是一个任意字符串,该字符串也会出现在某些函数声明中的 _Function_class_ 注释中。 若当前正在分析的函数使用与 name 具有相同值的 _Function_class_ 进行批注,则 _Called_from_function_class_ 返回非零值;否则,返回零值。
_Check_return_ 批注一个返回值,并声明调用方应检查此值。 如果在 void 上下文中调用函数,则检查器将报告错误。
_Function_class_(name) name 参数为由用户指定的任意字符串。 它存在于与其他命名空间不同的命名空间中。 函数、函数指针或(最有用)函数指针类型可指定为属于一个或多个函数类。
_Raises_SEH_exception_ 根据 _When__On_failure_ 条件,批注始终引发结构化异常处理程序 (SEH) 异常的函数。 有关详细信息,请参阅指定何时和何处应用批注
_Maybe_raises_SEH_exception_ 根据 _When__On_failure_ 条件,批注可选择引发 SEH 异常的函数。
_Must_inspect_result_ 批注所有输出值,包括返回值、参数和全局值。 如果随后不检查批注对象中的值,则分析器将报告错误。 “检查”包括是否用于条件表达式,可分配给输出参数或全局,或作为参数传递。 对于返回值,_Must_inspect_result_ 暗指 _Check_return_
_Use_decl_annotations_ 可用于函数定义(也称为函数体),代替标头中的注释列表。 使用 _Use_decl_annotations_ 时,将使用出现在同一函数的范围内标头上的注释,就像它们也存在于具有 _Use_decl_annotations_ 注释的定义中一样。

成功/失败批注

函数可能会失败,此时,函数的结果可能不完整或与成功时的结果不同。 下面列表中的批注提供了表示失败行为的方法。 若要使用这些批注,您必须使它们能够确定成功;因此,需要 _Success_ 批注。 请注意,NTSTATUSHRESULT 已内置 _Success_ 批注;但是,如果对 _Success_NTSTATUS 指定自己的 HRESULT 批注,则它将重写内置批注。

Annotation 说明
_Always_(anno_list) 等效于 anno_list _On_failure_(anno_list);也就是说,无论函数是否成功,anno_list 中的批注都适用。
_On_failure_(anno_list) 仅当同时使用 _Success_ 来批注函数时使用,并通过 typedef 的 _Return_type_success_ 以显式或隐式方式使用。 当 _On_failure_ 批注位于函数参数或返回值上时,anno_list (anno) 中的每个批注的行为就像将其编码为 _When_(!expr, anno),其中,expr 是所需 _Success_ 批注的参数。 这意味着,_Success_ 到所有后置条件的隐含应用并不适用于 _On_failure_
_Return_type_success_(expr) 可以应用于 typedef。 表示将批注所有返回该类型并且不显式具有 _Success_ 的所有函数,就像它们具有 _Success_(expr)_Return_type_success_ 不能用于函数或函数指针类型。
_Success_(expr) expr 是生成右值的表达式。 当 _Success_ 批注位于函数声明或定义上时,函数上以及后置条件中的每个批注 (anno) 的行为就像它已编码为 _When_(expr, anno)_Success_ 批注只能用于函数,而不能用于函数的参数或返回类型。 一个函数上最多可以有一个 _Success_ 批注,并且不能位于任何 _When__At__Group_ 中。 有关详细信息,请参阅指定何时和何处应用批注

另请参阅