Poznámky záhlaví
[Toto téma popisuje poznámky podporované v záhlavích Windows prostřednictvím Windows 7. Pokud vyvíjíte pro Windows 8, měli byste použít poznámky popsané v poznámkách SAL.]
Poznámky záhlaví popisují, jak funkce používá parametry a návratovou hodnotu. Tyto poznámky byly přidány do mnoha souborů hlaviček Systému Windows, které vám pomůžou zajistit správné volání rozhraní API systému Windows. Pokud povolíte analýzu kódu, která je dostupná od sady Visual Studio 2005, kompilátor vygeneruje upozornění na úroveň 6000, pokud tyto funkce nevoláte podle použití popsaného prostřednictvím poznámek. Tyto poznámky můžete také přidat do vlastního kódu, abyste měli jistotu, že se volá správně. Pokud chcete povolit analýzu kódu v sadě Visual Studio, přečtěte si dokumentaci k vaší verzi sady Visual Studio.
Tyto poznámky jsou definovány v sadě Specstrings.h. Jsou postaveny na primitivech, které jsou součástí standardnotační jazyk (SAL) a implementované pomocí _declspec("SAL_*").
Existují dvě třídy poznámek: poznámky vyrovnávací paměti a pokročilé poznámky.
Poznámky vyrovnávací paměti
Poznámky vyrovnávací paměti popisují, jak funkce používají své ukazatele a lze je použít k detekci přetečení vyrovnávací paměti. Každý parametr může používat nulovou nebo jednu poznámku vyrovnávací paměti. Poznámka vyrovnávací paměti se vytvoří s úvodním podtržítkem a komponentami popsanými v následujících částech.
| Velikost vyrovnávací paměti | Popis |
|---|---|
|
(velikost) |
Určuje celkovou velikost vyrovnávací paměti. Použití s _bcount a _ecount; nepoužívejte s _part. Tato hodnota je přístupný prostor; může být menší než přidělený prostor. |
|
(velikost,délka) |
Určuje celkovou velikost a inicializovanou délku vyrovnávací paměti. Používá se s _bcount_part a _ecount_part. Celková velikost může být menší než přidělený prostor. |
| Jednotky velikosti vyrovnávací paměti | Popis |
|---|---|
|
_bcount |
Velikost vyrovnávací paměti je v bajtech. |
|
_ecount |
Velikost vyrovnávací paměti je v elementech. |
| Směr | Popis |
|---|---|
|
_in |
Funkce čte z vyrovnávací paměti. Volající poskytuje vyrovnávací paměť a inicializuje ji. |
|
_inout |
Funkce čte z vyrovnávací paměti i zápisy do vyrovnávací paměti. Volající poskytuje vyrovnávací paměť a inicializuje ji. Pokud se používá s _deref, může být vyrovnávací paměť relokována funkcí. |
|
_out |
Funkce zapisuje do vyrovnávací paměti. Pokud se použije na návratové hodnotě nebo s _deref, funkce poskytne vyrovnávací paměť a inicializuje ji. V opačném případě volající poskytne vyrovnávací paměť a funkce ji inicializuje. |
| Bezcílnost | Popis |
|---|---|
|
_deref |
Dereference parametr získat ukazatel vyrovnávací paměti. Tento parametr nemusí být null. |
|
_deref_opt |
Dereference parametr získat ukazatel vyrovnávací paměti. Tento parametr může být null. |
| Inicializace | Popis |
|---|---|
|
_full |
Funkce inicializuje celou vyrovnávací paměť. Používejte pouze s výstupními vyrovnávacími paměťmi. |
|
_part |
Funkce inicializuje část vyrovnávací paměti a explicitně určuje, kolik. Používejte pouze s výstupními vyrovnávacími paměťmi. |
| Povinná nebo volitelná vyrovnávací paměť | Popis |
|---|---|
|
_opt |
Tento parametr může být null. |
Následující příklad ukazuje poznámky pro GetModuleFileName funkce. Parametr hModule je volitelný vstupní parametr . Parametr lpFilename je výstupní parametr; jeho velikost v znacích je určena parametrem nSize a jeho délka zahrnuje null-ukončovací znak. Parametr nSize je vstupní parametr.
DWORD
WINAPI
GetModuleFileName(
__in_opt HMODULE hModule,
__out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
__in DWORD nSize
);
Níže jsou uvedené poznámky definované v části Specstrings.h. Pomocí informací v tabulkách výše můžete interpretovat jejich význam.
__bcount( velikost)
__bcount_opt( velikost)
__deref_bcount(velikost)
__deref_bcount_opt(velikost)
__deref_ecount( velikost)
__deref_ecount_opt(velikost)
__deref_in
__deref_in_bcount( velikost)
__deref_in_bcount_opt(velikost)
__deref_in_ecount(velikost)
__deref_in_ecount_opt(velikost)
__deref_in_opt
__deref_inout
__deref_inout_bcount( velikost)
__deref_inout_bcount_full(velikost)
__deref_inout_bcount_full_opt(velikost)
__deref_inout_bcount_opt( velikost)
__deref_inout_bcount_part(velikost, délka)
__deref_inout_bcount_part_opt(velikost, délka)
__deref_inout_ecount(velikost)
__deref_inout_ecount_full(velikost)
__deref_inout_ecount_full_opt(velikost)
__deref_inout_ecount_opt(velikost)
__deref_inout_ecount_part(velikost,délka)
__deref_inout_ecount_part_opt(velikost,délka)
__deref_inout_opt
__deref_opt_bcount(velikost)
__deref_opt_bcount_opt(velikost)
__deref_opt_ecount(velikost)
__deref_opt_ecount_opt( velikost)
__deref_opt_in
__deref_opt_in_bcount( velikost)
__deref_opt_in_bcount_opt(velikost)
__deref_opt_in_ecount(velikost)
__deref_opt_in_ecount_opt(velikost)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount( velikost)
__deref_opt_inout_bcount_full( velikost)
__deref_opt_inout_bcount_full_opt( velikost)
__deref_opt_inout_bcount_opt(velikost)
__deref_opt_inout_bcount_part(velikost,délka)
__deref_opt_inout_bcount_part_opt(velikost,délka)
__deref_opt_inout_ecount(velikost)
__deref_opt_inout_ecount_full(velikost)
__deref_opt_inout_ecount_full_opt( velikost)
__deref_opt_inout_ecount_opt( velikost)
__deref_opt_inout_ecount_part(velikost,délka)
__deref_opt_inout_ecount_part_opt(velikost,délka)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount( velikost)
__deref_opt_out_bcount_full(velikost)
__deref_opt_out_bcount_full_opt( velikost)
__deref_opt_out_bcount_opt(velikost)
__deref_opt_out_bcount_part(velikost,délka)
__deref_opt_out_bcount_part_opt(velikost,délka)
__deref_opt_out_ecount(velikost)
__deref_opt_out_ecount_full( velikost)
__deref_opt_out_ecount_full_opt(velikost)
__deref_opt_out_ecount_opt( velikost)
__deref_opt_out_ecount_part(velikost,délka)
__deref_opt_out_ecount_part_opt(velikost,délka)
__deref_opt_out_opt
__deref_out
__deref_out_bcount( velikost)
__deref_out_bcount_full( velikost)
__deref_out_bcount_full_opt(velikost)
__deref_out_bcount_opt( velikost)
__deref_out_bcount_part(velikost,délka)
__deref_out_bcount_part_opt(velikost,délka)
__deref_out_ecount(velikost)
__deref_out_ecount_full(velikost)
__deref_out_ecount_full_opt( velikost)
__deref_out_ecount_opt( velikost)
__deref_out_ecount_part(velikost,délka)
__deref_out_ecount_part_opt(velikost,délka)
__deref_out_opt
__ecount(velikost)
__ecount_opt(velikost)
__v
__in_bcount(velikost)
__in_bcount_opt(velikost)
__in_ecount( velikost)
__in_ecount_opt(velikost)
__in_opt
__inout
__inout_bcount(velikost)
__inout_bcount_full( velikost)
__inout_bcount_full_opt(velikost)
__inout_bcount_opt(velikost)
__inout_bcount_part(velikost,délka)
__inout_bcount_part_opt(velikost,délka)
__inout_ecount( velikost)
__inout_ecount_full(velikost)
__inout_ecount_full_opt(velikost)
__inout_ecount_opt(velikost)
__inout_ecount_part(velikost,délka)
__inout_ecount_part_opt(velikost,délka)
__inout_opt
__ven
__out_bcount(velikost)
__out_bcount_full( velikost)
__out_bcount_full_opt(velikost)
__out_bcount_opt( velikost)
__out_bcount_part(velikost,délka)
__out_bcount_part_opt(velikost,délka)
__out_ecount( velikost)
__out_ecount_full( velikost)
__out_ecount_full_opt( velikost)
__out_ecount_opt(velikost)
__out_ecount_part(velikost, délka)
__out_ecount_part_opt(velikost,délka)
__out_opt
Rozšířené poznámky
Rozšířené poznámky poskytují další informace o parametru nebo návratové hodnotě. Každý parametr nebo návratová hodnota může používat nulovou nebo jednu pokročilou poznámku.
| Anotace | Popis |
|---|---|
|
__blocksOn(prostředek) |
Funkce blokuje zadaný prostředek. |
|
__callback |
Funkci lze použít jako ukazatel funkce. |
|
__checkReturn |
Volající musí zkontrolovat vrácenou hodnotu. |
|
__format_string |
Parametr je řetězec, který obsahuje značky % ve stylu printf. |
|
__in_awcount(výraz,velikost) |
Pokud je výraz při ukončení pravdivý, velikost vstupní vyrovnávací paměti je určena v bajtech. Pokud je výraz false, velikost je zadána v prvcích. |
|
__nullnullterminated |
Vyrovnávací paměť může být přístupná až do první sekvence dvou null znaků nebo ukazatelů. |
|
__nullterminated |
Vyrovnávací paměť může být přístupná až do prvního null znaku nebo ukazatele. |
|
__out_awcount(výraz,velikost) |
Pokud je výraz při ukončení pravdivý, velikost výstupní vyrovnávací paměti je určena v bajtech. Pokud je výraz false, velikost je zadána v prvcích. |
|
__override |
Určuje chování přepsání ve stylu C#u virtuálních metod. |
|
__reserved |
Parametr je vyhrazen pro budoucí použití a musí být nulový nebo NULL. |
|
__success(výraz) |
Pokud je výraz při ukončení pravdivý, volající může spoléhat na všechny záruky určené jinými poznámkami. Pokud je výraz nepravda, volající nemůže spoléhat na záruky. Tato poznámka se automaticky přidá do funkcí, které vrátí hodnotu HRESULT. |
|
__typefix(ctype) |
Zachází s parametrem jako se zadaným typem, nikoli s deklarovaným typem. |
Následující příklady ukazují vyrovnávací paměť a pokročilé poznámky pro DeleteTimerQueueTimer, FreeEnvironmentStringsa UnhandledExceptionFilter funkcí.
__checkReturn
BOOL
WINAPI
DeleteTimerQueueTimer(
__in_opt HANDLE TimerQueue,
__in HANDLE Timer,
__in_opt HANDLE CompletionEvent
);
BOOL
WINAPI
FreeEnvironmentStrings(
__in __nullnullterminated LPTCH
);
__callback
LONG
WINAPI
UnhandledExceptionFilter(
__in struct _EXCEPTION_POINTERS *ExceptionInfo
);