Adnotacje nagłówka
[W tym temacie opisano adnotacje obsługiwane w nagłówkach systemu Windows za pośrednictwem systemu Windows 7. Jeśli programujesz dla systemu Windows 8, należy użyć adnotacji opisanych w adnotacje SAL.]
Adnotacje nagłówków opisują sposób, w jaki funkcja używa swoich parametrów i zwracanej wartości. Te adnotacje zostały dodane do wielu plików nagłówków systemu Windows, aby zapewnić prawidłowe wywoływanie interfejsu API systemu Windows. Jeśli włączysz analizę kodu, która jest dostępna począwszy od programu Visual Studio 2005, kompilator utworzy ostrzeżenia na poziomie 6000, jeśli nie wywołujesz tych funkcji zgodnie z użyciem opisanym za pomocą adnotacji. Możesz również dodać te adnotacje we własnym kodzie, aby upewnić się, że jest ona wywoływana poprawnie. Aby włączyć analizę kodu w programie Visual Studio, zapoznaj się z dokumentacją dotyczącą używanej wersji programu Visual Studio.
Te adnotacje są definiowane w pliku Specstrings.h. Są one oparte na typach pierwotnych, które są częścią standardowego języka adnotacji (SAL) i implementowane przy użyciu _declspec("SAL_*").
Istnieją dwie klasy adnotacji: adnotacje buforu i zaawansowane adnotacje.
Adnotacje buforu
Adnotacje buforu opisują sposób używania wskaźników przez funkcje i mogą służyć do wykrywania przekroczenie buforu. Każdy parametr może używać adnotacji zero lub jednego buforu. Adnotacja buforu jest tworzona z wiodącym podkreśleniem i składnikami opisanymi w poniższych sekcjach.
| Rozmiar buforu | Opis |
|---|---|
|
(rozmiar) |
Określa całkowity rozmiar buforu. Używanie z _bcount i _ecount; nie należy używać z _part. Ta wartość to dostępna przestrzeń; może być mniejsza niż przydzielona przestrzeń. |
|
(rozmiar,długości) |
Określa całkowity rozmiar i zainicjowaną długość buforu. Używanie z _bcount_part i _ecount_part. Całkowity rozmiar może być mniejszy niż przydzielone miejsce. |
| Jednostki rozmiaru buforu | Opis |
|---|---|
|
_bcount |
Rozmiar buforu jest wyrażony w bajtach. |
|
_ecount |
Rozmiar buforu znajduje się w elementach. |
| Kierunek | Opis |
|---|---|
|
_in |
Funkcja odczytuje z buforu. Obiekt wywołujący udostępnia bufor i inicjuje go. |
|
_inout |
Funkcja odczytuje dane z i zapisuje w buforze. Obiekt wywołujący udostępnia bufor i inicjuje go. Jeśli jest używany z _deref, bufor może zostać przeniesiony przez funkcję. |
|
_out |
Funkcja zapisuje w buforze. Jeśli użyto wartości zwracanej lub z _deref, funkcja udostępnia bufor i inicjuje go. W przeciwnym razie obiekt wywołujący udostępnia bufor i inicjuje ją. |
| Pośrednia | Opis |
|---|---|
|
_deref |
Wyłusz parametr w celu uzyskania wskaźnika buforu. Ten parametr może nie być wartości NULL. |
|
_deref_opt |
Wyłusz parametr w celu uzyskania wskaźnika buforu. Ten parametr może być null. |
| Inicjowania | Opis |
|---|---|
|
_full |
Funkcja inicjuje cały bufor. Używaj tylko z wyjściowymi. |
|
_part |
Funkcja inicjuje część buforu i jawnie wskazuje, ile. Używaj tylko z wyjściowymi. |
| Wymagany lub opcjonalny bufor | Opis |
|---|---|
|
_opt |
Ten parametr może być null. |
W poniższym przykładzie przedstawiono adnotacje dla funkcji GetModuleFileName. Parametr hModule jest opcjonalnym parametrem wejściowym . Parametr lpFilename jest parametrem wyjściowym; jego rozmiar znaków jest określony przez parametr nSize, a jego długość zawiera null- znak zakończenia. Parametr nSize jest parametrem wejściowym.
DWORD
WINAPI
GetModuleFileName(
__in_opt HMODULE hModule,
__out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
__in DWORD nSize
);
Poniżej przedstawiono adnotacje zdefiniowane w pliku Specstrings.h. Użyj informacji w powyższych tabelach, aby zinterpretować ich znaczenie.
__bcount( rozmiar)
__bcount_opt(rozmiar)
__deref_bcount(rozmiar)
__deref_bcount_opt(rozmiar)
__deref_ecount( rozmiar)
__deref_ecount_opt( rozmiar)
__deref_in
__deref_in_bcount(rozmiar)
__deref_in_bcount_opt(rozmiar)
__deref_in_ecount( rozmiar)
__deref_in_ecount_opt(rozmiar)
__deref_in_opt
__deref_inout
__deref_inout_bcount(rozmiar)
__deref_inout_bcount_full(rozmiar)
__deref_inout_bcount_full_opt( rozmiar)
__deref_inout_bcount_opt(rozmiar)
__deref_inout_bcount_part( rozmiar,długości)
__deref_inout_bcount_part_opt(rozmiar,długości)
__deref_inout_ecount(rozmiar)
__deref_inout_ecount_full( rozmiar)
__deref_inout_ecount_full_opt( rozmiar)
__deref_inout_ecount_opt(rozmiar)
__deref_inout_ecount_part(rozmiar,długości)
__deref_inout_ecount_part_opt(rozmiar,długości)
__deref_inout_opt
__deref_opt_bcount(rozmiar)
__deref_opt_bcount_opt( rozmiar)
__deref_opt_ecount( rozmiar)
__deref_opt_ecount_opt( rozmiar)
__deref_opt_in
__deref_opt_in_bcount(rozmiar)
__deref_opt_in_bcount_opt(rozmiar)
__deref_opt_in_ecount(rozmiar)
__deref_opt_in_ecount_opt(rozmiar)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount( rozmiar)
__deref_opt_inout_bcount_full(rozmiar)
__deref_opt_inout_bcount_full_opt(rozmiar)
__deref_opt_inout_bcount_opt(rozmiar)
__deref_opt_inout_bcount_part(rozmiar,długości)
__deref_opt_inout_bcount_part_opt(rozmiar,długości)
__deref_opt_inout_ecount(rozmiar)
__deref_opt_inout_ecount_full( rozmiar)
__deref_opt_inout_ecount_full_opt( rozmiar)
__deref_opt_inout_ecount_opt( rozmiar)
__deref_opt_inout_ecount_part( rozmiar,długości)
__deref_opt_inout_ecount_part_opt(rozmiar,długości)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount( rozmiar)
__deref_opt_out_bcount_full(rozmiar)
__deref_opt_out_bcount_full_opt(rozmiar)
__deref_opt_out_bcount_opt( rozmiar)
__deref_opt_out_bcount_part(rozmiar,długości)
__deref_opt_out_bcount_part_opt(rozmiar,długości)
__deref_opt_out_ecount(rozmiar)
__deref_opt_out_ecount_full( rozmiar)
__deref_opt_out_ecount_full_opt(rozmiar)
__deref_opt_out_ecount_opt( rozmiar)
__deref_opt_out_ecount_part(rozmiar,długości)
__deref_opt_out_ecount_part_opt(rozmiar,długości)
__deref_opt_out_opt
__deref_out
__deref_out_bcount( rozmiar)
__deref_out_bcount_full(rozmiar)
__deref_out_bcount_full_opt( rozmiar)
__deref_out_bcount_opt(rozmiar)
__deref_out_bcount_part(rozmiar,długości)
__deref_out_bcount_part_opt( rozmiar,długości)
__deref_out_ecount( rozmiar)
__deref_out_ecount_full(rozmiar)
__deref_out_ecount_full_opt(rozmiar)
__deref_out_ecount_opt(rozmiar)
__deref_out_ecount_part( rozmiar,długości)
__deref_out_ecount_part_opt(rozmiar,długości)
__deref_out_opt
__ecount( rozmiar)
__ecount_opt(rozmiar)
__w
__in_bcount( rozmiar)
__in_bcount_opt( rozmiar)
__in_ecount( rozmiar)
__in_ecount_opt(rozmiar)
__in_opt
__inout
__inout_bcount( rozmiar)
__inout_bcount_full(rozmiar)
__inout_bcount_full_opt( rozmiar)
__inout_bcount_opt(rozmiar)
__inout_bcount_part( rozmiar,długości)
__inout_bcount_part_opt( rozmiar,długości)
__inout_ecount(rozmiar)
__inout_ecount_full( rozmiar)
__inout_ecount_full_opt( rozmiar)
__inout_ecount_opt(rozmiar)
__inout_ecount_part( rozmiar,długości)
__inout_ecount_part_opt(rozmiar,długości)
__inout_opt
__na zewnątrz
__out_bcount( rozmiar)
__out_bcount_full(rozmiar)
__out_bcount_full_opt(rozmiar)
__out_bcount_opt( rozmiar)
__out_bcount_part(rozmiar,długości)
__out_bcount_part_opt( rozmiar,długości)
__out_ecount( rozmiar)
__out_ecount_full(rozmiar)
__out_ecount_full_opt(rozmiar)
__out_ecount_opt(rozmiar)
__out_ecount_part( rozmiar,długości)
__out_ecount_part_opt( rozmiar,długości)
__out_opt
Adnotacje zaawansowane
Zaawansowane adnotacje zawierają dodatkowe informacje o parametrze lub zwracanej wartości. Każdy parametr lub wartość zwracana może używać zera lub jednej zaawansowanej adnotacji.
| Adnotacja | Opis |
|---|---|
|
__blocksOn(resource) |
Funkcje blokują określony zasób. |
|
__callback |
Funkcja może służyć jako wskaźnik funkcji. |
|
__checkReturn |
Osoby wywołujące muszą sprawdzić wartość zwracaną. |
|
__format_string |
Parametr jest ciągiem zawierającym znaczniki % typu printf. |
|
__in_awcount(rozmiar) |
Jeśli wyrażenie ma wartość true podczas zamykania, rozmiar buforu wejściowego jest określony w bajtach. Jeśli wyrażenie ma wartość false, rozmiar jest określony w elementach. |
|
__nullnullterminated |
Dostęp do buforu można uzyskać do i zawierać pierwszą sekwencję dwóch znaków o wartości null lub wskaźników. |
|
__nullterminated |
Dostęp do buforu można uzyskać do i zawierać pierwszy znak lub wskaźnik o wartości null. |
|
__out_awcount(expr,size) |
Jeśli wyrażenie ma wartość true podczas zamykania, rozmiar buforu wyjściowego jest określony w bajtach. Jeśli wyrażenie ma wartość false, rozmiar jest określony w elementach. |
|
__override |
Określa zachowanie zastępowania języka C#-style dla metod wirtualnych. |
|
__reserved |
Parametr jest zarezerwowany do użycia w przyszłości i musi mieć wartość zero lub null. |
|
__success(expr ) |
Jeśli wyrażenie ma wartość true podczas zamykania, obiekt wywołujący może polegać na wszystkich gwarancjach określonych przez inne adnotacje. Jeśli wyrażenie jest fałszywe, obiekt wywołujący nie może polegać na gwarancjach. Ta adnotacja jest automatycznie dodawana do funkcji, które zwracają wartość HRESULT. |
|
__typefix(ctype) |
Traktuj parametr jako określony typ, a nie jego zadeklarowany typ. |
W poniższych przykładach przedstawiono bufor i zaawansowane adnotacje dla funkcji DeleteTimerQueueTimer, FreeEnvironmentStringsi unhandledExceptionFilter.
__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
);