Partilhar via

Anotar o comportamento de funções

Além de anotar parâmetros de função e valores de retorno, 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 espera que seja verdade.

Anotação Descrição
_Called_from_function_class_(name) Não se destina a ficar sozinho; em vez disso, é um predicado a ser usado com a _When_ anotação. Para obter mais informações, consulte Especificando quando e onde uma anotação se aplica.

O name parâmetro é uma cadeia de caracteres arbitrária que também aparece em uma _Function_class_ anotação na declaração de algumas funções. _Called_from_function_class_ retorna diferente de zero se a função que está sendo analisada atualmente é anotada usando _Function_class_ que tem o mesmo valor de name; caso contrário, retorna zero.
_Check_return_ Anota um valor de retorno e afirma que o chamador deve inspecioná-lo. O verificador relata um erro se a função for chamada em um contexto vazio.
_Function_class_(name) O name parâmetro é uma cadeia de caracteres arbitrária que é 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 de manipulador de exceção estruturado (SEH), sujeita a _When_ e _On_failure_ condições. Para obter mais informações, consulte 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 a _When_ e _On_failure_ condições.
_Must_inspect_result_ Anota qualquer valor resultante, incluindo o valor de retorno, os parâmetros e as variáveis globais. O analisador relata um erro se o valor no objeto anotado não for inspecionado posteriormente. "Inspeção" inclui se ele é usado em uma expressão condicional, é atribuído a um parâmetro de saída ou global, ou é passado como um parâmetro. Para valores de retorno, _Must_inspect_result_ implica _Check_return_.
_Use_decl_annotations_ Pode ser usado em uma definição de função (também conhecida como corpo de função) no lugar da lista de anotações no cabeçalho. Quando _Use_decl_annotations_ é usado, as anotações que aparecem num cabeçalho dentro do escopo para a 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 sucesso/falha

Uma função pode falhar e, quando falha, seus resultados podem ser incompletos ou diferentes 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ê deve habilitá-las para determinar o sucesso; portanto, uma _Success_ anotação é necessária. Observe que NTSTATUS e HRESULT já têm uma _Success_ anotação integrada neles; no entanto, se especificar a sua própria _Success_ anotação em NTSTATUS ou HRESULT, ela sobrepõe a anotação incorporada.

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 quer a função seja bem-sucedida ou não.
_On_failure_(anno_list) Para ser usado somente quando _Success_ também é usado para anotar a função — seja de forma explícita ou implícita através de um typedef em _Return_type_success_. Quando a _On_failure_ anotação está presente em um parâmetro de função ou valor de retorno, cada anotação em anno_list (anno) se comporta como se fosse codificada como _When_(!expr, anno), onde expr é o parâmetro para a anotação necessária _Success_ . Isto significa que a aplicação implícita de _Success_ a todas as pós-condições não se aplica à _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 um ponteiro de função typedef.
_Success_(expr) expr é uma expressão que produz um rvalue. Quando a _Success_ anotação está presente numa declaração ou definição de função, cada anotação (anno) na função e na pós-condição comporta-se como se fosse codificada como _When_(expr, anno). A _Success_ anotação pode ser usada apenas em uma função, não em seus parâmetros ou tipo de retorno. Pode haver no máximo uma _Success_ anotação em uma função, e ela não pode estar em nenhuma _When_, _At_ou _Group_. Para obter mais informações, consulte Especificando quando e onde uma anotação se aplica.

Ver também

  • Last updated on