Anotace parametrů funkce a návratových hodnot

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í poznámek. Další poznámky týkající se funkcí najdete v tématu Popis chování funkce.

Parametry ukazatele

Pokud je u poznámek v následující tabulce anotován parametr ukazatele, analyzátor hlásí chybu, pokud má ukazatel 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ě je možné 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žijte na objekt, který nemůže vrátit hodnotu – například skalár, který je předán hodnotou. Parametr nemusí být platný v předběžném stavu, ale musí být platný v post-state.

• _Inout_

  Anotuje parametr, který funkce změní. Musí být platný v předběžném i po stavu, ale předpokládá se, že před voláním a po volání bude mít jiné hodnoty. Musí platit pro upravitelnou hodnotu.

• _In_z_

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

• _Inout_z_

  Ukazatel na pole znaků ukončené hodnotou null, které se změní. Musí být platný před a po volání, ale předpokládá se, že hodnota se změnila. Je možné přesunout ukončovací znak null, ale k prvkům až do původního ukončovacího znaku null lze přistupovat.

• _In_reads_(s)

  _In_reads_bytes_(s)

  Ukazatel na pole, které funkce čte. Pole má prvky s velikosti, z nichž všechny musí být platné.

  Varianta _bytes_ dává místo prvků velikost v bajtech. Tuto variantu použijte pouze v případě, že velikost nelze vyjádřit jako prvky. Řetězce například používají variantu pouze v případě, že by byla podobná char_bytes_ funkce, která wchar_t používá .

• _In_reads_z_(s)

  Ukazatel na pole, které je ukončeno hodnotou null a má známou velikost. Prvky až po ukončovací znak null (nebo pokud neexistuje ukončovací znak null) musí být platné s v předběžném stavu. Pokud je velikost známa v bajtech, s zmenšete velikost podle velikosti prvku.

• _In_reads_or_z_(s)

  Ukazatel na pole, které je ukončeno hodnotou null nebo má známou velikost nebo obojí. Prvky až po ukončovací znak null (nebo pokud neexistuje ukončovací znak null) musí být platné s v předběžném stavu. Pokud je velikost známa v bajtech, s zmenšete velikost podle velikosti prvku. (Používá se pro strn rodinu.)

• _Out_writes_(s)

  _Out_writes_bytes_(s)

  Ukazatel na pole prvků s (resp. bajtů), které funkce zapisuje. Prvky pole nemusí být platné v předběžném stavu a počet prvků, které jsou platné po stavu, není zadán. Pokud existují poznámky k typu parametru, 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é. Ještě důležitější je, že poznámka u znamená, že je ukončena hodnotou _Null_terminated_PWSTR null v p1 post-state. Tímto způsobem je počet platných prvků stále dobře definovaný, ale konkrétní počet prvků není vyžadován.

  Varianta _bytes_ dává místo prvků velikost v bajtech. Tuto variantu použijte pouze v případě, že velikost nelze vyjádřit jako prvky. Řetězce například používají variantu pouze v případě, že by byla podobná char_bytes_ funkce, která wchar_t používá .

• _Out_writes_z_(s)

  Ukazatel na pole s prvků. Prvky nemusí být platné v předběžném stavu. V post-state musí být prvky nahoru přes ukončovací znak null, který musí být přítomný, platné. Pokud je velikost známa v bajtech, s zmenšete velikost podle velikosti prvku.

• _Inout_updates_(s)

  _Inout_updates_bytes_(s)

  Ukazatel na pole, které je ve funkci čtené i zapsané na . Má velikost prvků s a je platná v předsoudku a po stavu.

  Varianta _bytes_ dává místo prvků velikost v bajtech. Tuto variantu použijte pouze v případě, že velikost nelze vyjádřit jako prvky. Řetězce například používají variantu pouze v případě, že by byla podobná char_bytes_ funkce, která wchar_t používá .

• _Inout_updates_z_(s)

  Ukazatel na pole, které je ukončeno hodnotou null a má známou velikost. Prvky, které musí být přítomné, až přes ukončovací znak null, musí být platné před stavem i po stavu. Předpokládá se, že hodnota v posouvce se liší od hodnoty v předběžném stavu. , která zahrnuje umístění ukončovací funkce null. Pokud je velikost známa v bajtech, s zmenšete velikost podle velikosti 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 c až do -th platné. Variantu _bytes_ lze použít, pokud je velikost známa v bajtech, nikoli v počtu prvků.

  Napří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. Je velikosti prvků, z nichž všechny musí být platné v předběžném stavu a prvky musí sc být platné v post-state.

  Varianta _bytes_ dává místo prvků velikost v bajtech. Tuto variantu použijte pouze v případě, že velikost nelze vyjádřit jako prvky. Řetězce například používají variantu pouze v případě, že by byla podobná char_bytes_ funkce, která wchar_t používá .

• _Inout_updates_all_(s)

  _Inout_updates_bytes_all_(s)

  Ukazatel na pole, které je čtena i zapsána funkcí prvků s velikosti. Definováno jako ekvivalent pro:

  _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ž do v předběžném stavu, je platný v předběžném i s po stavu.

  Varianta _bytes_ dává místo prvků velikost v bajtech. Tuto variantu použijte pouze v případě, že velikost nelze vyjádřit jako prvky. Řetězce například používají variantu pouze v případě, že by byla podobná char_bytes_ funkce, která wchar_t používá .

• _In_reads_to_ptr_(p)

  Ukazatel na pole, pro které p - _Curr_ je (to p znamená minus ) _Curr_ platný výraz. Prvky před p musí být platné v předběžném stavu.

  Například:

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

• _In_reads_to_ptr_z_(p)

  Ukazatel na pole ukončené hodnotou null, pro které je výraz (to znamená p - _Curr_p minus ) _Curr_ platným výrazem. Prvky před p musí být platné v předběžném stavu.

• _Out_writes_to_ptr_(p)

  Ukazatel na pole, pro které p - _Curr_ je (to p znamená minus ) _Curr_ platný výraz. Prvky před nemusí být platné v předběžném stavu a p musí být platné v post-state.

• _Out_writes_to_ptr_z_(p)

  Ukazatel na pole ukončené hodnotou null, pro které je (to znamená p - _Curr_ minus ) platný p_Curr_ výraz. Prvky před nemusí být platné v předběžném stavu a p musí být platné v post-state.

Volitelné parametry ukazatele

Pokud anotace parametru ukazatele zahrnuje _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 k parametrům ukazatele:

Parametry výstupního ukazatele

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

Poznámky a popisy

• _Outptr_

  Parametr nemůže mít hodnotu null a v poschodce nemůže být odkaz na umístění null a musí být platný.

• _Outptr_opt_

  Parametr může mít hodnotu null, ale v poschodce nemůže být odkaz na umístění null a musí být platný.

• _Outptr_result_maybenull_

  Parametr nemůže mít hodnotu null a v poschodce může být odkaz na umístění null.

• _Outptr_opt_result_maybenull_

  Parametr může mít hodnotu null a v poschodce může být odkaz na umístění null.

  V následující tabulce jsou do názvu poznámky vloženy další podřetězce, aby se dále kvalifikoval význam poznámky. Různé podřetězce jsou _z , , , a _COM__buffer__bytebuffer__to_ .

• _Outptr_result_z_

  _Outptr_opt_result_z_

  _Outptr_result_maybenull_z_

  _Outptr_opt_result_maybenull_z_

  Vrácený ukazatel má _Null_terminated_ anotaci.

• _COM_Outptr_

  _COM_Outptr_opt_

  _COM_Outptr_result_maybenull_

  _COM_Outptr_opt_result_maybenull_

  Vrácený ukazatel má sémantiku modelu COM, což znamená, _On_failure_ že má za předpokladu, že vrácený ukazatel je null.

• _Outptr_result_buffer_(s)

  _Outptr_result_bytebuffer_(s)

  _Outptr_opt_result_buffer_(s)

  _Outptr_opt_result_bytebuffer_(s)

  Vrácený ukazatel ukazuje na platnou vyrovnávací paměť s prvků velikosti 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 ukazuje na vyrovnávací paměť s prvků velikosti nebo bajtů, z nichž první c je platná.

Některé konvence rozhraní předpokládají, že výstupní parametry jsou nullified při selhání. S výjimkou explicitního kódu COM jsou upřednostňovány 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í jiné poznámky. Výsledek je nastaven na hodnotu null, pokud se funkce nezdařila.

• _Result_zeroonfailure_

  Upraví jiné poznámky. Výsledek je nastaven na hodnotu nula, pokud se funkce nezdařila.

• _Outptr_result_nullonfailure_

  Vrácený ukazatel ukazuje na platnou vyrovnávací paměť, pokud je funkce úspěšná, nebo null, pokud funkce selže. Tato anotace je určena pro nevolitelný parametr.

• _Outptr_opt_result_nullonfailure_

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

• _Outref_result_nullonfailure_

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

Výstupní parametry odkazu

Běžné použití referenčního parametru je pro výstupní parametry. Pro jednoduché výstupní parametry odkazu, jako int& je, _Out_ poskytuje správnou sémantiku. Pokud je však výstupní hodnota ukazatel, jako je například int *& , ekvivalentní poznámky k ukazateli, jako _Outptr_ int ** neposkytují správnou sémantiku. Pro stručné vyjádření sémantiky 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 nemůže mít hodnotu 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 nemůže mít hodnotu null. Odkazuje na platnou vyrovnávací paměť s prvků Size.

• _Outref_result_bytebuffer_(s)

  Výsledek musí být platný v post-State a nemůže mít hodnotu null. Odkazuje na platnou vyrovnávací paměť velikostí s bajtů.

• _Outref_result_buffer_to_(s, c)

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

• _Outref_result_bytebuffer_to_(s, c)

  Výsledek musí být platný v post-State a nemůže mít hodnotu null. Odkazuje na vyrovnávací paměť s bajtů, jejichž první c je platná.

• _Outref_result_buffer_all_(s)

  Výsledek musí být platný v post-State a nemůže mít hodnotu null. Odkazuje na platnou velikost vyrovnávací paměti s platných prvků.

• _Outref_result_bytebuffer_all_(s)

  Výsledek musí být platný v post-State a nemůže mít hodnotu null. Odkazuje na platnou vyrovnávací paměť s 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ěť s prvků Size.

• _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ěť velikostí s bajtů.

• _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 je platná.

• _Outref_result_bytebuffer_to_maybenull_(s,c)

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

• _Outref_result_buffer_all_maybenull_(s)

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

• _Outref_result_bytebuffer_all_maybenull_(s)

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

Vrácené hodnoty

Návratová hodnota funkce se podobá _Out_ parametru, ale je na jiné úrovni de reference a nemusíte považovat koncept ukazatele na výsledek. Pro následující poznámky je vrácená hodnota objekt s poznámkou – skalární, ukazatel na strukturu nebo ukazatel na vyrovnávací paměť. Tyto poznámky mají stejnou sémantiku jako odpovídající _Out_ Poznámka.

Parametry formátovacího řetězce

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

  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 scanf výrazu.

  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 scanf_s výrazu.

  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 jsou v rozsahu (včetně) z low na hi . Ekvivalent k _Satisfies_(_Curr_ >= low && _Curr_ <= hi) tomuto objektu s poznámkou se aplikuje spolu s příslušnými podmínkami předběžného nebo po stavu.

  Důležité

  I když názvy obsahují "in" a "out", sémantika _In_ a _Out_ neplatí pro _In_ tyto poznámky.

• _Pre_equal_to_(expr)

  _Post_equal_to_(expr)

  Hodnota v poznámce je přesně expr . Ekvivalent k _Satisfies_(_Curr_ == expr) tomuto objektu s poznámkou se aplikuje spolu s příslušnými podmínkami předběžného nebo po stavu.

• _Struct_size_bytes_(size)

  Platí pro strukturu nebo deklaraci třídy. Označuje, že platný objekt tohoto typu může být větší než deklarovaný typ, přičemž počet bajtů předávaných size . Například:

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

  Velikost vyrovnávací paměti v bajtech parametru pM typu je pak považována za MyStruct * :

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

Viz také

• Použití poznámek SAL k snížení míry výskytu závad kódu C/C++
• Porozumění SAL
• Zadávání poznámek k chování funkcí
• Zadávání poznámek ke strukturám a třídám
• Zadávání poznámek o chování při zamykání
• Určení, kdy a kde se má poznámka použít
• Vnitřní funkce
• Doporučené postupy a příklady