Annotazione di parametri di funzione e valori restituiti

  • Articolo

Questo articolo descrive gli utilizzi tipici delle annotazioni per semplici parametri scalari di funzioni e puntatori a strutture e classi e alla maggior parte dei tipi di buffer. Questo articolo inoltre, mostra modelli di utilizzo comuni per le annotazioni.Per le annotazioni aggiuntive correlate alle funzioni, vedere Annotazione del comportamento delle funzioni

Parametri dei puntatori

Per le annotazioni nella seguente tabella, quando un parametro di un puntatore viene annotato i rapporti dell'analizzatore segnalano un errore se il puntatore è null. Questo vale per i puntatori e per qualsiasi elemento di dati a cui si fa riferimento.

Annotazione

Descrizione

_In_

L'annotazione dei parametri di input che sono scalari, strutture, puntatori a strutture e così via. In modo esplicito possono essere utilizzati sugli scalari semplici. Il parametro deve essere valido nello stato precedente e non verrà modificato.

_Out_

L'annotazione dei parametri di output che sono scalari, strutture, puntatori a strutture e così via. Non applicare questo ad un oggetto che non restituisce valori, ad esempio uno scalare che viene passato per valore. Il parametro non deve essere valido nello stato precedente, ma deve essere valido nello stato successivo.

_Inout_

Annotazione di un parametro che verrà modificato dalla funzione. Deve essere valido in entrambi gli stati quello precedente e quello successivo, ma si presume di avere valori diversi prima e dopo la chiamata.Deve essere applicato a un valore modificabile.

_In_z_

Un puntatore a una stringa con terminazione null, viene utilizzato come input. La stringa deve essere valida nello stato precedente. Le varianti di PSTR, che già dispongono di annotazioni corrette, sono preferibili.

_Inout_z_

Un puntatore ad una matrice di caratteri con terminazione null che verrà modificato. Deve essere valido prima e dopo la chiamata, ma si presume che il valore deva essere modificato. Il terminatore null può essere spostato, ma si può accedere solo agli elementi fino all'originale terminatore a null.

_In_reads_(s)

_In_reads_bytes_(s)

Un puntatore ad una matrice, che viene letto da una funzione. La matrice ha dimensione degli elementi s, ognuno dei quali deve essere valido.

La variante _bytes_ fornisce la dimensione in byte anziché per elementi.Utilizzare questo solo quando la dimensione non può essere espressa come elementi. Ad esempio, char Le stringhe avrebbe utilizzato la variante in _bytes_ solamente se in una simile funzione venisse utilizzato wchar_t.

_In_reads_z_(s)

Un puntatore ad una matrice con terminazione null e con una dimensione nota.Gli elementi fino a terminatore null, oppure s se non vi è il terminatore a null, devono essere validi nello stato precedente. Se la dimensione in byte è nota, scala s dalla dimensione dell'elemento.

_In_reads_or_z_(s)

Un puntatore ad una matrice che ha terminazione a null oppure ha dimensione nota, o entrambi.Gli elementi fino a terminatore null, oppure s se non vi è il terminatore a null, devono essere validi nello stato precedente. Se la dimensione in byte è nota, scala s dalla dimensione dell'elemento. (Utilizzato per la famiglia strn ).

_Out_writes_(s)

_Out_writes_bytes_(s)

Un puntatore a una matrice di elementi (rispettivamente byte) di s che verranno scritti dalla funzione. Gli elementi di una matrice non devono essere validi in uno stato precedente e il numero di elementi validi nello stato successivo non deve essere specificato. In presenza di annotazioni sul tipo di parametro, si applicano nello stato successivo.Si consideri il codice di esempio seguente.

typedef _Null_terminated_ wchar_t *PWSTR;
void MyStringCopy(_Out_writes_ (size) PWSTR p1,
   _In_ size_t size,
   _In_ PWSTR p2);

In questo esempio, il chiamante fornisce un buffer degli elementi di size per p1. MyStringCopy rende parte degli elementi validi.Ancora più importante, l'annotazione _Null_terminated_ su PWSTR significa che p1 è terminato con null nello stato successivo. In questo modo, il numero di elementi validi è ancora ben definito ma un numero specifico dell'elemento non è obbligatorio.

La variante _bytes_ fornisce la dimensione in byte anziché per elementi.Utilizzare questo solo quando la dimensione non può essere espressa come elementi. Ad esempio, char Le stringhe avrebbe utilizzato la variante in _bytes_ solamente se in una simile funzione venisse utilizzato wchar_t.

_Out_writes_z_(s)

Un puntatore ad una matrice elementi s. Gli elementi non devono essere validi nello stato precedente. Nello stato successivo, gli elementi con terminatore a null, devono essere presenti e devono essere validi. Se la dimensione in byte è nota, scala s dalla dimensione dell'elemento.

_Inout_updates_(s)

_Inout_updates_bytes_(s)

Un puntatore ad una matrice, il quale scrive e legge per la funzione. Si tratta di elementi di dimensione s, validi nello stato precedente e nello stato successivo.

La variante _bytes_ fornisce la dimensione in byte anziché per elementi.Utilizzare questo solo quando la dimensione non può essere espressa come elementi. Ad esempio, char Le stringhe avrebbe utilizzato la variante in _bytes_ solamente se in una simile funzione venisse utilizzato wchar_t.

_Inout_updates_z_(s)

Un puntatore ad una matrice con terminazione null e con una dimensione nota.Gli elementi fino il terminatore null, devono essere presenti e devono essere validi in entrambi gli stati in quello precedente e in quello successivo. Il valore nello stato successivo si presume essere differente dal valore nello stato precedente; questo include la posizione del terminatore null.Se la dimensione in byte è nota, scala s dalla dimensione dell'elemento.

_Out_writes_to_(s,c)

_Out_writes_bytes_to_(s,c)

_Out_writes_all_(s)

_Out_writes_bytes_all_(s)

Un puntatore ad una matrice elementi s. Gli elementi non devono essere validi nello stato precedente. Nello stato precedente, gli elementi fino al c-esimo elemento devono essere validi. Se la dimensione in byte è nota, scala s e c dalla dimensione dell'elemento oppure utilizzare la variante _bytes_, definita come:

   _Out_writes_to_(_Old_(s), _Old_(s))
   _Out_writes_bytes_to_(_Old_(s), _Old_(s))

In altre parole, ogni elemento presente nello stato precedente nel buffer fino a s è valido nello stato successivo. Di seguito è riportato un esempio.

void *memcpy(_Out_writes_bytes_all_(s) char *p1,
   _In_reads_bytes_(s) char *p2,
   _In_ int s);
void * wordcpy(_Out_writes_all_(s) DWORD *p1, 
   _In_reads_(s) DWORD *p2,
   _In_ int s);

_Inout_updates_to_(s,c)

_Inout_updates_bytes_to_(s,c)

Un puntatore ad una matrice, che sia letto e scritto dalla funzione. Ha dimensione di elementi s , ognuno dei quali deve essere valido nello stato precedente e c elementi devono essere validi nello stato successivo.

La variante _bytes_ fornisce la dimensione in byte anziché per elementi.Utilizzare questo solo quando la dimensione non può essere espressa come elementi. Ad esempio, char Le stringhe avrebbe utilizzato la variante in _bytes_ solamente se in una simile funzione venisse utilizzato wchar_t.

_Inout_updates_all_(s)

_Inout_updates_bytes_all_(s)

Un puntatore ad una matrice, che sia letto e scritto dalla funzione, con dimensione di elementi s.Definito come equivalente a:

   _Inout_updates_to_(_Old_(s), _Old_(s))
   _Inout_updates_bytes_to_(_Old_(s), _Old_(s))

In altre parole, ogni elemento presente nello stato precedente nel buffer fino a s è valido nello stato precedente e nello stato successivo.

La variante _bytes_ fornisce la dimensione in byte anziché per elementi.Utilizzare questo solo quando la dimensione non può essere espressa come elementi. Ad esempio, char Le stringhe avrebbe utilizzato la variante in _bytes_ solamente se in una simile funzione venisse utilizzato wchar_t.

_In_reads_to_ptr_(p)

Un puntatore ad una matrice per cui l'espressione p – _Curr_ (ovvero, p meno _Curr_) è definito dallo standard appropriato di linguaggio. Gli elementi prima di p devono essere validi nello stato precedente.

_In_reads_to_ptr_z_(p)

Un puntatore ad una matrice con terminazione null, per cui l'espressione p – _Curr_ (ovvero p meno _Curr_) è definito dallo standard appropriato di linguaggio. Gli elementi prima di p devono essere validi nello stato precedente.

_Out_writes_to_ptr_(p)

Un puntatore ad una matrice per cui l'espressione p – _Curr_ (ovvero, p meno _Curr_) è definito dallo standard appropriato di linguaggio. Gli elementi prima di p non devono essere validi nello stato precedente e devono essere validi nello stato successivo.

_Out_writes_to_ptr_z_(p)

Un puntatore ad una matrice con terminazione null, per cui l'espressione p – _Curr_ (ovvero p meno _Curr_) è definito dallo standard appropriato di linguaggio. Gli elementi prima di p non devono essere validi nello stato precedente e devono essere validi nello stato successivo.

Parametri facoltativi del puntatore

Quando una notazione di un parametro di un puntatore include _opt_, indica che il parametro può essere null.In caso contrario, l'annotazione esegue la stessa versione che non include _opt_.Di seguito è riportato un elenco di varianti _opt_, delle annotazioni dei parametri di un puntatore:

_In_opt_

_Out_opt_

_Inout_opt_

_In_opt_z_

_Inout_opt_z_

_In_reads_opt_

_In_reads_bytes_opt_

_In_reads_opt_z_

_Out_writes_opt_

_Out_writes_opt_z_

_Inout_updates_opt_

_Inout_updates_bytes_opt_

_Inout_updates_opt_z_

_Out_writes_to_opt_

_Out_writes_bytes_to_opt_

_Out_writes_all_opt_

_Out_writes_bytes_all_opt_

_Inout_updates_to_opt_

_Inout_updates_bytes_to_opt_

_Inout_updates_all_opt_

_Inout_updates_bytes_all_opt_

_In_reads_to_ptr_opt_

_In_reads_to_ptr_opt_z_

_Out_writes_to_ptr_opt_

_Out_writes_to_ptr_opt_z_

Parametri di output di un puntatore

I parametri di output di un puntatore richiedono una speciale notazione per evitare ambiguità null-ness sul parametro a cui punta il percorso.

Annotazione

Descrizione

_Outptr_

Il parametro non può essere null, nello stato successivo il puntatore al percorso non può essere nullo e deve essere valido.

_Outptr_opt_

Il parametro può essere null, ma nello stato successivo il puntatore al percorso non può essere null e deve essere valido.

_Outptr_result_maybenull_

Il parametro non può essere null e nello stato successivo il puntatore al percorso può essere a null.

_Outptr_opt_result_maybenull_

Il parametro può essere null e nello stato successivo il puntatore al percorso può essere a null.

Nella seguente tabella, le sotto stringhe aggiuntive vengono inserite nell'annotazione del nome, per favorire la qualifica del significato dell'annotazione. Diverse sotto stringhe sono _z, _COM_, _buffer_, _bytebuffer_e _to_.

Nota importanteImportante

Se l'interfaccia annotata è COM, utilizzare il form COM per queste annotazioni.Non utilizzare le annotazioni COM con qualsiasi altro tipo di interfaccia.

Annotazione

Descrizione

_Outptr_result_z_

_Outptr_opt_result_z_

_Outptr_result_maybenull_z_

_Ouptr_opt_result_maybenull_z_

Il puntatore restituito avrà l'annotazione _Null_terminated_.

_COM_Outptr_

_COM_Outptr_opt_

_COM_Outptr_result_maybenull_

_COM_Outptr_opt_result_maybenull_

Il puntatore restituito ha una semantica COM, pertanto comporta una post-condizione _On_failure_, indicando che il puntatore restituito è null.

_Outptr_result_buffer_(s)

_Outptr_result_bytebuffer_(s)

_Outptr_opt_result_buffer_(s)

_Outptr_opt_result_bytebuffer_(s)

Il puntatore restituito punta ad un buffer valido di dimensione s di elementi oppure di byte.

_Outptr_result_buffer_to_(s, c)

_Outptr_result_bytebuffer_to_(s, c)

_Outptr_opt_result_buffer_to_(s,c)

_Outptr_opt_result_bytebuffer_to_(s,c)

Il puntatore restituirò punta ad un buffer di dimensione s di elementi oppure di byte, di cui il primo c è valido.

Alcune convenzioni sull'interfaccia, presumono che i parametri di output vengono annullati con un errore. Fatta eccezione per il codice COM esplicito, sono preferibili i form presenti nella seguente tabella. Per il codice COM, utilizzare i form COM corrispondenti che sono elencati nella sezione precedente.

Annotazione

Descrizione

_Result_nullonfailure_

Modificare altre annotazioni.Il risultato viene impostato a null, se la funzione ha esito negativo.

_Result_zeroonfailure_

Modificare altre annotazioni.Il risultato è impostato a zero, se la funzione ha esito negativo.

_Outptr_result_nullonfailure_

I valore di ritorno del puntatore puntano ad un buffer valido se la funzione ha esito positivo, oppure ritorna null se la funzione ha esito negativo.Questa voce è per un parametro non facoltativo.

_Outptr_opt_result_nullonfailure_

I valore di ritorno del puntatore puntano ad un buffer valido se la funzione ha esito positivo, oppure ritorna null se la funzione ha esito negativo.Questa voce è per un parametro facoltativo.

_Outref_result_nullonfailure_

I valore di ritorno del puntatore puntano ad un buffer valido se la funzione ha esito positivo, oppure ritorna null se la funzione ha esito negativo.Questa voce è per un parametro di riferimento.

Parametri di riferimento di output

Un utilizzo comune del parametro di riferimento è per parametri di output. Per un semplice parametro di riferimento, ad esempio int&—_Out_ fornisce la semantica corretta. Tuttavia, quando il valore di output è un puntatore, ad esempio int *& l'annotazione equivalente del puntatore come _Outptr_ int ** non fornisce la semantica corretta. La semantica dei parametri di riferimento di output per i tipi di puntatore, può essere brevemente espressa utilizzando queste annotazioni composte:

Annotazione

Descrizione

_Outref_

Il risultato deve essere valido nello stato successione e non può essere null.

_Outref_result_maybenull_

Il risultato deve essere valido nello stato successivo, ma può essere null nello stato successivo.

_Outref_result_buffer_(s)

Il risultato deve essere valido nello stato successione e non può essere null.Indica un buffer valido di dimensione s elementi.

_Outref_result_bytebuffer_(s)

Il risultato deve essere valido nello stato successione e non può essere null.Indica un buffer valido di dimensione s byte.

_Outref_result_buffer_to_(s, c)

Il risultato deve essere valido nello stato successione e non può essere null.Indica un buffer di s elementi, di cui il primo c è valido.

_Outref_result_bytebuffer_to_(s, c)

Il risultato deve essere valido nello stato successione e non può essere null.Indica un buffer di s byte, di cui il primo c è valido.

_Outref_result_buffer_all_(s)

Il risultato deve essere valido nello stato successione e non può essere null.Indica un buffer valido di dimensione s elementi validi.

_Outref_result_bytebuffer_all_(s)

Il risultato deve essere valido nello stato successione e non può essere null.Indica un buffer valido di s byte di elementi validi.

_Outref_result_buffer_maybenull_(s)

Il risultato deve essere valido nello stato successivo, ma può essere null nello stato successivo.Indica un buffer valido di dimensione s elementi.

_Outref_result_bytebuffer_maybenull_(s)

Il risultato deve essere valido nello stato successivo, ma può essere null nello stato successivo.Indica un buffer valido di dimensione s byte.

_Outref_result_buffer_to_maybenull_(s, c)

Il risultato deve essere valido nello stato successivo, ma può essere null nello stato successivo.Indica un buffer di s elementi, di cui il primo c è valido.

_Outref_result_bytebuffer_to_maybenull_(s,c)

Il risultato deve essere valido nello stato successivo, ma può anche essere null.Indica un buffer di s byte, di cui il primo c è valido.

_Outref_result_buffer_all_maybenull_(s)

Il risultato deve essere valido nello stato successivo, ma può anche essere null.Indica un buffer valido di dimensione s elementi validi.

_Outref_result_bytebuffer_all_maybenull_(s)

Il risultato deve essere valido nello stato successivo, ma può anche essere null.Indica un buffer valido di s byte di elementi validi.

Valori restituiti

Il valore di ritorno di una funzione è simile a un parametro _Out_, ma è ad un livello di riferimento diverso, dove non è necessario considerare il concetto di puntatore al risultato. Per le seguenti annotazioni il valore di ritorno è l'oggetto annotato come uno scalare, un puntatore ad uno struct oppure un puntatore ad un buffer.Queste annotazioni hanno la stessa semantica della corrispondente annotazione _Out_.

_Ret_z_

_Ret_writes_(s)

_Ret_writes_bytes_(s)

_Ret_writes_z_(s)

_Ret_writes_to_(s,c)

_Ret_writes_maybenull_(s)

_Ret_writes_to_maybenull_(s)

_Ret_writes_maybenull_z_(s)

_Ret_maybenull_

_Ret_maybenull_z_

_Ret_null_

_Ret_notnull_

_Ret_writes_bytes_to_

_Ret_writes_bytes_maybenull_

_Ret_writes_bytes_to_maybenull_

Altre annotazioni comuni

Annotazione

Descrizione

_In_range_(low, hi)

_Out_range_(low, hi)

_Ret_range_(low, hi)

_Deref_in_range_(low, hi)

_Deref_out_range_(low, hi)

_Deref_inout_range_(low, hi)

_Field_range_(low, hi)

Il parametro, il campo o il risultato sono nell'intervallo (incluso) da low a hi. Equivalente a _Satisfies_(_Curr_ >= low && _Curr_ <= hi) che si applica all'oggetto annotato, insieme alle appropriate condizioni di stato precedente oppure stato successivo.

Nota importanteImportante

Sebbene i nomi contengono "in" e "out", la semantica di _In_ e _Out_ eseguono non si applicano a queste notazioni queste annotazioni.

_Pre_equal_to_(expr)

_Post_equal_to_(expr)

Il valore annotato è esattamente expr. Equivalente a _Satisfies_(_Curr_ == expr) che si applica all'oggetto annotato, insieme alle appropriate condizioni di stato precedente oppure stato successivo.

_Struct_size_bytes_(size)

Si applica ad uno struct o ad una dichiarazione di classe. Indica che un oggetto valido di tale tipo può essere maggiore rispetto al tipo dichiarato, con il numero di byte forniti da size. Di seguito è riportato un esempio.

typedef _Struct_size_bytes_(nSize)
struct MyStruct {
   size_t nSize;
   ...
};

La dimensione in byte del buffer di un parametro pM di tipo MyStruct * è presa da:

   min(pM->nSize, sizeof(MyStruct))

Risorse correlate

Blog del team di analisi codice

Vedere anche

Riferimenti

Annotazione del comportamento delle funzioni

Annotazioni di struct e classi

Annotazione del comportamento di blocco

Specificare dove e quando applicare un'annotazione

Funzioni intrinseche

Suggerimenti ed esempi (SAL)

Concetti

Informazioni su SAL

Altre risorse

Utilizzo delle annotazioni SAL per ridurre gli errori del codice C/C++