Sidhuvudkommentarer
[Det här avsnittet beskriver de anteckningar som stöds i Windows-huvuden via Windows 7. Om du utvecklar för Windows 8 bör du använda anteckningarna som beskrivs i SAL-anteckningar.]
Rubrikanteckningar beskriver hur en funktion använder sina parametrar och returvärde. Dessa anteckningar har lagts till i många av Windows-huvudfilerna för att hjälpa dig att se till att du anropar Windows-API:et korrekt. Om du aktiverar kodanalys, som är tillgänglig från och med Visual Studio 2005, skapar kompilatorn nivå 6000-varningar om du inte anropar dessa funktioner enligt den användning som beskrivs i anteckningarna. Du kan också lägga till dessa anteckningar i din egen kod för att säkerställa att den anropas korrekt. Information om hur du aktiverar kodanalys i Visual Studio finns i dokumentationen för din version av Visual Studio.
Dessa anteckningar definieras i Specstrings.h. De bygger på primitiver som ingår i Standard Annotation Language (SAL) och implementeras med hjälp av _declspec("SAL_*").
Det finns två klasser av anteckningar: buffertanteckningar och avancerade anteckningar.
Buffertanteckningar
Buffertanteckningar beskriver hur funktioner använder sina pekare och kan användas för att identifiera buffertöverskridanden. Varje parameter kan använda noll eller en buffertanteckning. En buffertanteckning skapas med ett inledande understreck och de komponenter som beskrivs i följande avsnitt.
| Buffertstorlek | Beskrivning |
|---|---|
|
(storlek) |
Anger buffertens totala storlek. Använd med _bcount och _ecount; använd inte med _part. Det här värdet är det tillgängliga utrymmet. det kan vara mindre än det allokerade utrymmet. |
|
(storlek,längd) |
Anger buffertens totala storlek och initierade längd. Använd med _bcount_part och _ecount_part. Den totala storleken kan vara mindre än det allokerade utrymmet. |
| Buffertstorleksenheter | Beskrivning |
|---|---|
|
_bcount |
Buffertstorleken är i byte. |
|
_ecount |
Buffertstorleken finns i element. |
| Riktning | Beskrivning |
|---|---|
|
_in |
Funktionen läser från bufferten. Anroparen tillhandahåller bufferten och initierar den. |
|
_inout |
Funktionen både läser från och skriver till buffert. Anroparen tillhandahåller bufferten och initierar den. Om den används med _deref kan bufferten omallokeras av funktionen. |
|
_out |
Funktionen skriver till bufferten. Om den används på returvärdet eller med _deref tillhandahåller funktionen bufferten och initierar den. Annars tillhandahåller anroparen bufferten och funktionen initierar den. |
| Indirektion | Beskrivning |
|---|---|
|
_deref |
Dereference parametern för att hämta buffertpekaren. Den här parametern kanske inte är NULL-. |
|
_deref_opt |
Dereference parametern för att hämta buffertpekaren. Den här parametern kan vara NULL-. |
| Initiering | Beskrivning |
|---|---|
|
_full |
Funktionen initierar hela bufferten. Använd endast med utdatabuffertar. |
|
_part |
Funktionen initierar en del av bufferten och anger uttryckligen hur mycket. Använd endast med utdatabuffertar. |
| Obligatorisk eller valfri buffert | Beskrivning |
|---|---|
|
_opt |
Den här parametern kan vara NULL-. |
I följande exempel visas anteckningarna för funktionen GetModuleFileName. Parametern hModule är en valfri indataparameter . Parametern lpFilename är en utdataparameter. dess storlek i tecken anges av parametern nSize och dess längd innehåller null--avslutande tecken. Parametern nSize är en indataparameter.
DWORD
WINAPI
GetModuleFileName(
__in_opt HMODULE hModule,
__out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
__in DWORD nSize
);
Följande är de anteckningar som definierats i Specstrings.h. Använd informationen i tabellerna ovan för att tolka deras innebörd.
__bcount(storlek)
__bcount_opt(storlek)
__deref_bcount(storlek)
__deref_bcount_opt(storlek)
__deref_ecount(storlek)
__deref_ecount_opt(storlek)
__deref_in
__deref_in_bcount(storlek)
__deref_in_bcount_opt(storlek)
__deref_in_ecount(storlek)
__deref_in_ecount_opt(storlek)
__deref_in_opt
__deref_inout
__deref_inout_bcount(storlek)
__deref_inout_bcount_full(storlek)
__deref_inout_bcount_full_opt(storlek)
__deref_inout_bcount_opt(storlek)
__deref_inout_bcount_part(storlek,längd)
__deref_inout_bcount_part_opt(storlek,längd)
__deref_inout_ecount(storlek)
__deref_inout_ecount_full(storlek)
__deref_inout_ecount_full_opt(storlek)
__deref_inout_ecount_opt(storlek)
__deref_inout_ecount_part(storlek,längd)
__deref_inout_ecount_part_opt(storlek,längd)
__deref_inout_opt
__deref_opt_bcount(storlek)
__deref_opt_bcount_opt(storlek)
__deref_opt_ecount(storlek)
__deref_opt_ecount_opt(storlek)
__deref_opt_in
__deref_opt_in_bcount(storlek)
__deref_opt_in_bcount_opt(storlek)
__deref_opt_in_ecount(storlek)
__deref_opt_in_ecount_opt(storlek)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount(storlek)
__deref_opt_inout_bcount_full(storlek)
__deref_opt_inout_bcount_full_opt(storlek)
__deref_opt_inout_bcount_opt(storlek)
__deref_opt_inout_bcount_part(storlek,längd)
__deref_opt_inout_bcount_part_opt(storlek,längd)
__deref_opt_inout_ecount(storlek)
__deref_opt_inout_ecount_full(storlek)
__deref_opt_inout_ecount_full_opt(storlek)
__deref_opt_inout_ecount_opt(storlek)
__deref_opt_inout_ecount_part(storlek,längd)
__deref_opt_inout_ecount_part_opt(storlek,längd)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount(storlek)
__deref_opt_out_bcount_full(storlek)
__deref_opt_out_bcount_full_opt(storlek)
__deref_opt_out_bcount_opt(storlek)
__deref_opt_out_bcount_part(storlek,längd)
__deref_opt_out_bcount_part_opt(storlek,längd)
__deref_opt_out_ecount(storlek)
__deref_opt_out_ecount_full(storlek)
__deref_opt_out_ecount_full_opt(storlek)
__deref_opt_out_ecount_opt(storlek)
__deref_opt_out_ecount_part(storlek,längd)
__deref_opt_out_ecount_part_opt(storlek,längd)
__deref_opt_out_opt
__deref_out
__deref_out_bcount(storlek)
__deref_out_bcount_full(storlek)
__deref_out_bcount_full_opt(storlek)
__deref_out_bcount_opt(storlek)
__deref_out_bcount_part(storlek,längd)
__deref_out_bcount_part_opt(storlek,längd)
__deref_out_ecount(storlek)
__deref_out_ecount_full(storlek)
__deref_out_ecount_full_opt(storlek)
__deref_out_ecount_opt(storlek)
__deref_out_ecount_part(storlek,längd)
__deref_out_ecount_part_opt(storlek,längd)
__deref_out_opt
__ecount(storlek)
__ecount_opt(storlek)
__i
__in_bcount(storlek)
__in_bcount_opt(storlek)
__in_ecount(storlek)
__in_ecount_opt(storlek)
__in_opt
__inout
__inout_bcount(storlek)
__inout_bcount_full(storlek)
__inout_bcount_full_opt(storlek)
__inout_bcount_opt(storlek)
__inout_bcount_part(storlek,längd)
__inout_bcount_part_opt(storlek,längd)
__inout_ecount(storlek)
__inout_ecount_full(storlek)
__inout_ecount_full_opt(storlek)
__inout_ecount_opt(storlek)
__inout_ecount_part(storlek,längd)
__inout_ecount_part_opt(storlek,längd)
__inout_opt
__ut
__out_bcount(storlek)
__out_bcount_full(storlek)
__out_bcount_full_opt(storlek)
__out_bcount_opt(storlek)
__out_bcount_part(storlek,längd)
__out_bcount_part_opt(storlek,längd)
__out_ecount(storlek)
__out_ecount_full(storlek)
__out_ecount_full_opt(storlek)
__out_ecount_opt(storlek)
__out_ecount_part(storlek,längd)
__out_ecount_part_opt(storlek,längd)
__out_opt
Avancerade anteckningar
Avancerade anteckningar ger ytterligare information om parametern eller returvärdet. Varje parameter eller returvärde kan använda noll eller en avancerad anteckning.
| Anteckning | Beskrivning |
|---|---|
|
__blocksOn(resurs) |
Funktionerna blockeras på den angivna resursen. |
|
__callback |
Funktionen kan användas som en funktionspekare. |
|
__checkReturn |
Anropare måste kontrollera returvärdet. |
|
__format_string |
Parametern är en sträng som innehåller printf-format % markörer. |
|
__in_awcount(expr,storlek) |
Om uttrycket är sant vid avslut anges storleken på indatabufferten i byte. Om uttrycket är falskt anges storleken i element. |
|
__nullnullterminated |
Bufferten kan nås upp till och inklusive den första sekvensen med två null- tecken eller pekare. |
|
__nullterminated |
Bufferten kan nås upp till och inklusive den första null- tecken eller pekare. |
|
__out_awcount(expr,storlek) |
Om uttrycket är sant vid avslut anges storleken på utdatabufferten i byte. Om uttrycket är falskt anges storleken i element. |
|
__override |
Anger Åsidosättningsbeteende i C#-stil för virtuella metoder. |
|
__reserved |
Parametern är reserverad för framtida användning och måste vara noll eller NULL-. |
|
__success() |
Om uttrycket är sant vid avslut kan anroparen förlita sig på alla garantier som anges av andra anteckningar. Om uttrycket är falskt kan anroparen inte förlita sig på garantierna. Den här anteckningen läggs automatiskt till i funktioner som returnerar ett HRESULT- värde. |
|
__typefix(ctype) |
Behandla parametern som den angivna typen i stället för dess deklarerade typ. |
I följande exempel visas bufferten och avancerade anteckningar för funktionerna DeleteTimerQueueTimer, FreeEnvironmentStringsoch 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
);