Anotación del comportamiento de funciones

  • Artículo

Además de anotar los parámetros de función y valores devueltos, puede anotar las propiedades de toda la función.

Anotaciones de función

Las siguientes anotaciones se aplican a la función en su conjunto y describen cómo se comporta o lo que espera que sea true.

Annotation Descripción
_Called_from_function_class_(name) No se pretende que sea independiente; en su lugar, es un predicado que se va a usar con la anotación _When_. Para más información, consulte Especificar cuándo y dónde se aplica una anotación.

El parámetro name es una cadena arbitraria que también aparece en una anotación _Function_class_ en la declaración de algunas funciones. _Called_from_function_class_ devuelve un valor distinto de cero si la función que se analiza actualmente se anota mediante _Function_class_ que tiene el mismo valor de name; de lo contrario, devuelve cero.
_Check_return_ Anota un valor devuelto e indica que el autor de la llamada debe inspeccionarlo. El comprobador notifica un error si se llama a la función en un contexto nulo.
_Function_class_(name) El parámetro name es una cadena arbitraria designada por el usuario. Existe en un espacio de nombres distinto de otros espacios de nombres. Una función, un puntero de función o, lo que resulta más útil, un tipo de puntero de función, se puede designar como perteneciente a una o varias clases de función.
_Raises_SEH_exception_ Anota una función que siempre genera una excepción del controlador de excepciones estructurado (SEH), sujeta a condiciones _When_ y _On_failure_. Para más información, consulte Especificar cuándo y dónde se aplica una anotación.
_Maybe_raises_SEH_exception_ Anota una función que puede generar opcionalmente una excepción SEH, sujeta a condiciones _When_ y _On_failure_.
_Must_inspect_result_ Anota cualquier valor de salida, incluidos el valor devuelto, los parámetros y los valores globales. El analizador notifica un error si el valor del objeto anotado no se inspecciona posteriormente. La "inspección" incluye si se usará en una expresión condicional, se asigna a un parámetro de salida o global, o se pasa como parámetro. Para los valores devueltos, _Must_inspect_result_ implica _Check_return_.
_Use_decl_annotations_ Se puede usar en una definición de función (también conocida como cuerpo de función) en lugar de la lista de anotaciones en el encabezado. Cuando se usa _Use_decl_annotations_, las anotaciones que aparecen en un encabezado en el ámbito para la misma función se usan como si también estuvieran presentes en la definición que tiene la anotación _Use_decl_annotations_.

Anotaciones de éxito o error

Una función puede no ejecutarse correctamente y, cuando esto sucede, sus resultados pueden estar incompletos o variar con respecto a los resultados de cuando la función se ejecuta correctamente. Las anotaciones de la lista siguiente proporcionan formas de expresar el comportamiento del error. Para usar estas anotaciones, debe habilitarlas para determinar el éxito; por lo tanto, se requiere una anotación _Success_. Observe que NTSTATUS y HRESULT ya tienen una anotación _Success_ integrada; sin embargo, si especifica su propia anotación _Success_ en NTSTATUS o HRESULT, se invalida la anotación integrada.

Annotation Descripción
_Always_(anno_list) Equivalente a anno_list _On_failure_(anno_list); es decir, las anotaciones de anno_list se aplican tanto si la función se realiza correctamente como si no.
_On_failure_(anno_list) Para usarse solo cuando también se usa _Success_ para anotar la función, ya sea explícita o implícitamente mediante _Return_type_success_ de en una definición de tipo. Cuando la anotación _On_failure_ existe en un parámetro de función o un valor devuelto, cada anotación de anno_list (anno) se comporta como si estuviera programada como _When_(!expr, anno), donde expr es el parámetro para la anotación _Success_ necesaria. Esto significa que la aplicación implícita de _Success_ a todas las condiciones posteriores no se aplica a _On_failure_.
_Return_type_success_(expr) Se puede aplicar a una definición de tipo. Indica que todas las funciones que devuelven ese tipo y que no tienen _Success_ explícitamente se anoten como si tuvieran _Success_(expr). _Return_type_success_ no se puede usar en una función o en una definición de tipo de puntero de función.
_Success_(expr) expr es una expresión que produce un valor rvalue. Cuando la anotación _Success_ existe en una definición o declaración de función, cada anotación (anno) de la función y en la condición posterior se comporta como si estuviera programada como _When_(expr, anno). La anotación _Success_ solo se puede usar en una función, no en sus parámetros ni en su tipo de valor devuelto. Puede haber como máximo una anotación _Success_ en una función y no puede estar en ningún elemento _When_, _At_ o _Group_. Para más información, consulte Especificar cuándo y dónde se aplica una anotación.

Consulte también