Élőfej-széljegyzetek
[Ez a témakör a Windows-fejlécekben a Windows 7-ben támogatott széljegyzeteket ismerteti. Ha Windows 8-hoz fejleszt, használja a SAL annotationscímű cikkben leírt megjegyzéseket.
Az élőfej-széljegyzetek azt írják le, hogy egy függvény hogyan használja a paramétereit és adja vissza az értéket. Ezek a széljegyzetek számos Windows-fejlécfájlhoz lettek hozzáadva, hogy biztosan helyesen hívja meg a Windows API-t. Ha engedélyezi a Visual Studio 2005-től kezdődően elérhető kódelemzést, a fordító 6000-es szintű figyelmeztetéseket fog generálni, ha ezeket a függvényeket nem hívja meg a megjegyzésekben leírt használat alapján. Ezeket a széljegyzeteket a saját kódjában is hozzáadhatja, így meggyőződhet arról, hogy megfelelően van meghívva. A Visual Studio kódelemzésének engedélyezéséhez tekintse meg a Visual Studio verziójának dokumentációját.
Ezeket a széljegyzeteket a Specstrings.h határozza meg. Ezek olyan primitívekre épülnek, amelyek a Standard Annotation Language (SAL) részét képezik, és _declspec("SAL_*")használatával implementálják őket.
A széljegyzeteknek két osztálya van: pufferes széljegyzetek és speciális széljegyzetek.
Pufferjegyzetek
A pufferjegyzetek azt írják le, hogyan használják a függvények a mutatóikat, és hogyan észlelhetők a puffertúllépések. Minden paraméter használhat nulla vagy egy pufferjegyzetet. A puffer széljegyzete egy kezdő aláhúzásjellel és az alábbi szakaszokban leírt összetevőkkel jön létre.
| Puffer mérete | Leírás |
|---|---|
|
(méret) |
A puffer teljes méretét adja meg. _bcount és _ecount; ne használja _part. Ez az érték az akadálymentes terület; lehet, hogy kisebb, mint a lefoglalt terület. |
|
(méret,hossz) |
Megadja a puffer teljes méretét és inicializált hosszát. Használja _bcount_part és _ecount_part. A teljes méret kisebb lehet, mint a lefoglalt terület. |
| Pufferméretegységek | Leírás |
|---|---|
|
_bcount |
A puffer mérete bájtban van. |
|
_ecount |
A puffer mérete elemekben van. |
| Irány | Leírás |
|---|---|
|
_in |
A függvény a pufferből olvas be. A hívó biztosítja a puffert, és inicializálja azt. |
|
_inout |
A függvény mind a forrásból, mind pedig a pufferbe ír. A hívó biztosítja a puffert, és inicializálja azt. Ha a _deref használja, a függvény újratelepítheti a puffert. |
|
_out |
A függvény a pufferbe ír. Ha a visszatérési értéken vagy a _deref használja, a függvény biztosítja a puffert, és inicializálja azt. Ellenkező esetben a hívó biztosítja a puffert, és a függvény inicializálja azt. |
| Indirekt | Leírás |
|---|---|
|
_deref |
Halasztja a paramétert a puffermutató lekéréséhez. Ez a paraméter nem lehet NULL. |
|
_deref_opt |
Halasztja a paramétert a puffermutató lekéréséhez. Ez a paraméter lehet NULL. |
| Inicializálás | Leírás |
|---|---|
|
_full |
A függvény inicializálja a teljes puffert. Csak kimeneti pufferekkel használható. |
|
_part |
A függvény inicializálja a puffer egy részét, és explicit módon jelzi, hogy mennyi. Csak kimeneti pufferekkel használható. |
| Kötelező vagy nem kötelező puffer | Leírás |
|---|---|
|
_opt |
Ez a paraméter lehet NULL. |
Az alábbi példa a GetModuleFileName függvény megjegyzéseit mutatja be. A hModule paraméter nem kötelező bemeneti paraméter. Az lpFilename paraméter egy kimeneti paraméter; karakterméretét az nSize paraméter határozza meg, és a hossza tartalmazza a null-végződő karaktert. Az nSize paraméter egy bemeneti paraméter.
DWORD
WINAPI
GetModuleFileName(
__in_opt HMODULE hModule,
__out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
__in DWORD nSize
);
Az alábbiakban a Specstrings.h fájlban definiált széljegyzetek szerepelnek. A fenti táblázatokban szereplő információk segítségével értelmezze a jelentésüket.
__bcount(méret)
__bcount_opt(méret)
__deref_bcount(méret)
__deref_bcount_opt(méret)
__deref_ecount(méret)
__deref_ecount_opt(méret)
__deref_in
__deref_in_bcount(méret)
__deref_in_bcount_opt(méret)
__deref_in_ecount(méret)
__deref_in_ecount_opt(méret)
__deref_in_opt
__deref_inout
__deref_inout_bcount(méret)
__deref_inout_bcount_full(méret)
__deref_inout_bcount_full_opt(méret)
__deref_inout_bcount_opt(méret)
__deref_inout_bcount_part(méret,hossz)
__deref_inout_bcount_part_opt(méret,hossz)
__deref_inout_ecount(méret)
__deref_inout_ecount_full(méret)
__deref_inout_ecount_full_opt(méret)
__deref_inout_ecount_opt(méret)
__deref_inout_ecount_part(méret,hossz)
__deref_inout_ecount_part_opt(méret,hossz)
__deref_inout_opt
__deref_opt_bcount(méret)
__deref_opt_bcount_opt(méret)
__deref_opt_ecount(méret)
__deref_opt_ecount_opt(méret)
__deref_opt_in
__deref_opt_in_bcount(méret)
__deref_opt_in_bcount_opt(méret)
__deref_opt_in_ecount(méret)
__deref_opt_in_ecount_opt(méret)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount(méret)
__deref_opt_inout_bcount_full(méret)
__deref_opt_inout_bcount_full_opt(méret)
__deref_opt_inout_bcount_opt(méret)
__deref_opt_inout_bcount_part(méret,hossz)
__deref_opt_inout_bcount_part_opt(méret,hossz)
__deref_opt_inout_ecount(méret)
__deref_opt_inout_ecount_full(méret)
__deref_opt_inout_ecount_full_opt(méret)
__deref_opt_inout_ecount_opt(méret)
__deref_opt_inout_ecount_part(méret,hossz)
__deref_opt_inout_ecount_part_opt(méret,hossz)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount(méret)
__deref_opt_out_bcount_full(méret)
__deref_opt_out_bcount_full_opt(méret)
__deref_opt_out_bcount_opt(méret)
__deref_opt_out_bcount_part(méret,hossz)
__deref_opt_out_bcount_part_opt(méret,hossz)
__deref_opt_out_ecount(méret)
__deref_opt_out_ecount_full(méret)
__deref_opt_out_ecount_full_opt(méret)
__deref_opt_out_ecount_opt(méret)
__deref_opt_out_ecount_part(méret,hossz)
__deref_opt_out_ecount_part_opt(méret,hossz)
__deref_opt_out_opt
__deref_out
__deref_out_bcount(méret)
__deref_out_bcount_full(méret)
__deref_out_bcount_full_opt(méret)
__deref_out_bcount_opt(méret)
__deref_out_bcount_part(méret,hossz)
__deref_out_bcount_part_opt(méret,hossz)
__deref_out_ecount(méret)
__deref_out_ecount_full(méret)
__deref_out_ecount_full_opt(méret)
__deref_out_ecount_opt(méret)
__deref_out_ecount_part(méret,hossz)
__deref_out_ecount_part_opt(méret,hossz)
__deref_out_opt
__ecount(méret)
__ecount_opt(méret)
__ban
__in_bcount(méret)
__in_bcount_opt(méret)
__in_ecount(méret)
__in_ecount_opt(méret)
__in_opt
__inout
__inout_bcount(méret)
__inout_bcount_full(méret)
__inout_bcount_full_opt(méret)
__inout_bcount_opt(méret)
__inout_bcount_part(méret,hossz)
__inout_bcount_part_opt(méret,hossz)
__inout_ecount(méret)
__inout_ecount_full(méret)
__inout_ecount_full_opt(méret)
__inout_ecount_opt(méret)
__inout_ecount_part(méret,hossz)
__inout_ecount_part_opt(méret,hossz)
__inout_opt
__ki
__out_bcount(méret)
__out_bcount_full(méret)
__out_bcount_full_opt(méret)
__out_bcount_opt(méret)
__out_bcount_part(méret,hossz)
__out_bcount_part_opt(méret,hossz)
__out_ecount(méret)
__out_ecount_full(méret)
__out_ecount_full_opt(méret)
__out_ecount_opt(méret)
__out_ecount_part(méret,hossz)
__out_ecount_part_opt(méret,hossz)
__out_opt
Speciális széljegyzetek
A speciális széljegyzetek további információt nyújtanak a paraméterről vagy a visszatérési értékről. Minden paraméter vagy visszatérési érték nulla vagy egy speciális széljegyzetet használhat.
| Megjegyzés | Leírás |
|---|---|
|
__blocksOn(erőforrás-) |
A függvények blokkolják a megadott erőforrást. |
|
__callback |
A függvény használható függvénymutatóként. |
|
__checkReturn |
A hívónak ellenőriznie kell a visszatérési értéket. |
|
__format_string |
A paraméter egy olyan sztring, amely nyomtatóf stílusú % jelölőket tartalmaz. |
|
__in_awcount(kitevő,méret) |
Ha a kifejezés igaz a kilépéskor, a bemeneti puffer mérete bájtban van megadva. Ha a kifejezés hamis, a méret az elemekben van megadva. |
|
__nullnullterminated |
A puffer legfeljebb két null karakter vagy mutató első sorozatához érhető el. |
|
__nullterminated |
A puffer legfeljebb az első null karakterhez vagy mutatóhoz érhető el. |
|
__out_awcount(kitevő,méret) |
Ha a kifejezés igaz a kilépéskor, a kimeneti puffer mérete bájtban van megadva. Ha a kifejezés hamis, a méret az elemekben van megadva. |
|
__override |
C#-stílusú felülbírálási viselkedést ad meg a virtuális metódusokhoz. |
|
__reserved |
A paraméter jövőbeli használatra van fenntartva, és nulla vagy NULLkell lennie. |
|
__success(expr) |
Ha a kifejezés igaz a kilépéskor, a hívó a többi széljegyzet által megadott összes garanciára támaszkodhat. Ha a kifejezés hamis, a hívó nem támaszkodhat a garanciákra. A rendszer automatikusan hozzáadja ezt a megjegyzést az HRESULT értéket visszaadó függvényekhez. |
|
__typefix(ctype) |
A paramétert a deklarált típus helyett a megadott típusként kezelje. |
Az alábbi példák a DeleteTimerQueueTimer, FreeEnvironmentStringsés UnhandledExceptionFilter függvények pufferét és speciális megjegyzéseit mutatják be.
__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
);