Anotando o comportamento da função

  • Artigo

Além de anotar parâmetros de função e valores retornados, você pode anotar propriedades de toda a função.

Anotações de função

As anotações a seguir se aplicam à função como um todo e descrevem como ela se comporta ou o que ela espera que seja verdadeiro.

Anotação Descrição
_Called_from_function_class_(name) Não destinada a uso autônomo; em vez disso, é um predicado a ser usado com a anotação _When_. Para obter mais informações, confira Especificando quando e onde uma anotação se aplica.

O parâmetro name é uma cadeia de caracteres arbitrária que também aparece em uma anotação _Function_class_ na declaração de algumas funções. _Called_from_function_class_ retornará não zero se a função que está sendo analisada estiver anotada usando _Function_class_, que tem o mesmo valor de name; caso contrário, ela retornará zero.
_Check_return_ Anota um valor retornado e declara que o chamador deve inspecioná-lo. O verificador relatará um erro se a função for chamada em um contexto nulo.
_Function_class_(name) O parâmetro name é uma cadeia de caracteres arbitrária designada pelo usuário. Ele existe em um namespace que é distinto de outros namespaces. Uma função, um ponteiro de função ou, mais útil, um tipo de ponteiro de função pode ser designado como pertencente a uma ou mais classes de função.
_Raises_SEH_exception_ Anota uma função que sempre gera uma exceção SEH (manipulador de exceção estruturada), sujeita às condições _When_ e _On_failure_. Para obter mais informações, confira Especificando quando e onde uma anotação se aplica.
_Maybe_raises_SEH_exception_ Anota uma função que pode, opcionalmente, gerar uma exceção SEH, sujeita às condições _When_ e _On_failure_.
_Must_inspect_result_ Anota qualquer valor de saída, incluindo o valor retornado, os parâmetros e os globais. O analisador relatará um erro se o valor no objeto anotado não for inspecionado posteriormente. "Inspeção" inclui se ela é usada em uma expressão condicional, é atribuída a um parâmetro de saída ou global ou é passada como um parâmetro. Para valores retornados, _Must_inspect_result_ implica _Check_return_.
_Use_decl_annotations_ Pode ser usado em uma definição de função (também conhecida como corpo da função) no lugar da lista de anotações no cabeçalho. Quando _Use_decl_annotations_ é usada, as anotações que aparecem em um cabeçalho no escopo da mesma função são usadas como se também estivessem presentes na definição que tem a anotação _Use_decl_annotations_.

Anotações de êxito/falha

Uma função pode falhar e, quando isso acontece, os resultados dela podem estar incompletos ou diferir dos resultados quando a função é bem-sucedida. As anotações na lista a seguir fornecem maneiras de expressar o comportamento de falha. Para usar essas anotações, você precisa habilitá-las para determinar o sucesso; portanto, uma anotação _Success_ é necessária. Observe que NTSTATUS e HRESULT já tem uma anotação _Success_ interna neles; no entanto, se você especificar sua anotação _Success_ em NTSTATUS ou HRESULT, ela substituirá a anotação interna.

Anotação Descrição
_Always_(anno_list) Equivalente a anno_list _On_failure_(anno_list); ou seja, as anotações em anno_list se aplicam, independentemente de a função ter êxito ou não.
_On_failure_(anno_list) Para ser usado somente quando _Success_ também for usado para anotar a função, explicitamente ou implicitamente, por meio de _Return_type_success_ em um typedef. Quando a anotação _On_failure_ está presente em um parâmetro de função ou valor retornado, cada anotação em anno_list (anno) se comporta como se tivesse sido codificada como _When_(!expr, anno), em que expr é o parâmetro para a anotação _Success_ necessária. Isso significa que a aplicação implícita de _Success_ a todas as pós-condições não se aplica a _On_failure_.
_Return_type_success_(expr) Pode ser aplicado a um typedef. Indica que todas as funções que retornam esse tipo e não têm _Success_ explicitamente são anotadas como se tivessem _Success_(expr). _Return_type_success_ não pode ser usado em uma função ou em um typedef de ponteiro de função.
_Success_(expr) expr é uma expressão que gera um rvalue. Quando a anotação _Success_ está presente em uma definição ou declaração de função, cada anotação (anno) na função e na pós-condição se comporta como se fosse codificada como _When_(expr, anno). A anotação _Success_ pode ser usada apenas em uma função, não nos respectivos parâmetros ou tipo de retorno. Pode haver no máximo uma anotação _Success_ em uma função e ela não pode estar em nenhuma _When_, _At_ nem _Group_. Para obter mais informações, confira Especificando quando e onde uma anotação se aplica.

Confira também