Sdílet prostřednictvím

Přidávání poznámek k parametrům funkce a vráceným hodnotám

  • Článek

Tento článek popisuje typické použití poznámek pro jednoduché parametry funkce – skaláry a ukazatele na struktury a třídy – a většinu druhů vyrovnávacích pamětí. Tento článek také ukazuje běžné vzory použití pro poznámky. Další poznámky související s funkcemi najdete v tématu Přidávání poznámek k chování funkce.

Parametry ukazatele

Pro poznámky v následující tabulce, pokud je parametr ukazatele anotován, analyzátor hlásí chybu, pokud ukazatel má hodnotu null. Tato poznámka se vztahuje na ukazatele a na libovolnou datovou položku, na kterou odkazuje.

Poznámky a popisy

  • _In_

    Anotuje vstupní parametry, které jsou skaláry, struktury, ukazatele na struktury a podobně. Explicitně lze použít u jednoduchých skalárů. Parametr musí být platný v předběžném stavu a nebude změněn.

  • _Out_

    Anotuje výstupní parametry, které jsou skaláry, struktury, ukazatele na struktury a podobně. Tuto poznámku nepoužívejte u objektu, který nemůže vrátit hodnotu – například skalár předaný hodnotou. Parametr nemusí být platný v předběžném stavu, ale musí být platný v post-state.

  • _Inout_

    Anotuje parametr, který bude změněn funkcí. Musí být platný v představovém i po stavu, ale předpokládá se, že má před voláním a po něm různé hodnoty. Musí se použít na upravitelnou hodnotu.

  • _In_z_

    Ukazatel na řetězec ukončený hodnotou null, který se používá jako vstup. Řetězec musí být platný v předběžném stavu. Preferují se varianty PSTR, které již mají správné poznámky.

  • _Inout_z_

    Ukazatel na pole znaků s ukončenou hodnotou null, které bude změněno. Musí být platný před a po volání, ale předpokládá se, že se hodnota změnila. Ukončovací znak null může být přesunut, ale přístup k původnímu ukončovacímu znaku null může být pouze elementy.

  • _In_reads_(s)

    _In_reads_bytes_(s)

    Ukazatel na matici, která je přečtená funkcí. Pole má prvky velikosti s , z nichž všechny musí být platné.

    Varianta _bytes_ dává velikost v bajtech místo prvků. Tuto variantu použijte pouze v případě, že velikost nemůže být vyjádřena jako prvky. Například řetězce by používaly variantu _bytes_ pouze v případě, char že by podobná funkce, která by používalawchar_t.

  • _In_reads_z_(s)

    Ukazatel na pole, které je ukončeno null a má známou velikost. Prvky až do ukončovací funkce null (nebo s pokud neexistuje ukončovací modul s hodnotou null), musí být platné v představci. Pokud je velikost známá v bajtech, škálujte s velikost prvku.

  • _In_reads_or_z_(s)

    Ukazatel na pole, které je ukončeno null nebo má známou velikost nebo obojí. Prvky až do ukončovací funkce null (nebo s pokud neexistuje ukončovací modul s hodnotou null), musí být platné v představci. Pokud je velikost známá v bajtech, škálujte s velikost prvku. (Používá se pro strn rodinu.)

  • _Out_writes_(s)

    _Out_writes_bytes_(s)

    Ukazatel na pole s prvků (resp. bajtů), které bude funkce zapisovat. Prvky pole nemusí být platné v předběžném stavu a počet prvků, které jsou platné v post-state, není zadán. Pokud typ parametru obsahuje poznámky, použijí se v post-state. Představte si například následující kód.

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

    V tomto příkladu volající poskytuje vyrovnávací paměť size prvků pro p1. MyStringCopy některé z těchto prvků jsou platné. Důležitější je, že poznámka znamenáPWSTR, _Null_terminated_ že p1 je ukončena hodnotou null v post-state. Tímto způsobem je počet platných prvků stále dobře definovaný, ale konkrétní počet prvků není povinný.

    Varianta _bytes_ dává velikost v bajtech místo prvků. Tuto variantu použijte pouze v případě, že velikost nemůže být vyjádřena jako prvky. Například řetězce by používaly variantu _bytes_ pouze v případě, char že by podobná funkce, která by používalawchar_t.

  • _Out_writes_z_(s)

    Ukazatel na pole s prvků. Prvky nemusí být platné v předběžném stavu. V závěrečném stavu musí být elementy až přes ukončovací znak null , který musí existovat, platné. Pokud je velikost známá v bajtech, škálujte s velikost prvku.

  • _Inout_updates_(s)

    _Inout_updates_bytes_(s)

    Ukazatel na pole, které je čteno i zapsáno do funkce. Jedná se o prvky velikosti s a platné v představovém stavu a po stavu.

    Varianta _bytes_ dává velikost v bajtech místo prvků. Tuto variantu použijte pouze v případě, že velikost nemůže být vyjádřena jako prvky. Například řetězce by používaly variantu _bytes_ pouze v případě, char že by podobná funkce, která by používalawchar_t.

  • _Inout_updates_z_(s)

    Ukazatel na pole, které je ukončeno hodnotou null a má známou velikost. Prvky až do ukončovací funkce null , které musí být přítomny, musí být platné v představovém i po stavu. Hodnota v post-state se předpokládá, že se liší od hodnoty v představu; obsahující umístění ukončovací funkce null. Pokud je velikost známá v bajtech, škálujte s velikost prvku.

  • _Out_writes_to_(s,c)

    _Out_writes_bytes_to_(s,c)

    _Out_writes_all_(s)

    _Out_writes_bytes_all_(s)

    Ukazatel na pole s prvků. Prvky nemusí být platné v předběžném stavu. V post-state musí být prvky až do c-th elementu platné. Variantu _bytes_ lze použít, pokud je velikost známa v bajtech, nikoli v počtu prvků.

    Příklad:

    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)

    Ukazatel na pole, které funkce čte i zapisuje. Jedná se o prvky velikosti s , z nichž všechny musí být platné v předběžném stavu a c prvky musí být platné v post-state.

    Varianta _bytes_ dává velikost v bajtech místo prvků. Tuto variantu použijte pouze v případě, že velikost nemůže být vyjádřena jako prvky. Například řetězce by používaly variantu _bytes_ pouze v případě, char že by podobná funkce, která by používalawchar_t.

  • _Inout_updates_all_(s)

    _Inout_updates_bytes_all_(s)

    Ukazatel na pole, který je čtený i zapsaný funkcí prvků velikosti s . Definováno jako ekvivalentní:

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

    Jinými slovy, každý prvek, který existuje ve vyrovnávací paměti až s do stavu před stavem, je platný v představu a po stavu.

    Varianta _bytes_ dává velikost v bajtech místo prvků. Tuto variantu použijte pouze v případě, že velikost nemůže být vyjádřena jako prvky. Například řetězce by používaly variantu _bytes_ pouze v případě, char že by podobná funkce, která by používalawchar_t.

  • _In_reads_to_ptr_(p)

    Ukazatel na matici, p pro kterou p - _Curr_ (tedy minus_Curr_) je platný výraz. Prvky musí p být před stavem platné.

    Příklad:

    int ReadAllElements(_In_reads_to_ptr_(EndOfArray) const int *Array, const int *EndOfArray);

  • _In_reads_to_ptr_z_(p)

    Ukazatel na pole s ukončenou hodnotou null, pro který je výraz p - _Curr_ (tj p . minus _Curr_) platným výrazem. Prvky musí p být před stavem platné.

  • _Out_writes_to_ptr_(p)

    Ukazatel na matici, p pro kterou p - _Curr_ (tedy minus_Curr_) je platný výraz. Prvky před tím, než p musí být platné v předběžném stavu a musí být platné v post-state.

  • _Out_writes_to_ptr_z_(p)

    Ukazatel na pole s ukončenou hodnotou null, p pro které p - _Curr_ (tj. minus_Curr_) je platný výraz. Prvky před tím, než p musí být platné v předběžném stavu a musí být platné v post-state.

Volitelné parametry ukazatele

Pokud anotace parametru ukazatele obsahuje _opt_, znamená to, že parametr může mít hodnotu null. Jinak se poznámka chová stejně jako verze, která neobsahuje _opt_. Tady je seznam _opt_ variant poznámek parametrů ukazatele:

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

Parametry výstupního ukazatele

Parametry výstupního ukazatele vyžadují speciální notaci, která u parametru a umístění odkazuje na nejednoznačnost null.

Poznámky a popisy

  • _Outptr_

    Parametr nemůže mít hodnotu null a ve stavu post-to-to-location nemůže být null a musí být platný.

  • _Outptr_opt_

    Parametr může mít hodnotu null, ale ve stavu post-to-to-location nemůže být null a musí být platný.

  • _Outptr_result_maybenull_

    Parametr nemůže mít hodnotu null a ve stavu post-to-to-location může mít hodnotu null.

  • _Outptr_opt_result_maybenull_

    Parametr může mít hodnotu null a ve stavu post-to-to-location může mít hodnotu null.

    V následující tabulce jsou do názvu poznámky vloženy další podřetězené řetězce, které dále kvalifikují význam poznámky. Různé podřetětěce jsou _z, _COM_, _buffer_, _bytebuffer_a _to_.

Důležité

Pokud je rozhraní, které píšete poznámkami, com, použijte formu modelu COM těchto poznámek. Nepoužívejte poznámky MODELU COM s žádným jiným rozhraním typu.

  • _Outptr_result_z_

    _Outptr_opt_result_z_

    _Outptr_result_maybenull_z_

    _Outptr_opt_result_maybenull_z_

    Vrácený ukazatel má poznámku _Null_terminated_ .

  • _COM_Outptr_

    _COM_Outptr_opt_

    _COM_Outptr_result_maybenull_

    _COM_Outptr_opt_result_maybenull_

    Vrácený ukazatel má sémantiku modelu COM, což je důvod, proč nese _On_failure_ post-condition, že vrácený ukazatel má hodnotu null.

  • _Outptr_result_buffer_(s)

    _Outptr_result_bytebuffer_(s)

    _Outptr_opt_result_buffer_(s)

    _Outptr_opt_result_bytebuffer_(s)

    Vrácený ukazatel odkazuje na platnou vyrovnávací paměť prvků velikosti s nebo bajtů.

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

    Vrácený ukazatel odkazuje na vyrovnávací paměť prvků velikosti s nebo bajtů, z nichž první c jsou platné.

Některé konvence rozhraní předpokládají, že při selhání jsou výstupní parametry null. S výjimkou explicitního kódu COM jsou upřednostňované formuláře v následující tabulce. Pro kód COM použijte odpovídající formuláře MODELU COM, které jsou uvedeny v předchozí části.

  • _Result_nullonfailure_

    Upraví další poznámky. Výsledek je nastaven na hodnotu null, pokud funkce selže.

  • _Result_zeroonfailure_

    Upraví další poznámky. Pokud funkce selže, nastaví se výsledek na nulu.

  • _Outptr_result_nullonfailure_

    Vrácený ukazatel odkazuje na platnou vyrovnávací paměť, pokud je funkce úspěšná, nebo null, pokud funkce selže. Tato poznámka je určená pro nepovinný parametr.

  • _Outptr_opt_result_nullonfailure_

    Vrácený ukazatel odkazuje na platnou vyrovnávací paměť, pokud je funkce úspěšná, nebo null, pokud funkce selže. Tato poznámka je určená pro volitelný parametr.

  • _Outref_result_nullonfailure_

    Vrácený ukazatel odkazuje na platnou vyrovnávací paměť, pokud je funkce úspěšná, nebo null, pokud funkce selže. Tato poznámka je určená pro referenční parametr.

Výstupní referenční parametry

Běžné použití referenčního parametru je pro výstupní parametry. Pro jednoduché referenční parametry výstupu, jako int&je například , _Out_ poskytuje správnou sémantiku. Pokud je však výstupní hodnota ukazatel, například , ekvivalentní poznámky ukazatele, jako int *&_Outptr_ int ** je, neposkytují správnou sémantiku. Pokud chcete výstižně vyjádřit sémantiku výstupních referenčních parametrů pro typy ukazatelů, použijte tyto složené poznámky:

Poznámky a popisy

  • _Outref_

    Výsledek musí být platný v post-state a nesmí být null.

  • _Outref_result_maybenull_

    Výsledek musí být platný v post-state, ale může mít hodnotu null v post-state.

  • _Outref_result_buffer_(s)

    Výsledek musí být platný v post-state a nesmí být null. Odkazuje na platnou vyrovnávací paměť prvků velikosti s .

  • _Outref_result_bytebuffer_(s)

    Výsledek musí být platný v post-state a nesmí být null. Odkazuje na platnou vyrovnávací paměť bajtů velikosti s .

  • _Outref_result_buffer_to_(s, c)

    Výsledek musí být platný v post-state a nesmí být null. Odkazuje na vyrovnávací paměť s prvků, z nichž první c jsou platné.

  • _Outref_result_bytebuffer_to_(s, c)

    Výsledek musí být platný v post-state a nesmí být null. Odkazuje na vyrovnávací paměť s bajtů, z nichž první c jsou platné.

  • _Outref_result_buffer_all_(s)

    Výsledek musí být platný v post-state a nesmí být null. Odkazuje na platnou vyrovnávací paměť platných prvků velikosti s .

  • _Outref_result_bytebuffer_all_(s)

    Výsledek musí být platný v post-state a nesmí být null. Odkazuje na platnou s vyrovnávací paměť bajtů platných prvků.

  • _Outref_result_buffer_maybenull_(s)

    Výsledek musí být platný v post-state, ale může mít hodnotu null v post-state. Odkazuje na platnou vyrovnávací paměť prvků velikosti s .

  • _Outref_result_bytebuffer_maybenull_(s)

    Výsledek musí být platný v post-state, ale může mít hodnotu null v post-state. Odkazuje na platnou vyrovnávací paměť bajtů velikosti s .

  • _Outref_result_buffer_to_maybenull_(s, c)

    Výsledek musí být platný v post-state, ale může mít hodnotu null v post-state. Odkazuje na vyrovnávací paměť s prvků, z nichž první c jsou platné.

  • _Outref_result_bytebuffer_to_maybenull_(s,c)

    Výsledek musí být platný v post-state, ale může mít hodnotu null ve stavu post. Odkazuje na vyrovnávací paměť s bajtů, z nichž první c jsou platné.

  • _Outref_result_buffer_all_maybenull_(s)

    Výsledek musí být platný v post-state, ale může mít hodnotu null ve stavu post. Odkazuje na platnou vyrovnávací paměť platných prvků velikosti s .

  • _Outref_result_bytebuffer_all_maybenull_(s)

    Výsledek musí být platný v post-state, ale může mít hodnotu null ve stavu post. Odkazuje na platnou s vyrovnávací paměť bajtů platných prvků.

Vrácené hodnoty

Návratová hodnota funkce se podobá parametru _Out_ , ale je na jiné úrovni odkazu a nemusíte brát v úvahu koncept ukazatele na výsledek. U následujících poznámek je návratová hodnota objekt s poznámkami – skalár, ukazatel na strukturu nebo ukazatel na vyrovnávací paměť. Tyto poznámky mají stejnou sémantiku jako odpovídající _Out_ poznámka.

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

Formátování parametrů řetězce

  • _Printf_format_string_ Označuje, že parametr je formátovací řetězec pro použití ve výrazu printf .

    Příklad

    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_ Označuje, že parametr je formátovací řetězec pro použití ve výrazu scanf .

    Příklad

    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_ Označuje, že parametr je formátovací řetězec pro použití ve výrazu scanf_s .

    Příklad

    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;
}

Další běžné poznámky

Poznámky a popisy

  • _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, pole nebo výsledek je v rozsahu (včetně) od low do hi. Ekvivalent, _Satisfies_(_Curr_ >= low && _Curr_ <= hi) který se použije u anotovaného objektu společně s odpovídajícími podmínkami před stavem nebo po stavu.

    Důležité

    I když názvy obsahují "in" a "out", sémantika _In_ a _Out_nevztahuje se na tyto poznámky.

  • _Pre_equal_to_(expr)

    _Post_equal_to_(expr)

    Anotovaná hodnota je přesně expr. Ekvivalent, _Satisfies_(_Curr_ == expr) který se použije u anotovaného objektu společně s odpovídajícími podmínkami před stavem nebo po stavu.

  • _Struct_size_bytes_(size)

    Platí pro deklaraci struktury nebo třídy. Označuje, že platný objekt tohoto typu může být větší než deklarovaný typ s počtem bajtů, které jsou dány size. Příklad:

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

    Velikost vyrovnávací paměti v bajtech parametru pM typu MyStruct * se pak provede takto:

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

Viz také