Anotar el comportamiento de funcionesAnnotating Function Behavior

Además de anotar parámetros de función y valores devueltos, puede anotar las propiedades de la función completa.In addition to annotating function parameters and return values, you can annotate properties of the whole function.

Anotaciones (función)Function Annotations

Las anotaciones siguientes se aplican a la función como un todo y describen cómo se comporta o lo que espera que se establezca en true.The following annotations apply to the function as a whole and describe how it behaves or what it expects to be true.

AnotaciónAnnotation DescripciónDescription
_Called_from_function_class_(name) No pretende ser independiente; en su lugar, es un predicado que se usará con el _When_ anotación.Not intended to stand alone; instead, it is a predicate to be used with the _When_ annotation. Para obtener más información, consulte especificar cuando y donde una anotación se aplica.For more information, see Specifying When and Where an Annotation Applies.

El name parámetro es una cadena arbitraria que también aparece en un _Function_class_ anotación en la declaración de algunas funciones.The name parameter is an arbitrary string that also appears in a _Function_class_ annotation in the declaration of some functions. _Called_from_function_class_Devuelve un valor distinto de cero si la función que se está analizando actualmente se anota utilizando _Function_class_ que tiene el mismo valor de name; en caso contrario, devuelve cero._Called_from_function_class_ returns nonzero if the function that is currently being analyzed is annotated by using _Function_class_ that has the same value of name; otherwise, it returns zero.
_Check_return_ Anota un valor devuelto y se indican que el llamador debe inspeccionar.Annotates a return value and states that the caller should inspect it. El Comprobador de notifica un error si se llama a la función en un contexto void.The checker reports an error if the function is called in a void context.
_Function_class_(name) El name parámetro es una cadena arbitraria que se haya designado por el usuario.The name parameter is an arbitrary string that is designated by the user. Se encuentra en un espacio de nombres que es distinto de otros espacios de nombres.It exists in a namespace that is distinct from other namespaces. Una función, puntero a función, o: forma más útil: un tipo de puntero de función se pueden designar como perteneciente a una o más clases de función.A function, function pointer, or—most usefully—a function pointer type may be designated as belonging to one or more function classes.
_Raises_SEH_exception_ Anota una función que siempre genera una excepción (SEH, el) controlador de excepciones estructurado, sujeto a _When_ y _On_failure_ condiciones.Annotates a function that always raises a structured exception handler (SEH) exception, subject to _When_ and _On_failure_ conditions. Para obtener más información, consulte especificar cuando y donde una anotación se aplica.For more information, see Specifying When and Where an Annotation Applies.
_Maybe_raises_SEH_exception_ Anota una función que, opcionalmente, se puede producir una excepción SEH, sujeto a _When_ y _On_failure_ condiciones.Annotates a function that may optionally raise an SEH exception, subject to _When_ and _On_failure_ conditions.
_Must_inspect_result_ Anota ningún valor de salida, incluido el valor devuelto, parámetros y variables globales.Annotates any output value, including the return value, parameters, and globals. El analizador informa de un error si no se ha inspeccionado posteriormente el valor en el objeto anotado.The analyzer reports an error if the value in the annotated object is not subsequently inspected. "Inspección" incluye si se utiliza en una expresión condicional, se asigna a un parámetro de salida o global o se pasa como un parámetro."Inspection" includes whether it is used in a conditional expression, is assigned to an output parameter or global, or is passed as a parameter. Para los valores devueltos, _Must_inspect_result_ implica _Check_return_.For return values, _Must_inspect_result_ implies _Check_return_.
_Use_decl_annotations_ Puede utilizarse en una definición de función (también conocido como el cuerpo de una función) en lugar de la lista de anotaciones en el encabezado.May be used on a function definition (also known as a function body) in place of the list of annotations in the header. Cuando _Use_decl_annotations_ es utilizado, se usan las anotaciones que aparecen en un encabezado en el ámbito de la misma función como si también están presentes en la definición que tiene el _Use_decl_annotations_ anotación.When _Use_decl_annotations_ is used, the annotations that appear on an in-scope header for the same function are used as if they are also present in the definition that has the _Use_decl_annotations_ annotation.

Anotaciones de correcto o con erroresSuccess/Failure Annotations

Una función puede producir un error, y cuando lo haga, sus resultados pueden estar incompletos o diferir de los resultados cuando la función se realiza correctamente.A function can fail, and when it does, its results may be incomplete or differ from the results when the function succeeds. Las anotaciones en la lista siguiente proporcionan maneras de expresar el comportamiento del error.The annotations in the following list provide ways to express the failure behavior. Para usar estas anotaciones, debe habilitarlas determinar el éxito; por lo tanto, un _Success_ anotación es necesaria.To use these annotations, you must enable them to determine success; therefore, a _Success_ annotation is required. Tenga en cuenta que NTSTATUS y HRESULT ya tiene un _Success_ anotación integrada; sin embargo, si especifica su propia _Success_ anotación en NTSTATUS o HRESULT, reemplaza la anotación integrada.Notice that NTSTATUS and HRESULT already have a _Success_ annotation built into them; however, if you specify your own _Success_ annotation on NTSTATUS or HRESULT, it overrides the built-in annotation.

AnotaciónAnnotation DescripciónDescription
_Always_(anno_list) Equivalente a anno_list _On_failure_(anno_list); es decir, las anotaciones en anno_list aplican independientemente de que la función se realiza correctamente o no.Equivalent to anno_list _On_failure_(anno_list); that is, the annotations in anno_list apply whether or not the function succeeds.
_On_failure_(anno_list) Para usarse solo cuando _Success_ también se utiliza para agregar anotaciones a la función, ya sea explícita o implícitamente a través de _Return_type_success_ en una definición de tipo.To be used only when _Success_ is also used to annotate the function—either explicitly, or implicitly through _Return_type_success_ on a typedef. Cuando el _On_failure_ anotación está presente en un valor devuelto o parámetro de valor de función, cada anotación en anno_list (anno) se comporta como si se codifica como _When_(!expr, anno), donde expr sea el parámetro requerido _Success_ anotación.When the _On_failure_ annotation is present on a function parameter or return value, each annotation in anno_list (anno) behaves as if it were coded as _When_(!expr, anno), where expr is the parameter to the required _Success_ annotation. Esto significa que la aplicación implícita de _Success_ a todas las condiciones posteriores no se aplica a _On_failure_.This means that the implied application of _Success_ to all post-conditions does not apply for _On_failure_.
_Return_type_success_(expr) Se puede aplicar a una definición de tipo.May be applied to a typedef. Indica que todas las funciones que devuelven que escriba y no tienen establecida explícitamente _Success_ se anotan como si tuvieran _Success_(expr).Indicates that all functions that return that type and do not explicitly have _Success_ are annotated as if they had _Success_(expr). _Return_type_success_no se puede usar en una función o una definición de tipo de puntero de función._Return_type_success_ cannot be used on a function or a function pointer typedef.
_Success_(expr) expres una expresión que da como resultado un valor r.expr is an expression that yields an rvalue. Cuando el _Success_ anotación está presente en una declaración de función o definiciones, cada anotación (anno) en la función y en la condición posterior a la que se comporta como si se codifica como _When_(expr, anno).When the _Success_ annotation is present on a function declaration or definition, each annotation (anno) on the function and in post-condition behaves as if it were coded as _When_(expr, anno). El _Success_ anotación puede usarse solo en una función, no en sus parámetros o tipo de valor devuelto.The _Success_ annotation may be used only on a function, not on its parameters or return type. Puede haber a lo sumo una _Success_ anotación en una función y no puede estar en cualquier _When_, _At_, o _Group_.There can be at most one _Success_ annotation on a function, and it cannot be in any _When_, _At_, or _Group_. Para obtener más información, consulte especificar cuando y donde una anotación se aplica.For more information, see Specifying When and Where an Annotation Applies.

Vea tambiénSee Also

Utilizar anotaciones SAL para reducir defectos de código de c/c ++ Using SAL Annotations to Reduce C/C++ Code Defects
Introducción a SAL Understanding SAL
Anotar parámetros de función y valores devueltos Annotating Function Parameters and Return Values
Anotar Structs y clases Annotating Structs and Classes
Anotar comportamiento de bloqueo Annotating Locking Behavior
Especificar cuándo y dónde se aplica una anotación Specifying When and Where an Annotation Applies
Funciones intrínsecas Intrinsic Functions
Procedimientos recomendados y ejemplosBest Practices and Examples