Kopfzeilenanmerkungen

  • Artikel

[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 in SAL-Anmerkungen beschriebenen Anmerkungen verwenden.]

Headeranmerkungen beschreiben, wie eine Funktion ihre Parameter und den Rückgabewert verwendet. Diese Anmerkungen wurden zu 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, erzeugt der Compiler Warnungen der Ebene 6000, wenn Sie diese Funktionen nicht gemäß der in den Anmerkungen beschriebenen Verwendung aufrufen. Sie können diese Anmerkungen auch in Ihrem eigenen Code hinzufügen, um sicherzustellen, dass sie ordnungsgemäß aufgerufen werden. Informationen zum Aktivieren der Codeanalyse in Visual Studio finden Sie in der Dokumentation für Ihre Visual Studio-Version.

Diese Anmerkungen werden in Specstrings.h definiert. Sie basieren auf Grundtypen, die Teil der StandardAnmerkungssprache (SAL) sind und mit _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. Verwenden Mit _bcount und _ecount; nicht mit _part verwenden. Dieser Wert ist der zugängliche Raum; er kann kleiner als der zugewiesene Speicherplatz sein.
(Größe,Länge)
 Gibt die Gesamtgröße und die initialisierte Länge des Puffers an. Verwenden Sie mit _bcount_part und _ecount_part. Die Gesamtgröße kann kleiner als der zugeordnete Speicherplatz sein.
Puffergrößeneinheiten BESCHREIBUNG
_bcount
 Die Puffergröße ist in Bytes angegeben.
_ecount
 Die Puffergröße befindet sich in Elementen.
Direction BESCHREIBUNG
_In
 Die Funktion liest aus dem Puffer. Der Aufrufer stellt den Puffer bereit und initialisiert ihn.
_Inout
 Die Funktion liest aus dem Puffer und schreibt in diesen. 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. Bei Verwendung für den Rückgabewert oder mit _deref stellt die Funktion den Puffer bereit und initialisiert ihn. Andernfalls stellt der Aufrufer den Puffer bereit, und die Funktion initialisiert ihn.
Dereferenzierung BESCHREIBUNG
_Deref
 Dereferenzieren des Parameters zum Abrufen des Pufferzeigers. Dieser Parameter ist möglicherweise nicht NULL.
_deref_opt
 Dereferenzieren des Parameters zum Abrufen des Pufferzeigers. Dieser Parameter kann NULL sein.
Initialisierung BESCHREIBUNG
_Voll
 Die Funktion initialisiert den gesamten Puffer. Verwenden Sie nur mit Ausgabepuffern.
_Teil
 Die Funktion initialisiert einen Teil des Puffers und gibt explizit an, wie viel. Verwenden Sie nur mit Ausgabepuffern.
Erforderlicher oder optionaler Puffer BESCHREIBUNG
_Opt
 Dieser Parameter kann NULL sein.

Das folgende Beispiel zeigt die Anmerkungen für die GetModuleFileName-Funktion . Der hModule-Parameter ist ein optionaler Eingabeparameter . Der Parameter lpFilename ist ein Ausgabeparameter. seine Größe in Zeichen wird durch den nSize-Parameter angegeben, und seine Länge enthält das NULL-Endzeichen. 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 in Specstrings.h definierten Anmerkungen aufgeführt. Verwenden Sie die Informationen in den obigen Tabellen, um deren Bedeutung zu interpretieren.

__bcount(Größe)
__bcount_opt(Größe)
__deref_bcount(size)
__deref_bcount_opt(Größe)
__deref_ecount(Size)
__deref_ecount_opt(Größe)
__deref_in
__deref_in_bcount(Size)
__deref_in_bcount_opt(size)
__deref_in_ecount(Size)
__deref_in_ecount_opt(size)
__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(Size)
__deref_inout_ecount_part(Größe,Länge)
__deref_inout_ecount_part_opt(Größe,Länge)
__deref_inout_opt
__deref_opt_bcount(Size)
__deref_opt_bcount_opt(Größe)
__deref_opt_ecount(Größe)
__deref_opt_ecount_opt(Größe)
__deref_opt_in
__deref_opt_in_bcount(Size)
__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(Size)
__deref_opt_inout_bcount_full(Size)
__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(Size)
__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(Size)
__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(Size)
__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(Size)
__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
__out
__out_bcount(Größe)
__out_bcount_full(Size)
__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(Size)
__out_ecount_full_opt(Size)
__out_ecount_opt(Size)
__out_ecount_part(Größe,Länge)
__out_ecount_part_opt(Größe,Länge)
__out_opt

Erweiterte Anmerkungen

Erweiterte Anmerkungen bieten 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 für die angegebene Ressource.
__Rückruf
 Die Funktion kann als Funktionszeiger verwendet werden.
__checkReturn
 Aufrufer müssen den Rückgabewert überprüfen.
__Format_string
 Der Parameter ist eine Zeichenfolge, die %-Marker im Printf-Stil enthält.
__in_awcount(expr,size)
 Wenn der Ausdruck beim Beenden true ist, wird die Größe des Eingabepuffers in Bytes angegeben. Wenn der Ausdruck false ist, wird die Größe in Elementen angegeben.
__nullnullterminated
 Auf den Puffer kann bis einschließlich der ersten Sequenz von zwei NULL-Zeichen oder Zeigern zugegriffen werden.
__Nullterminated
 Auf den Puffer kann bis einschließlich des ersten NULL-Zeichens oder Zeigers zugegriffen werden.
__out_awcount(expr,size)
 Wenn der Ausdruck beim Beenden true ist, wird die Größe des Ausgabepuffers in Bytes angegeben. Wenn der Ausdruck false ist, wird die Größe in Elementen angegeben.
__Überschreiben
 Gibt das Außerkraftsetzungsverhalten im C#-Format für virtuelle Methoden an.
__Reserviert
 Der Parameter ist für die zukünftige Verwendung reserviert und muss null oder NULL sein.
__success(expr)
 Wenn der Ausdruck beim Beenden true ist, kann sich der Aufrufer auf alle Garantien verlassen, die von anderen Anmerkungen angegeben werden. Wenn der Ausdruck false ist, kann sich der Aufrufer nicht auf die Garantien verlassen. Diese Anmerkung wird automatisch zu Funktionen hinzugefügt, die einen HRESULT-Wert zurückgeben.
__typefix(ctype)
 Behandeln Sie den Parameter als angegebenen Typ und nicht als deklarierten Typ.

Die folgenden Beispiele zeigen den Puffer und erweiterte Anmerkungen für die Funktionen DeleteTimerQueueTimer, FreeEnvironmentStrings und 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
    );

SAL-Anmerkungen

Exemplarische Vorgehensweise: Analysieren von C/C++-Code auf Fehler