Annotazione del comportamento della funzione

  • Articolo

Oltre a annotare i parametri della funzione e i valori restituiti, è possibile annotare le proprietà dell'intera funzione.

Annotazioni di funzione

Le seguenti annotazioni si applicano all'intera funzione e descrivono come si comporta o il valore previsto per restituire true.

Annotazione Descrizione
_Called_from_function_class_(name) Non inteso singolarmente; è un predicato da utilizzare con l'annotazione _When_. Per altre informazioni, vedere Specifica di quando e dove si applica un'annotazione.

Il name parametro è una stringa arbitraria che viene visualizzata anche in un'annotazione _Function_class_ nella dichiarazione di alcune funzioni. _Called_from_function_class_ restituisce un valore diverso da zero se la funzione attualmente analizzata viene annotata usando _Function_class_ che ha lo stesso valore di name; in caso contrario, restituisce zero.
_Check_return_ Annota un valore restituito e dichiara che il chiamante deve esaminarlo. La verifica restituisce un errore se la funzione viene chiamata in un contesto void.
_Function_class_(name) Il parametro name è una stringa arbitraria definita dall'utente. Esiste in uno spazio dei nomi distinto da tutti gli altri spazi dei nomi. Una funzione, un puntatore a funzione o, più utile, un tipo di puntatore a funzione può essere definito come appartenente a una o più classi di funzione.
_Raises_SEH_exception_ Annota una funzione che genera sempre un'eccezione del gestore eccezioni strutturate soggetta alle condizioni _When_ e _On_failure_. Per altre informazioni, vedere Specifica di quando e dove si applica un'annotazione.
_Maybe_raises_SEH_exception_ Annota una funzione che può facoltativamente generare un'eccezione del gestore eccezioni strutturate soggetta alle condizioni _When_ e _On_failure_.
_Must_inspect_result_ Annota qualsiasi valore di output, incluso il valore restituito, i parametri e le globals. L'analizzatore segnala un errore se il valore dell'oggetto annotato non è controllato in seguito. "L'ispezione" include se viene utilizzata in un'espressione condizionale, viene assegnata a un parametro di output o globale o viene passata come parametro. Per i valori restituiti, _Must_inspect_result_ implica _Check_return_.
_Use_decl_annotations_ Può essere usato in una definizione di funzione (nota anche come corpo della funzione) al posto dell'elenco di annotazioni nell'intestazione. Quando _Use_decl_annotations_ viene usato, le annotazioni visualizzate in un'intestazione nell'ambito per la stessa funzione vengono usate come se fossero presenti anche nella definizione con l'annotazione _Use_decl_annotations_ .

Annotazioni di esito positivo/negativo

Una funzione può non riuscire e, quando questo accade, i risultati possono essere incompleti o differire dai risultati della funzione con ha esito positivo. Le annotazioni nell'elenco seguente forniscono le modalità per esprimere il comportamento dell'errore. Per utilizzare ognuna di queste annotazioni, è necessario consentire loro di determinare l'esito positivo; pertanto è necessaria un'annotazione _Success_. Si noti che NTSTATUS e HRESULT già includono un'annotazione _Success_ compilata. Tuttavia, se si specifica un'annotazione _Success_ in NTSTATUS o HRESULT, viene eseguito l'override dell'annotazione incorporata.

Annotazione Descrizione
_Always_(anno_list) Analogamente a anno_list _On_failure_(anno_list), le annotazioni in anno_list si applicano indipendentemente dall'esito della funzione.
_On_failure_(anno_list) Da utilizzare solo quando si usa anche _Success_ per annotare la funzione, esplicitamente o implicitamente, mediante _Return_type_success_ in un typedef. Quando l'annotazione _On_failure_ è presente in un parametro di funzione o un valore restituito, ciascuna annotazione in anno_list (anno) si comporta come se fosse codificata come _When_(!expr, anno), dove expr è il parametro dell'annotazione _Success_ richiesta. Ciò significa che l'applicazione implicita di _Success_ per tutte le post-condizioni non è applicabile per _On_failure_.
_Return_type_success_(expr) Può essere applicato a un typedef. Indica che tutte le funzioni che restituiscono quel tipo e non includono _Success_ in modo esplicito, sono annotate come se includessero _Success_(expr). _Return_type_success_ non può essere utilizzato in una funzione o in un typedef di puntatore a funzione.
_Success_(expr) expr è un'espressione che produce un rvalue. Quando l'annotazione _Success_ è presente in una dichiarazione di funzione o una definizione, ciascuna annotazione (anno) nella funzione e in post-condizione si comporta come se fosse codificata come _When_(expr, anno). L'annotazione _Success_ può essere utilizzata solo in una funzione e non nei relativi parametri o nel tipo restituito. Ci può essere al massimo un'annotazione _Success_ in una funzione e non può trovarsi all'interno di qualsiasi _When_, _At_ o _Group_. Per altre informazioni, vedere Specifica di quando e dove si applica un'annotazione.

Vedi anche