Kopfzeilenanmerkungen
[In diesem Thema werden die Anmerkungen beschrieben, die in den Windows-Headern über Windows 7 unterstützt werden. Wenn Sie für Windows 8 entwickeln, sollten Sie die anmerkungen verwenden, die in SAL Annotationsbeschrieben sind.]
Kopfzeilenanmerkungen beschreiben, wie eine Funktion ihre Parameter und rückgabewerte verwendet. Diese Anmerkungen wurden vielen der Windows-Headerdateien hinzugefügt, um sicherzustellen, dass Sie die Windows-API ordnungsgemäß aufrufen. Wenn Sie die Codeanalyse aktivieren, die ab Visual Studio 2005 verfügbar ist, generiert der Compiler Warnungen der Ebene 6000, wenn Sie diese Funktionen nicht gemäß der durch die Anmerkungen beschriebenen Verwendung aufrufen. Sie können diese Anmerkungen auch in Ihrem eigenen Code hinzufügen, um sicherzustellen, dass sie ordnungsgemäß aufgerufen wird. Informationen zum Aktivieren der Codeanalyse in Visual Studio finden Sie in der Dokumentation zu Ihrer Version von Visual Studio.
Diese Anmerkungen werden in Specstrings.h definiert. Sie basieren auf Grundtypen, die Teil der Standardanmerkungssprache (STANDARD Annotation Language, SAL) sind und mithilfe von _declspec("SAL_*")implementiert werden.
Es gibt zwei Klassen von Anmerkungen: Pufferanmerkungen und erweiterte Anmerkungen.
Pufferanmerkungen
Pufferanmerkungen beschreiben, wie Funktionen ihre Zeiger verwenden und zum Erkennen von Pufferüberläufen verwendet werden können. Jeder Parameter kann null oder eine Pufferanmerkung verwenden. Eine Pufferanmerkung wird mit einem führenden Unterstrich und den in den folgenden Abschnitten beschriebenen Komponenten erstellt.
| Puffergröße | Beschreibung |
|---|---|
|
(Größe) |
Gibt die Gesamtgröße des Puffers an. Verwendung mit _bcount und _ecount; verwenden Sie nicht mit _part. Dieser Wert ist der barrierefreie Raum; es kann kleiner als der zugewiesene Platz sein. |
|
(Größe,Länge) |
Gibt die Gesamtgröße und initialisierte Länge des Puffers an. Wird mit _bcount_part und _ecount_part verwendet. Die Gesamtgröße kann kleiner als der zugewiesene Speicherplatz sein. |
| Puffergrößeneinheiten | Beschreibung |
|---|---|
|
_bcount |
Die Puffergröße befindet sich in Byte. |
|
_ecount |
Die Puffergröße befindet sich in Elementen. |
| Richtung | Beschreibung |
|---|---|
|
_in |
Die Funktion liest aus dem Puffer. Der Aufrufer stellt den Puffer bereit und initialisiert ihn. |
|
_inout |
Die Funktion liest sowohl aus als auch schreibgeschützt in Puffer. Der Aufrufer stellt den Puffer bereit und initialisiert ihn. Bei Verwendung mit _deref kann der Puffer von der Funktion neu zugeordnet werden. |
|
_out |
Die Funktion schreibt in den Puffer. Wenn sie für den Rückgabewert oder mit _deref verwendet wird, stellt die Funktion den Puffer bereit und initialisiert ihn. Andernfalls stellt der Aufrufer den Puffer bereit, und die Funktion initialisiert ihn. |
| Dereferenzierung | Beschreibung |
|---|---|
|
_deref |
Leiten Sie den Parameter ab, um den Pufferzeiger abzurufen. Dieser Parameter ist möglicherweise nicht NULL-. |
|
_deref_opt |
Leiten Sie den Parameter ab, um den Pufferzeiger abzurufen. Dieser Parameter kann NULL-sein. |
| Initialisierung | Beschreibung |
|---|---|
|
_full |
Die Funktion initialisiert den gesamten Puffer. Wird nur für Ausgabepuffer verwendet. |
|
_part |
Die Funktion initialisiert einen Teil des Puffers und gibt explizit an, wie viel. Wird nur für Ausgabepuffer verwendet. |
| Erforderlicher oder optionaler Puffer | Beschreibung |
|---|---|
|
_opt |
Dieser Parameter kann NULL-sein. |
Das folgende Beispiel zeigt die Anmerkungen für die funktion GetModuleFileName. Der hModule--Parameter ist ein optionaler Eingabeparameter. Der parameter lpFilename ist ein Ausgabeparameter; Die Größe in Zeichen wird durch den nSize Parameter angegeben, und die Länge enthält das NULL-zeichen-endating-Zeichen. Der nSize Parameter ist ein Eingabeparameter.
DWORD
WINAPI
GetModuleFileName(
__in_opt HMODULE hModule,
__out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
__in DWORD nSize
);
Im Folgenden sind die Anmerkungen aufgeführt, die in Specstrings.h definiert sind. Verwenden Sie die Informationen in den obigen Tabellen, um ihre Bedeutung zu interpretieren.
__bcount(Größe)
__bcount_opt(Größe)
__deref_bcount(Größe)
__deref_bcount_opt(Größe)
__deref_ecount(Größe)
__deref_ecount_opt(Größe)
__deref_in
__deref_in_bcount(Größe)
__deref_in_bcount_opt(Größe)
__deref_in_ecount(Größe)
__deref_in_ecount_opt(Größe)
__deref_in_opt
__deref_inout
__deref_inout_bcount(Größe)
__deref_inout_bcount_full(Größe)
__deref_inout_bcount_full_opt(Größe)
__deref_inout_bcount_opt(Größe)
__deref_inout_bcount_part(Größe,Länge)
__deref_inout_bcount_part_opt(Größe,Länge)
__deref_inout_ecount(Größe)
__deref_inout_ecount_full(Größe)
__deref_inout_ecount_full_opt(Größe)
__deref_inout_ecount_opt(Größe)
__deref_inout_ecount_part(Größe,Länge)
__deref_inout_ecount_part_opt(Größe,Länge)
__deref_inout_opt
__deref_opt_bcount(Größe)
__deref_opt_bcount_opt(Größe)
__deref_opt_ecount(Größe)
__deref_opt_ecount_opt(Größe)
__deref_opt_in
__deref_opt_in_bcount(Größe)
__deref_opt_in_bcount_opt(Größe)
__deref_opt_in_ecount(Größe)
__deref_opt_in_ecount_opt(Größe)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount(Größe)
__deref_opt_inout_bcount_full(Größe)
__deref_opt_inout_bcount_full_opt(Größe)
__deref_opt_inout_bcount_opt(Größe)
__deref_opt_inout_bcount_part(Größe,Länge)
__deref_opt_inout_bcount_part_opt(Größe,Länge)
__deref_opt_inout_ecount(Größe)
__deref_opt_inout_ecount_full(Größe)
__deref_opt_inout_ecount_full_opt(Größe)
__deref_opt_inout_ecount_opt(Größe)
__deref_opt_inout_ecount_part(Größe,Länge)
__deref_opt_inout_ecount_part_opt(Größe,Länge)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount(Größe)
__deref_opt_out_bcount_full(Größe)
__deref_opt_out_bcount_full_opt(Größe)
__deref_opt_out_bcount_opt(Größe)
__deref_opt_out_bcount_part(Größe,Länge)
__deref_opt_out_bcount_part_opt(Größe,Länge)
__deref_opt_out_ecount(Größe)
__deref_opt_out_ecount_full(Größe)
__deref_opt_out_ecount_full_opt(Größe)
__deref_opt_out_ecount_opt(Größe)
__deref_opt_out_ecount_part(Größe,Länge)
__deref_opt_out_ecount_part_opt(Größe,Länge)
__deref_opt_out_opt
__deref_out
__deref_out_bcount(Größe)
__deref_out_bcount_full(Größe)
__deref_out_bcount_full_opt(Größe)
__deref_out_bcount_opt(Größe)
__deref_out_bcount_part(Größe,Länge)
__deref_out_bcount_part_opt(Größe,Länge)
__deref_out_ecount(Größe)
__deref_out_ecount_full(Größe)
__deref_out_ecount_full_opt(Größe)
__deref_out_ecount_opt(Größe)
__deref_out_ecount_part(Größe,Länge)
__deref_out_ecount_part_opt(Größe,Länge)
__deref_out_opt
__ecount(Größe)
__ecount_opt(Größe)
__in
__in_bcount(Größe)
__in_bcount_opt(Größe)
__in_ecount(Größe)
__in_ecount_opt(Größe)
__in_opt
__inout
__inout_bcount(Größe)
__inout_bcount_full(Größe)
__inout_bcount_full_opt(Größe)
__inout_bcount_opt(Größe)
__inout_bcount_part(Größe,Länge)
__inout_bcount_part_opt(Größe,Länge)
__inout_ecount(Größe)
__inout_ecount_full(Größe)
__inout_ecount_full_opt(Größe)
__inout_ecount_opt(Größe)
__inout_ecount_part(Größe,Länge)
__inout_ecount_part_opt(Größe,Länge)
__inout_opt
__aus
__out_bcount(Größe)
__out_bcount_full(Größe)
__out_bcount_full_opt(Größe)
__out_bcount_opt(Größe)
__out_bcount_part(Größe,Länge)
__out_bcount_part_opt(Größe,Länge)
__out_ecount(Größe)
__out_ecount_full(Größe)
__out_ecount_full_opt(Größe)
__out_ecount_opt(Größe)
__out_ecount_part(Größe,Länge)
__out_ecount_part_opt(Größe,Länge)
__out_opt
Erweiterte Anmerkungen
Erweiterte Anmerkungen enthalten zusätzliche Informationen zum Parameter oder Rückgabewert. Jeder Parameter oder Rückgabewert kann null oder eine erweiterte Anmerkung verwenden.
| Anmerkung | Beschreibung |
|---|---|
|
__blocksOn(Ressource) |
Die Funktionen blockieren die angegebene Ressource. |
|
__callback |
Die Funktion kann als Funktionszeiger verwendet werden. |
|
__checkReturn |
Anrufer müssen den Rückgabewert überprüfen. |
|
__format_string |
Der Parameter ist eine Zeichenfolge, die printf-style % Markierungen enthält. |
|
__in_awcount(Ausdruck,Größe) |
Wenn der Ausdruck beim Beenden wahr ist, wird die Größe des Eingabepuffers in Byte angegeben. Wenn der Ausdruck falsch ist, wird die Größe in Elementen angegeben. |
|
__nullnullterminated |
Auf den Puffer kann bis einschließlich der ersten Sequenz von zwei null Zeichen oder Zeiger zugegriffen werden. |
|
__nullterminated |
Auf den Puffer kann bis zu und einschließlich des ersten null Zeichen oder Zeigers zugegriffen werden. |
|
__out_awcount(Ausdruck,Größe) |
Wenn der Ausdruck beim Beenden wahr ist, wird die Größe des Ausgabepuffers in Byte angegeben. Wenn der Ausdruck falsch ist, wird die Größe in Elementen angegeben. |
|
__override |
Gibt das Verhalten der Außerkraftsetzung im C#-Stil für virtuelle Methoden an. |
|
__reserved |
Der Parameter ist für die zukünftige Verwendung reserviert und muss null oder NULLsein. |
|
__success(Ausdruck) |
Wenn der Ausdruck beim Beenden wahr ist, kann der Aufrufer auf alle garantien zurückgreifen, die von anderen Anmerkungen angegeben werden. Wenn der Ausdruck falsch ist, kann der Aufrufer nicht auf die Garantien vertrauen. Diese Anmerkung wird automatisch zu Funktionen hinzugefügt, die einen HRESULT- Wert zurückgeben. |
|
__typefix(ctype) |
Behandeln Sie den Parameter nicht als deklarierten Typ, sondern als angegebenen Typ. |
Die folgenden Beispiele zeigen den Puffer und erweiterte Anmerkungen für die DeleteTimerQueueTimer, FreeEnvironmentStringsund UnhandledExceptionFilter- Funktionen.
__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
);