Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
[In dit onderwerp worden de aantekeningen beschreven die worden ondersteund in de Windows-headers via Windows 7. Als u ontwikkelt voor Windows 8, moet u de aantekeningen gebruiken die worden beschreven in SAL-aantekeningen.]
Headeraantekeningen beschrijven hoe een functie de parameters en retourwaarde gebruikt. Deze aantekeningen zijn toegevoegd aan veel van de Windows-headerbestanden om ervoor te zorgen dat u de Windows-API correct aanroept. Als u codeanalyse inschakelt, die beschikbaar is vanaf Visual Studio 2005, produceert de compiler waarschuwingen op niveau 6000 als u deze functies niet aanroept volgens het gebruik dat wordt beschreven via de aantekeningen. U kunt deze aantekeningen ook toevoegen in uw eigen code om ervoor te zorgen dat deze correct worden aangeroepen. Zie de documentatie voor uw versie van Visual Studio om codeanalyse in te schakelen in Visual Studio.
Deze aantekeningen worden gedefinieerd in Specstrings.h. Ze zijn gebouwd op primitieven die deel uitmaken van de Standard Annotation Language (SAL) en geïmplementeerd met behulp van _declspec("SAL_*").
Er zijn twee klassen aantekeningen: bufferaantekeningen en geavanceerde aantekeningen.
Bufferaantekeningen
Bufferaantekeningen beschrijven hoe functies hun aanwijzers gebruiken en kunnen worden gebruikt om bufferoverschrijdingen te detecteren. Elke parameter kan nul of één bufferaantekening gebruiken. Een bufferaantekening wordt samengesteld met een voorlooponderstrepingsteken en de onderdelen die in de volgende secties worden beschreven.
| Buffergrootte | Beschrijving |
|---|---|
|
(grootte) |
Hiermee geeft u de totale grootte van de buffer. Gebruiken met _bcount en _ecount; niet gebruiken met _part. Deze waarde is de toegankelijke ruimte; deze kan kleiner zijn dan de toegewezen ruimte. |
|
(grootte,lengte) |
Hiermee geeft u de totale grootte en geïnitialiseerde lengte van de buffer. Gebruiken met _bcount_part en _ecount_part. De totale grootte mag kleiner zijn dan de toegewezen ruimte. |
| Buffergrootte-eenheden | Beschrijving |
|---|---|
|
_bcount |
De buffergrootte is in bytes. |
|
_ecount |
De buffergrootte bevindt zich in elementen. |
| Richting | Beschrijving |
|---|---|
|
_in |
De functie leest uit de buffer. De aanroeper biedt de buffer en initialiseert deze. |
|
_inout |
De functie leest van en schrijft naar buffer. De aanroeper biedt de buffer en initialiseert deze. Als deze wordt gebruikt met _deref, kan de buffer opnieuw worden toegewezen door de functie. |
|
_out |
De functie schrijft naar de buffer. Als deze wordt gebruikt voor de retourwaarde of met _deref, levert de functie de buffer en initialiseert deze. Anders levert de aanroeper de buffer en initialiseert de functie deze. |
| Indirectie | Beschrijving |
|---|---|
|
_deref |
Deductie van de parameter om de bufferaanwijzer te verkrijgen. Deze parameter is mogelijk niet NULL-. |
|
_deref_opt |
Deductie van de parameter om de bufferaanwijzer te verkrijgen. Deze parameter kan worden NULL-. |
| Initialisatie | Beschrijving |
|---|---|
|
_full |
De functie initialiseert de volledige buffer. Gebruik alleen met uitvoerbuffers. |
|
_part |
De functie initialiseert een deel van de buffer en geeft expliciet aan hoeveel. Gebruik alleen met uitvoerbuffers. |
| Vereiste of optionele buffer | Beschrijving |
|---|---|
|
_opt |
Deze parameter kan worden NULL-. |
In het volgende voorbeeld ziet u de aantekeningen voor de functie GetModuleFileName. De parameter hModule is een optionele invoerparameter. De parameter lpFilename is een uitvoerparameter; de grootte in tekens wordt opgegeven door de nSize parameter en de lengte bevat het null--terminating teken. De nSize parameter is een invoerparameter.
DWORD
WINAPI
GetModuleFileName(
__in_opt HMODULE hModule,
__out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
__in DWORD nSize
);
Hieronder ziet u de aantekeningen die zijn gedefinieerd in Specstrings.h. Gebruik de informatie in de bovenstaande tabellen om hun betekenis te interpreteren.
__bcount(grootte)
__bcount_opt(grootte)
__deref_bcount(grootte)
__deref_bcount_opt(grootte)
__deref_ecount(grootte)
__deref_ecount_opt(grootte)
__deref_in
__deref_in_bcount(grootte)
__deref_in_bcount_opt(grootte)
__deref_in_ecount(grootte)
__deref_in_ecount_opt(grootte)
__deref_in_opt
__deref_inout
__deref_inout_bcount(grootte)
__deref_inout_bcount_full(grootte)
__deref_inout_bcount_full_opt(grootte)
__deref_inout_bcount_opt(grootte)
__deref_inout_bcount_part(grootte,lengte)
__deref_inout_bcount_part_opt(grootte,lengte)
__deref_inout_ecount(grootte)
__deref_inout_ecount_full(grootte)
__deref_inout_ecount_full_opt(grootte)
__deref_inout_ecount_opt(grootte)
__deref_inout_ecount_part(grootte,lengte)
__deref_inout_ecount_part_opt(grootte,lengte)
__deref_inout_opt
__deref_opt_bcount(grootte)
__deref_opt_bcount_opt(grootte)
__deref_opt_ecount(grootte)
__deref_opt_ecount_opt(grootte)
__deref_opt_in
__deref_opt_in_bcount(grootte)
__deref_opt_in_bcount_opt(grootte)
__deref_opt_in_ecount(grootte)
__deref_opt_in_ecount_opt(grootte)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount(grootte)
__deref_opt_inout_bcount_full(grootte)
__deref_opt_inout_bcount_full_opt(grootte)
__deref_opt_inout_bcount_opt(grootte)
__deref_opt_inout_bcount_part(grootte,lengte)
__deref_opt_inout_bcount_part_opt(grootte,lengte)
__deref_opt_inout_ecount(grootte)
__deref_opt_inout_ecount_full(grootte)
__deref_opt_inout_ecount_full_opt(grootte)
__deref_opt_inout_ecount_opt(grootte)
__deref_opt_inout_ecount_part(grootte,lengte)
__deref_opt_inout_ecount_part_opt(grootte,lengte)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount(grootte)
__deref_opt_out_bcount_full(grootte)
__deref_opt_out_bcount_full_opt(grootte)
__deref_opt_out_bcount_opt(grootte)
__deref_opt_out_bcount_part(grootte,lengte)
__deref_opt_out_bcount_part_opt(grootte,lengte)
__deref_opt_out_ecount(grootte)
__deref_opt_out_ecount_full(grootte)
__deref_opt_out_ecount_full_opt(grootte)
__deref_opt_out_ecount_opt(grootte)
__deref_opt_out_ecount_part(grootte,lengte)
__deref_opt_out_ecount_part_opt(grootte,lengte)
__deref_opt_out_opt
__deref_out
__deref_out_bcount(grootte)
__deref_out_bcount_full(grootte)
__deref_out_bcount_full_opt(grootte)
__deref_out_bcount_opt(grootte)
__deref_out_bcount_part(grootte,lengte)
__deref_out_bcount_part_opt(grootte,lengte)
__deref_out_ecount(grootte)
__deref_out_ecount_full(grootte)
__deref_out_ecount_full_opt(grootte)
__deref_out_ecount_opt(grootte)
__deref_out_ecount_part(grootte,lengte)
__deref_out_ecount_part_opt(grootte,lengte)
__deref_out_opt
__ecount(grootte)
__ecount_opt(grootte)
__in
__in_bcount(grootte)
__in_bcount_opt(grootte)
__in_ecount(grootte)
__in_ecount_opt(grootte)
__in_opt
__inout
__inout_bcount(grootte)
__inout_bcount_full(grootte)
__inout_bcount_full_opt(grootte)
__inout_bcount_opt(grootte)
__inout_bcount_part(grootte,lengte)
__inout_bcount_part_opt(grootte,lengte)
__inout_ecount(grootte)
__inout_ecount_full(grootte)
__inout_ecount_full_opt(grootte)
__inout_ecount_opt(grootte)
__inout_ecount_part(grootte,lengte)
__inout_ecount_part_opt(grootte,lengte)
__inout_opt
__buiten
__out_bcount(grootte)
__out_bcount_full(grootte)
__out_bcount_full_opt(grootte)
__out_bcount_opt(grootte)
__out_bcount_part(grootte,lengte)
__out_bcount_part_opt(grootte,lengte)
__out_ecount(grootte)
__out_ecount_full(grootte)
__out_ecount_full_opt(grootte)
__out_ecount_opt(grootte)
__out_ecount_part(grootte,lengte)
__out_ecount_part_opt(grootte,lengte)
__out_opt
Geavanceerde aantekeningen
Geavanceerde aantekeningen bieden aanvullende informatie over de parameter of retourwaarde. Elke parameter of retourwaarde kan nul of één geavanceerde aantekening gebruiken.
| Aantekening | Beschrijving |
|---|---|
|
__blocksOn() |
De functies worden geblokkeerd voor de opgegeven resource. |
|
__callback |
De functie kan worden gebruikt als functiepointer. |
|
__checkReturn |
Bellers moeten de retourwaarde controleren. |
|
__format_string |
De parameter is een tekenreeks die printf-style % markeringen bevat. |
|
__in_awcount(expr,grootte) |
Als de expressie waar is bij het afsluiten, wordt de grootte van de invoerbuffer opgegeven in bytes. Als de expressie onwaar is, wordt de grootte opgegeven in elementen. |
|
__nullnullterminated |
De buffer kan worden geopend tot en met de eerste reeks van twee null- tekens of aanwijzers. |
|
__nullterminated |
De buffer kan worden geopend tot en met de eerste null- teken of aanwijzer. |
|
__out_awcount(expr,grootte) |
Als de expressie waar is bij het afsluiten, wordt de grootte van de uitvoerbuffer opgegeven in bytes. Als de expressie onwaar is, wordt de grootte opgegeven in elementen. |
|
__override |
Hiermee geeft u het gedrag van C#-stijl overschrijven voor virtuele methoden. |
|
__reserved |
De parameter is gereserveerd voor toekomstig gebruik en moet nul of NULL-zijn. |
|
__success(expr) |
Als de expressie waar is bij het afsluiten, kan de aanroeper vertrouwen op alle garanties die zijn opgegeven door andere aantekeningen. Als de expressie onwaar is, kan de aanroeper niet vertrouwen op de garanties. Deze aantekening wordt automatisch toegevoegd aan functies die een HRESULT--waarde retourneren. |
|
__typefix(ctype) |
Behandel de parameter als het opgegeven type in plaats van het gedeclareerde type. |
In de volgende voorbeelden ziet u de buffer en geavanceerde aantekeningen voor de functies DeleteTimerQueueTimer, FreeEnvironmentStringsen 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
);