함수 매개 변수 및 반환 값에 주석 지정

아티클
03/12/2013

간단한 함수 매개 변수에 대 한 주석을 일반적인 용도 설명, 즉, 스칼라 및 구조체와 클래스에 대 한 포인터-및 대부분의 종류의 버퍼.이 문서에서는 또한 주석에 대 한 일반적인 사용 패턴을 보여줍니다.함수에 관련 된 추가 주석을 참조 하십시오.함수 동작에 주석 지정

포인터 매개 변수

다음 표에서 주석 포인터 매개 변수에 주석이 추가 되 면 포인터가 null 인 경우 분석기 오류가 보고 됩니다.이 포인터와를 가리키는 모든 데이터 항목에 적용 됩니다.

주석	설명
_In_	스칼라, 구조, 구조에 대 한 포인터 등 입력된 매개 변수 주석을 추가 합니다.간단한 스칼라에서 명시적으로 사용할 수 있습니다.매개 변수 pre-state에서 유효 해야 하 고 수정 되지 않습니다.
_Out_	스칼라, 구조, 구조에 대 한 포인터와 같은 출력 매개 변수에 주석을 추가 합니다.값을 반환할 수 없는 개체에 적용 되지 않습니다-예를 들어, 값으로 전달 된 스칼라입니다.매개 변수 pre-state에 유효 하 게 하지는 않지만 post-state에서 사용할 수 있어야 합니다.
_Inout_	매개 변수는 해당 함수에 의해 변경 될 주석을 추가 합니다.Pre-state와 post-state, 유효 해야 하지만 호출 전후의 값이 다른 것으로 가정 합니다.수정할 수 있는 값을 적용 해야 합니다.
_In_z_	입력으로 사용 되는 null로 끝나는 문자열에 대 한 포인터입니다.문자열 pre-state에 유효 해야 합니다.변형 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 종료 문자 없음-pre-state에서 사용할 수 있어야 합니다.바이트 단위로 크기를 알 수 있으면 크기 조정 s 요소 크기입니다.
_In_reads_or_z_(s)	Null로 끝나는 또는 알려진된 크기, 또는 둘 모두에 배열에 대 한 포인터입니다.요소에 null 종결자가 최대-또는 s 이면 null 종료 문자 없음-pre-state에서 사용할 수 있어야 합니다.바이트 단위로 크기를 알 수 있으면 크기 조정 s 요소 크기입니다.(사용 되는 strn 제품군입니다.)
_Out_writes_(s) _Out_writes_bytes_(s)	에 대 한 포인터의 배열 s (깜박이고 요소바이트) 함수에 의해 기록 됩니다.배열 요소 pre-state에서 사용할 수 없는 및 post-state에서 잘못 된 요소 수가 지정 되지 않습니다.주석에서 매개 변수 형식이 있는 경우 해당 post-state에 적용 됩니다.예를 들어, 다음과 같은 코드를 생각해 볼 수 있습니다. `typedef _Null_terminated_ wchar_t *PWSTR; void MyStringCopy(_Out_writes_ (size) PWSTR p1, _In_ size_t size, _In_ PWSTR p2);` 이 예제에서는 호출자의 버퍼를 제공 합니다. size 요소에 대 한 p1.MyStringCopy이러한 요소의 일부를 사용할 수 있도록 합니다.무엇 보다는 _Null_terminated_ 에서 주석 PWSTR 즉 p1 post-state를 null로 종료 됩니다.이렇게 하면 유효한 요소 수가 여전히 잘 이지만 특정 요소 개수가 필요 하지 않습니다. _bytes_ 변형 요소 대신 바이트에서 크기를 제공 합니다.요소 크기만 표현할 수 없는 경우이 사용 합니다.예를 들어, char 문자열 사용의 _bytes_ 만 비슷한 함수의 경우 variant를 사용 하 여 wchar_t 것입니다.
_Out_writes_z_(s)	에 대 한 포인터의 배열 s 요소.요소에서 pre-state를 사용할 수 없습니다.Post-state에 null 종결자를 통해 구성 요소에서-존재 여야 — 유효 해야 합니다.바이트 단위로 크기를 알 수 있으면 크기 조정 s 요소 크기입니다.
_Inout_updates_(s) _Inout_updates_bytes_(s)	모두 읽고 쓸 함수에는 배열에 대 한 포인터입니다.크기가 s 요소 및 pre-state 및 post-state에서 유효 합니다. _bytes_ 변형 요소 대신 바이트에서 크기를 제공 합니다.요소 크기만 표현할 수 없는 경우이 사용 합니다.예를 들어, char 문자열 사용의 _bytes_ 만 비슷한 함수의 경우 variant를 사용 하 여 wchar_t 것입니다.
_Inout_updates_z_(s)	Null로 종결 되 고 알려진된 크기 배열에 대 한 포인터입니다.구성 요소는 null 종결자를 통해-존재 여야-pre-state와 post-state에 모두 사용할 수 있어야 합니다.값은 post-state에는 pre-state의 값과 다른 것으로 간주 됩니다. 이 위치를 null 종결자를 포함 되어 있습니다.바이트 단위로 크기를 알 수 있으면 크기 조정 s 요소 크기입니다.
_Out_writes_to_(s,c) _Out_writes_bytes_to_(s,c) _Out_writes_all_(s) _Out_writes_bytes_all_(s)	에 대 한 포인터의 배열 s 요소.요소에서 pre-state를 사용할 수 없습니다.Post-state, 구성 요소에에서는 c-th 요소가 유효 해야 합니다.바이트 단위로 크기를 알 수 있으면 크기 조정 s 및 c 요소 크기 또는 사용은 _bytes_ variant는 다음과 같이 정의 됩니다: `_Out_writes_to_(_Old_(s), _Old_(s)) _Out_writes_bytes_to_(_Old_(s), _Old_(s))` 최대 버퍼에 있는 모든 요소 즉, s pre-state에서 post-state에 유효 합니다.예를 들면 다음과 같습니다. `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 요소를 모두 유효 해야에 pre-state, 및 c 요소가 유효 해야 post-state에. _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 pre-state에는 pre-state 및 post-state에서 잘못 되었습니다. _bytes_ 변형 요소 대신 바이트에서 크기를 제공 합니다.요소 크기만 표현할 수 없는 경우이 사용 합니다.예를 들어, char 문자열 사용의 _bytes_ 만 비슷한 함수의 경우 variant를 사용 하 여 wchar_t 것입니다.
_In_reads_to_ptr_(p)	포인터 배열입니다 식 p - _Curr_ (즉, p - _Curr_)는 적절 한 언어 표준에서 정의 됩니다.이전에 요소 p pre-state에서 사용할 수 있어야 합니다.
_In_reads_to_ptr_z_(p)	Null로 끝나는 배열에 대 한 포인터 식 p – _Curr_ (즉, p - _Curr_)는 적절 한 언어 표준에서 정의 됩니다.이전에 요소 p pre-state에서 사용할 수 있어야 합니다.
_Out_writes_to_ptr_(p)	포인터 배열입니다 식 p - _Curr_ (즉, p - _Curr_)는 적절 한 언어 표준에서 정의 됩니다.이전에 요소 p pre-state에서 사용할 수 없는 및 post-state에서 사용할 수 있어야 합니다.
_Out_writes_to_ptr_z_(p)	Null로 끝나는 배열에 대 한 포인터 식 p – _Curr_ (즉, p - _Curr_)는 적절 한 언어 표준에서 정의 됩니다.이전에 요소 p pre-state에서 사용할 수 없는 및 post-state에서 사용할 수 있어야 합니다.

선택적 포인터 매개 변수

때 한 포인터 매개 변수에 주석을 포함 _opt_, 매개 변수는 null 일 수를 나타냅니다.그렇지 않으면이 주석이 포함 되지 않은 버전과 같은 수행 _opt_.목록은 다음과 같습니다에 _opt_ 변형 포인터 매개 변수 주석:

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

포인터 매개 변수를 출력 합니다.

출력 포인터 매개 변수는 특별 한 표기법을 통해 null 매개 변수가 가리키는 위치에 명확 하 게 필요 합니다.

주석	설명
_Outptr_	매개 변수는 null 일 수 고는 post-state에서 가리키는 위치 null 일 수 없습니다 사용할 수 있어야 합니다.
_Outptr_opt_	Post-state를 가리키는 위치가 null 일 수 없습니다 및 유효 해야 매개 변수는 null 일 수 있습니다.
_Outptr_result_maybenull_	매개 변수는 null 일 수 및 post-state에서 가리키는 위치를 null 일 수 있습니다.
_Outptr_opt_result_maybenull_	매개 변수는 null 일 수 및 post-state에서 가리키는 위치를 null 일 수 있습니다.

다음 표에 추가 부분 추가로 주석의 의미를 한 정하는 데 주석 이름으로 삽입 됩니다.The various substrings are _z, _COM_, _buffer_, _bytebuffer_, and _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_ post-condition 반환 된 포인터가 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 유효 합니다.

출력 매개 변수에서 실패를 nullified는 특정 인터페이스 규칙 가정 하겠습니다.COM 코드를 제외 하 고 명시적으로 다음과 같은 표 형태로 많이 사용 됩니다.COM 코드를 이전 섹션에 나열 된 해당 COM 폼을 사용 합니다.

주석	설명
_Result_nullonfailure_	기타 주석을 수정합니다.결과 함수가 실패 하면 null로 설정 됩니다.
_Result_zeroonfailure_	기타 주석을 수정합니다.함수가 실패 하면 그 결과 0으로 설정 됩니다.
_Outptr_result_nullonfailure_	함수가 실패 하면 반환 된 포인터가 유효한 함수가 성공 하면 버퍼 또는 null을 가리킵니다.이 주석이 아닌 선택적 매개 변수입니다.
_Outptr_opt_result_nullonfailure_	함수가 실패 하면 반환 된 포인터가 유효한 함수가 성공 하면 버퍼 또는 null을 가리킵니다.이 주석에서는 선택적 매개 변수입니다.
_Outref_result_nullonfailure_	함수가 실패 하면 반환 된 포인터가 유효한 함수가 성공 하면 버퍼 또는 null을 가리킵니다.이 주석은 참조 매개 변수입니다.

참조 매개 변수를 출력 합니다.

일반적으로 참조 매개 변수 사용에 대 한 출력 매개 변수입니다.간단한 출력 참조 매개 변수를-예를 들어, int&-_Out_ 올바른 의미 체계를 제공 합니다.그러나 출력 값에 대 한 일 경우-예를 들어 int *&-등가 포인터 주석 처럼 _Outptr_ int ** 올바른 구문을 제공 하지 않습니다.포인터 형식은 참조 매개 변수 출력 의미를 간결 하 게 표현 하려면 이러한 복합 주석을 사용 합니다.

주석	설명
_Outref_	결과 post-state에서 유효 해야 하 고 null 일 수 없습니다.
_Outref_result_maybenull_	결과 post-state에서 유효 해야 하지만 post-state에 null 일 수 있습니다.
_Outref_result_buffer_(s)	결과 post-state에서 유효 해야 하 고 null 일 수 없습니다.올바른 크기의 버퍼를 가리키는 s 요소.
_Outref_result_bytebuffer_(s)	결과 post-state에서 유효 해야 하 고 null 일 수 없습니다.올바른 크기의 버퍼를 가리키는 s 바이트입니다.
_Outref_result_buffer_to_(s, c)	결과 post-state에서 유효 해야 하 고 null 일 수 없습니다.버퍼를 가리키는 s 요소는 첫 번째 c 유효 합니다.
_Outref_result_bytebuffer_to_(s, c)	결과 post-state에서 유효 해야 하 고 null 일 수 없습니다.버퍼를 가리키는 s 바이트의 첫 번째 c 유효 합니다.
_Outref_result_buffer_all_(s)	결과 post-state에서 유효 해야 하 고 null 일 수 없습니다.올바른 크기의 버퍼를 가리키는 s 유효한 요소입니다.
_Outref_result_bytebuffer_all_(s)	결과 post-state에서 유효 해야 하 고 null 일 수 없습니다.올바른 버퍼를 가리키는 s 유효한 요소 바이트입니다.
_Outref_result_buffer_maybenull_(s)	결과 post-state에서 유효 해야 하지만 post-state에 null 일 수 있습니다.올바른 크기의 버퍼를 가리키는 s 요소.
_Outref_result_bytebuffer_maybenull_(s)	결과 post-state에서 유효 해야 하지만 post-state에 null 일 수 있습니다.올바른 크기의 버퍼를 가리키는 s 바이트입니다.
_Outref_result_buffer_to_maybenull_(s, c)	결과 post-state에서 유효 해야 하지만 post-state에 null 일 수 있습니다.버퍼를 가리키는 s 요소는 첫 번째 c 유효 합니다.
_Outref_result_bytebuffer_to_maybenull_(s,c)	결과 post-state에서 유효 해야 하지만 post 상태는 null 일 수 있습니다.버퍼를 가리키는 s 바이트의 첫 번째 c 유효 합니다.
_Outref_result_buffer_all_maybenull_(s)	결과 post-state에서 유효 해야 하지만 post 상태는 null 일 수 있습니다.올바른 크기의 버퍼를 가리키는 s 유효한 요소입니다.
_Outref_result_bytebuffer_all_maybenull_(s)	결과 post-state에서 유효 해야 하지만 post 상태는 null 일 수 있습니다.올바른 버퍼를 가리키는 s 유효한 요소 바이트입니다.

반환 값

유사한 함수의 반환 값은 _Out_ 매개 변수 이지만 다른 de-reference, 수준 및 결과에 대 한 포인터의 개념을 고려할 필요가 없습니다.주석이 달린된 개체 반환 값은 다음과 같은 주석입니다-스칼라, 구조체, 포인터 또는 버퍼에 대 한 포인터입니다.해당 이름으로 동일한 구문을 이러한 주석이 있는 _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) 적절 한 pre-state 또는 post-state 조건 함께 주석이 달린된 개체에 적용 됩니다. 중요 이름이 "in" 및 "아웃"의 의미를 포함 하지만 _In_ 및 _Out_ 하지 하지 이러한 주석 적용 합니다.
_Pre_equal_to_(expr) _Post_equal_to_(expr)	주석된 값을 정확 하 게이 expr.에 해당 하는 _Satisfies_(_Curr_ == expr) 적절 한 pre-state 또는 post-state 조건 함께 주석이 달린된 개체에 적용 됩니다.
_Struct_size_bytes_(size)	구조체 또는 클래스 선언에 적용 됩니다.해당 형식의 올바른 개체를 바이트 수로 지정 되 고 선언 된 형식 보다 더 큰 있을 수 있음을 나타냅니다 size.예를 들면 다음과 같습니다. `typedef _Struct_size_bytes_(nSize) struct MyStruct { size_t nSize; ... };` 버퍼 크기 (바이트) 매개 변수의 pM 유형 MyStruct * 다음 간주 됩니다. `min(pM->nSize, sizeof(MyStruct))`

주석

설명

_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) 적절 한 pre-state 또는 post-state 조건 함께 주석이 달린된 개체에 적용 됩니다.

중요

이름이 "in" 및 "아웃"의 의미를 포함 하지만 _In_ 및 _Out_ 하지 하지 이러한 주석 적용 합니다.

_Pre_equal_to_(expr)

_Post_equal_to_(expr)

주석된 값을 정확 하 게이 expr.에 해당 하는 _Satisfies_(_Curr_ == expr) 적절 한 pre-state 또는 post-state 조건 함께 주석이 달린된 개체에 적용 됩니다.

_Struct_size_bytes_(size)

구조체 또는 클래스 선언에 적용 됩니다.해당 형식의 올바른 개체를 바이트 수로 지정 되 고 선언 된 형식 보다 더 큰 있을 수 있음을 나타냅니다 size.예를 들면 다음과 같습니다.

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

버퍼 크기 (바이트) 매개 변수의 pM 유형 MyStruct * 다음 간주 됩니다.

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

참고 항목

다음을 통해 공유