Kommentieren von Funktionsparametern und Rückgabe WertenAnnotating function parameters and return values

In diesem Artikel werden typische Verwendungsmöglichkeiten von Anmerkungen für einfache Funktionsparameter – skalare und Zeiger auf Strukturen und Klassen – und die meisten Puffer Typen beschrieben.This article describes typical uses of annotations for simple function parameters—scalars, and pointers to structures and classes—and most kinds of buffers. Dieser Artikel zeigt auch gängige Verwendungs Muster für Anmerkungen.This article also shows common usage patterns for annotations. Weitere Anmerkungen, die sich auf Funktionen beziehen, finden Sie unter kommentieren von Funktionsverhalten.For additional annotations that are related to functions, see Annotating function behavior.

Zeiger ParameterPointer parameters

Wenn ein Zeiger Parameter mit Anmerkungen versehen ist, meldet der Analyzer in der folgenden Tabelle einen Fehler, wenn der Zeiger NULL ist.For the annotations in the following table, when a pointer parameter is annotated, the analyzer reports an error if the pointer is null. Diese Anmerkung gilt für Zeiger und für jedes Datenelement, auf das verwiesen wird.This annotation applies to pointers and to any data item that's pointed to.

Anmerkungen und BeschreibungenAnnotations and descriptions

  • _In_

    Kommentiert Eingabe Parametern, bei denen es sich um skalare, Strukturen, Zeiger auf Strukturen und ähnliches handelt.Annotates input parameters that are scalars, structures, pointers to structures and the like. Kann explizit auf einfachen skalaren verwendet werden.Explicitly may be used on simple scalars. Der-Parameter muss im Voraus State gültig sein und wird nicht geändert.The parameter must be valid in pre-state and won't be modified.

  • _Out_

    Kommentiert Ausgabeparameter, bei denen es sich um skalare, Strukturen, Zeiger auf Strukturen und ähnliches handelt.Annotates output parameters that are scalars, structures, pointers to structures and the like. Wenden Sie diese Anmerkung nicht auf ein Objekt an, das keinen Wert zurückgeben kann, z. –. ein Skalar, der als Wert übergangen wird.Don't apply this annotation to an object that can't return a value—for example, a scalar that's passed by value. Der-Parameter muss im Voraus State nicht gültig sein, muss jedoch im Post-Status gültig sein.The parameter doesn't have to be valid in pre-state but must be valid in post-state.

  • _Inout_

    Kommentiert einen Parameter, der von der-Funktion geändert wird.Annotates a parameter that will be changed by the function. Er muss sowohl im Zustand vor als auch nach dem Status gültig sein, es wird jedoch davon ausgegangen, dass er vor und nach dem-Befehl über unterschiedliche Werte verfügt.It must be valid in both pre-state and post-state, but is assumed to have different values before and after the call. Muss auf einen änderbaren Wert angewendet werden.Must apply to a modifiable value.

  • _In_z_

    Ein Zeiger auf eine auf NULL endende Zeichenfolge, die als Eingabe verwendet wird.A pointer to a null-terminated string that's used as input. Die Zeichenfolge muss im Voraus State gültig sein.The string must be valid in pre-state. Varianten von PSTR , die bereits über die richtigen Anmerkungen verfügen, werden bevorzugt.Variants of PSTR, which already have the correct annotations, are preferred.

  • _Inout_z_

    Ein Zeiger auf ein mit Null endendes Zeichen Array, das geändert wird.A pointer to a null-terminated character array that will be modified. Sie muss vor und nach dem-Befehl gültig sein, aber es wird davon ausgegangen, dass sich der Wert geändert hat.It must be valid before and after the call, but it's assumed the value has changed. Der NULL-Terminator kann verschoben werden, aber nur die Elemente bis zum ursprünglichen null-Terminator können aufgerufen werden.The null terminator may be moved, but only the elements up to the original null terminator may be accessed.

  • _In_reads_(s)

    _In_reads_bytes_(s)

    Ein Zeiger auf ein Array, das von der Funktion gelesen wird.A pointer to an array, which is read by the function. Das Array weist Größen s Elemente auf, die alle gültig sein müssen.The array is of size s elements, all of which must be valid.

    Die _bytes_ Variante gibt die Größe in Bytes anstelle von Elementen an.The _bytes_ variant gives the size in bytes instead of elements. Verwenden Sie diese Variante nur, wenn die Größe nicht als Elemente ausgedrückt werden kann.Use this variant only when the size can't be expressed as elements. Beispielsweise würden Zeichen folgen char die _bytes_ Variante nur dann verwenden, wenn eine ähnliche Funktion, die verwendet, wchar_t wäre.For example, char strings would use the _bytes_ variant only if a similar function that uses wchar_t would.

  • _In_reads_z_(s)

    Ein Zeiger auf ein Array, das NULL-terminierte und eine bekannte Größe aufweist.A pointer to an array that is null-terminated and has a known size. Die Elemente bis zum NULL-Terminator – oder, s Wenn kein NULL-Terminator vorhanden ist – müssen im Zustand "vor dem Zustand" gültig sein.The elements up to the null terminator—or s if there isn't a null terminator—must be valid in pre-state. Wenn die Größe in Bytes bekannt ist, Skalieren Sie s nach der Elementgröße.If the size is known in bytes, scale s by the element size.

  • _In_reads_or_z_(s)

    Ein Zeiger auf ein Array, das NULL-terminierte oder eine bekannte Größe hat, oder beides.A pointer to an array that is null-terminated or has a known size, or both. Die Elemente bis zum NULL-Terminator – oder, s Wenn kein NULL-Terminator vorhanden ist – müssen im Zustand "vor dem Zustand" gültig sein.The elements up to the null terminator—or s if there isn't a null terminator—must be valid in pre-state. Wenn die Größe in Bytes bekannt ist, Skalieren Sie s nach der Elementgröße.If the size is known in bytes, scale s by the element size. (Wird für die strn Familie verwendet.)(Used for the strn family.)

  • _Out_writes_(s)

    _Out_writes_bytes_(s)

    Ein Zeiger auf ein Array von- s Elementen (bzw. Bytes), die von der-Funktion geschrieben werden.A pointer to an array of s elements (resp. bytes) that will be written by the function. Die Array Elemente müssen nicht im Voraus State gültig sein, und die Anzahl der Elemente, die im Post-State gültig sind, ist nicht angegeben.The array elements don't have to be valid in pre-state, and the number of elements that are valid in post-state is unspecified. Wenn Anmerkungen zum Parametertyp vorhanden sind, werden Sie im nach Zustand angewendet.If there are annotations on the parameter type, they're applied in post-state. Betrachten Sie hierzu den folgenden Beispielcode:For example, consider the following code.

    typedef _Null_terminated_ wchar_t *PWSTR;
    void MyStringCopy(_Out_writes_(size) PWSTR p1, _In_ size_t size, _In_ PWSTR p2);
    

    In diesem Beispiel stellt der Aufrufer einen Puffer von size Elementen für bereit p1 .In this example, the caller provides a buffer of size elements for p1. MyStringCopy macht einige dieser Elemente gültig.MyStringCopy makes some of those elements valid. Noch wichtiger ist, _Null_terminated_ dass die Anmerkung in PWSTR bedeutet, dass p1 im Post-State NULL-terminiert ist.More importantly, the _Null_terminated_ annotation on PWSTR means that p1 is null-terminated in post-state. Auf diese Weise ist die Anzahl der gültigen Elemente immer noch klar definiert, aber eine bestimmte Element Anzahl ist nicht erforderlich.In this way, the number of valid elements is still well-defined, but a specific element count isn't required.

    Die _bytes_ Variante gibt die Größe in Bytes anstelle von Elementen an.The _bytes_ variant gives the size in bytes instead of elements. Verwenden Sie diese Variante nur, wenn die Größe nicht als Elemente ausgedrückt werden kann.Use this variant only when the size can't be expressed as elements. Beispielsweise würden Zeichen folgen char die _bytes_ Variante nur dann verwenden, wenn eine ähnliche Funktion, die verwendet, wchar_t wäre.For example, char strings would use the _bytes_ variant only if a similar function that uses wchar_t would.

  • _Out_writes_z_(s)

    Ein Zeiger auf ein Array von- s Elementen.A pointer to an array of s elements. Die Elemente müssen nicht im Voraus State gültig sein.The elements don't have to be valid in pre-state. Im Post-Zustand müssen die Elemente, die durch das NULL-Abschluss Zeichen – das vorhanden sein müssen – gültig sein.In post-state, the elements up through the null terminator—which must be present—must be valid. Wenn die Größe in Bytes bekannt ist, Skalieren Sie s nach der Elementgröße.If the size is known in bytes, scale s by the element size.

  • _Inout_updates_(s)

    _Inout_updates_bytes_(s)

    Ein Zeiger auf ein Array, das in der Funktion gelesen und geschrieben wird.A pointer to an array, which is both read and written to in the function. Sie ist von den Größen s Elementen und im Zustand vor und nach dem Zustand gültig.It's of size s elements, and valid in pre-state and post-state.

    Die _bytes_ Variante gibt die Größe in Bytes anstelle von Elementen an.The _bytes_ variant gives the size in bytes instead of elements. Verwenden Sie diese Variante nur, wenn die Größe nicht als Elemente ausgedrückt werden kann.Use this variant only when the size can't be expressed as elements. Beispielsweise würden Zeichen folgen char die _bytes_ Variante nur dann verwenden, wenn eine ähnliche Funktion, die verwendet, wchar_t wäre.For example, char strings would use the _bytes_ variant only if a similar function that uses wchar_t would.

  • _Inout_updates_z_(s)

    Ein Zeiger auf ein Array, das NULL-terminierte und eine bekannte Größe aufweist.A pointer to an array that's null-terminated and has a known size. Die Elemente, die durch das NULL-Abschluss Zeichen – die vorhanden sein müssen, müssen – sowohl im Zustand vor als auch nach dem Status gültig sein.The elements up through the null terminator—which must be present—must be valid in both pre-state and post-state. Es wird davon ausgegangen, dass sich der Wert im Post-State von dem Wert im Zustand "vor" unterscheidet. , der den Speicherort des NULL-Abschluss Zeichens einschließt.The value in the post-state is presumed to be different from the value in the pre-state; that includes the location of the null terminator. Wenn die Größe in Bytes bekannt ist, Skalieren Sie s nach der Elementgröße.If the size is known in bytes, scale s by the element size.

  • _Out_writes_to_(s,c)

    _Out_writes_bytes_to_(s,c)

    _Out_writes_all_(s)

    _Out_writes_bytes_all_(s)

    Ein Zeiger auf ein Array von- s Elementen.A pointer to an array of s elements. Die Elemente müssen nicht im Voraus State gültig sein.The elements don't have to be valid in pre-state. Im Post-State müssen die Elemente bis zum c -th-Element gültig sein.In post-state, the elements up to the c-th element must be valid. Die _bytes_ Variante kann verwendet werden, wenn die Größe in Bytes und nicht in der Anzahl der Elemente bekannt ist.The _bytes_ variant can be used if the size is known in bytes rather than number of elements.

    Beispiel:For example:

    void *memcpy(_Out_writes_bytes_all_(s) char *p1, _In_reads_bytes_(s) char *p2, _In_ int s);
    void *wordcpy(_Out_writes_all_(s) DWORD *p1, _In_reads_(s) DWORD *p2, _In_ int s);
    
  • _Inout_updates_to_(s,c)

    _Inout_updates_bytes_to_(s,c)

    Ein Zeiger auf ein Array, das von der Funktion gelesen und geschrieben wird.A pointer to an array, which is both read and written by the function. Es s sind Größen Elemente, die alle im Voraus State gültig sein müssen, und c Elemente müssen im Post-State gültig sein.It's of size s elements, all of which must be valid in pre-state, and c elements must be valid in post-state.

    Die _bytes_ Variante gibt die Größe in Bytes anstelle von Elementen an.The _bytes_ variant gives the size in bytes instead of elements. Verwenden Sie diese Variante nur, wenn die Größe nicht als Elemente ausgedrückt werden kann.Use this variant only when the size can't be expressed as elements. Beispielsweise würden Zeichen folgen char die _bytes_ Variante nur dann verwenden, wenn eine ähnliche Funktion, die verwendet, wchar_t wäre.For example, char strings would use the _bytes_ variant only if a similar function that uses wchar_t would.

  • _Inout_updates_all_(s)

    _Inout_updates_bytes_all_(s)

    Ein Zeiger auf ein Array, das von der Funktion der Size-Elemente gelesen und geschrieben wird s .A pointer to an array, which is both read and written by the function of size s elements. Definiert als äquivalent zu:Defined as equivalent to:

    _Inout_updates_to_(_Old_(s), _Old_(s)) _Inout_updates_bytes_to_(_Old_(s), _Old_(s))

    Das heißt, dass jedes Element, das im Puffer bis zu im Zustand "Pre" vorhanden s ist, im Zustand vor und nach dem Zustand gültig ist.In other words, every element that exists in the buffer up to s in the pre-state is valid in the pre-state and post-state.

    Die _bytes_ Variante gibt die Größe in Bytes anstelle von Elementen an.The _bytes_ variant gives the size in bytes instead of elements. Verwenden Sie diese Variante nur, wenn die Größe nicht als Elemente ausgedrückt werden kann.Use this variant only when the size can't be expressed as elements. Beispielsweise würden Zeichen folgen char die _bytes_ Variante nur dann verwenden, wenn eine ähnliche Funktion, die verwendet, wchar_t wäre.For example, char strings would use the _bytes_ variant only if a similar function that uses wchar_t would.

  • _In_reads_to_ptr_(p)

    Ein Zeiger auf ein Array, für das (d. h p - _Curr_ p _Curr_ . minus) ein gültiger Ausdruck ist.A pointer to an array for which p - _Curr_ (that is, p minus _Curr_) is a valid expression. Die-Elemente vor p müssen im Voraus State gültig sein.The elements before p must be valid in pre-state.

    Beispiel:For example:

    int ReadAllElements(_In_reads_to_ptr_(EndOfArray) const int *Array, const int *EndOfArray);
    
  • _In_reads_to_ptr_z_(p)

    Ein Zeiger auf ein mit Null endendes Array, für den Expression (d. h p - _Curr_ p _Curr_ . minus) ein gültiger Ausdruck ist.A pointer to a null-terminated array for which expression p - _Curr_ (that is, p minus _Curr_) is a valid expression. Die-Elemente vor p müssen im Voraus State gültig sein.The elements before p must be valid in pre-state.

  • _Out_writes_to_ptr_(p)

    Ein Zeiger auf ein Array, für das (d. h p - _Curr_ p _Curr_ . minus) ein gültiger Ausdruck ist.A pointer to an array for which p - _Curr_ (that is, p minus _Curr_) is a valid expression. Die Elemente vor müssen p nicht im Voraus State gültig sein und müssen im Post-State gültig sein.The elements before p don't have to be valid in pre-state and must be valid in post-state.

  • _Out_writes_to_ptr_z_(p)

    Ein Zeiger auf ein mit Null endendes Array, für das (d. h p - _Curr_ p _Curr_ . minus) ein gültiger Ausdruck ist.A pointer to a null-terminated array for which p - _Curr_ (that is, p minus _Curr_) is a valid expression. Die Elemente vor müssen p nicht im Voraus State gültig sein und müssen im Post-State gültig sein.The elements before p don't have to be valid in pre-state and must be valid in post-state.

Optionale Zeiger ParameterOptional pointer parameters

Wenn eine Zeiger Parameter Anmerkung enthält _opt_ , gibt Sie an, dass der Parameter möglicherweise NULL ist.When a pointer parameter annotation includes _opt_, it indicates that the parameter may be null. Andernfalls verhält sich die-Anmerkung genauso wie die Version, die nicht enthält _opt_ .Otherwise, the annotation behaves the same as the version that doesn't include _opt_. Im folgenden finden Sie eine Liste der _opt_ Varianten der Zeiger Parameter Anmerkungen:Here is a list of the _opt_ variants of the pointer parameter annotations:

_In_opt_
_Out_opt_
_Inout_opt_
_In_opt_z_
_Inout_opt_z_
_In_reads_opt_
_In_reads_bytes_opt_
_In_reads_opt_z_

_Out_writes_opt_
_Out_writes_opt_z_
_Inout_updates_opt_
_Inout_updates_bytes_opt_
_Inout_updates_opt_z_
_Out_writes_to_opt_
_Out_writes_bytes_to_opt_
_Out_writes_all_opt_
_Out_writes_bytes_all_opt_

_Inout_updates_to_opt_
_Inout_updates_bytes_to_opt_
_Inout_updates_all_opt_
_Inout_updates_bytes_all_opt_
_In_reads_to_ptr_opt_
_In_reads_to_ptr_opt_z_
_Out_writes_to_ptr_opt_
_Out_writes_to_ptr_opt_z_

Ausgabe Zeiger ParameterOutput pointer parameters

Ausgabe Zeiger Parameter erfordern eine besondere Schreibweise, um NULL-Werte für den Parameter und den Punkt auf den Speicherort zu unterscheiden.Output pointer parameters require special notation to disambiguate nullness on the parameter and the pointed-to location.

Anmerkungen und BeschreibungenAnnotations and descriptions

  • _Outptr_

    Der Parameter darf nicht NULL sein, und im Post-State darf der Punkt-zu-Speicherort nicht NULL sein und muss gültig sein.Parameter can't be null, and in the post-state the pointed-to location can't be null and must be valid.

  • _Outptr_opt_

    Der Parameter kann NULL sein, aber im Post-State darf der Punkt-zu-Speicherort nicht NULL sein und muss gültig sein.Parameter may be null, but in the post-state the pointed-to location can't be null and must be valid.

  • _Outptr_result_maybenull_

    Der Parameter darf nicht NULL sein, und im Post-State kann der Punkt-zu-Standort den Wert NULL haben.Parameter can't be null, and in the post-state the pointed-to location can be null.

  • _Outptr_opt_result_maybenull_

    Der-Parameter kann NULL sein, und im Post-State kann der Punkt-zu-Standort den Wert NULL haben.Parameter may be null, and in the post-state the pointed-to location can be null.

    In der folgenden Tabelle werden zusätzliche Teil Zeichenfolgen in den Namen der Anmerkung eingefügt, um die Bedeutung der Anmerkung weiter zu qualifizieren.In the following table, additional substrings are inserted into the annotation name to further qualify the meaning of the annotation. Die verschiedenen Teil Zeichenfolgen sind _z , _COM_ , _buffer_ , _bytebuffer_ und _to_ .The various substrings are _z, _COM_, _buffer_, _bytebuffer_, and _to_.

Wichtig

Wenn die Schnittstelle, die Sie kommentieren, com ist, verwenden Sie das com-Formular dieser Anmerkungen.If the interface that you are annotating is COM, use the COM form of these annotations. Verwenden Sie die com-Anmerkungen nicht mit anderen typschnittstellen.Don't use the COM annotations with any other type interface.

  • _Outptr_result_z_

    _Outptr_opt_result_z_

    _Outptr_result_maybenull_z_

    _Outptr_opt_result_maybenull_z_

    Der zurückgegebene Zeiger verfügt über die-Anmerkung _Null_terminated_ .The returned pointer has the _Null_terminated_ annotation.

  • _COM_Outptr_

    _COM_Outptr_opt_

    _COM_Outptr_result_maybenull_

    _COM_Outptr_opt_result_maybenull_

    Der zurückgegebene Zeiger hat eine com-Semantik, weshalb er eine _On_failure_ nach Bedingung enthält, dass der zurückgegebene Zeiger NULL ist.The returned pointer has COM semantics, which is why it carries an _On_failure_ post-condition that the returned pointer is null.

  • _Outptr_result_buffer_(s)

    _Outptr_result_bytebuffer_(s)

    _Outptr_opt_result_buffer_(s)

    _Outptr_opt_result_bytebuffer_(s)

    Der zurückgegebene Zeiger verweist auf einen gültigen Puffer der Größen s Elemente oder Bytes.The returned pointer points to a valid buffer of size s elements or bytes.

  • _Outptr_result_buffer_to_(s, c)

    _Outptr_result_bytebuffer_to_(s, c)

    _Outptr_opt_result_buffer_to_(s,c)

    _Outptr_opt_result_bytebuffer_to_(s,c)

    Der zurückgegebene Zeiger zeigt auf einen Puffer der Größen s Elemente oder bytes, von denen der erste c gültig ist.The returned pointer points to a buffer of size s elements or bytes, of which the first c are valid.

Bestimmte Schnittstellen Konventionen setzen voraus, dass Ausgabeparameter bei einem Fehler NULL sind.Certain interface conventions presume that output parameters are nullified on failure. Mit Ausnahme des expliziten com-Codes werden die Formulare in der folgenden Tabelle bevorzugt.Except for explicitly COM code, the forms in the following table are preferred. Verwenden Sie für com-Code die entsprechenden com-Formulare, die im vorherigen Abschnitt aufgelistet sind.For COM code, use the corresponding COM forms that are listed in the previous section.

  • _Result_nullonfailure_

    Ändert andere Anmerkungen.Modifies other annotations. Das Ergebnis wird auf NULL festgelegt, wenn die Funktion fehlschlägt.The result is set to null if the function fails.

  • _Result_zeroonfailure_

    Ändert andere Anmerkungen.Modifies other annotations. Das Ergebnis wird auf 0 festgelegt, wenn die Funktion fehlschlägt.The result is set to zero if the function fails.

  • _Outptr_result_nullonfailure_

    Der zurückgegebene Zeiger zeigt auf einen gültigen Puffer, wenn die Funktion erfolgreich ist, oder NULL, wenn die Funktion fehlschlägt.The returned pointer points to a valid buffer if the function succeeds, or null if the function fails. Diese Anmerkung gilt für einen nicht optionalen Parameter.This annotation is for a non-optional parameter.

  • _Outptr_opt_result_nullonfailure_

    Der zurückgegebene Zeiger zeigt auf einen gültigen Puffer, wenn die Funktion erfolgreich ist, oder NULL, wenn die Funktion fehlschlägt.The returned pointer points to a valid buffer if the function succeeds, or null if the function fails. Diese Anmerkung ist für einen optionalen Parameter.This annotation is for an optional parameter.

  • _Outref_result_nullonfailure_

    Der zurückgegebene Zeiger zeigt auf einen gültigen Puffer, wenn die Funktion erfolgreich ist, oder NULL, wenn die Funktion fehlschlägt.The returned pointer points to a valid buffer if the function succeeds, or null if the function fails. Diese Anmerkung ist für einen Verweis Parameter.This annotation is for a reference parameter.

Ausgabe Verweis ParameterOutput reference parameters

Der Verweis Parameter wird häufig für Ausgabeparameter verwendet.A common use of the reference parameter is for output parameters. Für einfache Ausgabe Verweis Parameter, wie int& z _Out_ . b., stellt die richtige Semantik bereit.For simple output reference parameters such as int&, _Out_ provides the correct semantics. Wenn der Ausgabewert jedoch ein Zeiger ist int *& , z. b., stellen die entsprechenden Zeiger Anmerkungen wie _Outptr_ int ** nicht die richtige Semantik bereit.However, when the output value is a pointer such as int *&, the equivalent pointer annotations like _Outptr_ int ** don't provide the correct semantics. Verwenden Sie die folgenden zusammengesetzten Anmerkungen, um die Semantik der Ausgabe Verweis Parameter für Zeiger Typen kurz auszudrücken:To concisely express the semantics of output reference parameters for pointer types, use these composite annotations:

Anmerkungen und BeschreibungenAnnotations and descriptions

  • _Outref_

    Das Ergebnis muss im Post-State gültig sein und darf nicht NULL sein.Result must be valid in post-state and can't be null.

  • _Outref_result_maybenull_

    Das Ergebnis muss im Post-State gültig sein, kann jedoch im Post-State NULL sein.Result must be valid in post-state, but may be null in post-state.

  • _Outref_result_buffer_(s)

    Das Ergebnis muss im Post-State gültig sein und darf nicht NULL sein.Result must be valid in post-state and can't be null. Zeigt auf einen gültigen Puffer von size- s Elementen.Points to valid buffer of size s elements.

  • _Outref_result_bytebuffer_(s)

    Das Ergebnis muss im Post-State gültig sein und darf nicht NULL sein.Result must be valid in post-state and can't be null. Zeigt auf einen gültigen Puffer mit einer Größe von s Bytes.Points to valid buffer of size s bytes.

  • _Outref_result_buffer_to_(s, c)

    Das Ergebnis muss im Post-State gültig sein und darf nicht NULL sein.Result must be valid in post-state and can't be null. Zeigt auf den Puffer von s Elementen, von denen der erste c gültig ist.Points to buffer of s elements, of which the first c are valid.

  • _Outref_result_bytebuffer_to_(s, c)

    Das Ergebnis muss im Post-State gültig sein und darf nicht NULL sein.Result must be valid in post-state and can't be null. Zeigt auf den Puffer von s bytes, von denen der erste c gültig ist.Points to buffer of s bytes of which the first c are valid.

  • _Outref_result_buffer_all_(s)

    Das Ergebnis muss im Post-State gültig sein und darf nicht NULL sein.Result must be valid in post-state and can't be null. Verweist auf einen gültigen Puffer der s gültigen Größe von Elementen.Points to valid buffer of size s valid elements.

  • _Outref_result_bytebuffer_all_(s)

    Das Ergebnis muss im Post-State gültig sein und darf nicht NULL sein.Result must be valid in post-state and can't be null. Verweist auf einen gültigen Puffer von s Bytes gültiger-Elemente.Points to valid buffer of s bytes of valid elements.

  • _Outref_result_buffer_maybenull_(s)

    Das Ergebnis muss im Post-State gültig sein, kann jedoch im Post-State NULL sein.Result must be valid in post-state, but may be null in post-state. Zeigt auf einen gültigen Puffer von size- s Elementen.Points to valid buffer of size s elements.

  • _Outref_result_bytebuffer_maybenull_(s)

    Das Ergebnis muss im Post-State gültig sein, kann jedoch im Post-State NULL sein.Result must be valid in post-state, but may be null in post-state. Zeigt auf einen gültigen Puffer mit einer Größe von s Bytes.Points to valid buffer of size s bytes.

  • _Outref_result_buffer_to_maybenull_(s, c)

    Das Ergebnis muss im Post-State gültig sein, kann jedoch im Post-State NULL sein.Result must be valid in post-state, but may be null in post-state. Zeigt auf den Puffer von s Elementen, von denen der erste c gültig ist.Points to buffer of s elements, of which the first c are valid.

  • _Outref_result_bytebuffer_to_maybenull_(s,c)

    Das Ergebnis muss im Post-State gültig sein, kann jedoch im Post-Zustand NULL sein.Result must be valid in post-state, but may be null in post state. Zeigt auf den Puffer von s bytes, von denen der erste c gültig ist.Points to buffer of s bytes of which the first c are valid.

  • _Outref_result_buffer_all_maybenull_(s)

    Das Ergebnis muss im Post-State gültig sein, kann jedoch im Post-Zustand NULL sein.Result must be valid in post-state, but may be null in post state. Verweist auf einen gültigen Puffer der s gültigen Größe von Elementen.Points to valid buffer of size s valid elements.

  • _Outref_result_bytebuffer_all_maybenull_(s)

    Das Ergebnis muss im Post-State gültig sein, kann jedoch im Post-Zustand NULL sein.Result must be valid in post-state, but may be null in post state. Verweist auf einen gültigen Puffer von s Bytes gültiger-Elemente.Points to valid buffer of s bytes of valid elements.

RückgabewerteReturn values

Der Rückgabewert einer Funktion ähnelt einem _Out_ Parameter, befindet sich jedoch auf einer anderen Ebene von "de-Reference", und Sie müssen das Konzept des Zeigers auf das Ergebnis nicht überprüfen.The return value of a function resembles an _Out_ parameter but is at a different level of de-reference, and you don't have to consider the concept of the pointer to the result. Für die folgenden Anmerkungen ist der Rückgabewert das mit Anmerkungen versehene Objekt – ein Skalar, ein Zeiger auf eine Struktur oder ein Zeiger auf einen Puffer.For the following annotations, the return value is the annotated object—a scalar, a pointer to a struct, or a pointer to a buffer. Diese Anmerkungen haben die gleiche Semantik wie die entsprechende _Out_ Anmerkung.These annotations have the same semantics as the corresponding _Out_ annotation.

_Ret_z_
_Ret_writes_(s)
_Ret_writes_bytes_(s)
_Ret_writes_z_(s)
_Ret_writes_to_(s,c)
_Ret_writes_maybenull_(s)
_Ret_writes_to_maybenull_(s)
_Ret_writes_maybenull_z_(s)

_Ret_maybenull_
_Ret_maybenull_z_
_Ret_null_
_Ret_notnull_
_Ret_writes_bytes_to_
_Ret_writes_bytes_maybenull_
_Ret_writes_bytes_to_maybenull_

Zeichen folgen Parameter formatierenFormat string parameters

  • _Printf_format_string_ Gibt an, dass der Parameter eine Format Zeichenfolge für die Verwendung in einem- printf Ausdruck ist._Printf_format_string_ Indicates that the parameter is a format string for use in a printf expression.

    BeispielExample

    int MyPrintF(_Printf_format_string_ const wchar_t* format, ...)
    {
           va_list args;
           va_start(args, format);
           int ret = vwprintf(format, args);
           va_end(args);
           return ret;
    }
    
  • _Scanf_format_string_ Gibt an, dass der Parameter eine Format Zeichenfolge für die Verwendung in einem- scanf Ausdruck ist._Scanf_format_string_ Indicates that the parameter is a format string for use in a scanf expression.

    BeispielExample

    int MyScanF(_Scanf_format_string_ const wchar_t* format, ...)
    {
           va_list args;
           va_start(args, format);
           int ret = vwscanf(format, args);
           va_end(args);
           return ret;
    }
    
  • _Scanf_s_format_string_ Gibt an, dass der Parameter eine Format Zeichenfolge für die Verwendung in einem- scanf_s Ausdruck ist._Scanf_s_format_string_ Indicates that the parameter is a format string for use in a scanf_s expression.

    BeispielExample

    int MyScanF_s(_Scanf_s_format_string_ const wchar_t* format, ...)
    {
           va_list args;
           va_start(args, format);
           int ret = vwscanf_s(format, args);
           va_end(args);
           return ret;
    }
    

Andere gängige AnmerkungenOther common annotations

Anmerkungen und BeschreibungenAnnotations and descriptions

  • _In_range_(low, hi)

    _Out_range_(low, hi)

    _Ret_range_(low, hi)

    _Deref_in_range_(low, hi)

    _Deref_out_range_(low, hi)

    _Deref_inout_range_(low, hi)

    _Field_range_(low, hi)

    Der Parameter, das Feld oder das Ergebnis befindet sich im Bereich (einschließlich) von low bis hi .The parameter, field, or result is in the range (inclusive) from low to hi. Entspricht dem, _Satisfies_(_Curr_ >= low && _Curr_ <= hi) das auf das mit Anmerkungen versehene Objekt in Verbindung mit den entsprechenden Bedingungen vor oder nach Bundesstaat angewendet wird.Equivalent to _Satisfies_(_Curr_ >= low && _Curr_ <= hi) that is applied to the annotated object together with the appropriate pre-state or post-state conditions.

    Wichtig

    Obwohl die Namen "in" und "out" enthalten, gilt die Semantik _In_ von _Out_ und nicht für diese Anmerkungen.Although the names contain "in" and "out", the semantics of _In_ and _Out_ do not apply to these annotations.

  • _Pre_equal_to_(expr)

    _Post_equal_to_(expr)

    Der mit Anmerkungen versehene Wert ist genau expr .The annotated value is exactly expr. Entspricht dem, _Satisfies_(_Curr_ == expr) das auf das mit Anmerkungen versehene Objekt in Verbindung mit den entsprechenden Bedingungen vor oder nach Bundesstaat angewendet wird.Equivalent to _Satisfies_(_Curr_ == expr) that is applied to the annotated object together with the appropriate pre-state or post-state conditions.

  • _Struct_size_bytes_(size)

    Gilt für eine Struktur-oder Klassen Deklaration.Applies to a struct or class declaration. Gibt an, dass ein gültiges Objekt dieses Typs größer als der deklarierte Typ und mit der Anzahl von Bytes sein kann, die von angegeben werden size .Indicates that a valid object of that type may be larger than the declared type, with the number of bytes being given by size. Beispiel:For example:

    typedef _Struct_size_bytes_(nSize) struct MyStruct { size_t nSize; ... };

    Die Puffergröße eines Parameters pM vom Typ in Byte MyStruct * wird dann wie folgt angenommen:The buffer size in bytes of a parameter pM of type MyStruct * is then taken to be:

    min(pM->nSize, sizeof(MyStruct))

Weitere InformationenSee also