註釋函式參數和傳回值

發行項
06/08/2015

本文說明簡單的函式參數純量型別附註的一般用法，有指向結構和類別以及大多數種類緩衝區。本文也顯示附註的一般使用模式。如需使用功能相關的額外的附註，請參閱註釋函式行為

指標參數

在下表中的附註，，當指標參數被加註時，如果指標是空的，此分析器會報告錯誤。這適用於指標和任何被指向的資料項目。

註釋	說明
_In_	附註的輸入參數是純量，結構，結構的指標等。簡單的純量可以明確使用。參數必須是有效的目前狀態，並不會修改。
_Out_	附註的輸出參數是純量，結構，結構的指標等等。請勿將這個套用至無法傳回值中的物件，例如以傳值方式的純量。參數不是有效的目前狀態，而是必須是有效的後置狀態。
_Inout_	附註會被函式變更的參數。在呼叫之前，它一定適用於目前狀態和後置狀態之後，不過，在呼叫的前後則會假設具有不同的值。必須套用至可修改的值。
_In_z_	會使用以NULL 結尾字串的輸入做為指標。字串必須是有效的目前狀態。PSTR的變數，已經有正確的註解，會優先採用。
_Inout_z_	以null 結尾字元陣列的指標將會被修改。在呼叫之前和之後就必須是有效的，不過，值假設已變更。null 結束字元可能已經移動，但是，只可以存取依據原始 null 結束字元的項目。
_In_reads_(s) _In_reads_bytes_(s)	被函式所讀取的陣列指標。陣列大小為 s 項目，必須是有效的。 _bytes_ 變數在位元組寫入大小而不是項目。只有在大小不能以項目表達時，請使用這個程序。例如， char 字串會使用 _bytes_ Variant ，只有在 wchar_t 類似的函式的時候。
_In_reads_z_(s)	為 null 結尾且具有固定大小陣列的指標。以 null 結束字元或 s 的項目，如果沒有 null 結束字元必須是在目前的有效狀態。如果大小知道的話 (以位元組為單位)，依照知道項目的大小去縮放 s 。
_In_reads_or_z_(s)	null 結尾或具有已知大小的陣列、指標或兩者。以 null 結束字元或 s 的項目，如果沒有 null 結束字元必須是在目前的有效狀態。如果大小知道的話 (以位元組為單位)，依照知道項目的大小去縮放 s 。(用於 strn 系列)。
_Out_writes_(s) _Out_writes_bytes_(s)	陣列的指標。 s 項目 (resp。將函式所寫入的位元組)。陣列元素並不適用於目前的狀態，，而且在後置狀態有效的項目數目是不明。如果附註緊接在參數，就會套用在後置狀態。例如，試想下列程式碼。 `typedef _Null_terminated_ wchar_t *PWSTR; void MyStringCopy(_Out_writes_ (size) PWSTR p1, _In_ size_t size, _In_ PWSTR p2);` 在此範例中，呼叫端為 p1提供 size 項目緩衝區。 MyStringCopy 可讓這些項目有效。更重要的是，在 PWSTR 的 _Null_terminated_ 附註表示 p1 緊接在狀態是以 null 結束的。如此一來，有效的項目數是妥善定義的，不過，這不需要特定的項目計數。 _bytes_ 變數在位元組寫入大小而不是項目。只有在大小不能以項目表達時，請使用這個程序。例如， char 字串會使用 _bytes_ Variant ，只有在 wchar_t 類似的函式的時候。
_Out_writes_z_(s)	s 項目的物件陣列指標。項目不需要在之前的狀態是有效地。緊接在後置狀態項目，以結束字元是 null 目前必須是有效的。如果大小知道的話 (以位元組為單位)，依照知道項目的大小去縮放 s 。
_Inout_updates_(s) _Inout_updates_bytes_(s)	將陣列的指標，這會為在函式讀取和寫入。它不區分 s 項目和適用於目前狀態和後置狀態。 _bytes_ 變數在位元組寫入大小而不是項目。只有在大小不能以項目表達時，請使用這個程序。例如， char 字串會使用 _bytes_ Variant ，只有在 wchar_t 類似的函式的時候。
_Inout_updates_z_(s)	為 null 結尾且具有固定大小陣列的指標。項目引發以結束字元是 null 目前必須適用於目前狀態和後置狀態。在這個建置狀態的值是假設為具有目前狀態的值不同，這包括 null 結束字元的位置。如果大小知道的話 (以位元組為單位)，依照知道項目的大小去縮放 s 。
_Out_writes_to_(s,c) _Out_writes_bytes_to_(s,c) _Out_writes_all_(s) _Out_writes_bytes_all_(s)	s 項目的物件陣列指標。項目不需要在之前的狀態是有效地。在後置狀態，由 c- th 項目必須是有效的。如果大小知道的話 (以位元組為單位)，由知道項目的大小去縮放s和 c 或使用 _bytes_變數，定義如下: `_Out_writes_to_(_Old_(s), _Old_(s)) _Out_writes_bytes_to_(_Old_(s), _Old_(s))` 換句話說，存在於緩衝區的目前狀態的 s 的每個項目在後置狀態都是有效的。例如： `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)	函式所讀取和寫入的陣列指標。它不區分 s 項目，一定適用於目前的狀態，而且， c 項目必須在後置狀態是有效的。 _bytes_ 變數在位元組寫入大小而不是項目。只有在大小不能以項目表達時，請使用這個程序。例如， char 字串會使用 _bytes_ Variant ，只有在 wchar_t 類似的函式的時候。
_Inout_updates_all_(s) _Inout_updates_bytes_all_(s)	陣列的指標，這是由項目的大小 s 函式讀取和寫入。定義為對等用法: `_Inout_updates_to_(_Old_(s), _Old_(s)) _Inout_updates_bytes_to_(_Old_(s), _Old_(s))` 換句話說，存在於緩衝區都是以目前狀態的 s 的每個項目僅在這個狀態之前和之後的狀態有效。 _bytes_ 變數在位元組寫入大小而不是項目。只有在大小不能以項目表達時，請使用這個程序。例如， char 字串會使用 _bytes_ Variant ，只有在 wchar_t 類似的函式的時候。
_In_reads_to_ptr_(p)	將陣列的指標運算式 p – _Curr_ (也就是以 _Curr_的 p ) 定義是以適當的語言標準。在 p 之前的項目一定在目前的狀態是有效的。
_In_reads_to_ptr_z_(p)	為 Null 終端陣列的指標運算式 p – _Curr_ (也就是以 _Curr_的 p ) 定義是以適當的語言標準。在 p 之前的項目一定在目前的狀態是有效的。
_Out_writes_to_ptr_(p)	將陣列的指標運算式 p – _Curr_ (也就是以 _Curr_的 p ) 定義是以適當的語言標準。在 p 之前的項目不需要在之前的狀態是有效，而且在後置狀態必須是有效的。
_Out_writes_to_ptr_z_(p)	為 Null 終端陣列的指標運算式 p – _Curr_ (也就是以 _Curr_的 p ) 定義是以適當的語言標準。在 p 之前的項目不需要在之前的狀態是有效，而且在後置狀態必須是有效的。

選擇性指標參數

當指標參數附註由 _opt_時，它會指示參數可以是 null。否則，附註執行同一個不包括 _opt_版本相同。這個指標參數標記法的 _opt_ Variant 清單:

_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_

輸出指標參數

輸出指標參數需要特殊的標記法釐清參數的空間、和指向的位置。

註釋	說明
_Outptr_	參數不能是空的，因此，在這個之後狀態指向位置不是 null，而且必須是有效的。
_Outptr_opt_	參數可以是 null，不過，在這個後置狀態指向位置不是 null，而且必須是有效的。
_Outptr_result_maybenull_	參數不能是空的，因此，在這個後置狀態指向位置可以是空的。
_Outptr_opt_result_maybenull_	參數可以是 null，因此，在這個之後狀態指向位置可以是空的。

在下表中，其他子字串插入附註名稱進一步限定附註的意義。各種子字串是 _z、 _COM_、 _buffer_、 _bytebuffer_和 _to_。

重要事項
如果您標註為 COM 介面，使用這些附註 COM 表單。請不要使用與其他類型的 COM 介面的附註。

註釋	說明
_Outptr_result_z_ _Outptr_opt_result_z_ _Outptr_result_maybenull_z_ _Ouptr_opt_result_maybenull_z_	會傳回_Null_terminated_ 附註的指標。
_COM_Outptr_ _COM_Outptr_opt_ _COM_Outptr_result_maybenull_ _COM_Outptr_opt_result_maybenull_	傳回的指標使用 COM 語意，並帶有 _On_failure_ 後置狀況，傳回的指標是 NULL。
_Outptr_result_buffer_(s) _Outptr_result_bytebuffer_(s) _Outptr_opt_result_buffer_(s) _Outptr_opt_result_bytebuffer_(s)	有效的傳回 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)	s 項目或位元組的大小緩衝區的回傳指標，第一個 c 是有效的。

某些介面慣例假設輸出參數是失敗的空值。除了明確 COM 程式碼，表單在下表中是慣用的。對於 COM 程式碼，請使用本節在之前的部分所列的對應的 COM 表單。

註釋	說明
_Result_nullonfailure_	修改其他標記法。如果函式失敗，則結果設定為空值。
_Result_zeroonfailure_	修改其他標記法。如果函式失敗，則結果為零。
_Outptr_result_nullonfailure_	如果函式成功，則有效的回覆緩衝區的傳回指標，如果函式失敗，則為回傳空值。這個標記法是針對非選擇性參數。
_Outptr_opt_result_nullonfailure_	如果函式成功，則有效的回覆緩衝區的傳回指標，如果函式失敗，則為回傳空值。這個標記法是選擇性參數。
_Outref_result_nullonfailure_	如果函式成功，則有效的回覆緩衝區的傳回指標，如果函式失敗，則為回傳空值。這個標記法是參考參數。

輸出參考參數

一般參考參數為輸出參數。提供簡單的輸出參考參數 (例如， int&—_Out_ 提供正確的語意。不過，當輸出值是指標，例如: int *&—對等指標附註，如 _Outptr_ int ** 不提供正確的語意。精確地表示輸出參考參數語意指標型別的，請使用這些複合附註:

註釋	說明
_Outref_	結果一定在後置狀態是有效的，而且不能是空值。
_Outref_result_maybenull_	結果一定要在後置狀態是有效的，但是也有可能是空值。
_Outref_result_buffer_(s)	結果一定在後置狀態是有效的，而且不能是空值。s 大小項目有效緩衝區中的點。
_Outref_result_bytebuffer_(s)	結果一定在後置狀態是有效的，而且不能是空值。s 大小位元組有效緩衝區中的點。
_Outref_result_buffer_to_(s, c)	結果一定在後置狀態是有效的，而且不能是空值。s 項目至緩衝區中的點，第一個 c 是有效的。
_Outref_result_bytebuffer_to_(s, c)	結果一定在後置狀態是有效的，而且不能是空值。s 大小位元組緩衝區中的點，第一個 c 是有效的。
_Outref_result_buffer_all_(s)	結果一定在後置狀態是有效的，而且不能是空值。s 大小有效項目中有效緩衝區中的點。
_Outref_result_bytebuffer_all_(s)	結果一定在後置狀態是有效的，而且不能是空值。為有效項目 s 位元組緩衝區中的點。
_Outref_result_buffer_maybenull_(s)	結果一定要在後置狀態是有效的，但是也有可能是空值。s 大小項目有效緩衝區中的點。
_Outref_result_bytebuffer_maybenull_(s)	結果一定要在後置狀態是有效的，但是也有可能是空值。s 大小位元組有效緩衝區中的點。
_Outref_result_buffer_to_maybenull_(s, c)	結果一定要在後置狀態是有效的，但是也有可能是空值。s 項目至緩衝區中的點，第一個 c 是有效的。
_Outref_result_bytebuffer_to_maybenull_(s,c)	結果一定要在後置狀態是有效的，但是也有可能是空值。s 大小位元組緩衝區中的點，第一個 c 是有效的。
_Outref_result_buffer_all_maybenull_(s)	結果一定要在後置狀態是有效的，但是也有可能是空值。s 大小有效項目中有效緩衝區中的點。
_Outref_result_bytebuffer_all_maybenull_(s)	結果一定要在後置狀態是有效的，但是也有可能是空值。為有效項目 s 位元組緩衝區中的點。

傳回值

函式的傳回值類似 _Out_ 參數，但在取值的不同層級，因此，您不需要考慮指標的概念加入至結果。對於下列附註，傳回值為標註物件純量、指向結構或指標至緩衝區。這些附註的語意 (Semantics) 與對應的 _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_

其他通用的附註

註釋

說明

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

這個參數、欄位或結果範圍 (包含) 從 low 至 hi。套用至標註物件以適當的狀態之前或之後狀態條件為_Satisfies_(_Curr_ >= low && _Curr_ <= hi) 的對等用法。

重要事項
雖然名稱不能包含「in」和「out」， _In_ 語意和 _Out_不會適用於下列附註。

_Pre_equal_to_(expr)

_Post_equal_to_(expr)

附註的值就是 expr。套用至標註物件以適當的狀態之前或之後狀態條件為_Satisfies_(_Curr_ == expr) 的對等用法。

_Struct_size_bytes_(size)

適用於結構或類別宣告。表示該型別有效的物件比宣告型別大，與 size所指定的位元組數相比。例如：

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

緩衝區大小在參數型別 MyStruct *pM 的位元組會接受如下:

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

請參閱