Hinzufügen einer Anmerkung zum FunktionsverhaltenAnnotating function behavior

Zusätzlich zum Kommentieren von Funktionsparametern und Rückgabe Wertenkönnen Sie die Eigenschaften der gesamten Funktion mit Anmerkungen versehen.In addition to annotating function parameters and return values, you can annotate properties of the whole function.

Funktions AnmerkungenFunction annotations

Die folgenden Anmerkungen gelten für die Funktion als Ganzes und beschreiben, wie Sie sich verhält oder was Sie erwartet.The following annotations apply to the function as a whole and describe how it behaves or what it expects to be true.

AnmerkungAnnotation BESCHREIBUNGDescription
_Called_from_function_class_(name) Nicht für eigenständige bereitstellen. Stattdessen ist es ein Prädikat, das mit der-Anmerkung verwendet werden soll _When_ .Not intended to stand alone; instead, it is a predicate to be used with the _When_ annotation. Weitere Informationen finden Sie unter angeben, wann und wo eine Anmerkung anwendbarist.For more information, see Specifying When and Where an Annotation Applies.

Der- name Parameter ist eine beliebige Zeichenfolge, die auch in einer Anmerkung _Function_class_ in der Deklaration einiger Funktionen angezeigt wird.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_ Gibt einen Wert ungleich 0 (null) zurück, wenn die Funktion, die gerade analysiert wird _Function_class_ , mit dem gleichen Wert von versehen wird, name andernfalls wird 0 (null) zurückgegeben._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_ Kommentiert einen Rückgabewert und gibt an, dass der Aufrufer ihn überprüfen soll.Annotates a return value and states that the caller should inspect it. Die Prüfung meldet einen Fehler, wenn die Funktion in einem leeren Kontext aufgerufen wird.The checker reports an error if the function is called in a void context.
_Function_class_(name) Der- name Parameter ist eine beliebige Zeichenfolge, die vom Benutzer angegeben wird.The name parameter is an arbitrary string that is designated by the user. Es ist in einem Namespace vorhanden, der sich von anderen Namespaces unterscheidet.It exists in a namespace that is distinct from other namespaces. Eine Funktion, ein Funktionszeiger oder – am nützlichsten – ein Funktions Zeigertyp kann als zu einer oder mehreren Funktionsklassen gehörend festgelegt werden.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_ Kommentiert eine Funktion, die immer eine strukturierte Ausnahmehandler-Ausnahme (SEH) auslöst, unterliegt _When_ den _On_failure_ Bedingungen und.Annotates a function that always raises a structured exception handler (SEH) exception, subject to _When_ and _On_failure_ conditions. Weitere Informationen finden Sie unter angeben, wann und wo eine Anmerkung anwendbarist.For more information, see Specifying When and Where an Annotation Applies.
_Maybe_raises_SEH_exception_ Kommentiert eine Funktion, die optional eine SEH-Ausnahme auslöst, unterliegt den _When_ _On_failure_ Bedingungen und.Annotates a function that may optionally raise an SEH exception, subject to _When_ and _On_failure_ conditions.
_Must_inspect_result_ Kommentiert jeden Ausgabewert, einschließlich des Rückgabewerts, der Parameter und Globals.Annotates any output value, including the return value, parameters, and globals. Der Analyzer meldet einen Fehler, wenn der Wert im Objekt mit Anmerkungen nicht nachfolgend überprüft wird.The analyzer reports an error if the value in the annotated object is not subsequently inspected. "Überprüfung" gibt an, ob es in einem bedingten Ausdruck verwendet wird, einem Ausgabeparameter oder einem globalen Ausdruck zugewiesen ist oder als Parameter übergeben wird."Inspection" includes whether it is used in a conditional expression, is assigned to an output parameter or global, or is passed as a parameter. Bei Rückgabe Werten _Must_inspect_result_ impliziert _Check_return_ .For return values, _Must_inspect_result_ implies _Check_return_.
_Use_decl_annotations_ Kann in einer Funktionsdefinition (auch als Funktions Rumpf bezeichnet) anstelle der Liste der Anmerkungen in der Kopfzeile verwendet werden.May be used on a function definition (also known as a function body) in place of the list of annotations in the header. Wenn _Use_decl_annotations_ verwendet wird, werden die Anmerkungen, die in einem Gültigkeitsbereich für die gleiche Funktion angezeigt werden, so verwendet, als wären Sie auch in der Definition mit der-Anmerkung vorhanden _Use_decl_annotations_ .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.

Anmerkungen zu Erfolg/FehlerSuccess/failure annotations

Eine Funktion kann fehlschlagen, und wenn dies der Fall ist, sind die Ergebnisse möglicherweise unvollständig oder unterscheiden sich von den Ergebnissen, wenn die Funktion erfolgreich ausgeführt wird.A function can fail, and when it does, its results may be incomplete or differ from the results when the function succeeds. Die Anmerkungen in der folgenden Liste bieten Möglichkeiten, das Fehler Verhalten auszudrücken.The annotations in the following list provide ways to express the failure behavior. Um diese Anmerkungen zu verwenden, müssen Sie Sie aktivieren, um den Erfolg zu ermitteln. Daher ist eine Anmerkung _Success_ erforderlich.To use these annotations, you must enable them to determine success; therefore, a _Success_ annotation is required. Beachten Sie, dass NTSTATUS und HRESULT bereits eine Anmerkung _Success_ integriert sind. Wenn Sie jedoch ihre eigene Anmerkung _Success_ für NTSTATUS oder angeben HRESULT , wird die integrierte Anmerkung überschrieben.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.

AnmerkungAnnotation BESCHREIBUNGDescription
_Always_(anno_list) Entspricht, anno_list _On_failure_(anno_list) d. h. die Anmerkungen in gelten, unabhängig davon, anno_list ob die Funktion erfolgreich ausgeführt wurde.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) Wird nur verwendet, wenn _Success_ auch verwendet wird, um die Funktion zu kommentieren – entweder explizit oder implizit über _Return_type_success_ eine typedef.To be used only when _Success_ is also used to annotate the function—either explicitly, or implicitly through _Return_type_success_ on a typedef. Wenn die Anmerkung _On_failure_ in einem Funktionsparameter oder Rückgabewert vorhanden ist, verhält sich jede Anmerkung in anno_list (anno) so, als ob Sie als programmiert wäre _When_(!expr, anno) , wobei expr der Parameter für die erforderliche _Success_ Anmerkung ist.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. Dies bedeutet, dass die implizite Anwendung von _Success_ auf alle Post Bedingungen nicht für gilt _On_failure_ .This means that the implied application of _Success_ to all post-conditions does not apply for _On_failure_.
_Return_type_success_(expr) Kann auf eine typedef angewendet werden.May be applied to a typedef. Gibt an, dass alle Funktionen, die diesen Typ zurückgeben und nicht explizit vorhanden _Success_ sind, so kommentiert werden, als wären Sie hätten _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_ kann nicht für eine Funktion oder eine funktionszeigertypedef verwendet werden._Return_type_success_ cannot be used on a function or a function pointer typedef.
_Success_(expr) expr ein Ausdruck, der einen Rvalue-Wert ergibt.expr is an expression that yields an rvalue. Wenn die Anmerkung in _Success_ einer Funktionsdeklaration oder-Definition vorhanden ist, verhält sich jede Anmerkung ( anno ) in der Funktion und in der Post-Bedingung so, als wäre sie als codiert _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). Die-Anmerkung _Success_ kann nur für eine Funktion verwendet werden, nicht für deren Parameter oder Rückgabetyp.The _Success_ annotation may be used only on a function, not on its parameters or return type. Es kann höchstens eine Anmerkung _Success_ für eine Funktion geben, und Sie darf nicht in _When_ , _At_ oder sein _Group_ .There can be at most one _Success_ annotation on a function, and it cannot be in any _When_, _At_, or _Group_. Weitere Informationen finden Sie unter angeben, wann und wo eine Anmerkung anwendbarist.For more information, see Specifying When and Where an Annotation Applies.

Siehe auchSee also