Annotazioni intestazione
[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
);