Annotazione dei parametri della funzione e valori restituiti

Questo articolo descrive gli usi tipici delle annotazioni per parametri di funzione semplici, scalari e puntatori a strutture e classi, e la maggior parte dei tipi di buffer. Questo articolo illustra anche i modelli di utilizzo comuni per le annotazioni. Per altre annotazioni correlate alle funzioni, vedere Annotazione del comportamento della funzione.

Parametri del puntatore

Per le annotazioni nella tabella seguente, quando viene annotato un parametro puntatore, l'analizzatore segnala un errore se il puntatore è Null. Questa annotazione si applica ai puntatori e a qualsiasi elemento di dati a cui punta.

Annotazioni e descrizioni

• _In_

  Annota i parametri di input che sono scalari, strutture, puntatori a strutture e simili. È possibile usare in modo esplicito su semplici scalari. Il parametro deve essere valido in stato pre-stato e non verrà modificato.

• _Out_

  Annota i parametri di output che sono scalari, strutture, puntatori a strutture e simili. Non applicare questa annotazione a un oggetto che non può restituire un valore, ad esempio un valore scalare passato per valore. Il parametro non deve essere valido in stato pre-stato, ma deve essere valido dopo lo stato.

• _Inout_

  Annota un parametro che verrà modificato dalla funzione . Deve essere valido sia in stato pre-stato che post-stato, ma si presuppone che abbia valori diversi prima e dopo la chiamata. Deve essere applicato a un valore modificabile.

• _In_z_

  Puntatore a una stringa con terminazione Null usata come input. La stringa deve essere valida in stato pre-stato. Le varianti di PSTR, che hanno già le annotazioni corrette, sono preferibili.

• _Inout_z_

  Puntatore a una matrice di caratteri con terminazione Null che verrà modificata. Deve essere valido prima e dopo la chiamata, ma si presuppone che il valore sia stato modificato. È possibile spostare il carattere di terminazione Null, ma è possibile accedere solo agli elementi fino al carattere di terminazione Null originale.

• _In_reads_(s)

  _In_reads_bytes_(s)

  Puntatore a una matrice, che viene letta dalla funzione . La matrice è di elementi di dimensioni s , tutti validi.

  La _bytes_ variante restituisce le dimensioni in byte anziché gli elementi. Usare questa variante solo quando le dimensioni non possono essere espresse come elementi. Ad esempio, char le stringhe userebbero la _bytes_ variante solo se una funzione simile che usa wchar_t sarebbe .

• _In_reads_z_(s)

  Puntatore a una matrice con terminazione Null e con dimensioni note. Gli elementi fino al carattere di terminazione Null, o s se non è presente un carattere di terminazione Null, devono essere validi in stato pre-stato. Se le dimensioni sono note in byte, scalare s in base alle dimensioni dell'elemento.

• _In_reads_or_z_(s)

  Puntatore a una matrice con terminazione Null o con dimensioni note o entrambe. Gli elementi fino al carattere di terminazione Null, o s se non è presente un carattere di terminazione Null, devono essere validi in stato pre-stato. Se le dimensioni sono note in byte, scalare s in base alle dimensioni dell'elemento. (Usato per la strn famiglia.

• _Out_writes_(s)

  _Out_writes_bytes_(s)

  Puntatore a una matrice di s elementi (resp. byte) che verranno scritti dalla funzione. Gli elementi della matrice non devono essere validi in stato pre-stato e il numero di elementi validi dopo lo stato non è specificato. Se sono presenti annotazioni sul tipo di parametro, vengono applicate dopo lo stato. 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 di size elementi per p1. MyStringCopy rende validi alcuni di questi elementi. Più importante, l'annotazione _Null_terminated_ su PWSTR significa che p1 è con terminazione Null in post-stato. In questo modo, il numero di elementi validi è ancora ben definito, ma non è necessario un conteggio di elementi specifico.

  La _bytes_ variante restituisce le dimensioni in byte anziché gli elementi. Usare questa variante solo quando le dimensioni non possono essere espresse come elementi. Ad esempio, char le stringhe userebbero la _bytes_ variante solo se una funzione simile che usa wchar_t sarebbe .

• _Out_writes_z_(s)

  Puntatore a una matrice di s elementi. Gli elementi non devono essere validi in stato preliminare. In post-stato, gli elementi fino al carattere di terminazione Null, che devono essere presenti, devono essere validi. Se le dimensioni sono note in byte, scalare s in base alle dimensioni dell'elemento.

• _Inout_updates_(s)

  _Inout_updates_bytes_(s)

  Puntatore a una matrice, che è sia letta che scritta in nella funzione. Si tratta di elementi di dimensioni s e validi in stato pre-stato e post-stato.

  La _bytes_ variante restituisce le dimensioni in byte anziché gli elementi. Usare questa variante solo quando le dimensioni non possono essere espresse come elementi. Ad esempio, char le stringhe userebbero la _bytes_ variante solo se una funzione simile che usa wchar_t sarebbe .

• _Inout_updates_z_(s)

  Puntatore a una matrice con terminazione Null e con dimensioni note. Gli elementi fino al carattere di terminazione Null, che devono essere presenti, devono essere validi sia in stato pre-stato che post-stato. Si presuppone che il valore nello stato post-stato sia diverso dal valore nello stato precedente; che include la posizione del carattere di terminazione Null. Se le dimensioni sono note in byte, scalare s in base alle dimensioni dell'elemento.

• _Out_writes_to_(s,c)

  _Out_writes_bytes_to_(s,c)

  _Out_writes_all_(s)

  _Out_writes_bytes_all_(s)

  Puntatore a una matrice di s elementi. Gli elementi non devono essere validi in stato preliminare. In post-stato, gli elementi fino all'elemento c-th devono essere validi. La _bytes_ variante può essere utilizzata se la dimensione è nota in byte anziché in numero di elementi.

  Ad 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)

  Puntatore a una matrice, che è sia letta che scritta dalla funzione. Si tratta di elementi di dimensioni s , tutti i quali devono essere validi in pre-stato e c gli elementi devono essere validi dopo lo stato.

  La _bytes_ variante restituisce le dimensioni in byte anziché gli elementi. Usare questa variante solo quando le dimensioni non possono essere espresse come elementi. Ad esempio, char le stringhe userebbero la _bytes_ variante solo se una funzione simile che usa wchar_t sarebbe .

• _Inout_updates_all_(s)

  _Inout_updates_bytes_all_(s)

  Puntatore a una matrice, che è sia letta che scritta dalla funzione degli elementi di dimensioni 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 nel buffer fino a s nello stato precedente è valido nello stato pre-stato e post-stato.

  La _bytes_ variante restituisce le dimensioni in byte anziché gli elementi. Usare questa variante solo quando le dimensioni non possono essere espresse come elementi. Ad esempio, char le stringhe userebbero la _bytes_ variante solo se una funzione simile che usa wchar_t sarebbe .

• _In_reads_to_ptr_(p)

  Puntatore a una matrice per la quale p - _Curr_ (ad esempio, p meno _Curr_) è un'espressione valida. Gli elementi prima p devono essere validi in stato pre-stato.

  Ad esempio:

  int ReadAllElements(_In_reads_to_ptr_(EndOfArray) const int *Array, const int *EndOfArray);
  

• _In_reads_to_ptr_z_(p)

  Puntatore a una matrice con terminazione Null per cui expression p - _Curr_ (ovvero meno p _Curr_) è un'espressione valida. Gli elementi prima p devono essere validi in stato pre-stato.

• _Out_writes_to_ptr_(p)

  Puntatore a una matrice per la quale p - _Curr_ (ad esempio, p meno _Curr_) è un'espressione valida. Gli elementi precedenti p non devono essere validi in stato pre-stato e devono essere validi dopo lo stato.

• _Out_writes_to_ptr_z_(p)

  Puntatore a una matrice con terminazione Null per la quale p - _Curr_ (ad esempio, p meno _Curr_) è un'espressione valida. Gli elementi precedenti p non devono essere validi in stato pre-stato e devono essere validi dopo lo stato.

Parametri del puntatore facoltativi

Quando un'annotazione del parametro puntatore include _opt_, indica che il parametro può essere Null. In caso contrario, l'annotazione si comporta come la versione che non include _opt_. Di seguito è riportato un elenco delle _opt_ varianti delle annotazioni dei parametri del puntatore:

Parametri del puntatore di output

I parametri del puntatore di output richiedono una notazione speciale per disambiguare nullness nel parametro e nella posizione a cui punta.

Annotazioni e descrizioni

• _Outptr_

  Il parametro non può essere Null e nello stato post-stato la posizione a punta non può essere Null e deve essere valida.

• _Outptr_opt_

  Il parametro può essere Null, ma nello stato post-stato la posizione a cui punta non può essere null e deve essere valida.

• _Outptr_result_maybenull_

  Il parametro non può essere Null e nello stato post-stato la posizione a punta può essere Null.

• _Outptr_opt_result_maybenull_

  Il parametro può essere Null e nello stato post-stato la posizione a punta può essere Null.

  Nella tabella seguente le sottostringhe aggiuntive vengono inserite nel nome dell'annotazione per qualificare ulteriormente il significato dell'annotazione. Le varie sottostringhe sono _z, _COM_, _buffer_, _bytebuffer_e _to_.

• _Outptr_result_z_

  _Outptr_opt_result_z_

  _Outptr_result_maybenull_z_

  _Outptr_opt_result_maybenull_z_

  Il puntatore restituito ha 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, motivo per cui contiene una _On_failure_ post-condizione 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 a un buffer valido di elementi o byte di dimensioni s .

• _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 restituito punta a un buffer di elementi o byte di dimensioni s , di cui il primo c è valido.

Alcune convenzioni di interfaccia presupporre che i parametri di output siano nullificati in caso di errore. Ad eccezione del codice COM esplicito, è preferibile usare i moduli nella tabella seguente. Per il codice COM, usare i moduli COM corrispondenti elencati nella sezione precedente.

• _Result_nullonfailure_

  Modifica altre annotazioni. Il risultato è impostato su Null se la funzione ha esito negativo.

• _Result_zeroonfailure_

  Modifica altre annotazioni. Il risultato è impostato su zero se la funzione ha esito negativo.

• _Outptr_result_nullonfailure_

  Il puntatore restituito punta a un buffer valido se la funzione ha esito positivo o null se la funzione ha esito negativo. Questa annotazione è per un parametro non facoltativo.

• _Outptr_opt_result_nullonfailure_

  Il puntatore restituito punta a un buffer valido se la funzione ha esito positivo o null se la funzione ha esito negativo. Questa annotazione è per un parametro facoltativo.

• _Outref_result_nullonfailure_

  Il puntatore restituito punta a un buffer valido se la funzione ha esito positivo o null se la funzione ha esito negativo. Questa annotazione è per un parametro di riferimento.

Parametri di riferimento di output

Un uso comune del parametro di riferimento è per i parametri di output. Per i parametri di riferimento di output semplici, ad int&esempio , _Out_ fornisce la semantica corretta. Tuttavia, quando il valore di output è un puntatore, ad int *&esempio , le annotazioni del puntatore equivalenti come _Outptr_ int ** non forniscono la semantica corretta. Per esprimere concisamente la semantica dei parametri di riferimento di output per i tipi di puntatore, usare queste annotazioni composite:

Annotazioni e descrizioni

• _Outref_

  Il risultato deve essere valido dopo lo stato e non può essere Null.

• _Outref_result_maybenull_

  Il risultato deve essere valido dopo lo stato, ma può essere null nello stato post-stato.

• _Outref_result_buffer_(s)

  Il risultato deve essere valido dopo lo stato e non può essere Null. Punta al buffer valido degli elementi delle dimensioni s .

• _Outref_result_bytebuffer_(s)

  Il risultato deve essere valido dopo lo stato e non può essere Null. Punta a un buffer valido di byte di dimensioni s .

• _Outref_result_buffer_to_(s, c)

  Il risultato deve essere valido dopo lo stato e non può essere Null. Punta al buffer degli s elementi, di cui il primo c è valido.

• _Outref_result_bytebuffer_to_(s, c)

  Il risultato deve essere valido dopo lo stato e non può essere Null. Punta al buffer di byte di s cui il primo c è valido.

• _Outref_result_buffer_all_(s)

  Il risultato deve essere valido dopo lo stato e non può essere Null. Punta a un buffer di dimensioni s valido per gli elementi validi.

• _Outref_result_bytebuffer_all_(s)

  Il risultato deve essere valido dopo lo stato e non può essere Null. Punta al buffer valido di s byte di elementi validi.

• _Outref_result_buffer_maybenull_(s)

  Il risultato deve essere valido dopo lo stato, ma può essere null nello stato post-stato. Punta al buffer valido degli elementi delle dimensioni s .

• _Outref_result_bytebuffer_maybenull_(s)

  Il risultato deve essere valido dopo lo stato, ma può essere null nello stato post-stato. Punta a un buffer valido di byte di dimensioni s .

• _Outref_result_buffer_to_maybenull_(s, c)

  Il risultato deve essere valido dopo lo stato, ma può essere null nello stato post-stato. Punta al buffer degli s elementi, di cui il primo c è valido.

• _Outref_result_bytebuffer_to_maybenull_(s,c)

  Il risultato deve essere valido dopo lo stato, ma può essere null nello stato post.Result must be valid in post-state, but may be null in post-state. Punta al buffer di byte di s cui il primo c è valido.

• _Outref_result_buffer_all_maybenull_(s)

  Il risultato deve essere valido dopo lo stato, ma può essere null nello stato post.Result must be valid in post-state, but may be null in post-state. Punta a un buffer di dimensioni s valido per gli elementi validi.

• _Outref_result_bytebuffer_all_maybenull_(s)

  Il risultato deve essere valido dopo lo stato, ma può essere null nello stato post.Result must be valid in post-state, but may be null in post-state. Punta al buffer valido di s byte di elementi validi.

Valori restituiti

Il valore restituito di una funzione è simile a un _Out_ parametro, ma è a un livello diverso di de-riferimento e non è necessario considerare il concetto del puntatore al risultato. Per le annotazioni seguenti, il valore restituito è l'oggetto annotato, ovvero un scalare, un puntatore a uno struct o un puntatore a un buffer. Queste annotazioni hanno la stessa semantica dell'annotazione corrispondente _Out_ .

Formattare i parametri della stringa

• _Printf_format_string_ Indica che il parametro è una stringa di formato da usare in un'espressione printf .

  Esempio

  int MyPrintF(_Printf_format_string_ const wchar_t* format, ...)
  {
         va_list args;
         va_start(args, format);
         int ret = vwprintf(format, args);
         va_end(args);
         return ret;
  }
  

• _Scanf_format_string_ Indica che il parametro è una stringa di formato da usare in un'espressione scanf .

  Esempio

  int MyScanF(_Scanf_format_string_ const wchar_t* format, ...)
  {
         va_list args;
         va_start(args, format);
         int ret = vwscanf(format, args);
         va_end(args);
         return ret;
  }
  

• _Scanf_s_format_string_ Indica che il parametro è una stringa di formato da usare in un'espressione scanf_s .

  Esempio

  int MyScanF_s(_Scanf_s_format_string_ const wchar_t* format, ...)
  {
         va_list args;
         va_start(args, format);
         int ret = vwscanf_s(format, args);
         va_end(args);
         return ret;
  }
  

Altre annotazioni comuni

Annotazioni e descrizioni

• _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 si trova nell'intervallo (inclusivo) da low a hi. Equivalente a che viene applicato all'oggetto con annotazioni insieme alle _Satisfies_(_Curr_ >= low && _Curr_ <= hi) condizioni di pre-stato o post-stato appropriate.

  Importante

  Anche se i nomi contengono "in" e "out", la semantica di _In_ e _Out_ non si applica a queste annotazioni.

• _Pre_equal_to_(expr)

  _Post_equal_to_(expr)

  Il valore annotato è esattamente expr. Equivalente a che viene applicato all'oggetto con annotazioni insieme alle _Satisfies_(_Curr_ == expr) condizioni di pre-stato o post-stato appropriate.

• _Struct_size_bytes_(size)

  Si applica a una dichiarazione di struct o classe. Indica che un oggetto valido di tale tipo può essere maggiore del tipo dichiarato, con il numero di byte assegnato da size. Ad esempio:

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

  Le dimensioni del buffer in byte di un parametro pM di tipo MyStruct * vengono quindi prese in modo che siano:

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

Vedi anche

• Uso delle annotazioni SAL per ridurre gli errori del codice C/C++
• Informazioni su SAL
• 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