Freigeben über

Hinzufügen einer Anmerkung zu Funktionsparametern und Rückgabewerten

  • Artikel

In diesem Artikel werden typische Verwendungen von Anmerkungen für ParameterSkalare der einfachen Funktion und Zeiger auf Strukturen und Klasse- und auf die meisten Arten Puffer.In diesem Artikel wird auch allgemeine Verwendungsmuster für Anmerkungen an.Weitere Anmerkungen, die mit Funktionen verknüpft werden, finden Sie unter Hinzufügen einer Anmerkung zum Funktionsverhalten

Zeiger-Parameter

Für die Anmerkungen in der folgenden Tabelle, wenn ein Zeigerparameter kommentiert wird, meldet der Analyzer ein Fehler, wenn der Zeiger NULL ist.Dies gilt zu Zeigern und auf jedes Datenelement zu, in dem gezeigt wird.

Anmerkung

Beschreibung

_In_

Kommentiert Eingabeparameter, die Skalare, Strukturen, Zeiger auf Strukturen usw. sind.Kann in einfachen Skalaren explizit verwendet werden.Der Parameter muss im Vor-Zustand gültig sein und nicht geändert werden.

_Out_

Kommentiert Ausgabeparameter, die Skalare, Strukturen, Zeiger auf Strukturen usw. sind.Wenden Sie dieses nicht auf ein Objekt, das ein Beispiel werden nicht zurückgeben kann, ein Skalar, das als Wert übergeben wird.Der Parameter muss nicht, im Vor-Zustand gültig sein muss jedoch im Nach-Zustand gültig sein.

_Inout_

Kommentiert einen Parameter, der von der Funktion geändert wird.Sie muss im Vor-Zustand und im Nach-Zustand gültig sein, jedoch wird angenommen, dass verschiedene Werte vor und nach dem Aufruf von haben.muss auf einen änderbaren Wert gelten.

_In_z_

Ein Zeiger auf eine auf NULL endende Zeichenfolge, die als Eingabe verwendet wird.Die Zeichenfolge muss im Vor-Zustand gültig sein.Varianten von PSTR, die bereits die richtigen Anmerkungen haben, werden bevorzugt.

_Inout_z_

Ein Zeiger auf ein mit Null endendes Zeichenarray, die geändert werden.Es muss gültig sein, vor und nach der Aufruf, aber der Wert angenommen wird geändert haben.Das NULL-Zeichen wird verschoben, sondern nur auf die Elemente bis zum ursprünglichen NULL-Zeichen werden zugegriffen werden.

_In_reads_(s)

_In_reads_bytes_(s)

Ein Zeiger auf ein Array, das von der Funktion gelesen wird.Das Array besteht aus Größe s Elementen, die gültig sein müssen.

Die _bytes_ Variante gibt die Größe in Bytes anstelle der Elemente.Verwenden Sie dieses nur, wenn die Größe nicht als Elemente dargestellt werden kann.Beispielsweise können char Zeichenfolgen die _bytes_ Variante nur verwenden, wenn eine ähnliche Funktion, die wchar_t verwendet, wurde.

_In_reads_z_(s)

Ein Zeiger auf ein Array, das auf NULL endende ist und eine bekannte Größe besitzt.Die Elemente bis zur NULL Abschlusszeichen- oder zu s, wenn keine NULL gibt, Abschlusszeichen-müssen im Vor-Zustand gültig sein.Wenn die Größe in Bytes bezeichnet, Skalierung s durch die Elementgröße.

_In_reads_or_z_(s)

Ein Zeiger auf ein Array, das auf NULL endende ist oder eine bekannte Größe besitzt oder beides.Die Elemente bis zur NULL Abschlusszeichen- oder zu s, wenn keine NULL gibt, Abschlusszeichen-müssen im Vor-Zustand gültig sein.Wenn die Größe in Bytes bezeichnet, Skalierung s durch die Elementgröße.(Wird für die strn Familie.)

_Out_writes_(s)

_Out_writes_bytes_(s)

Ein Zeiger auf ein Array s-Elementen (bzw.Bytes) die von der Funktion geschrieben werden.Die Arrayelemente müssen nicht im Vor-Zustand gültig sein, und die Anzahl von Elementen, die im Nach-Zustand gültig sind, ist nicht angegeben.Wenn es Anmerkungen auf dem Parametertyp gibt, werden sie im Nach-Zustand angewendet.Betrachten Sie hierzu den folgenden Beispielcode:

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 p1 bereit.MyStringCopy macht mehrere aus den Elementen gültig.Wichtiger, bedeutet dies _Null_terminated_ Anmerkung auf PWSTR, dass p1 im Nach-Zustand auf NULL endende ist.Auf diese Weise ist die Anzahl der gültigen Elementen noch ordnungsgemäß definiert, aber eine bestimmte Elementanzahl ist nicht erforderlich.

Die _bytes_ Variante gibt die Größe in Bytes anstelle der Elemente.Verwenden Sie dieses nur, wenn die Größe nicht als Elemente dargestellt werden kann.Beispielsweise können char Zeichenfolgen die _bytes_ Variante nur verwenden, wenn eine ähnliche Funktion, die wchar_t verwendet, wurde.

_Out_writes_z_(s)

Ein Zeiger auf ein Array s-Elementen.Die Elemente müssen nicht im Vor-Zustand gültig sein.Im Nach-Zustand Geschenk-müssen die Elemente oben durch die NULL, Abschlusszeichen-die sein muss, gültig sein.Wenn die Größe in Bytes bezeichnet, Skalierung s durch die Elementgröße.

_Inout_updates_(s)

_Inout_updates_bytes_(s)

Ein Zeiger auf ein Array, das der Funktion gelesen und geschrieben wird.Es besteht aus Größe s Elementen, und gültig Vor-Zustand im und im Nach-Zustand.

Die _bytes_ Variante gibt die Größe in Bytes anstelle der Elemente.Verwenden Sie dieses nur, wenn die Größe nicht als Elemente dargestellt werden kann.Beispielsweise können char Zeichenfolgen die _bytes_ Variante nur verwenden, wenn eine ähnliche Funktion, die wchar_t verwendet, wurde.

_Inout_updates_z_(s)

Ein Zeiger auf ein Array, das auf NULL endende ist und eine bekannte Größe besitzt.Die Elemente bis einschließlich dem NULL-Abschlusszeichen – das vorhanden sein muss – müssen im Vor-Zustand und im Nach-Zustand gültig sein.Der Wert im Nach-Zustand wird davon ausgegangen, dass auf dem Wert im Vor-Zustand unterschiedlich sein; Dies schließt auch den Speicherort des NULL-Abschlusszeichens ein.Wenn die Größe in Bytes bezeichnet, Skalierung s durch die Elementgröße.

_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 s-Elementen.Die Elemente müssen nicht im Vor-Zustand gültig sein.Im Nach-Zustand die Elemente bis zu c- Thelement muss gültig sein.Wenn die Größe in Bytes bekannt ist, verwenden s Skala und c durch die Elementgröße oder die _bytes_ Variante, die als definiert ist:

   _Out_writes_to_(_Old_(s), _Old_(s))
   _Out_writes_bytes_to_(_Old_(s), _Old_(s))

Das heißt, ist jedes Element, das im Puffer bis zu s im Vor-Zustand vorhanden ist, im Nach-Zustand gültig.Beispiel:

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.Es besteht aus Größe s Elementen, die im Vor-Zustand gültig sein müssen, und c-Elemente müssen im Nach-Zustand gültig sein.

Die _bytes_ Variante gibt die Größe in Bytes anstelle der Elemente.Verwenden Sie dieses nur, wenn die Größe nicht als Elemente dargestellt werden kann.Beispielsweise können char Zeichenfolgen die _bytes_ Variante nur verwenden, wenn eine ähnliche Funktion, die wchar_t verwendet, wurde.

_Inout_updates_all_(s)

_Inout_updates_bytes_all_(s)

Ein Zeiger auf ein Array, das von der Funktion von Größe s Elementen gelesen und geschrieben wird.Definiert als Äquivalent zu:

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

Das heißt, ist jedes Element, das im Puffer bis zu s im Vor-Zustand vorhanden ist, Vor-Zustand im und im Nach-Zustand gültig.

Die _bytes_ Variante gibt die Größe in Bytes anstelle der Elemente.Verwenden Sie dieses nur, wenn die Größe nicht als Elemente dargestellt werden kann.Beispielsweise können char Zeichenfolgen die _bytes_ Variante nur verwenden, wenn eine ähnliche Funktion, die wchar_t verwendet, wurde.

_In_reads_to_ptr_(p)

Ein Zeiger auf das für ein Array der Ausdruck p - _Curr_ (das heißt, p minus _Curr_) wird durch den entsprechenden Sprachenstandard definiert.Die Elemente vor p müssen im Vor-Zustand gültig sein.

_In_reads_to_ptr_z_(p)

Ein Zeiger auf das für ein mit Null endendes Array der Ausdruck p - _Curr_ (das heißt, p minus _Curr_) wird durch den entsprechenden Sprachenstandard definiert.Die Elemente vor p müssen im Vor-Zustand gültig sein.

_Out_writes_to_ptr_(p)

Ein Zeiger auf das für ein Array der Ausdruck p - _Curr_ (das heißt, p minus _Curr_) wird durch den entsprechenden Sprachenstandard definiert.Die Elemente vor p müssen nicht im Vor-Zustand gültig sein und müssen im Nach-Zustand gültig sein.

_Out_writes_to_ptr_z_(p)

Ein Zeiger auf das für ein mit Null endendes Array der Ausdruck p - _Curr_ (das heißt, p minus _Curr_) wird durch den entsprechenden Sprachenstandard definiert.Die Elemente vor p müssen nicht im Vor-Zustand gültig sein und müssen im Nach-Zustand gültig sein.

Optionale Zeiger-Parameter

Wenn eine Zeigerparameteranmerkung _opt_ umfasst, wird damit angezeigt, dass der Parameter NULL sein kann.Andernfalls führt die Anmerkung sein wie die Version aus, die nicht _opt_ umfasst.Im Folgenden finden Sie eine Liste der _opt_ Varianten der Zeigerparameteranmerkungen:

_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-Parameter

Ausgabezeigerparameter erfordern spezielle Notation, NULLNess auf dem Parameter Eindeutigkeit herzustellen und gezeigte-zum Speicherort.

Anmerkung

Beschreibung

_Outptr_

Parameter darf nicht NULL sein, und im Nach-Zustand, der gezeigte-zum Speicherort nicht sein kann NULL ist und muss gültig sein.

_Outptr_opt_

Parameter NULL ist, aber im Nach-Zustand, der gezeigte-zum Speicherort nicht sein kann NULL ist und muss gültig sein.

_Outptr_result_maybenull_

Parameter darf nicht NULL sein, und im Nach-Zustand, der gezeigte-zum Speicherort befindet, kann NULL sein.

_Outptr_opt_result_maybenull_

Parameter kann NULL und im Nach-Zustand, der gezeigte-zum Speicherort befindet, kann NULL sein.

In der folgenden Tabelle werden zusätzliche Teilzeichenfolgen in den Anmerkungsnamen eingefügt, um die Wichtigkeit der Anmerkung weiter zu qualifizieren.Die verschiedenen Teilzeichenfolgen sind _z, _COM_, _buffer_, _bytebuffer_ und _to_.

Wichtiger HinweisWichtig

Wenn die Schnittstelle, die Sie kommentieren, COM ist, verwenden Sie das COM-Formular dieser Anmerkungen.Verwenden Sie nicht die COM-Anmerkungen bei jeder anderen Typschnittstelle.

Anmerkung

Beschreibung

_Outptr_result_z_

_Outptr_opt_result_z_

_Outptr_result_maybenull_z_

_Ouptr_opt_result_maybenull_z_

Der zurückgegebene Zeiger verfügt über die _Null_terminated_ Anmerkung.

_COM_Outptr_

_COM_Outptr_opt_

_COM_Outptr_result_maybenull_

_COM_Outptr_opt_result_maybenull_

Der zurückgegebene Zeiger verfügt über COM-Semantik und gilt daher eine _On_failure_ Nachbedingung, dass der zurückgegebene Zeiger NULL ist.

_Outptr_result_buffer_(s)

_Outptr_result_bytebuffer_(s)

_Outptr_opt_result_buffer_(s)

_Outptr_opt_result_bytebuffer_(s)

Der zurückgegebene Zeiger zeigt auf einen gültigen Puffer von Größe s Elementen oder 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 verweist auf einen Puffer von Größe s Elementen oder Bytes, von denen erste c gültig sind.

Bestimmte Schnittstellenkonventionen wird davon ausgegangen, dass Ausgabeparameter auf Fehler annulliert werden.Neben explizit COM-Code werden die Formulare in der folgenden Tabelle bevorzugt.Für COM-Code verwenden Sie die entsprechenden COM-Formulare, die im vorherigen Abschnitt aufgeführt werden.

Anmerkung

Beschreibung

_Result_nullonfailure_

Ändert andere Anmerkungen.Das Ergebnis wird festgelegt, um ungültig zu machen, wenn die Funktion fehlschlägt.

_Result_zeroonfailure_

Ändert andere Anmerkungen.Das Ergebnis wird auf Null gestellt, wenn die Funktion fehlschlägt.

_Outptr_result_nullonfailure_

Der zurückgegebene Zeiger zeigt auf einen gültigen Puffer, wenn die Funktion folgt, oder auf NULL, wenn die Funktion fehlschlägt.Diese Anmerkung ist für einen NichtOPTIONAL-Parameter.

_Outptr_opt_result_nullonfailure_

Der zurückgegebene Zeiger zeigt auf einen gültigen Puffer, wenn die Funktion folgt, oder auf NULL, wenn die Funktion fehlschlägt.Diese Anmerkung ist für einen optionalen Parameter.

_Outref_result_nullonfailure_

Der zurückgegebene Zeiger zeigt auf einen gültigen Puffer, wenn die Funktion folgt, oder auf NULL, wenn die Funktion fehlschlägt.Diese Anmerkung ist für einen Verweisparameter.

Ausgabe-Verweisparameter

Eine häufige Verwendung von dem Verweisparameter ist für Ausgabeparameter.Als einfache Ausgabereferenz Parameter – z. B. int&-_Out_ stellt die korrekte Semantik.Wenn der Ausgabewert einer Zeiger-für Beispiel int *&- die entsprechenden Zeigeranmerkungen ist, wie _Outptr_ int ** nicht die richtige Semantik angeben.Um die Semantik von Ausgabeverweisparametern für Zeigertypen kurz auszudrücken, verwenden Sie diese zusammengesetzten Anmerkungen:

Anmerkung

Beschreibung

_Outref_

Ergebnis muss im Nach-Zustand gültig sein und darf nicht NULL sein.

_Outref_result_maybenull_

Ergebnis muss im Nach-Zustand gültig sein, aber möglicherweise im Nach-Zustand NULL.

_Outref_result_buffer_(s)

Ergebnis muss im Nach-Zustand gültig sein und darf nicht NULL sein.Zeigt auf einen gültigen Puffer von Größe s Elementen.

_Outref_result_bytebuffer_(s)

Ergebnis muss im Nach-Zustand gültig sein und darf nicht NULL sein.Zeigt auf einen gültigen Puffer von Größe s Bytes.

_Outref_result_buffer_to_(s, c)

Ergebnis muss im Nach-Zustand gültig sein und darf nicht NULL sein.Zeigt auf den Puffer von s-Elemente, von denen erste c gültig sind.

_Outref_result_bytebuffer_to_(s, c)

Ergebnis muss im Nach-Zustand gültig sein und darf nicht NULL sein.Zeigt auf den Puffer von s Bytes, von denen erste c gültig sind.

_Outref_result_buffer_all_(s)

Ergebnis muss im Nach-Zustand gültig sein und darf nicht NULL sein.Zeigt auf einen gültigen Puffer von Größe s gültigen Elementen.

_Outref_result_bytebuffer_all_(s)

Ergebnis muss im Nach-Zustand gültig sein und darf nicht NULL sein.Zeigt auf einen gültigen Puffer von s Bytes gültigen Elementen.

_Outref_result_buffer_maybenull_(s)

Ergebnis muss im Nach-Zustand gültig sein, aber möglicherweise im Nach-Zustand NULL.Zeigt auf einen gültigen Puffer von Größe s Elementen.

_Outref_result_bytebuffer_maybenull_(s)

Ergebnis muss im Nach-Zustand gültig sein, aber möglicherweise im Nach-Zustand NULL.Zeigt auf einen gültigen Puffer von Größe s Bytes.

_Outref_result_buffer_to_maybenull_(s, c)

Ergebnis muss im Nach-Zustand gültig sein, aber möglicherweise im Nach-Zustand NULL.Zeigt auf den Puffer von s-Elemente, von denen erste c gültig sind.

_Outref_result_bytebuffer_to_maybenull_(s,c)

Ergebnis muss im Nach-Zustand gültig sein, aber möglicherweise im Nachbedingung NULL.Zeigt auf den Puffer von s Bytes, von denen erste c gültig sind.

_Outref_result_buffer_all_maybenull_(s)

Ergebnis muss im Nach-Zustand gültig sein, aber möglicherweise im Nachbedingung NULL.Zeigt auf einen gültigen Puffer von Größe s gültigen Elementen.

_Outref_result_bytebuffer_all_maybenull_(s)

Ergebnis muss im Nach-Zustand gültig sein, aber möglicherweise im Nachbedingung NULL.Zeigt auf einen gültigen Puffer von s Bytes gültigen Elementen.

Rückgabewerte

Der Rückgabewert einer Funktion ähnelt, einem _Out_-Parameter ist jedoch auf einer anderen Ebene von De-reference, und Sie müssen das Konzept des Zeigers nicht zum Ergebnis berücksichtigen.Für die folgenden Anmerkungen ist der Rückgabewert das Objekt-einskalar mit Anmerkungen, ein Zeiger auf eine Struktur oder ein Zeiger auf einen Puffer.Diese Anmerkungen weisen die gleiche Semantik wie die entsprechende _Out_ Anmerkung.

_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_

Andere allgemeine Anmerkungen

Anmerkung

Beschreibung

_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 ist im Bereich (einschließlich) von low zu hi.Entspricht _Satisfies_(_Curr_ >= low && _Curr_ <= hi), die dem Objekt mit Anmerkungen zusammen mit den entsprechenden Vor-Zustands- oder Nach-Zustandszuständen angewendet wird.

Wichtiger HinweisWichtig
Obwohl die Namen "in" und "out" enthalten, gelten die Semantik von _In_ und _Out_not auf diese Anmerkungen zu.

_Pre_equal_to_(expr)

_Post_equal_to_(expr)

Der Wert mit Anmerkungen ist genau expr.Entspricht _Satisfies_(_Curr_ == expr), die dem Objekt mit Anmerkungen zusammen mit den entsprechenden Vor-Zustands- oder Nach-Zustandszuständen angewendet wird.

_Struct_size_bytes_(size)

Gilt für eine Struktur oder eine Klassendeklaration zu.Gibt an, dass ein gültiges Objekt dieses Typs möglicherweise größer als der deklarierten Typ ist, mit der Anzahl der Bytes an, die von size angegeben werden.Beispiel:

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

Die Puffergröße in Bytes eines Parameters pM des Typs MyStruct * wird dann verwendet, um zu sein:

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

Verwandte Ressourcen

Codeanalyse-Team-Blog

Siehe auch

Referenz

Hinzufügen einer Anmerkung zum Funktionsverhalten

Hinzufügen einer Anmerkung zu Strukturen und Klassen

Hinzufügen einer Anmerkung zum Sperrverhalten

Angeben, wann und wo eine Anmerkung gültig ist

Systeminterne Funktionen

Empfohlene Vorgehensweisen und Beispiele (SAL)

Konzepte

Einführung in SAL

Weitere Ressourcen

Verwenden von SAL-Anmerkungen zum Reduzieren von C/C++-Codefehlern