Dodawanie adnotacji do parametrów funkcji i zwracanych wartości

Artykuł
03/12/2013

W tym artykule opisano typowe zastosowania adnotacji parametry funkcji prosty — liczba funkcji skalarnych i wskaźniki do struktur i klasy — i w większości wypadków buforów.W tym artykule przedstawiono również wspólnych wzorów użycia dla adnotacji.Aby uzyskać dodatkowe adnotacje, które odnoszą się do funkcji zobaczZachowanie funkcji dodawania adnotacji

Parametry wskaźnika

Adnotacji w poniższej tabeli gdy parametr wskaźnika jest jednoczesnym odnotowaniu, analizator zgłasza błąd Jeżeli wskaźnik ma wartość null.Dotyczy to wskaźniki i do dowolnego elementu danych, który jest wskazywany.

Adnotacja	Opis
_In_	Opisz parametrów wejściowych, które są wielkości skalarne, struktury, wskaźniki do struktur i tym podobne.Jawnie były użytkowane na prostych funkcji skalarnych.Parametr musi być prawidłowa w pre-state i nie będzie modyfikowana.
_Out_	Opisz parametrów wyjściowych, które są wielkości skalarne, struktury, wskaźniki do struktur i tym podobne.Nie dotyczą tego obiektu, która nie zwraca wartości — na przykład, wartość skalarną, który jest przekazywany przez wartość.Parametr nie musi być ważny, w pre-state, ale muszą być prawidłowe w post-state.
_Inout_	Opisz parametru, która ma zostać zmieniona przez funkcję.Muszą być prawidłowe w pre-state i post-state, ale zakłada się, że różne wartości, przed i po wywołaniu.Stosuje się do wartości można modyfikować.
_In_z_	Wskaźnik na ciąg zakończony znakiem null, który jest używany jako dane wejściowe.Ciąg musi być prawidłową w pre-state.Warianty PSTR, które już poprawne adnotacjami, są preferowane.
_Inout_z_	Wskaźnik do tablicy zakończonego znakiem null, która będzie modyfikowana.Musi być prawidłową przed i po wywołaniu, ale przyjmuje się, że zostały zmienione.Null terminator, które mogą być przenoszone, ale mogą być dostępne tylko elementy do oryginalnego terminator null.
_In_reads_(s) _In_reads_bytes_(s)	Wskaźnik do tablicy, która jest odczytywana przez funkcję.Tablica ma wielkość s elementów, z których wszystkie muszą być prawidłowe. _bytes_ Wariant daje rozmiar w bajtach, zamiast elementów.Użyj go, tylko, jeśli rozmiar nie może być wyrażona jako elementy.Na przykład char użyłaby ciągi _bytes_ wariant tylko wtedy, gdy podobne funkcja wykorzystuje wchar_t się.
_In_reads_z_(s)	Wskaźnik do tablicy, zakończony wartością zerową i ma znanej wielkości.Elementy do null terminator — lub s Jeśli nie ma żadnych terminator null — muszą być prawidłowe w pre-state.Jeśli rozmiar jest znany w bajtach, skalować s przez rozmiar elementu.
_In_reads_or_z_(s)	Wskaźnik do tablicy, które jest zerem lub ma znanej wielkości lub obu.Elementy do null terminator — lub s Jeśli nie ma żadnych terminator null — muszą być prawidłowe w pre-state.Jeśli rozmiar jest znany w bajtach, skalować s przez rozmiar elementu.(Używane do strn rodziny.)
_Out_writes_(s) _Out_writes_bytes_(s)	Wskaźnik do tablicy s elementy (ODP.bajtów) które będą zapisywane przez funkcję.Elementy tablicy nie trzeba być ważny, w pre-state, a liczba elementów, które są prawidłowe w post-state jest nieokreślony.W przypadku adnotacje na typ parametru, są one stosowane w post-state.Na przykład rozważmy następujący kod. `typedef _Null_terminated_ wchar_t *PWSTR; void MyStringCopy(_Out_writes_ (size) PWSTR p1, _In_ size_t size, _In_ PWSTR p2);` W tym przykładzie, obiekt wywołujący zapewnia bufor o size elementy dla p1.MyStringCopysprawia, że niektóre z tych elementów prawidłowy.Co ważniejsze _Null_terminated_ adnotacji na PWSTR oznacza, że p1 jest zakończony znakiem null w post-state.W ten sposób liczba ważne elementy jest nadal wyraźnie określone, ale wynik jest określony element nie jest wymagane. _bytes_ Wariant daje rozmiar w bajtach, zamiast elementów.Użyj go, tylko, jeśli rozmiar nie może być wyrażona jako elementy.Na przykład char użyłaby ciągi _bytes_ wariant tylko wtedy, gdy podobne funkcja wykorzystuje wchar_t się.
_Out_writes_z_(s)	Wskaźnik do tablicy s elementy.Elementy nie trzeba być ważny, w pre-state.W post-state, elementy w górę przez null terminator — musi być obecny — musi być prawidłowa.Jeśli rozmiar jest znany w bajtach, skalować s przez rozmiar elementu.
_Inout_updates_(s) _Inout_updates_bytes_(s)	Wskaźnik do tablicy, która jest zarówno odczytać i napisane w funkcji.To ma wielkość s elementów i prawidłowe w pre-state i post-state. _bytes_ Wariant daje rozmiar w bajtach, zamiast elementów.Użyj go, tylko, jeśli rozmiar nie może być wyrażona jako elementy.Na przykład char użyłaby ciągi _bytes_ wariant tylko wtedy, gdy podobne funkcja wykorzystuje wchar_t się.
_Inout_updates_z_(s)	Wskaźnik do tablicy, zakończony wartością zerową i ma znanej wielkości.Elementy w górę przez null terminator — musi być obecny — muszą być prawidłowe w pre-state i post-state.Wartość w post-state zakłada się różnić od wartości w pre-state; zawiera lokalizację null terminator.Jeśli rozmiar jest znany w bajtach, skalować s przez rozmiar elementu.
_Out_writes_to_(s,c) _Out_writes_bytes_to_(s,c) _Out_writes_all_(s) _Out_writes_bytes_all_(s)	Wskaźnik do tablicy s elementy.Elementy nie trzeba być ważny, w pre-state.W post-state, elementy do c-Ty element musi być prawidłowy.Jeśli rozmiar jest znany w bajtach, skalować s i c przez rozmiar elementu lub użycia _bytes_ wariant, która jest zdefiniowana jako: `_Out_writes_to_(_Old_(s), _Old_(s)) _Out_writes_bytes_to_(_Old_(s), _Old_(s))` Innymi słowy, każdy element, który znajduje się w buforze do s w pre-state jest prawidłowa w post-state.Na przykład: `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)	Wskaźnik do tablicy, co jest zarówno odczytywana i zapisywana przez funkcję.To o rozmiarze s elementów, z których wszystkie muszą być ważny, w pre-state, i c w post-state elementy muszą być prawidłowe. _bytes_ Wariant daje rozmiar w bajtach, zamiast elementów.Użyj go, tylko, jeśli rozmiar nie może być wyrażona jako elementy.Na przykład char użyłaby ciągi _bytes_ wariant tylko wtedy, gdy podobne funkcja wykorzystuje wchar_t się.
_Inout_updates_all_(s) _Inout_updates_bytes_all_(s)	Wskaźnik do tablicy, co jest zarówno odczytywana i zapisywana przez funkcję rozmiar s elementy.Określone jako równoważne: `_Inout_updates_to_(_Old_(s), _Old_(s)) _Inout_updates_bytes_to_(_Old_(s), _Old_(s))` Innymi słowy, każdy element, który znajduje się w buforze do s w pre-state jest prawidłowa w pre-state i post-state. _bytes_ Wariant daje rozmiar w bajtach, zamiast elementów.Użyj go, tylko, jeśli rozmiar nie może być wyrażona jako elementy.Na przykład char użyłaby ciągi _bytes_ wariant tylko wtedy, gdy podobne funkcja wykorzystuje wchar_t się.
_In_reads_to_ptr_(p)	Wskaźnik do tablicy, dla którego wyrażenie p - _Curr_ (oznacza to, p minus _Curr_) jest zdefiniowany przez standard odpowiedniego języka.Elementy przed p muszą być prawidłowe w pre-state.
_In_reads_to_ptr_z_(p)	Wskaźnik do tablicy zakończonym znakiem null, dla którego wyrażenie p - _Curr_ (oznacza to, p minus _Curr_) jest zdefiniowany przez standard odpowiedniego języka.Elementy przed p muszą być prawidłowe w pre-state.
_Out_writes_to_ptr_(p)	Wskaźnik do tablicy, dla którego wyrażenie p - _Curr_ (oznacza to, p minus _Curr_) jest zdefiniowany przez standard odpowiedniego języka.Elementy przed p nie trzeba być ważny, w pre-state i musi być ważne w post-state.
_Out_writes_to_ptr_z_(p)	Wskaźnik do tablicy zakończonym znakiem null, dla którego wyrażenie p - _Curr_ (oznacza to, p minus _Curr_) jest zdefiniowany przez standard odpowiedniego języka.Elementy przed p nie trzeba być ważny, w pre-state i musi być ważne w post-state.

Parametry opcjonalne wskaźnika

Kiedy wskaźnik parametr zawiera _opt_, wskazuje, że parametr może być null.W przeciwnym razie, adnotacja wykonuje, taka sama jak wersja, który nie zawiera _opt_.Oto lista _opt_ wariantów adnotacje parametr wskaźnika:

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

Wskaźnik parametrów wyjściowych

Parametry wyjściowe wskaźnik wymagają specjalnych notacji, aby odróżnić null ności na parametr i wskazał miejsce.

Adnotacja	Opis
_Outptr_	Parametr nie może mieć wartości null, a w post-state wskazał miejsce nie może być zerowy i muszą być prawidłowe.
_Outptr_opt_	Parametr może mieć wartości null, ale w post-state wskazał miejsce nie może być zerowy i muszą być prawidłowe.
_Outptr_result_maybenull_	Parametr nie może mieć wartości null, a w post-state wskazał miejsce może być równa null.
_Outptr_opt_result_maybenull_	Parametr może mieć wartości null, a w post-state wskazał miejsce może być równa null.

W poniższej tabeli dodatkowe podciągów są wstawiane do nazwę adnotacji, aby bardziej szczegółowo. rozumieniu adnotację.The various substrings are _z, _COM_, _buffer_, _bytebuffer_, and _to_.

Ważne
Jeśli interfejs, który są adnotacje COM, formularz COM tych adnotacji.Nie należy używać adnotacje COM z żadnego innego typu interfejsu.

Adnotacja	Opis
_Outptr_result_z_ _Outptr_opt_result_z_ _Outptr_result_maybenull_z_ _Ouptr_opt_result_maybenull_z_	Zwrócony wskaźnik ma _Null_terminated_ adnotacji.
_COM_Outptr_ _COM_Outptr_opt_ _COM_Outptr_result_maybenull_ _COM_Outptr_opt_result_maybenull_	Zwrócony wskaźnik ma semantykę COM i dlatego _On_failure_ post-condition, że zwrócony wskaźnik ma wartość null.
_Outptr_result_buffer_(s) _Outptr_result_bytebuffer_(s) _Outptr_opt_result_buffer_(s) _Outptr_opt_result_bytebuffer_(s)	Zwrócony wskaźnik wskazuje na nieprawidłowy bufor o rozmiarze s elementów lub bajtów.
_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)	Zwrócony wskaźnik wskazuje bufor o rozmiarze s elementów lub bajtów, których pierwszy c są prawidłowe.

Pewnych Konwencji interfejsu przypuszczać, że w przypadku awarii są zniweczone parametrów wyjściowych.Z wyjątkiem jawnie COM kodu formularze w poniższej tabeli są preferowane.Kod, COM należy użyć odpowiednie formularze COM, które są wymienione w poprzedniej sekcji.

Adnotacja	Opis
_Result_nullonfailure_	Modyfikuje innych adnotacji.Wynik jest równa null, jeśli funkcja zakończy się niepowodzeniem.
_Result_zeroonfailure_	Modyfikuje innych adnotacji.Wynik jest równa zero, jeśli ta funkcja zawiedzie.
_Outptr_result_nullonfailure_	Zwrócony wskaźnik wskazuje na ważnego bufora, jeśli funkcja się powiedzie, lub null, jeśli funkcja zakończy się niepowodzeniem.Ta adnotacja jest obowiązkowe parametru.
_Outptr_opt_result_nullonfailure_	Zwrócony wskaźnik wskazuje na ważnego bufora, jeśli funkcja się powiedzie, lub null, jeśli funkcja zakończy się niepowodzeniem.Ta adnotacja jest parametr opcjonalny.
_Outref_result_nullonfailure_	Zwrócony wskaźnik wskazuje na ważnego bufora, jeśli funkcja się powiedzie, lub null, jeśli funkcja zakończy się niepowodzeniem.Ta adnotacja jest dla parametru odniesienia.

Parametry wyjściowe odniesienia

Wspólne korzystanie z parametru odniesienia jest dla parametrów wyjściowych.Dla parametrów odniesienia prosty wyjściowy — na przykład, int&—_Out_ zapewnia poprawne semantyka.Jednakże, gdy wartość danych wyjściowych jest wskaźnik — na przykład int *&— jak adnotacje równoważne wskaźnik _Outptr_ int ** nie zapewniają prawidłowe semantyka.Aby zwięźle express semantykę odniesienia parametry wyjściowe typów wskaźników, należy użyć adnotacje kompozytowe:

Adnotacja	Opis
_Outref_	Wynik musi być prawidłowa w post-state i nie może być zerowy.
_Outref_result_maybenull_	Wynik musi być ważny, w post-state, ale może mieć wartości null w post-state.
_Outref_result_buffer_(s)	Wynik musi być prawidłowa w post-state i nie może być zerowy.Wskazuje na nieprawidłowy bufor o rozmiarze s elementy.
_Outref_result_bytebuffer_(s)	Wynik musi być prawidłowa w post-state i nie może być zerowy.Wskazuje na nieprawidłowy bufor o rozmiarze s bajtów.
_Outref_result_buffer_to_(s, c)	Wynik musi być prawidłowa w post-state i nie może być zerowy.Wskazuje bufor o s elementów, z których pierwszy c są prawidłowe.
_Outref_result_bytebuffer_to_(s, c)	Wynik musi być prawidłowa w post-state i nie może być zerowy.Wskazuje bufor o s bajtów, których pierwszy c są prawidłowe.
_Outref_result_buffer_all_(s)	Wynik musi być prawidłowa w post-state i nie może być zerowy.Wskazuje na nieprawidłowy bufor o rozmiarze s ważne elementy.
_Outref_result_bytebuffer_all_(s)	Wynik musi być prawidłowa w post-state i nie może być zerowy.Wskazuje na nieprawidłowy bufor o s bajtów ważne elementy.
_Outref_result_buffer_maybenull_(s)	Wynik musi być ważny, w post-state, ale może mieć wartości null w post-state.Wskazuje na nieprawidłowy bufor o rozmiarze s elementy.
_Outref_result_bytebuffer_maybenull_(s)	Wynik musi być ważny, w post-state, ale może mieć wartości null w post-state.Wskazuje na nieprawidłowy bufor o rozmiarze s bajtów.
_Outref_result_buffer_to_maybenull_(s, c)	Wynik musi być ważny, w post-state, ale może mieć wartości null w post-state.Wskazuje bufor o s elementów, z których pierwszy c są prawidłowe.
_Outref_result_bytebuffer_to_maybenull_(s,c)	Wynik musi być ważny, w post-state, ale może mieć wartości null w stanie post.Wskazuje bufor o s bajtów, których pierwszy c są prawidłowe.
_Outref_result_buffer_all_maybenull_(s)	Wynik musi być ważny, w post-state, ale może mieć wartości null w stanie post.Wskazuje na nieprawidłowy bufor o rozmiarze s ważne elementy.
_Outref_result_bytebuffer_all_maybenull_(s)	Wynik musi być ważny, w post-state, ale może mieć wartości null w stanie post.Wskazuje na nieprawidłowy bufor o s bajtów ważne elementy.

Zwracają wartości

Wartość zwracana funkcji jest podobna do _Out_ parametru, ale jest na innym poziomie de-reference, a nie trzeba wziąć pod uwagę pojęcia wskaźnika, aby wynik.Następujących adnotacji, zwracana jest wartość obiektu adnotacjami — wartość skalarną, wskaźnik do struct lub wskaźnik do buforu.Adnotacje te mają tą samą semantyką jako odpowiadające im _Out_ adnotacji.

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

Inne typowe adnotacje

Adnotacja	Opis
_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)	Parametr, pola lub wynik mieści się w zakresie (włącznie), z low do hi.Równoważne z _Satisfies_(_Curr_ >= low && _Curr_ <= hi) zastosowanego do obiektu adnotacjami, wraz z odpowiednimi warunkami pre-state lub post-state. Ważne Chociaż nazwy zawierają "w" i "out", semantykę _In_ i _Out_ czy nie mają zastosowanie do tych adnotacji.
_Pre_equal_to_(expr) _Post_equal_to_(expr)	Wartość adnotacjami jest dokładnie expr.Równoważne z _Satisfies_(_Curr_ == expr) zastosowanego do obiektu adnotacjami, wraz z odpowiednimi warunkami pre-state lub post-state.
_Struct_size_bytes_(size)	Stosuje się do zgłoszenia struct lub klasy.Wskazuje prawidłowy obiekt tego typu może być większy od deklarowanego typu o liczbę bajtów, która jest podana przez size.Na przykład: `typedef _Struct_size_bytes_(nSize) struct MyStruct { size_t nSize; ... };` Rozmiar buforu w bajtach z parametru pM typu MyStruct * następnie przyjmuje: `min(pM->nSize, sizeof(MyStruct))`

Adnotacja

Opis

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

Parametr, pola lub wynik mieści się w zakresie (włącznie), z low do hi.Równoważne z _Satisfies_(_Curr_ >= low && _Curr_ <= hi) zastosowanego do obiektu adnotacjami, wraz z odpowiednimi warunkami pre-state lub post-state.

Ważne

Chociaż nazwy zawierają "w" i "out", semantykę _In_ i _Out_ czy nie mają zastosowanie do tych adnotacji.

_Pre_equal_to_(expr)

_Post_equal_to_(expr)

Wartość adnotacjami jest dokładnie expr.Równoważne z _Satisfies_(_Curr_ == expr) zastosowanego do obiektu adnotacjami, wraz z odpowiednimi warunkami pre-state lub post-state.

_Struct_size_bytes_(size)

Stosuje się do zgłoszenia struct lub klasy.Wskazuje prawidłowy obiekt tego typu może być większy od deklarowanego typu o liczbę bajtów, która jest podana przez size.Na przykład:

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

Rozmiar buforu w bajtach z parametru pM typu MyStruct * następnie przyjmuje:

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

Zasoby pokrewne

Blog zespołu Code Analysis

Zobacz też

Udostępnij za pośrednictwem

Dodawanie adnotacji do parametrów funkcji i zwracanych wartości

Parametry wskaźnika

Parametry opcjonalne wskaźnika

Wskaźnik parametrów wyjściowych

Parametry wyjściowe odniesienia

Zwracają wartości

Inne typowe adnotacje

Zasoby pokrewne

Zobacz też

Informacje

Koncepcje

Inne zasoby

Dodatkowe zasoby