Annotazioni intestazione

  • Articolo

[Questo argomento descrive le annotazioni supportate nelle intestazioni di Windows tramite Windows 7. Se si sta sviluppando per Windows 8, è necessario usare le annotazioni descritte in annotazioni SAL.

Le annotazioni di intestazione descrivono come una funzione usa i parametri e il valore restituito. Queste annotazioni sono state aggiunte a molti dei file di intestazione di Windows per assicurarsi di chiamare correttamente l'API Di Windows. Se si abilita l'analisi del codice, disponibile a partire da Visual Studio 2005, il compilatore produrrà avvisi di livello 6000 se non si chiamano queste funzioni per ogni utilizzo descritto tramite le annotazioni. È anche possibile aggiungere queste annotazioni nel proprio codice per assicurarsi che venga chiamato correttamente. Per abilitare l'analisi del codice in Visual Studio, vedere la documentazione per la versione di Visual Studio.

Queste annotazioni sono definite in Specstrings.h. Si basano su primitive che fanno parte del linguaggio di annotazione standard (SAL) e implementate usando _declspec("SAL_*").

Esistono due classi di annotazioni: annotazioni buffer e annotazioni avanzate.

Annotazioni del buffer

Le annotazioni del buffer descrivono come le funzioni usano i puntatori e possono essere usate per rilevare l'overrun del buffer. Ogni parametro può usare zero o un'annotazione del buffer. Un'annotazione del buffer viene creata con un carattere di sottolineatura iniziale e i componenti descritti nelle sezioni seguenti.

Dimensioni del buffer Descrizione
(dimensioni)
 Specifica la dimensione totale del buffer. Usare con _bcount e _ecount; non usare con _part. Questo valore è lo spazio accessibile; può essere minore dello spazio allocato.
(dimensioni, lunghezza)
 Specifica la dimensione totale e la lunghezza inizializzata del buffer. Usare con _bcount_part e _ecount_part. La dimensione totale può essere minore dello spazio allocato.
Unità di dimensione del buffer Descrizione
_bcount
 Le dimensioni del buffer sono in byte.
_ecount
 La dimensione del buffer è in elementi.
Direzione Descrizione
_Pollici
 La funzione legge dal buffer. Il chiamante fornisce il buffer e lo inizializza.
_Inout
 La funzione legge da e scrive nel buffer. Il chiamante fornisce il buffer e lo inizializza. Se usato con _deref, il buffer può essere riallocato dalla funzione.
_Cambio
 La funzione scrive nel buffer. Se usato nel valore restituito o con _deref, la funzione fornisce il buffer e lo inizializza. In caso contrario, il chiamante fornisce il buffer e la funzione la inizializza.
Riferimento indiretto Descrizione
_deref
 Dereference il parametro per ottenere il puntatore del buffer. Questo parametro potrebbe non essere NULL.
_deref_opt
 Dereference il parametro per ottenere il puntatore del buffer. Questo parametro può essere NULL.
Inizializzazione Descrizione
_Completo
 La funzione inizializza l'intero buffer. Usare solo con i buffer di output.
_Parte
 La funzione inizializza parte del buffer e indica in modo esplicito quanto. Usare solo con i buffer di output.
Buffer obbligatorio o facoltativo Descrizione
_Optare
 Questo parametro può essere NULL.

Nell'esempio seguente vengono illustrate le annotazioni per la funzione GetModuleFileName . Il parametro hModule è un parametro di input facoltativo. Il parametro lpFilename è un parametro di output; le relative dimensioni in caratteri vengono specificate dal parametro nSize e la relativa lunghezza include il carattere null-terminazione. Il parametro nSize è un parametro di input.

DWORD
WINAPI
GetModuleFileName(
    __in_opt HMODULE hModule,
    __out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
    __in DWORD nSize
    );

Di seguito sono riportate le annotazioni definite in Specstrings.h. Usare le informazioni nelle tabelle precedenti per interpretare il loro significato.

__bcount(dimensioni)
__bcount_opt(dimensioni)
__deref_bcount(dimensioni)
__deref_bcount_opt(dimensioni)
__deref_ecount(dimensioni)
__deref_ecount_opt(dimensioni)
__deref_in
__deref_in_bcount(dimensioni)
__deref_in_bcount_opt(dimensioni)
__deref_in_ecount(dimensioni)
__deref_in_ecount_opt(dimensioni)
__deref_in_opt
__deref_inout
__deref_inout_bcount(dimensioni)
__deref_inout_bcount_full(dimensioni)
__deref_inout_bcount_full_opt(dimensioni)
__deref_inout_bcount_opt(dimensioni)
__deref_inout_bcount_part(size,length)
__deref_inout_bcount_part_opt(size,length)
__deref_inout_ecount(dimensioni)
__deref_inout_ecount_full(dimensioni)
__deref_inout_ecount_full_opt(dimensioni)
__deref_inout_ecount_opt(dimensioni)
__deref_inout_ecount_part(size,length)
__deref_inout_ecount_part_opt(size,length)
__deref_inout_opt
__deref_opt_bcount(dimensioni)
__deref_opt_bcount_opt(dimensioni)
__deref_opt_ecount(dimensioni)
__deref_opt_ecount_opt(dimensioni)
__deref_opt_in
__deref_opt_in_bcount(dimensioni)
__deref_opt_in_bcount_opt(dimensioni)
__deref_opt_in_ecount(dimensioni)
__deref_opt_in_ecount_opt(dimensioni)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount(dimensioni)
__deref_opt_inout_bcount_full(dimensioni)
__deref_opt_inout_bcount_full_opt(dimensioni)
__deref_opt_inout_bcount_opt(dimensioni)
__deref_opt_inout_bcount_part(size,length)
__deref_opt_inout_bcount_part_opt(size,length)
__deref_opt_inout_ecount(dimensioni)
__deref_opt_inout_ecount_full(dimensioni)
__deref_opt_inout_ecount_full_opt(dimensioni)
__deref_opt_inout_ecount_opt(dimensioni)
__deref_opt_inout_ecount_part(size,length)
__deref_opt_inout_ecount_part_opt(size,length)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount(dimensioni)
__deref_opt_out_bcount_full(dimensioni)
__deref_opt_out_bcount_full_opt(dimensioni)
__deref_opt_out_bcount_opt(dimensioni)
__deref_opt_out_bcount_part(size,length)
__deref_opt_out_bcount_part_opt(size,length)
__deref_opt_out_ecount(dimensioni)
__deref_opt_out_ecount_full(dimensioni)
__deref_opt_out_ecount_full_opt(dimensioni)
__deref_opt_out_ecount_opt(dimensioni)
__deref_opt_out_ecount_part(size,length)
__deref_opt_out_ecount_part_opt(size,length)
__deref_opt_out_opt
__deref_out
__deref_out_bcount(dimensioni)
__deref_out_bcount_full(dimensioni)
__deref_out_bcount_full_opt(dimensioni)
__deref_out_bcount_opt(dimensioni)
__deref_out_bcount_part(size,length)
__deref_out_bcount_part_opt(size,length)
__deref_out_ecount(dimensioni)
__deref_out_ecount_full(dimensioni)
__deref_out_ecount_full_opt(dimensioni)
__deref_out_ecount_opt(dimensioni)
__deref_out_ecount_part(size,length)
__deref_out_ecount_part_opt(size,length)
__deref_out_opt
__ecount(dimensioni)
__ecount_opt(dimensioni)
__Pollici
__in_bcount(dimensioni)
__in_bcount_opt(dimensioni)
__in_ecount(dimensioni)
__in_ecount_opt(dimensioni)
__in_opt
__Inout
__inout_bcount(dimensioni)
__inout_bcount_full(dimensioni)
__inout_bcount_full_opt(dimensioni)
__inout_bcount_opt(dimensioni)
__inout_bcount_part(size,length)
__inout_bcount_part_opt(size,length)
__inout_ecount(dimensioni)
__inout_ecount_full(dimensioni)
__inout_ecount_full_opt(dimensioni)
__inout_ecount_opt(dimensioni)
__inout_ecount_part(size,length)
__inout_ecount_part_opt(size,length)
__inout_opt
__Cambio
__out_bcount(dimensioni)
__out_bcount_full(dimensioni)
__out_bcount_full_opt(dimensioni)
__out_bcount_opt(dimensioni)
__out_bcount_part(size,length)
__out_bcount_part_opt(size,length)
__out_ecount(dimensioni)
__out_ecount_full(dimensioni)
__out_ecount_full_opt(dimensioni)
__out_ecount_opt(dimensioni)
__out_ecount_part(size,length)
__out_ecount_part_opt(size,length)
__out_opt

Annotazioni avanzate

Le annotazioni avanzate forniscono informazioni aggiuntive sul parametro o sul valore restituito. Ogni parametro o valore restituito può usare zero o un'annotazione avanzata.

Annotazione Descrizione
__blocksOn(risorsa)
 Le funzioni si bloccano sulla risorsa specificata.
__Callback
 La funzione può essere usata come puntatore a funzione.
__checkReturn
 I chiamanti devono controllare il valore restituito.
__Format_string
 Il parametro è una stringa che contiene indicatori % di tipo printf.
__in_awcount(expr,size)
 Se l'espressione è true all'uscita, le dimensioni del buffer di input sono specificate in byte. Se l'espressione è false, le dimensioni vengono specificate negli elementi .
__nullnullterminated
 È possibile accedere al buffer fino a e includere la prima sequenza di due caratteri Null o puntatori.
__nullterminated
 È possibile accedere al buffer e includere il primo carattere Null o il puntatore.
__out_awcount(expr,size)
 Se l'espressione è true all'uscita, le dimensioni del buffer di output vengono specificate in byte. Se l'espressione è false, le dimensioni vengono specificate negli elementi .
__prevalere
 Specifica il comportamento di override in stile C#per i metodi virtuali.
__Riservati
 Il parametro è riservato per uso futuro e deve essere zero o NULL.
__success(expr)
 Se l'espressione è true all'uscita, il chiamante può basarsi su tutte le garanzie specificate da altre annotazioni. Se l'espressione è false, il chiamante non può basarsi sulle garanzie. Questa annotazione viene aggiunta automaticamente alle funzioni che restituiscono un valore HRESULT .
__typefix(ctype)
 Considerare il parametro come tipo specificato anziché il tipo dichiarato.

Gli esempi seguenti illustrano il buffer e le annotazioni avanzate per le funzioni DeleteTimerQueueTimer, FreeEnvironmentStrings e 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
    );

Annotazioni SAL

Procedura guidata: analisi del codice C/C++ per l'identificazione degli errori